doc/uImage.FIT/howto.txt

   1 How to use images in the new image format
   2 =========================================
   3
   4 Author: Bartlomiej Sieka <tur@semihalf.com>
   5
   6
   7 Overview
   8 --------
   9
  10 The new uImage format allows more flexibility in handling images of various
  11 types (kernel, ramdisk, etc.), it also enhances integrity protection of images
  12 with sha1 and md5 checksums.
  13
  14 Two auxiliary tools are needed on the development host system in order to
  15 create 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
  17 behind the scenes, but needs to be present in the $PATH nevertheless. It is
  18 important that the dtc used has support for binary includes -- refer to
  19
  20         git://git.kernel.org/pub/scm/utils/dtc/dtc.git
  21
  22 for its latest version. mkimage (together with dtc) takes as input
  23 an image source file, which describes the contents of the image and defines
  24 its various properties used during booting. By convention, image source file
  25 has the ".its" extension, also, the details of its format are given in
  26 doc/uImage.FIT/source_file_format.txt. The actual data that is to be included in
  27 the uImage (kernel, ramdisk, etc.) is specified in the image source file in the
  28 form of paths to appropriate data files. The outcome of the image creation
  29 process is a binary file (by convention with the ".itb" extension) that
  30 contains all the referenced data (kernel, ramdisk, etc.) and other information
  31 needed by U-Boot to handle the uImage properly. The uImage file is then
  32 transferred to the target (e.g., via tftp) and booted using the bootm command.
  33
  34 To 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
  41 Here's a graphical overview of the image creation and booting process:
  42
  43 image source file     mkimage + dtc               transfer to target
  44         +            ---------------> image file --------------------> bootm
  45 image data file(s)
  46
  47 SPL usage
  48 ---------
  49
  50 The SPL can make use of the new image format as well, this traditionally
  51 is used to ship multiple device tree files within one image. Code in the SPL
  52 will choose the one matching the current board and append this to the
  53 U-Boot proper binary to be automatically used up by it.
  54 Aside from U-Boot proper and one device tree blob the SPL can load multiple,
  55 arbitrary image files as well. These binaries should be specified in their
  56 own subnode under the /images node, which should then be referenced from one or
  57 multiple /configurations subnodes. The required images must be enumerated in
  58 the "loadables" property as a list of strings.
  59
  60 If a platform specific image source file (.its) is shipped with the U-Boot
  61 source, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol.
  62 In this case it will be automatically used by U-Boot's Makefile to generate
  63 the image.
  64 If a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR
  65 can point to a script which generates this image source file during
  66 the build process. It gets passed a list of device tree files (taken from the
  67 CONFIG_OF_LIST symbol).
  68
  69 The SPL also records to a DT all additional images (called loadables) which are
  70 loaded. The information about loadables locations is passed via the DT node with
  71 fit-images name.
  72
  73 Finally, if there are multiple xPL phases (e.g. SPL, VPL), images can be marked
  74 as intended for a particular phase using the 'phase' property. For example, if
  75 fit_image_load() is called with image_ph(IH_PHASE_SPL, IH_TYPE_FIRMWARE), then
  76 only the image listed into the "firmware" property where phase is set to "spl"
  77 will be loaded.
  78
  79 Loadables Example
  80 -----------------
  81 Consider the following case for an ARM64 platform where U-Boot runs in EL2
  82 started by ATF where SPL is loading U-Boot (as loadables) and ATF (as firmware).
  83
  84 /dts-v1/;
  85
  86 / {
  87         description = "Configuration to load ATF before U-Boot";
  88
  89         images {
  90                 uboot {
  91                         description = "U-Boot (64-bit)";
  92                         data = /incbin/("u-boot-nodtb.bin");
  93                         type = "firmware";
  94                         os = "u-boot";
  95                         arch = "arm64";
  96                         compression = "none";
  97                         load = <0x8 0x8000000>;
  98                         entry = <0x8 0x8000000>;
  99                         hash {
 100                                 algo = "md5";
 101                         };
 102                 };
 103                 atf {
 104                         description = "ARM Trusted Firmware";
 105                         data = /incbin/("bl31.bin");
 106                         type = "firmware";
 107                         os = "arm-trusted-firmware";
 108                         arch = "arm64";
 109                         compression = "none";
 110                         load = <0xfffea000>;
 111                         entry = <0xfffea000>;
 112                         hash {
 113                                 algo = "md5";
 114                         };
 115                 };
 116                 fdt_1 {
 117                         description = "zynqmp-zcu102-revA";
 118                         data = /incbin/("arch/arm/dts/zynqmp-zcu102-revA.dtb");
 119                         type = "flat_dt";
 120                         arch = "arm64";
 121                         compression = "none";
 122                         load = <0x100000>;
 123                         hash {
 124                                 algo = "md5";
 125                         };
 126                 };
 127         };
 128         configurations {
 129                 default = "config_1";
 130
 131                 config_1 {
 132                         description = "zynqmp-zcu102-revA";
 133                         firmware = "atf";
 134                         loadables = "uboot";
 135                         fdt = "fdt_1";
 136                 };
 137         };
 138 };
 139
 140 In this case the SPL records via fit-images DT node the information about
 141 loadables U-Boot image.
 142
 143 ZynqMP> fdt addr $fdtcontroladdr
 144 ZynqMP> fdt print /fit-images
 145 fit-images {
 146         uboot {
 147                 os = "u-boot";
 148                 type = "firmware";
 149                 size = <0x001017c8>;
 150                 entry = <0x00000008 0x08000000>;
 151                 load = <0x00000008 0x08000000>;
 152         };
 153 };
 154
 155 As you can see entry and load properties are 64bit wide to support loading
 156 images above 4GB (in past entry and load properties where just 32bit).
 157
 158
 159 Example 1 -- old-style (non-FDT) kernel booting
 160 -----------------------------------------------
 161
 162 Consider a simple scenario, where a PPC Linux kernel built from sources on the
 163 development host is to be booted old-style (non-FDT) by U-Boot on an embedded
 164 target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
 165 contains a gzip-compressed PPC Linux kernel (the only data file in this case).
 166 The uImage can be produced using the image source file
 167 doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
 168 in the current working directory; if desired, an alternative path can be
 169 specified in the kernel.its file). Here's how to create the image and inspect
 170 its contents:
 171
 172 [on the host system]
 173 $ mkimage -f kernel.its kernel.itb
 174 DTC: dts->dtb  on file "kernel.its"
 175 $
 176 $ mkimage -l kernel.itb
 177 FIT description: Simple image with single Linux kernel
 178 Created:         Tue Mar 11 17:26:15 2008
 179  Image 0 (kernel)
 180   Description:  Vanilla Linux kernel
 181   Type:         Kernel Image
 182   Compression:  gzip compressed
 183   Data Size:    943347 Bytes = 921.24 kB = 0.90 MB
 184   Architecture: PowerPC
 185   OS:           Linux
 186   Load Address: 0x00000000
 187   Entry Point:  0x00000000
 188   Hash algo:    crc32
 189   Hash value:   2ae2bb40
 190   Hash algo:    sha1
 191   Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
 192  Default Configuration: 'config-1'
 193  Configuration 0 (config-1)
 194   Description:  Boot Linux kernel
 195   Kernel:       kernel
 196
 197
 198 The resulting image file kernel.itb can be now transferred to the target,
 199 inspected and booted (note that first three U-Boot commands below are shown
 200 for completeness -- they are part of the standard booting procedure and not
 201 specific to the new image format).
 202
 203 [on the target system]
 204 => print nfsargs
 205 nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
 206 => print addip
 207 addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
 208 => run nfsargs addip
 209 => tftp 900000 /path/to/tftp/location/kernel.itb
 210 Using FEC device
 211 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 212 Filename '/path/to/tftp/location/kernel.itb'.
 213 Load address: 0x900000
 214 Loading: #################################################################
 215 done
 216 Bytes transferred = 944464 (e6950 hex)
 217 => iminfo
 218
 219 ## Checking Image at 00900000 ...
 220    FIT image found
 221    FIT description: Simple image with single Linux kernel
 222    Created:         2008-03-11  16:26:15 UTC
 223     Image 0 (kernel)
 224      Description:  Vanilla Linux kernel
 225      Type:         Kernel Image
 226      Compression:  gzip compressed
 227      Data Start:   0x009000e0
 228      Data Size:    943347 Bytes = 921.2 kB
 229      Architecture: PowerPC
 230      OS:           Linux
 231      Load Address: 0x00000000
 232      Entry Point:  0x00000000
 233      Hash algo:    crc32
 234      Hash value:   2ae2bb40
 235      Hash algo:    sha1
 236      Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
 237     Default Configuration: 'config-1'
 238     Configuration 0 (config-1)
 239      Description:  Boot Linux kernel
 240      Kernel:       kernel
 241
 242 => bootm
 243 ## Booting kernel from FIT Image at 00900000 ...
 244    Using 'config-1' configuration
 245    Trying 'kernel' kernel subimage
 246      Description:  Vanilla Linux kernel
 247      Type:         Kernel Image
 248      Compression:  gzip compressed
 249      Data Start:   0x009000e0
 250      Data Size:    943347 Bytes = 921.2 kB
 251      Architecture: PowerPC
 252      OS:           Linux
 253      Load Address: 0x00000000
 254      Entry Point:  0x00000000
 255      Hash algo:    crc32
 256      Hash value:   2ae2bb40
 257      Hash algo:    sha1
 258      Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
 259    Verifying Hash Integrity ... crc32+ sha1+ OK
 260    Uncompressing Kernel Image ... OK
 261 Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
 262 Linux 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
 263 On node 0 totalpages: 65536
 264 zone(0): 65536 pages.
 265 zone(1): 0 pages.
 266 zone(2): 0 pages.
 267 Kernel 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
 268 Calibrating delay loop... 307.20 BogoMIPS
 269
 270
 271 Example 2 -- new-style (FDT) kernel booting
 272 -------------------------------------------
 273
 274 Consider another simple scenario, where a PPC Linux kernel is to be booted
 275 new-style, i.e., with a FDT blob. In this case there are two prerequisite data
 276 files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
 277 be produced using image source file doc/uImage.FIT/kernel_fdt.its like this
 278 (note again, that both prerequisite data files are assumed to be present in
 279 the current working directory -- image source file kernel_fdt.its can be
 280 modified to take the files from some other location if needed):
 281
 282 [on the host system]
 283 $ mkimage -f kernel_fdt.its kernel_fdt.itb
 284 DTC: dts->dtb  on file "kernel_fdt.its"
 285 $
 286 $ mkimage -l kernel_fdt.itb
 287 FIT description: Simple image with single Linux kernel and FDT blob
 288 Created:         Tue Mar 11 16:29:22 2008
 289  Image 0 (kernel)
 290   Description:  Vanilla Linux kernel
 291   Type:         Kernel Image
 292   Compression:  gzip compressed
 293   Data Size:    1092037 Bytes = 1066.44 kB = 1.04 MB
 294   Architecture: PowerPC
 295   OS:           Linux
 296   Load Address: 0x00000000
 297   Entry Point:  0x00000000
 298   Hash algo:    crc32
 299   Hash value:   2c0cc807
 300   Hash algo:    sha1
 301   Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 302  Image 1 (fdt-1)
 303   Description:  Flattened Device Tree blob
 304   Type:         Flat Device Tree
 305   Compression:  uncompressed
 306   Data Size:    16384 Bytes = 16.00 kB = 0.02 MB
 307   Architecture: PowerPC
 308   Hash algo:    crc32
 309   Hash value:   0d655d71
 310   Hash algo:    sha1
 311   Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 312  Default Configuration: 'conf-1'
 313  Configuration 0 (conf-1)
 314   Description:  Boot Linux kernel with FDT blob
 315   Kernel:       kernel
 316   FDT:          fdt-1
 317
 318
 319 The resulting image file kernel_fdt.itb can be now transferred to the target,
 320 inspected and booted:
 321
 322 [on the target system]
 323 => tftp 900000 /path/to/tftp/location/kernel_fdt.itb
 324 Using FEC device
 325 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 326 Filename '/path/to/tftp/location/kernel_fdt.itb'.
 327 Load address: 0x900000
 328 Loading: #################################################################
 329          ###########
 330 done
 331 Bytes transferred = 1109776 (10ef10 hex)
 332 => iminfo
 333
 334 ## Checking Image at 00900000 ...
 335    FIT image found
 336    FIT description: Simple image with single Linux kernel and FDT blob
 337    Created:         2008-03-11  15:29:22 UTC
 338     Image 0 (kernel)
 339      Description:  Vanilla Linux kernel
 340      Type:         Kernel Image
 341      Compression:  gzip compressed
 342      Data Start:   0x009000ec
 343      Data Size:    1092037 Bytes =  1 MB
 344      Architecture: PowerPC
 345      OS:           Linux
 346      Load Address: 0x00000000
 347      Entry Point:  0x00000000
 348      Hash algo:    crc32
 349      Hash value:   2c0cc807
 350      Hash algo:    sha1
 351      Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 352     Image 1 (fdt-1)
 353      Description:  Flattened Device Tree blob
 354      Type:         Flat Device Tree
 355      Compression:  uncompressed
 356      Data Start:   0x00a0abdc
 357      Data Size:    16384 Bytes = 16 kB
 358      Architecture: PowerPC
 359      Hash algo:    crc32
 360      Hash value:   0d655d71
 361      Hash algo:    sha1
 362      Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 363     Default Configuration: 'conf-1'
 364     Configuration 0 (conf-1)
 365      Description:  Boot Linux kernel with FDT blob
 366      Kernel:       kernel
 367      FDT:          fdt-1
 368 => bootm
 369 ## Booting kernel from FIT Image at 00900000 ...
 370    Using 'conf-1' configuration
 371    Trying 'kernel' kernel subimage
 372      Description:  Vanilla Linux kernel
 373      Type:         Kernel Image
 374      Compression:  gzip compressed
 375      Data Start:   0x009000ec
 376      Data Size:    1092037 Bytes =  1 MB
 377      Architecture: PowerPC
 378      OS:           Linux
 379      Load Address: 0x00000000
 380      Entry Point:  0x00000000
 381      Hash algo:    crc32
 382      Hash value:   2c0cc807
 383      Hash algo:    sha1
 384      Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 385    Verifying Hash Integrity ... crc32+ sha1+ OK
 386    Uncompressing Kernel Image ... OK
 387 ## Flattened Device Tree from FIT Image at 00900000
 388    Using 'conf-1' configuration
 389    Trying 'fdt-1' FDT blob subimage
 390      Description:  Flattened Device Tree blob
 391      Type:         Flat Device Tree
 392      Compression:  uncompressed
 393      Data Start:   0x00a0abdc
 394      Data Size:    16384 Bytes = 16 kB
 395      Architecture: PowerPC
 396      Hash algo:    crc32
 397      Hash value:   0d655d71
 398      Hash algo:    sha1
 399      Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 400    Verifying Hash Integrity ... crc32+ sha1+ OK
 401    Booting using the fdt blob at 0xa0abdc
 402    Loading Device Tree to 007fc000, end 007fffff ... OK
 403 [    0.000000] Using lite5200 machine description
 404 [    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
 405
 406
 407 Example 3 -- advanced booting
 408 -----------------------------
 409
 410 Refer to doc/uImage.FIT/multi.its for an image source file that allows more
 411 sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).