path: root/README

# SPDX-License-Identifier: GPL-2.0-only

barebox
-------

barebox is a bootloader that follows the tradition of Das U-Boot, while
adopting 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, but more like a tar archive.
  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 are a number of different filesystems ported:
  ext4, efi, efivarfs, ext4, fat, jffs2, NFS, pstore, squashfs, ubifs,
  u-boot variable FS among others.

- device/driver model
  Devices are no longer described by defines in the config file. Instead
  devices are registered as they are discovered (e.g. through OpenFirmware
  device tree traversal or EFI handles) or by board code.
  Drivers will match upon the devices automatically.

- clocksource support
  Timekeeping has been simplified by the use of the Linux clocksource API.
  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.

- ARCH=sandbox 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 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.

- device parameter support
  Each device can have an 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
  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.

- 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
works on at least IA32 hosts and x86-64 hosts.

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

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 configuration data.
You can generate an environment using the example environment contained
in board/sandbox/env:

  # ./scripts/bareboxenv -s -p 0x10000 arch/sandbox/board/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'
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/*/include        -> architecture specific includes
arch/*/mach-*         -> SoC specific code
arch/*/mach-*/include -> SoC specific includes

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

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/        -> Sphinx generated documentation. Call "make docs" to
                         generate a HTML version in Documentation/html.


Release Strategy
----------------

barebox is developed with git. On a monthly schedule, 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 https://www.barebox.org/download/ and this location
  does never change, in order to make life easier for distribution
  people.


Contributing
------------

For any questions regarding barebox, send a mail to the mailing list at
<barebox@lists.infradead.org>. The archives for this list are available
publicly at <http://lists.infradead.org/pipermail/barebox/> and
<https://lore.barebox.org/barebox/>.

The same list should also be used to send patches. barebox uses a similar
process as the Linux kernel, so most of the Linux guide for submitting patches
<https://www.kernel.org/doc/html/latest/process/submitting-patches.html> also
applies to barebox (except the step for selecting your recipient - we don't
have a MAINTAINERS file, instead all patches go to the list).


License
-------

Copyright (C) 2000 - 2005 Wolfgang Denk, DENX Software Engineering, wd@denx.de.
Copyright (C) 2018 Sascha Hauer, Pengutronix, and individual contributors

barebox is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License, version 2, as published by the Free
Software Foundation.

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 in the file
COPYING along with this program. If not, see <https://www.gnu.org/licenses/>.

Individual files may contain the following SPDX license tags as a shorthand for
the above copyright and warranty notices:

    SPDX-License-Identifier: GPL-2.0-only
    SPDX-License-Identifier: GPL-2.0-or-later

This eases machine processing of licensing information based on the SPDX
License Identifiers that are available at http://spdx.org/licenses/.

Also note that some files in the barebox source tree are available under
several different GPLv2-compatible open-source licenses. This fact is noted
clearly in the file headers of the respective files.