]>
Commit | Line | Data |
---|---|---|
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 | |
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 | |
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. | |
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 | ||
43 | image source file mkimage + dtc transfer to target | |
44 | + ---------------> image file --------------------> bootm | |
45 | image data file(s) | |
46 | ||
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). | |
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). | |
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: | |
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 | |
88 | Created: Tue Mar 11 17:26:15 2008 | |
89 | Image 0 (kernel) | |
90 | Description: Vanilla Linux kernel | |
91 | Type: Kernel Image | |
92 | Compression: gzip compressed | |
93 | Data Size: 943347 Bytes = 921.24 kB = 0.90 MB | |
94 | Architecture: PowerPC | |
95 | OS: Linux | |
96 | Load Address: 0x00000000 | |
97 | Entry Point: 0x00000000 | |
98 | Hash algo: crc32 | |
99 | Hash value: 2ae2bb40 | |
100 | Hash algo: sha1 | |
101 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 | |
102 | Default Configuration: 'config-1' | |
103 | Configuration 0 (config-1) | |
104 | Description: Boot Linux kernel | |
105 | Kernel: kernel | |
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 | |
120 | Using FEC device | |
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 | |
132 | Created: 2008-03-11 16:26:15 UTC | |
133 | Image 0 (kernel) | |
134 | Description: Vanilla Linux kernel | |
135 | Type: Kernel Image | |
136 | Compression: gzip compressed | |
137 | Data Start: 0x009000e0 | |
138 | Data Size: 943347 Bytes = 921.2 kB | |
139 | Architecture: PowerPC | |
140 | OS: Linux | |
141 | 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 | |
150 | Kernel: kernel | |
151 | ||
152 | => bootm | |
153 | ## Booting kernel from FIT Image at 00900000 ... | |
154 | Using 'config-1' configuration | |
155 | Trying 'kernel' kernel subimage | |
156 | Description: Vanilla Linux kernel | |
157 | Type: Kernel Image | |
158 | Compression: gzip compressed | |
159 | Data Start: 0x009000e0 | |
160 | Data Size: 943347 Bytes = 921.2 kB | |
161 | Architecture: PowerPC | |
162 | OS: Linux | |
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 | |
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): | |
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 | |
198 | Created: Tue Mar 11 16:29:22 2008 | |
199 | Image 0 (kernel) | |
200 | Description: Vanilla Linux kernel | |
201 | Type: Kernel Image | |
202 | Compression: gzip compressed | |
203 | Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB | |
204 | Architecture: PowerPC | |
205 | OS: Linux | |
206 | Load Address: 0x00000000 | |
207 | Entry Point: 0x00000000 | |
208 | Hash algo: crc32 | |
209 | Hash value: 2c0cc807 | |
210 | Hash algo: sha1 | |
211 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb | |
212 | Image 1 (fdt-1) | |
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 | |
217 | Architecture: PowerPC | |
218 | Hash algo: crc32 | |
219 | Hash value: 0d655d71 | |
220 | Hash algo: sha1 | |
221 | Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def | |
222 | Default Configuration: 'conf-1' | |
223 | Configuration 0 (conf-1) | |
224 | Description: Boot Linux kernel with FDT blob | |
225 | Kernel: kernel | |
226 | FDT: fdt-1 | |
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 | |
234 | Using FEC device | |
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: ################################################################# | |
239 | ########### | |
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 | |
247 | Created: 2008-03-11 15:29:22 UTC | |
248 | Image 0 (kernel) | |
249 | Description: Vanilla Linux kernel | |
250 | Type: Kernel Image | |
251 | Compression: gzip compressed | |
252 | Data Start: 0x009000ec | |
253 | Data Size: 1092037 Bytes = 1 MB | |
254 | Architecture: PowerPC | |
255 | OS: Linux | |
256 | 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 | |
264 | Type: Flat Device Tree | |
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 | |
273 | Default Configuration: 'conf-1' | |
274 | Configuration 0 (conf-1) | |
275 | Description: Boot Linux kernel with FDT blob | |
276 | Kernel: kernel | |
277 | FDT: fdt-1 | |
278 | => bootm | |
279 | ## Booting kernel from FIT Image at 00900000 ... | |
280 | Using 'conf-1' configuration | |
281 | Trying 'kernel' kernel subimage | |
282 | Description: Vanilla Linux kernel | |
283 | Type: Kernel Image | |
284 | Compression: gzip compressed | |
285 | Data Start: 0x009000ec | |
286 | Data Size: 1092037 Bytes = 1 MB | |
287 | Architecture: PowerPC | |
288 | OS: Linux | |
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 | |
298 | Using 'conf-1' configuration | |
299 | Trying 'fdt-1' FDT blob subimage | |
300 | Description: Flattened Device Tree blob | |
301 | Type: Flat Device Tree | |
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 | ||
320 | Refer to doc/uImage.FIT/multi.its for an image source file that allows more | |
321 | sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). |