]>
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 | |
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 | |
09b72d69 MY |
23 | doc/uImage.FIT/source_file_format.txt. The actual data that is to be included in |
24 | the uImage (kernel, ramdisk, etc.) is specified in the image source file in the | |
3310c549 MB |
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. | |
30 | ||
31 | To summarize the prerequisites needed for new uImage creation: | |
32 | - mkimage | |
33 | - dtc (with support for binary includes) | |
34 | - image source file (*.its) | |
35 | - image data file(s) | |
36 | ||
37 | ||
38 | Here's a graphical overview of the image creation and booting process: | |
39 | ||
438a4c11 WD |
40 | image source file mkimage + dtc transfer to target |
41 | + ---------------> image file --------------------> bootm | |
09b72d69 | 42 | image data file(s) |
3310c549 MB |
43 | |
44 | ||
45 | Example 1 -- old-style (non-FDT) kernel booting | |
46 | ----------------------------------------------- | |
47 | ||
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). | |
43142e81 BS |
52 | The uImage can be produced using the image source file |
53 | doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is | |
54 | in the current working directory; if desired, an alternative path can be | |
55 | specified in the kernel.its file). Here's how to create the image and inspect | |
56 | its contents: | |
3310c549 MB |
57 | |
58 | [on the host system] | |
59 | $ mkimage -f kernel.its kernel.itb | |
60 | DTC: dts->dtb on file "kernel.its" | |
61 | $ | |
62 | $ mkimage -l kernel.itb | |
63 | FIT description: Simple image with single Linux kernel | |
438a4c11 | 64 | Created: Tue Mar 11 17:26:15 2008 |
3310c549 | 65 | Image 0 (kernel@1) |
438a4c11 WD |
66 | Description: Vanilla Linux kernel |
67 | Type: Kernel Image | |
68 | Compression: gzip compressed | |
69 | Data Size: 943347 Bytes = 921.24 kB = 0.90 MB | |
3310c549 | 70 | Architecture: PowerPC |
438a4c11 | 71 | OS: Linux |
3310c549 | 72 | Load Address: 0x00000000 |
438a4c11 WD |
73 | Entry Point: 0x00000000 |
74 | Hash algo: crc32 | |
75 | Hash value: 2ae2bb40 | |
76 | Hash algo: sha1 | |
77 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 | |
3310c549 MB |
78 | Default Configuration: 'config@1' |
79 | Configuration 0 (config@1) | |
438a4c11 WD |
80 | Description: Boot Linux kernel |
81 | Kernel: kernel@1 | |
3310c549 MB |
82 | |
83 | ||
84 | The resulting image file kernel.itb can be now transferred to the target, | |
85 | inspected and booted (note that first three U-Boot commands below are shown | |
86 | for completeness -- they are part of the standard booting procedure and not | |
87 | specific to the new image format). | |
88 | ||
89 | [on the target system] | |
90 | => print nfsargs | |
91 | nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} | |
92 | => print addip | |
93 | addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1 | |
94 | => run nfsargs addip | |
95 | => tftp 900000 /path/to/tftp/location/kernel.itb | |
48690d80 | 96 | Using FEC device |
3310c549 MB |
97 | TFTP from server 192.168.1.1; our IP address is 192.168.160.5 |
98 | Filename '/path/to/tftp/location/kernel.itb'. | |
99 | Load address: 0x900000 | |
100 | Loading: ################################################################# | |
101 | done | |
102 | Bytes transferred = 944464 (e6950 hex) | |
103 | => iminfo | |
104 | ||
105 | ## Checking Image at 00900000 ... | |
106 | FIT image found | |
107 | FIT description: Simple image with single Linux kernel | |
438a4c11 | 108 | Created: 2008-03-11 16:26:15 UTC |
3310c549 MB |
109 | Image 0 (kernel@1) |
110 | Description: Vanilla Linux kernel | |
438a4c11 | 111 | Type: Kernel Image |
3310c549 MB |
112 | Compression: gzip compressed |
113 | Data Start: 0x009000e0 | |
114 | Data Size: 943347 Bytes = 921.2 kB | |
115 | Architecture: PowerPC | |
438a4c11 | 116 | OS: Linux |
3310c549 MB |
117 | Load Address: 0x00000000 |
118 | Entry Point: 0x00000000 | |
119 | Hash algo: crc32 | |
120 | Hash value: 2ae2bb40 | |
121 | Hash algo: sha1 | |
122 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 | |
123 | Default Configuration: 'config@1' | |
124 | Configuration 0 (config@1) | |
125 | Description: Boot Linux kernel | |
438a4c11 | 126 | Kernel: kernel@1 |
3310c549 MB |
127 | |
128 | => bootm | |
129 | ## Booting kernel from FIT Image at 00900000 ... | |
130 | Using 'config@1' configuration | |
131 | Trying 'kernel@1' kernel subimage | |
132 | Description: Vanilla Linux kernel | |
438a4c11 | 133 | Type: Kernel Image |
3310c549 MB |
134 | Compression: gzip compressed |
135 | Data Start: 0x009000e0 | |
136 | Data Size: 943347 Bytes = 921.2 kB | |
137 | Architecture: PowerPC | |
438a4c11 | 138 | OS: Linux |
3310c549 MB |
139 | Load Address: 0x00000000 |
140 | Entry Point: 0x00000000 | |
141 | Hash algo: crc32 | |
142 | Hash value: 2ae2bb40 | |
143 | Hash algo: sha1 | |
144 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 | |
145 | Verifying Hash Integrity ... crc32+ sha1+ OK | |
146 | Uncompressing Kernel Image ... OK | |
147 | Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb | |
148 | 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 | |
149 | On node 0 totalpages: 65536 | |
150 | zone(0): 65536 pages. | |
151 | zone(1): 0 pages. | |
152 | zone(2): 0 pages. | |
153 | 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 | |
154 | Calibrating delay loop... 307.20 BogoMIPS | |
155 | ||
156 | ||
157 | Example 2 -- new-style (FDT) kernel booting | |
158 | ------------------------------------------- | |
159 | ||
160 | Consider another simple scenario, where a PPC Linux kernel is to be booted | |
161 | new-style, i.e., with a FDT blob. In this case there are two prerequisite data | |
162 | files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can | |
43142e81 BS |
163 | be produced using image source file doc/uImage.FIT/kernel_fdt.its like this |
164 | (note again, that both prerequisite data files are assumed to be present in | |
165 | the current working directory -- image source file kernel_fdt.its can be | |
166 | modified to take the files from some other location if needed): | |
3310c549 MB |
167 | |
168 | [on the host system] | |
169 | $ mkimage -f kernel_fdt.its kernel_fdt.itb | |
170 | DTC: dts->dtb on file "kernel_fdt.its" | |
171 | $ | |
172 | $ mkimage -l kernel_fdt.itb | |
173 | FIT description: Simple image with single Linux kernel and FDT blob | |
438a4c11 | 174 | Created: Tue Mar 11 16:29:22 2008 |
3310c549 | 175 | Image 0 (kernel@1) |
438a4c11 WD |
176 | Description: Vanilla Linux kernel |
177 | Type: Kernel Image | |
178 | Compression: gzip compressed | |
179 | Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB | |
3310c549 | 180 | Architecture: PowerPC |
438a4c11 | 181 | OS: Linux |
3310c549 | 182 | Load Address: 0x00000000 |
438a4c11 WD |
183 | Entry Point: 0x00000000 |
184 | Hash algo: crc32 | |
185 | Hash value: 2c0cc807 | |
186 | Hash algo: sha1 | |
187 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb | |
3310c549 | 188 | Image 1 (fdt@1) |
438a4c11 WD |
189 | Description: Flattened Device Tree blob |
190 | Type: Flat Device Tree | |
191 | Compression: uncompressed | |
192 | Data Size: 16384 Bytes = 16.00 kB = 0.02 MB | |
3310c549 | 193 | Architecture: PowerPC |
438a4c11 WD |
194 | Hash algo: crc32 |
195 | Hash value: 0d655d71 | |
196 | Hash algo: sha1 | |
197 | Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def | |
3310c549 MB |
198 | Default Configuration: 'conf@1' |
199 | Configuration 0 (conf@1) | |
438a4c11 WD |
200 | Description: Boot Linux kernel with FDT blob |
201 | Kernel: kernel@1 | |
202 | FDT: fdt@1 | |
3310c549 MB |
203 | |
204 | ||
205 | The resulting image file kernel_fdt.itb can be now transferred to the target, | |
206 | inspected and booted: | |
207 | ||
208 | [on the target system] | |
209 | => tftp 900000 /path/to/tftp/location/kernel_fdt.itb | |
48690d80 | 210 | Using FEC device |
3310c549 MB |
211 | TFTP from server 192.168.1.1; our IP address is 192.168.160.5 |
212 | Filename '/path/to/tftp/location/kernel_fdt.itb'. | |
213 | Load address: 0x900000 | |
214 | Loading: ################################################################# | |
438a4c11 | 215 | ########### |
3310c549 MB |
216 | done |
217 | Bytes transferred = 1109776 (10ef10 hex) | |
218 | => iminfo | |
219 | ||
220 | ## Checking Image at 00900000 ... | |
221 | FIT image found | |
222 | FIT description: Simple image with single Linux kernel and FDT blob | |
438a4c11 | 223 | Created: 2008-03-11 15:29:22 UTC |
3310c549 MB |
224 | Image 0 (kernel@1) |
225 | Description: Vanilla Linux kernel | |
438a4c11 | 226 | Type: Kernel Image |
3310c549 MB |
227 | Compression: gzip compressed |
228 | Data Start: 0x009000ec | |
229 | Data Size: 1092037 Bytes = 1 MB | |
230 | Architecture: PowerPC | |
438a4c11 | 231 | OS: Linux |
3310c549 MB |
232 | Load Address: 0x00000000 |
233 | Entry Point: 0x00000000 | |
234 | Hash algo: crc32 | |
235 | Hash value: 2c0cc807 | |
236 | Hash algo: sha1 | |
237 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb | |
238 | Image 1 (fdt@1) | |
239 | Description: Flattened Device Tree blob | |
438a4c11 | 240 | Type: Flat Device Tree |
3310c549 MB |
241 | Compression: uncompressed |
242 | Data Start: 0x00a0abdc | |
243 | Data Size: 16384 Bytes = 16 kB | |
244 | Architecture: PowerPC | |
245 | Hash algo: crc32 | |
246 | Hash value: 0d655d71 | |
247 | Hash algo: sha1 | |
248 | Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def | |
249 | Default Configuration: 'conf@1' | |
250 | Configuration 0 (conf@1) | |
251 | Description: Boot Linux kernel with FDT blob | |
438a4c11 WD |
252 | Kernel: kernel@1 |
253 | FDT: fdt@1 | |
3310c549 MB |
254 | => bootm |
255 | ## Booting kernel from FIT Image at 00900000 ... | |
256 | Using 'conf@1' configuration | |
257 | Trying 'kernel@1' kernel subimage | |
258 | Description: Vanilla Linux kernel | |
438a4c11 | 259 | Type: Kernel Image |
3310c549 MB |
260 | Compression: gzip compressed |
261 | Data Start: 0x009000ec | |
262 | Data Size: 1092037 Bytes = 1 MB | |
263 | Architecture: PowerPC | |
438a4c11 | 264 | OS: Linux |
3310c549 MB |
265 | Load Address: 0x00000000 |
266 | Entry Point: 0x00000000 | |
267 | Hash algo: crc32 | |
268 | Hash value: 2c0cc807 | |
269 | Hash algo: sha1 | |
270 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb | |
271 | Verifying Hash Integrity ... crc32+ sha1+ OK | |
272 | Uncompressing Kernel Image ... OK | |
273 | ## Flattened Device Tree from FIT Image at 00900000 | |
274 | Using 'conf@1' configuration | |
275 | Trying 'fdt@1' FDT blob subimage | |
276 | Description: Flattened Device Tree blob | |
438a4c11 | 277 | Type: Flat Device Tree |
3310c549 MB |
278 | Compression: uncompressed |
279 | Data Start: 0x00a0abdc | |
280 | Data Size: 16384 Bytes = 16 kB | |
281 | Architecture: PowerPC | |
282 | Hash algo: crc32 | |
283 | Hash value: 0d655d71 | |
284 | Hash algo: sha1 | |
285 | Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def | |
286 | Verifying Hash Integrity ... crc32+ sha1+ OK | |
287 | Booting using the fdt blob at 0xa0abdc | |
288 | Loading Device Tree to 007fc000, end 007fffff ... OK | |
289 | [ 0.000000] Using lite5200 machine description | |
290 | [ 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 | |
291 | ||
292 | ||
293 | Example 3 -- advanced booting | |
294 | ----------------------------- | |
295 | ||
43142e81 | 296 | Refer to doc/uImage.FIT/multi.its for an image source file that allows more |
3310c549 | 297 | sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). |