ref-manual: Document updated UBOOT_CONFIG flow
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
@@ -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
Hi,
Quoted 39 lines · Ryan Eatmon via lists.yoctoproject.org
The
UBOOT_CONFIGflow 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
Signed-off-by Ryan Eatmon <[email protected]>--- 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@@ -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
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 FITimage creation, the :term:
UBOOT_DTB_LOADADDRESSvariable 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