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
   6 1) Introduction
   7 ---------------
   8
   9 Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
  10 booting method which requires that hardware description is available to the
  11 kernel in the form of Flattened Device Tree.
  12
  13 Booting with a Flattened Device Tree is much more flexible and is intended to
  14 replace direct passing of 'struct bd_info' which was used to boot pre-FDT
  15 kernels.
  16
  17 However, U-boot needs to support both techniques to provide backward
  18 compatibility for platforms which are not FDT ready. Number of elements
  19 playing role in the booting process has increased and now includes the FDT
  20 blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed
  21 in the system memory and passed to bootm as a arguments. Some of them may be
  22 missing: FDT is not present for legacy platforms, ramdisk is always optional.
  23 Additionally, old uImage format has been extended to support multi sub-images
  24 but the support is limited by simple format of the legacy uImage structure.
  25 Single binary header 'struct image_header' is not flexible enough to cover all
  26 possible scenarios.
  27
  28 All those factors combined clearly show that there is a need for new, more
  29 flexible, multi component uImage format.
  30
  31
  32 2) New uImage format assumptions
  33 --------------------------------
  34
  35 a) Implementation
  36
  37 Libfdt has been selected for the new uImage format implementation as (1) it
  38 provides needed functionality, (2) is actively maintained and developed and
  39 (3) increases code reuse as it is already part of the U-boot source tree.
  40
  41 b) Terminology
  42
  43 This document defines new uImage structure by providing FDT bindings for new
  44 uImage internals. Bindings are defined from U-boot perspective, i.e. describe
  45 final form of the uImage at the moment when it reaches U-boot. User
  46 perspective may be simpler, as some of the properties (like timestamps and
  47 hashes) will need to be filled in automatically by the U-boot mkimage tool.
  48
  49 To avoid confusion with the kernel FDT the following naming convention is
  50 proposed for the new uImage format related terms:
  51
  52 FIT     - Flattened uImage Tree
  53
  54 FIT is formally a flattened device tree (in the libfdt meaning), which
  55 conforms to bindings defined in this document.
  56
  57 .its    - image tree source
  58 .itb    - image tree blob
  59
  60 c) Image building procedure
  61
  62 The following picture shows how the new uImage is prepared. Input consists of
  63 image source file (.its) and a set of data files. Image is created with the
  64 help of standard U-boot mkimage tool which in turn uses dtc (device tree
  65 compiler) to produce image tree blob (.itb).  Resulting .itb file is is the
  66 actual binary of a new uImage.
  67
  68
  69 tqm5200.its
  70 +
  71 vmlinux.bin.gz     mkimage + dtc               xfer to target
  72 eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> bootm
  73 tqm5200.dtb                          /|\
  74 ...                                   |
  75                                  'new uImage'
  76
  77         - create .its file, automatically filled-in properties are omitted
  78         - call mkimage tool on a .its file
  79         - mkimage calls dtc to create .itb image and assures that
  80           missing properties are added
  81         - .itb (new uImage) is uploaded onto the target and used therein
  82
  83
  84 d) Unique identifiers
  85
  86 To identify FIT sub-nodes representing images, hashes, configurations (which
  87 are defined in the following sections), the "unit name" of the given sub-node
  88 is used as it's identifier as it assures uniqueness without additional
  89 checking required.
  90
  91
  92 3) Root node properties
  93 -----------------------
  94
  95 Root node of the uImage Tree should have the following layout:
  96
  97 / o image-tree
  98     |- description = "image description"
  99     |- timestamp = <12399321>
 100     |- #address-cells = <1>
 101     |
 102     o images
 103     | |
 104     | o img@1 {...}
 105     | o img@2 {...}
 106     | ...
 107     |
 108     o configurations
 109       |- default = "cfg@1"
 110       |
 111       o cfg@1 {...}
 112       o cfg@2 {...}
 113       ...
 114
 115
 116   Optional property:
 117   - description : Textual description of the uImage
 118
 119   Mandatory property:
 120   - timestamp : Last image modification time being counted in seconds since
 121     1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
 122
 123   Conditionally mandatory property:
 124   - #address-cells : Number of 32bit cells required to represent entry and
 125     load addresses supplied within sub-image nodes. May be omitted when no
 126     entry or load addresses are used.
 127
 128   Mandatory node:
 129   - images : This node contains a set of sub-nodes, each of them representing
 130     single component sub-image (like kernel, ramdisk, etc.). At least one
 131     sub-image is required.
 132
 133   Optional node:
 134   - configurations : Contains a set of available configuration nodes and
 135     defines a default configuration.
 136
 137
 138 4) '/images' node
 139 -----------------
 140
 141 This node is a container node for component sub-image nodes. Each sub-node of
 142 the '/images' node should have the following layout:
 143
 144  o image@1
 145    |- description = "component sub-image description"
 146    |- data = /incbin/("path/to/data/file.bin")
 147    |- type = "sub-image type name"
 148    |- arch = "ARCH name"
 149    |- os = "OS name"
 150    |- compression = "compression name"
 151    |- load = <00000000>
 152    |- entry = <00000000>
 153    |
 154    o hash@1 {...}
 155    o hash@2 {...}
 156    ...
 157
 158   Mandatory properties:
 159   - description : Textual description of the component sub-image
 160   - type : Name of component sub-image type, supported types are:
 161     "standalone", "kernel", "ramdisk", "firmware", "script", "filesystem",
 162     "fdt".
 163   - data : Path to the external file which contains this node's binary data.
 164   - compression : Compression used by included data. Supported compressions
 165     are "gzip" and "bzip2". If no compression is used compression property
 166     should be set to "none".
 167
 168   Conditionally mandatory property:
 169   - os : OS name, mandatory for type="kernel", valid OS names are: "openbsd",
 170     "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix", "solaris", "irix",
 171     "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx", "u_boot",
 172     "rtems", "unity", "integrity".
 173   - arch : Architecture name, mandatory for types: "standalone", "kernel",
 174     "firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha",
 175     "arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc",
 176     "sparc64", "m68k", "nios", "microblaze", "nios2", "blackfin", "avr32",
 177     "st200".
 178   - entry : entry point address, address size is determined by
 179     '#address-cells' property of the root node. Mandatory for for types:
 180     "standalone" and "kernel".
 181   - load : load address, address size is determined by '#address-cells'
 182     property of the root node. Mandatory for types: "standalone" and "kernel".
 183
 184   Optional nodes:
 185   - hash@1 : Each hash sub-node represents separate hash or checksum
 186     calculated for node's data according to specified algorithm.
 187
 188
 189 5) Hash nodes
 190 -------------
 191
 192 o hash@1
 193   |- algo = "hash or checksum algorithm name"
 194   |- value = [hash or checksum value]
 195
 196   Mandatory properties:
 197   - algo : Algorithm name, supported are "crc32", "md5" and "sha1".
 198   - value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes
 199     long.
 200
 201
 202 6) '/configurations' node
 203 -------------------------
 204
 205 The 'configurations' node is optional. If present, it allows to create a
 206 convenient, labeled boot configurations, which combine together kernel images
 207 with their ramdisks and fdt blobs.
 208
 209 The 'configurations' node has has the following structure:
 210
 211 o configurations
 212   |- default = "default configuration sub-node unit name"
 213   |
 214   o config@1 {...}
 215   o config@2 {...}
 216   ...
 217
 218
 219   Optional property:
 220   - default : Selects one of the configuration sub-nodes as a default
 221     configuration.
 222
 223   Mandatory nodes:
 224   - configuration-sub-node-unit-name : At least one of the configuration
 225     sub-nodes is required.
 226
 227
 228 7) Configuration nodes
 229 ----------------------
 230
 231 Each configuration has the following structure:
 232
 233 o config@1
 234   |- description = "configuration description"
 235   |- kernel = "kernel sub-node unit name"
 236   |- ramdisk = "ramdisk sub-node unit name"
 237   |- fdt = "fdt sub-node unit-name"
 238
 239
 240   Mandatory properties:
 241   - description : Textual configuration description.
 242   - kernel : Unit name of the corresponding kernel image (image sub-node of a
 243     "kernel" type).
 244
 245   Optional properties:
 246   - ramdisk : Unit name of the corresponding ramdisk image (component image
 247     node of a "ramdisk" type).
 248   - fdt : Unit name of the corresponding fdt blob (component image node of a
 249     "fdt type").
 250
 251 The FDT blob is required to properly boot FDT based kernel, so the minimal
 252 configuration for 2.6 FDT kernel is (kernel, fdt) pair.
 253
 254 Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
 255 'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
 256 not* be specified in a configuration node.
 257
 258
 259 8) Examples
 260 -----------
 261
 262 Please see doc/uImage.FIT/*.its for actual image source files.