← Back to branch summary

~ubuntu-branches/ubuntu/maverick/u-boot-omap3/maverick

« back to all changes in this revision

Viewing changes to doc/uImage.FIT/howto.txt

  • Committer: Bazaar Package Importer
  • Author(s): Oliver Grawert
  • Date: 2010-03-22 15:06:23 UTC
  • Revision ID: james.westby@ubuntu.com-20100322150623-i21g8rgiyl5dohag
Tags: upstream-2010.3git20100315
Import upstream version 2010.3git20100315

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/uImage.FIT/howto.txt
 
1
How to use images in the new image format
 
2
=========================================
 
3
 
 
4
Author: Bartlomiej Sieka <tur@semihalf.com>
 
5
 
 
6
 
 
7
Overview
 
8
--------
 
9
 
 
10
The new uImage format allows more flexibility in handling images of various
 
11
types (kernel, ramdisk, etc.), it also enhances integrity protection of images
 
12
with sha1 and md5 checksums.
 
13
 
 
14
Two auxiliary tools are needed on the development host system in order to
 
15
create an uImage in the new format: mkimage and dtc, although only one
 
16
(mkimage) is invoked directly. dtc is called from within mkimage and operates
 
17
behind the scenes, but needs to be present in the $PATH nevertheless. It is
 
18
important that the dtc used has support for binary includes -- refer to
 
19
www.jdl.com for its latest version. mkimage (together with dtc) takes as input
 
20
an image source file, which describes the contents of the image and defines
 
21
its various properties used during booting. By convention, image source file
 
22
has the ".its" extension, also, the details of its format are given in
 
23
doc/source_file_format.txt. The actual data that is to be included in the
 
24
uImage (kernel, ramdisk, etc.) is specified in the image source file in the
 
25
form of paths to appropriate data files. The outcome of the image creation
 
26
process is a binary file (by convention with the ".itb" extension) that
 
27
contains all the referenced data (kernel, ramdisk, etc.) and other information
 
28
needed by U-Boot to handle the uImage properly. The uImage file is then
 
29
transferred to the target (e.g., via tftp) and booted using the bootm command.
 
30
 
 
31
To summarize the prerequisites needed for new uImage creation:
 
32
- mkimage
 
33
- dtc (with support for binary includes)
 
34
- image source file (*.its)
 
35
- image data file(s)
 
36
 
 
37
 
 
38
Here's a graphical overview of the image creation and booting process:
 
39
 
 
40
image source file     mkimage + dtc               transfer to target
 
41
        +            ---------------> image file --------------------> bootm
 
42
image data files(s)
 
43
 
 
44
 
 
45
Example 1 -- old-style (non-FDT) kernel booting
 
46
-----------------------------------------------
 
47
 
 
48
Consider a simple scenario, where a PPC Linux kernel built from sources on the
 
49
development host is to be booted old-style (non-FDT) by U-Boot on an embedded
 
50
target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
 
51
contains a gzip-compressed PPC Linux kernel (the only data file in this case).
 
52
The uImage can be produced using the image source file
 
53
doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
 
54
in the current working directory; if desired, an alternative path can be
 
55
specified in the kernel.its file). Here's how to create the image and inspect
 
56
its contents:
 
57
 
 
58
[on the host system]
 
59
$ mkimage -f kernel.its kernel.itb
 
60
DTC: dts->dtb  on file "kernel.its"
 
61
$
 
62
$ mkimage -l kernel.itb
 
63
FIT description: Simple image with single Linux kernel
 
64
Created:         Tue Mar 11 17:26:15 2008
 
65
 Image 0 (kernel@1)
 
66
  Description:  Vanilla Linux kernel
 
67
  Type:         Kernel Image
 
68
  Compression:  gzip compressed
 
69
  Data Size:    943347 Bytes = 921.24 kB = 0.90 MB
 
70
  Architecture: PowerPC
 
71
  OS:           Linux
 
72
  Load Address: 0x00000000
 
73
  Entry Point:  0x00000000
 
74
  Hash algo:    crc32
 
75
  Hash value:   2ae2bb40
 
76
  Hash algo:    sha1
 
77
  Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
 
78
 Default Configuration: 'config@1'
 
79
 Configuration 0 (config@1)
 
80
  Description:  Boot Linux kernel
 
81
  Kernel:       kernel@1
 
82
 
 
83
 
 
84
The resulting image file kernel.itb can be now transferred to the target,
 
85
inspected and booted (note that first three U-Boot commands below are shown
 
86
for completeness -- they are part of the standard booting procedure and not
 
87
specific to the new image format).
 
88
 
 
89
[on the target system]
 
90
=> print nfsargs
 
91
nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
 
92
=> print addip
 
93
addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
 
