1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
|
.. SPDX-License-Identifier: GPL-2.0+
Flattened Image Tree (FIT) Format
=================================
Introduction
------------
The number of elements playing a role in the kernel booting process has
increased over time and now typically includes the devicetree, kernel image and
possibly a ramdisk image. Generally, all must be placed in the system memory and
booted together.
For firmware images a similar process has taken place, with various binaries
loaded at different addresses, such as ARM's ATF, OpenSBI, FPGA and U-Boot
itself.
FIT provides a flexible and extensible format to deal with this complexity. It
provides support for multiple components. It also supports multiple
configurations, so that the same FIT can be used to boot multiple boards, with
some components in common (e.g. kernel) and some specific to that board (e.g.
devicetree).
Terminology
~~~~~~~~~~~
This document defines FIT by providing FDT (Flat Device Tree) bindings. These
describe the final form of the FIT at the moment when it is used. The user
perspective may be simpler, as some of the properties (like timestamps and
hashes) are filled in automatically by the U-Boot mkimage tool.
To avoid confusion with the kernel FDT the following naming convention is used:
FIT
Flattened Image Tree
FIT is formally a flattened devicetree (in the libfdt meaning), which conforms
to bindings defined in this document.
.its
image tree source
.itb
flattened image tree blob
Image-building procedure
~~~~~~~~~~~~~~~~~~~~~~~~
The following picture shows how the FIT is prepared. Input consists of
image source file (.its) and a set of data files. Image is created with the
help of standard U-Boot mkimage tool which in turn uses dtc (device tree
compiler) to produce image tree blob (.itb). The resulting .itb file is the
actual binary of a new FIT::
tqm5200.its
+
vmlinux.bin.gz mkimage + dtc xfer to target
eldk-4.2-ramdisk --------------> tqm5200.itb --------------> boot
tqm5200.dtb /|\
|
'new FIT'
Steps:
#. Create .its file, automatically filled-in properties are omitted
#. Call mkimage tool on a .its file
#. mkimage calls dtc to create .itb image and assures that
missing properties are added
#. .itb (new FIT) is uploaded onto the target and used therein
Unique identifiers
~~~~~~~~~~~~~~~~~~
To identify FIT sub-nodes representing images, hashes, configurations (which
are defined in the following sections), the "unit name" of the given sub-node
is used as it's identifier as it assures uniqueness without additional
checking required.
Root-node properties
--------------------
The root node of the FIT should have the following layout::
/ o image-tree
|- description = "image description"
|- timestamp = <12399321>
|- #address-cells = <1>
|
o images
| |
| o image-1 {...}
| o image-2 {...}
| ...
|
o configurations
|- default = "conf-1"
|
o conf-1 {...}
o conf-2 {...}
...
Optional property
~~~~~~~~~~~~~~~~~
description
Textual description of the FIT
Mandatory property
~~~~~~~~~~~~~~~~~~
timestamp
Last image modification time being counted in seconds since
1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
Conditionally mandatory property
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#address-cells
Number of 32bit cells required to represent entry and
load addresses supplied within sub-image nodes. May be omitted when no
entry or load addresses are used.
Mandatory nodes
~~~~~~~~~~~~~~~
images
This node contains a set of sub-nodes, each of them representing
single component sub-image (like kernel, ramdisk, etc.). At least one
sub-image is required.
configurations
Contains a set of available configuration nodes and
defines a default configuration.
'/images' node
--------------
This node is a container node for component sub-image nodes. Each sub-node of
the '/images' node should have the following layout::
o image-1
|- description = "component sub-image description"
|- data = /incbin/("path/to/data/file.bin")
|- type = "sub-image type name"
|- arch = "ARCH name"
|- os = "OS name"
|- compression = "compression name"
|- load = <00000000>
|- entry = <00000000>
|
o hash-1 {...}
o hash-2 {...}
...
Mandatory properties
~~~~~~~~~~~~~~~~~~~~
description
Textual description of the component sub-image
type
Name of component sub-image type, supported types are:
"standalone", "kernel", "kernel_noload", "ramdisk", "firmware", "script",
"filesystem", "flat_dt" and others (see uimage_type in common/image.c).
data
Path to the external file which contains this node's binary data.
compression
Compression used by included data. Supported compressions
are "gzip" and "bzip2". If no compression is used compression property
should be set to "none". If the data is compressed but it should not be
uncompressed by U-Boot (e.g. compressed ramdisk), this should also be set
to "none".
Conditionally mandatory property
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
os
OS name, mandatory for types "kernel". Valid OS names are:
"openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix",
"solaris", "irix", "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx",
"u-boot", "rtems", "unity", "integrity".
arch
Architecture name, mandatory for types: "standalone", "kernel",
"firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha",
"arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc",
"sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200",
"sandbox".
entry
entry point address, address size is determined by
'#address-cells' property of the root node.
Mandatory for types: "firmware", and "kernel".
load
load address, address size is determined by '#address-cells'
property of the root node.
Mandatory for types: "firmware", and "kernel".
compatible
compatible method for loading image.
Mandatory for types: "fpga", and images that do not specify a load address.
Supported compatible methods:
"u-boot,fpga-legacy"
the generic fpga loading routine.
"u-boot,zynqmp-fpga-ddrauth"
signed non-encrypted FPGA bitstream for
Xilinx Zynq UltraScale+ (ZymqMP) device.
"u-boot,zynqmp-fpga-enc"
encrypted FPGA bitstream for Xilinx Zynq
UltraScale+ (ZynqMP) device.
phase
U-Boot phase for which the image is intended.
"spl"
image is an SPL image
"u-boot"
image is a U-Boot image
Optional nodes:
hash-1
Each hash sub-node represents separate hash or checksum
calculated for node's data according to specified algorithm.
Hash nodes
----------
::
o hash-1
|- algo = "hash or checksum algorithm name"
|- value = [hash or checksum value]
Mandatory properties
~~~~~~~~~~~~~~~~~~~~
algo
Algorithm name, supported are "crc32", "md5" and "sha1".
value
Actual checksum or hash value, correspondingly 4, 16 or 20 bytes long.
'/configurations' node
----------------------
The 'configurations' node creates convenient, labeled boot configurations,
which combine together kernel images with their ramdisks and fdt blobs.
The 'configurations' node has the following structure::
o configurations
|- default = "default configuration sub-node unit name"
|
o config-1 {...}
o config-2 {...}
...
Optional property
~~~~~~~~~~~~~~~~~
default
Selects one of the configuration sub-nodes as a default configuration.
Mandatory nodes
~~~~~~~~~~~~~~~
configuration-sub-node-unit-name
At least one of the configuration sub-nodes is required.
Configuration nodes
-------------------
Each configuration has the following structure::
o config-1
|- description = "configuration description"
|- kernel = "kernel sub-node unit name"
|- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
|- loadables = "loadables sub-node unit-name"
|- script = "
|- compatible = "vendor,board-style device tree compatible string"
Mandatory properties
~~~~~~~~~~~~~~~~~~~~
description
Textual configuration description.
kernel or firmware
Unit name of the corresponding kernel or firmware
(u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified,
control is passed to the firmware image.
Optional properties
~~~~~~~~~~~~~~~~~~~
fdt
Unit name of the corresponding fdt blob (component image node of a
"fdt type"). Additional fdt overlay nodes can be supplied which signify
that the resulting device tree blob is generated by the first base fdt
blob with all subsequent overlays applied.
fpga
Unit name of the corresponding fpga bitstream blob
(component image node of a "fpga type").
loadables
Unit name containing a list of additional binaries to be
loaded at their given locations. "loadables" is a comma-separated list
of strings. U-Boot will load each binary at its given start-address and
may optionally invoke additional post-processing steps on this binary based
on its component image node type.
script
The image to use when loading a U-Boot script (for use with the
source command).
compatible
The root compatible string of the U-Boot device tree that
this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is
enabled. If this property is not provided, the compatible string will be
extracted from the fdt blob instead. This is only possible if the fdt is
not compressed, so images with compressed fdts that want to use compatible
string matching must always provide this property.
The FDT blob is required to properly boot FDT based kernel, so the minimal
configuration for 2.6 FDT kernel is (kernel, fdt) pair.
Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
not* be specified in a configuration node.
External data
-------------
The above format shows a 'data' property which holds the data for each image.
It is also possible for this data to reside outside the FIT itself. This
allows the FIT to be quite small, so that it can be loaded and scanned
without loading a large amount of data. Then when an image is needed it can
be loaded from an external source.
In this case the 'data' property is omitted. Instead you can use:
data-offset
offset of the data in a separate image store. The image
store is placed immediately after the last byte of the device tree binary,
aligned to a 4-byte boundary.
data-size
size of the data in bytes
The 'data-offset' property can be substituted with 'data-position', which
defines an absolute position or address as the offset. This is helpful when
booting U-Boot proper before performing relocation. Pass '-p [offset]' to
mkimage to enable 'data-position'.
Normal kernel FIT image has data embedded within FIT structure. U-Boot image
for SPL boot has external data. Existence of 'data-offset' can be used to
identify which format is used.
For FIT image with external data, it would be better to align each blob of data
to block(512 byte) for block device, so that we don't need to do the copy when
read the image data in SPL. Pass '-B 0x200' to mkimage to align the FIT
structure and data to 512 byte, other values available for other align size.
Examples
--------
Some example files are available here, showing various scenarios
.. toctree::
:maxdepth: 1
kernel
kernel_fdt
kernel_fdts_compressed
kernel
multi
multi_spl
multi-with-fpga
multi-with-loadables
sec_firmware_ppa
sign-configs
sign-images
uefi
update3
update_uboot
.. sectionauthor:: Marian Balakowicz <m8@semihalf.com>
.. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
|