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 19www.jdl.com for its latest version. mkimage (together with dtc) takes as input 20an image source file, which describes the contents of the image and defines 21its various properties used during booting. By convention, image source file 22has the ".its" extension, also, the details of its format are given in 23doc/source_file_format.txt. The actual data that is to be included in the 24uImage (kernel, ramdisk, etc.) is specified in the image source file in the 25form of paths to appropriate data files. The outcome of the image creation 26process is a binary file (by convention with the ".itb" extension) that 27contains all the referenced data (kernel, ramdisk, etc.) and other information 28needed by U-Boot to handle the uImage properly. The uImage file is then 29transferred to the target (e.g., via tftp) and booted using the bootm command. 30 31To 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 38Here's a graphical overview of the image creation and booting process: 39 40image source file mkimage + dtc transfer to target 41 + ---------------> image file --------------------> bootm 42image data files(s) 43 44 45Example 1 -- old-style (non-FDT) kernel booting 46----------------------------------------------- 47 48Consider a simple scenario, where a PPC Linux kernel built from sources on the 49development host is to be booted old-style (non-FDT) by U-Boot on an embedded 50target. Assume that the outcome of the build is vmlinux.bin.gz, a file which 51contains a gzip-compressed PPC Linux kernel (the only data file in this case). 52The uImage can be produced using the image source file 53doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is 54in the current working directory; if desired, an alternative path can be 55specified in the kernel.its file). Here's how to create the image and inspect 56its contents: 57 58[on the host system] 59$ mkimage -f kernel.its kernel.itb 60DTC: dts->dtb on file "kernel.its" 61$ 62$ mkimage -l kernel.itb 63FIT description: Simple image with single Linux kernel 64Created: 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 84The resulting image file kernel.itb can be now transferred to the target, 85inspected and booted (note that first three U-Boot commands below are shown 86for completeness -- they are part of the standard booting procedure and not 87specific to the new image format). 88 89[on the target system] 90=> print nfsargs 91nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} 92=> print addip 93addip=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 96Using FEC ETHERNET device 97TFTP from server 192.168.1.1; our IP address is 192.168.160.5 98Filename '/path/to/tftp/location/kernel.itb'. 99Load address: 0x900000 100Loading: ################################################################# 101done 102Bytes 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 147Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb 148Linux 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 149On node 0 totalpages: 65536 150zone(0): 65536 pages. 151zone(1): 0 pages. 152zone(2): 0 pages. 153Kernel 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 154Calibrating delay loop... 307.20 BogoMIPS 155 156 157Example 2 -- new-style (FDT) kernel booting 158------------------------------------------- 159 160Consider another simple scenario, where a PPC Linux kernel is to be booted 161new-style, i.e., with a FDT blob. In this case there are two prerequisite data 162files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can 163be 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 165the current working directory -- image source file kernel_fdt.its can be 166modified 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 170DTC: dts->dtb on file "kernel_fdt.its" 171$ 172$ mkimage -l kernel_fdt.itb 173FIT description: Simple image with single Linux kernel and FDT blob 174Created: 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 205The resulting image file kernel_fdt.itb can be now transferred to the target, 206inspected and booted: 207 208[on the target system] 209=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb 210Using FEC ETHERNET device 211TFTP from server 192.168.1.1; our IP address is 192.168.160.5 212Filename '/path/to/tftp/location/kernel_fdt.itb'. 213Load address: 0x900000 214Loading: ################################################################# 215 ########### 216done 217Bytes 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 293Example 3 -- advanced booting 294----------------------------- 295 296Refer to doc/uImage.FIT/multi.its for an image source file that allows more 297sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). 298