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 47SPL usage 48--------- 49 50The SPL can make use of the new image format as well, this traditionally 51is used to ship multiple device tree files within one image. Code in the SPL 52will choose the one matching the current board and append this to the 53U-Boot proper binary to be automatically used up by it. 54Aside from U-Boot proper and one device tree blob the SPL can load multiple, 55arbitrary image files as well. These binaries should be specified in their 56own subnode under the /images node, which should then be referenced from one or 57multiple /configurations subnodes. The required images must be enumerated in 58the "loadables" property as a list of strings. 59 60If a platform specific image source file (.its) is shipped with the U-Boot 61source, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol. 62In this case it will be automatically used by U-Boot's Makefile to generate 63the image. 64If a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR 65can point to a script which generates this image source file during 66the build process. It gets passed a list of device tree files (taken from the 67CONFIG_OF_LIST symbol). 68 69Example 1 -- old-style (non-FDT) kernel booting 70----------------------------------------------- 71 72Consider a simple scenario, where a PPC Linux kernel built from sources on the 73development host is to be booted old-style (non-FDT) by U-Boot on an embedded 74target. Assume that the outcome of the build is vmlinux.bin.gz, a file which 75contains a gzip-compressed PPC Linux kernel (the only data file in this case). 76The uImage can be produced using the image source file 77doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is 78in the current working directory; if desired, an alternative path can be 79specified in the kernel.its file). Here's how to create the image and inspect 80its contents: 81 82[on the host system] 83$ mkimage -f kernel.its kernel.itb 84DTC: dts->dtb on file "kernel.its" 85$ 86$ mkimage -l kernel.itb 87FIT description: Simple image with single Linux kernel 88Created: 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 108The resulting image file kernel.itb can be now transferred to the target, 109inspected and booted (note that first three U-Boot commands below are shown 110for completeness -- they are part of the standard booting procedure and not 111specific to the new image format). 112 113[on the target system] 114=> print nfsargs 115nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} 116=> print addip 117addip=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 120Using FEC device 121TFTP from server 192.168.1.1; our IP address is 192.168.160.5 122Filename '/path/to/tftp/location/kernel.itb'. 123Load address: 0x900000 124Loading: ################################################################# 125done 126Bytes 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 171Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb 172Linux 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 173On node 0 totalpages: 65536 174zone(0): 65536 pages. 175zone(1): 0 pages. 176zone(2): 0 pages. 177Kernel 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 178Calibrating delay loop... 307.20 BogoMIPS 179 180 181Example 2 -- new-style (FDT) kernel booting 182------------------------------------------- 183 184Consider another simple scenario, where a PPC Linux kernel is to be booted 185new-style, i.e., with a FDT blob. In this case there are two prerequisite data 186files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can 187be 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 189the current working directory -- image source file kernel_fdt.its can be 190modified 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 194DTC: dts->dtb on file "kernel_fdt.its" 195$ 196$ mkimage -l kernel_fdt.itb 197FIT description: Simple image with single Linux kernel and FDT blob 198Created: 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 229The resulting image file kernel_fdt.itb can be now transferred to the target, 230inspected and booted: 231 232[on the target system] 233=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb 234Using FEC device 235TFTP from server 192.168.1.1; our IP address is 192.168.160.5 236Filename '/path/to/tftp/location/kernel_fdt.itb'. 237Load address: 0x900000 238Loading: ################################################################# 239 ########### 240done 241Bytes 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 317Example 3 -- advanced booting 318----------------------------- 319 320Refer to doc/uImage.FIT/multi.its for an image source file that allows more 321sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). 322