source_file_format.txt 12.1 KB
Newer Older
Bin Meng's avatar
Bin Meng committed
1
U-Boot new uImage source file format (bindings definition)
2
3
4
==========================================================

Author: Marian Balakowicz <m8@semihalf.com>
5
External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
6
7
8
9
10
11
12
13
14
15
16
17

1) Introduction
---------------

Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
booting method which requires that hardware description is available to the
kernel in the form of Flattened Device Tree.

Booting with a Flattened Device Tree is much more flexible and is intended to
replace direct passing of 'struct bd_info' which was used to boot pre-FDT
kernels.

Bin Meng's avatar
Bin Meng committed
18
However, U-Boot needs to support both techniques to provide backward
19
20
21
22
23
24
25
compatibility for platforms which are not FDT ready. Number of elements
playing role in the booting process has increased and now includes the FDT
blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed
in the system memory and passed to bootm as a arguments. Some of them may be
missing: FDT is not present for legacy platforms, ramdisk is always optional.
Additionally, old uImage format has been extended to support multi sub-images
but the support is limited by simple format of the legacy uImage structure.
26
Single binary header 'struct legacy_img_hdr' is not flexible enough to cover all
27
28
29
30
31
32
33
34
35
36
37
38
39
possible scenarios.

All those factors combined clearly show that there is a need for new, more
flexible, multi component uImage format.


2) New uImage format assumptions
--------------------------------

a) Implementation

Libfdt has been selected for the new uImage format implementation as (1) it
provides needed functionality, (2) is actively maintained and developed and
Bin Meng's avatar
Bin Meng committed
40
(3) increases code reuse as it is already part of the U-Boot source tree.
41
42
43
44

b) Terminology

This document defines new uImage structure by providing FDT bindings for new
Bin Meng's avatar
Bin Meng committed
45
46
uImage internals. Bindings are defined from U-Boot perspective, i.e. describe
final form of the uImage at the moment when it reaches U-Boot. User
47
perspective may be simpler, as some of the properties (like timestamps and
Bin Meng's avatar
Bin Meng committed
48
hashes) will need to be filled in automatically by the U-Boot mkimage tool.
49
50
51
52
53
54
55
56
57
58

To avoid confusion with the kernel FDT the following naming convention is
proposed for the new uImage format related terms:

FIT	- Flattened uImage Tree

FIT is formally a flattened device tree (in the libfdt meaning), which
conforms to bindings defined in this document.

.its	- image tree source
59
.itb	- flattened image tree blob
60
61
62
63
64

c) Image building procedure

The following picture shows how the new uImage is prepared. Input consists of
image source file (.its) and a set of data files. Image is created with the
Bin Meng's avatar
Bin Meng committed
65
help of standard U-Boot mkimage tool which in turn uses dtc (device tree
66
compiler) to produce image tree blob (.itb).  Resulting .itb file is the
67
68
69
70
71
actual binary of a new uImage.


tqm5200.its
+
72
vmlinux.bin.gz	   mkimage + dtc	       xfer to target
73
eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> bootm
74
75
76
tqm5200.dtb			     /|\
...				      |
				 'new uImage'
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

	- 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 uImage) is uploaded onto the target and used therein


d) 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.


3) Root node properties
-----------------------

Root node of the uImage Tree should have the following layout:

/ o image-tree
    |- description = "image description"
    |- timestamp = <12399321>
    |- #address-cells = <1>
    |
    o images
    | |
105
106
    | o image-1 {...}
    | o image-2 {...}
107
108
109
    | ...
    |
    o configurations
110
      |- default = "conf-1"
111
      |
112
113
      o conf-1 {...}
      o conf-2 {...}
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
      ...


  Optional property:
  - description : Textual description of the uImage

  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.

129
  Mandatory nodes:
130
131
132
133
134
135
136
137
138
139
140
141
142
  - 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.


4) '/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:

143
 o image-1
144
145
146
147
148
149
150
151
152
   |- 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>
   |
153
154
   o hash-1 {...}
   o hash-2 {...}
155
156
157
158
159
   ...

  Mandatory properties:
  - description : Textual description of the component sub-image
  - type : Name of component sub-image type, supported types are:
160
161
    "standalone", "kernel", "kernel_noload", "ramdisk", "firmware", "script",
    "filesystem", "flat_dt" and others (see uimage_type in common/image.c).
162
163
164
  - 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
165
166
167
    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".
168
169

  Conditionally mandatory property:
170
171
  - os : OS name, mandatory for types "kernel". Valid OS names 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
175
176
  - 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",
177
178
    "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200",
    "sandbox".
179
  - entry : entry point address, address size is determined by
180
181
    '#address-cells' property of the root node.
    Mandatory for types: "firmware", and "kernel".
182
  - load : load address, address size is determined by '#address-cells'
183
184
185
186
    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.
187
188
189
190
    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.
191
192
    "u-boot,zynqmp-fpga-enc" - encrypted FPGA bitstream for Xilinx Zynq
    UltraScale+ (ZynqMP) device.
193
194
195
  - phase : U-Boot phase for which the image is intended.
    "spl" - image is an SPL image
    "u-boot" - image is a U-Boot image
196
197

  Optional nodes:
198
  - hash-1 : Each hash sub-node represents separate hash or checksum
199
200
201
202
203
204
    calculated for node's data according to specified algorithm.


5) Hash nodes
-------------

205
o hash-1
206
207
208
209
210
211
212
213
214
215
216
217
  |- 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.


6) '/configurations' node
-------------------------

218
219
The 'configurations' node creates convenient, labeled boot configurations,
which combine together kernel images with their ramdisks and fdt blobs.
220
221
222
223
224
225

The 'configurations' node has has the following structure:

o configurations
  |- default = "default configuration sub-node unit name"
  |
226
227
  o config-1 {...}
  o config-2 {...}
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
  ...


  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.


7) Configuration nodes
----------------------

Each configuration has the following structure:

245
o config-1
246
247
  |- description = "configuration description"
  |- kernel = "kernel sub-node unit name"
Pantelis Antoniou's avatar
Pantelis Antoniou committed
248
  |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
249
  |- loadables = "loadables sub-node unit-name"
250
  |- script = "
251
  |- compatible = "vendor,board-style device tree compatible string"
252
253
254
255


  Mandatory properties:
  - description : Textual configuration description.
256
257
258
  - 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.
259
260
261

  Optional properties:
  - fdt : Unit name of the corresponding fdt blob (component image node of a
Pantelis Antoniou's avatar
Pantelis Antoniou committed
262
263
264
    "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.
265
266
  - fpga : Unit name of the corresponding fpga bitstream blob
    (component image node of a "fpga type").
267
268
  - loadables : Unit name containing a list of additional binaries to be
    loaded at their given locations.  "loadables" is a comma-separated list
269
    of strings. U-Boot will load each binary at its given start-address and
270
    may optionally invoke additional post-processing steps on this binary based
271
    on its component image node type.
272
273
  - script : The image to use when loading a U-Boot script (for use with the
    source command).
274
275
276
277
278
279
  - 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.
280
281
282
283
284
285
286
287
288

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.


289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
8) 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

305
306
The 'data-offset' property can be substituted with 'data-position', which
defines an absolute position or address as the offset. This is helpful when
307
308
booting U-Boot proper before performing relocation. Pass '-p [offset]' to
mkimage to enable 'data-position'.
309

310
311
312
313
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.

314
315
316
317
318
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.

319
9) Examples
320
321
-----------

322
Please see doc/uImage.FIT/*.its for actual image source files.