9
0
Fork 0
barebox/README

224 lines
7.9 KiB
Plaintext
Raw Permalink Normal View History

Barebox
-------
2007-07-05 16:02:04 +00:00
Barebox is a bootloader that follows the tradition of Das U-Boot, while
adopting modern design ideas from the Linux kernel.
2007-07-05 19:40:46 +00:00
Features
--------
- 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.
2007-07-05 19:40:46 +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.
- 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
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
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
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
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
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
Building Barebox
----------------
2007-07-05 16:02:04 +00:00
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
2007-07-05 16:02:04 +00:00
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
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
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
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
directory of the source code.
2007-07-05 16:02:04 +00:00
Once barebox is configured, we can start the compilation
2007-07-05 16:02:04 +00:00
# make
If everything goes well, the result is a file called barebox:
2007-07-05 16:02:04 +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
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
in board/sandbox/env:
2007-07-05 16:02:19 +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
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
# ./barebox -e env.bin -i cramfs.bin
2007-07-05 16:02:04 +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
barebox> /
2007-07-05 16:02:04 +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].
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
loaded the example environment barebox will show you a menu asking for
2007-07-05 16:02:19 +00:00
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 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.
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.
2007-07-05 16:02:04 +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
Documentation/ -> Doxygen generated documentation
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.