]> git.sur5r.net Git - u-boot/blob - doc/uImage.FIT/howto.txt
easylogo: add optional gzip support
[u-boot] / doc / uImage.FIT / howto.txt
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
23 doc/source_file_format.txt. The actual data that is to be included in the
24 uImage (kernel, ramdisk, etc.) is specified in the image source file in the
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
40 image source file     mkimage + dtc               transfer to target
41         +            ---------------> image file --------------------> bootm
42 image data files(s)
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).
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:
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
64 Created:         Tue Mar 11 17:26:15 2008
65  Image 0 (kernel@1)
66   Description:  Vanilla Linux kernel
67   Type:         Kernel Image
68   Compression:  gzip compressed
69   Data Size:    943347 Bytes = 921.24 kB = 0.90 MB
70   Architecture: PowerPC
71   OS:           Linux
72   Load Address: 0x00000000
73   Entry Point:  0x00000000
74   Hash algo:    crc32
75   Hash value:   2ae2bb40
76   Hash algo:    sha1
77   Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
78  Default Configuration: 'config@1'
79  Configuration 0 (config@1)
80   Description:  Boot Linux kernel
81   Kernel:       kernel@1
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
96 Using FEC ETHERNET device
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
108    Created:         2008-03-11  16:26:15 UTC
109     Image 0 (kernel@1)
110      Description:  Vanilla Linux kernel
111      Type:         Kernel Image
112      Compression:  gzip compressed
113      Data Start:   0x009000e0
114      Data Size:    943347 Bytes = 921.2 kB
115      Architecture: PowerPC
116      OS:           Linux
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
126      Kernel:       kernel@1
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
133      Type:         Kernel Image
134      Compression:  gzip compressed
135      Data Start:   0x009000e0
136      Data Size:    943347 Bytes = 921.2 kB
137      Architecture: PowerPC
138      OS:           Linux
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
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):
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
174 Created:         Tue Mar 11 16:29:22 2008
175  Image 0 (kernel@1)
176   Description:  Vanilla Linux kernel
177   Type:         Kernel Image
178   Compression:  gzip compressed
179   Data Size:    1092037 Bytes = 1066.44 kB = 1.04 MB
180   Architecture: PowerPC
181   OS:           Linux
182   Load Address: 0x00000000
183   Entry Point:  0x00000000
184   Hash algo:    crc32
185   Hash value:   2c0cc807
186   Hash algo:    sha1
187   Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
188  Image 1 (fdt@1)
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
193   Architecture: PowerPC
194   Hash algo:    crc32
195   Hash value:   0d655d71
196   Hash algo:    sha1
197   Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
198  Default Configuration: 'conf@1'
199  Configuration 0 (conf@1)
200   Description:  Boot Linux kernel with FDT blob
201   Kernel:       kernel@1
202   FDT:          fdt@1
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
210 Using FEC ETHERNET device
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: #################################################################
215          ###########
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
223    Created:         2008-03-11  15:29:22 UTC
224     Image 0 (kernel@1)
225      Description:  Vanilla Linux kernel
226      Type:         Kernel Image
227      Compression:  gzip compressed
228      Data Start:   0x009000ec
229      Data Size:    1092037 Bytes =  1 MB
230      Architecture: PowerPC
231      OS:           Linux
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
240      Type:         Flat Device Tree
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
252      Kernel:       kernel@1
253      FDT:          fdt@1
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
259      Type:         Kernel Image
260      Compression:  gzip compressed
261      Data Start:   0x009000ec
262      Data Size:    1092037 Bytes =  1 MB
263      Architecture: PowerPC
264      OS:           Linux
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
277      Type:         Flat Device Tree
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
296 Refer to doc/uImage.FIT/multi.its for an image source file that allows more
297 sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).