blob: 2988a52aa176629483e9fe6333a1ec600cb93cc7 [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
Jon Loeliger5f658262014-05-27 09:12:48 -050019
20 git://git.kernel.org/pub/scm/utils/dtc/dtc.git
21
22for its latest version. mkimage (together with dtc) takes as input
Marian Balakowicz3310c542008-03-12 12:13:13 +010023an image source file, which describes the contents of the image and defines
24its various properties used during booting. By convention, image source file
25has the ".its" extension, also, the details of its format are given in
Masahiro Yamada09b72d62014-01-16 11:05:23 +090026doc/uImage.FIT/source_file_format.txt. The actual data that is to be included in
27the uImage (kernel, ramdisk, etc.) is specified in the image source file in the
Marian Balakowicz3310c542008-03-12 12:13:13 +010028form of paths to appropriate data files. The outcome of the image creation
29process is a binary file (by convention with the ".itb" extension) that
30contains all the referenced data (kernel, ramdisk, etc.) and other information
31needed by U-Boot to handle the uImage properly. The uImage file is then
32transferred to the target (e.g., via tftp) and booted using the bootm command.
33
34To summarize the prerequisites needed for new uImage creation:
35- mkimage
36- dtc (with support for binary includes)
37- image source file (*.its)
38- image data file(s)
39
40
41Here's a graphical overview of the image creation and booting process:
42
Wolfgang Denk438a4c12008-03-26 11:48:46 +010043image source file mkimage + dtc transfer to target
44 + ---------------> image file --------------------> bootm
Masahiro Yamada09b72d62014-01-16 11:05:23 +090045image data file(s)
Marian Balakowicz3310c542008-03-12 12:13:13 +010046
Andre Przywara411cf322017-04-26 01:32:37 +010047SPL usage
48---------
49
50The SPL can make use of the new image format as well, this traditionally
51is used to ship multiple device tree files within one image. Code in the SPL
52will choose the one matching the current board and append this to the
53U-Boot proper binary to be automatically used up by it.
54Aside from U-Boot proper and one device tree blob the SPL can load multiple,
55arbitrary image files as well. These binaries should be specified in their
56own subnode under the /images node, which should then be referenced from one or
57multiple /configurations subnodes. The required images must be enumerated in
58the "loadables" property as a list of strings.
59
60If a platform specific image source file (.its) is shipped with the U-Boot
61source, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol.
62In this case it will be automatically used by U-Boot's Makefile to generate
63the image.
64If a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR
65can point to a script which generates this image source file during
66the build process. It gets passed a list of device tree files (taken from the
67CONFIG_OF_LIST symbol).
Marian Balakowicz3310c542008-03-12 12:13:13 +010068
69Example 1 -- old-style (non-FDT) kernel booting
70-----------------------------------------------
71
72Consider a simple scenario, where a PPC Linux kernel built from sources on the
73development host is to be booted old-style (non-FDT) by U-Boot on an embedded
74target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
75contains a gzip-compressed PPC Linux kernel (the only data file in this case).
Bartlomiej Sieka43142e82008-03-20 23:10:19 +010076The uImage can be produced using the image source file
77doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
78in the current working directory; if desired, an alternative path can be
79specified in the kernel.its file). Here's how to create the image and inspect
80its contents:
Marian Balakowicz3310c542008-03-12 12:13:13 +010081
82[on the host system]
83$ mkimage -f kernel.its kernel.itb
84DTC: dts->dtb on file "kernel.its"
85$
86$ mkimage -l kernel.itb
87FIT description: Simple image with single Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +010088Created: Tue Mar 11 17:26:15 2008
Marian Balakowicz3310c542008-03-12 12:13:13 +010089 Image 0 (kernel@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +010090 Description: Vanilla Linux kernel
91 Type: Kernel Image
92 Compression: gzip compressed
93 Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
Marian Balakowicz3310c542008-03-12 12:13:13 +010094 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +010095 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +010096 Load Address: 0x00000000
Wolfgang Denk438a4c12008-03-26 11:48:46 +010097 Entry Point: 0x00000000
98 Hash algo: crc32
99 Hash value: 2ae2bb40
100 Hash algo: sha1
101 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
Marian Balakowicz3310c542008-03-12 12:13:13 +0100102 Default Configuration: 'config@1'
103 Configuration 0 (config@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100104 Description: Boot Linux kernel
105 Kernel: kernel@1
Marian Balakowicz3310c542008-03-12 12:13:13 +0100106
107
108The resulting image file kernel.itb can be now transferred to the target,
109inspected and booted (note that first three U-Boot commands below are shown
110for completeness -- they are part of the standard booting procedure and not
111specific to the new image format).
112
113[on the target system]
114=> print nfsargs
115nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
116=> print addip
117addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
118=> run nfsargs addip
119=> tftp 900000 /path/to/tftp/location/kernel.itb
Heiko Schocher48690d82010-07-20 17:45:02 +0200120Using FEC device
Marian Balakowicz3310c542008-03-12 12:13:13 +0100121TFTP from server 192.168.1.1; our IP address is 192.168.160.5
122Filename '/path/to/tftp/location/kernel.itb'.
123Load address: 0x900000
124Loading: #################################################################
125done
126Bytes transferred = 944464 (e6950 hex)
127=> iminfo
128
129## Checking Image at 00900000 ...
130 FIT image found
131 FIT description: Simple image with single Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100132 Created: 2008-03-11 16:26:15 UTC
Marian Balakowicz3310c542008-03-12 12:13:13 +0100133 Image 0 (kernel@1)
134 Description: Vanilla Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100135 Type: Kernel Image
Marian Balakowicz3310c542008-03-12 12:13:13 +0100136 Compression: gzip compressed
137 Data Start: 0x009000e0
138 Data Size: 943347 Bytes = 921.2 kB
139 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100140 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100141 Load Address: 0x00000000
142 Entry Point: 0x00000000
143 Hash algo: crc32
144 Hash value: 2ae2bb40
145 Hash algo: sha1
146 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
147 Default Configuration: 'config@1'
148 Configuration 0 (config@1)
149 Description: Boot Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100150 Kernel: kernel@1
Marian Balakowicz3310c542008-03-12 12:13:13 +0100151
152=> bootm
153## Booting kernel from FIT Image at 00900000 ...
154 Using 'config@1' configuration
155 Trying 'kernel@1' kernel subimage
156 Description: Vanilla Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100157 Type: Kernel Image
Marian Balakowicz3310c542008-03-12 12:13:13 +0100158 Compression: gzip compressed
159 Data Start: 0x009000e0
160 Data Size: 943347 Bytes = 921.2 kB
161 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100162 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100163 Load Address: 0x00000000
164 Entry Point: 0x00000000
165 Hash algo: crc32
166 Hash value: 2ae2bb40
167 Hash algo: sha1
168 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
169 Verifying Hash Integrity ... crc32+ sha1+ OK
170 Uncompressing Kernel Image ... OK
171Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
172Linux 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
173On node 0 totalpages: 65536
174zone(0): 65536 pages.
175zone(1): 0 pages.
176zone(2): 0 pages.
177Kernel 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
178Calibrating delay loop... 307.20 BogoMIPS
179
180
181Example 2 -- new-style (FDT) kernel booting
182-------------------------------------------
183
184Consider another simple scenario, where a PPC Linux kernel is to be booted
185new-style, i.e., with a FDT blob. In this case there are two prerequisite data
186files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
Bartlomiej Sieka43142e82008-03-20 23:10:19 +0100187be produced using image source file doc/uImage.FIT/kernel_fdt.its like this
188(note again, that both prerequisite data files are assumed to be present in
189the current working directory -- image source file kernel_fdt.its can be
190modified to take the files from some other location if needed):
Marian Balakowicz3310c542008-03-12 12:13:13 +0100191
192[on the host system]
193$ mkimage -f kernel_fdt.its kernel_fdt.itb
194DTC: dts->dtb on file "kernel_fdt.its"
195$
196$ mkimage -l kernel_fdt.itb
197FIT description: Simple image with single Linux kernel and FDT blob
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100198Created: Tue Mar 11 16:29:22 2008
Marian Balakowicz3310c542008-03-12 12:13:13 +0100199 Image 0 (kernel@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100200 Description: Vanilla Linux kernel
201 Type: Kernel Image
202 Compression: gzip compressed
203 Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
Marian Balakowicz3310c542008-03-12 12:13:13 +0100204 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100205 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100206 Load Address: 0x00000000
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100207 Entry Point: 0x00000000
208 Hash algo: crc32
209 Hash value: 2c0cc807
210 Hash algo: sha1
211 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
Marian Balakowicz3310c542008-03-12 12:13:13 +0100212 Image 1 (fdt@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100213 Description: Flattened Device Tree blob
214 Type: Flat Device Tree
215 Compression: uncompressed
216 Data Size: 16384 Bytes = 16.00 kB = 0.02 MB
Marian Balakowicz3310c542008-03-12 12:13:13 +0100217 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100218 Hash algo: crc32
219 Hash value: 0d655d71
220 Hash algo: sha1
221 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
Marian Balakowicz3310c542008-03-12 12:13:13 +0100222 Default Configuration: 'conf@1'
223 Configuration 0 (conf@1)
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100224 Description: Boot Linux kernel with FDT blob
225 Kernel: kernel@1
226 FDT: fdt@1
Marian Balakowicz3310c542008-03-12 12:13:13 +0100227
228
229The resulting image file kernel_fdt.itb can be now transferred to the target,
230inspected and booted:
231
232[on the target system]
233=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
Heiko Schocher48690d82010-07-20 17:45:02 +0200234Using FEC device
Marian Balakowicz3310c542008-03-12 12:13:13 +0100235TFTP from server 192.168.1.1; our IP address is 192.168.160.5
236Filename '/path/to/tftp/location/kernel_fdt.itb'.
237Load address: 0x900000
238Loading: #################################################################
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100239 ###########
Marian Balakowicz3310c542008-03-12 12:13:13 +0100240done
241Bytes transferred = 1109776 (10ef10 hex)
242=> iminfo
243
244## Checking Image at 00900000 ...
245 FIT image found
246 FIT description: Simple image with single Linux kernel and FDT blob
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100247 Created: 2008-03-11 15:29:22 UTC
Marian Balakowicz3310c542008-03-12 12:13:13 +0100248 Image 0 (kernel@1)
249 Description: Vanilla Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100250 Type: Kernel Image
Marian Balakowicz3310c542008-03-12 12:13:13 +0100251 Compression: gzip compressed
252 Data Start: 0x009000ec
253 Data Size: 1092037 Bytes = 1 MB
254 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100255 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100256 Load Address: 0x00000000
257 Entry Point: 0x00000000
258 Hash algo: crc32
259 Hash value: 2c0cc807
260 Hash algo: sha1
261 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
262 Image 1 (fdt@1)
263 Description: Flattened Device Tree blob
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100264 Type: Flat Device Tree
Marian Balakowicz3310c542008-03-12 12:13:13 +0100265 Compression: uncompressed
266 Data Start: 0x00a0abdc
267 Data Size: 16384 Bytes = 16 kB
268 Architecture: PowerPC
269 Hash algo: crc32
270 Hash value: 0d655d71
271 Hash algo: sha1
272 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
273 Default Configuration: 'conf@1'
274 Configuration 0 (conf@1)
275 Description: Boot Linux kernel with FDT blob
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100276 Kernel: kernel@1
277 FDT: fdt@1
Marian Balakowicz3310c542008-03-12 12:13:13 +0100278=> bootm
279## Booting kernel from FIT Image at 00900000 ...
280 Using 'conf@1' configuration
281 Trying 'kernel@1' kernel subimage
282 Description: Vanilla Linux kernel
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100283 Type: Kernel Image
Marian Balakowicz3310c542008-03-12 12:13:13 +0100284 Compression: gzip compressed
285 Data Start: 0x009000ec
286 Data Size: 1092037 Bytes = 1 MB
287 Architecture: PowerPC
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100288 OS: Linux
Marian Balakowicz3310c542008-03-12 12:13:13 +0100289 Load Address: 0x00000000
290 Entry Point: 0x00000000
291 Hash algo: crc32
292 Hash value: 2c0cc807
293 Hash algo: sha1
294 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
295 Verifying Hash Integrity ... crc32+ sha1+ OK
296 Uncompressing Kernel Image ... OK
297## Flattened Device Tree from FIT Image at 00900000
298 Using 'conf@1' configuration
299 Trying 'fdt@1' FDT blob subimage
300 Description: Flattened Device Tree blob
Wolfgang Denk438a4c12008-03-26 11:48:46 +0100301 Type: Flat Device Tree
Marian Balakowicz3310c542008-03-12 12:13:13 +0100302 Compression: uncompressed
303 Data Start: 0x00a0abdc
304 Data Size: 16384 Bytes = 16 kB
305 Architecture: PowerPC
306 Hash algo: crc32
307 Hash value: 0d655d71
308 Hash algo: sha1
309 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
310 Verifying Hash Integrity ... crc32+ sha1+ OK
311 Booting using the fdt blob at 0xa0abdc
312 Loading Device Tree to 007fc000, end 007fffff ... OK
313[ 0.000000] Using lite5200 machine description
314[ 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
315
316
317Example 3 -- advanced booting
318-----------------------------
319
Bartlomiej Sieka43142e82008-03-20 23:10:19 +0100320Refer to doc/uImage.FIT/multi.its for an image source file that allows more
Marian Balakowicz3310c542008-03-12 12:13:13 +0100321sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).