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