13310c549SMarian BalakowiczHow to use images in the new image format 23310c549SMarian Balakowicz========================================= 33310c549SMarian Balakowicz 43310c549SMarian BalakowiczAuthor: Bartlomiej Sieka <tur@semihalf.com> 53310c549SMarian Balakowicz 63310c549SMarian Balakowicz 73310c549SMarian BalakowiczOverview 83310c549SMarian Balakowicz-------- 93310c549SMarian Balakowicz 103310c549SMarian BalakowiczThe new uImage format allows more flexibility in handling images of various 113310c549SMarian Balakowicztypes (kernel, ramdisk, etc.), it also enhances integrity protection of images 123310c549SMarian Balakowiczwith sha1 and md5 checksums. 133310c549SMarian Balakowicz 143310c549SMarian BalakowiczTwo auxiliary tools are needed on the development host system in order to 153310c549SMarian Balakowiczcreate an uImage in the new format: mkimage and dtc, although only one 163310c549SMarian Balakowicz(mkimage) is invoked directly. dtc is called from within mkimage and operates 173310c549SMarian Balakowiczbehind the scenes, but needs to be present in the $PATH nevertheless. It is 183310c549SMarian Balakowiczimportant that the dtc used has support for binary includes -- refer to 195f65826bSJon Loeliger 205f65826bSJon Loeliger git://git.kernel.org/pub/scm/utils/dtc/dtc.git 215f65826bSJon Loeliger 225f65826bSJon Loeligerfor its latest version. mkimage (together with dtc) takes as input 233310c549SMarian Balakowiczan image source file, which describes the contents of the image and defines 243310c549SMarian Balakowiczits various properties used during booting. By convention, image source file 253310c549SMarian Balakowiczhas the ".its" extension, also, the details of its format are given in 2609b72d69SMasahiro Yamadadoc/uImage.FIT/source_file_format.txt. The actual data that is to be included in 2709b72d69SMasahiro Yamadathe uImage (kernel, ramdisk, etc.) is specified in the image source file in the 283310c549SMarian Balakowiczform of paths to appropriate data files. The outcome of the image creation 293310c549SMarian Balakowiczprocess is a binary file (by convention with the ".itb" extension) that 303310c549SMarian Balakowiczcontains all the referenced data (kernel, ramdisk, etc.) and other information 313310c549SMarian Balakowiczneeded by U-Boot to handle the uImage properly. The uImage file is then 323310c549SMarian Balakowicztransferred to the target (e.g., via tftp) and booted using the bootm command. 333310c549SMarian Balakowicz 343310c549SMarian BalakowiczTo summarize the prerequisites needed for new uImage creation: 353310c549SMarian Balakowicz- mkimage 363310c549SMarian Balakowicz- dtc (with support for binary includes) 373310c549SMarian Balakowicz- image source file (*.its) 383310c549SMarian Balakowicz- image data file(s) 393310c549SMarian Balakowicz 403310c549SMarian Balakowicz 413310c549SMarian BalakowiczHere's a graphical overview of the image creation and booting process: 423310c549SMarian Balakowicz 433310c549SMarian Balakowiczimage source file mkimage + dtc transfer to target 443310c549SMarian Balakowicz + ---------------> image file --------------------> bootm 4509b72d69SMasahiro Yamadaimage data file(s) 463310c549SMarian Balakowicz 47411cf32dSAndre PrzywaraSPL usage 48411cf32dSAndre Przywara--------- 49411cf32dSAndre Przywara 50411cf32dSAndre PrzywaraThe SPL can make use of the new image format as well, this traditionally 51411cf32dSAndre Przywarais used to ship multiple device tree files within one image. Code in the SPL 52411cf32dSAndre Przywarawill choose the one matching the current board and append this to the 53411cf32dSAndre PrzywaraU-Boot proper binary to be automatically used up by it. 54411cf32dSAndre PrzywaraAside from U-Boot proper and one device tree blob the SPL can load multiple, 55411cf32dSAndre Przywaraarbitrary image files as well. These binaries should be specified in their 56411cf32dSAndre Przywaraown subnode under the /images node, which should then be referenced from one or 57411cf32dSAndre Przywaramultiple /configurations subnodes. The required images must be enumerated in 58411cf32dSAndre Przywarathe "loadables" property as a list of strings. 59411cf32dSAndre Przywara 60411cf32dSAndre PrzywaraIf a platform specific image source file (.its) is shipped with the U-Boot 61411cf32dSAndre Przywarasource, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol. 62411cf32dSAndre PrzywaraIn this case it will be automatically used by U-Boot's Makefile to generate 63411cf32dSAndre Przywarathe image. 64411cf32dSAndre PrzywaraIf a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR 65411cf32dSAndre Przywaracan point to a script which generates this image source file during 66411cf32dSAndre Przywarathe build process. It gets passed a list of device tree files (taken from the 67411cf32dSAndre PrzywaraCONFIG_OF_LIST symbol). 683310c549SMarian Balakowicz 693310c549SMarian BalakowiczExample 1 -- old-style (non-FDT) kernel booting 703310c549SMarian Balakowicz----------------------------------------------- 713310c549SMarian Balakowicz 723310c549SMarian BalakowiczConsider a simple scenario, where a PPC Linux kernel built from sources on the 733310c549SMarian Balakowiczdevelopment host is to be booted old-style (non-FDT) by U-Boot on an embedded 743310c549SMarian Balakowicztarget. Assume that the outcome of the build is vmlinux.bin.gz, a file which 753310c549SMarian Balakowiczcontains a gzip-compressed PPC Linux kernel (the only data file in this case). 7643142e81SBartlomiej SiekaThe uImage can be produced using the image source file 7743142e81SBartlomiej Siekadoc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is 7843142e81SBartlomiej Siekain the current working directory; if desired, an alternative path can be 7943142e81SBartlomiej Siekaspecified in the kernel.its file). Here's how to create the image and inspect 8043142e81SBartlomiej Siekaits contents: 813310c549SMarian Balakowicz 823310c549SMarian Balakowicz[on the host system] 833310c549SMarian Balakowicz$ mkimage -f kernel.its kernel.itb 843310c549SMarian BalakowiczDTC: dts->dtb on file "kernel.its" 853310c549SMarian Balakowicz$ 863310c549SMarian Balakowicz$ mkimage -l kernel.itb 873310c549SMarian BalakowiczFIT description: Simple image with single Linux kernel 883310c549SMarian BalakowiczCreated: Tue Mar 11 17:26:15 2008 89*83840405SAndre Przywara Image 0 (kernel) 903310c549SMarian Balakowicz Description: Vanilla Linux kernel 913310c549SMarian Balakowicz Type: Kernel Image 923310c549SMarian Balakowicz Compression: gzip compressed 933310c549SMarian Balakowicz Data Size: 943347 Bytes = 921.24 kB = 0.90 MB 943310c549SMarian Balakowicz Architecture: PowerPC 953310c549SMarian Balakowicz OS: Linux 963310c549SMarian Balakowicz Load Address: 0x00000000 973310c549SMarian Balakowicz Entry Point: 0x00000000 983310c549SMarian Balakowicz Hash algo: crc32 993310c549SMarian Balakowicz Hash value: 2ae2bb40 1003310c549SMarian Balakowicz Hash algo: sha1 1013310c549SMarian Balakowicz Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 102*83840405SAndre Przywara Default Configuration: 'config-1' 103*83840405SAndre Przywara Configuration 0 (config-1) 1043310c549SMarian Balakowicz Description: Boot Linux kernel 105*83840405SAndre Przywara Kernel: kernel 1063310c549SMarian Balakowicz 1073310c549SMarian Balakowicz 1083310c549SMarian BalakowiczThe resulting image file kernel.itb can be now transferred to the target, 1093310c549SMarian Balakowiczinspected and booted (note that first three U-Boot commands below are shown 1103310c549SMarian Balakowiczfor completeness -- they are part of the standard booting procedure and not 1113310c549SMarian Balakowiczspecific to the new image format). 1123310c549SMarian Balakowicz 1133310c549SMarian Balakowicz[on the target system] 1143310c549SMarian Balakowicz=> print nfsargs 1153310c549SMarian Balakowicznfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} 1163310c549SMarian Balakowicz=> print addip 1173310c549SMarian Balakowiczaddip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1 1183310c549SMarian Balakowicz=> run nfsargs addip 1193310c549SMarian Balakowicz=> tftp 900000 /path/to/tftp/location/kernel.itb 12048690d80SHeiko SchocherUsing FEC device 1213310c549SMarian BalakowiczTFTP from server 192.168.1.1; our IP address is 192.168.160.5 1223310c549SMarian BalakowiczFilename '/path/to/tftp/location/kernel.itb'. 1233310c549SMarian BalakowiczLoad address: 0x900000 1243310c549SMarian BalakowiczLoading: ################################################################# 1253310c549SMarian Balakowiczdone 1263310c549SMarian BalakowiczBytes transferred = 944464 (e6950 hex) 1273310c549SMarian Balakowicz=> iminfo 1283310c549SMarian Balakowicz 1293310c549SMarian Balakowicz## Checking Image at 00900000 ... 1303310c549SMarian Balakowicz FIT image found 1313310c549SMarian Balakowicz FIT description: Simple image with single Linux kernel 1323310c549SMarian Balakowicz Created: 2008-03-11 16:26:15 UTC 133*83840405SAndre Przywara Image 0 (kernel) 1343310c549SMarian Balakowicz Description: Vanilla Linux kernel 1353310c549SMarian Balakowicz Type: Kernel Image 1363310c549SMarian Balakowicz Compression: gzip compressed 1373310c549SMarian Balakowicz Data Start: 0x009000e0 1383310c549SMarian Balakowicz Data Size: 943347 Bytes = 921.2 kB 1393310c549SMarian Balakowicz Architecture: PowerPC 1403310c549SMarian Balakowicz OS: Linux 1413310c549SMarian Balakowicz Load Address: 0x00000000 1423310c549SMarian Balakowicz Entry Point: 0x00000000 1433310c549SMarian Balakowicz Hash algo: crc32 1443310c549SMarian Balakowicz Hash value: 2ae2bb40 1453310c549SMarian Balakowicz Hash algo: sha1 1463310c549SMarian Balakowicz Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 147*83840405SAndre Przywara Default Configuration: 'config-1' 148*83840405SAndre Przywara Configuration 0 (config-1) 1493310c549SMarian Balakowicz Description: Boot Linux kernel 150*83840405SAndre Przywara Kernel: kernel 1513310c549SMarian Balakowicz 1523310c549SMarian Balakowicz=> bootm 1533310c549SMarian Balakowicz## Booting kernel from FIT Image at 00900000 ... 154*83840405SAndre Przywara Using 'config-1' configuration 155*83840405SAndre Przywara Trying 'kernel' kernel subimage 1563310c549SMarian Balakowicz Description: Vanilla Linux kernel 1573310c549SMarian Balakowicz Type: Kernel Image 1583310c549SMarian Balakowicz Compression: gzip compressed 1593310c549SMarian Balakowicz Data Start: 0x009000e0 1603310c549SMarian Balakowicz Data Size: 943347 Bytes = 921.2 kB 1613310c549SMarian Balakowicz Architecture: PowerPC 1623310c549SMarian Balakowicz OS: Linux 1633310c549SMarian Balakowicz Load Address: 0x00000000 1643310c549SMarian Balakowicz Entry Point: 0x00000000 1653310c549SMarian Balakowicz Hash algo: crc32 1663310c549SMarian Balakowicz Hash value: 2ae2bb40 1673310c549SMarian Balakowicz Hash algo: sha1 1683310c549SMarian Balakowicz Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 1693310c549SMarian Balakowicz Verifying Hash Integrity ... crc32+ sha1+ OK 1703310c549SMarian Balakowicz Uncompressing Kernel Image ... OK 1713310c549SMarian BalakowiczMemory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb 1723310c549SMarian BalakowiczLinux 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 1733310c549SMarian BalakowiczOn node 0 totalpages: 65536 1743310c549SMarian Balakowiczzone(0): 65536 pages. 1753310c549SMarian Balakowiczzone(1): 0 pages. 1763310c549SMarian Balakowiczzone(2): 0 pages. 1773310c549SMarian BalakowiczKernel 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 1783310c549SMarian BalakowiczCalibrating delay loop... 307.20 BogoMIPS 1793310c549SMarian Balakowicz 1803310c549SMarian Balakowicz 1813310c549SMarian BalakowiczExample 2 -- new-style (FDT) kernel booting 1823310c549SMarian Balakowicz------------------------------------------- 1833310c549SMarian Balakowicz 1843310c549SMarian BalakowiczConsider another simple scenario, where a PPC Linux kernel is to be booted 1853310c549SMarian Balakowicznew-style, i.e., with a FDT blob. In this case there are two prerequisite data 1863310c549SMarian Balakowiczfiles: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can 18743142e81SBartlomiej Siekabe produced using image source file doc/uImage.FIT/kernel_fdt.its like this 18843142e81SBartlomiej Sieka(note again, that both prerequisite data files are assumed to be present in 18943142e81SBartlomiej Siekathe current working directory -- image source file kernel_fdt.its can be 19043142e81SBartlomiej Siekamodified to take the files from some other location if needed): 1913310c549SMarian Balakowicz 1923310c549SMarian Balakowicz[on the host system] 1933310c549SMarian Balakowicz$ mkimage -f kernel_fdt.its kernel_fdt.itb 1943310c549SMarian BalakowiczDTC: dts->dtb on file "kernel_fdt.its" 1953310c549SMarian Balakowicz$ 1963310c549SMarian Balakowicz$ mkimage -l kernel_fdt.itb 1973310c549SMarian BalakowiczFIT description: Simple image with single Linux kernel and FDT blob 1983310c549SMarian BalakowiczCreated: Tue Mar 11 16:29:22 2008 199*83840405SAndre Przywara Image 0 (kernel) 2003310c549SMarian Balakowicz Description: Vanilla Linux kernel 2013310c549SMarian Balakowicz Type: Kernel Image 2023310c549SMarian Balakowicz Compression: gzip compressed 2033310c549SMarian Balakowicz Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB 2043310c549SMarian Balakowicz Architecture: PowerPC 2053310c549SMarian Balakowicz OS: Linux 2063310c549SMarian Balakowicz Load Address: 0x00000000 2073310c549SMarian Balakowicz Entry Point: 0x00000000 2083310c549SMarian Balakowicz Hash algo: crc32 2093310c549SMarian Balakowicz Hash value: 2c0cc807 2103310c549SMarian Balakowicz Hash algo: sha1 2113310c549SMarian Balakowicz Hash value: 264b59935470e42c418744f83935d44cdf59a3bb 212*83840405SAndre Przywara Image 1 (fdt-1) 2133310c549SMarian Balakowicz Description: Flattened Device Tree blob 2143310c549SMarian Balakowicz Type: Flat Device Tree 2153310c549SMarian Balakowicz Compression: uncompressed 2163310c549SMarian Balakowicz Data Size: 16384 Bytes = 16.00 kB = 0.02 MB 2173310c549SMarian Balakowicz Architecture: PowerPC 2183310c549SMarian Balakowicz Hash algo: crc32 2193310c549SMarian Balakowicz Hash value: 0d655d71 2203310c549SMarian Balakowicz Hash algo: sha1 2213310c549SMarian Balakowicz Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def 222*83840405SAndre Przywara Default Configuration: 'conf-1' 223*83840405SAndre Przywara Configuration 0 (conf-1) 2243310c549SMarian Balakowicz Description: Boot Linux kernel with FDT blob 225*83840405SAndre Przywara Kernel: kernel 226*83840405SAndre Przywara FDT: fdt-1 2273310c549SMarian Balakowicz 2283310c549SMarian Balakowicz 2293310c549SMarian BalakowiczThe resulting image file kernel_fdt.itb can be now transferred to the target, 2303310c549SMarian Balakowiczinspected and booted: 2313310c549SMarian Balakowicz 2323310c549SMarian Balakowicz[on the target system] 2333310c549SMarian Balakowicz=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb 23448690d80SHeiko SchocherUsing FEC device 2353310c549SMarian BalakowiczTFTP from server 192.168.1.1; our IP address is 192.168.160.5 2363310c549SMarian BalakowiczFilename '/path/to/tftp/location/kernel_fdt.itb'. 2373310c549SMarian BalakowiczLoad address: 0x900000 2383310c549SMarian BalakowiczLoading: ################################################################# 2393310c549SMarian Balakowicz ########### 2403310c549SMarian Balakowiczdone 2413310c549SMarian BalakowiczBytes transferred = 1109776 (10ef10 hex) 2423310c549SMarian Balakowicz=> iminfo 2433310c549SMarian Balakowicz 2443310c549SMarian Balakowicz## Checking Image at 00900000 ... 2453310c549SMarian Balakowicz FIT image found 2463310c549SMarian Balakowicz FIT description: Simple image with single Linux kernel and FDT blob 2473310c549SMarian Balakowicz Created: 2008-03-11 15:29:22 UTC 248*83840405SAndre Przywara Image 0 (kernel) 2493310c549SMarian Balakowicz Description: Vanilla Linux kernel 2503310c549SMarian Balakowicz Type: Kernel Image 2513310c549SMarian Balakowicz Compression: gzip compressed 2523310c549SMarian Balakowicz Data Start: 0x009000ec 2533310c549SMarian Balakowicz Data Size: 1092037 Bytes = 1 MB 2543310c549SMarian Balakowicz Architecture: PowerPC 2553310c549SMarian Balakowicz OS: Linux 2563310c549SMarian Balakowicz Load Address: 0x00000000 2573310c549SMarian Balakowicz Entry Point: 0x00000000 2583310c549SMarian Balakowicz Hash algo: crc32 2593310c549SMarian Balakowicz Hash value: 2c0cc807 2603310c549SMarian Balakowicz Hash algo: sha1 2613310c549SMarian Balakowicz Hash value: 264b59935470e42c418744f83935d44cdf59a3bb 262*83840405SAndre Przywara Image 1 (fdt-1) 2633310c549SMarian Balakowicz Description: Flattened Device Tree blob 2643310c549SMarian Balakowicz Type: Flat Device Tree 2653310c549SMarian Balakowicz Compression: uncompressed 2663310c549SMarian Balakowicz Data Start: 0x00a0abdc 2673310c549SMarian Balakowicz Data Size: 16384 Bytes = 16 kB 2683310c549SMarian Balakowicz Architecture: PowerPC 2693310c549SMarian Balakowicz Hash algo: crc32 2703310c549SMarian Balakowicz Hash value: 0d655d71 2713310c549SMarian Balakowicz Hash algo: sha1 2723310c549SMarian Balakowicz Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def 273*83840405SAndre Przywara Default Configuration: 'conf-1' 274*83840405SAndre Przywara Configuration 0 (conf-1) 2753310c549SMarian Balakowicz Description: Boot Linux kernel with FDT blob 276*83840405SAndre Przywara Kernel: kernel 277*83840405SAndre Przywara FDT: fdt-1 2783310c549SMarian Balakowicz=> bootm 2793310c549SMarian Balakowicz## Booting kernel from FIT Image at 00900000 ... 280*83840405SAndre Przywara Using 'conf-1' configuration 281*83840405SAndre Przywara Trying 'kernel' kernel subimage 2823310c549SMarian Balakowicz Description: Vanilla Linux kernel 2833310c549SMarian Balakowicz Type: Kernel Image 2843310c549SMarian Balakowicz Compression: gzip compressed 2853310c549SMarian Balakowicz Data Start: 0x009000ec 2863310c549SMarian Balakowicz Data Size: 1092037 Bytes = 1 MB 2873310c549SMarian Balakowicz Architecture: PowerPC 2883310c549SMarian Balakowicz OS: Linux 2893310c549SMarian Balakowicz Load Address: 0x00000000 2903310c549SMarian Balakowicz Entry Point: 0x00000000 2913310c549SMarian Balakowicz Hash algo: crc32 2923310c549SMarian Balakowicz Hash value: 2c0cc807 2933310c549SMarian Balakowicz Hash algo: sha1 2943310c549SMarian Balakowicz Hash value: 264b59935470e42c418744f83935d44cdf59a3bb 2953310c549SMarian Balakowicz Verifying Hash Integrity ... crc32+ sha1+ OK 2963310c549SMarian Balakowicz Uncompressing Kernel Image ... OK 2973310c549SMarian Balakowicz## Flattened Device Tree from FIT Image at 00900000 298*83840405SAndre Przywara Using 'conf-1' configuration 299*83840405SAndre Przywara Trying 'fdt-1' FDT blob subimage 3003310c549SMarian Balakowicz Description: Flattened Device Tree blob 3013310c549SMarian Balakowicz Type: Flat Device Tree 3023310c549SMarian Balakowicz Compression: uncompressed 3033310c549SMarian Balakowicz Data Start: 0x00a0abdc 3043310c549SMarian Balakowicz Data Size: 16384 Bytes = 16 kB 3053310c549SMarian Balakowicz Architecture: PowerPC 3063310c549SMarian Balakowicz Hash algo: crc32 3073310c549SMarian Balakowicz Hash value: 0d655d71 3083310c549SMarian Balakowicz Hash algo: sha1 3093310c549SMarian Balakowicz Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def 3103310c549SMarian Balakowicz Verifying Hash Integrity ... crc32+ sha1+ OK 3113310c549SMarian Balakowicz Booting using the fdt blob at 0xa0abdc 3123310c549SMarian Balakowicz Loading Device Tree to 007fc000, end 007fffff ... OK 3133310c549SMarian Balakowicz[ 0.000000] Using lite5200 machine description 3143310c549SMarian Balakowicz[ 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 3153310c549SMarian Balakowicz 3163310c549SMarian Balakowicz 3173310c549SMarian BalakowiczExample 3 -- advanced booting 3183310c549SMarian Balakowicz----------------------------- 3193310c549SMarian Balakowicz 32043142e81SBartlomiej SiekaRefer to doc/uImage.FIT/multi.its for an image source file that allows more 3213310c549SMarian Balakowiczsophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). 322