[PATCH v2 11/14] doc: Move external FIT docs into the main body

[Simon Glass]

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 at chromium.org>
---

(no changes since v1)

 doc/usage/fit/source_file_format.rst | 74 ++++++++++++++--------------
 1 file changed, 38 insertions(+), 36 deletions(-)

diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst
index 1c72230c0604..f1cc1bc4931c 100644
--- a/doc/usage/fit/source_file_format.rst
+++ b/doc/usage/fit/source_file_format.rst
@@ -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
 --------
 
-- 
2.41.0.162.gfafddb0af9-goog