-.. SPDX-License-Identifier: GPL-2.0+
+.. SPDX-License-Identifier: GPL-2.0-or-later
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.
-
-
-External data
-~~~~~~~~~~~~~
-
-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.
-
-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:
-
- ==================== ==================
- 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 Device Image (bitstream file, vendor specific)
- 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
- ==================== ==================
-
-
-Conditionally mandatory property
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-data-size
- Size of the data in bytes. This is mandatory if external data is used.
-
-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.
-
-
-Hash nodes
-----------
-
-::
-
- o hash-1
- |- algo = "hash or checksum algorithm name"
- |- value = [hash or checksum value]
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-Image-signature nodes
----------------------
-
-::
-
- o signature-1
- |- algo = "algorithm name"
- |- key-name-hint = "key name"
- |- value = [hash or checksum value]
-
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-_`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
-
-
-'/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.
-
-Optional nodes
-~~~~~~~~~~~~~~
-
-signature-1
- Each signature sub-node represents separate signature
- calculated for the configuration according to specified algorithm.
-
-
-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"
- o signature-1 {...}
-
-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.
-
-Configuration-signature nodes
------------------------------
-
-::
-
- o signature-1
- |- algo = "algorithm name"
- |- key-name-hint = "key name"
- |- sign-images = "path1", "path2";
- |- value = [hash or checksum value]
- |- hashed-strings = <0 len>
-
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-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
-
-
-
-Examples
---------
-
-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>
+FIT format documentation has been moved to
+`a separate project <https://fitspec.osfw.foundation/>`_. Updates to the
+format/specification should be submitted there.
projects / u-boot.git / commitdiff