94
=> run nfsargs addip
 
95
=> tftp 900000 /path/to/tftp/location/kernel.itb
 
96
Using FEC ETHERNET device
 
97
TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 
98
Filename '/path/to/tftp/location/kernel.itb'.
 
99
Load address: 0x900000
 
100
Loading: #################################################################
 
101
done
 
102
Bytes transferred = 944464 (e6950 hex)
 
103
=> iminfo
 
104
 
 
105
## Checking Image at 00900000 ...
 
106
   FIT image found
 
107
   FIT description: Simple image with single Linux kernel
 
108
   Created:         2008-03-11  16:26:15 UTC
 
109
    Image 0 (kernel@1)
 
110
     Description:  Vanilla Linux kernel
 
111
     Type:         Kernel Image
 
112
     Compression:  gzip compressed
 
113
     Data Start:   0x009000e0
 
114
     Data Size:    943347 Bytes = 921.2 kB
 
115
     Architecture: PowerPC
 
116
     OS:           Linux
 
117
     Load Address: 0x00000000
 
118
     Entry Point:  0x00000000
 
119
     Hash algo:    crc32
 
120
     Hash value:   2ae2bb40
 
121
     Hash algo:    sha1
 
122
     Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
 
123
    Default Configuration: 'config@1'
 
124
    Configuration 0 (config@1)
 
125
     Description:  Boot Linux kernel
 
126
     Kernel:       kernel@1
 
127
 
 
128
=> bootm
 
129
## Booting kernel from FIT Image at 00900000 ...
 
130
   Using 'config@1' configuration
 
131
   Trying 'kernel@1' kernel subimage
 
132
     Description:  Vanilla Linux kernel
 
133
     Type:         Kernel Image
 
134
     Compression:  gzip compressed
 
135
     Data Start:   0x009000e0
 
136
     Data Size:    943347 Bytes = 921.2 kB
 
137
     Architecture: PowerPC
 
138
     OS:           Linux
 
139
     Load Address: 0x00000000
 
140
     Entry Point:  0x00000000
 
141
     Hash algo:    crc32
 
142
     Hash value:   2ae2bb40
 
143
     Hash algo:    sha1
 
144
     Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
 
145
   Verifying Hash Integrity ... crc32+ sha1+ OK
 
146
   Uncompressing Kernel Image ... OK
 
147
Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
 
148
Linux version 2.4.25 (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.0 4.0.0)) #2 czw lip 5 17:56:18 CEST 2007
 
149
On node 0 totalpages: 65536
 
150
zone(0): 65536 pages.
 
151
zone(1): 0 pages.
 
152
zone(2): 0 pages.
 
153
Kernel command line: root=/dev/nfs rw nfsroot=192.168.1.1:/opt/eldk-4.1/ppc_6xx ip=192.168.160.5:192.168.1.1::255.255.0.0:lite5200b:eth0:off panic=1
 
154
Calibrating delay loop... 307.20 BogoMIPS
 
155
 
 
156
 
 
157
Example 2 -- new-style (FDT) kernel booting
 
158
-------------------------------------------
 
159
 
 
160
Consider another simple scenario, where a PPC Linux kernel is to be booted
 
161
new-style, i.e., with a FDT blob. In this case there are two prerequisite data
 
162
files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
 
163
be produced using image source file doc/uImage.FIT/kernel_fdt.its like this
 
164
(note again, that both prerequisite data files are assumed to be present in
 
165
the current working directory -- image source file kernel_fdt.its can be
 
166
modified to take the files from some other location if needed):
 
167
 
 
168
[on the host system]
 
169
$ mkimage -f kernel_fdt.its kernel_fdt.itb
 
170
DTC: dts->dtb  on file "kernel_fdt.its"
 
171
$
 
172
$ mkimage -l kernel_fdt.itb
 
173
FIT description: Simple image with single Linux kernel and FDT blob
 
174
Created:         Tue Mar 11 16:29:22 2008
 
175
 Image 0 (kernel@1)
 
176
  Description:  Vanilla Linux kernel
 
177
  Type:         Kernel Image
 
178
  Compression:  gzip compressed
 
179
  Data Size:    1092037 Bytes = 1066.44 kB = 1.04 MB
 
180
  Architecture: PowerPC
 
181
  OS:           Linux
 
182
  Load Address: 0x00000000
 
183
  Entry Point:  0x00000000
 
184
  Hash algo:    crc32
 
185
  Hash value:   2c0cc807
 
186
  Hash algo:    sha1
 
187
  Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 
188
 Image 1 (fdt@1)
 
189
  Description:  Flattened Device Tree blob
 
190
  Type:         Flat Device Tree
 
191
  Compression:  uncompressed
 
