README

   1 U2Boot
   2 ------
   3
   4 This is u2boot, our proposal for a next generation of the famous U-Boot
   5 bootloader. U-Boot offers an excellent choice as a bootloader for
   6 today's embedded systems, seen from a user's point of view.
   7 Nevertheless, there are quite some design flaws which turned out over
   8 the last years and we think that they cannot be solved in a production
   9 tree. So this tree tries to do several things right - without caring
  10 about losing support for old boards.
  11
  12 General features include:
  13
  14 - A posix based file API
  15   inside U-Boot the usual open/close/read/write/lseek functions are used.
  16   This makes it familiar to everyone who has programmed under unix systems.
  17
  18 - usual shell commands like ls/cd/mkdir/echo/cat,...
  19
  20 - The environment is not a variable store anymore, but a file store. It has
  21   currently some limitations, of course. The environment is not a real
  22   read/write filesystem, it is more like a tar archive, or even more like
  23   an ar archive, because it cannot handle directories. The saveenv command
  24   saves the files under a certain directory (by default /env) in persistent
  25   storage (by default /dev/env0). There is a counterpart called loadenv, too.
  26
  27 - Real filesystem support
  28   The loader starts up with mounting a ramdisk on /. Then a devfs is mounted
  29   on /dev allowing the user (or shell commands) to access devices. Apart from
  30   these two filesystems there is currently one filesystem ported: cramfs. One
  31   can mount it with the usual mount command.
  32
  33 - device/driver model
  34   Devices are no longer described by defines in the config file. Instead
  35   there are devices which can be registered in the board .c file or
  36   dynamically allocated. Drivers will match upon the devices automatically.
  37
  38 - clocksource support
  39   Timekeeping has been simplified by the use of the Linux clocksource API.
  40   Only one function is needed for a new board, no [gs]et_timer[masked]() or
  41   reset_timer[masked]() functions.
  42
  43 - Kconfig and Kernel build system
  44   Only targets which are really needed get recompiled. Parallel builds are
  45   no problem anymore. This also removes the need for many many ifdefs in
  46   the code.
  47
  48 - simulation target
  49   U-Boot can be compiled to run under Linux. While this is rather useless
  50   in real world this is a great debugging and development aid. New features
  51   can be easily developped and tested on long train journeys and started
  52   under gdb. There is a console driver for linux which emulates a serial
  53   device and a tap based ethernet driver. Linux files can be mapped to
  54   devices under U-Boot to emulate storage devices.
  55
  56 - device parameter support
  57   Each device can have a unlimited number of parameters. They can be accessed
  58   on the command line with <devid>.<param>="...", for example
  59   'eth0.ip=192.168.0.7' or 'echo $eth0.ip'
  60
  61 - initcalls
  62   hooks in the startup process can be archieved with *_initcall() directives
  63   in each file.
  64
  65 - getopt
  66   There is a small getopt implementation. Some commands got really
  67   complicated (both in code and in usage) due to the fact that U-Boot only
  68   allowed positional parameters.
  69
  70 - editor
  71   Scripts can be edited with a small editor. This editor has no features
  72   except the ones really needed: moving the cursor and typing characters.
  73
  74
  75 Building U-Boot
  76 ---------------
  77
  78 U-Boot uses the Linux kernel's build system. It consists of two parts:
  79 the makefile infrastructure (kbuild), plus a configuration system
  80 (kconfig). So building U-Boot is very similar to building the Linux
  81 kernel.
  82
  83 For the examples below, we use the User Mode U-Boot implementation, which
  84 is a port of U-Boot to the Linux userspace. This makes it possible to
  85 test drive the code without having real hardware. So for this test
  86 scenario, ARCH=sandbox is the valid architecture selection. This currently
  87 only works on ia32 hosts and partly on x86-64.
  88
  89 Selection of the architecture and the cross compiler can be done by using
  90 the environment variables ARCH and CROSS_COMPILE.
  91
  92 In order to configure the various aspects of U-Boot, start the U-Boot
  93 configuration system:
  94
  95   # make menuconfig
  96
  97 This command starts a menu box and lets you select all the different
  98 options available for your architecture. Once the configuration was
  99 finished (you can simulate this by using the standard demo config file
 100 with 'make sandbox_defconfig'), there is a .config file in the toplevel
 101 directory of the sourcode.
 102
 103 Once U-Boot is configured, we can start the compilation
 104
 105   # make
 106
 107 If everything goes well, the result is a file called uboot:
 108
 109   # ls -l uboot
 110     -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 uboot
 111
 112 U-Boot usually needs an environment for storing the configuation data.
 113 You can generate an environment using the example environment contained
 114 in examples/environment:
 115
 116   # ./scripts/ubootenv -s -p 0x10000 examples/environment/ env.bin
 117
 118 To get some files to play with you can generate a cramfs image:
 119   # mkcramfs somedir/ cramfs.bin
 120
 121 The U-Boot image is a normal Linux executable, so it can be started
 122 just like every other program:
 123
 124   # ./uboot -e env.bin -i cramfs.bin
 125
 126   U-Boot 2.0.0-trunk (Jun 26 2007 - 22:34:38)
 127
 128   loading environment from /dev/env0
 129   uboot> /
 130
 131 Specifying -[ie] <file> tells U-Boot to map the file as a device
 132 under /dev. Files given with '-e' will appear as /dev/env[n]. Files
 133 given with '-i' will appear as /dev/fd[n].
 134 If U-Boot finds a valid configuration sector on /dev/env0 it will
 135 load it to /env. It then executes /env/init if it exists. If you have
 136 loaded the example environment U-Boot will show you a menu asking for
 137 your settings.
 138
 139 If you have started U-Boot as root you will find a new tap device on your
 140 host which you can configure using ifconfig. Once you configured U-Boots
 141 network settings accordingly you can do a ping or tftpboot.
 142
 143 If you have mapped a cramfs image try mounting it with
 144
 145   # mkdir /cram
 146   # mount /dev/fd0 cramfs /cram
 147
 148 Memory can be examined as usual using md/mw commands. They both understand
 149 the -f <file> option to tell the commands that they should work on the
 150 specified files instead of /dev/mem which holds the complete address space.
 151 Note that if you call 'md /dev/fd0' (without -f) U-Boot will segfault on
 152 the host, because it will interpret /dev/fd0 as a number.
 153
 154 Directory layout
 155 ----------------
 156
 157 Most of the directory layout is based upon the Linux Kernel:
 158
 159 arch/*/               -> contains architecture specific parts
 160 arch/*/mach-*/        -> SoC specific code
 161
 162 drivers/serial        -> drivers
 163 drivers/net
 164 drivers/...
 165
 166 include/asm-*         -> architecture specific includes
 167 include/asm-*/arch-*  -> SoC specific includes
 168
 169 fs/                   -> filesystem support and filesystem drivers
 170
 171 lib/                  -> generic library functions (getopt, readline and the
 172                          like)
 173
 174 common/               -> common stuff
 175
 176 commands/             -> many things previously in common/cmd_*, one command
 177                          per file
 178
 179 net/                  -> Networking stuff
 180
 181 scripts/              -> Kconfig system
 182
 183 Documentation/        ->