Add explicit support for multi-step loading

There are cases where multiple FITs must be loaded to complete a boot,
e.g. where the first FIT contains devicetrees and the second contains
the OS.

At present this is not permitted, since every FIT must contain a
bootable kernel (or firmware).

Add a new 'load-only' property to indicate that a configuration can be
loaded but not booted. Add a table indicating how this should be
implemented. Describe how the option works in the 'usage' section.

Signed-off-by: Simon Glass <[email protected]>

Author: sjg20

source/chapter2-source-file-format.rst

@@ -574,10 +574,15 @@ Mandatory properties
 description
     Textual configuration description.
 
+Conditionally mandatory property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 kernel or firmware
     Unit name of the corresponding :index:`kernel` or :index:`firmware`
     (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified,
-    control is passed to the firmware image.
+    control is passed to the firmware image. For `load_only`_ images, these two
+    properties are optional.
+
 
 Optional properties
 ~~~~~~~~~~~~~~~~~~~
@@ -621,13 +626,22 @@ compatible
     Note that U-Boot requires the :index:`CONFIG_FIT_BEST_MATCH` option to be
     enabled for this matching to work.
 
+.. _load_only:
+
+load-only
+    Indicates that this configuration does not necessarily contain an executable
+    image, i.e. kernel or firmware. The configuration's images may be loaded
+    into memory for use by the executable image, which comes from another
+    configuration or FIT. See see :ref:`multi_step`.
+
 The FDT blob is required to properly boot FDT-based kernel, so the minimal
 configuration for 2.6 FDT kernel is (kernel, fdt) pair.
 
 Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
 'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
 not* be specified in a configuration node.
 
+
 Configuration-signature nodes
 -----------------------------
 

source/chapter3-usage.rst

@@ -192,6 +192,48 @@ before SPL), then TPL will only load images with a phase of "spl". This allows
 all images to be provided in a single FIT, with each phase pulling out what is
 needed as the boot proceeds.
 
+.. _multi_step:
+
+Multi-step loading
+------------------
+
+The most common use of a FIT is where each configuration contains everything
+needed to boot. For example, on ARM systems a configuration contains a kernel,
+devicetree(s) and a ramdisk if needed. This approach is widely used on embedded
+systems.
+
+This approach is not always desirable, however, particularly when the firmware
+and the OS are supplied by different parties. In that case, the devicetree may
+be provided by the firmware with the other pieces coming from the OS. This
+means that FIT may omit the devicetree images.
+
+With devicetree in particular, it is common for the OS to provide its own
+version, or perhaps a devicetree overlay to add some new nodes and properties.
+
+Obviously if the OS has to provide a devicetree for every device, the OS files
+would become very large. A middle path could be that the hardware vendor
+provides a FIT on a boot partition, containing devicetrees for hardware
+supported by that vendor. Then the bootloader can load that FIT to get just the
+devicetree, followed by the main FIT to load the OS.
+
+To enable this last case, add a :ref:`load_only` property to the configuration.
+This signals to the bootloader that it should not require an executable (i.e.
+kernel or firmware), nor should it try to boot with this configuration. Booting
+then becomes a two-step process: load one FIT to obtain the devicetree, then
+another to obtain the OS. Only the second FIT is booted.
+
+Specifically, the 'load-only' property adjusts the meaning of loading a FIT, so
+that implementors should follow the following behaviour:
+
+===================  ==================  ====================
+'load-only' present  Executable present  Behaviour
+===================  ==================  ====================
+no                   no                  Raise an error
+yes                  no                  Only load the images
+no                   yes                 Execute binary
+yes                  yes                 Execute binary
+===================  ==================  ====================
+
 Security
 --------