]> git.ipfire.org Git - people/ms/u-boot.git/blame - doc/uImage.FIT/howto.txt
ARM: Implement non-cached memory support
[people/ms/u-boot.git] / doc / uImage.FIT / howto.txt
CommitLineData
3310c549
MB
1How 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
5f65826b
JL
19
20 git://git.kernel.org/pub/scm/utils/dtc/dtc.git
21
22for its latest version. mkimage (together with dtc) takes as input
3310c549
MB
23an 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
09b72d69
MY
26doc/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
3310c549
MB
28form 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
438a4c11
WD
43image source file mkimage + dtc transfer to target
44 + ---------------> image file --------------------> bootm
09b72d69 45image data file(s)
3310c549
MB
46
47
48Example 1 -- old-style (non-FDT) kernel booting
49-----------------------------------------------
50
51Consider a simple scenario, where a PPC Linux kernel built from sources on the
52development host is to be booted old-style (non-FDT) by U-Boot on an embedded
53target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
54contains a gzip-compressed PPC Linux kernel (the only data file in this case).
43142e81
BS
55The uImage can be produced using the image source file
56doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
57in the current working directory; if desired, an alternative path can be
58specified in the kernel.its file). Here's how to create the image and inspect
59its contents:
3310c549
MB
60
61[on the host system]
62$ mkimage -f kernel.its kernel.itb
63DTC: dts->dtb on file "kernel.its"
64$
65$ mkimage -l kernel.itb
66FIT description: Simple image with single Linux kernel
438a4c11 67Created: 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
87The resulting image file kernel.itb can be now transferred to the target,
88inspected and booted (note that first three U-Boot commands below are shown
89for completeness -- they are part of the standard booting procedure and not
90specific to the new image format).
91
92[on the target system]
93=> print nfsargs
94nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
95=> print addip
96addip=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 99Using FEC device
3310c549
MB
100TFTP from server 192.168.1.1; our IP address is 192.168.160.5
101Filename '/path/to/tftp/location/kernel.itb'.
102Load address: 0x900000
103Loading: #################################################################
104done
105Bytes 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
150Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
151Linux 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
152On node 0 totalpages: 65536
153zone(0): 65536 pages.
154zone(1): 0 pages.
155zone(2): 0 pages.
156Kernel 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
157Calibrating delay loop... 307.20 BogoMIPS
158
159
160Example 2 -- new-style (FDT) kernel booting
161-------------------------------------------
162
163Consider another simple scenario, where a PPC Linux kernel is to be booted
164new-style, i.e., with a FDT blob. In this case there are two prerequisite data
165files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
43142e81
BS
166be 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
168the current working directory -- image source file kernel_fdt.its can be
169modified 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
173DTC: dts->dtb on file "kernel_fdt.its"
174$
175$ mkimage -l kernel_fdt.itb
176FIT description: Simple image with single Linux kernel and FDT blob
438a4c11 177Created: 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
208The resulting image file kernel_fdt.itb can be now transferred to the target,
209inspected and booted:
210
211[on the target system]
212=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
48690d80 213Using FEC device
3310c549
MB
214TFTP from server 192.168.1.1; our IP address is 192.168.160.5
215Filename '/path/to/tftp/location/kernel_fdt.itb'.
216Load address: 0x900000
217Loading: #################################################################
438a4c11 218 ###########
3310c549
MB
219done
220Bytes 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
296Example 3 -- advanced booting
297-----------------------------
298
43142e81 299Refer to doc/uImage.FIT/multi.its for an image source file that allows more
3310c549 300sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).