doc/usage/fit/source_file_format.rst

.. SPDX-License-Identifier: GPL-2.0+

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 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


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.

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.


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.


'/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.


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"


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.


Examples
--------

Some example files are available here, showing various scenarios

.. toctree::
    :maxdepth: 1

    kernel
    kernel_fdt
    kernel_fdts_compressed
    kernel
    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>