]>
Commit | Line | Data |
---|---|---|
3310c549 MB |
1 | How to use images in the new image format |
2 | ========================================= | |
3 | ||
4 | Author: Bartlomiej Sieka <tur@semihalf.com> | |
5 | ||
6 | ||
7 | Overview | |
8 | -------- | |
9 | ||
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. | |
13 | ||
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 | |
5f65826b JL |
19 | |
20 | git://git.kernel.org/pub/scm/utils/dtc/dtc.git | |
21 | ||
22 | for its latest version. mkimage (together with dtc) takes as input | |
3310c549 MB |
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 | |
09b72d69 MY |
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 | |
3310c549 MB |
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. | |
33 | ||
34 | To 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 | ||
41 | Here's a graphical overview of the image creation and booting process: | |
42 | ||
438a4c11 WD |
43 | image source file mkimage + dtc transfer to target |
44 | + ---------------> image file --------------------> bootm | |
09b72d69 | 45 | image data file(s) |
3310c549 | 46 | |
411cf32d AP |
47 | SPL usage |
48 | --------- | |
49 | ||
50 | The SPL can make use of the new image format as well, this traditionally | |
51 | is used to ship multiple device tree files within one image. Code in the SPL | |
52 | will choose the one matching the current board and append this to the | |
53 | U-Boot proper binary to be automatically used up by it. | |
54 | Aside from U-Boot proper and one device tree blob the SPL can load multiple, | |
55 | arbitrary image files as well. These binaries should be specified in their | |
56 | own subnode under the /images node, which should then be referenced from one or | |
57 | multiple /configurations subnodes. The required images must be enumerated in | |
58 | the "loadables" property as a list of strings. | |
59 | ||
60 | If a platform specific image source file (.its) is shipped with the U-Boot | |
61 | source, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol. | |
62 | In this case it will be automatically used by U-Boot's Makefile to generate | |
63 | the image. | |
64 | If a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR | |
65 | can point to a script which generates this image source file during | |
66 | the build process. It gets passed a list of device tree files (taken from the | |
67 | CONFIG_OF_LIST symbol). | |
3310c549 MB |
68 | |
69 | Example 1 -- old-style (non-FDT) kernel booting | |
70 | ----------------------------------------------- | |
71 | ||
72 | Consider a simple scenario, where a PPC Linux kernel built from sources on the | |
73 | development host is to be booted old-style (non-FDT) by U-Boot on an embedded | |
74 | target. Assume that the outcome of the build is vmlinux.bin.gz, a file which | |
75 | contains a gzip-compressed PPC Linux kernel (the only data file in this case). | |
43142e81 BS |
76 | The uImage can be produced using the image source file |
77 | doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is | |
78 | in the current working directory; if desired, an alternative path can be | |
79 | specified in the kernel.its file). Here's how to create the image and inspect | |
80 | its contents: | |
3310c549 MB |
81 | |
82 | [on the host system] | |
83 | $ mkimage -f kernel.its kernel.itb | |
84 | DTC: dts->dtb on file "kernel.its" | |
85 | $ | |
86 | $ mkimage -l kernel.itb | |
87 | FIT description: Simple image with single Linux kernel | |
438a4c11 | 88 | Created: Tue Mar 11 17:26:15 2008 |
83840405 | 89 | Image 0 (kernel) |
438a4c11 WD |
90 | Description: Vanilla Linux kernel |
91 | Type: Kernel Image | |
92 | Compression: gzip compressed | |
93 | Data Size: 943347 Bytes = 921.24 kB = 0.90 MB | |
3310c549 | 94 | Architecture: PowerPC |
438a4c11 | 95 | OS: Linux |
3310c549 | 96 | Load Address: 0x00000000 |
438a4c11 WD |
97 | Entry Point: 0x00000000 |
98 | Hash algo: crc32 | |
99 | Hash value: 2ae2bb40 | |
100 | Hash algo: sha1 | |
101 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 | |
83840405 AP |
102 | Default Configuration: 'config-1' |
103 | Configuration 0 (config-1) | |
438a4c11 | 104 | Description: Boot Linux kernel |
83840405 | 105 | Kernel: kernel |
3310c549 MB |
106 | |
107 | ||
108 | The resulting image file kernel.itb can be now transferred to the target, | |
109 | inspected and booted (note that first three U-Boot commands below are shown | |
110 | for completeness -- they are part of the standard booting procedure and not | |
111 | specific to the new image format). | |
112 | ||
113 | [on the target system] | |
114 | => print nfsargs | |
115 | nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} | |
116 | => print addip | |
117 | addip=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 | |
48690d80 | 120 | Using FEC device |
3310c549 MB |
121 | TFTP from server 192.168.1.1; our IP address is 192.168.160.5 |
122 | Filename '/path/to/tftp/location/kernel.itb'. | |
123 | Load address: 0x900000 | |
124 | Loading: ################################################################# | |
125 | done | |
126 | Bytes 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 | |
438a4c11 | 132 | Created: 2008-03-11 16:26:15 UTC |
83840405 | 133 | Image 0 (kernel) |
3310c549 | 134 | Description: Vanilla Linux kernel |
438a4c11 | 135 | Type: Kernel Image |
3310c549 MB |
136 | Compression: gzip compressed |
137 | Data Start: 0x009000e0 | |
138 | Data Size: 943347 Bytes = 921.2 kB | |
139 | Architecture: PowerPC | |
438a4c11 | 140 | OS: Linux |
3310c549 MB |
141 | Load Address: 0x00000000 |
142 | Entry Point: 0x00000000 | |
143 | Hash algo: crc32 | |
144 | Hash value: 2ae2bb40 | |
145 | Hash algo: sha1 | |
146 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 | |
83840405 AP |
147 | Default Configuration: 'config-1' |
148 | Configuration 0 (config-1) | |
3310c549 | 149 | Description: Boot Linux kernel |
83840405 | 150 | Kernel: kernel |
3310c549 MB |
151 | |
152 | => bootm | |
153 | ## Booting kernel from FIT Image at 00900000 ... | |
83840405 AP |
154 | Using 'config-1' configuration |
155 | Trying 'kernel' kernel subimage | |
3310c549 | 156 | Description: Vanilla Linux kernel |
438a4c11 | 157 | Type: Kernel Image |
3310c549 MB |
158 | Compression: gzip compressed |
159 | Data Start: 0x009000e0 | |
160 | Data Size: 943347 Bytes = 921.2 kB | |
161 | Architecture: PowerPC | |
438a4c11 | 162 | OS: Linux |
3310c549 MB |
163 | 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 | |
171 | Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb | |
172 | 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 | |
173 | On node 0 totalpages: 65536 | |
174 | zone(0): 65536 pages. | |
175 | zone(1): 0 pages. | |
176 | zone(2): 0 pages. | |
177 | 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 | |
178 | Calibrating delay loop... 307.20 BogoMIPS | |
179 | ||
180 | ||
181 | Example 2 -- new-style (FDT) kernel booting | |
182 | ------------------------------------------- | |
183 | ||
184 | Consider another simple scenario, where a PPC Linux kernel is to be booted | |
185 | new-style, i.e., with a FDT blob. In this case there are two prerequisite data | |
186 | files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can | |
43142e81 BS |
187 | be 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 | |
189 | the current working directory -- image source file kernel_fdt.its can be | |
190 | modified to take the files from some other location if needed): | |
3310c549 MB |
191 | |
192 | [on the host system] | |
193 | $ mkimage -f kernel_fdt.its kernel_fdt.itb | |
194 | DTC: dts->dtb on file "kernel_fdt.its" | |
195 | $ | |
196 | $ mkimage -l kernel_fdt.itb | |
197 | FIT description: Simple image with single Linux kernel and FDT blob | |
438a4c11 | 198 | Created: Tue Mar 11 16:29:22 2008 |
83840405 | 199 | Image 0 (kernel) |
438a4c11 WD |
200 | Description: Vanilla Linux kernel |
201 | Type: Kernel Image | |
202 | Compression: gzip compressed | |
203 | Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB | |
3310c549 | 204 | Architecture: PowerPC |
438a4c11 | 205 | OS: Linux |
3310c549 | 206 | Load Address: 0x00000000 |
438a4c11 WD |
207 | Entry Point: 0x00000000 |
208 | Hash algo: crc32 | |
209 | Hash value: 2c0cc807 | |
210 | Hash algo: sha1 | |
211 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb | |
83840405 | 212 | Image 1 (fdt-1) |
438a4c11 WD |
213 | Description: Flattened Device Tree blob |
214 | Type: Flat Device Tree | |
215 | Compression: uncompressed | |
216 | Data Size: 16384 Bytes = 16.00 kB = 0.02 MB | |
3310c549 | 217 | Architecture: PowerPC |
438a4c11 WD |
218 | Hash algo: crc32 |
219 | Hash value: 0d655d71 | |
220 | Hash algo: sha1 | |
221 | Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def | |
83840405 AP |
222 | Default Configuration: 'conf-1' |
223 | Configuration 0 (conf-1) | |
438a4c11 | 224 | Description: Boot Linux kernel with FDT blob |
83840405 AP |
225 | Kernel: kernel |
226 | FDT: fdt-1 | |
3310c549 MB |
227 | |
228 | ||
229 | The resulting image file kernel_fdt.itb can be now transferred to the target, | |
230 | inspected and booted: | |
231 | ||
232 | [on the target system] | |
233 | => tftp 900000 /path/to/tftp/location/kernel_fdt.itb | |
48690d80 | 234 | Using FEC device |
3310c549 MB |
235 | TFTP from server 192.168.1.1; our IP address is 192.168.160.5 |
236 | Filename '/path/to/tftp/location/kernel_fdt.itb'. | |
237 | Load address: 0x900000 | |
238 | Loading: ################################################################# | |
438a4c11 | 239 | ########### |
3310c549 MB |
240 | done |
241 | Bytes 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 | |
438a4c11 | 247 | Created: 2008-03-11 15:29:22 UTC |
83840405 | 248 | Image 0 (kernel) |
3310c549 | 249 | Description: Vanilla Linux kernel |
438a4c11 | 250 | Type: Kernel Image |
3310c549 MB |
251 | Compression: gzip compressed |
252 | Data Start: 0x009000ec | |
253 | Data Size: 1092037 Bytes = 1 MB | |
254 | Architecture: PowerPC | |
438a4c11 | 255 | OS: Linux |
3310c549 MB |
256 | Load Address: 0x00000000 |
257 | Entry Point: 0x00000000 | |
258 | Hash algo: crc32 | |
259 | Hash value: 2c0cc807 | |
260 | Hash algo: sha1 | |
261 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb | |
83840405 | 262 | Image 1 (fdt-1) |
3310c549 | 263 | Description: Flattened Device Tree blob |
438a4c11 | 264 | Type: Flat Device Tree |
3310c549 MB |
265 | 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 | |
83840405 AP |
273 | Default Configuration: 'conf-1' |
274 | Configuration 0 (conf-1) | |
3310c549 | 275 | Description: Boot Linux kernel with FDT blob |
83840405 AP |
276 | Kernel: kernel |
277 | FDT: fdt-1 | |
3310c549 MB |
278 | => bootm |
279 | ## Booting kernel from FIT Image at 00900000 ... | |
83840405 AP |
280 | Using 'conf-1' configuration |
281 | Trying 'kernel' kernel subimage | |
3310c549 | 282 | Description: Vanilla Linux kernel |
438a4c11 | 283 | Type: Kernel Image |
3310c549 MB |
284 | Compression: gzip compressed |
285 | Data Start: 0x009000ec | |
286 | Data Size: 1092037 Bytes = 1 MB | |
287 | Architecture: PowerPC | |
438a4c11 | 288 | OS: Linux |
3310c549 MB |
289 | 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 | |
83840405 AP |
298 | Using 'conf-1' configuration |
299 | Trying 'fdt-1' FDT blob subimage | |
3310c549 | 300 | Description: Flattened Device Tree blob |
438a4c11 | 301 | Type: Flat Device Tree |
3310c549 MB |
302 | 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 | ||
317 | Example 3 -- advanced booting | |
318 | ----------------------------- | |
319 | ||
43142e81 | 320 | Refer to doc/uImage.FIT/multi.its for an image source file that allows more |
3310c549 | 321 | sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). |