[PATCH 3/9] doc: Reformat the FIT documentation to make it nicer
Simon Glass
sjg at chromium.org
Thu Jun 22 22:21:10 CEST 2023
Fix up headings and tables to read better.
Signed-off-by: Simon Glass <sjg at chromium.org>
---
doc/usage/fit/source_file_format.rst | 255 ++++++++++++++++++---------
1 file changed, 172 insertions(+), 83 deletions(-)
diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst
index 9f4688db2a15..4d2ea0a7b158 100644
--- a/doc/usage/fit/source_file_format.rst
+++ b/doc/usage/fit/source_file_format.rst
@@ -1,11 +1,8 @@
U-Boot new uImage source file format (bindings definition)
==========================================================
-Author: Marian Balakowicz <m8 at semihalf.com>
-External data additions, 25/1/16 Simon Glass <sjg at chromium.org>
-
-1) Introduction
----------------
+Introduction
+------------
Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
booting method which requires that hardware description is available to the
@@ -30,16 +27,18 @@ All those factors combined clearly show that there is a need for new, more
flexible, multi component uImage format.
-2) New uImage format assumptions
---------------------------------
+New uImage format assumptions
+-----------------------------
-a) Implementation
+Implementation
+~~~~~~~~~~~~~~
Libfdt has been selected for the new uImage format implementation as (1) it
provides needed functionality, (2) is actively maintained and developed and
(3) increases code reuse as it is already part of the U-Boot source tree.
-b) Terminology
+Terminology
+~~~~~~~~~~~
This document defines new uImage structure by providing FDT bindings for new
uImage internals. Bindings are defined from U-Boot perspective, i.e. describe
@@ -50,15 +49,20 @@ hashes) will need to be filled in automatically by the U-Boot mkimage tool.
To avoid confusion with the kernel FDT the following naming convention is
proposed for the new uImage format related terms:
-FIT - Flattened uImage Tree
+FIT
+ Flattened uImage Tree
FIT is formally a flattened device tree (in the libfdt meaning), which
conforms to bindings defined in this document.
-.its - image tree source
-.itb - flattened image tree blob
+.its
+ image tree source
+
+.itb
+ flattened image tree blob
-c) Image building procedure
+Image building procedure
+~~~~~~~~~~~~~~~~~~~~~~~~
The following picture shows how the new uImage is prepared. Input consists of
image source file (.its) and a set of data files. Image is created with the
@@ -74,14 +78,20 @@ actual binary of a new uImage::
... |
'new uImage'
- - 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 uImage) is uploaded onto the target and used therein
+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 uImage) is uploaded onto the target and used therein
-d) Unique identifiers
+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
@@ -89,8 +99,8 @@ is used as it's identifier as it assures uniqueness without additional
checking required.
-3) Root node properties
------------------------
+Root node properties
+--------------------
Root node of the uImage Tree should have the following layout::
@@ -113,28 +123,42 @@ Root node of the uImage Tree should have the following layout::
...
- Optional property:
- - description : Textual description of the uImage
+Optional property
+~~~~~~~~~~~~~~~~~
- Mandatory property:
- - timestamp : Last image modification time being counted in seconds since
+description
+ Textual description of the uImage
+
+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
+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
+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
+
+configurations
+ Contains a set of available configuration nodes and
defines a default configuration.
-4) '/images' node
------------------
+'/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::
@@ -153,53 +177,89 @@ the '/images' node should have the following layout::
o hash-2 {...}
...
- Mandatory properties:
- - description : Textual description of the component sub-image
- - type : Name of component sub-image type, supported types are:
+Mandatory properties
+~~~~~~~~~~~~~~~~~~~~
+
+description
+ Textual description of the component sub-image
+
+type
+ Name of component sub-image type, supported types are:
+
"standalone", "kernel", "kernel_noload", "ramdisk", "firmware", "script",
"filesystem", "flat_dt" and others (see uimage_type in common/image.c).
- - data : Path to the external file which contains this node's binary data.
- - compression : Compression used by included data. Supported compressions
+
+data
+ Path to the external file which contains this node's binary data.
+
+compression
+ Compression used by included data. Supported compressions
are "gzip" and "bzip2". If no compression is used compression property
should be set to "none". If the data is compressed but it should not be
uncompressed by U-Boot (e.g. compressed ramdisk), this should also be set
to "none".
- Conditionally mandatory property:
- - os : OS name, mandatory for types "kernel". Valid OS names are:
+Conditionally mandatory property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+os
+ OS name, mandatory for types "kernel". Valid OS names are:
"openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix",
"solaris", "irix", "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx",
"u-boot", "rtems", "unity", "integrity".
- - arch : Architecture name, mandatory for types: "standalone", "kernel",
+
+arch
+ Architecture name, mandatory for types: "standalone", "kernel",
"firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha",
"arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc",
"sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200",
"sandbox".
- - entry : entry point address, address size is determined by
+
+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'
+
+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.
+
+compatible
+ compatible method for loading image.
Mandatory for types: "fpga", and images that do not specify a load address.
Supported compatible methods:
- "u-boot,fpga-legacy" - the 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
+
+ "u-boot,fpga-legacy"
+ the 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
+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.
-5) Hash nodes
--------------
+Hash nodes
+----------
::
@@ -207,14 +267,18 @@ the '/images' node should have the following layout::
|- algo = "hash or checksum algorithm name"
|- value = [hash or checksum value]
- Mandatory properties:
- - algo : Algorithm name, supported are "crc32", "md5" and "sha1".
- - value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes
- long.
+Mandatory properties
+~~~~~~~~~~~~~~~~~~~~
+
+algo
+ Algorithm name, supported are "crc32", "md5" and "sha1".
+
+value
+ Actual checksum or hash value, correspondingly 4, 16 or 20 bytes long.
-6) '/configurations' node
--------------------------
+'/configurations' node
+----------------------
The 'configurations' node creates convenient, labeled boot configurations,
which combine together kernel images with their ramdisks and fdt blobs.
@@ -229,17 +293,21 @@ The 'configurations' node has has the following structure::
...
- Optional property:
- - default : Selects one of the configuration sub-nodes as a default
- configuration.
+Optional property
+~~~~~~~~~~~~~~~~~
- Mandatory nodes:
- - configuration-sub-node-unit-name : At least one of the configuration
- sub-nodes is required.
+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.
-7) Configuration nodes
-----------------------
+
+Configuration nodes
+-------------------
Each configuration has the following structure::
@@ -252,27 +320,43 @@ Each configuration has the following structure::
|- 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
+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
+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
+
+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
+
+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
+
+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
+
+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
@@ -287,8 +371,8 @@ Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
not* be specified in a configuration node.
-8) External data
-----------------
+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
@@ -298,10 +382,12 @@ 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
+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
+
+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
@@ -317,7 +403,10 @@ 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.
-9) Examples
------------
+Examples
+--------
Please see `doc/uImage.FIT/*.its` for actual image source files.
+
+.. sectionauthor:: Marian Balakowicz <m8 at semihalf.com>
+.. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg at chromium.org>
--
2.41.0.162.gfafddb0af9-goog
More information about the U-Boot
mailing list