rename README.u2 to README

1 files changed, 201 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000000..6f978a3dbf
--- /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 <devid>.<param>="...", 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] <file> 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 <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) 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
+