blob: 8065e9e1d8d4d65a9b5fe0fce08d3709183d0ee4 [file] [log] [blame]
Marian Balakowicz3310c542008-03-12 12:13:13 +01001How 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
23doc/source_file_format.txt. The actual data that is to be included in the
24uImage (kernel, ramdisk, etc.) is specified in the image source file in the
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
Wolfgang Denk438a4c12008-03-26 11:48:46 +010040image source file mkimage + dtc transfer to target
41 + ---------------> image file --------------------> bootm
Marian Balakowicz3310c542008-03-12 12:13:13 +010042image data files(s)
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).
Bartlomiej Sieka43142e82008-03-20 23:10:19 +010052The 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:
Marian Balakowicz3310c542008-03-12 12:13:13 +010057
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
Wolfgang Denk438a4c12008-03-26 11:48:46 +010064Created: Tue Mar 11 17:26:15 2008
Marian Balakowicz3310c542008-03-12 12:13:13 +010065 Image 0 (kernel@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +010066 Description: Vanilla Linux kernel
67 Type: Kernel Image
68 Compression: gzip compressed
69 Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
Marian Balakowicz3310c542008-03-12 12:13:13 +010070 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +010071 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +010072 Load Address: 0x00000000
Wolfgang Denk438a4c12008-03-26 11:48:46 +010073 Entry Point: 0x00000000
74 Hash algo: crc32
75 Hash value: 2ae2bb40
76 Hash algo: sha1
77 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
Marian Balakowicz3310c542008-03-12 12:13:13 +010078 Default Configuration: 'config@1'
79 Configuration 0 (config@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +010080 Description: Boot Linux kernel
81 Kernel: kernel@1
Marian Balakowicz3310c542008-03-12 12:13:13 +010082
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
96Using FEC ETHERNET device
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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100108 Created: 2008-03-11 16:26:15 UTC
Marian Balakowicz3310c542008-03-12 12:13:13 +0100109 Image 0 (kernel@1)
110 Description: Vanilla Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100111 Type: Kernel Image
Marian Balakowicz3310c542008-03-12 12:13:13 +0100112 Compression: gzip compressed
113 Data Start: 0x009000e0
114 Data Size: 943347 Bytes = 921.2 kB
115 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100116 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100117 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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100126 Kernel: kernel@1
Marian Balakowicz3310c542008-03-12 12:13:13 +0100127
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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100133 Type: Kernel Image
Marian Balakowicz3310c542008-03-12 12:13:13 +0100134 Compression: gzip compressed
135 Data Start: 0x009000e0
136 Data Size: 943347 Bytes = 921.2 kB
137 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100138 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100139 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
Bartlomiej Sieka43142e82008-03-20 23:10:19 +0100163be 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):
Marian Balakowicz3310c542008-03-12 12:13:13 +0100167
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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100174Created: Tue Mar 11 16:29:22 2008
Marian Balakowicz3310c542008-03-12 12:13:13 +0100175 Image 0 (kernel@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100176 Description: Vanilla Linux kernel
177 Type: Kernel Image
178 Compression: gzip compressed
179 Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
Marian Balakowicz3310c542008-03-12 12:13:13 +0100180 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100181 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100182 Load Address: 0x00000000
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100183 Entry Point: 0x00000000
184 Hash algo: crc32
185 Hash value: 2c0cc807
186 Hash algo: sha1
187 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
Marian Balakowicz3310c542008-03-12 12:13:13 +0100188 Image 1 (fdt@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100189 Description: Flattened Device Tree blob
190 Type: Flat Device Tree
191 Compression: uncompressed
192 Data Size: 16384 Bytes = 16.00 kB = 0.02 MB
Marian Balakowicz3310c542008-03-12 12:13:13 +0100193 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100194 Hash algo: crc32
195 Hash value: 0d655d71
196 Hash algo: sha1
197 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
Marian Balakowicz3310c542008-03-12 12:13:13 +0100198 Default Configuration: 'conf@1'
199 Configuration 0 (conf@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100200 Description: Boot Linux kernel with FDT blob
201 Kernel: kernel@1
202 FDT: fdt@1
Marian Balakowicz3310c542008-03-12 12:13:13 +0100203
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
210Using FEC ETHERNET device
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: #################################################################
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100215 ###########
Marian Balakowicz3310c542008-03-12 12:13:13 +0100216done
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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100223 Created: 2008-03-11 15:29:22 UTC
Marian Balakowicz3310c542008-03-12 12:13:13 +0100224 Image 0 (kernel@1)
225 Description: Vanilla Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100226 Type: Kernel Image
Marian Balakowicz3310c542008-03-12 12:13:13 +0100227 Compression: gzip compressed
228 Data Start: 0x009000ec
229 Data Size: 1092037 Bytes = 1 MB
230 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100231 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100232 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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100240 Type: Flat Device Tree
Marian Balakowicz3310c542008-03-12 12:13:13 +0100241 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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100252 Kernel: kernel@1
253 FDT: fdt@1
Marian Balakowicz3310c542008-03-12 12:13:13 +0100254=> 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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100259 Type: Kernel Image
Marian Balakowicz3310c542008-03-12 12:13:13 +0100260 Compression: gzip compressed
261 Data Start: 0x009000ec
262 Data Size: 1092037 Bytes = 1 MB
263 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100264 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100265 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
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100277 Type: Flat Device Tree
Marian Balakowicz3310c542008-03-12 12:13:13 +0100278 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
Bartlomiej Sieka43142e82008-03-20 23:10:19 +0100296Refer to doc/uImage.FIT/multi.its for an image source file that allows more
Marian Balakowicz3310c542008-03-12 12:13:13 +0100297sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).