Skip to contentSkip to conversation

ref-manual: Document updated UBOOT_CONFIG flow

PATCH Applied Ryan Eatmon 2 participants 3 messages Jan 27 – Feb 13

lore
Share & tools
lore
#0 lore raw

PATCH v2 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] https://git.openembedded.org/openembedded-core/commit/?id=cd9e7304481b24b27df61c03ad73496d18e4d47c

---
v2: - Added missing commit URL.
- Applied feedback from Antonin Godard.

 documentation/ref-manual/classes.rst   | 112 ++++++++++++++++++++++---
 documentation/ref-manual/variables.rst | 109 ++++++++++++++++++++++--
 2 files changed, 201 insertions(+), 20 deletions(-)
documentation/ref-manual/classes.rst +100 -12
index 2e219a59c..0e36c6c0d 100644
@@ -3269,13 +3269,104 @@ 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.  For exmaple::
+
+      UBOOT_CONFIG = "foo"
+      UBOOT_CONFIG[foo] = "config"
+      UBOOT_CONFIG[bar] = "config2"
+
+   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.*
+
+      See the documentation of :term:`UBOOT_CONFIG` for more information.
+
+   -  ``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.
+
+      See the documentation of :term:`UBOOT_CONFIG_IMAGE_FSTYPES` for more information.
+
+   -  ``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.
+
+      See the documentation of :term:`UBOOT_CONFIG_BINARY` for more information.
+
+   -  ``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.
+
+      See the documentation of :term:`UBOOT_CONFIG_MAKE_OPTS` for more information.
+
+   -  ``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.
+
+      See the documentation of :term:`UBOOT_CONFIG_FRAGMENTS` for more information.
+
+-  Or, a legacy method using the :term:`UBOOT_CONFIG` variable by itself.
+   *This method is being deprecated, see note below.*  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 +3404,12 @@ 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::
+.. note::
 
-      UBOOT_MACHINE = "config"
-      UBOOT_BINARY = "u-boot.bin"
+   The legacy flow has been deprecated.  It is recommended to not use this
+   legacy flow as any future extensions to the control knobs will be not added
+   to this methodology.  This functionality will be removed after the wrynose
+   LTS release.
 
 Using :term:`UBOOT_MACHINE` and :term:`UBOOT_CONFIG` at the same time is not
 possible.
documentation/ref-manual/variables.rst +101 -8

136 lines not on this page · raw message

Signature · 1 line
2.43.0
#1 lore raw

Hi,

Thanks, I'll merge this patch with the following typo fixes:

documentation/ref-manual/variables.rst +6 -6
index 595b90f87..a7c92e326 100644
@@ -10692,7 +10692,7 @@ system and gives an overview of their function and contents.
       the "sd..." configurations define an individual name for
       :term:`UBOOT_CONFIG_BINARY`.
 
-      For more information on how the :term:`UBOOT_CONFIG` is handled, see the
+      For more information on how the :term:`UBOOT_CONFIG` variable is handled, see the
       :ref:`ref-classes-uboot-config` class.
 
    :term:`UBOOT_CONFIG_BINARY`
@@ -10725,15 +10725,15 @@ system and gives an overview of their function and contents.
          UBOOT_CONFIG_FRAGMENTS[foo] = "frag1 frag2"
          UBOOT_CONFIG_FRAGMENTS[bar] = "frag3"
 
-      Specify a list of fragments from the source tree that should be combined
+      It specifies a list of fragments from the source tree that should be combined
       with the defconfig from :term:`UBOOT_CONFIG` that are used during ``do_configure()``
-      to configure the build.  These fragments are located in same 
+      to configure the build.  These fragments are located in same
       ``${S}/configs/`` directory as the defconfig.
 
       This option is not required and you only need to specify it for
       configs that need them.
 
-      For more information on how the :term:`UBOOT_CONFIG_FRAGMENTS` is handled, see the
+      For more information on how the :term:`UBOOT_CONFIG_FRAGMENTS` variable is handled, see the
       :ref:`ref-classes-uboot-config` class.
 
    :term:`UBOOT_CONFIG_IMAGE_FSTYPES`
@@ -10750,8 +10750,8 @@ system and gives an overview of their function and contents.
       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
-      :ref:`ref-classes-uboot-config` class.
+      For more information on how the :term:`UBOOT_CONFIG_IMAGE_FSTYPES`
+      variable is handled, see the :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

Antonin

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