doc/uImage.FIT/source_file_format.txt

   1 U-Boot new uImage source file format (bindings definition)
   2 ==========================================================
   3
   4 Author: Marian Balakowicz <m8@semihalf.com>
   5 External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
   6
   7 1) Introduction
   8 ---------------
   9
  10 Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
  11 booting method which requires that hardware description is available to the
  12 kernel in the form of Flattened Device Tree.
  13
  14 Booting with a Flattened Device Tree is much more flexible and is intended to
  15 replace direct passing of 'struct bd_info' which was used to boot pre-FDT
  16 kernels.
  17
  18 However, U-Boot needs to support both techniques to provide backward
  19 compatibility for platforms which are not FDT ready. Number of elements
  20 playing role in the booting process has increased and now includes the FDT
  21 blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed
  22 in the system memory and passed to bootm as a arguments. Some of them may be
  23 missing: FDT is not present for legacy platforms, ramdisk is always optional.
  24 Additionally, old uImage format has been extended to support multi sub-images
  25 but the support is limited by simple format of the legacy uImage structure.
  26 Single binary header 'struct legacy_img_hdr' is not flexible enough to cover all
  27 possible scenarios.
  28
  29 All those factors combined clearly show that there is a need for new, more
  30 flexible, multi component uImage format.
  31
  32
  33 2) New uImage format assumptions
  34 --------------------------------
  35
  36 a) Implementation
  37
  38 Libfdt has been selected for the new uImage format implementation as (1) it
  39 provides needed functionality, (2) is actively maintained and developed and
  40 (3) increases code reuse as it is already part of the U-Boot source tree.
  41
  42 b) Terminology
  43
  44 This document defines new uImage structure by providing FDT bindings for new
  45 uImage internals. Bindings are defined from U-Boot perspective, i.e. describe
  46 final form of the uImage at the moment when it reaches U-Boot. User
  47 perspective may be simpler, as some of the properties (like timestamps and
  48 hashes) will need to be filled in automatically by the U-Boot mkimage tool.
  49
  50 To avoid confusion with the kernel FDT the following naming convention is
  51 proposed for the new uImage format related terms:
  52
  53 FIT     - Flattened uImage Tree
  54
  55 FIT is formally a flattened device tree (in the libfdt meaning), which
  56 conforms to bindings defined in this document.
  57
  58 .its    - image tree source
  59 .itb    - flattened image tree blob
  60
  61 c) Image building procedure
  62
  63 The following picture shows how the new uImage is prepared. Input consists of
  64 image source file (.its) and a set of data files. Image is created with the
  65 help of standard U-Boot mkimage tool which in turn uses dtc (device tree
  66 compiler) to produce image tree blob (.itb).  Resulting .itb file is the
  67 actual binary of a new uImage.
  68
  69
  70 tqm5200.its
  71 +
  72 vmlinux.bin.gz     mkimage + dtc               xfer to target
  73 eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> bootm
  74 tqm5200.dtb                          /|\
  75 ...                                   |
  76                                  'new uImage'
  77
  78         - create .its file, automatically filled-in properties are omitted
  79         - call mkimage tool on a .its file
  80         - mkimage calls dtc to create .itb image and assures that
  81           missing properties are added
  82         - .itb (new uImage) is uploaded onto the target and used therein
  83
  84
  85 d) Unique identifiers
  86
  87 To identify FIT sub-nodes representing images, hashes, configurations (which
  88 are defined in the following sections), the "unit name" of the given sub-node
  89 is used as it's identifier as it assures uniqueness without additional
  90 checking required.
  91
  92
  93 3) Root node properties
  94 -----------------------
  95
  96 Root node of the uImage Tree should have the following layout:
  97
  98 / o image-tree
  99     |- description = "image description"
 100     |- timestamp = <12399321>
 101     |- #address-cells = <1>
 102     |
 103     o images
 104     | |
 105     | o image-1 {...}
 106     | o image-2 {...}
 107     | ...
 108     |
 109     o configurations
 110       |- default = "conf-1"
 111       |
 112       o conf-1 {...}
 113       o conf-2 {...}
 114       ...
 115
 116
 117   Optional property:
 118   - description : Textual description of the uImage
 119
 120   Mandatory property:
 121   - timestamp : Last image modification time being counted in seconds since
 122     1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
 123
 124   Conditionally mandatory property:
 125   - #address-cells : Number of 32bit cells required to represent entry and
 126     load addresses supplied within sub-image nodes. May be omitted when no
 127     entry or load addresses are used.
 128
 129   Mandatory nodes:
 130   - images : This node contains a set of sub-nodes, each of them representing
 131     single component sub-image (like kernel, ramdisk, etc.). At least one
 132     sub-image is required.
 133   - configurations : Contains a set of available configuration nodes and
 134     defines a default configuration.
 135
 136
 137 4) '/images' node
 138 -----------------
 139
 140 This node is a container node for component sub-image nodes. Each sub-node of
 141 the '/images' node should have the following layout:
 142
 143  o image-1
 144    |- description = "component sub-image description"
 145    |- data = /incbin/("path/to/data/file.bin")
 146    |- type = "sub-image type name"
 147    |- arch = "ARCH name"
 148    |- os = "OS name"
 149    |- compression = "compression name"
 150    |- load = <00000000>
 151    |- entry = <00000000>
 152    |
 153    o hash-1 {...}
 154    o hash-2 {...}
 155    ...
 156
 157   Mandatory properties:
 158   - description : Textual description of the component sub-image
 159   - type : Name of component sub-image type, supported types are:
 160     "standalone", "kernel", "kernel_noload", "ramdisk", "firmware", "script",
 161     "filesystem", "flat_dt" and others (see uimage_type in common/image.c).
 162   - data : Path to the external file which contains this node's binary data.
 163   - compression : Compression used by included data. Supported compressions
 164     are "gzip" and "bzip2". If no compression is used compression property
 165     should be set to "none". If the data is compressed but it should not be
 166     uncompressed by U-Boot (e.g. compressed ramdisk), this should also be set
 167     to "none".
 168
 169   Conditionally mandatory property:
 170   - os : OS name, mandatory for types "kernel". Valid OS names are:
 171     "openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix",
 172     "solaris", "irix", "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx",
 173     "u-boot", "rtems", "unity", "integrity".
 174   - arch : Architecture name, mandatory for types: "standalone", "kernel",
 175     "firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha",
 176     "arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc",
 177     "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200",
 178     "sandbox".
 179   - entry : entry point address, address size is determined by
 180     '#address-cells' property of the root node.
 181     Mandatory for types: "firmware", and "kernel".
 182   - load : load address, address size is determined by '#address-cells'
 183     property of the root node.
 184     Mandatory for types: "firmware", and "kernel".
 185   - compatible : compatible method for loading image.
 186     Mandatory for types: "fpga", and images that do not specify a load address.
 187     Supported compatible methods:
 188     "u-boot,fpga-legacy" - the generic fpga loading routine.
 189     "u-boot,zynqmp-fpga-ddrauth" - signed non-encrypted FPGA bitstream for
 190     Xilinx Zynq UltraScale+ (ZymqMP) device.
 191     "u-boot,zynqmp-fpga-enc" - encrypted FPGA bitstream for Xilinx Zynq
 192     UltraScale+ (ZynqMP) device.
 193   - phase : U-Boot phase for which the image is intended.
 194     "spl" - image is an SPL image
 195     "u-boot" - image is a U-Boot image
 196
 197   Optional nodes:
 198   - hash-1 : Each hash sub-node represents separate hash or checksum
 199     calculated for node's data according to specified algorithm.
 200
 201
 202 5) Hash nodes
 203 -------------
 204
 205 o hash-1
 206   |- algo = "hash or checksum algorithm name"
 207   |- value = [hash or checksum value]
 208
 209   Mandatory properties:
 210   - algo : Algorithm name, supported are "crc32", "md5" and "sha1".
 211   - value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes
 212     long.
 213
 214
 215 6) '/configurations' node
 216 -------------------------
 217
 218 The 'configurations' node creates convenient, labeled boot configurations,
 219 which combine together kernel images with their ramdisks and fdt blobs.
 220
 221 The 'configurations' node has has the following structure:
 222
 223 o configurations
 224   |- default = "default configuration sub-node unit name"
 225   |
 226   o config-1 {...}
 227   o config-2 {...}
 228   ...
 229
 230
 231   Optional property:
 232   - default : Selects one of the configuration sub-nodes as a default
 233     configuration.
 234
 235   Mandatory nodes:
 236   - configuration-sub-node-unit-name : At least one of the configuration
 237     sub-nodes is required.
 238
 239
 240 7) Configuration nodes
 241 ----------------------
 242
 243 Each configuration has the following structure:
 244
 245 o config-1
 246   |- description = "configuration description"
 247   |- kernel = "kernel sub-node unit name"
 248   |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
 249   |- loadables = "loadables sub-node unit-name"
 250   |- script = "
 251   |- compatible = "vendor,board-style device tree compatible string"
 252
 253
 254   Mandatory properties:
 255   - description : Textual configuration description.
 256   - kernel or firmware: Unit name of the corresponding kernel or firmware
 257     (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified,
 258     control is passed to the firmware image.
 259
 260   Optional properties:
 261   - fdt : Unit name of the corresponding fdt blob (component image node of a
 262     "fdt type"). Additional fdt overlay nodes can be supplied which signify
 263     that the resulting device tree blob is generated by the first base fdt
 264     blob with all subsequent overlays applied.
 265   - fpga : Unit name of the corresponding fpga bitstream blob
 266     (component image node of a "fpga type").
 267   - loadables : Unit name containing a list of additional binaries to be
 268     loaded at their given locations.  "loadables" is a comma-separated list
 269     of strings. U-Boot will load each binary at its given start-address and
 270     may optionally invoke additional post-processing steps on this binary based
 271     on its component image node type.
 272   - script : The image to use when loading a U-Boot script (for use with the
 273     source command).
 274   - compatible : The root compatible string of the U-Boot device tree that
 275     this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is
 276     enabled. If this property is not provided, the compatible string will be
 277     extracted from the fdt blob instead. This is only possible if the fdt is
 278     not compressed, so images with compressed fdts that want to use compatible
 279     string matching must always provide this property.
 280
 281 The FDT blob is required to properly boot FDT based kernel, so the minimal
 282 configuration for 2.6 FDT kernel is (kernel, fdt) pair.
 283
 284 Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
 285 'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
 286 not* be specified in a configuration node.
 287
 288
 289 8) External data
 290 ----------------
 291
 292 The above format shows a 'data' property which holds the data for each image.
 293 It is also possible for this data to reside outside the FIT itself. This
 294 allows the FIT to be quite small, so that it can be loaded and scanned
 295 without loading a large amount of data. Then when an image is needed it can
 296 be loaded from an external source.
 297
 298 In this case the 'data' property is omitted. Instead you can use:
 299
 300   - data-offset : offset of the data in a separate image store. The image
 301     store is placed immediately after the last byte of the device tree binary,
 302     aligned to a 4-byte boundary.
 303   - data-size : size of the data in bytes
 304
 305 The 'data-offset' property can be substituted with 'data-position', which
 306 defines an absolute position or address as the offset. This is helpful when
 307 booting U-Boot proper before performing relocation. Pass '-p [offset]' to
 308 mkimage to enable 'data-position'.
 309
 310 Normal kernel FIT image has data embedded within FIT structure. U-Boot image
 311 for SPL boot has external data. Existence of 'data-offset' can be used to
 312 identify which format is used.
 313
 314 For FIT image with external data, it would be better to align each blob of data
 315 to block(512 byte) for block device, so that we don't need to do the copy when
 316 read the image data in SPL. Pass '-B 0x200' to mkimage to align the FIT
 317 structure and data to 512 byte, other values available for other align size.
 318
 319 9) Examples
 320 -----------
 321
 322 Please see doc/uImage.FIT/*.its for actual image source files.