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