barebox/README.u2

U2Boot
------

This is u2boot, our proposal for a next generation of the famous U-Boot
bootloader. U-Boot offers an excellent choice as a bootloader for
today's embedded systems, seen from a user's point of view.
Nevertheless, there are quite some design flaws which turned out over
the last years and we think that they cannot be solved in a production
tree. So this tree tries to do several things right - without caring
about losing support for old boards. So if you aim at stability at this
time, stay with the official U-Boot releases.


Building U-Boot
---------------

U-Boot uses the Linux kernel's build system. It consists of two parts:
the makefile infrastructure (kbuild), plus a configuration system
(kconfig). So building U-Boot is very similar to building the Linux
kernel.

For the examples below, we use the User Mode U-Boot implementation, which
is a port of U-Boot to the Linux userspace. This makes it possible to
test drive the code without having real hardware. So for this test
scenario, ARCH=linux is the valid architecture selection.

Selection of the architecture and the cross compiler can be done in two
ways. You can either specify it using the environment variables ARCH
and CROSS_COMPILE, or you can create the soft links cross_arch and
cross_compile pointing to your architecture and compiler. For ARCH=linux
we do not need a cross compiler so it is sufficient to specify the
architecture:

  # ln -s linux cross_arch

In order to configure the various aspects of U-Boot, start the U-Boot
configuration system:

  # make menuconfig

This command starts a menu box and lets you select all the different
options available for your architecture. Once the configuration was
finished (you can simulate this by using the standard demo config file
with 'make linux_defconfig'), there is a .config file in the toplevel
directory of the sourcode.

U-Boot usually needs an environment, storing the configuation data, plus
a filesystem space for scripts etc. You can create one locally with

  # dd if=/dev/zero of=env.bin bs=1024 count=128
  # FIXME - what to do to get a solid environemt
  # mkcramfs somedir/ cramfs.bin
  # FIXME - create filesystem

Once U-Boot is configured, we can start the compilation

  # make

If everything goes well, the result is a file called uboot:

  # ls -l uboot
    -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 uboot

This U-Boot image is a normal Linux executable, so it can be started
just like evary other program:

  # ./uboot -e env.bin -i cramfs.bin

  U-Boot 2.0.0-trunk (Jun 26 2007 - 22:34:38)

  loading environment from /dev/env0
  uboot> /

FIXME: cfi currently doesn't work with um-uboot


Commands
--------

devinfo
addpart
pwd
cd
ls
cat
tftpboot <dest> <source> FIXME: order?
tftpboot /dev/nor0.1 <source>
erase -f /dev/nor0.1
help
edit -> ctrl-c ctrl-d
md -f /dev/nor0.1
exec /env/init FIXME: doesn't work yet
saveenv (makes /env persistent) -> /dev/env0
printenv (FIXME: obsolete)
mount

Shell
-----

- doesn't have switch/case yet
- only one variable space
[ ] add variable space

Drivers
-------

/dev
serial
partition
environment -> /env; /env/init

Design
------

include/driver.h
board/scb9328.c
include/param.h: each device can have parameters; can be changed on
runtime; get/set can be overwritten by implementation.

- xfunctions: do panic if error
- proposed design:
  arch/
  arch/arm/cpu-arm920t/
  arch/arm/board-.../
  board/ is obsolete

- arch/*/Makefile is central makefile