diff mbox series

[v4] ref-manual: cover UBOOT_ENV variables

Message ID 20250225222442.3347665-1-adrian.freihofer@siemens.com
State Accepted
Headers show
Series [v4] ref-manual: cover UBOOT_ENV variables | expand

Commit Message

Adrian Freihofer Feb. 25, 2025, 10:24 p.m. UTC
Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
---
 documentation/ref-manual/variables.rst | 63 ++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

Comments

Quentin Schulz Feb. 26, 2025, 10:35 a.m. UTC | #1
Hi Adrian,

On 2/25/25 11:24 PM, Adrian Freihofer via lists.yoctoproject.org wrote:
> Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
> ---
>   documentation/ref-manual/variables.rst | 63 ++++++++++++++++++++++++++
>   1 file changed, 63 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index adbef69d8f3..a3d59390cd1 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3180,6 +3180,31 @@ 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.
> +
> +      When inheriting the :ref:`ref-classes-kernel-fitimage` class a
> +      script file should be included in the :term:`SRC_URI` of the Linux
> +      kernel recipe.
> +
> +      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. The name of the script in
> +         FIT image is ``bootscr-${FIT_UBOOT_ENV}``. This example loads the FIT
> +         image from a TFTP server::
> +
> +            tftp $loadaddr $fit_tftp_path
> +            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.
> @@ -9791,6 +9816,44 @@ system and gives an overview of their function and contents.
>         :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
>         classes.
>   
> +   :term:`UBOOT_ENV`
> +      This variable allows to add additional environment variables or a script
> +      to be installed together with U-Boot.
> +      This file, typically ``uEnv.txt`` or ``boot.cmd``, is installed in
> +      ``/boot`` as well as copied to the :term:`DEPLOYDIR` directory.
> +
> +      For machine configurations needing one of these files a ``.bbappend``
> +      file should include it in the :term:`SRC_URI` of 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 verbatim.
> +
> +      Some examples:
> +
> +      -  Adding a script ``boot.cmd`` as a uImage to ``/boot``::
> +
> +            UBOOT_ENV = "boot"
> +            UBOOT_ENV_SUFFIX = "scr"
> +            SRC_URI += "file://${UBOOT_ENV_SRC}"
> +
> +      -  Adding a script ``uEnv.txt`` as a plain text file to ``/boot``::
> +
> +            UBOOT_ENV = "uEnv"
> +            UBOOT_ENV_SUFFIX = "txt"
> +            SRC_URI += "file://${UBOOT_ENV_BINARY}"
> +

It is indeed odd to specify UBOOT_ENV_BINARY/UBOOT_ENV_SRC out of nowhere.

We could state that one should use UBOOT_ENV_BINARY when referencing the 
uboot environment in any form, to be installed. And UBOOT_ENV_SRC when 
referring to the source script that will be installed as uImage, 
otherwise use UBOOT_ENV_BINARY.

Considering setting UBOOT_ENV_SRC_SUFFIX to txt would allow use to use 
UBOOT_ENV_SRC for every example above, maybe we should do that instead 
so it's less confusing?

Then we would only need to specify what UBOOT_ENV_SRC means in a note 
(or in a new term in the glossary), e.g. that it defaults to 
${UBOOT_ENV}.${UBOOT_ENV_SRC_SUFFIX}?

What do you think?

In any case, this looks good to me, therefore:

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin
Antonin Godard March 10, 2025, 1:20 p.m. UTC | #2
Applied, thanks!

[1/1] ref-manual: cover UBOOT_ENV variables
      commit: dc2ff96a3401eba8dac86fc8305b261be52c8a13

Best regards,
diff mbox series

Patch

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index adbef69d8f3..a3d59390cd1 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3180,6 +3180,31 @@  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.
+
+      When inheriting the :ref:`ref-classes-kernel-fitimage` class a
+      script file should be included in the :term:`SRC_URI` of the Linux
+      kernel recipe.
+
+      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. The name of the script in
+         FIT image is ``bootscr-${FIT_UBOOT_ENV}``. This example loads the FIT
+         image from a TFTP server::
+
+            tftp $loadaddr $fit_tftp_path
+            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.
@@ -9791,6 +9816,44 @@  system and gives an overview of their function and contents.
       :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
       classes.
 
+   :term:`UBOOT_ENV`
+      This variable allows to add additional environment variables or a script
+      to be installed together with U-Boot.
+      This file, typically ``uEnv.txt`` or ``boot.cmd``, is installed in
+      ``/boot`` as well as copied to the :term:`DEPLOYDIR` directory.
+
+      For machine configurations needing one of these files a ``.bbappend``
+      file should include it in the :term:`SRC_URI` of 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 verbatim.
+
+      Some examples:
+
+      -  Adding a script ``boot.cmd`` as a uImage to ``/boot``::
+
+            UBOOT_ENV = "boot"
+            UBOOT_ENV_SUFFIX = "scr"
+            SRC_URI += "file://${UBOOT_ENV_SRC}"
+
+      -  Adding a script ``uEnv.txt`` as a plain text file to ``/boot``::
+
+            UBOOT_ENV = "uEnv"
+            UBOOT_ENV_SUFFIX = "txt"
+            SRC_URI += "file://${UBOOT_ENV_BINARY}"
+
+   :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 it is specified in the :term:`SRC_URI` of the
+      U-Boot recipe. It defaults to ``cmd``.
+
+   :term:`UBOOT_ENV_SUFFIX`
+      If this variable is set to ``scr`` the script referred to 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_FIT_ADDRESS_CELLS`
       Specifies the value of the ``#address-cells`` value for the
       description of the U-Boot FIT image.