[RFC v3 1/2] doc: Remove FIT documentation that is elsewhere

Heinrich Schuchardt xypron.glpk at gmx.de
Mon Jul 8 18:13:37 CEST 2024


On 08.07.24 17:39, Sam Povilus wrote:
> FIT documentation is now a separate project, instead of having a
> duplicate, we should point at the other project.
>
> Signed-off-by: Sam Povilus <sam.povilus at amd.com>
> ---
>   doc/usage/fit/index.rst              |   5 +-
>   doc/usage/fit/source_file_format.rst | 682 +--------------------------
>   2 files changed, 5 insertions(+), 682 deletions(-)
>
> diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst
> index bd25bd30b2..af2e481212 100644
> --- a/doc/usage/fit/index.rst
> +++ b/doc/usage/fit/index.rst
> @@ -4,13 +4,12 @@ Flat Image Tree (FIT)
>   =====================
>
>   U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging
> -images that it it reads and boots. Documentation about FIT is available at
> -doc/uImage.FIT
> +images that it it reads and boots. Documentation about FIT is available in

%s/it it/it/

> +`the Flattened Image Tree project <https://fitspec.osfw.foundation/>`_.
>
>   .. toctree::
>       :maxdepth: 1
>
> -    source_file_format

It would preferable not to remove the line in this patch instead of
adding it in the second patch again.

>       howto
>       x86-fit-boot
>       signature
> diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst
> index b2b1e42bd7..0c44329a82 100644
> --- a/doc/usage/fit/source_file_format.rst
> +++ b/doc/usage/fit/source_file_format.rst
> @@ -3,682 +3,6 @@
>   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.
> -
> -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 at semihalf.com>
> -.. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg at chromium.org>
> +FIT format documentation has been moved to

%s/FIT/The FIT/g

Otherwise looks good to me.

Best regards

Heinrich

> +`a separate project <https://fitspec.osfw.foundation/>`_. Updates to the
> +format/specification should be submitted there.
> \ No newline at end of file



More information about the U-Boot mailing list