doc: rework user manual
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
This commit is contained in:
parent
7a21761d03
commit
839b210601
|
@ -1,166 +1,74 @@
|
||||||
/** @mainpage Universal Bootloader
|
/** @mainpage Barebox
|
||||||
|
|
||||||
@section barebox_intro Introduction
|
Barebox is a bootloader that initializes a hardware and boots Linux and
|
||||||
|
maybe other operating systems or bare metal code on a variety of
|
||||||
|
processors. It was initialy derived from U-Boot and captures up with
|
||||||
|
several of it's ideas, so users being familiar with U-Boot should come
|
||||||
|
into production quickly with Barebox.
|
||||||
|
|
||||||
@a Barebox is a bootloader which follows the tradition of U-Boot. U-Boot
|
However, as the Barebox developers are highly addicted to the Linux
|
||||||
offers an excellent choice as a bootloader for today's embedded systems,
|
kernel, it's coding style and code quality, we try to stick as closely
|
||||||
seen from a user's point of view. Nevertheless, there are quite some
|
as possible to the methodologies and techniques developed in Linux. In
|
||||||
design flaws which turned out over the last years and we think that they
|
addition we have a strong background in POSIX, so you'll find several
|
||||||
cannot be solved in a production tree. So this tree tries to do several
|
good old Unix traditions realized in Barebox as well.
|
||||||
things right - without caring about losing support for old boards.
|
|
||||||
|
|
||||||
@par General features include:
|
@par Highlights:
|
||||||
|
|
||||||
- A posix based file API
|
- <b>POSIX File API:</b><br>
|
||||||
- inside @a barebox the usual open/close/read/write/lseek functions are used.
|
@a Barebox uses the the well known open/close/read/write/lseek access
|
||||||
This makes it familiar to everyone who has programmed under unix systems.
|
functions, together with a model of representing devices by files. This
|
||||||
|
makes the APIs familiar to everyone who has experience with Unix
|
||||||
|
systems.
|
||||||
|
|
||||||
- usual shell commands like ls/cd/mkdir/echo/cat,...
|
- <b>Shell:</b><br>
|
||||||
|
We have the standard shell commands like ls/cd/mkdir/echo/cat,...
|
||||||
|
|
||||||
- The environment is not a variable store anymore, but a file store. It has
|
- <b>Environment Filesystem:</b><br>
|
||||||
currently some limitations, of course. The environment is not a real
|
In contrast to U-Boot, Barebox doesn't misuse the environment for
|
||||||
read/write filesystem, it is more like a tar archive, or even more like
|
scripting. If you start the bootloader, it gives you a shell and
|
||||||
an ar archive, because it cannot handle directories. The saveenv command
|
something that looks like a filesystem. In fact it isn't: it is a very
|
||||||
saves the files under a certain directory (by default /env) in persistent
|
simple ar archive being extracted from flash into a ramdisk with 'loadenv'
|
||||||
storage (by default /dev/env0). There is a counterpart called loadenv, too.
|
and stored back with 'saveenv'.
|
||||||
|
|
||||||
- Real filesystem support
|
- <b>Filesystem Support:</b><br>
|
||||||
- The loader starts up with mounting a ramdisk on /. Then a devfs is mounted
|
When starting up, the environment is mounted to /, followed by a
|
||||||
on /dev allowing the user (or shell commands) to access devices. Apart from
|
device filesytem being mounted to /dev in order to make it possible to
|
||||||
these two filesystems there is currently one filesystem ported: cramfs. One
|
access devices. Other filesystems can be mounted on demand.
|
||||||
can mount it with the usual mount command.
|
|
||||||
|
|
||||||
- device/driver model
|
- <b>Driver Model (borrowed from Linux):</b><br>
|
||||||
- Devices are no longer described by defines in the config file. Instead
|
Barebox follows the Linux driver model: devices can be specified in a
|
||||||
there are devices which can be registered in the board .c file or
|
hardware specific file, and drivers feel responsible for these devices
|
||||||
dynamically allocated. Drivers will match upon the devices automatically.
|
if they have the same name.
|
||||||
|
|
||||||
- clocksource support
|
- <b>Clocksource:</b><br>
|
||||||
- Timekeeping has been simplified by the use of the Linux clocksource API.
|
We use the clocksource API knwon from Linux.
|
||||||
Only one function is needed for a new board, no [gs]et_timer[masked]() or
|
|
||||||
reset_timer[masked]() functions.
|
|
||||||
|
|
||||||
- Kconfig and Kernel build system
|
- <b>Kconfig/Kbuild:</b><br>
|
||||||
- Only targets which are really needed get recompiled. Parallel builds are
|
This gives us parallel builds and removes the need for lots of ifdefs.
|
||||||
no problem anymore. This also removes the need for many many ifdefs in
|
|
||||||
the code.
|
|
||||||
|
|
||||||
- simulation target
|
- <b>Sandbox:</b><br>
|
||||||
- @a barebox can be compiled to run under Linux. While this is rather useless
|
If you develop features for @a Barebox, you can use the 'sandbox'
|
||||||
in real world this is a great debugging and development aid. New features
|
target which compiles @a Barebox as a POSIX application in the Linux
|
||||||
can be easily developed and tested on long train journeys and started
|
userspace: it can be started like a normal command and even has
|
||||||
under gdb. There is a console driver for linux which emulates a serial
|
network access (tun/tap). Files from the local filesytem can be used
|
||||||
device and a tap based ethernet driver. Linux files can be mapped to
|
to simulate devices.
|
||||||
devices under @a barebox to emulate storage devices.
|
|
||||||
|
|
||||||
- device parameter support
|
- <b>Device Parameters:</b><br>
|
||||||
- Each device can have a unlimited number of parameters. They can be accessed
|
There is a parameter model in @a Barebox: each device can specify it's
|
||||||
on the command line with \<devid\>.\<param\>="...", for example
|
own parameters, which do exist for every instance. Parameters can be
|
||||||
'eth0.ip=192.168.0.7' or 'echo $eth0.ip'
|
changed on the command line with \<devid\>.\<param\>="...". For
|
||||||
|
example, if you want to access the IPv4 address for eth0, this is done
|
||||||
|
with 'eth0.ip=192.168.0.7' and 'echo $eth0.ip'.
|
||||||
|
|
||||||
- initcalls
|
- <b>Getopt:</b><br>
|
||||||
- hooks in the startup process can be achieved with *_initcall() directives
|
@a Barebox has a lightweight getopt() implementation. This makes it
|
||||||
in each file.
|
unnecessary to use positional parameters, which can be hard to read.
|
||||||
|
|
||||||
- getopt
|
- <b>Integrated Editor:</b><br>
|
||||||
- There is a small getopt implementation. Some commands got really
|
Scripts can be edited with a small integrated fullscreen editor.
|
||||||
complicated (both in code and in usage) due to the fact that @a U-Boot only
|
This editor has no features except the ones really needed: moving
|
||||||
allowed positional parameters.
|
the cursor around, typing characters, exiting and saving.
|
||||||
|
|
||||||
- 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.
|
|
||||||
|
|
||||||
@par Building barebox
|
|
||||||
|
|
||||||
@a Barebox uses the Linux kernel's build system. It consists of two parts:
|
|
||||||
the makefile infrastructure (kbuild), plus a configuration system
|
|
||||||
(kconfig). So building @a barebox is very similar to building the Linux
|
|
||||||
kernel.
|
|
||||||
|
|
||||||
For the examples below, we use the User Mode @a barebox implementation, which
|
|
||||||
is a port of @a barebox to the Linux userspace. This makes it possible to
|
|
||||||
test drive the code without having real hardware. So for this test
|
|
||||||
scenario, @p 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 @p ARCH
|
|
||||||
and @p CROSS_COMPILE, or you can create the soft links cross_arch and
|
|
||||||
cross_compile pointing to your architecture and compiler. For @p ARCH=sandbox
|
|
||||||
we do not need a cross compiler so it is sufficient to specify the
|
|
||||||
architecture:
|
|
||||||
|
|
||||||
@code # ln -s arch/sandbox cross_arch @endcode
|
|
||||||
|
|
||||||
In order to configure the various aspects of @a barebox, start the @a barebox
|
|
||||||
configuration system:
|
|
||||||
|
|
||||||
@code # make menuconfig @endcode
|
|
||||||
|
|
||||||
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 sourcecode.
|
|
||||||
|
|
||||||
Once @a barebox is configured, we can start the compilation
|
|
||||||
|
|
||||||
@code # make @endcode
|
|
||||||
|
|
||||||
If everything goes well, the result is a file called @p barebox:
|
|
||||||
|
|
||||||
@code
|
|
||||||
# ls -l barebox
|
|
||||||
-rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
|
|
||||||
@endcode
|
|
||||||
|
|
||||||
@a barebox usually needs an environment for storing the configuration data.
|
|
||||||
You can generate an environment using the example environment contained
|
|
||||||
in arch/sanbox/board/env:
|
|
||||||
|
|
||||||
@code # ./scripts/bareboxenv -s -p 0x10000 arch/sanbox/board/env/ env.bin @endcode
|
|
||||||
|
|
||||||
To get some files to play with you can generate a cramfs image:
|
|
||||||
|
|
||||||
@code # mkcramfs somedir/ cramfs.bin @endcode
|
|
||||||
|
|
||||||
The @a barebox image is a normal Linux executable, so it can be started
|
|
||||||
just like every other program:
|
|
||||||
|
|
||||||
@code
|
|
||||||
# ./barebox -e env.bin -i cramfs.bin
|
|
||||||
|
|
||||||
barebox 2.0.0-trunk (Jun 26 2007 - 22:34:38)
|
|
||||||
|
|
||||||
loading environment from /dev/env0
|
|
||||||
barebox\> /
|
|
||||||
@endcode
|
|
||||||
|
|
||||||
Specifying -[ie] \<file\> tells @a barebox to map the file as a device
|
|
||||||
under @p /dev. Files given with '-e' will appear as @p /dev/env[n]. Files
|
|
||||||
given with '-i' will appear as @p /dev/fd[n].
|
|
||||||
If @a barebox finds a valid configuration sector on @p /dev/env0 it will
|
|
||||||
load it to @p /env. It then executes @p /env/init if it exists. If you have
|
|
||||||
loaded the example environment @a barebox will show you a menu asking for
|
|
||||||
your settings.
|
|
||||||
|
|
||||||
If you have started @a barebox as root you will find a new tap device on your
|
|
||||||
host which you can configure using ifconfig. Once you configured the
|
|
||||||
network settings accordingly you can do a ping or tftpboot.
|
|
||||||
|
|
||||||
If you have mapped a cramfs image try mounting it with
|
|
||||||
|
|
||||||
@code
|
|
||||||
# mkdir /cram
|
|
||||||
# mount /dev/fd0 cramfs /cram
|
|
||||||
@endcode
|
|
||||||
|
|
||||||
Memory can be examined as usual using @p md/mw commands. They both understand
|
|
||||||
the -f \<file\> option to tell the commands that they should work on the
|
|
||||||
specified files instead of @p /dev/mem which holds the complete address space.
|
|
||||||
Note that if you call 'md /dev/fd0' (without -f) @a barebox will segfault on
|
|
||||||
the host, because it will interpret @p /dev/fd0 as a number.
|
|
||||||
|
|
||||||
@par Directory layout
|
@par Directory layout
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,62 @@
|
||||||
|
/** @page building Building
|
||||||
|
|
||||||
|
<i>This section describes how to build the Barebox bootloader.</i>
|
||||||
|
|
||||||
|
@a Barebox uses Kconfig/Kbuild from the Linux kernel to build it's
|
||||||
|
sources. It consists of two parts: the makefile infrastructure (kbuild)
|
||||||
|
and a configuration system (kconfig). So building @a barebox is very
|
||||||
|
similar to building the Linux kernel.
|
||||||
|
|
||||||
|
In the examples below we use the "sandbox" configuration, which is a
|
||||||
|
port of @a Barebox to the Linux userspace. This makes it possible to
|
||||||
|
test the code without having real hardware or even qemu. Note that the
|
||||||
|
sandbox architecture does only work well on x86 and has some issues on
|
||||||
|
x86_64.
|
||||||
|
|
||||||
|
\todo Find out about issues on x86_64.
|
||||||
|
|
||||||
|
Selecting the architecture and the corresponding cross compiler can be
|
||||||
|
done with two methods: You can either specify it using the environment
|
||||||
|
variables @p ARCH and @p CROSS_COMPILE or you can create the soft links
|
||||||
|
<i>cross_arch</i> and <i>cross_compile</i>, pointing to your
|
||||||
|
architecture and compiler.
|
||||||
|
|
||||||
|
\todo How to use the links? This doesn't work!
|
||||||
|
|
||||||
|
For @p ARCH=sandbox we do not need a cross compiler, so it is sufficient
|
||||||
|
to specify the architecture:
|
||||||
|
|
||||||
|
@code
|
||||||
|
# ln -s arch/sandbox cross_arch
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
In order to configure the various aspects of @a barebox, start the
|
||||||
|
@a barebox configuration system:
|
||||||
|
|
||||||
|
@code
|
||||||
|
# make menuconfig
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
This command starts a menu box and lets you select all the different
|
||||||
|
options available for the selected architecture. Once the configuration
|
||||||
|
is finished (you can simulate this by using the default config file with
|
||||||
|
'make sandbox_defconfig'), there is a .config file in the toplevel
|
||||||
|
directory of the sourcecode.
|
||||||
|
|
||||||
|
After @a barebox is configured, we can start the compilation:
|
||||||
|
|
||||||
|
@code
|
||||||
|
# make
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
You can use '-j \<n\>' in order to do a parallel build if you have more
|
||||||
|
than one cpus.
|
||||||
|
|
||||||
|
If everything goes well, the result is a file called @p barebox:
|
||||||
|
|
||||||
|
@code
|
||||||
|
# ls -l barebox
|
||||||
|
-rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
*/
|
|
@ -1,5 +1,19 @@
|
||||||
/**
|
/**
|
||||||
* @page command_reference Supported Shell Commands
|
* @page command_reference Shell Commands
|
||||||
|
|
||||||
|
<i>This section describes the commands which are available on the @a
|
||||||
|
Barebox shell. </i>
|
||||||
|
|
||||||
|
@a Barebox, as a bootloader, usually shall start the Linux kernel right
|
||||||
|
away. However, there are several use cases around which make it
|
||||||
|
necessary to have some (customizable) logic and interactive scripting
|
||||||
|
possibilities. In order to achieve this, @a Barebox offers several
|
||||||
|
commands on it's integrated commandline shell.
|
||||||
|
|
||||||
|
The following alphabetically sorted list documents all commands
|
||||||
|
available in @a Barebox:
|
||||||
|
|
||||||
|
\todo Sort this by functionality?
|
||||||
|
|
||||||
@li @subpage addpart_command
|
@li @subpage addpart_command
|
||||||
@li @subpage bmp_command
|
@li @subpage bmp_command
|
||||||
|
@ -28,4 +42,5 @@
|
||||||
@li @subpage sh_command
|
@li @subpage sh_command
|
||||||
@li @subpage unprotect_command
|
@li @subpage unprotect_command
|
||||||
@li @subpage linux16_command
|
@li @subpage linux16_command
|
||||||
|
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -0,0 +1,61 @@
|
||||||
|
/** @page first_steps First Steps
|
||||||
|
|
||||||
|
<i>This section demonstrates the first steps with the 'sandbox'
|
||||||
|
platform. </i>
|
||||||
|
|
||||||
|
@a barebox usually needs an environment for storing it's configuration.
|
||||||
|
You can generate an environment using the example-environment contained
|
||||||
|
in arch/sanbox/board/env:
|
||||||
|
|
||||||
|
@code
|
||||||
|
# ./scripts/bareboxenv -s -p 0x10000 arch/sanbox/board/env/ env.bin
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
To get some files to play with you can generate a cramfs image:
|
||||||
|
|
||||||
|
@code
|
||||||
|
# mkcramfs somedir/ cramfs.bin
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
The @a barebox image is a normal Linux executable, so it can be started
|
||||||
|
just like every other program:
|
||||||
|
|
||||||
|
@code
|
||||||
|
# ./barebox -e env.bin -i cramfs.bin
|
||||||
|
|
||||||
|
barebox 2010.10.0 (Oct 29 2010 - 13:47:17)
|
||||||
|
|
||||||
|
loading environment from /dev/env0
|
||||||
|
barebox\> /
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
Specifying -[ie] \<file\> tells @a barebox to map the file as a device
|
||||||
|
under @p /dev. Files given with '-e' will appear as @p /dev/env[n]. Files
|
||||||
|
given with '-i' will appear as @p /dev/fd[n].
|
||||||
|
|
||||||
|
If @a barebox finds a valid configuration sector on @p /dev/env0, it
|
||||||
|
will be loaded into @p /env and executes @p /env/init if existing.
|
||||||
|
The default environment from the example above will show up a menu
|
||||||
|
asking for the relevant settings.
|
||||||
|
|
||||||
|
If you have started @a barebox as root you will find a new tap device on
|
||||||
|
your host which you can configure using ifconfig. Once configured with
|
||||||
|
valid network addresses, barebox can be used to ping the host machine or
|
||||||
|
to fetch files with tftp.
|
||||||
|
|
||||||
|
\todo Add more about tun/tap configuration
|
||||||
|
|
||||||
|
If you have mapped a cramfs image, try mounting it with
|
||||||
|
|
||||||
|
@code
|
||||||
|
# mkdir /cram
|
||||||
|
# mount /dev/fd0 cramfs /cram
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
Memory can be examined using @p md/mw commands. They both understand the
|
||||||
|
-f \<file\> option to tell the commands that they should work on the
|
||||||
|
specified files instead of @p /dev/mem (which holds the complete address
|
||||||
|
space). Note that if you call 'md /dev/fd0' (without -f), @a barebox will
|
||||||
|
segfault on the host, because it will interpret @p /dev/fd0 as a number.
|
||||||
|
|
||||||
|
*/
|
|
@ -1,14 +1,16 @@
|
||||||
/** @page users_manual User's Manual
|
/** @page users_manual User's Manual
|
||||||
|
|
||||||
Who should read this part?
|
This manual provides help for working with @a Barebox from the user's
|
||||||
|
point of view. So if you want to use @a Barebox for booting your target,
|
||||||
|
you find a lot of nice tricks on these pages to make your life easier.
|
||||||
|
|
||||||
Mostly everyone. The user needs it to find help for his daily work to manage
|
@li @subpage building
|
||||||
his targets. The developer to find out all the new features that make his
|
@li @subpage first_steps
|
||||||
work easier.
|
@li @subpage command_reference
|
||||||
|
|
||||||
|
\todo Rework the following sections
|
||||||
@li @subpage shell_notes
|
@li @subpage shell_notes
|
||||||
@li @subpage readline_parser
|
@li @subpage readline_parser
|
||||||
@li @subpage command_reference
|
|
||||||
@li @subpage x86_bootloader
|
@li @subpage x86_bootloader
|
||||||
@li @subpage net_netconsole
|
@li @subpage net_netconsole
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue