Re: [docs] [PATCH 1/2] ref-manual/variables.rst: document UBOOT_INITIAL_ENV_BINARY variables

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

Hi,

On Wed Jan 7, 2026 at 6:01 PM CET, Pierre-loup GOSSE via lists.yoctoproject.org wrote:
> From: Pierre-Loup GOSSE <pierre-loup.gosse@smile.fr>
>
> Added by commit cf11b14a4cfc ("u-boot: make initial environment binary
> image") in OE-Core.
>
> Signed-off-by: Pierre-Loup GOSSE <pierre-loup.gosse@smile.fr>
> ---
>  documentation/ref-manual/variables.rst | 38 ++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index ee776c110..01bf346fc 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -10974,6 +10974,44 @@ system and gives an overview of their function and contents.
>  
>        See the :ref:`ref-classes-uboot-sign` class for details.
>  
> +   :term:`UBOOT_INITIAL_ENV_BINARY`
> +      This variable enables the generation of the U-Boot initial environment in
> +      binary format. The binary size must be specified using
> +      :term:`UBOOT_INITIAL_ENV_BINARY_SIZE`.
> +
> +      Its default value is "0", set it to "1" to enable this functionality::
> +
> +         UBOOT_INITIAL_ENV_BINARY = "1"
> +

Suggestion, add:

"""
If set to "1", you must also set the size of the environment with
:term:`UBOOT_INITIAL_ENV_BINARY_SIZE`.
"""

> +      This variable is used in the :ref:`ref-classes-uboot-config` class.
> +
> +      The resulting binary can be flashed using WIC or any other flashing

I would add a link here:

s/WIC/:doc:`WIC </dev-manual/wic>`/

> +      method at the environment offset, overriding any existing environment if
> +      one is present. Below is an example of a WKS file to flash the binary::
> +
> +         part --source rawcopy --sourceparams="file=u-boot-initial-env-sd.bin" --ondisk sda --no-table --offset 4096k
> +
> +      In this example, the U-Boot initial environment binary
> +      `u-boot-initial-env-sd.bin` is flashed at offset 4096 kibibyte.
> +
> +   :term:`UBOOT_INITIAL_ENV_BINARY_REDUND`
> +      When using redundant U-Boot environment, this variable must be enabled to
> +      support the multiple copies layout. Enable it as follows::

Maybe I would rephrase it to:

"""
If redundant environment support is enabled in U-boot's configuration, this
variable should to properly generate the redundant environment in the output
U-boot environment binary file.
"""


> +
> +         UBOOT_INITIAL_ENV_BINARY_REDUND = "1"
> +

I would add:

"""
The :term:`UBOOT_INITIAL_ENV_BINARY` must also be set to "1" if
:term:`UBOOT_INITIAL_ENV_BINARY_REDUND` is enabled.
"""

> +      This variable is used in the :ref:`ref-classes-uboot-config` class.
> +
> +

Extra empty line here

> +   :term:`UBOOT_INITIAL_ENV_BINARY_SIZE`
> +      This variable sets the binary size (in bytes) of the U-Boot initial
> +      environment. Both hexadecimal and decimal values are supported and can be
> +      set as follows::
> +
> +         UBOOT_INITIAL_ENV_BINARY_SIZE = "0x4000"
> +
> +      This variable is used in the :ref:`ref-classes-uboot-config` class.
> +
>     :term:`UBOOT_LOADADDRESS`
>        Specifies the load address for the U-Boot image. During U-Boot image
>        creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a


Thanks for following up with the docs patch, appreciated!

Antonin

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