ref-manual/classes.rst: uboot-config: improve documentation

Improve the documentation of the uboot-config class. It was not
explaining any of its entry in UBOOT_CONFIG. Mention that using
UBOOT_CONFIG and UBOOT_MACHINE at the same time is not possible.

(From yocto-docs rev: 3bbd85798f4c9a8b7f930e9f156cf6e970593da0)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 52 insertions, 6 deletions

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index f77f99f964..b92b9e28b3 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -3169,15 +3169,61 @@ variable using the "type" varflag. Here is an example::
 ``uboot-config``
 ================
 
-The :ref:`ref-classes-uboot-config` class provides support for U-Boot configuration for
-a machine. Specify the machine in your recipe as follows::
+The :ref:`ref-classes-uboot-config` class provides support for configuring one
+or more U-Boot build configurations.
 
-   UBOOT_CONFIG ??= <default>
-   UBOOT_CONFIG[foo] = "config,images,binary"
+There are two ways to configure the recipe for your machine:
 
-You can also specify the machine using this method::
+-  Using :term:`UBOOT_CONFIG` variable. For example::
 
-   UBOOT_MACHINE = "config"
+      UBOOT_CONFIG ??= "foo bar"
+      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
+   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`, that can take up to three comma-separated options
+   (``config,images,binary``):
+
+   -  ``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.*
+
+   -  ``images``: 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 empty.
+
+   -  ``binary``: 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 unset.
+
+-  Or, 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_MACHINE` and :term:`UBOOT_CONFIG` at the same time is not
+possible.
 
 See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
 information.