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 www.jdl.com for its latest version. mkimage (together with dtc) takes as input
  20 an image source file, which describes the contents of the image and defines
  21 its various properties used during booting. By convention, image source file
  22 has the ".its" extension, also, the details of its format are given in
  23 doc/source_file_format.txt. The actual data that is to be included in the
  24 uImage (kernel, ramdisk, etc.) is specified in the image source file in the
  25 form of paths to appropriate data files. The outcome of the image creation
  26 process is a binary file (by convention with the ".itb" extension) that
  27 contains all the referenced data (kernel, ramdisk, etc.) and other information
  28 needed by U-Boot to handle the uImage properly. The uImage file is then
  29 transferred to the target (e.g., via tftp) and booted using the bootm command.
  30
  31 To summarize the prerequisites needed for new uImage creation:
  32 - mkimage
  33 - dtc (with support for binary includes)
  34 - image source file (*.its)
  35 - image data file(s)
  36
  37
  38 Here's a graphical overview of the image creation and booting process:
  39
  40 image source file     mkimage + dtc               transfer to target
  41         +            ---------------> image file --------------------> bootm
  42 image data files(s)
  43
  44
  45 Example 1 -- old-style (non-FDT) kernel booting
  46 -----------------------------------------------
  47
  48 Consider a simple scenario, where a PPC Linux kernel built from sources on the
  49 development host is to be booted old-style (non-FDT) by U-Boot on an embedded
  50 target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
  51 contains a gzip-compressed PPC Linux kernel (the only data file in this case).
  52 The uImage can be produced using the image source file
  53 doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
  54 in the current working directory; if desired, an alternative path can be
  55 specified in the kernel.its file). Here's how to create the image and inspect
  56 its contents:
  57
  58 [on the host system]
  59 $ mkimage -f kernel.its kernel.itb
  60 DTC: dts->dtb  on file "kernel.its"
  61 $
  62 $ mkimage -l kernel.itb
  63 FIT description: Simple image with single Linux kernel
  64 Created:         Tue Mar 11 17:26:15 2008
  65  Image 0 (kernel@1)
  66   Description:  Vanilla Linux kernel
  67   Type:         Kernel Image
  68   Compression:  gzip compressed
  69   Data Size:    943347 Bytes = 921.24 kB = 0.90 MB
  70   Architecture: PowerPC
  71   OS:           Linux
  72   Load Address: 0x00000000
  73   Entry Point:  0x00000000
  74   Hash algo:    crc32
  75   Hash value:   2ae2bb40
  76   Hash algo:    sha1
  77   Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
  78  Default Configuration: 'config@1'
  79  Configuration 0 (config@1)
  80   Description:  Boot Linux kernel
  81   Kernel:       kernel@1
  82
  83
  84 The resulting image file kernel.itb can be now transferred to the target,
  85 inspected and booted (note that first three U-Boot commands below are shown
  86 for completeness -- they are part of the standard booting procedure and not
  87 specific to the new image format).
  88
  89 [on the target system]
  90 => print nfsargs
  91 nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
  92 => print addip
  93 addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
  94 => run nfsargs addip
  95 => tftp 900000 /path/to/tftp/location/kernel.itb
  96 Using FEC ETHERNET device
  97 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
  98 Filename '/path/to/tftp/location/kernel.itb'.
  99 Load address: 0x900000
 100 Loading: #################################################################
 101 done
 102 Bytes transferred = 944464 (e6950 hex)
 103 => iminfo
 104
 105 ## Checking Image at 00900000 ...
 106    FIT image found
 107    FIT description: Simple image with single Linux kernel
 108    Created:         2008-03-11  16:26:15 UTC
 109     Image 0 (kernel@1)
 110      Description:  Vanilla Linux kernel
 111      Type:         Kernel Image
 112      Compression:  gzip compressed
 113      Data Start:   0x009000e0
 114      Data Size:    943347 Bytes = 921.2 kB
 115      Architecture: PowerPC
 116      OS:           Linux
 117      Load Address: 0x00000000
 118      Entry Point:  0x00000000
 119      Hash algo:    crc32
 120      Hash value:   2ae2bb40
 121      Hash algo:    sha1
 122      Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
 123     Default Configuration: 'config@1'
 124     Configuration 0 (config@1)
 125      Description:  Boot Linux kernel
 126      Kernel:       kernel@1
 127
 128 => bootm
 129 ## Booting kernel from FIT Image at 00900000 ...
 130    Using 'config@1' configuration
 131    Trying 'kernel@1' kernel subimage
 132      Description:  Vanilla Linux kernel
 133      Type:         Kernel Image
 134      Compression:  gzip compressed
 135      Data Start:   0x009000e0
 136      Data Size:    943347 Bytes = 921.2 kB
 137      Architecture: PowerPC
 138      OS:           Linux
 139      Load Address: 0x00000000
 140      Entry Point:  0x00000000
 141      Hash algo:    crc32
 142      Hash value:   2ae2bb40
 143      Hash algo:    sha1
 144      Hash value:   3c200f34e2c226ddc789240cca0c59fc54a67cf4
 145    Verifying Hash Integrity ... crc32+ sha1+ OK
 146    Uncompressing Kernel Image ... OK
 147 Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
 148 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
 149 On node 0 totalpages: 65536
 150 zone(0): 65536 pages.
 151 zone(1): 0 pages.
 152 zone(2): 0 pages.
 153 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
 154 Calibrating delay loop... 307.20 BogoMIPS
 155
 156
 157 Example 2 -- new-style (FDT) kernel booting
 158 -------------------------------------------
 159
 160 Consider another simple scenario, where a PPC Linux kernel is to be booted
 161 new-style, i.e., with a FDT blob. In this case there are two prerequisite data
 162 files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
 163 be produced using image source file doc/uImage.FIT/kernel_fdt.its like this
 164 (note again, that both prerequisite data files are assumed to be present in
 165 the current working directory -- image source file kernel_fdt.its can be
 166 modified to take the files from some other location if needed):
 167
 168 [on the host system]
 169 $ mkimage -f kernel_fdt.its kernel_fdt.itb
 170 DTC: dts->dtb  on file "kernel_fdt.its"
 171 $
 172 $ mkimage -l kernel_fdt.itb
 173 FIT description: Simple image with single Linux kernel and FDT blob
 174 Created:         Tue Mar 11 16:29:22 2008
 175  Image 0 (kernel@1)
 176   Description:  Vanilla Linux kernel
 177   Type:         Kernel Image
 178   Compression:  gzip compressed
 179   Data Size:    1092037 Bytes = 1066.44 kB = 1.04 MB
 180   Architecture: PowerPC
 181   OS:           Linux
 182   Load Address: 0x00000000
 183   Entry Point:  0x00000000
 184   Hash algo:    crc32
 185   Hash value:   2c0cc807
 186   Hash algo:    sha1
 187   Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 188  Image 1 (fdt@1)
 189   Description:  Flattened Device Tree blob
 190   Type:         Flat Device Tree
 191   Compression:  uncompressed
 192   Data Size:    16384 Bytes = 16.00 kB = 0.02 MB
 193   Architecture: PowerPC
 194   Hash algo:    crc32
 195   Hash value:   0d655d71
 196   Hash algo:    sha1
 197   Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 198  Default Configuration: 'conf@1'
 199  Configuration 0 (conf@1)
 200   Description:  Boot Linux kernel with FDT blob
 201   Kernel:       kernel@1
 202   FDT:          fdt@1
 203
 204
 205 The resulting image file kernel_fdt.itb can be now transferred to the target,
 206 inspected and booted:
 207
 208 [on the target system]
 209 => tftp 900000 /path/to/tftp/location/kernel_fdt.itb
 210 Using FEC ETHERNET device
 211 TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 212 Filename '/path/to/tftp/location/kernel_fdt.itb'.
 213 Load address: 0x900000
 214 Loading: #################################################################
 215          ###########
 216 done
 217 Bytes transferred = 1109776 (10ef10 hex)
 218 => iminfo
 219
 220 ## Checking Image at 00900000 ...
 221    FIT image found
 222    FIT description: Simple image with single Linux kernel and FDT blob
 223    Created:         2008-03-11  15:29:22 UTC
 224     Image 0 (kernel@1)
 225      Description:  Vanilla Linux kernel
 226      Type:         Kernel Image
 227      Compression:  gzip compressed
 228      Data Start:   0x009000ec
 229      Data Size:    1092037 Bytes =  1 MB
 230      Architecture: PowerPC
 231      OS:           Linux
 232      Load Address: 0x00000000
 233      Entry Point:  0x00000000
 234      Hash algo:    crc32
 235      Hash value:   2c0cc807
 236      Hash algo:    sha1
 237      Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 238     Image 1 (fdt@1)
 239      Description:  Flattened Device Tree blob
 240      Type:         Flat Device Tree
 241      Compression:  uncompressed
 242      Data Start:   0x00a0abdc
 243      Data Size:    16384 Bytes = 16 kB
 244      Architecture: PowerPC
 245      Hash algo:    crc32
 246      Hash value:   0d655d71
 247      Hash algo:    sha1
 248      Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 249     Default Configuration: 'conf@1'
 250     Configuration 0 (conf@1)
 251      Description:  Boot Linux kernel with FDT blob
 252      Kernel:       kernel@1
 253      FDT:          fdt@1
 254 => bootm
 255 ## Booting kernel from FIT Image at 00900000 ...
 256    Using 'conf@1' configuration
 257    Trying 'kernel@1' kernel subimage
 258      Description:  Vanilla Linux kernel
 259      Type:         Kernel Image
 260      Compression:  gzip compressed
 261      Data Start:   0x009000ec
 262      Data Size:    1092037 Bytes =  1 MB
 263      Architecture: PowerPC
 264      OS:           Linux
 265      Load Address: 0x00000000
 266      Entry Point:  0x00000000
 267      Hash algo:    crc32
 268      Hash value:   2c0cc807
 269      Hash algo:    sha1
 270      Hash value:   264b59935470e42c418744f83935d44cdf59a3bb
 271    Verifying Hash Integrity ... crc32+ sha1+ OK
 272    Uncompressing Kernel Image ... OK
 273 ## Flattened Device Tree from FIT Image at 00900000
 274    Using 'conf@1' configuration
 275    Trying 'fdt@1' FDT blob subimage
 276      Description:  Flattened Device Tree blob
 277      Type:         Flat Device Tree
 278      Compression:  uncompressed
 279      Data Start:   0x00a0abdc
 280      Data Size:    16384 Bytes = 16 kB
 281      Architecture: PowerPC
 282      Hash algo:    crc32
 283      Hash value:   0d655d71
 284      Hash algo:    sha1
 285      Hash value:   25ab4e15cd4b8a5144610394560d9c318ce52def
 286    Verifying Hash Integrity ... crc32+ sha1+ OK
 287    Booting using the fdt blob at 0xa0abdc
 288    Loading Device Tree to 007fc000, end 007fffff ... OK
 289 [    0.000000] Using lite5200 machine description
 290 [    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
 291
 292
 293 Example 3 -- advanced booting
 294 -----------------------------
 295
 296 Refer to doc/uImage.FIT/multi.its for an image source file that allows more
 297 sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).