2009-12-15 13:32:28 +00:00
|
|
|
Barebox
|
|
|
|
-------
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 13:32:28 +00:00
|
|
|
Barebox is a bootloader that follows the tradition of Das U-Boot, while
|
2011-12-11 19:03:15 +00:00
|
|
|
adopting modern design ideas from the Linux kernel.
|
2007-07-05 19:40:46 +00:00
|
|
|
|
|
|
|
|
2009-12-15 13:32:28 +00:00
|
|
|
Features
|
|
|
|
--------
|
|
|
|
|
2011-12-11 19:03:15 +00:00
|
|
|
- A POSIX-based file API
|
2009-12-15 13:32:28 +00:00
|
|
|
Inside barebox the usual open/close/read/write/lseek functions are used.
|
2011-12-11 19:03:15 +00:00
|
|
|
This makes it familiar to everyone who has programmed under UNIX systems.
|
2007-07-05 19:40:46 +00:00
|
|
|
|
2009-12-15 13:32:28 +00:00
|
|
|
- Usual shell commands like ls/cd/mkdir/echo/cat,...
|
2007-07-05 19:40:46 +00:00
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
2009-12-15 13:32:28 +00:00
|
|
|
- filesystem support
|
2007-07-05 19:40:46 +00:00
|
|
|
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
|
2009-12-15 08:11:09 +00:00
|
|
|
barebox can be compiled to run under Linux. While this is rather useless
|
2007-07-05 19:40:46 +00:00
|
|
|
in real world this is a great debugging and development aid. New features
|
2011-12-11 19:03:15 +00:00
|
|
|
can be easily developed 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
|
2009-12-15 08:11:09 +00:00
|
|
|
devices under barebox to emulate storage devices.
|
2007-07-05 19:40:46 +00:00
|
|
|
|
|
|
|
- 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
|
2012-05-05 22:55:10 +00:00
|
|
|
hooks in the startup process can be achieved with *_initcall() directives
|
2007-07-05 19:40:46 +00:00
|
|
|
in each file.
|
|
|
|
|
|
|
|
- getopt
|
|
|
|
There is a small getopt implementation. Some commands got really
|
2011-12-11 19:03:15 +00:00
|
|
|
complicated (both in code and in usage) due to the fact that U-Boot
|
|
|
|
allowed only positional parameters.
|
2007-07-05 19:40:46 +00:00
|
|
|
|
|
|
|
- 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.
|
2007-07-05 16:02:04 +00:00
|
|
|
|
|
|
|
|
2009-12-15 13:32:28 +00:00
|
|
|
Building Barebox
|
|
|
|
----------------
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 13:32:28 +00:00
|
|
|
Barebox uses the Linux kernel's build system. It consists of two parts:
|
2011-12-11 19:03:15 +00:00
|
|
|
the Makefile infrastructure (kbuild), plus a configuration system
|
2009-12-15 08:11:09 +00:00
|
|
|
(kconfig). So building barebox is very similar to building the Linux
|
2007-07-05 16:02:04 +00:00
|
|
|
kernel.
|
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
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
|
2007-07-05 16:02:04 +00:00
|
|
|
test drive the code without having real hardware. So for this test
|
2007-07-12 10:19:39 +00:00
|
|
|
scenario, ARCH=sandbox is the valid architecture selection. This currently
|
2007-07-05 19:40:46 +00:00
|
|
|
only works on ia32 hosts and partly on x86-64.
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2008-08-26 09:31:33 +00:00
|
|
|
Selection of the architecture and the cross compiler can be done by using
|
|
|
|
the environment variables ARCH and CROSS_COMPILE.
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
In order to configure the various aspects of barebox, start the barebox
|
2007-07-05 16:02:04 +00:00
|
|
|
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
|
2007-07-12 10:19:39 +00:00
|
|
|
with 'make sandbox_defconfig'), there is a .config file in the toplevel
|
2012-05-05 22:55:10 +00:00
|
|
|
directory of the source code.
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
Once barebox is configured, we can start the compilation
|
2007-07-05 16:02:04 +00:00
|
|
|
|
|
|
|
# make
|
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
If everything goes well, the result is a file called barebox:
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
# ls -l barebox
|
|
|
|
-rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2012-05-05 22:55:10 +00:00
|
|
|
Barebox usually needs an environment for storing the configuration data.
|
2007-07-05 16:02:19 +00:00
|
|
|
You can generate an environment using the example environment contained
|
2011-12-12 10:37:51 +00:00
|
|
|
in board/sandbox/env:
|
2007-07-05 16:02:19 +00:00
|
|
|
|
2012-05-21 15:54:01 +00:00
|
|
|
# ./scripts/bareboxenv -s -p 0x10000 arch/sandbox/board/env env.bin
|
2007-07-05 16:02:19 +00:00
|
|
|
|
|
|
|
To get some files to play with you can generate a cramfs image:
|
|
|
|
# mkcramfs somedir/ cramfs.bin
|
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
The barebox image is a normal Linux executable, so it can be started
|
2007-07-05 16:02:19 +00:00
|
|
|
just like every other program:
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
# ./barebox -e env.bin -i cramfs.bin
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
barebox 2.0.0-trunk (Jun 26 2007 - 22:34:38)
|
2007-07-05 16:02:04 +00:00
|
|
|
|
|
|
|
loading environment from /dev/env0
|
2009-12-15 08:11:09 +00:00
|
|
|
barebox> /
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
Specifying -[ie] <file> tells barebox to map the file as a device
|
2007-07-05 16:02:19 +00:00
|
|
|
under /dev. Files given with '-e' will appear as /dev/env[n]. Files
|
|
|
|
given with '-i' will appear as /dev/fd[n].
|
2009-12-15 13:32:28 +00:00
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
If barebox finds a valid configuration sector on /dev/env0 it will
|
2007-07-05 16:02:19 +00:00
|
|
|
load it to /env. It then executes /env/init if it exists. If you have
|
2009-12-15 08:11:09 +00:00
|
|
|
loaded the example environment barebox will show you a menu asking for
|
2007-07-05 16:02:19 +00:00
|
|
|
your settings.
|
|
|
|
|
2009-12-15 08:11:09 +00:00
|
|
|
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 bareboxs
|
2007-07-05 19:40:46 +00:00
|
|
|
network settings accordingly you can do a ping or tftpboot.
|
2007-07-05 16:02:19 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
If you have mapped a cramfs image try mounting it with
|
2007-07-05 16:02:19 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
# mkdir /cram
|
|
|
|
# mount /dev/fd0 cramfs /cram
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
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.
|
2009-12-15 08:11:09 +00:00
|
|
|
Note that if you call 'md /dev/fd0' (without -f) barebox will segfault on
|
2009-12-15 13:32:28 +00:00
|
|
|
the host, because it will interpret /dev/fd0 as a number.
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2009-12-15 13:32:28 +00:00
|
|
|
|
|
|
|
Directory Layout
|
2007-07-05 19:40:46 +00:00
|
|
|
----------------
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
Most of the directory layout is based upon the Linux Kernel:
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
arch/*/ -> contains architecture specific parts
|
|
|
|
arch/*/mach-*/ -> SoC specific code
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
drivers/serial -> drivers
|
|
|
|
drivers/net
|
|
|
|
drivers/...
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
include/asm-* -> architecture specific includes
|
|
|
|
include/asm-*/arch-* -> SoC specific includes
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
fs/ -> filesystem support and filesystem drivers
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
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
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2007-07-05 19:40:46 +00:00
|
|
|
scripts/ -> Kconfig system
|
2007-07-05 16:02:04 +00:00
|
|
|
|
2014-07-26 17:17:10 +00:00
|
|
|
Documentation/ -> Sphinx generated documentation
|
2009-12-15 13:32:28 +00:00
|
|
|
|
2009-12-15 13:33:35 +00:00
|
|
|
|
|
|
|
Release Strategy
|
|
|
|
----------------
|
|
|
|
|
|
|
|
Barebox is developed with git. From time to time, tarball releases are
|
|
|
|
branched from the repository and released on the project web site. Here
|
|
|
|
are the release rules:
|
|
|
|
|
|
|
|
- Releases follow a time based scheme:
|
|
|
|
|
|
|
|
barebox-xxxx.yy.z.tar.bz2
|
|
|
|
^^^^ ^^ ^----------- Bugfix Number, starting at 0
|
|
|
|
\ \------------- Month
|
|
|
|
\---------------- Year
|
|
|
|
|
|
|
|
Example: barebox-2009.12.0.tar.bz2
|
|
|
|
|
|
|
|
- Releases are made around the beginning of the month. As we are aiming
|
|
|
|
for monthly releases, development is considered to be a continuous
|
|
|
|
process. If you find bugs in one release, you have the chance to get
|
|
|
|
patches in on a very short time scale.
|
|
|
|
|
|
|
|
- Usually, there are no bugfix releases, so z=0. If there is a need
|
|
|
|
to make a bugfix release, z is the right place to increment.
|
|
|
|
|
|
|
|
- If there may be a reason for pre releases, they are called
|
|
|
|
|
|
|
|
barebox-xxxx.yy.z-pren.tar.bz
|
|
|
|
^------ Number of prerelease, starting with 1
|
|
|
|
|
|
|
|
Example: barebox-2009.12.0-pre1.tar.bz2
|
|
|
|
|
|
|
|
We think that there is no need for pre releases, but if it's ever
|
|
|
|
necessary, this is the scheme we follow.
|
|
|
|
|
|
|
|
- Only the monthly releases are archived on the web site. The tarballs
|
|
|
|
are located in http://www.barebox.org/download/ and this location
|
|
|
|
does never change, in order to make life easier for distribution
|
|
|
|
people.
|
|
|
|
|