==========================================================
Author: Marian Balakowicz <m8@semihalf.com>
+External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
1) Introduction
---------------
conforms to bindings defined in this document.
.its - image tree source
-.fit - flattened image tree blob
+.itb - flattened image tree blob
c) Image building procedure
|
o images
| |
- | o image@1 {...}
- | o image@2 {...}
+ | o image-1 {...}
+ | o image-2 {...}
| ...
|
o configurations
- |- default = "conf@1"
+ |- default = "conf-1"
|
- o conf@1 {...}
- o conf@2 {...}
+ o conf-1 {...}
+ o conf-2 {...}
...
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
+ o image-1
|- description = "component sub-image description"
|- data = /incbin/("path/to/data/file.bin")
|- type = "sub-image type name"
|- load = <00000000>
|- entry = <00000000>
|
- o hash@1 {...}
- o hash@2 {...}
+ 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", "ramdisk", "firmware", "script", "filesystem",
- "flat_dt" and others (see uimage_type in common/image.c).
+ "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
property of the root node. Mandatory for types: "standalone" and "kernel".
Optional nodes:
- - hash@1 : Each hash sub-node represents separate hash or checksum
+ - hash-1 : Each hash sub-node represents separate hash or checksum
calculated for node's data according to specified algorithm.
5) Hash nodes
-------------
-o hash@1
+o hash-1
|- algo = "hash or checksum algorithm name"
|- value = [hash or checksum value]
o configurations
|- default = "default configuration sub-node unit name"
|
- o config@1 {...}
- o config@2 {...}
+ o config-1 {...}
+ o config-2 {...}
...
Each configuration has the following structure:
-o config@1
+o config-1
|- description = "configuration description"
|- kernel = "kernel sub-node unit name"
|- ramdisk = "ramdisk sub-node unit name"
- |- fdt = "fdt sub-node unit-name"
+ |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
+ |- fpga = "fpga sub-node unit-name"
|- loadables = "loadables sub-node unit-name"
- ramdisk : Unit name of the corresponding ramdisk image (component image
node of a "ramdisk" type).
- fdt : Unit name of the corresponding fdt blob (component image node of a
- "fdt type").
+ "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.
- setup : Unit name of the corresponding setup binary (used for booting
an x86 kernel). This contains the setup.bin file built by the kernel.
+ - 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.
+ of strings. U-Boot will load each binary at its given start-address and
+ may optionaly invoke additional post-processing steps on this binary based
+ on its component image node type.
The FDT blob is required to properly boot FDT based kernel, so the minimal
configuration for 2.6 FDT kernel is (kernel, fdt) pair.
not* be specified in a configuration node.
-8) Examples
+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
+
+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.
+
+9) Examples
-----------
Please see doc/uImage.FIT/*.its for actual image source files.