Skip to contentSkip to conversation

ref-manual: Document updated UBOOT_CONFIG flow

PATCH Superseded Ryan Eatmon 2 participants 2 messages Jan 20 – Jan 27

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 ref-manual: Document updated UBOOT_CONFIG flow

The UBOOT_CONFIG flow was updated in oe-core [1]. Document all of the new variables and preferred method of specifying the various controls for each config.

[1] xxx

---
 documentation/ref-manual/classes.rst   |  96 +++++++++++++++++++----
 documentation/ref-manual/variables.rst | 101 +++++++++++++++++++++++--
 2 files changed, 176 insertions(+), 21 deletions(-)
documentation/ref-manual/classes.rst +83 -13
index 2e219a59c..4eb811387 100644
@@ -3269,13 +3269,89 @@ variable using the "type" varflag. Here is an example::
 The :ref:`ref-classes-uboot-config` class provides support for configuring one
 or more U-Boot build configurations.
 
-There are two ways to configure the recipe for your machine:
+There are three ways to configure the recipe for your machine:
 
--  Using :term:`UBOOT_CONFIG` variable. For example::
+-  Using the :term:`UBOOT_MACHINE` variable (and its companion variable
+   :term:`UBOOT_BINARY`). For example::
+
+      UBOOT_MACHINE = "config"
+      UBOOT_BINARY = "u-boot.bin"
+
+-  Using :term:`UBOOT_CONFIG` variables. For example::
+
+      UBOOT_CONFIG ??= "foo bar"
+      UBOOT_CONFIG[foo] = "config"
+      UBOOT_CONFIG[bar] = "config2"
+
+      UBOOT_CONFIG_IMAGE_FSTYPES[bar] = "fstype"
+
+      UBOOT_CONFIG_BINARY[foo] = "binary"
+
+      UBOOT_CONFIG_MAKE_OPTS[foo] = "FOO=1"
+      UBOOT_CONFIG_MAKE_OPTS[bar] = "BAR=1"
+
+      UBOOT_CONFIG_FRAGMENTS[foo] = "foo.fragment"
+
+   In this example, all possible configurations are selected (``foo`` and
+   ``bar``), but it is also possible to build only ``foo`` or ``bar`` by
+   changing the value of :term:`UBOOT_CONFIG` to include either one or the
+   other.
+
+   Each build configuration is associated to a variable flag definition of
+   :term:`UBOOT_CONFIG`, and associated changes for each config as defined
+   in the various UBOOT_CONFIG_* variables.
+
+   -  UBOOT_CONFIG[config]: defconfig file selected for this build configuration.
+      These files are found in the source tree's ``configs`` folder of U-Boot.
+
+      *This option is mandatory.*
+
+   -  :term:`UBOOT_CONFIG_IMAGE_FSTYPES` [config]: image types to append to the
+      :term:`IMAGE_FSTYPES` variable for image generation for this build
+      configuration.
+
+      This can allow building an extra image format that uses the binary
+      generated by this build configuration.
+
+      This option is not mandatory and can be left unspecified if not needed.
+
+   -  :term:`UBOOT_CONFIG_BINARY` [config]: binary to select as the one to deploy in
+      :term:`DEPLOY_DIR_IMAGE`. The output of a U-Boot build may be more than
+      one binary, for example::
+
+         u-boot.bin
+         u-boot-with-spl.bin
+
+      Setting the ``binary`` value to ``u-boot-with-spl.bin`` will make this
+      binary the one deployed in :term:`DEPLOY_DIR_IMAGE`. It is renamed to
+      include the build configuration name in the process (``foo`` or ``bar`` in
+      the above example).
+
+      This option defaults to :term:`UBOOT_BINARY` if not specified.
+
+   -  :term:`UBOOT_CONFIG_MAKE_OPTS` [config]: additional options passed to
+      ``make`` when configuring and compiling U-Boot for this configuration
+      entry. The options in this entry are added before the options in
+      :term:`UBOOT_MAKE_OPTS`.
+
+      This option is not mandatory and adds nothing if not specified.  If
+      you do not have a make option for a given config, you can simply not
+      set the flag for that config.
+
+   -  :term:`UBOOT_CONFIG_FRAGMENTS` [config]: additional config fragment(s)
+      from the source tree that is used during ``do_configure()`` to setup the
+      build.  The options in this entry are added before the fragments in
+      :term:`UBOOT_FRAGMENTS`.
+
+      This option is not mandatory and adds nothing if not specified.  If
+      you do not have a fragment a given config, you can simply not set the
+      flag for that config.
+
+-  Or, a legacy method using the :term:`UBOOT_CONFIG` variable by itself. For example::
 
       UBOOT_CONFIG ??= "foo bar"
