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

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@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@semihalf.com -.. sectionauthor:: External data additions, 25/1/16 Simon Glass sjg@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