diff --git a/README b/README new file mode 100644 index 0000000..6f978a3 --- /dev/null +++ b/README @@ -0,0 +1,201 @@ +U2Boot +------ + +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. + +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. + + +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: + + # ln -s sandbox cross_arch + +In order to configure the various aspects of U-Boot, start the U-Boot +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 U-Boot is configured, we can start the compilation + + # make + +If everything goes well, the result is a file called uboot: + + # ls -l uboot + -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 uboot + +U-Boot usually needs an environment for storing the configuation data. +You can generate an environment using the example environment contained +in examples/environment: + + # ./scripts/ubootenv -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 U-Boot image is a normal Linux executable, so it can be started +just like every other program: + + # ./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> / + +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 + + # mkdir /cram + # mount /dev/fd0 cramfs /cram + +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. + +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/ -> + +There is still the old directory layout in the tree which of course should be +merged in one way or the other: + +lib_*/ -> currently unused +cpu/* -> currently unsused +post/ -> untouched +nand_spl/ -> untouched +dtt/ -> untouched +disk/ -> untouched +documentation/ -> untouched + diff --git a/README.u2 b/README.u2 deleted file mode 100644 index 6f978a3..0000000 --- a/README.u2 +++ /dev/null @@ -1,201 +0,0 @@ -U2Boot ------- - -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. - -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. - - -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: - - # ln -s sandbox cross_arch - -In order to configure the various aspects of U-Boot, start the U-Boot -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 U-Boot is configured, we can start the compilation - - # make - -If everything goes well, the result is a file called uboot: - - # ls -l uboot - -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 uboot - -U-Boot usually needs an environment for storing the configuation data. -You can generate an environment using the example environment contained -in examples/environment: - - # ./scripts/ubootenv -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 U-Boot image is a normal Linux executable, so it can be started -just like every other program: - - # ./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> / - -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 - - # mkdir /cram - # mount /dev/fd0 cramfs /cram - -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. - -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/ -> - -There is still the old directory layout in the tree which of course should be -merged in one way or the other: - -lib_*/ -> currently unused -cpu/* -> currently unsused -post/ -> untouched -nand_spl/ -> untouched -dtt/ -> untouched -disk/ -> untouched -documentation/ -> untouched -