From: Tom Rini Date: Fri, 23 Jun 2023 18:23:11 +0000 (-0400) Subject: Merge tag 'doc-2023-07-rc6' of https://source.denx.de/u-boot/custodians/u-boot-efi X-Git-Url: http://git.dujemihanovic.xyz/img/static/git-favicon.png?a=commitdiff_plain;h=b2101df305212dd3b98486cbec1d1f15da0832de;p=u-boot.git Merge tag 'doc-2023-07-rc6' of https://source.denx.de/u-boot/custodians/u-boot-efi Pull request doc-2023-07-rc6 * move FIT documentation to HTML * man-pages for the bind, bootm, and unbind commands --- b2101df305212dd3b98486cbec1d1f15da0832de diff --cc doc/usage/fit/source_file_format.rst index 0000000000,1f6c33834b..b2b1e42bd7 mode 000000,100644..100644 --- a/doc/usage/fit/source_file_format.rst +++ b/doc/usage/fit/source_file_format.rst @@@ -1,0 -1,685 +1,684 @@@ + .. SPDX-License-Identifier: GPL-2.0+ + + 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 , its + private key is stored in .key and the certificate is stored in + .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 , its + private key is stored in .key and the certificate is stored in + .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 - kernel + multi + multi_spl + multi-with-fpga + multi-with-loadables + sec_firmware_ppa + sign-configs + sign-images + uefi + update3 + update_uboot + + .. sectionauthor:: Marian Balakowicz + .. sectionauthor:: External data additions, 25/1/16 Simon Glass