README - barebox/mindspeed - Git at Google

 Barebox
 -------

 Barebox is a bootloader that follows the tradition of Das U-Boot, while
 adapting modern design ideas from the Linux kernel.


 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.

 - 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.

 - 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 U-Boot 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 by using
 the environment variables ARCH and CROSS_COMPILE.

 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 examples/environment:

   # ./scripts/bareboxenv -s -p 0x10000 examples/environment/ 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 bareboxs
 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/        -> 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.
	Barebox
	-------

	Barebox is a bootloader that follows the tradition of Das U-Boot, while
	adapting modern design ideas from the Linux kernel.


	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.

	- 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.

	- 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 U-Boot 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 by using
	the environment variables ARCH and CROSS_COMPILE.

	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 examples/environment:

	# ./scripts/bareboxenv -s -p 0x10000 examples/environment/ 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 bareboxs
	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/ -> 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.