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).
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
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
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.
FIT is normally built initially with image data in the 'data' property of each image node. It is also possible for this data to reside outside the FIT itself. This allows the 'FDT' part of 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.
External FITs use 'data-offset' or 'data-position' instead of 'data'.
The mkimage tool can convert a FIT to use external data using the -E argument, optionally using -p to specific a fixed position.
It is often desirable to align each image to a block size or cache-line size (e.g. 512 bytes), so that there is no need to copy it to an aligned address when reading the image data. The mkimage tool provides a -B argument to support this.
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 {...}
...
- description
- Textual description of the FIT
- timestamp
- Last image modification time being counted in seconds since 1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
- #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.
- 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.
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 {...}
...
- description
- Textual description of the component sub-image
- type
Name of component sub-image type. Supported types are:
Sub-image type Meaning invalid Invalid Image aisimage Davinci AIS image atmelimage ATMEL ROM-Boot Image copro Coprocessor Image} fdt_legacy legacy Image with Flat Device Tree filesystem Filesystem Image firmware Firmware firmware_ivt Firmware with HABv4 IVT } flat_dt Flat Device Tree fpga FPGA Image } gpimage TI Keystone SPL Image imx8image NXP i.MX8 Boot Image imx8mimage NXP i.MX8M Boot Image imximage Freescale i.MX Boot Image kernel Kernel Image kernel_noload Kernel Image (no loading done) kwbimage Kirkwood Boot Image lpc32xximage LPC32XX Boot Image mtk_image MediaTek BootROM loadable Image } multi Multi-File Image mxsimage Freescale MXS Boot Image omapimage TI OMAP SPL With GP CH pblimage Freescale PBL Boot Image pmmc TI Power Management Micro-Controller Firmware ramdisk RAMDisk Image rkimage Rockchip Boot Image } rksd Rockchip SD Boot Image } rkspi Rockchip SPI Boot Image } script Script socfpgaimage Altera SoCFPGA CV/AV preloader socfpgaimage_v1 Altera SoCFPGA A10 preloader spkgimage Renesas SPKG Image } standalone Standalone Program stm32image STMicroelectronics STM32 Image } sunxi_egon Allwinner eGON Boot Image } sunxi_toc0 Allwinner TOC0 Boot Image } tee Trusted Execution Environment Image ublimage Davinci UBL image vybridimage Vybrid Boot Image x86_setup x86 setup.bin zynqimage Xilinx Zynq Boot Image } zynqmpbif Xilinx ZynqMP Boot Image (bif) } zynqmpimage Xilinx ZynqMP Boot Image } - compression
Compression used by included data. If no compression is used, the compression property should be set to "none". If the data is compressed but it should not be uncompressed by the loader (e.g. compressed ramdisk), this should also be set to "none".
Supported compression types are:
Compression type Meaning none uncompressed bzip2 bzip2 compressed gzip gzip compressed lz4 lz4 compressed lzma lzma compressed lzo lzo compressed zstd zstd compressed - data-size
- size of the data in bytes
- data
- Path to the external file which contains this node's binary data. Within the FIT this is the contents of the file. This is mandatory unless external data is used.
- 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. This is mandatory if external data is used, with an offset.
- data-position
- Machine address at which the data is to be found. This is a fixed address not relative to the loading of the FIT. This is mandatory if external data used with a fixed address.
- os
OS name, mandatory for types "kernel". Valid OS names are:
OS name Meaning invalid Invalid OS 4_4bsd 4_4BSD arm-trusted-firmware ARM Trusted Firmware dell Dell efi EFI Firmware esix Esix freebsd FreeBSD integrity INTEGRITY irix Irix linux Linux ncr NCR netbsd NetBSD openbsd OpenBSD openrtos OpenRTOS opensbi RISC-V OpenSBI ose Enea OSE plan9 Plan 9 psos pSOS qnx QNX rtems RTEMS sco SCO solaris Solaris svr4 SVR4 tee Trusted Execution Environment u-boot U-Boot vxworks VxWorks - arch
Architecture name, mandatory for types: "standalone", "kernel", "firmware", "ramdisk" and "fdt". Valid architecture names are:
Architecture type Meaning invalid Invalid ARCH alpha Alpha arc ARC arm64 AArch64 arm ARM avr32 AVR32 blackfin Blackfin ia64 IA64 m68k M68K microblaze MicroBlaze mips64 MIPS 64 Bit mips MIPS nds32 NDS32 nios2 NIOS II or1k OpenRISC 1000 powerpc PowerPC ppc PowerPC riscv RISC-V s390 IBM S390 sandbox Sandbox sh SuperH sparc64 SPARC 64 Bit sparc SPARC x86_64 AMD x86_64 x86 Intel x86 xtensa Xtensa - 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:
Compatible string Meaning u-boot,fpga-legacy 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.
- signature-1
- Each signature sub-node represents separate signature calculated for node's data according to specified algorithm.
o hash-1
|- algo = "hash or checksum algorithm name"
|- value = [hash or checksum value]
- algo
Algorithm name. Supported algoriths and their value sizes are:
Sub-image type Size (bytes) Meaning crc16-ccitt 2 Cyclic Redundancy Check 16-bit (Consultative Committee for International Telegraphy and Telephony) crc32 4 Cyclic Redundancy Check 32-bit md5 16 Message Digest 5 (MD5) sha1 20 Secure Hash Algorithm 1 (SHA1) sha256 32 Secure Hash Algorithm 2 (SHA256) sha384 48 Secure Hash Algorithm 2 (SHA384) sha512 64 Secure Hash Algorithm 2 (SHA512) - value
- Actual checksum or hash value.
o signature-1
|- algo = "algorithm name"
|- key-name-hint = "key name"
|- value = [hash or checksum value]
FIT Algorithm:
- algo
Algorithm name. Supported algoriths and their value sizes are shown below. Note that the hash is specified separately from the signing algorithm, so it is possible to mix and match any SHA algorithm with any signing algorithm. The size of the signature relates to the signing algorithm, not the hash, since it is the hash that is signed.
Sub-image type Size (bytes) Meaning sha1,rsa2048 256 SHA1 hash signed with 2048-bit Rivest–Shamir–Adleman algorithm sha1,rsa3072 384 SHA1 hash signed with 2048-bit RSA sha1,rsa4096 512 SHA1 hash signed with 2048-bit RSA sha1,ecdsa256 32 SHA1 hash signed with 256-bit Elliptic Curve Digital Signature Algorithm sha256,... sha384,... sha512,... - key-name-hint
- Name of key to use for signing. The keys will normally be in a single directory (parameter -k to mkimage). For a given key <name>, its private key is stored in <name>.key and the certificate is stored in <name>.crt.
- sign-images
- A list of images to sign, each being a property of the conf node that contains then. The default is "kernel,fdt" which means that these two images will be looked up in the config and signed if present. This is used by mkimage to determine which images to sign.
The following properies are added as part of signing, and are mandatory:
- value
- Actual signature value. This is added by mkimage.
- hashed-nodes
A list of nodes which were hashed by the signer. Each is a string - the full path to node. A typical value might be:
hashed-nodes = "/", "/configurations/conf-1", "/images/kernel", "/images/kernel/hash-1", "/images/fdt-1", "/images/fdt-1/hash-1";- hashed-strings
- The start and size of the string region of the FIT that was hashed. The start is normally 0, indicating the first byte of the string table. The size indicates the number of bytes hashed as part of signing.
The following properies are added as part of signing, and are optional:
- timestamp
- Time when image was signed (standard Unix time_t format)
- signer-name
- Name of the signer (e.g. "mkimage")
- signer-version
- Version string of the signer (e.g. "2013.01")
- comment
- Additional information about the signer or image
- padding
- The padding algorithm, it may be pkcs-1.5 or pss, if no value is provided we assume pkcs-1.5
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 {...}
...
- default
- Selects one of the configuration sub-nodes as a default configuration.
- configuration-sub-node-unit-name
- At least one of the configuration sub-nodes is required.
- signature-1
- Each signature sub-node represents separate signature calculated for the configuration according to specified algorithm.
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"
o signature-1 {...}
- 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.
- 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.
o signature-1
|- algo = "algorithm name"
|- key-name-hint = "key name"
|- sign-images = "path1", "path2";
|- value = [hash or checksum value]
|- hashed-strings = <0 len>
- algo
- See FIT Algorithm.
- key-name-hint
- Name of key to use for signing. The keys will normally be in a single directory (parameter -k to mkimage). For a given key <name>, its private key is stored in <name>.key and the certificate is stored in <name>.crt.
The following properies are added as part of signing, and are mandatory:
- value
- Actual signature value. This is added by mkimage.
The following properies are added as part of signing, and are optional:
- timestamp
- Time when image was signed (standard Unix time_t format)
- signer-name
- Name of the signer (e.g. "mkimage")
- signer-version
- Version string of the signer (e.g. "2013.01")
- comment
- Additional information about the signer or image
- padding
- The padding algorithm, it may be pkcs-1.5 or pss, if no value is provided we assume pkcs-1.5
Some example files are available here, showing various scenarios
.. toctree::
:maxdepth: 1
kernel
kernel_fdt
kernel_fdts_compressed
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>