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 Example 1 -- old-style (non-FDT) kernel booting
  70 -----------------------------------------------
  71
  72 Consider a simple scenario, where a PPC Linux kernel built from sources on the
  73 development host is to be booted old-style (non-FDT) by U-Boot on an embedded
  74 target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
  75 contains a gzip-compressed PPC Linux kernel (the only data file in this case).
  76 The uImage can be produced using the image source file
  77 doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
  78 in the current working directory; if desired, an alternative path can be
  79 specified in the kernel.its file). Here's how to create the image and inspect
  80 its contents:
  81
  82 [on the host system]
  83 $ mkimage -f kernel.its kernel.itb
  84 DTC: dts->dtb  on file "kernel.its"
  85 $
  86 $ mkimage -l kernel.itb
  87 FIT description: Simple image with single Linux kernel
  88 Created:         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
 108 The resulting image file kernel.itb can be now transferred to the target,
 109 inspected and booted (note that first three U-Boot commands below are shown
 110 for completeness -- they are part of the standard booting procedure and not
 111 specific to the new image format).
 112
 113 [on the target system]
 114 => print nfsargs
 115 nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
 116 => print addip
 117 addip=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
 120 Using FEC device
 121 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 122 Filename '/path/to/tftp/location/kernel.itb'.
 123 Load address: 0x900000
 124 Loading: #################################################################
 125 done
 126 Bytes 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
 171 Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
 172 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
 173 On node 0 totalpages: 65536
 174 zone(0): 65536 pages.
 175 zone(1): 0 pages.
 176 zone(2): 0 pages.
 177 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
 178 Calibrating delay loop... 307.20 BogoMIPS
 179
 180
 181 Example 2 -- new-style (FDT) kernel booting
 182 -------------------------------------------
 183
 184 Consider another simple scenario, where a PPC Linux kernel is to be booted
 185 new-style, i.e., with a FDT blob. In this case there are two prerequisite data
 186 files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
 187 be 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
 189 the current working directory -- image source file kernel_fdt.its can be
 190 modified 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
 194 DTC: dts->dtb  on file "kernel_fdt.its"
 195 $
 196 $ mkimage -l kernel_fdt.itb
 197 FIT description: Simple image with single Linux kernel and FDT blob
 198 Created:         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
 229 The resulting image file kernel_fdt.itb can be now transferred to the target,
 230 inspected and booted:
 231
 232 [on the target system]
 233 => tftp 900000 /path/to/tftp/location/kernel_fdt.itb
 234 Using FEC device
 235 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 236 Filename '/path/to/tftp/location/kernel_fdt.itb'.
 237 Load address: 0x900000
 238 Loading: #################################################################
 239          ###########
 240 done
 241 Bytes 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
 317 Example 3 -- advanced booting
 318 -----------------------------
 319
 320 Refer to doc/uImage.FIT/multi.its for an image source file that allows more
 321 sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).