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