ref-manual/variables.rst: document new FIT image variables

From: Adrian Freihofer <adrian.freihofer@siemens.com>

- FIT_MKIMAGE_EXTRA_OPTS: new variable to pass extra mkimage options
- FIT_CONF_MAPPINGS for flexible DTB mappings

Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
---
 documentation/ref-manual/variables.rst | 44 ++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

Hi,

On Thu Jan 8, 2026 at 11:20 PM CET, Adrian Freihofer via lists.yoctoproject.org wrote:
> From: Adrian Freihofer <adrian.freihofer@siemens.com>
>
> - FIT_MKIMAGE_EXTRA_OPTS: new variable to pass extra mkimage options
> - FIT_CONF_MAPPINGS for flexible DTB mappings
>
> Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
> ---
>  documentation/ref-manual/variables.rst | 44 ++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index ee776c110..734dfcbd4 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3383,6 +3383,35 @@ system and gives an overview of their function and contents.
>  
>        This variable is used in the :ref:`ref-classes-kernel-fit-image` class.
>  
> +   :term:`FIT_CONF_MAPPINGS`

Start with

"""
When inheriting the :ref:`ref-classes-kernel-fit-image`, the
:term:`FIT_CONF_MAPPINGS` variable allows ..."
"""

> +      Allows specifying mappings to rename configuration nodes or add extra
> +      configuration nodes for existing DTBs in FIT images. This provides

For clarity:
s/DTBs/device tree blobs (DTBs)/

Then you can use DTBs below?

> +      flexibility when a 1-1 mapping between DTB names and configuration

For clarity:
s/1-1/1 to 1/

> +      node names does not work.

Could you provide an example of such a scenario?

> +      The variable accepts a space-separated list of mapping commands:
> +
> +      - ``dtb-conf:DTB_NAME:NEW_NAME``

Two spaces after the list "-"

You could say that the ``DTB_NAME`` is the name of the DTB without its ``.dtb``
suffix?

> +        Renames the configuration node for a specific DTB.
> +
> +      - ``dtb-extra-conf:DTB_NAME:EXTRA_NAME``
> +        Creates an additional configuration node for an existing DTB.

I wonder why that would be needed? This would duplicate the configuration
without another name, but what's the point?

> +
> +      For example::
> +
> +         FIT_CONF_MAPPINGS = "\
> +             dtb-extra-conf:am335x-bonegreen:bonegreen \
> +             dtb-conf:am335x-boneblack:bbblack"
> +
> +      This generates three configuration nodes from two DTBs:
> +
> +      - ``am335x-bonegreen``: a standard configuration node for a DTB

I would rephrase to "the original configuration node for the
``am335x-bonegreen`` device tree".

> +      - ``bonegreen``: an extra configuration node for the same DTB

s/for the same DTB/for the same ``am335x-bonegreen`` DTB/

> +      - ``bbblack``: a renamed configuration node for the ``am335x-boneblack`` DTB
> +
> +      The :ref:`ref-classes-kernel-fit-image` class validates all mappings
> +      and ensures they match existing DTBs.
> +
>     :term:`FIT_CONF_PREFIX`
>        When using the :ref:`ref-classes-kernel-fit-image`, this is the prefix
>        used for creating FIT configuration nodes. Its default value is "conf-".
> @@ -3473,6 +3502,21 @@ system and gives an overview of their function and contents.
>        The default value is set to "x509" by the
>        :ref:`ref-classes-kernel-fit-image` class.
>  
> +   :term:`FIT_MKIMAGE_EXTRA_OPTS`

Instead of ending the definition with "The :ref:`ref-classes-kernel-fit-image`
class uses this variable.", just start with "When inheriting the
:ref:`ref-classes-kernel-fit-image`, the :term:`FIT_MKIMAGE_EXTRA_OPTS` variable ..."

> +      This variable allows passing extra options to ``mkimage`` during FIT
> +      image generation, providing flexibility for platforms that require
> +      additional ``mkimage`` arguments beyond the defaults.
> +
> +      For example::
> +
> +         FIT_MKIMAGE_EXTRA_OPTS = "-B 8 -E"
> +
> +      This results in the ``mkimage`` command being invoked as::
> +
> +         mkimage -B 8 -E -f fit-image.its fitImage

Nit:

"""
This results in the ``mkimage`` command being invoked as:

.. parsed-literal::

   mkimage *-B 8 -E* -f fit-image.its fitImage
"""

This will highlight the new options

> +
> +      The :ref:`ref-classes-kernel-fit-image` class uses this variable.
> +
>     :term:`FIT_PAD_ALG`
>        Specifies the padding algorithm used in creating the FIT Image.
>        The default value is set to "pkcs-1.5" by the

Thanks!
Antonin