u-boot/doc/usage/fit/source_file_format.rst
Simon Glass ccdb0e6bbe doc: Expand FIT tables to include all values
Add tables which include all values for type, algo, arch, algo and
compression.

Signed-off-by: Simon Glass <sjg@chromium.org>
2023-06-23 16:28:13 +02:00

538 lines
17 KiB
ReStructuredText

.. 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.
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 }
==================== ==================
data
Path to the external file which contains this node's binary data.
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
==================== ==================
Conditionally mandatory property
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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.
'/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.
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"
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.
External data
-------------
The above format shows a 'data' property which holds the data for each image.
It is also possible for this data to reside outside the FIT itself. This
allows 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.
In this case the 'data' property is omitted. Instead you can use:
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.
data-size
size of the data in bytes
The 'data-offset' property can be substituted with 'data-position', which
defines an absolute position or address as the offset. This is helpful when
booting U-Boot proper before performing relocation. Pass '-p [offset]' to
mkimage to enable 'data-position'.
Normal kernel FIT image has data embedded within FIT structure. U-Boot image
for SPL boot has external data. Existence of 'data-offset' can be used to
identify which format is used.
For FIT image with external data, it would be better to align each blob of data
to block(512 byte) for block device, so that we don't need to do the copy when
read the image data in SPL. Pass '-B 0x200' to mkimage to align the FIT
structure and data to 512 byte, other values available for other align size.
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 <m8@semihalf.com>
.. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg@chromium.org>