[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