mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-12-14 07:13:03 +00:00
ccdb0e6bbe
Add tables which include all values for type, algo, arch, algo and compression. Signed-off-by: Simon Glass <sjg@chromium.org>
538 lines
17 KiB
ReStructuredText
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>
|