-      UBOOT_CONFIG[foo] = "config,images,binary,makeopts"
-      UBOOT_CONFIG[bar] = "config2,images2,binary2,makeopts2"
+      UBOOT_CONFIG[foo] = "config,images,binary"
+      UBOOT_CONFIG[bar] = "config2,images2,binary2"
 
    In this example, all possible configurations are selected (``foo`` and
    ``bar``), but it is also possible to build only ``foo`` or ``bar`` by
@@ -3313,15 +3389,9 @@ There are two ways to configure the recipe for your machine:
 
       This option defaults to :term:`UBOOT_BINARY` if unset.
 
-   -  ``makeopts``: the additional options passed to ``make`` when configuring
-      and compiling U-Boot for this configuration entry. The options in this
-      entry are added before the options in :term:`UBOOT_MAKE_OPTS`.
-
--  Or, using the :term:`UBOOT_MACHINE` variable (and its companion variable
-   :term:`UBOOT_BINARY`). For example::
-
-      UBOOT_MACHINE = "config"
-      UBOOT_BINARY = "u-boot.bin"
+.. note::
+   It is recommended to not use this legacy flow as any future extensions
+   to the control knobs will be not added to this methodology.
 
 Using :term:`UBOOT_MACHINE` and :term:`UBOOT_CONFIG` at the same time is not
 possible.
documentation/ref-manual/variables.rst +93 -8

128 lines not on this page · raw message

Signature · 1 line
2.43.0
#1 lore raw

Hi,

Quoted 39 lines · Ryan Eatmon via lists.yoctoproject.org

The UBOOT_CONFIG flow was updated in oe-core [1]. Document all of the new variables and preferred method of specifying the various controls for each config.

[1] xxx

---
 documentation/ref-manual/classes.rst   |  96 +++++++++++++++++++----
 documentation/ref-manual/variables.rst | 101 +++++++++++++++++++++++--
 2 files changed, 176 insertions(+), 21 deletions(-)
documentation/ref-manual/classes.rst +16 -2
index 2e219a59c..4eb811387 100644
@@ -3269,13 +3269,89 @@ variable using the "type" varflag. Here is an example::
 The :ref:`ref-classes-uboot-config` class provides support for configuring one
 or more U-Boot build configurations.
 
-There are two ways to configure the recipe for your machine:
+There are three ways to configure the recipe for your machine:
 
--  Using :term:`UBOOT_CONFIG` variable. For example::
+-  Using the :term:`UBOOT_MACHINE` variable (and its companion variable
+   :term:`UBOOT_BINARY`). For example::
+
+      UBOOT_MACHINE = "config"
+      UBOOT_BINARY = "u-boot.bin"
+
+-  Using :term:`UBOOT_CONFIG` variables. For example::
+
+      UBOOT_CONFIG ??= "foo bar"
+      UBOOT_CONFIG[foo] = "config"
+      UBOOT_CONFIG[bar] = "config2"
+
+      UBOOT_CONFIG_IMAGE_FSTYPES[bar] = "fstype"
+
+      UBOOT_CONFIG_BINARY[foo] = "binary"

documentation/ref-manual/classes.rst variable using the "type" varflag. Here is an example:: · line 3298

Quoted 10 lines
documentation/ref-manual/classes.rst +10 -0
+
+      UBOOT_CONFIG_MAKE_OPTS[foo] = "FOO=1"
+      UBOOT_CONFIG_MAKE_OPTS[bar] = "BAR=1"
+
+      UBOOT_CONFIG_FRAGMENTS[foo] = "foo.fragment"
+
+   In this example, all possible configurations are selected (``foo`` and
+   ``bar``), but it is also possible to build only ``foo`` or ``bar`` by
+   changing the value of :term:`UBOOT_CONFIG` to include either one or the
+   other.

For clarity, add:

"""
For example::

UBOOT_CONFIG = "foo"
"""

