1How to use images in the new image format
   4Author: Bartlomiej Sieka <tur@semihalf.com>
  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.
  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
  20        git://git.kernel.org/pub/scm/utils/dtc/dtc.git
  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.
  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)
  41Here's a graphical overview of the image creation and booting process:
  43image source file     mkimage + dtc               transfer to target
  44        +            ---------------> image file --------------------> bootm
  45image data file(s)
  47SPL usage
  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.
  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).
  69Example 1 -- old-style (non-FDT) kernel booting
  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:
  82[on the host system]
  83$ mkimage -f kernel.its kernel.itb
  84DTC: dts->dtb  on file "kernel.its"
  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@1)
  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@1
 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).
 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; our IP address is
 122Filename '/path/to/tftp/location/kernel.itb'.
 123Load address: 0x900000
 124Loading: #################################################################
 126Bytes transferred = 944464 (e6950 hex)
 127=> iminfo
 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@1)
 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@1
 152=> bootm
 153## Booting kernel from FIT Image at 00900000 ...
 154   Using 'config@1' configuration
 155   Trying 'kernel@1' 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= ip= panic=1
 178Calibrating delay loop... 307.20 BogoMIPS
 181Example 2 -- new-style (FDT) kernel booting
 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):
 192[on the host system]
 193$ mkimage -f kernel_fdt.its kernel_fdt.itb
 194DTC: dts->dtb  on file "kernel_fdt.its"
 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@1)
 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@1
 226  FDT:          fdt@1
 229The resulting image file kernel_fdt.itb can be now transferred to the target,
 230inspected and booted:
 232[on the target system]
 233=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
 234Using FEC device
 235TFTP from server; our IP address is
 236Filename '/path/to/tftp/location/kernel_fdt.itb'.
 237Load address: 0x900000
 238Loading: #################################################################
 239         ###########
 241Bytes transferred = 1109776 (10ef10 hex)
 242=> iminfo
 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@1)
 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@1
 277     FDT:          fdt@1
 278=> bootm
 279## Booting kernel from FIT Image at 00900000 ...
 280   Using 'conf@1' configuration
 281   Trying 'kernel@1' 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
 317Example 3 -- advanced booting
 320Refer to doc/uImage.FIT/multi.its for an image source file that allows more
 321sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).