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