Add variant property for mutually exclusive images

Some platforms include multiple versions of the same firmware component
where only one is loaded at runtime based on platform-specific criteria
(e.g. device security state). These images typically share the same load
address, creating an apparent memory overlap that is intentional.

Add a 'variant' property to identify groups of mutually exclusive images.
Images sharing the same variant value form a group where at most one will
be loaded during any given boot. This allows overlap-detection tools to
distinguish intentional address sharing from genuine conflicts.

Also add an "Optional properties" section heading to chapter 2, which was
missing, and a "Variant images" section to chapter 3 explaining the use
case with a detailed example based on TI K3 platforms.

Co-developed-by: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>

Author: sjg20

source/chapter2-source-file-format.rst

@@ -371,6 +371,9 @@ load
        The compatible here is not derived from the fdt, nor is it used to identify
        the fdt. Such usage belongs in the configuration node.
 
+Optional properties
+~~~~~~~~~~~~~~~~~~~
+
 .. _prop_phase:
 
 :index:`phase`
@@ -382,6 +385,39 @@ load
     "u-boot"
         image is a U-Boot image
 
+.. _prop_variant:
+
+:index:`variant`
+    Identifies a group of :index:`mutually exclusive <pair: images; mutually exclusive>`
+    images. Images sharing the same variant value will not all be loaded
+    simultaneously; the boot firmware selects at most one at runtime based on
+    platform-specific criteria (e.g. device security state).
+
+    This property is used by tooling to suppress false-positive overlap warnings
+    when multiple images in a configuration share the same load address but are
+    never loaded together.
+
+    Example: A platform may include firmware stubs for different security
+    levels::
+
+        tifsstub-hs {
+            description = "TIFSSTUB for HS devices";
+            type = "firmware";
+            load = <0x9dc00000>;
+            variant = "tifsstub";
+        };
+        tifsstub-fs {
+            description = "TIFSSTUB for FS devices";
+            type = "firmware";
+            load = <0x9dc00000>;
+            variant = "tifsstub";
+        };
+
+    At runtime, the boot firmware loads only the appropriate stub based on the
+    detected security state. Because both images declare ``variant = "tifsstub"``,
+    overlap-detection tools understand that the shared load address is
+    intentional.
+
 Optional nodes
 ~~~~~~~~~~~~~~
 

source/chapter3-usage.rst

@@ -192,6 +192,81 @@ 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.
 
+Variant images
+--------------
+
+Some platforms require multiple versions of the same firmware component, where
+only one version is loaded at runtime based on platform-specific criteria. A
+common example is security-state-dependent firmware: a device may ship with
+firmware stubs for different security levels (e.g. high-security, field-
+securable, general-purpose), but only one is appropriate for the detected
+hardware state.
+
+These images typically share the same load address, since they serve the same
+purpose and the hardware expects the firmware at a fixed location. This creates
+an apparent memory overlap in the FIT, but it is intentional because the images
+are mutually exclusive at runtime.
+
+To express this relationship, images can declare a ``variant`` property (see
+:ref:`prop_variant`). Images sharing the same variant value form a mutually
+exclusive group: at most one image from the group will be loaded during any
+given boot.
+
+Example::
+
+    images {
+        tifsstub-hs {
+            description = "TIFSSTUB for HS devices";
+            type = "firmware";
+            arch = "arm32";
+            compression = "none";
+            load = <0x9dc00000>;
+            entry = <0x9dc00000>;
+            variant = "tifsstub";
+        };
+        tifsstub-fs {
+            description = "TIFSSTUB for FS devices";
+            type = "firmware";
+            arch = "arm32";
+            compression = "none";
+            load = <0x9dc00000>;
+            entry = <0x9dc00000>;
+            variant = "tifsstub";
+        };
+        tifsstub-gp {
+            description = "TIFSSTUB for GP devices";
+            type = "firmware";
+            arch = "arm32";
+            compression = "none";
+            load = <0x9dc00000>;
+            entry = <0x9dc00000>;
+            variant = "tifsstub";
+        };
+    };
+
+    configurations {
+        conf-1 {
+            firmware = "atf";
+            loadables = "tee", "tifsstub-hs", "tifsstub-fs", "tifsstub-gp";
+            fdt = "fdt-1";
+        };
+    };
+
+The boot firmware is responsible for selecting the appropriate image from each
+variant group. This selection is platform-specific; for example, TI K3 platforms
+select based on the device's security state.
+
+Memory-overlap detection
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tools that validate FIT images (such as ``mkimage``) may check for memory
+overlaps between images in a configuration. When images declare the same
+``variant`` value, overlap-detection tools should not report conflicts between
+them, since they are mutually exclusive by design.
+
+Genuine overlaps (images without a shared variant that would occupy the same
+memory simultaneously) remain errors and should be reported.
+
 .. _multi_step:
 
 Multi-step loading