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 19 20 git://git.kernel.org/pub/scm/utils/dtc/dtc.git 21 22for its latest version. mkimage (together with dtc) takes as input 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 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 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 43image source file mkimage + dtc transfer to target 44 + ---------------> image file --------------------> bootm 45image data file(s) 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). 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: 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 67Created: Tue Mar 11 17:26:15 2008 68 Image 0 (kernel@1) 69 Description: Vanilla Linux kernel 70 Type: Kernel Image 71 Compression: gzip compressed 72 Data Size: 943347 Bytes = 921.24 kB = 0.90 MB 73 Architecture: PowerPC 74 OS: Linux 75 Load Address: 0x00000000 76 Entry Point: 0x00000000 77 Hash algo: crc32 78 Hash value: 2ae2bb40 79 Hash algo: sha1 80 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 81 Default Configuration: 'config@1' 82 Configuration 0 (config@1) 83 Description: Boot Linux kernel 84 Kernel: kernel@1 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 99Using FEC device 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 111 Created: 2008-03-11 16:26:15 UTC 112 Image 0 (kernel@1) 113 Description: Vanilla Linux kernel 114 Type: Kernel Image 115 Compression: gzip compressed 116 Data Start: 0x009000e0 117 Data Size: 943347 Bytes = 921.2 kB 118 Architecture: PowerPC 119 OS: Linux 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 129 Kernel: kernel@1 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 136 Type: Kernel Image 137 Compression: gzip compressed 138 Data Start: 0x009000e0 139 Data Size: 943347 Bytes = 921.2 kB 140 Architecture: PowerPC 141 OS: Linux 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 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): 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 177Created: Tue Mar 11 16:29:22 2008 178 Image 0 (kernel@1) 179 Description: Vanilla Linux kernel 180 Type: Kernel Image 181 Compression: gzip compressed 182 Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB 183 Architecture: PowerPC 184 OS: Linux 185 Load Address: 0x00000000 186 Entry Point: 0x00000000 187 Hash algo: crc32 188 Hash value: 2c0cc807 189 Hash algo: sha1 190 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb 191 Image 1 (fdt@1) 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 196 Architecture: PowerPC 197 Hash algo: crc32 198 Hash value: 0d655d71 199 Hash algo: sha1 200 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def 201 Default Configuration: 'conf@1' 202 Configuration 0 (conf@1) 203 Description: Boot Linux kernel with FDT blob 204 Kernel: kernel@1 205 FDT: fdt@1 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 213Using FEC device 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: ################################################################# 218 ########### 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 226 Created: 2008-03-11 15:29:22 UTC 227 Image 0 (kernel@1) 228 Description: Vanilla Linux kernel 229 Type: Kernel Image 230 Compression: gzip compressed 231 Data Start: 0x009000ec 232 Data Size: 1092037 Bytes = 1 MB 233 Architecture: PowerPC 234 OS: Linux 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 243 Type: Flat Device Tree 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 255 Kernel: kernel@1 256 FDT: fdt@1 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 262 Type: Kernel Image 263 Compression: gzip compressed 264 Data Start: 0x009000ec 265 Data Size: 1092037 Bytes = 1 MB 266 Architecture: PowerPC 267 OS: Linux 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 280 Type: Flat Device Tree 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 299Refer to doc/uImage.FIT/multi.its for an image source file that allows more 300sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). 301