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

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

[pierre-loup.gosse]

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"
+
+      This variable is used in the :ref:`ref-classes-uboot-config` class.
+
+      The resulting binary can be flashed using WIC or any other flashing
+      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::
+
+         UBOOT_INITIAL_ENV_BINARY_REDUND = "1"
+
+      This variable is used in the :ref:`ref-classes-uboot-config` class.
+
+
+   :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
-- 
2.34.1

[PATCH 2/2] migration-guides/release-notes-6.0.rst: add U-Boot initial env binary

[pierre-loup.gosse]

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/migration-guides/release-notes-6.0.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/documentation/migration-guides/release-notes-6.0.rst b/documentation/migration-guides/release-notes-6.0.rst
index cfc51fc3a..13ce28b3b 100644
--- a/documentation/migration-guides/release-notes-6.0.rst
+++ b/documentation/migration-guides/release-notes-6.0.rst
@@ -71,6 +71,12 @@ New Features / Enhancements in |yocto-ver|
 
 -  :ref:`ref-classes-sanity` class changes:
 
+-  U-boot related changes:
+
+   -  :ref:`ref-classes-uboot-config`: Add support for generating the U-Boot
+      initial environment in binary format using
+      :term:`UBOOT_INITIAL_ENV_BINARY`.
+
 -  Miscellaneous changes:
 
 Known Issues in |yocto-ver|
-- 
2.34.1

Re: [docs] [PATCH 2/2] migration-guides/release-notes-6.0.rst: add U-Boot initial env binary

[Antonin Godard]

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/migration-guides/release-notes-6.0.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/documentation/migration-guides/release-notes-6.0.rst b/documentation/migration-guides/release-notes-6.0.rst
> index cfc51fc3a..13ce28b3b 100644
> --- a/documentation/migration-guides/release-notes-6.0.rst
> +++ b/documentation/migration-guides/release-notes-6.0.rst
> @@ -71,6 +71,12 @@ New Features / Enhancements in |yocto-ver|
>  
>  -  :ref:`ref-classes-sanity` class changes:
>  
> +-  U-boot related changes:
> +
> +   -  :ref:`ref-classes-uboot-config`: Add support for generating the U-Boot
> +      initial environment in binary format using
> +      :term:`UBOOT_INITIAL_ENV_BINARY`.
> +
>  -  Miscellaneous changes:
>  
>  Known Issues in |yocto-ver|

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

Thanks,
Antonin

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

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

[Antonin Godard]

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