[PATCH] doc: FIT image: Clarify format and simplify syntax

[Alexandru Gagniuc]

** Introduction

There are currently four ways to load an OS image with u-boot
  1. SPL -> u-boot -> bootm
  2. SPL blue falcon mode
  3. "Basic" FIT image (CONFIG_LOAD_FIT)
  4. "Full-featured" FIT image (CONFIG_LOAD_FIT_FULL)

These four code paths were developed independently, and share very
little code. (3) and (4), behave very differently, are littered with
special cases. They even have different DTS syntax and properties.

The cause of this divergence is that the FIT format specification
leaves a number of things open to interpretation. The purpose of this
change is to enable the reduction of code size, duplication, and
complexity by updating and streamlining the FIT format.

We are only marginally concerned with backwards compatibility, because
we don't have inter-compatibility. For example, CONFIG_LOAD_FIT is
able to load images that CONFIG_LOAD_FIT_FULL won't. This is a direct
result of the incompatible syntax between the two implementations.

Ideally, these changes would enable "simple" FIT to be a subset of the
"full" fit implementation, and share most code. These changes should
also eliminate the need for falcon mode (although we are not
advocating for the removal of falcon mode at this time).

** Description of changes

 * The "configurations" node is now mandatory

Guessing how to load components based on their "os" and "type" invites
confusion and superfluous heuristics. Instead, require each FIT image
to be explicit on how components should be loaded.

 * Eliminate "ramdisk", "setup", "standalone", and "fpga" properties

Having too many special purpose properties requires special-casing
FIT loading code. When a special property can be handled by another
property, it is redundant.
 - A "ramdisk" is identical to a loadable. Thus ramdisk images should
   be placed under "loadables".
 - A "setup" node can be achieved by using a "kernel" or "firmware"
   property instead.
 - "standalone" is used for u-boot nodes. The correct property to use
   in this case is "firmware".
 - "fpga" is a loadable

 * Prioritize control between "firmware" and "kernel"

"firmware" and "kernel" are special nodes in that control is passed
to the "entry-point" of the image. Both can be present, for example,
an OP-TEE firmware with a linux kernel. When both are present,
control is passed to the "firmware" image.

** Further generalizations (not included herein)

The "firmware" and "kernel" properties could be generalized as a
"next-boot-stage", or similar name. This "next" stage would be special
in that it is both executable, and is the stage that is passed
control. For example, "next-stage" could be an op-tee image, with
linux as a loadable, or a u-boot image.

Signed-off-by: Alexandru Gagniuc <mr.nuke.me at gmail.com>
---
 doc/uImage.FIT/source_file_format.txt | 33 ++++++++++++---------------
 1 file changed, 14 insertions(+), 19 deletions(-)

diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt
index 884a58456f..2e7e11747c 100644
--- a/doc/uImage.FIT/source_file_format.txt
+++ b/doc/uImage.FIT/source_file_format.txt
@@ -126,12 +126,10 @@ Root node of the uImage Tree should have the following layout:
     load addresses supplied within sub-image nodes. May be omitted when no
     entry or load addresses are used.
 
-  Mandatory node:
+  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.
-
-  Optional node:
   - configurations : Contains a set of available configuration nodes and
     defines a default configuration.
 
@@ -169,8 +167,8 @@ the '/images' node should have the following layout:
     to "none".
 
   Conditionally mandatory property:
-  - os : OS name, mandatory for types "kernel" and "ramdisk". Valid OS names
-    are: "openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix",
+  - 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",
@@ -179,10 +177,13 @@ the '/images' node should have the following layout:
     "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200",
     "sandbox".
   - entry : entry point address, address size is determined by
-    '#address-cells' property of the root node. Mandatory for for types:
-    "standalone" and "kernel".
+    '#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: "standalone" and "kernel".
+    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.
 
   Optional nodes:
   - hash-1 : Each hash sub-node represents separate hash or checksum
@@ -205,9 +206,8 @@ o hash-1
 6) '/configurations' node
 -------------------------
 
-The 'configurations' node is optional. If present, it allows to create a
-convenient, labeled boot configurations, which combine together kernel images
-with their ramdisks and fdt blobs.
+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:
 
@@ -236,27 +236,22 @@ Each configuration has the following structure:
 o config-1
   |- description = "configuration description"
   |- kernel = "kernel sub-node unit name"
-  |- ramdisk = "ramdisk sub-node unit name"
   |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
-  |- fpga = "fpga sub-node unit-name"
   |- loadables = "loadables sub-node unit-name"
   |- compatible = "vendor,board-style device tree compatible string"
 
 
   Mandatory properties:
   - description : Textual configuration description.
-  - kernel : Unit name of the corresponding kernel image (image sub-node of a
-    "kernel" type).
+  - 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:
-  - ramdisk : Unit name of the corresponding ramdisk image (component image
-    node of a "ramdisk" type).
   - 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.
-  - setup : Unit name of the corresponding setup binary (used for booting
-    an x86 kernel). This contains the setup.bin file built by the kernel.
   - 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
-- 
2.26.2