documentation/ref-manual/classes.rst variable using the "type" varflag. Here is an example:: · line 3304

Quoted 6 lines
documentation/ref-manual/classes.rst +6 -0
+
+   Each build configuration is associated to a variable flag definition of
+   :term:`UBOOT_CONFIG`, and associated changes for each config as defined
+   in the various UBOOT_CONFIG_* variables.
+
+   -  UBOOT_CONFIG[config]: defconfig file selected for this build configuration.

I'm afraid this will render oddly, enclose with `` ``:

"""
- ``UBOOT_CONFIG[config]``: ...
"""

To keep an hyperlink to the variable definition, I would end each bullet point in the list here with:

"""
See the documentation of :term:UBOOT_CONFIG* for more information.
"""

Quoted 59 lines
documentation/ref-manual/classes.rst +48 -2
+      These files are found in the source tree's ``configs`` folder of U-Boot.
+
+      *This option is mandatory.*
+
+   -  :term:`UBOOT_CONFIG_IMAGE_FSTYPES` [config]: image types to append to the
+      :term:`IMAGE_FSTYPES` variable for image generation for this build
+      configuration.
+
+      This can allow building an extra image format that uses the binary
+      generated by this build configuration.
+
+      This option is not mandatory and can be left unspecified if not needed.
+
+   -  :term:`UBOOT_CONFIG_BINARY` [config]: binary to select as the one to deploy in
+      :term:`DEPLOY_DIR_IMAGE`. The output of a U-Boot build may be more than
+      one binary, for example::
+
+         u-boot.bin
+         u-boot-with-spl.bin
+
+      Setting the ``binary`` value to ``u-boot-with-spl.bin`` will make this
+      binary the one deployed in :term:`DEPLOY_DIR_IMAGE`. It is renamed to
+      include the build configuration name in the process (``foo`` or ``bar`` in
+      the above example).
+
+      This option defaults to :term:`UBOOT_BINARY` if not specified.
+
+   -  :term:`UBOOT_CONFIG_MAKE_OPTS` [config]: additional options passed to
+      ``make`` when configuring and compiling U-Boot for this configuration
+      entry. The options in this entry are added before the options in
+      :term:`UBOOT_MAKE_OPTS`.
+
+      This option is not mandatory and adds nothing if not specified.  If
+      you do not have a make option for a given config, you can simply not
+      set the flag for that config.
+
+   -  :term:`UBOOT_CONFIG_FRAGMENTS` [config]: additional config fragment(s)
+      from the source tree that is used during ``do_configure()`` to setup the
+      build.  The options in this entry are added before the fragments in
+      :term:`UBOOT_FRAGMENTS`.
+
+      This option is not mandatory and adds nothing if not specified.  If
+      you do not have a fragment a given config, you can simply not set the
+      flag for that config.
+
+-  Or, a legacy method using the :term:`UBOOT_CONFIG` variable by itself. For example::
 
       UBOOT_CONFIG ??= "foo bar"
-      UBOOT_CONFIG[foo] = "config,images,binary,makeopts"
-      UBOOT_CONFIG[bar] = "config2,images2,binary2,makeopts2"
+      UBOOT_CONFIG[foo] = "config,images,binary"
+      UBOOT_CONFIG[bar] = "config2,images2,binary2"
 
    In this example, all possible configurations are selected (``foo`` and
    ``bar``), but it is also possible to build only ``foo`` or ``bar`` by
@@ -3313,15 +3389,9 @@ There are two ways to configure the recipe for your machine:
 
       This option defaults to :term:`UBOOT_BINARY` if unset.
 

documentation/ref-manual/classes.rst There are two ways to configure the recipe for your machine: · line 3392

Quoted 10 lines
documentation/ref-manual/classes.rst +1 -9
-   -  ``makeopts``: the additional options passed to ``make`` when configuring
-      and compiling U-Boot for this configuration entry. The options in this
-      entry are added before the options in :term:`UBOOT_MAKE_OPTS`.
-
--  Or, using the :term:`UBOOT_MACHINE` variable (and its companion variable
-   :term:`UBOOT_BINARY`). For example::
-
-      UBOOT_MACHINE = "config"
-      UBOOT_BINARY = "u-boot.bin"
+.. note::

Missing a newline between .. note:: and the text here

