cmd: Migrate from_env() from pxe.c to nvedit.c
[oweals/u-boot.git] / 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
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).