doc/uImage.FIT/source_file_format.txt - filogic/uboot - Gitiles

 U-Boot new uImage source file format (bindings definition)
 ==========================================================

 Author: Marian Balakowicz <m8@semihalf.com>
 External data additions, 25/1/16 Simon Glass <sjg@chromium.org>

 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.

 However, U-Boot needs to support both techniques to provide backward
 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.
 Single binary header 'struct image_header' is not flexible enough to cover all
 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
 (3) increases code reuse as it is already part of the U-Boot source tree.

 b) Terminology

 This document defines new uImage structure by providing FDT bindings for new
 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
 perspective may be simpler, as some of the properties (like timestamps and
 hashes) will need to be filled in automatically by the U-Boot mkimage tool.

 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
 .itb	- flattened image tree blob

 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
 help of standard U-Boot mkimage tool which in turn uses dtc (device tree
 compiler) to produce image tree blob (.itb).  Resulting .itb file is the
 actual binary of a new uImage.


 tqm5200.its
 +
 vmlinux.bin.gz	   mkimage + dtc	       xfer to target
 eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> bootm
 tqm5200.dtb			     /|\
 ...				      |
 				 'new uImage'

 	- 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
     | |
     | o image-1 {...}
     | o image-2 {...}
     | ...
     |
     o configurations
       |- default = "conf-1"
       |
       o conf-1 {...}
       o conf-2 {...}
       ...


   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.

   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.


 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:

  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.
     To use the generic fpga loading routine, use "u-boot,fpga-legacy".

   Optional nodes:
   - 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
   |- 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
 -------------------------

 The 'configurations' node creates convenient, labeled boot configurations,
 which combine together kernel images with their ramdisks and fdt blobs.

 The 'configurations' node has 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.


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


 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.

 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.

 9) Examples
 -----------

 Please see doc/uImage.FIT/*.its for actual image source files.
	U-Boot new uImage source file format (bindings definition)
	==========================================================

	Author: Marian Balakowicz <m8@semihalf.com>
	External data additions, 25/1/16 Simon Glass <sjg@chromium.org>

	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.

	However, U-Boot needs to support both techniques to provide backward
	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.
	Single binary header 'struct image_header' is not flexible enough to cover all
	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
	(3) increases code reuse as it is already part of the U-Boot source tree.

	b) Terminology

	This document defines new uImage structure by providing FDT bindings for new
	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
	perspective may be simpler, as some of the properties (like timestamps and
	hashes) will need to be filled in automatically by the U-Boot mkimage tool.

	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
	.itb - flattened image tree blob

	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
	help of standard U-Boot mkimage tool which in turn uses dtc (device tree
	compiler) to produce image tree blob (.itb). Resulting .itb file is the
	actual binary of a new uImage.


	tqm5200.its
	+
	vmlinux.bin.gz mkimage + dtc xfer to target
	eldk-4.2-ramdisk --------------> tqm5200.itb --------------> bootm
	tqm5200.dtb /\|\
	... \|
	'new uImage'

	- 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
	\| \|
	\| o image-1 {...}
	\| o image-2 {...}
	\| ...
	\|
	o configurations
	\|- default = "conf-1"
	\|
	o conf-1 {...}
	o conf-2 {...}
	...


	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.

	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.


	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:

	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.
	To use the generic fpga loading routine, use "u-boot,fpga-legacy".

	Optional nodes:
	- 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
	\|- 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
	-------------------------

	The 'configurations' node creates convenient, labeled boot configurations,
	which combine together kernel images with their ramdisks and fdt blobs.

	The 'configurations' node has 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.


	7) 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"
	\|- 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.
	- 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.


	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.

	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.

	9) Examples
	-----------

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