diff --git a/Documentation/uboot-main.dox b/Documentation/uboot-main.dox new file mode 100644 index 000000000..694989bdd --- /dev/null +++ b/Documentation/uboot-main.dox @@ -0,0 +1,217 @@ +/** @mainpage Unified Bootloader + +@section uboot_v2_intro Introduction + +This is u2boot, our proposal for a next generation of the famous U-Boot +bootloader. U-Boot offers an excellent choice as a bootloader for +today's embedded systems, seen from a user's point of view. +Nevertheless, there are quite some design flaws which turned out over +the last years and we think that they cannot be solved in a production +tree. So this tree tries to do several things right - without caring +about losing support for old boards. + +@par General features include: + +- A posix based file API + - inside U-Boot 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. + +- Real 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 + - U-Boot 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 U-Boot 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 .="...", 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. + +@par Building U-Boot + +U-Boot uses the Linux kernel's build system. It consists of two parts: +the makefile infrastructure (kbuild), plus a configuration system +(kconfig). So building U-Boot is very similar to building the Linux +kernel. + +For the examples below, we use the User Mode U-Boot implementation, which +is a port of U-Boot 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 in two +ways. You can either specify it using the environment variables ARCH +and CROSS_COMPILE, or you can create the soft links cross_arch and +cross_compile pointing to your architecture and compiler. For ARCH=sandbox +we do not need a cross compiler so it is sufficient to specify the +architecture: + +@code # ln -s sandbox cross_arch @endcode + +In order to configure the various aspects of U-Boot, start the U-Boot +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 sourcode. + +Once U-Boot is configured, we can start the compilation + +@code # make @endcode + +If everything goes well, the result is a file called uboot: + +@code + # ls -l uboot + -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 uboot +@endcode + +U-Boot usually needs an environment for storing the configuation data. +You can generate an environment using the example environment contained +in examples/environment: + +@code # ./scripts/ubootenv -s -p 0x10000 examples/environment/ env.bin @endcode + +To get some files to play with you can generate a cramfs image: + +@code # mkcramfs somedir/ cramfs.bin @endcode + +The U-Boot image is a normal Linux executable, so it can be started +just like every other program: + +@code + # ./uboot -e env.bin -i cramfs.bin + + U-Boot 2.0.0-trunk (Jun 26 2007 - 22:34:38) + + loading environment from /dev/env0 + uboot> / +@endcode + +Specifying -[ie] tells U-Boot 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 U-Boot 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 U-Boot will show you a menu asking for +your settings. + +If you have started U-Boot as root you will find a new tap device on your +host which you can configure using ifconfig. Once you configured U-Boots +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 md/mw commands. They both understand +the -f 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) U-Boot will segfault on +the host, because it will interpret /dev/fd0 as a number. + +@par Directory layout + +Most of the directory layout is based upon the Linux Kernel: + +@verbatim +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 / -> +@endverbatim + +@section license UBoot's License + +@verbatim +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License as +published by the Free Software Foundation; either version 2 of +the License, or (at your option) any later version. + +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 +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place, Suite 330, Boston, +MA 02111-1307 USA +@endverbatim + +*/