random-mirrors/smaeul-u-boot
1
0
Fork 0
mirror of https://github.com/smaeul/u-boot.git synced 2025-10-29 19:18:22 +00:00
Code Issues Packages Projects Releases Wiki Activity
smaeul-u-boot/doc/usage/fit/source_file_format.rst
Tom Rini b2101df305 Pull request doc-2023-07-rc6 
* move FIT documentation to HTML
 * man-pages for the bind, bootm, and unbind commands
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCAAdFiEEbcT5xx8ppvoGt20zxIHbvCwFGsQFAmSV3UIACgkQxIHbvCwF
 GsRKGhAAh3njwDmic/Ai7Q6naJ/kDJmCrQiNefmeMObmPX9T+5ct9I7WY76f0fhZ
 iA9NmxoSsrly2zREnmT54OhFCpQup2WRh9Tp9ljcw/lqsasfg0ea8iQkGsIPxgrV
 8E8W7v3Y0RyLtyZcKZuKIE5oqYq+fYRTB5cWTUV6R50XySJ8kvffF4wxlqlGKnM0
 qr7WLE+yK4XKAMfJmtrUkieEzSVcJnqRiVYqhO5wJN5CNlyYGluLPM17qgW+lef/
 TCPgW4ZKxNJCy7y82uteaVIx4On6BJ0SHHJUQBVWPWvhUMGYsvhr1IDhxQyyfXeL
 NL8RtncnzNriSY3qR/mysSUr2iJQEN0Yk/Cgh5SehJ/5t6+i19cT+axAyIDD2bMf
 RxOIUgUtEmevFw+Ump/OiPSOm13MdYYpaI40WAgoCvWHnaSE4NPitRqdEg8ZrJL+
 Cw6EScUdztC3tLau13xbdVCHeF/9nRWCeG9JvfV5/iSmrvgNjnkV3IaiGoh/9edw
 hLhig57AQsYdQRrrMU+Z5Wl0HwfCMqnM4uR/j4bJovN12Ns3QU3NElvzWD1ticjU
 b1Lv4HR7/Wm9O+91Gi76NrnW4S2Kl5FlLXfyyGg1WNgaMDmXBGiUU9pMPuo7ekdK
 kogWPQkcZEA3DNsQgrsktTEGubjT2F4zQI3uSyKASdUvPrFCCi8=
 =WVuv
 -----END PGP SIGNATURE-----

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
2023-06-23 14:31:55 -04:00

685 lines
22 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

.. 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 <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>
Reference in New Issue View Git Blame Copy Permalink