Am 1. Juli 2024 21:52:12 MESZ schrieb Sam Povilus sam.povilus@amd.com:
On 6/18/2024 12:03 AM, Heinrich Schuchardt wrote:
Caution: This message originated from an External Source. Use proper caution when opening attachments, clicking links, or responding.
On 6/17/24 22:20, 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 | 14 +- doc/usage/fit/source_file_format.rst | 682 +-------------------------- 2 files changed, 5 insertions(+), 691 deletions(-)
diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst index bd25bd30b2..12a8c6fb16 100644 --- a/doc/usage/fit/index.rst +++ b/doc/usage/fit/index.rst @@ -4,16 +4,6 @@ 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 +`the Flattened Image Tree project https://fitspec.osfw.foundation/`_.
-.. toctree:: - :maxdepth: 1
- source_file_format
This is the only entry to be replaced by the external link.
- howto - x86-fit-boot - signature - verified-boot - beaglebone_vboot - overlay-fdt-boot
All of these files are staying around and must be kept linked.
I would argue that if this list is not being maintained, it is better to remove it than to try to keep it up to date. Maybe that should be a separate patch though?
Users will not be able to find the documents in the html documentation if you remove the links. Please, do not remove links for existing documents.
Best regards
Heinrich
Many links are missing here. The complete list should be:
beaglebone_vboot howto kernel_fdt kernel_fdts_compressed kernel multi multi_spl multi-with-fpga multi-with-loadables overlay-fdt-boot sec_firmware_ppa signature sign-configs sign-images uefi update3 update_uboot verified-boot x86-fit-boot
These other documents should be carefully redacted. E.g. howto.rst refers to the FIT file format as "the new uImage format".
I agree that it would be nice to take a pass through all this documentation and clean it up, but I think there is value in doing small cleanups as one has time.
Best regards
Heinrich
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 +`a separate project https://fitspec.osfw.foundation/`_. Updates to the +format/specification should be submitted there. \ No newline at end of file