Re: [docs] [PATCH v2] ref-manual: uboot-sign: Support firmware property in FIT config

["Antonin Godard" <antonin.godard@bootlin.com>]

On Fri May 23, 2025 at 10:43 AM CEST, Jamin Lin via lists.yoctoproject.org wrote:
> Add documentation for the UBOOT_FIT_CONF_FIRMWARE variable, which allows
> users to specify an image to be assigned to the "firmware" property of
> the FIT configuration node. This explicitly defines the primary image
> to boot, instead of relying on the first entry in the "loadables" list.
>
> Signed-off-by: Jamin Lin <jamin_lin@aspeedtech.com>
> ---
>  documentation/ref-manual/classes.rst   | 2 ++
>  documentation/ref-manual/variables.rst | 8 ++++++++
>  2 files changed, 10 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 5187033f7..54a98bf24 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -3426,6 +3426,8 @@ The variables used by this class are:
>  -  :term:`UBOOT_FIT_USER_SETTINGS`: adds a user-specific snippet to the U-Boot
>     Image Tree Source (ITS). Users can include their custom U-Boot Image Tree
>     Source (ITS) snippet in this variable.
> +-  :term:`UBOOT_FIT_CONF_FIRMWARE`: adds one image to the ``firmware`` property
> +   of the configuration node.
>  -  :term:`UBOOT_FIT_CONF_USER_LOADABLES`: adds one or more user-defined images
>     to the ``loadables`` property of the configuration node.
>  
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 643a3e7ae..b382e2281 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -10327,6 +10327,14 @@ system and gives an overview of their function and contents.
>  
>           do_compile[depends] += "trusted-firmware-a:do_deploy"
>  
> +   :term:`UBOOT_FIT_CONF_FIRMWARE`
> +      Adds one image to the ``firmware`` property of the configuration node
> +      of the U-Boot Image Tree Source (ITS). Sets the firmware property to select
> +      the image to boot first. If not set, the first entry in "loadables" is used
> +      to boot instead::

Reading this a second time I think it is a bit odd to put the example below
after that sentence.

I would suggest:

"""
Sets the firmware property to select the image to boot first::

   UBOOT_FIT_CONF_FIRMWARE = "fwa"

If not set, the first entry in "loadables" is used to boot instead.
"""

What do you think?

> +         UBOOT_FIT_CONF_FIRMWARE = "fwa"
> +
>     :term:`UBOOT_FIT_CONF_USER_LOADABLES`
>        Adds one or more user-defined images to the ``loadables`` property of the
>        configuration node of the U-Boot Image Tree Source (ITS). This variable


Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com