Universal Bootloader

1

Introduction

Barebox is a bootloader which follows the tradition of U-Boot. 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.

General features include:

• A posix based file API
  • inside barebox the usual open/close/read/write/lseek functions are used. This makes it familiar to everyone who has programmed under unix systems.

• usual shell commands like ls/cd/mkdir/echo/cat,...

• The environment is not a variable store anymore, but a file store. It has currently some limitations, of course. The environment is not a real read/write filesystem, it is more like a tar archive, or even more like an ar archive, because it cannot handle directories. The saveenv command saves the files under a certain directory (by default /env) in persistent storage (by default /dev/env0). There is a counterpart called loadenv, too.

• Real filesystem support
  • The loader starts up with mounting a ramdisk on /. Then a devfs is mounted on /dev allowing the user (or shell commands) to access devices. Apart from these two filesystems there is currently one filesystem ported: cramfs. One can mount it with the usual mount command.

• device/driver model
  • Devices are no longer described by defines in the config file. Instead there are devices which can be registered in the board .c file or dynamically allocated. Drivers will match upon the devices automatically.

• clocksource support
  • Timekeeping has been simplified by the use of the Linux clocksource API. Only one function is needed for a new board, no [gs]et_timer[masked]() or reset_timer[masked]() functions.

• Kconfig and Kernel build system
  • Only targets which are really needed get recompiled. Parallel builds are no problem anymore. This also removes the need for many many ifdefs in the code.

• simulation target
  • barebox can be compiled to run under Linux. While this is rather useless in real world this is a great debugging and development aid. New features can be easily developped and tested on long train journeys and started under gdb. There is a console driver for linux which emulates a serial device and a tap based ethernet driver. Linux files can be mapped to devices under barebox to emulate storage devices.

• device parameter support
  • Each device can have a unlimited number of parameters. They can be accessed on the command line with <devid>.<param>="...", for example 'eth0.ip=192.168.0.7' or 'echo $eth0.ip'

• initcalls
  • hooks in the startup process can be archieved with *_initcall() directives in each file.

• getopt
  • There is a small getopt implementation. Some commands got really complicated (both in code and in usage) due to the fact that barebox only allowed positional parameters.

• editor
  • Scripts can be edited with a small editor. This editor has no features except the ones really needed: moving the cursor and typing characters.

Building barebox

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

For the examples below, we use the User Mode barebox implementation, which is a port of barebox to the Linux userspace. This makes it possible to test drive the code without having real hardware. So for this test scenario, ARCH=sandbox is the valid architecture selection. This currently only works on ia32 hosts and partly on x86-64.

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=sandbox we do not need a cross compiler so it is sufficient to specify the architecture:

 # ln -s sandbox cross_arch 

In order to configure the various aspects of barebox, start the barebox 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 sandbox_defconfig'), there is a .config file in the toplevel directory of the sourcode.

Once barebox is configured, we can start the compilation

 # make 

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

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

barebox usually needs an environment for storing the configuation data. You can generate an environment using the example environment contained in board/sandbox/env:

 # ./scripts/bareboxenv -s -p 0x10000 board/sandbox/env/ env.bin 

To get some files to play with you can generate a cramfs image:

 # mkcramfs somedir/ cramfs.bin 

The barebox image is a normal Linux executable, so it can be started just like every other program:

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

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

  loading environment from /dev/env0
  barebox\> /

Specifying -[ie] <file> tells barebox to map the file as a device under /dev. Files given with '-e' will appear as /dev/env[n]. Files given with '-i' will appear as /dev/fd[n]. If barebox finds a valid configuration sector on /dev/env0 it will load it to /env. It then executes /env/init if it exists. If you have loaded the example environment barebox will show you a menu asking for your settings.

If you have started barebox as root you will find a new tap device on your host which you can configure using ifconfig. Once you configured barebox's network settings accordingly you can do a ping or tftpboot.

If you have mapped a cramfs image try mounting it with

  # mkdir /cram
  # mount /dev/fd0 cramfs /cram

Memory can be examined as usual using md/mw commands. They both understand the -f <file> option to tell the commands that they should work on the specified files instead of /dev/mem which holds the complete address space. Note that if you call 'md /dev/fd0' (without -f) barebox will segfault on the host, because it will interpret /dev/fd0 as a number.

Directory layout

Most of the directory layout is based upon the Linux Kernel:

arch / * /                -> contains architecture specific parts
arch / * / mach-* /       -> SoC specific code

drivers / serial          -> drivers
drivers / net
drivers / ...

include / asm-*           -> architecture specific includes
include / asm-* / arch-*  -> SoC specific includes

fs /                      -> filesystem support and filesystem drivers

lib /                     -> generic library functions (getopt, readline and the
                              like)

common /                  -> common stuff

commands /                -> many things previously in common/cmd_*, one command
                             per file

net /                     -> Networking stuff

scripts /                 -> Kconfig system

Documentation /           -> Parts of the documention, also doxygen

barebox's License

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA

User's Manual

Developer's Manual

Supported Boards