summaryrefslogtreecommitdiffstats
path: root/Documentation/uboot-main.dox
blob: 70529a413c097ccb869edf577860b6342df4271e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
/** @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 <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.

@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] <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

@code
  # mkdir /cram
  # mount /dev/fd0 cramfs /cram
@endcode

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. 

@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

*/