Re: [docs] [PATCH v2 1/2] ref-manual: cover UBOOT_ENV variables

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

Hi Adrian,

On Mon Feb 24, 2025 at 9:27 AM CET, Adrian Freihofer via lists.yoctoproject.org wrote:
> Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
> ---
>  documentation/ref-manual/variables.rst | 64 ++++++++++++++++++++++++++
>  1 file changed, 64 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index adbef69d8f3..82dd80ca130 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3180,6 +3180,30 @@ system and gives an overview of their function and contents.
>        The default value for this variable is set to "2048"
>        by the :ref:`ref-classes-kernel-fitimage` class.
>  
> +   :term:`FIT_UBOOT_ENV`
> +      This variable allows to add a U-Boot script as a text file to the
> +      FIT image. Such a script can be sourced from the U-Boot shell.
> +
> +      For machine configurations needing such a script a
> +      ``linux-yocto_%.bbappend`` file should include it in the :term:`SRC_URI`
> +      of the kernel recipe.

s/kernel/Linux kernel/

> +
> +      Example:
> +
> +      -  Add a script ``boot.cmd`` to the Linux kernel recipe::
> +
> +            FIT_UBOOT_ENV = "boot.cmd"
> +            SRC_URI += "file://${FIT_UBOOT_ENV}"
> +
> +      -  Use the script file from the U-Boot shell. This example loads the FIT
> +         image from a TFP server.::

s/TFP/TFTP/

> +
> +            tftp $loadaddr $fit_url
> +            source $loadaddr#bootscr-boot.cmd
> +
> +      More information can be found in the official U-Boot documentation:
> +      `U-Boot source command <https://docs.u-boot.org/en/latest/usage/cmd/source.html#fit-image.f>`__
> +
>     :term:`FONT_EXTRA_RDEPENDS`
>        When inheriting the :ref:`ref-classes-fontcache` class,
>        this variable specifies the runtime dependencies for font packages.
> @@ -9777,6 +9801,46 @@ system and gives an overview of their function and contents.
>        :ref:`ref-classes-kernel-fitimage` class to specify the load address to be
>        used in creating the dtbo sections of Image Tree Source for the FIT image.
>  
> +   :term:`UBOOT_ENV`
> +      Additional environment variables or a script can be installed alongside

Can you start the paragraph with "This variable allows..." like the other? So
the next sentence doesn't feel out of context, and the user instantly knows what
the variable is used for.

> +      U-Boot to be used automatically on boot.
> +      This file, typically ``uEnv.txt`` or ``boot.cmd``, gets packaged along
> +      with U-Boot (installed into ``/boot``) as well as placed in the deploy
> +      directory.
> +
> +      For machine configurations needing one of these files a
> +      ``u-boot_%.bbappend`` file should include it in the :term:`SRC_URI` of

s/``u-boot_%.bbappend``/``.bbappend``/ (not limited to u-boot.bb only I assume
but any virtual/bootloader representing U-boot)

> +      the U-Boot recipe.
> +
> +      If the variable :term:`UBOOT_ENV_SUFFIX` is set to ``scr`` the script is
> +      packaged as a uImage (``mkimage -T script..``) otherwise it gets
> +      installed as it is.
> +
> +      Some Examples:

s/Examples/examples/

> +
> +      -  Adding a script ``boot.cmd`` as an uImage to ``/boot``::
> +
> +            UBOOT_ENV = "boot"
> +            UBOOT_ENV_SUFFIX = "scr"

Or shouldn't you set UBOOT_ENV_SRC_SUFFIX to "cmd" here too? I'm a little
confused as why you refer to boot.cmd yet "cmd" is not defined here.

> +            SRC_URI += "file://${UBOOT_ENV}.${UBOOT_ENV_SRC_SUFFIX}"
> +
> +      -  Adding a script ``uEnv.txt`` as a plain text file to ``/boot``::
> +
> +            UBOOT_ENV = "uEnv"
> +            UBOOT_ENV_SUFFIX = "txt"
> +            SRC_URI += "file://${UBOOT_ENV}.${UBOOT_ENV_SUFFIX}"
> +
> +   :term:`UBOOT_ENV_SUFFIX`
> +      If this variable is set to ``scr`` the script referred by
> +      :term:`UBOOT_ENV` gets packaged as a uImage before it gets installed.
> +      The default is ``txt`` which means the script is installed as-is, with
> +      no modification.
> +
> +   :term:`UBOOT_ENV_SRC_SUFFIX`
> +      If :term:`UBOOT_ENV_SUFFIX` is set to ``scr`` this is the suffix of the
> +      plain text script file as is it specified in the :term:`SRC_URI` of the
> +      U-Boot recipe.
> +
>     :term:`UBOOT_ENTRYPOINT`
>        Specifies the entry point for the U-Boot image. During U-Boot image
>        creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a

Thanks!
Antonin

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