uboot/doc/uImage.FIT/howto.txt
<<
>>
Prefs
   1How to use images in the new image format
   2=========================================
   3
   4Author: Bartlomiej Sieka <tur@semihalf.com>
   5
   6
   7Overview
   8--------
   9
  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.
  13
  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
  19
  20        git://git.kernel.org/pub/scm/utils/dtc/dtc.git
  21
  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.
  33
  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)
  39
  40
  41Here's a graphical overview of the image creation and booting process:
  42
  43image source file     mkimage + dtc               transfer to target
  44        +            ---------------> image file --------------------> bootm
  45image data file(s)
  46
  47
  48Example 1 -- old-style (non-FDT) kernel booting
  49-----------------------------------------------
  50
  51Consider a simple scenario, where a PPC Linux kernel built from sources on the
  52development host is to be booted old-style (non-FDT) by U-Boot on an embedded
  53target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
  54contains a gzip-compressed PPC Linux kernel (the only data file in this case).
  55The uImage can be produced using the image source file
  56doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
  57in the current working directory; if desired, an alternative path can be
  58specified in the kernel.its file). Here's how to create the image and inspect
  59its contents:
  60
  61[on the host system]
  62$ mkimage -f kernel.its kernel.itb
  63DTC: dts->dtb  on file "kernel.its"
  64$
  65$ mkimage -l kernel.itb
  66FIT description: Simple image with single Linux kernel
  67Created:         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
  87The resulting image file kernel.itb can be now transferred to the target,
  88inspected and booted (note that first three U-Boot commands below are shown
  89for completeness -- they are part of the standard booting procedure and not
  90specific to the new image format).
  91
  92[on the target system]
  93=> print nfsargs
  94nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
  95=> print addip
  96addip=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
  99Using FEC device
 100TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 101Filename '/path/to/tftp/location/kernel.itb'.
 102Load address: 0x900000
 103Loading: #################################################################
 104done
 105Bytes 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
 150Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
 151Linux 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
 152On node 0 totalpages: 65536
 153zone(0): 65536 pages.
 154zone(1): 0 pages.
 155zone(2): 0 pages.
 156Kernel 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
 157Calibrating delay loop... 307.20 BogoMIPS
 158
 159
 160Example 2 -- new-style (FDT) kernel booting
 161-------------------------------------------
 162
 163Consider another simple scenario, where a PPC Linux kernel is to be booted
 164new-style, i.e., with a FDT blob. In this case there are two prerequisite data
 165files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
 166be 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
 168the current working directory -- image source file kernel_fdt.its can be
 169modified 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
 173DTC: dts->dtb  on file "kernel_fdt.its"
 174$
 175$ mkimage -l kernel_fdt.itb
 176FIT description: Simple image with single Linux kernel and FDT blob
 177Created:         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
 208The resulting image file kernel_fdt.itb can be now transferred to the target,
 209inspected and booted:
 210
 211[on the target system]
 212=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
 213Using FEC device
 214TFTP from server 192.168.1.1; our IP address is 192.168.160.5
 215Filename '/path/to/tftp/location/kernel_fdt.itb'.
 216Load address: 0x900000
 217Loading: #################################################################
 218         ###########
 219done
 220Bytes 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
 296Example 3 -- advanced booting
 297-----------------------------
 298
 299Refer to doc/uImage.FIT/multi.its for an image source file that allows more
 300sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).
 301