Djam/u-boot
1
0
Fork 0
mirror of https://github.com/u-boot/u-boot.git synced 2025-04-19 11:24:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: Move external FIT docs into the main body

Browse source 
Rather than having this as an addition to the end, move this into the
main body of the spec, rewriting as needed.

Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass 2023-06-23 13:22:11 +01:00 • committed by Heinrich Schuchardt
parent ccdb0e6bbe
commit 9d0750064e
1 changed files with 38 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
doc/usage/fit/source_file_format.rst
View file

@ -81,6 +81,25 @@ 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
--------------------
@ -215,9 +234,6 @@ type
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
@ -238,9 +254,28 @@ compression
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:
@ -478,39 +513,6 @@ 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.
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
--------