1U-boot new uImage source file format (bindings definition)
2==========================================================
3
4Author: Marian Balakowicz <m8@semihalf.com>
5
61) Introduction
7---------------
8
9Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
10booting method which requires that hardware description is available to the
11kernel in the form of Flattened Device Tree.
12
13Booting with a Flattened Device Tree is much more flexible and is intended to
14replace direct passing of 'struct bd_info' which was used to boot pre-FDT
15kernels.
16
17However, U-boot needs to support both techniques to provide backward
18compatibility for platforms which are not FDT ready. Number of elements
19playing role in the booting process has increased and now includes the FDT
20blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed
21in the system memory and passed to bootm as a arguments. Some of them may be
22missing: FDT is not present for legacy platforms, ramdisk is always optional.
23Additionally, old uImage format has been extended to support multi sub-images
24but the support is limited by simple format of the legacy uImage structure.
25Single binary header 'struct image_header' is not flexible enough to cover all
26possible scenarios.
27
28All those factors combined clearly show that there is a need for new, more
29flexible, multi component uImage format.
30
31
322) New uImage format assumptions
33--------------------------------
34
35a) Implementation
36
37Libfdt has been selected for the new uImage format implementation as (1) it
38provides 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
41b) Terminology
42
43This document defines new uImage structure by providing FDT bindings for new
44uImage internals. Bindings are defined from U-boot perspective, i.e. describe
45final form of the uImage at the moment when it reaches U-boot. User
46perspective may be simpler, as some of the properties (like timestamps and
47hashes) will need to be filled in automatically by the U-boot mkimage tool.
48
49To avoid confusion with the kernel FDT the following naming convention is
50proposed for the new uImage format related terms:
51
52FIT	- Flattened uImage Tree
53
54FIT is formally a flattened device tree (in the libfdt meaning), which
55conforms to bindings defined in this document.
56
57.its	- image tree source
58.itb	- image tree blob
59
60c) Image building procedure
61
62The following picture shows how the new uImage is prepared. Input consists of
63image source file (.its) and a set of data files. Image is created with the
64help of standard U-boot mkimage tool which in turn uses dtc (device tree
65compiler) to produce image tree blob (.itb).  Resulting .itb file is is the
66actual binary of a new uImage.
67
68
69tqm5200.its
70+
71vmlinux.bin.gz	   mkimage + dtc	       xfer to target
72eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> bootm
73tqm5200.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
84d) Unique identifiers
85
86To identify FIT sub-nodes representing images, hashes, configurations (which
87are defined in the following sections), the "unit name" of the given sub-node
88is used as it's identifier as it assures uniqueness without additional
89checking required.
90
91
923) Root node properties
93-----------------------
94
95Root 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
1384) '/images' node
139-----------------
140
141This node is a container node for component sub-image nodes. Each sub-node of
142the '/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
1895) Hash nodes
190-------------
191
192o 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
2026) '/configurations' node
203-------------------------
204
205The 'configurations' node is optional. If present, it allows to create a
206convenient, labeled boot configurations, which combine together kernel images
207with their ramdisks and fdt blobs.
208
209The 'configurations' node has has the following structure:
210
211o 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
2287) Configuration nodes
229----------------------
230
231Each configuration has the following structure:
232
233o 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
251The FDT blob is required to properly boot FDT based kernel, so the minimal
252configuration for 2.6 FDT kernel is (kernel, fdt) pair.
253
254Older, 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
256not* be specified in a configuration node.
257
258
2598) Examples
260-----------
261
262Please see doc/uImage.FIT/*.its for actual image source files.
263