192
  Data Size:    16384 Bytes = 16.00 kB = 0.02 MB
 
193
  Architecture: PowerPC
 
194
  Hash algo:    crc32
 
195
  Hash value:   0d655d71
 
196
  Hash algo:    sha1
 
197
  Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 
198
 Default Configuration: 'conf@1'
 
199
 Configuration 0 (conf@1)
 
200
  Description:  Boot Linux kernel with FDT blob
 
201
  Kernel:       kernel@1
 
202
  FDT:          fdt@1
 
203
 
 
204
 
 
205
The resulting image file kernel_fdt.itb can be now transferred to the target,
 
206
inspected and booted:
 
207
 
 
208
[on the target system]
 
209
=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
 
210
Using FEC ETHERNET device
 
211
TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 
212
Filename '/path/to/tftp/location/kernel_fdt.itb'.
 
213
Load address: 0x900000
 
214
Loading: #################################################################
 
215
         ###########
 
216
done
 
217
Bytes transferred = 1109776 (10ef10 hex)
 
218
=> iminfo
 
219
 
 
220
## Checking Image at 00900000 ...
 
221
   FIT image found
 
222
   FIT description: Simple image with single Linux kernel and FDT blob
 
223
   Created:         2008-03-11  15:29:22 UTC
 
224
    Image 0 (kernel@1)
 
225
     Description:  Vanilla Linux kernel
 
226
     Type:         Kernel Image
 
227
     Compression:  gzip compressed
 
228
     Data Start:   0x009000ec
 
229
     Data Size:    1092037 Bytes =  1 MB
 
230
     Architecture: PowerPC
 
231
     OS:           Linux
 
232
     Load Address: 0x00000000
 
233
     Entry Point:  0x00000000
 
234
     Hash algo:    crc32
 
235
     Hash value:   2c0cc807
 
236
     Hash algo:    sha1
 
237
     Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 
238
    Image 1 (fdt@1)
 
239
     Description:  Flattened Device Tree blob
 
240
     Type:         Flat Device Tree
 
241
     Compression:  uncompressed
 
242
     Data Start:   0x00a0abdc
 
243
     Data Size:    16384 Bytes = 16 kB
 
244
     Architecture: PowerPC
 
245
     Hash algo:    crc32
 
246
     Hash value:   0d655d71
 
247
     Hash algo:    sha1
 
248
     Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 
249
    Default Configuration: 'conf@1'
 
250
    Configuration 0 (conf@1)
 
251
     Description:  Boot Linux kernel with FDT blob
 
252
     Kernel:       kernel@1
 
253
     FDT:          fdt@1
 
254
=> bootm
 
255
## Booting kernel from FIT Image at 00900000 ...
 
256
   Using 'conf@1' configuration
 
257
   Trying 'kernel@1' kernel subimage
 
258
     Description:  Vanilla Linux kernel
 
259
     Type:         Kernel Image
 
260
     Compression:  gzip compressed
 
261
     Data Start:   0x009000ec
 
262
     Data Size:    1092037 Bytes =  1 MB
 
263
     Architecture: PowerPC
 
264
     OS:           Linux
 
265
     Load Address: 0x00000000
 
266
     Entry Point:  0x00000000
 
267
     Hash algo:    crc32
 
268
     Hash value:   2c0cc807
 
269
     Hash algo:    sha1
 
270
     Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 
271
   Verifying Hash Integrity ... crc32+ sha1+ OK
 
272
   Uncompressing Kernel Image ... OK
 
273
## Flattened Device Tree from FIT Image at 00900000
 
274
   Using 'conf@1' configuration
 
275
   Trying 'fdt@1' FDT blob subimage
 
276
     Description:  Flattened Device Tree blob
 
277
     Type:         Flat Device Tree
 
278
     Compression:  uncompressed
 
279
     Data Start:   0x00a0abdc
 
280
     Data Size:    16384 Bytes = 16 kB
 
281
     Architecture: PowerPC
 
282
     Hash algo:    crc32
 
283
     Hash value:   0d655d71
 
284
     Hash algo:    sha1
 
285
     Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 
286
   Verifying Hash Integrity ... crc32+ sha1+ OK
 
287
   Booting using the fdt blob at 0xa0abdc
 
288
   Loading Device Tree to 007fc000, end 007fffff ... OK
 
289
[    0.000000] Using lite5200 machine description
 
290
[    0.000000] Linux version 2.6.24-rc6-gaebecdfc (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.1 4.0.0)) #1 Sat Jan 12 15:38:48 CET 2008
 
291
 
 
292
 
 
293
Example 3 -- advanced booting
 
294
-----------------------------
 
295
 
 
296
Refer to doc/uImage.FIT/multi.its for an image source file that allows more
 
297
sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).