Quoted 10 lines
documentation/ref-manual/classes.rst +2 -0
+   It is recommended to not use this legacy flow as any future extensions
+   to the control knobs will be not added to this methodology.
 
 Using :term:`UBOOT_MACHINE` and :term:`UBOOT_CONFIG` at the same time is not
 possible.
documentation/ref-manual/variables.rst +0 -0
index 4d8a35473..dec260a3f 100644

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 10672

Quoted 6 lines
documentation/ref-manual/variables.rst +1 -2
@@ -10669,29 +10669,108 @@ system and gives an overview of their function and contents.
 
    :term:`UBOOT_CONFIG`
       Configures one or more U-Boot configurations to build. Each
-      configuration can define the :term:`UBOOT_MACHINE` and optionally the
-      :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`.
+      configuration must define the :term:`UBOOT_MACHINE`.  Additional control

"the term:UBOOT_MACHINE variable."

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 10673

Quoted 1 line
documentation/ref-manual/variables.rst +1 -0
+      variables can found at: :term:`UBOOT_CONFIG_BINARY`,

s/can found at:/are:/

Quoted 31 lines
documentation/ref-manual/variables.rst +12 -6
+      :term:`UBOOT_CONFIG_FRAGMENTS`, :term:`UBOOT_CONFIG_IMAGE_FSTYPES`, and
+      :term:`UBOOT_CONFIG_MAKE_OPTS`. 
 
-      Here is an example from the ``meta-freescale`` layer. ::
+      Here is an updated example from the ``meta-freescale`` layer. ::
 
          UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor"
+
          UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig"
-         UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig,,u-boot-with-spl-pbl.bin"
-         UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig,,u-boot-with-spl-pbl.bin"
+         UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig"
+         UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig"
          UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig"
          UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig"
          UBOOT_CONFIG[secure-boot] = "ls1021atwr_nor_SECURE_BOOT_defconfig"
-         UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig,,u-boot-with-spl-pbl.bin"
+         UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig"
+
+         UBOOT_CONFIG_BINARY[sdcard-ifc] = "u-boot-with-spl-pbl.bin"
+         UBOOT_CONFIG_BINARY[sdcard-qspi] = "u-boot-with-spl-pbl.bin"
+         UBOOT_CONFIG_BINARY[sdcard-ifc-secure-boot] = "u-boot-with-spl-pbl.bin"
 
       In this example, all possible seven configurations are selected. Each
       configuration specifies "..._defconfig" as :term:`UBOOT_MACHINE`, and
       the "sd..." configurations define an individual name for
-      :term:`UBOOT_BINARY`. No configuration defines a second parameter for
-      :term:`IMAGE_FSTYPES` to use for the U-Boot image.
+      :term:`UBOOT_CONFIG_BINARY`.
 
       For more information on how the :term:`UBOOT_CONFIG` is handled, see the

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 10708

Quoted 10 lines
documentation/ref-manual/variables.rst +8 -0
       :ref:`ref-classes-uboot-config` class.
 
+   :term:`UBOOT_CONFIG_BINARY`
+      This variable cannot be set to a value in a config, it is a placeholder
+      for configuring the :term:`UBOOT_CONFIG` flow via flags::
+
+         UBOOT_CONFIG_BINARY[foo] = "binary1"
+         UBOOT_CONFIG_BINARY[bar] = "binary2"
+
+      Specify the binary to select as the one to deploy in :term:`DEPLOY_DIR_IMAGE`.

s/Specify/It specifies/

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 10721

Quoted 13 lines
documentation/ref-manual/variables.rst +13 -0
+      The output of a U-Boot build may be more than one binary, for example::
+
+         u-boot.bin
+         u-boot-with-spl.bin
+
+      Setting the ``binary`` value to ``u-boot-with-spl.bin`` will make this
+      binary the one deployed in :term:`DEPLOY_DIR_IMAGE`. It is renamed to
+      include the build configuration name in the process (``foo`` or ``bar`` in
+      the above example).
+
+      This option defaults to :term:`UBOOT_BINARY` if not specified.
+
+      For more information on how the :term:`UBOOT_CONFIG_BINARY` is handled, see the

"the :term:UBOOT_CONFIG_BINARY variable"

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 10731

Quoted 11 lines
documentation/ref-manual/variables.rst +10 -0
+      :ref:`ref-classes-uboot-config` class.
+
+   :term:`UBOOT_CONFIG_FRAGMENTS`
+      This variable cannot be set to a value in a config, it is a placeholder
+      for configuring the :term:`UBOOT_CONFIG` flow via flags::
+
+         UBOOT_CONFIG_FRAGMENTS[foo] = "frag1 frag2"
+         UBOOT_CONFIG_FRAGMENTS[bar] = "frag3"
 
+
+      Specify a list of fragments from the source tree that should be combined

s/Specify/It specifies/

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 10733

Quoted 2 lines
documentation/ref-manual/variables.rst +2 -0
+      with the defconfig from :term:`UBOOT_CONFIG` that are used during ``do_configure()``
+      to configure the build.

Can we specify from what these fragments paths are relative to? ${S}?

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 10736

Quoted 2 lines
documentation/ref-manual/variables.rst +2 -0
+
+      This option is not required and you only need to specify flag settings for

s/to specify flag settings/to specify it/ ?

Quoted 20 lines
documentation/ref-manual/variables.rst +20 -0
+      configs that need them.
+
+      For more information on how the :term:`UBOOT_CONFIG_FRAGMENTS` is handled, see the
+      :ref:`ref-classes-uboot-config` class.
+
+   :term:`UBOOT_CONFIG_IMAGE_FSTYPES`
+      This variable cannot be set to a value in a config, it is a placeholder
+      for configuring the :term:`UBOOT_CONFIG` flow via flags::
+
+         UBOOT_CONFIG_IMAGE_FSTYPES[foo] = "fstype1"
+         UBOOT_CONFIG_IMAGE_FSTYPES[bar] = "fstype2"
+
+      Append additional image types to the :term:`IMAGE_FSTYPES` variable for
+      image generation for this build configuration.  This can allow building an
+      extra image format that uses the binary generated by this build configuration.
+
+      This option is not required and you only need to specify flag settings for
+      configs that need them.
+
+      For more information on how the :term:`UBOOT_CONFIG_IMAGE_FSTYPES` is handled, see the

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 10765

Quoted 10 lines
documentation/ref-manual/variables.rst +10 -0
+      :ref:`ref-classes-uboot-config` class.
+
+   :term:`UBOOT_CONFIG_MAKE_OPTS`
+      This variable cannot be set to a value in a config, it is a placeholder
+      for configuring the :term:`UBOOT_CONFIG` flow via flags::
+
+         UBOOT_CONFIG_MAKE_OPTS[foo] = "OPT1=foo OPT2=2"
+         UBOOT_CONFIG_MAKE_OPTS[bar] = "OPT1=bar"
+
+      Specify a list of make command line options that are passed to the ``make`` command

s/Specify/It specifies/

Quoted 12 lines
documentation/ref-manual/variables.rst +8 -0
+      during ``do_compile()``.
+
+      This option is not required and you only need to specify flag settings for
+      configs that need them.
+
+      For more information on how the :term:`UBOOT_CONFIG_MAKE_OPTS` is handled, see the
+      :ref:`ref-classes-uboot-config` class.
+
    :term:`UBOOT_DTB_LOADADDRESS`
       Specifies the load address for the dtb image used by U-Boot. During FIT

image creation, the :term:UBOOT_DTB_LOADADDRESS variable is used in

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 11064

Quoted 6 lines
documentation/ref-manual/variables.rst +3 -0
@@ -10980,6 +11059,12 @@ system and gives an overview of their function and contents.
 
       See the :ref:`ref-classes-uboot-sign` class for details.
 
+   :term:`UBOOT_FRAGMENTS`
+      The :term:`UBOOT_FRAGMENTS` variable can be used to pass extra config
+      fragments from the source tree to ``make`` when U-Boot is configured.

Once again we should specify from what the paths here are relative to, and maybe provide an example. Maybe somewhat of a realistic example, maybe with a path leading to some configuration name. Any existing fragment in mainline U-boot maybe?

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 11070

Quoted 6 lines
documentation/ref-manual/variables.rst +3 -0
+
+      See the :ref:`ref-classes-uboot-config` class for more information.
+
    :term:`UBOOT_INITIAL_ENV_BINARY`
       This variable enables the generation of the U-Boot initial environment in
       binary format.

Thanks a lot for the patch!
Antonin

Signature · 3 lines
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com