1U-Boot new uImage source file format (bindings definition)
2==========================================================
3
4Author: Marian Balakowicz <m8@semihalf.com>
5External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
6
71) Introduction
8---------------
9
10Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
11booting method which requires that hardware description is available to the
12kernel in the form of Flattened Device Tree.
13
14Booting with a Flattened Device Tree is much more flexible and is intended to
15replace direct passing of 'struct bd_info' which was used to boot pre-FDT
16kernels.
17
18However, U-Boot needs to support both techniques to provide backward
19compatibility for platforms which are not FDT ready. Number of elements
20playing role in the booting process has increased and now includes the FDT
21blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed
22in the system memory and passed to bootm as a arguments. Some of them may be
23missing: FDT is not present for legacy platforms, ramdisk is always optional.
24Additionally, old uImage format has been extended to support multi sub-images
25but the support is limited by simple format of the legacy uImage structure.
26Single binary header 'struct image_header' is not flexible enough to cover all
27possible scenarios.
28
29All those factors combined clearly show that there is a need for new, more
30flexible, multi component uImage format.
31
32
332) New uImage format assumptions
34--------------------------------
35
36a) Implementation
37
38Libfdt has been selected for the new uImage format implementation as (1) it
39provides 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
42b) Terminology
43
44This document defines new uImage structure by providing FDT bindings for new
45uImage internals. Bindings are defined from U-Boot perspective, i.e. describe
46final form of the uImage at the moment when it reaches U-Boot. User
47perspective may be simpler, as some of the properties (like timestamps and
48hashes) will need to be filled in automatically by the U-Boot mkimage tool.
49
50To avoid confusion with the kernel FDT the following naming convention is
51proposed for the new uImage format related terms:
52
53FIT	- Flattened uImage Tree
54
55FIT is formally a flattened device tree (in the libfdt meaning), which
56conforms to bindings defined in this document.
57
58.its	- image tree source
59.itb	- flattened image tree blob
60
61c) Image building procedure
62
63The following picture shows how the new uImage is prepared. Input consists of
64image source file (.its) and a set of data files. Image is created with the
65help of standard U-Boot mkimage tool which in turn uses dtc (device tree
66compiler) to produce image tree blob (.itb).  Resulting .itb file is the
67actual binary of a new uImage.
68
69
70tqm5200.its
71+
72vmlinux.bin.gz	   mkimage + dtc	       xfer to target
73eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> bootm
74tqm5200.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
85d) Unique identifiers
86
87To identify FIT sub-nodes representing images, hashes, configurations (which
88are defined in the following sections), the "unit name" of the given sub-node
89is used as it's identifier as it assures uniqueness without additional
90checking required.
91
92
933) Root node properties
94-----------------------
95
96Root 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 node:
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
134  Optional node:
135  - configurations : Contains a set of available configuration nodes and
136    defines a default configuration.
137
138
1394) '/images' node
140-----------------
141
142This node is a container node for component sub-image nodes. Each sub-node of
143the '/images' node should have the following layout:
144
145 o image-1
146   |- description = "component sub-image description"
147   |- data = /incbin/("path/to/data/file.bin")
148   |- type = "sub-image type name"
149   |- arch = "ARCH name"
150   |- os = "OS name"
151   |- compression = "compression name"
152   |- load = <00000000>
153   |- entry = <00000000>
154   |
155   o hash-1 {...}
156   o hash-2 {...}
157   ...
158
159  Mandatory properties:
160  - description : Textual description of the component sub-image
161  - type : Name of component sub-image type, supported types are:
162    "standalone", "kernel", "kernel_noload", "ramdisk", "firmware", "script",
163    "filesystem", "flat_dt" and others (see uimage_type in common/image.c).
164  - data : Path to the external file which contains this node's binary data.
165  - compression : Compression used by included data. Supported compressions
166    are "gzip" and "bzip2". If no compression is used compression property
167    should be set to "none".
168
169  Conditionally mandatory property:
170  - os : OS name, mandatory for types "kernel" and "ramdisk". Valid OS names
171    are: "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. Mandatory for for types:
181    "standalone" and "kernel".
182  - load : load address, address size is determined by '#address-cells'
183    property of the root node. Mandatory for types: "standalone" and "kernel".
184
185  Optional nodes:
186  - hash-1 : Each hash sub-node represents separate hash or checksum
187    calculated for node's data according to specified algorithm.
188
189
1905) Hash nodes
191-------------
192
193o hash-1
194  |- algo = "hash or checksum algorithm name"
195  |- value = [hash or checksum value]
196
197  Mandatory properties:
198  - algo : Algorithm name, supported are "crc32", "md5" and "sha1".
199  - value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes
200    long.
201
202
2036) '/configurations' node
204-------------------------
205
206The 'configurations' node is optional. If present, it allows to create a
207convenient, labeled boot configurations, which combine together kernel images
208with their ramdisks and fdt blobs.
209
210The 'configurations' node has has the following structure:
211
212o configurations
213  |- default = "default configuration sub-node unit name"
214  |
215  o config-1 {...}
216  o config-2 {...}
217  ...
218
219
220  Optional property:
221  - default : Selects one of the configuration sub-nodes as a default
222    configuration.
223
224  Mandatory nodes:
225  - configuration-sub-node-unit-name : At least one of the configuration
226    sub-nodes is required.
227
228
2297) Configuration nodes
230----------------------
231
232Each configuration has the following structure:
233
234o config-1
235  |- description = "configuration description"
236  |- kernel = "kernel sub-node unit name"
237  |- ramdisk = "ramdisk sub-node unit name"
238  |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
239  |- fpga = "fpga sub-node unit-name"
240  |- loadables = "loadables sub-node unit-name"
241
242
243  Mandatory properties:
244  - description : Textual configuration description.
245  - kernel : Unit name of the corresponding kernel image (image sub-node of a
246    "kernel" type).
247
248  Optional properties:
249  - ramdisk : Unit name of the corresponding ramdisk image (component image
250    node of a "ramdisk" type).
251  - fdt : Unit name of the corresponding fdt blob (component image node of a
252    "fdt type"). Additional fdt overlay nodes can be supplied which signify
253    that the resulting device tree blob is generated by the first base fdt
254    blob with all subsequent overlays applied.
255  - setup : Unit name of the corresponding setup binary (used for booting
256    an x86 kernel). This contains the setup.bin file built by the kernel.
257  - fpga : Unit name of the corresponding fpga bitstream blob
258    (component image node of a "fpga type").
259  - loadables : Unit name containing a list of additional binaries to be
260    loaded at their given locations.  "loadables" is a comma-separated list
261    of strings. U-Boot will load each binary at its given start-address and
262    may optionaly invoke additional post-processing steps on this binary based
263    on its component image node type.
264
265The FDT blob is required to properly boot FDT based kernel, so the minimal
266configuration for 2.6 FDT kernel is (kernel, fdt) pair.
267
268Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
269'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
270not* be specified in a configuration node.
271
272
2738) External data
274----------------
275
276The above format shows a 'data' property which holds the data for each image.
277It is also possible for this data to reside outside the FIT itself. This
278allows the FIT to be quite small, so that it can be loaded and scanned
279without loading a large amount of data. Then when an image is needed it can
280be loaded from an external source.
281
282In this case the 'data' property is omitted. Instead you can use:
283
284  - data-offset : offset of the data in a separate image store. The image
285    store is placed immediately after the last byte of the device tree binary,
286    aligned to a 4-byte boundary.
287  - data-size : size of the data in bytes
288
289The 'data-offset' property can be substituted with 'data-position', which
290defines an absolute position or address as the offset. This is helpful when
291booting U-Boot proper before performing relocation. Pass '-p [offset]' to
292mkimage to enable 'data-position'.
293
294Normal kernel FIT image has data embedded within FIT structure. U-Boot image
295for SPL boot has external data. Existence of 'data-offset' can be used to
296identify which format is used.
297
2989) Examples
299-----------
300
301Please see doc/uImage.FIT/*.its for actual image source files.
302