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 69The SPL also records to a DT all additional images (called loadables) which are 70loaded. The information about loadables locations is passed via the DT node with 71fit-images name. 72 73Loadables Example 74----------------- 75Consider the following case for an ARM64 platform where U-Boot runs in EL2 76started by ATF where SPL is loading U-Boot (as loadables) and ATF (as firmware). 77 78/dts-v1/; 79 80/ { 81 description = "Configuration to load ATF before U-Boot"; 82 83 images { 84 uboot { 85 description = "U-Boot (64-bit)"; 86 data = /incbin/("u-boot-nodtb.bin"); 87 type = "firmware"; 88 os = "u-boot"; 89 arch = "arm64"; 90 compression = "none"; 91 load = <0x8 0x8000000>; 92 entry = <0x8 0x8000000>; 93 hash { 94 algo = "md5"; 95 }; 96 }; 97 atf { 98 description = "ARM Trusted Firmware"; 99 data = /incbin/("bl31.bin"); 100 type = "firmware"; 101 os = "arm-trusted-firmware"; 102 arch = "arm64"; 103 compression = "none"; 104 load = <0xfffea000>; 105 entry = <0xfffea000>; 106 hash { 107 algo = "md5"; 108 }; 109 }; 110 fdt_1 { 111 description = "zynqmp-zcu102-revA"; 112 data = /incbin/("arch/arm/dts/zynqmp-zcu102-revA.dtb"); 113 type = "flat_dt"; 114 arch = "arm64"; 115 compression = "none"; 116 load = <0x100000>; 117 hash { 118 algo = "md5"; 119 }; 120 }; 121 }; 122 configurations { 123 default = "config_1"; 124 125 config_1 { 126 description = "zynqmp-zcu102-revA"; 127 firmware = "atf"; 128 loadables = "uboot"; 129 fdt = "fdt_1"; 130 }; 131 }; 132}; 133 134In this case the SPL records via fit-images DT node the information about 135loadables U-Boot image. 136 137ZynqMP> fdt addr $fdtcontroladdr 138ZynqMP> fdt print /fit-images 139fit-images { 140 uboot { 141 os = "u-boot"; 142 type = "firmware"; 143 size = <0x001017c8>; 144 entry = <0x00000008 0x08000000>; 145 load = <0x00000008 0x08000000>; 146 }; 147}; 148 149As you can see entry and load properties are 64bit wide to support loading 150images above 4GB (in past entry and load properties where just 32bit). 151 152 153Example 1 -- old-style (non-FDT) kernel booting 154----------------------------------------------- 155 156Consider a simple scenario, where a PPC Linux kernel built from sources on the 157development host is to be booted old-style (non-FDT) by U-Boot on an embedded 158target. Assume that the outcome of the build is vmlinux.bin.gz, a file which 159contains a gzip-compressed PPC Linux kernel (the only data file in this case). 160The uImage can be produced using the image source file 161doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is 162in the current working directory; if desired, an alternative path can be 163specified in the kernel.its file). Here's how to create the image and inspect 164its contents: 165 166[on the host system] 167$ mkimage -f kernel.its kernel.itb 168DTC: dts->dtb on file "kernel.its" 169$ 170$ mkimage -l kernel.itb 171FIT description: Simple image with single Linux kernel 172Created: Tue Mar 11 17:26:15 2008 173 Image 0 (kernel) 174 Description: Vanilla Linux kernel 175 Type: Kernel Image 176 Compression: gzip compressed 177 Data Size: 943347 Bytes = 921.24 kB = 0.90 MB 178 Architecture: PowerPC 179 OS: Linux 180 Load Address: 0x00000000 181 Entry Point: 0x00000000 182 Hash algo: crc32 183 Hash value: 2ae2bb40 184 Hash algo: sha1 185 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 186 Default Configuration: 'config-1' 187 Configuration 0 (config-1) 188 Description: Boot Linux kernel 189 Kernel: kernel 190 191 192The resulting image file kernel.itb can be now transferred to the target, 193inspected and booted (note that first three U-Boot commands below are shown 194for completeness -- they are part of the standard booting procedure and not 195specific to the new image format). 196 197[on the target system] 198=> print nfsargs 199nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} 200=> print addip 201addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1 202=> run nfsargs addip 203=> tftp 900000 /path/to/tftp/location/kernel.itb 204Using FEC device 205TFTP from server 192.168.1.1; our IP address is 192.168.160.5 206Filename '/path/to/tftp/location/kernel.itb'. 207Load address: 0x900000 208Loading: ################################################################# 209done 210Bytes transferred = 944464 (e6950 hex) 211=> iminfo 212 213## Checking Image at 00900000 ... 214 FIT image found 215 FIT description: Simple image with single Linux kernel 216 Created: 2008-03-11 16:26:15 UTC 217 Image 0 (kernel) 218 Description: Vanilla Linux kernel 219 Type: Kernel Image 220 Compression: gzip compressed 221 Data Start: 0x009000e0 222 Data Size: 943347 Bytes = 921.2 kB 223 Architecture: PowerPC 224 OS: Linux 225 Load Address: 0x00000000 226 Entry Point: 0x00000000 227 Hash algo: crc32 228 Hash value: 2ae2bb40 229 Hash algo: sha1 230 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 231 Default Configuration: 'config-1' 232 Configuration 0 (config-1) 233 Description: Boot Linux kernel 234 Kernel: kernel 235 236=> bootm 237## Booting kernel from FIT Image at 00900000 ... 238 Using 'config-1' configuration 239 Trying 'kernel' kernel subimage 240 Description: Vanilla Linux kernel 241 Type: Kernel Image 242 Compression: gzip compressed 243 Data Start: 0x009000e0 244 Data Size: 943347 Bytes = 921.2 kB 245 Architecture: PowerPC 246 OS: Linux 247 Load Address: 0x00000000 248 Entry Point: 0x00000000 249 Hash algo: crc32 250 Hash value: 2ae2bb40 251 Hash algo: sha1 252 Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 253 Verifying Hash Integrity ... crc32+ sha1+ OK 254 Uncompressing Kernel Image ... OK 255Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb 256Linux 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 257On node 0 totalpages: 65536 258zone(0): 65536 pages. 259zone(1): 0 pages. 260zone(2): 0 pages. 261Kernel 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 262Calibrating delay loop... 307.20 BogoMIPS 263 264 265Example 2 -- new-style (FDT) kernel booting 266------------------------------------------- 267 268Consider another simple scenario, where a PPC Linux kernel is to be booted 269new-style, i.e., with a FDT blob. In this case there are two prerequisite data 270files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can 271be produced using image source file doc/uImage.FIT/kernel_fdt.its like this 272(note again, that both prerequisite data files are assumed to be present in 273the current working directory -- image source file kernel_fdt.its can be 274modified to take the files from some other location if needed): 275 276[on the host system] 277$ mkimage -f kernel_fdt.its kernel_fdt.itb 278DTC: dts->dtb on file "kernel_fdt.its" 279$ 280$ mkimage -l kernel_fdt.itb 281FIT description: Simple image with single Linux kernel and FDT blob 282Created: Tue Mar 11 16:29:22 2008 283 Image 0 (kernel) 284 Description: Vanilla Linux kernel 285 Type: Kernel Image 286 Compression: gzip compressed 287 Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB 288 Architecture: PowerPC 289 OS: Linux 290 Load Address: 0x00000000 291 Entry Point: 0x00000000 292 Hash algo: crc32 293 Hash value: 2c0cc807 294 Hash algo: sha1 295 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb 296 Image 1 (fdt-1) 297 Description: Flattened Device Tree blob 298 Type: Flat Device Tree 299 Compression: uncompressed 300 Data Size: 16384 Bytes = 16.00 kB = 0.02 MB 301 Architecture: PowerPC 302 Hash algo: crc32 303 Hash value: 0d655d71 304 Hash algo: sha1 305 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def 306 Default Configuration: 'conf-1' 307 Configuration 0 (conf-1) 308 Description: Boot Linux kernel with FDT blob 309 Kernel: kernel 310 FDT: fdt-1 311 312 313The resulting image file kernel_fdt.itb can be now transferred to the target, 314inspected and booted: 315 316[on the target system] 317=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb 318Using FEC device 319TFTP from server 192.168.1.1; our IP address is 192.168.160.5 320Filename '/path/to/tftp/location/kernel_fdt.itb'. 321Load address: 0x900000 322Loading: ################################################################# 323 ########### 324done 325Bytes transferred = 1109776 (10ef10 hex) 326=> iminfo 327 328## Checking Image at 00900000 ... 329 FIT image found 330 FIT description: Simple image with single Linux kernel and FDT blob 331 Created: 2008-03-11 15:29:22 UTC 332 Image 0 (kernel) 333 Description: Vanilla Linux kernel 334 Type: Kernel Image 335 Compression: gzip compressed 336 Data Start: 0x009000ec 337 Data Size: 1092037 Bytes = 1 MB 338 Architecture: PowerPC 339 OS: Linux 340 Load Address: 0x00000000 341 Entry Point: 0x00000000 342 Hash algo: crc32 343 Hash value: 2c0cc807 344 Hash algo: sha1 345 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb 346 Image 1 (fdt-1) 347 Description: Flattened Device Tree blob 348 Type: Flat Device Tree 349 Compression: uncompressed 350 Data Start: 0x00a0abdc 351 Data Size: 16384 Bytes = 16 kB 352 Architecture: PowerPC 353 Hash algo: crc32 354 Hash value: 0d655d71 355 Hash algo: sha1 356 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def 357 Default Configuration: 'conf-1' 358 Configuration 0 (conf-1) 359 Description: Boot Linux kernel with FDT blob 360 Kernel: kernel 361 FDT: fdt-1 362=> bootm 363## Booting kernel from FIT Image at 00900000 ... 364 Using 'conf-1' configuration 365 Trying 'kernel' kernel subimage 366 Description: Vanilla Linux kernel 367 Type: Kernel Image 368 Compression: gzip compressed 369 Data Start: 0x009000ec 370 Data Size: 1092037 Bytes = 1 MB 371 Architecture: PowerPC 372 OS: Linux 373 Load Address: 0x00000000 374 Entry Point: 0x00000000 375 Hash algo: crc32 376 Hash value: 2c0cc807 377 Hash algo: sha1 378 Hash value: 264b59935470e42c418744f83935d44cdf59a3bb 379 Verifying Hash Integrity ... crc32+ sha1+ OK 380 Uncompressing Kernel Image ... OK 381## Flattened Device Tree from FIT Image at 00900000 382 Using 'conf-1' configuration 383 Trying 'fdt-1' FDT blob subimage 384 Description: Flattened Device Tree blob 385 Type: Flat Device Tree 386 Compression: uncompressed 387 Data Start: 0x00a0abdc 388 Data Size: 16384 Bytes = 16 kB 389 Architecture: PowerPC 390 Hash algo: crc32 391 Hash value: 0d655d71 392 Hash algo: sha1 393 Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def 394 Verifying Hash Integrity ... crc32+ sha1+ OK 395 Booting using the fdt blob at 0xa0abdc 396 Loading Device Tree to 007fc000, end 007fffff ... OK 397[ 0.000000] Using lite5200 machine description 398[ 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 399 400 401Example 3 -- advanced booting 402----------------------------- 403 404Refer to doc/uImage.FIT/multi.its for an image source file that allows more 405sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). 406