[PATCH v2 02/14] doc: Convert FIT source-file format to rST

Simon Glass sjg at chromium.org
Fri Jun 23 14:22:02 CEST 2023


Move this document and convert it to rST. Make minimal changes, enough
for it to build successfully.

Future patches will tidy this up.

Signed-off-by: Simon Glass <sjg at chromium.org>
---

Changes in v2:
- Update commit message
- Tidy up the diagram alignment in two cases

 doc/usage/fit/index.rst                       |   2 +
 .../fit/source_file_format.rst}               | 126 +++++++++---------
 2 files changed, 65 insertions(+), 63 deletions(-)
 rename doc/{uImage.FIT/source_file_format.txt => usage/fit/source_file_format.rst} (84%)

diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst
index 40f0d1193626..93a962319035 100644
--- a/doc/usage/fit/index.rst
+++ b/doc/usage/fit/index.rst
@@ -9,3 +9,5 @@ doc/uImage.FIT
 
 .. toctree::
     :maxdepth: 1
+
+    source_file_format
diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/usage/fit/source_file_format.rst
similarity index 84%
rename from doc/uImage.FIT/source_file_format.txt
rename to doc/usage/fit/source_file_format.rst
index 269e1fa0b580..bfe8f36c4a0c 100644
--- a/doc/uImage.FIT/source_file_format.txt
+++ b/doc/usage/fit/source_file_format.rst
@@ -64,16 +64,15 @@ 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
 help of standard U-Boot mkimage tool which in turn uses dtc (device tree
 compiler) to produce image tree blob (.itb).  Resulting .itb file is the
-actual binary of a new uImage.
+actual binary of a new uImage::
 
-
-tqm5200.its
-+
-vmlinux.bin.gz	   mkimage + dtc	       xfer to target
-eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> bootm
-tqm5200.dtb			     /|\
-...				      |
-				 'new uImage'
+    tqm5200.its
+    +
+    vmlinux.bin.gz     mkimage + dtc               xfer to target
+    eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> bootm
+    tqm5200.dtb                          /|\
+                                          |
+                                     'new uImage'
 
 	- create .its file, automatically filled-in properties are omitted
 	- call mkimage tool on a .its file
@@ -93,26 +92,25 @@ checking required.
 3) Root node properties
 -----------------------
 
-Root node of the uImage Tree 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 {...}
-      ...
-
+Root node of the uImage Tree 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 uImage
@@ -138,21 +136,21 @@ Root node of the uImage Tree should have the following layout:
 -----------------
 
 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 {...}
-   ...
+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
@@ -202,9 +200,11 @@ the '/images' node should have the following layout:
 5) Hash nodes
 -------------
 
-o hash-1
-  |- algo = "hash or checksum algorithm name"
-  |- value = [hash or checksum value]
+::
+
+    o hash-1
+        |- algo = "hash or checksum algorithm name"
+        |- value = [hash or checksum value]
 
   Mandatory properties:
   - algo : Algorithm name, supported are "crc32", "md5" and "sha1".
@@ -218,14 +218,14 @@ o hash-1
 The 'configurations' node creates convenient, labeled boot configurations,
 which combine together kernel images with their ramdisks and fdt blobs.
 
-The 'configurations' node has has the following structure:
+The 'configurations' node has the following structure::
 
-o configurations
-  |- default = "default configuration sub-node unit name"
-  |
-  o config-1 {...}
-  o config-2 {...}
-  ...
+    o configurations
+        |- default = "default configuration sub-node unit name"
+        |
+        o config-1 {...}
+        o config-2 {...}
+        ...
 
 
   Optional property:
@@ -240,15 +240,15 @@ o configurations
 7) Configuration nodes
 ----------------------
 
-Each configuration has the following structure:
+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"
+    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:
@@ -319,4 +319,4 @@ structure and data to 512 byte, other values available for other align size.
 9) Examples
 -----------
 
-Please see doc/uImage.FIT/*.its for actual image source files.
+Please see `doc/uImage.FIT/*.its` for actual image source files.
-- 
2.41.0.162.gfafddb0af9-goog



More information about the U-Boot mailing list