]> git.ipfire.org Git - people/ms/u-boot.git/blame - doc/uImage.FIT/howto.txt
Merge branch 'master' of git://git.denx.de/u-boot-arm
[people/ms/u-boot.git] / doc / uImage.FIT / howto.txt
CommitLineData
3310c549
MB
1How to use images in the new image format
2=========================================
3
4Author: Bartlomiej Sieka <tur@semihalf.com>
5
6
7Overview
8--------
9
10The new uImage format allows more flexibility in handling images of various
11types (kernel, ramdisk, etc.), it also enhances integrity protection of images
12with sha1 and md5 checksums.
13
14Two auxiliary tools are needed on the development host system in order to
15create 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
17behind the scenes, but needs to be present in the $PATH nevertheless. It is
18important that the dtc used has support for binary includes -- refer to
19www.jdl.com for its latest version. mkimage (together with dtc) takes as input
20an image source file, which describes the contents of the image and defines
21its various properties used during booting. By convention, image source file
22has the ".its" extension, also, the details of its format are given in
09b72d69
MY
23doc/uImage.FIT/source_file_format.txt. The actual data that is to be included in
24the uImage (kernel, ramdisk, etc.) is specified in the image source file in the
3310c549
MB
25form of paths to appropriate data files. The outcome of the image creation
26process is a binary file (by convention with the ".itb" extension) that
27contains all the referenced data (kernel, ramdisk, etc.) and other information
28needed by U-Boot to handle the uImage properly. The uImage file is then
29transferred to the target (e.g., via tftp) and booted using the bootm command.
30
31To 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
38Here's a graphical overview of the image creation and booting process:
39
438a4c11
WD
40image source file mkimage + dtc transfer to target
41 + ---------------> image file --------------------> bootm
09b72d69 42image data file(s)
3310c549
MB
43
44
45Example 1 -- old-style (non-FDT) kernel booting
46-----------------------------------------------
47
48Consider a simple scenario, where a PPC Linux kernel built from sources on the
49development host is to be booted old-style (non-FDT) by U-Boot on an embedded
50target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
51contains a gzip-compressed PPC Linux kernel (the only data file in this case).
43142e81
BS
52The uImage can be produced using the image source file
53doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
54in the current working directory; if desired, an alternative path can be
55specified in the kernel.its file). Here's how to create the image and inspect
56its contents:
3310c549
MB
57
58[on the host system]
59$ mkimage -f kernel.its kernel.itb
60DTC: dts->dtb on file "kernel.its"
61$
62$ mkimage -l kernel.itb
63FIT description: Simple image with single Linux kernel
438a4c11 64Created: Tue Mar 11 17:26:15 2008
3310c549 65 Image 0 (kernel@1)
438a4c11
WD
66 Description: Vanilla Linux kernel
67 Type: Kernel Image
68 Compression: gzip compressed
69 Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
3310c549 70 Architecture: PowerPC
438a4c11 71 OS: Linux
3310c549 72 Load Address: 0x00000000
438a4c11
WD
73 Entry Point: 0x00000000
74 Hash algo: crc32
75 Hash value: 2ae2bb40
76 Hash algo: sha1
77 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
3310c549
MB
78 Default Configuration: 'config@1'
79 Configuration 0 (config@1)
438a4c11
WD
80 Description: Boot Linux kernel
81 Kernel: kernel@1
3310c549
MB
82
83
84The resulting image file kernel.itb can be now transferred to the target,
85inspected and booted (note that first three U-Boot commands below are shown
86for completeness -- they are part of the standard booting procedure and not
87specific to the new image format).
88
89[on the target system]
90=> print nfsargs
91nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
92=> print addip
93addip=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
48690d80 96Using FEC device
3310c549
MB
97TFTP from server 192.168.1.1; our IP address is 192.168.160.5
98Filename '/path/to/tftp/location/kernel.itb'.
99Load address: 0x900000
100Loading: #################################################################
101done
102Bytes 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
438a4c11 108 Created: 2008-03-11 16:26:15 UTC
3310c549
MB
109 Image 0 (kernel@1)
110 Description: Vanilla Linux kernel
438a4c11 111 Type: Kernel Image
3310c549
MB
112 Compression: gzip compressed
113 Data Start: 0x009000e0
114 Data Size: 943347 Bytes = 921.2 kB
115 Architecture: PowerPC
438a4c11 116 OS: Linux
3310c549
MB
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
438a4c11 126 Kernel: kernel@1
3310c549
MB
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
438a4c11 133 Type: Kernel Image
3310c549
MB
134 Compression: gzip compressed
135 Data Start: 0x009000e0
136 Data Size: 943347 Bytes = 921.2 kB
137 Architecture: PowerPC
438a4c11 138 OS: Linux
3310c549
MB
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
147Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
148Linux 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
149On node 0 totalpages: 65536
150zone(0): 65536 pages.
151zone(1): 0 pages.
152zone(2): 0 pages.
153Kernel 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
154Calibrating delay loop... 307.20 BogoMIPS
155
156
157Example 2 -- new-style (FDT) kernel booting
158-------------------------------------------
159
160Consider another simple scenario, where a PPC Linux kernel is to be booted
161new-style, i.e., with a FDT blob. In this case there are two prerequisite data
162files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
43142e81
BS
163be 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
165the current working directory -- image source file kernel_fdt.its can be
166modified to take the files from some other location if needed):
3310c549
MB
167
168[on the host system]
169$ mkimage -f kernel_fdt.its kernel_fdt.itb
170DTC: dts->dtb on file "kernel_fdt.its"
171$
172$ mkimage -l kernel_fdt.itb
173FIT description: Simple image with single Linux kernel and FDT blob
438a4c11 174Created: Tue Mar 11 16:29:22 2008
3310c549 175 Image 0 (kernel@1)
438a4c11
WD
176 Description: Vanilla Linux kernel
177 Type: Kernel Image
178 Compression: gzip compressed
179 Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
3310c549 180 Architecture: PowerPC
438a4c11 181 OS: Linux
3310c549 182 Load Address: 0x00000000
438a4c11
WD
183 Entry Point: 0x00000000
184 Hash algo: crc32
185 Hash value: 2c0cc807
186 Hash algo: sha1
187 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
3310c549 188 Image 1 (fdt@1)
438a4c11
WD
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
3310c549 193 Architecture: PowerPC
438a4c11
WD
194 Hash algo: crc32
195 Hash value: 0d655d71
196 Hash algo: sha1
197 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
3310c549
MB
198 Default Configuration: 'conf@1'
199 Configuration 0 (conf@1)
438a4c11
WD
200 Description: Boot Linux kernel with FDT blob
201 Kernel: kernel@1
202 FDT: fdt@1
3310c549
MB
203
204
205The resulting image file kernel_fdt.itb can be now transferred to the target,
206inspected and booted:
207
208[on the target system]
209=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
48690d80 210Using FEC device
3310c549
MB
211TFTP from server 192.168.1.1; our IP address is 192.168.160.5
212Filename '/path/to/tftp/location/kernel_fdt.itb'.
213Load address: 0x900000
214Loading: #################################################################
438a4c11 215 ###########
3310c549
MB
216done
217Bytes 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
438a4c11 223 Created: 2008-03-11 15:29:22 UTC
3310c549
MB
224 Image 0 (kernel@1)
225 Description: Vanilla Linux kernel
438a4c11 226 Type: Kernel Image
3310c549
MB
227 Compression: gzip compressed
228 Data Start: 0x009000ec
229 Data Size: 1092037 Bytes = 1 MB
230 Architecture: PowerPC
438a4c11 231 OS: Linux
3310c549
MB
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
438a4c11 240 Type: Flat Device Tree
3310c549
MB
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
438a4c11
WD
252 Kernel: kernel@1
253 FDT: fdt@1
3310c549
MB
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
438a4c11 259 Type: Kernel Image
3310c549
MB
260 Compression: gzip compressed
261 Data Start: 0x009000ec
262 Data Size: 1092037 Bytes = 1 MB
263 Architecture: PowerPC
438a4c11 264 OS: Linux
3310c549
MB
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
438a4c11 277 Type: Flat Device Tree
3310c549
MB
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
293Example 3 -- advanced booting
294-----------------------------
295
43142e81 296Refer to doc/uImage.FIT/multi.its for an image source file that allows more
3310c549 297sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).