From a3ffa97f40dc81f2d6b07ee964f2340fe0c1ba97 Mon Sep 17 00:00:00 2001 From: Sascha Hauer Date: Tue, 15 Dec 2009 09:11:09 +0100 Subject: rename U-Boot-v2 project to barebox This has been done with the following script: find -path ./.git -prune -o -type f -print0 | xargs -0 -r sed -i \ -e 's/u2boot/barebox/g' \ -e 's/U2Boot/barebox/g' \ -e 's/U-boot V2/barebox/g' \ -e 's/u-boot v2/barebox/g' \ -e 's/U-Boot V2/barebox/g' \ -e 's/U-Boot-v2/barebox/g' \ -e 's/U_BOOT/BAREBOX/g' \ -e 's/UBOOT/BAREBOX/g' \ -e 's/uboot/barebox/g' \ -e 's/u-boot/barebox/g' \ -e 's/u_boot/barebox/g' \ -e 's/U-Boot/barebox/g' \ -e 's/U-boot/barebox/g' \ -e 's/U-BOOT/barebox/g' find -path ./.git -prune -o \( -name "*u-boot*" -o -name "*uboot*" -o -name "*u_boot*" \) -print0 | \ xargs -0 -r rename 's/u[-_]?boot/barebox/' It needs some manual fixup following in the next patch Signed-off-by: Sascha Hauer --- Documentation/barebox-main.dox | 223 ++++++++++++++++++++++++++++++++++++ Documentation/boards.dox | 2 +- Documentation/console.txt | 4 +- Documentation/developers_manual.dox | 10 +- Documentation/devices_drivers.txt | 2 +- Documentation/manual_org.dox | 2 +- Documentation/porting.txt | 30 ++--- Documentation/timekeeping.txt | 4 +- Documentation/uboot-main.dox | 223 ------------------------------------ 9 files changed, 250 insertions(+), 250 deletions(-) create mode 100644 Documentation/barebox-main.dox delete mode 100644 Documentation/uboot-main.dox (limited to 'Documentation') diff --git a/Documentation/barebox-main.dox b/Documentation/barebox-main.dox new file mode 100644 index 0000000000..2246775269 --- /dev/null +++ b/Documentation/barebox-main.dox @@ -0,0 +1,223 @@ +/** @mainpage Universal Bootloader + +@section barebox_v2_intro Introduction + +This is barebox, our proposal for a next generation of the famous barebox +bootloader. barebox 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 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. + +- 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 + - 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 \.\="...", 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 barebox 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 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 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 barebox, start the 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 sourcode. + +Once barebox is configured, we can start the compilation + +@code # make @endcode + +If everything goes well, the result is a file called barebox: + +@code + # ls -l barebox + -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox +@endcode + +barebox usually needs an environment for storing the configuation data. +You can generate an environment using the example environment contained +in examples/environment: + +@code # ./scripts/bareboxenv -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 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] \ 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 + +@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) barebox 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 barebox'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 + +@subpage users_manual + +@subpage developers_manual + +@subpage supported_boards + +*/ diff --git a/Documentation/boards.dox b/Documentation/boards.dox index c4d05d69af..6c958324e1 100644 --- a/Documentation/boards.dox +++ b/Documentation/boards.dox @@ -1,6 +1,6 @@ /** @page supported_boards Supported Boards -This is a list of boards that are currently supported by U-Boot-v2. +This is a list of boards that are currently supported by barebox. PowerPC type: diff --git a/Documentation/console.txt b/Documentation/console.txt index 7ed67202e4..76b6107ac6 100644 --- a/Documentation/console.txt +++ b/Documentation/console.txt @@ -1,6 +1,6 @@ --------------- U-Boot consoles ------------------ +-------------- barebox consoles ------------------ -U-Boot supports multiple consoles which may be simultaneously active. +barebox supports multiple consoles which may be simultaneously active. Depending on the configuration none, the first or all consoles are activated on startup, see CONSOLE_ACTIVATE_FIRST and CONSOLE_ACTIVATE_ALL options. diff --git a/Documentation/developers_manual.dox b/Documentation/developers_manual.dox index ab941e23b8..6326d453bd 100644 --- a/Documentation/developers_manual.dox +++ b/Documentation/developers_manual.dox @@ -1,23 +1,23 @@ /** @page developers_manual Developer's Manual -This part of the documentation is intended for developers of U-Boot-v2. +This part of the documentation is intended for developers of barebox. -@section devel_backgrounds Some background knowledge for some frameworks U-Boot-v2 +@section devel_backgrounds Some background knowledge for some frameworks barebox @li @subpage driver_model @li @subpage dev_params -@section devel_hints Hints and tips for simply adapting U-Boot-v2 +@section devel_hints Hints and tips for simply adapting barebox @li @subpage dev_architecture @li @subpage dev_cpu @li @subpage dev_board -@section devel_themes Various themes about U-Boot-v2 +@section devel_themes Various themes about barebox @li @subpage how_mount_works @li @subpage boot_preparation -@li @subpage uboot_simul +@li @subpage barebox_simul @li @subpage io_access_functions @li @subpage mcfv4e_MCDlib diff --git a/Documentation/devices_drivers.txt b/Documentation/devices_drivers.txt index 06e788de86..af929fa8c7 100644 --- a/Documentation/devices_drivers.txt +++ b/Documentation/devices_drivers.txt @@ -1,5 +1,5 @@ ----------- Devices and drivers in U-Boot -------------- +---------- Devices and drivers in barebox -------------- We follow a rather simplistic driver model here. There is a struct device which describes a particular device present in the system. A struct driver represents diff --git a/Documentation/manual_org.dox b/Documentation/manual_org.dox index f9cb238a4b..6f3b157876 100644 --- a/Documentation/manual_org.dox +++ b/Documentation/manual_org.dox @@ -6,7 +6,7 @@ than listed here. But these files are the main control files: - Documentation - Documentation/Doxyfile - - Documentation/uboot-main.dox + - Documentation/barebox-main.dox - Documentation/users_manual.dox - Documentation/commands.dox - Documentation/developers_manual.dox diff --git a/Documentation/porting.txt b/Documentation/porting.txt index 174a16ba38..ccfe598a74 100644 --- a/Documentation/porting.txt +++ b/Documentation/porting.txt @@ -1,5 +1,5 @@ -When porting from old U-Boot the follwing steps must be taken (please complain +When porting from old barebox the follwing steps must be taken (please complain if there's something missing here ;) @@ -9,24 +9,24 @@ if there's something missing here ;) configured with the Kconfig system feel free to add them there. - The linker script needs a new section for the initcalls. The handling of the - U-Boot command table has changed, too. (The commands are now sorted by the + barebox command table has changed, too. (The commands are now sorted by the linker instead at runtime.) To change it you need an entry like the following in your linker script: -#include +#include - __u_boot_cmd_start = .; - .u_boot_cmd : { U_BOOT_CMDS } - __u_boot_cmd_end = .; + __barebox_cmd_start = .; + .barebox_cmd : { BAREBOX_CMDS } + __barebox_cmd_end = .; - __u_boot_initcalls_start = .; - .u_boot_initcalls : { INITCALLS } - __u_boot_initcalls_end = .; + __barebox_initcalls_start = .; + .barebox_initcalls : { INITCALLS } + __barebox_initcalls_end = .; -- Rename your linker script to u-boot.lds.S and add the following entry to the +- Rename your linker script to barebox.lds.S and add the following entry to the Makefile to make sure the linker script is generated: -extra-y += u-boot.lds +extra-y += barebox.lds - Register the devices present in your system in the board specific .c file. To see anything you have to at least register a console. In scb9328.c this @@ -72,7 +72,7 @@ extra-y += u-boot.lds set_mac_address() set the MAC address in the device. All magic previously done with getenv/setenv(ethaddr) must be removed. - During startup U-Boot calls get_mac_address() to see if an EEPROM is + During startup barebox calls get_mac_address() to see if an EEPROM is connected. If so, it calls set_mac_address() with this address. This is done even if networking is not used during startup. This makes sure that the MAC address is set in the device and Linux can pick it up later. @@ -91,8 +91,8 @@ extra-y += u-boot.lds - Adjust start.S. On PowerPC there is at least the Problem that the relocation offset is defined at compile time. It is easily possible to determine the - address U-Boot is currently starting from at runtime and thus allowing it - U-Boot to be started at any address. Look at the relocation code and replace + address barebox is currently starting from at runtime and thus allowing it + barebox to be started at any address. Look at the relocation code and replace TEXT_BASE with the following calculation of the runtime address: bl calc_source /* Calculate Source Address */ @@ -105,7 +105,7 @@ calc_source: fortunately I know next to nothing of PowerPC assembler, so if you have a better way to archieve this, please write to the list.) - On PowerPC U-Boot now runs at the address it was linked to, so you have + On PowerPC barebox now runs at the address it was linked to, so you have to adjust TEXT_BASE to be in RAM. This makes the various fixup relocation functions unnecessary. On PowerPC the removal of -fPIC saves around 10% of binary space. It also simplifies debugging because you will see the correct diff --git a/Documentation/timekeeping.txt b/Documentation/timekeeping.txt index 9d778117c1..ed5ef62fe0 100644 --- a/Documentation/timekeeping.txt +++ b/Documentation/timekeeping.txt @@ -1,6 +1,6 @@ ------------- U-Boot timekeeping ------------- +------------ barebox timekeeping ------------- -In U-Boot we use the clocksource mechanism from the Linux Kernel. This makes +In barebox we use the clocksource mechanism from the Linux Kernel. This makes it fairly easy to add timer functionality for a new board or architecture. Apart from initialization there is only one function required: clocksource_read(). This function returns the current value of a free running diff --git a/Documentation/uboot-main.dox b/Documentation/uboot-main.dox deleted file mode 100644 index 424e369c6b..0000000000 --- a/Documentation/uboot-main.dox +++ /dev/null @@ -1,223 +0,0 @@ -/** @mainpage Universal 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 U-Boot'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 - -@subpage users_manual - -@subpage developers_manual - -@subpage supported_boards - -*/ -- cgit v1.2.3