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
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.
31 To summarize the prerequisites needed for new uImage creation:
33 - dtc (with support for binary includes)
34 - image source file (*.its)
38 Here's a graphical overview of the image creation and booting process:
40 image source file mkimage + dtc transfer to target
41 + ---------------> image file --------------------> bootm
45 Example 1 -- old-style (non-FDT) kernel booting
46 -----------------------------------------------
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 examples/kernel.its
53 (note that kernel.its assumes that vmlinux.bin.gz is in the current working
54 directory; if desired, an alternative path can be specified in the kernel.its
55 file). Here's how to create the image and inspect its contents:
58 $ mkimage -f kernel.its kernel.itb
59 DTC: dts->dtb on file "kernel.its"
61 $ mkimage -l kernel.itb
62 FIT description: Simple image with single Linux kernel
63 Created: Tue Mar 11 17:26:15 2008
65 Description: Vanilla Linux kernel
67 Compression: gzip compressed
68 Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
71 Load Address: 0x00000000
72 Entry Point: 0x00000000
76 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
77 Default Configuration: 'config@1'
78 Configuration 0 (config@1)
79 Description: Boot Linux kernel
83 The resulting image file kernel.itb can be now transferred to the target,
84 inspected and booted (note that first three U-Boot commands below are shown
85 for completeness -- they are part of the standard booting procedure and not
86 specific to the new image format).
88 [on the target system]
90 nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
92 addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
94 => tftp 900000 /path/to/tftp/location/kernel.itb
95 Using FEC ETHERNET device
96 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
97 Filename '/path/to/tftp/location/kernel.itb'.
98 Load address: 0x900000
99 Loading: #################################################################
101 Bytes transferred = 944464 (e6950 hex)
104 ## Checking Image at 00900000 ...
106 FIT description: Simple image with single Linux kernel
107 Created: 2008-03-11 16:26:15 UTC
109 Description: Vanilla Linux kernel
111 Compression: gzip compressed
112 Data Start: 0x009000e0
113 Data Size: 943347 Bytes = 921.2 kB
114 Architecture: PowerPC
116 Load Address: 0x00000000
117 Entry Point: 0x00000000
121 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
122 Default Configuration: 'config@1'
123 Configuration 0 (config@1)
124 Description: Boot Linux kernel
128 ## Booting kernel from FIT Image at 00900000 ...
129 Using 'config@1' configuration
130 Trying 'kernel@1' kernel subimage
131 Description: Vanilla Linux kernel
133 Compression: gzip compressed
134 Data Start: 0x009000e0
135 Data Size: 943347 Bytes = 921.2 kB
136 Architecture: PowerPC
138 Load Address: 0x00000000
139 Entry Point: 0x00000000
143 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
144 Verifying Hash Integrity ... crc32+ sha1+ OK
145 Uncompressing Kernel Image ... OK
146 Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
147 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
148 On node 0 totalpages: 65536
149 zone(0): 65536 pages.
152 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
153 Calibrating delay loop... 307.20 BogoMIPS
156 Example 2 -- new-style (FDT) kernel booting
157 -------------------------------------------
159 Consider another simple scenario, where a PPC Linux kernel is to be booted
160 new-style, i.e., with a FDT blob. In this case there are two prerequisite data
161 files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
162 be produced using image source file examples/kernel_fdt.its like this (note
163 again, that both prerequisite data files are assumed to be present in the
164 current working directory -- image source file kernel_fdt.its can be modified
165 to take the files from some other location if needed):
168 $ mkimage -f kernel_fdt.its kernel_fdt.itb
169 DTC: dts->dtb on file "kernel_fdt.its"
171 $ mkimage -l kernel_fdt.itb
172 FIT description: Simple image with single Linux kernel and FDT blob
173 Created: Tue Mar 11 16:29:22 2008
175 Description: Vanilla Linux kernel
177 Compression: gzip compressed
178 Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
179 Architecture: PowerPC
181 Load Address: 0x00000000
182 Entry Point: 0x00000000
186 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
188 Description: Flattened Device Tree blob
189 Type: Flat Device Tree
190 Compression: uncompressed
191 Data Size: 16384 Bytes = 16.00 kB = 0.02 MB
192 Architecture: PowerPC
196 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
197 Default Configuration: 'conf@1'
198 Configuration 0 (conf@1)
199 Description: Boot Linux kernel with FDT blob
204 The resulting image file kernel_fdt.itb can be now transferred to the target,
205 inspected and booted:
207 [on the target system]
208 => tftp 900000 /path/to/tftp/location/kernel_fdt.itb
209 Using FEC ETHERNET device
210 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
211 Filename '/path/to/tftp/location/kernel_fdt.itb'.
212 Load address: 0x900000
213 Loading: #################################################################
216 Bytes transferred = 1109776 (10ef10 hex)
219 ## Checking Image at 00900000 ...
221 FIT description: Simple image with single Linux kernel and FDT blob
222 Created: 2008-03-11 15:29:22 UTC
224 Description: Vanilla Linux kernel
226 Compression: gzip compressed
227 Data Start: 0x009000ec
228 Data Size: 1092037 Bytes = 1 MB
229 Architecture: PowerPC
231 Load Address: 0x00000000
232 Entry Point: 0x00000000
236 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
238 Description: Flattened Device Tree blob
239 Type: Flat Device Tree
240 Compression: uncompressed
241 Data Start: 0x00a0abdc
242 Data Size: 16384 Bytes = 16 kB
243 Architecture: PowerPC
247 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
248 Default Configuration: 'conf@1'
249 Configuration 0 (conf@1)
250 Description: Boot Linux kernel with FDT blob
254 ## Booting kernel from FIT Image at 00900000 ...
255 Using 'conf@1' configuration
256 Trying 'kernel@1' kernel subimage
257 Description: Vanilla Linux kernel
259 Compression: gzip compressed
260 Data Start: 0x009000ec
261 Data Size: 1092037 Bytes = 1 MB
262 Architecture: PowerPC
264 Load Address: 0x00000000
265 Entry Point: 0x00000000
269 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
270 Verifying Hash Integrity ... crc32+ sha1+ OK
271 Uncompressing Kernel Image ... OK
272 ## Flattened Device Tree from FIT Image at 00900000
273 Using 'conf@1' configuration
274 Trying 'fdt@1' FDT blob subimage
275 Description: Flattened Device Tree blob
276 Type: Flat Device Tree
277 Compression: uncompressed
278 Data Start: 0x00a0abdc
279 Data Size: 16384 Bytes = 16 kB
280 Architecture: PowerPC
284 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
285 Verifying Hash Integrity ... crc32+ sha1+ OK
286 Booting using the fdt blob at 0xa0abdc
287 Loading Device Tree to 007fc000, end 007fffff ... OK
288 [ 0.000000] Using lite5200 machine description
289 [ 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
292 Example 3 -- advanced booting
293 -----------------------------
295 Refer to examples/multi.its for an image source file that allows more
296 sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).