1 How to use images in the new image format
2 =========================================
4 Author: Bartlomiej Sieka <tur@semihalf.com>
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.
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
20 git://git.kernel.org/pub/scm/utils/dtc/dtc.git
22 for its latest version. mkimage (together with dtc) takes as input
23 an image source file, which describes the contents of the image and defines
24 its various properties used during booting. By convention, image source file
25 has the ".its" extension, also, the details of its format are given in
26 doc/uImage.FIT/source_file_format.txt. The actual data that is to be included in
27 the uImage (kernel, ramdisk, etc.) is specified in the image source file in the
28 form of paths to appropriate data files. The outcome of the image creation
29 process is a binary file (by convention with the ".itb" extension) that
30 contains all the referenced data (kernel, ramdisk, etc.) and other information
31 needed by U-Boot to handle the uImage properly. The uImage file is then
32 transferred to the target (e.g., via tftp) and booted using the bootm command.
34 To summarize the prerequisites needed for new uImage creation:
36 - dtc (with support for binary includes)
37 - image source file (*.its)
41 Here's a graphical overview of the image creation and booting process:
43 image source file mkimage + dtc transfer to target
44 + ---------------> image file --------------------> bootm
48 Example 1 -- old-style (non-FDT) kernel booting
49 -----------------------------------------------
51 Consider a simple scenario, where a PPC Linux kernel built from sources on the
52 development host is to be booted old-style (non-FDT) by U-Boot on an embedded
53 target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
54 contains a gzip-compressed PPC Linux kernel (the only data file in this case).
55 The uImage can be produced using the image source file
56 doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
57 in the current working directory; if desired, an alternative path can be
58 specified in the kernel.its file). Here's how to create the image and inspect
62 $ mkimage -f kernel.its kernel.itb
63 DTC: dts->dtb on file "kernel.its"
65 $ mkimage -l kernel.itb
66 FIT description: Simple image with single Linux kernel
67 Created: Tue Mar 11 17:26:15 2008
69 Description: Vanilla Linux kernel
71 Compression: gzip compressed
72 Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
75 Load Address: 0x00000000
76 Entry Point: 0x00000000
80 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
81 Default Configuration: 'config@1'
82 Configuration 0 (config@1)
83 Description: Boot Linux kernel
87 The resulting image file kernel.itb can be now transferred to the target,
88 inspected and booted (note that first three U-Boot commands below are shown
89 for completeness -- they are part of the standard booting procedure and not
90 specific to the new image format).
92 [on the target system]
94 nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
96 addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
98 => tftp 900000 /path/to/tftp/location/kernel.itb
100 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
101 Filename '/path/to/tftp/location/kernel.itb'.
102 Load address: 0x900000
103 Loading: #################################################################
105 Bytes transferred = 944464 (e6950 hex)
108 ## Checking Image at 00900000 ...
110 FIT description: Simple image with single Linux kernel
111 Created: 2008-03-11 16:26:15 UTC
113 Description: Vanilla Linux kernel
115 Compression: gzip compressed
116 Data Start: 0x009000e0
117 Data Size: 943347 Bytes = 921.2 kB
118 Architecture: PowerPC
120 Load Address: 0x00000000
121 Entry Point: 0x00000000
125 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
126 Default Configuration: 'config@1'
127 Configuration 0 (config@1)
128 Description: Boot Linux kernel
132 ## Booting kernel from FIT Image at 00900000 ...
133 Using 'config@1' configuration
134 Trying 'kernel@1' kernel subimage
135 Description: Vanilla Linux kernel
137 Compression: gzip compressed
138 Data Start: 0x009000e0
139 Data Size: 943347 Bytes = 921.2 kB
140 Architecture: PowerPC
142 Load Address: 0x00000000
143 Entry Point: 0x00000000
147 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
148 Verifying Hash Integrity ... crc32+ sha1+ OK
149 Uncompressing Kernel Image ... OK
150 Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
151 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
152 On node 0 totalpages: 65536
153 zone(0): 65536 pages.
156 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
157 Calibrating delay loop... 307.20 BogoMIPS
160 Example 2 -- new-style (FDT) kernel booting
161 -------------------------------------------
163 Consider another simple scenario, where a PPC Linux kernel is to be booted
164 new-style, i.e., with a FDT blob. In this case there are two prerequisite data
165 files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
166 be produced using image source file doc/uImage.FIT/kernel_fdt.its like this
167 (note again, that both prerequisite data files are assumed to be present in
168 the current working directory -- image source file kernel_fdt.its can be
169 modified to take the files from some other location if needed):
172 $ mkimage -f kernel_fdt.its kernel_fdt.itb
173 DTC: dts->dtb on file "kernel_fdt.its"
175 $ mkimage -l kernel_fdt.itb
176 FIT description: Simple image with single Linux kernel and FDT blob
177 Created: Tue Mar 11 16:29:22 2008
179 Description: Vanilla Linux kernel
181 Compression: gzip compressed
182 Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
183 Architecture: PowerPC
185 Load Address: 0x00000000
186 Entry Point: 0x00000000
190 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
192 Description: Flattened Device Tree blob
193 Type: Flat Device Tree
194 Compression: uncompressed
195 Data Size: 16384 Bytes = 16.00 kB = 0.02 MB
196 Architecture: PowerPC
200 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
201 Default Configuration: 'conf@1'
202 Configuration 0 (conf@1)
203 Description: Boot Linux kernel with FDT blob
208 The resulting image file kernel_fdt.itb can be now transferred to the target,
209 inspected and booted:
211 [on the target system]
212 => tftp 900000 /path/to/tftp/location/kernel_fdt.itb
214 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
215 Filename '/path/to/tftp/location/kernel_fdt.itb'.
216 Load address: 0x900000
217 Loading: #################################################################
220 Bytes transferred = 1109776 (10ef10 hex)
223 ## Checking Image at 00900000 ...
225 FIT description: Simple image with single Linux kernel and FDT blob
226 Created: 2008-03-11 15:29:22 UTC
228 Description: Vanilla Linux kernel
230 Compression: gzip compressed
231 Data Start: 0x009000ec
232 Data Size: 1092037 Bytes = 1 MB
233 Architecture: PowerPC
235 Load Address: 0x00000000
236 Entry Point: 0x00000000
240 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
242 Description: Flattened Device Tree blob
243 Type: Flat Device Tree
244 Compression: uncompressed
245 Data Start: 0x00a0abdc
246 Data Size: 16384 Bytes = 16 kB
247 Architecture: PowerPC
251 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
252 Default Configuration: 'conf@1'
253 Configuration 0 (conf@1)
254 Description: Boot Linux kernel with FDT blob
258 ## Booting kernel from FIT Image at 00900000 ...
259 Using 'conf@1' configuration
260 Trying 'kernel@1' kernel subimage
261 Description: Vanilla Linux kernel
263 Compression: gzip compressed
264 Data Start: 0x009000ec
265 Data Size: 1092037 Bytes = 1 MB
266 Architecture: PowerPC
268 Load Address: 0x00000000
269 Entry Point: 0x00000000
273 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
274 Verifying Hash Integrity ... crc32+ sha1+ OK
275 Uncompressing Kernel Image ... OK
276 ## Flattened Device Tree from FIT Image at 00900000
277 Using 'conf@1' configuration
278 Trying 'fdt@1' FDT blob subimage
279 Description: Flattened Device Tree blob
280 Type: Flat Device Tree
281 Compression: uncompressed
282 Data Start: 0x00a0abdc
283 Data Size: 16384 Bytes = 16 kB
284 Architecture: PowerPC
288 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
289 Verifying Hash Integrity ... crc32+ sha1+ OK
290 Booting using the fdt blob at 0xa0abdc
291 Loading Device Tree to 007fc000, end 007fffff ... OK
292 [ 0.000000] Using lite5200 machine description
293 [ 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
296 Example 3 -- advanced booting
297 -----------------------------
299 Refer to doc/uImage.FIT/multi.its for an image source file that allows more
300 sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).