Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 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 |
Simon Glass | 750d66c | 2014-10-19 21:11:23 -0600 | [diff] [blame] | 58 | .fit - flattened image tree blob |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 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 |
Masahiro Yamada | 89af930 | 2013-09-13 20:28:21 +0900 | [diff] [blame] | 65 | compiler) to produce image tree blob (.itb). Resulting .itb file is the |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 66 | actual binary of a new uImage. |
| 67 | |
| 68 | |
| 69 | tqm5200.its |
| 70 | + |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 71 | vmlinux.bin.gz mkimage + dtc xfer to target |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 72 | eldk-4.2-ramdisk --------------> tqm5200.itb --------------> bootm |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 73 | tqm5200.dtb /|\ |
| 74 | ... | |
| 75 | 'new uImage' |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 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 | | | |
Simon Glass | 750d66c | 2014-10-19 21:11:23 -0600 | [diff] [blame] | 104 | | o image@1 {...} |
| 105 | | o image@2 {...} |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 106 | | ... |
| 107 | | |
| 108 | o configurations |
Simon Glass | 750d66c | 2014-10-19 21:11:23 -0600 | [diff] [blame] | 109 | |- default = "conf@1" |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 110 | | |
Simon Glass | 750d66c | 2014-10-19 21:11:23 -0600 | [diff] [blame] | 111 | o conf@1 {...} |
| 112 | o conf@2 {...} |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 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", |
Simon Glass | 750d66c | 2014-10-19 21:11:23 -0600 | [diff] [blame] | 162 | "flat_dt" and others (see uimage_type in common/images.c). |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 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", |
Peter Tyser | 56b8dd1 | 2008-09-08 14:56:49 -0500 | [diff] [blame] | 172 | "rtems", "unity", "integrity". |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 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", |
Simon Glass | 750d66c | 2014-10-19 21:11:23 -0600 | [diff] [blame] | 176 | "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200", |
| 177 | "sandbox". |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 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"). |
Simon Glass | 0129b52 | 2014-10-19 21:11:24 -0600 | [diff] [blame] | 250 | - setup : Unit name of the corresponding setup binary (used for booting |
| 251 | an x86 kernel). This contains the setup.bin file built by the kernel. |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 252 | |
| 253 | The FDT blob is required to properly boot FDT based kernel, so the minimal |
| 254 | configuration for 2.6 FDT kernel is (kernel, fdt) pair. |
| 255 | |
| 256 | Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases |
| 257 | 'struct bd_info' must be passed instead of FDT blob, thus fdt property *must |
| 258 | not* be specified in a configuration node. |
| 259 | |
| 260 | |
| 261 | 8) Examples |
| 262 | ----------- |
| 263 | |
Bartlomiej Sieka | 739d2d7 | 2008-03-20 23:10:19 +0100 | [diff] [blame] | 264 | Please see doc/uImage.FIT/*.its for actual image source files. |