README

   1 Barebox
   2 -------
   3
   4 Barebox is a bootloader that follows the tradition of Das U-Boot, while
   5 adapting modern design ideas from the Linux kernel.
   6
   7
   8 Features
   9 --------
  10
  11 - A POSIX based file API
  12   Inside barebox the usual open/close/read/write/lseek functions are used.
  13   This makes it familiar to everyone who has programmed under unix systems.
  14
  15 - Usual shell commands like ls/cd/mkdir/echo/cat,...
  16
  17 - The environment is not a variable store anymore, but a file store. It has
  18   currently some limitations, of course. The environment is not a real
  19   read/write filesystem, it is more like a tar archive, or even more like
  20   an ar archive, because it cannot handle directories. The saveenv command
  21   saves the files under a certain directory (by default /env) in persistent
  22   storage (by default /dev/env0). There is a counterpart called loadenv, too.
  23
  24 - filesystem support
  25   The loader starts up with mounting a ramdisk on /. Then a devfs is mounted
  26   on /dev allowing the user (or shell commands) to access devices. Apart from
  27   these two filesystems there is currently one filesystem ported: cramfs. One
  28   can mount it with the usual mount command.
  29
  30 - device/driver model
  31   Devices are no longer described by defines in the config file. Instead
  32   there are devices which can be registered in the board .c file or
  33   dynamically allocated. Drivers will match upon the devices automatically.
  34
  35 - clocksource support
  36   Timekeeping has been simplified by the use of the Linux clocksource API.
  37   Only one function is needed for a new board, no [gs]et_timer[masked]() or
  38   reset_timer[masked]() functions.
  39
  40 - Kconfig and Kernel build system
  41   Only targets which are really needed get recompiled. Parallel builds are
  42   no problem anymore. This also removes the need for many many ifdefs in
  43   the code.
  44
  45 - simulation target
  46   barebox can be compiled to run under Linux. While this is rather useless
  47   in real world this is a great debugging and development aid. New features
  48   can be easily developped and tested on long train journeys and started
  49   under gdb. There is a console driver for linux which emulates a serial
  50   device and a tap based ethernet driver. Linux files can be mapped to
  51   devices under barebox to emulate storage devices.
  52
  53 - device parameter support
  54   Each device can have a unlimited number of parameters. They can be accessed
  55   on the command line with <devid>.<param>="...", for example
  56   'eth0.ip=192.168.0.7' or 'echo $eth0.ip'
  57
  58 - initcalls
  59   hooks in the startup process can be archieved with *_initcall() directives
  60   in each file.
  61
  62 - getopt
  63   There is a small getopt implementation. Some commands got really
  64   complicated (both in code and in usage) due to the fact that U-Boot only
  65   allowed positional parameters.
  66
  67 - editor
  68   Scripts can be edited with a small editor. This editor has no features
  69   except the ones really needed: moving the cursor and typing characters.
  70
  71
  72 Building Barebox
  73 ----------------
  74
  75 Barebox uses the Linux kernel's build system. It consists of two parts:
  76 the makefile infrastructure (kbuild), plus a configuration system
  77 (kconfig). So building barebox is very similar to building the Linux
  78 kernel.
  79
  80 For the examples below, we use the User Mode barebox implementation, which
  81 is a port of barebox to the Linux userspace. This makes it possible to
  82 test drive the code without having real hardware. So for this test
  83 scenario, ARCH=sandbox is the valid architecture selection. This currently
  84 only works on ia32 hosts and partly on x86-64.
  85
  86 Selection of the architecture and the cross compiler can be done by using
  87 the environment variables ARCH and CROSS_COMPILE.
  88
  89 In order to configure the various aspects of barebox, start the barebox
  90 configuration system:
  91
  92   # make menuconfig
  93
  94 This command starts a menu box and lets you select all the different
  95 options available for your architecture. Once the configuration was
  96 finished (you can simulate this by using the standard demo config file
  97 with 'make sandbox_defconfig'), there is a .config file in the toplevel
  98 directory of the sourcode.
  99
 100 Once barebox is configured, we can start the compilation
 101
 102   # make
 103
 104 If everything goes well, the result is a file called barebox:
 105
 106   # ls -l barebox
 107     -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
 108
 109 Barebox usually needs an environment for storing the configuation data.
 110 You can generate an environment using the example environment contained
 111 in examples/environment:
 112
 113   # ./scripts/bareboxenv -s -p 0x10000 examples/environment/ env.bin
 114
 115 To get some files to play with you can generate a cramfs image:
 116   # mkcramfs somedir/ cramfs.bin
 117
 118 The barebox image is a normal Linux executable, so it can be started
 119 just like every other program:
 120
 121   # ./barebox -e env.bin -i cramfs.bin
 122
 123   barebox 2.0.0-trunk (Jun 26 2007 - 22:34:38)
 124
 125   loading environment from /dev/env0
 126   barebox> /
 127
 128 Specifying -[ie] <file> tells barebox to map the file as a device
 129 under /dev. Files given with '-e' will appear as /dev/env[n]. Files
 130 given with '-i' will appear as /dev/fd[n].
 131
 132 If barebox finds a valid configuration sector on /dev/env0 it will
 133 load it to /env. It then executes /env/init if it exists. If you have
 134 loaded the example environment barebox will show you a menu asking for
 135 your settings.
 136
 137 If you have started barebox as root you will find a new tap device on your
 138 host which you can configure using ifconfig. Once you configured bareboxs
 139 network settings accordingly you can do a ping or tftpboot.
 140
 141 If you have mapped a cramfs image try mounting it with
 142
 143   # mkdir /cram
 144   # mount /dev/fd0 cramfs /cram
 145
 146 Memory can be examined as usual using md/mw commands. They both understand
 147 the -f <file> option to tell the commands that they should work on the
 148 specified files instead of /dev/mem which holds the complete address space.
 149 Note that if you call 'md /dev/fd0' (without -f) barebox will segfault on
 150 the host, because it will interpret /dev/fd0 as a number.
 151
 152
 153 Directory Layout
 154 ----------------
 155
 156 Most of the directory layout is based upon the Linux Kernel:
 157
 158 arch/*/               -> contains architecture specific parts
 159 arch/*/mach-*/        -> SoC specific code
 160
 161 drivers/serial        -> drivers
 162 drivers/net
 163 drivers/...
 164
 165 include/asm-*         -> architecture specific includes
 166 include/asm-*/arch-*  -> SoC specific includes
 167
 168 fs/                   -> filesystem support and filesystem drivers
 169
 170 lib/                  -> generic library functions (getopt, readline and the
 171                          like)
 172
 173 common/               -> common stuff
 174
 175 commands/             -> many things previously in common/cmd_*, one command
 176                          per file
 177
 178 net/                  -> Networking stuff
 179
 180 scripts/              -> Kconfig system
 181
 182 Documentation/        -> Doxygen generated documentation
 183
 184
 185 Release Strategy
 186 ----------------
 187
 188 Barebox is developed with git. From time to time, tarball releases are
 189 branched from the repository and released on the project web site. Here
 190 are the release rules:
 191
 192 - Releases follow a time based scheme:
 193
 194   barebox-xxxx.yy.z.tar.bz2
 195           ^^^^ ^^ ^----------- Bugfix Number, starting at 0
 196             \   \------------- Month
 197              \---------------- Year
 198
 199   Example: barebox-2009.12.0.tar.bz2
 200
 201 - Releases are made around the beginning of the month. As we are aiming
 202   for monthly releases, development is considered to be a continuous
 203   process. If you find bugs in one release, you have the chance to get
 204   patches in on a very short time scale.
 205
 206 - Usually, there are no bugfix releases, so z=0. If there is a need
 207   to make a bugfix release, z is the right place to increment.
 208
 209 - If there may be a reason for pre releases, they are called
 210
 211   barebox-xxxx.yy.z-pren.tar.bz
 212                        ^------ Number of prerelease, starting with 1
 213
 214   Example: barebox-2009.12.0-pre1.tar.bz2
 215
 216   We think that there is no need for pre releases, but if it's ever
 217   necessary, this is the scheme we follow.
 218
 219 - Only the monthly releases are archived on the web site. The tarballs
 220   are located in http://www.barebox.org/download/ and this location
 221   does never change, in order to make life easier for distribution
 222   people.
 223