ref-manual: Document updated UBOOT_CONFIG flow
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
Signed-off-by Ryan Eatmon <[email protected]>
---
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
@@ -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
Hi,
Thanks, I'll merge this patch with the following typo fixes:
documentation/ref-manual/variables.rst +6 -6
@@ -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
Antonin Godard
AppliedApplied, thanks!
[1/1] ref-manual: Document updated UBOOT_CONFIG flow
commit: d3f9b0a5a13ba94a7f9f7945c370ac0685ab6d62