Message ID | 20240708153941.1045588-2-sam.povilus@amd.com |
---|---|
State | Superseded, archived |
Delegated to: | Heinrich Schuchardt |
Headers | show |
Series | FIT documentation link vs copy | expand |
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
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 +`the Flattened Image Tree project <https://fitspec.osfw.foundation/>`_. .. toctree:: :maxdepth: 1 - source_file_format 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 +`a separate project <https://fitspec.osfw.foundation/>`_. Updates to the +format/specification should be submitted there. \ No newline at end of file
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(-)