[kirkstone][PATCH 0/6] documentation backports

[kirkstone][PATCH 0/6] documentation backports

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>


Enguerrand de Ribaucourt (1):
  manuals: document VSCode extension

Jörg Sommer (1):
  documentation: Add UBOOT_BINARY, extend UBOOT_CONFIG

Maxin B. John (1):
  ref-manual: classes: remove insserv bbclass

Michael Opdenacker (2):
  contributor-guide: use "apt" instead of "aptitude"
  ref-manual: resources: sync with master branch

Simone Weiß (1):
  dev-manual: start.rst: update use of Download page

 .../contributor-guide/submit-changes.rst      |  2 +-
 documentation/dev-manual/building.rst         |  4 ++
 documentation/dev-manual/start.rst            | 33 ++++++---
 .../development-environment.rst               |  8 +++
 documentation/overview-manual/yp-intro.rst    | 20 ++++++
 documentation/ref-manual/classes.rst          | 12 +---
 documentation/ref-manual/resources.rst        | 71 ++++++++++---------
 documentation/ref-manual/variables.rst        | 39 +++++-----
 documentation/what-i-wish-id-known.rst        |  7 ++
 9 files changed, 124 insertions(+), 72 deletions(-)

-- 
2.34.1

[kirkstone][PATCH 1/6] contributor-guide: use "apt" instead of "aptitude"

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

As used in the rest of the manual.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/contributor-guide/submit-changes.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
index 289ec1383c..86f73c1dd0 100644
--- a/documentation/contributor-guide/submit-changes.rst
+++ b/documentation/contributor-guide/submit-changes.rst
@@ -57,7 +57,7 @@ Set up Git
 The first thing to do is to install Git packages. Here is an example
 on Debian and Ubuntu::
 
-   sudo aptitude install git-core git-email
+   sudo apt install git-core git-email
 
 Then, you need to set a name and e-mail address that Git will
 use to identify your commits::
-- 
2.34.1

[kirkstone][PATCH 2/6] dev-manual: start.rst: update use of Download page

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Simone Weiß <simone.p.weiss@posteo.com>

The yocto website has changed its structure. Update the section for
Accessing the Downloads page to match the new structure.

Signed-off-by: Simone Weiß <simone.p.weiss@posteo.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/start.rst | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index 3bc4244595..5a81506a9b 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -642,7 +642,7 @@ Follow these steps to locate and download a particular tarball:
 Using the Downloads Page
 ------------------------
 
-The :yocto_home:`Yocto Project Website <>` uses a "DOWNLOADS" page
+The :yocto_home:`Yocto Project Website <>` uses a "RELEASES" page
 from which you can locate and download tarballs of any Yocto Project
 release. Rather than Git repositories, these files represent snapshot
 tarballs similar to the tarballs located in the Index of Releases
@@ -651,11 +651,13 @@ described in the ":ref:`dev-manual/start:accessing index of releases`" section.
 1. *Go to the Yocto Project Website:* Open The
    :yocto_home:`Yocto Project Website <>` in your browser.
 
-2. *Get to the Downloads Area:* Select the "DOWNLOADS" item from the
-   pull-down "SOFTWARE" tab menu near the top of the page.
+#. *Get to the Downloads Area:* Select the "RELEASES" item from the
+   pull-down "DEVELOPMENT" tab menu near the top of the page.
 
-3. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to
-   display and choose a recent or past supported Yocto Project release
+#. *Select a Yocto Project Release:* On the top of the "RELEASE" page currently
+   supported releases are displayed, further down past supported Yocto Project
+   releases are visible. The "Download" links in the rows of the table there
+   will lead to the download tarballs for the release
    (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth).
 
    .. note::
@@ -666,9 +668,9 @@ described in the ":ref:`dev-manual/start:accessing index of releases`" section.
    You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto
    Project releases.
 
-4. *Download Tools or Board Support Packages (BSPs):* From the
-   "DOWNLOADS" page, you can download tools or BSPs as well. Just scroll
-   down the page and look for what you need.
+#. *Download Tools or Board Support Packages (BSPs):* Next to the tarballs you
+   will find download tools or BSPs as well. Just select a Yocto Project
+   release and look for what you need.
 
 Cloning and Checking Out Branches
 =================================
-- 
2.34.1

[kirkstone][PATCH 3/6] ref-manual: classes: remove insserv bbclass

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Maxin B. John <maxin.john@gmail.com>

insserv.bbclass was removed from oe-core:

commit e6bb5dbb62257a7de730ea9085dfd89520f3e47d
Author: Richard Purdie <richard.purdie@linuxfoundation.org>
Date:   Sun May 10 12:30:49 2015 +0100

insserv: Remove

Signed-off-by: Maxin John <maxin.john@gmail.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/classes.rst | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 6074ea0f52..0677157b3b 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1462,16 +1462,6 @@ Here are the tests you can list with the :term:`WARN_QA` and
    automatically get these versions. Consequently, you should only need
    to explicitly add dependencies to binary driver recipes.
 
-.. _ref-classes-insserv:
-
-``insserv``
-===========
-
-The :ref:`ref-classes-insserv` class uses the ``insserv`` utility to update the order
-of symbolic links in ``/etc/rc?.d/`` within an image based on
-dependencies specified by LSB headers in the ``init.d`` scripts
-themselves.
-
 .. _ref-classes-kernel:
 
 ``kernel``
-- 
2.34.1

[kirkstone][PATCH 4/6] ref-manual: resources: sync with master branch

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/resources.rst | 66 +++++++++++++-------------
 1 file changed, 33 insertions(+), 33 deletions(-)

diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst
index a175a1db8e..8c3726e83b 100644
--- a/documentation/ref-manual/resources.rst
+++ b/documentation/ref-manual/resources.rst
@@ -63,26 +63,28 @@ and announcements. To subscribe to one of the following mailing lists,
 click on the appropriate URL in the following list and follow the
 instructions:
 
--  :yocto_lists:`/g/yocto` - General Yocto Project
+-  :yocto_lists:`/g/yocto` --- general Yocto Project
    discussion mailing list.
 
--  :oe_lists:`/g/openembedded-core` - Discussion mailing
+-  :oe_lists:`/g/openembedded-core` --- discussion mailing
    list about OpenEmbedded-Core (the core metadata).
 
--  :oe_lists:`/g/openembedded-devel` - Discussion
+-  :oe_lists:`/g/openembedded-devel` --- discussion
    mailing list about OpenEmbedded.
 
--  :oe_lists:`/g/bitbake-devel` - Discussion mailing
+-  :oe_lists:`/g/bitbake-devel` --- discussion mailing
    list about the :term:`BitBake` build tool.
 
--  :yocto_lists:`/g/poky` - Discussion mailing list
+-  :yocto_lists:`/g/poky` --- discussion mailing list
    about :term:`Poky`.
 
--  :yocto_lists:`/g/yocto-announce` - Mailing list to
+-  :yocto_lists:`/g/yocto-announce` --- mailing list to
    receive official Yocto Project release and milestone announcements.
 
-For more Yocto Project-related mailing lists, see the
-:yocto_home:`Yocto Project Website <>`.
+-  :yocto_lists:`/g/docs` --- discussion mailing list about the Yocto Project
+   documentation.
+
+See also :yocto_home:`the description of all mailing lists </community/mailing-lists/>`.
 
 .. _resources-irc:
 
@@ -103,93 +105,91 @@ Links and Related Documentation
 
 Here is a list of resources you might find helpful:
 
--  :yocto_home:`The Yocto Project Website <>`\ *:* The home site
+-  :yocto_home:`The Yocto Project Website <>`: The home site
    for the Yocto Project.
 
--  :yocto_wiki:`The Yocto Project Main Wiki Page <>`\ *:* The main wiki page for
+-  :yocto_wiki:`The Yocto Project Main Wiki Page <>`: The main wiki page for
    the Yocto Project. This page contains information about project
    planning, release engineering, QA & automation, a reference site map,
    and other resources related to the Yocto Project.
 
--  :oe_home:`OpenEmbedded <>`\ *:* The build system used by the
+-  :oe_home:`OpenEmbedded <>`: The build system used by the
    Yocto Project. This project is the upstream, generic, embedded
    distribution from which the Yocto Project derives its build system
    (Poky) and to which it contributes.
 
--  :oe_wiki:`BitBake </BitBake>`\ *:* The tool used to process metadata.
+-  :oe_wiki:`BitBake </BitBake>`: The tool used to process metadata.
 
--  :doc:`BitBake User Manual <bitbake:index>`\ *:* A comprehensive
+-  :doc:`BitBake User Manual <bitbake:index>`: A comprehensive
    guide to the BitBake tool. If you want information on BitBake, see
    this manual.
 
--  :doc:`/brief-yoctoprojectqs/index` *:* This
+-  :doc:`/brief-yoctoprojectqs/index`: This
    short document lets you experience building an image using the Yocto
    Project without having to understand any concepts or details.
 
--  :doc:`/overview-manual/index` *:* This manual provides overview
+-  :doc:`/overview-manual/index`: This manual provides overview
    and conceptual information about the Yocto Project.
 
--  :doc:`/dev-manual/index` *:* This manual is a "how-to" guide
+-  :doc:`/dev-manual/index`: This manual is a "how-to" guide
    that presents procedures useful to both application and system
    developers who use the Yocto Project.
 
--  :doc:`/sdk-manual/index` *manual :* This
+-  :doc:`/sdk-manual/index` manual: This
    guide provides information that lets you get going with the standard
    or extensible SDK. An SDK, with its cross-development toolchains,
    allows you to develop projects inside or outside of the Yocto Project
    environment.
 
--  :doc:`/bsp-guide/bsp` *:* This guide defines the structure
+-  :doc:`/bsp-guide/bsp`: This guide defines the structure
    for BSP components. Having a commonly understood structure encourages
    standardization.
 
--  :doc:`/kernel-dev/index` *:* This manual describes
+-  :doc:`/kernel-dev/index`: This manual describes
    how to work with Linux Yocto kernels as well as provides a bit of
    conceptual information on the construction of the Yocto Linux kernel
    tree.
 
--  :doc:`/ref-manual/index` *:* This
+-  :doc:`/ref-manual/index`: This
    manual provides reference material such as variable, task, and class
    descriptions.
 
--  :yocto_docs:`Yocto Project Mega-Manual </singleindex.html>`\ *:* This manual
+-  :yocto_docs:`Yocto Project Mega-Manual </singleindex.html>`: This manual
    is simply a single HTML file comprised of the bulk of the Yocto
    Project manuals. It makes it easy to search for phrases and terms used
    in the Yocto Project documentation set.
 
--  :doc:`/profile-manual/index` *:* This manual presents a set of
+-  :doc:`/profile-manual/index`: This manual presents a set of
    common and generally useful tracing and profiling schemes along with
    their applications (as appropriate) to each tool.
 
--  :doc:`/toaster-manual/index` *:* This manual
+-  :doc:`/toaster-manual/index`: This manual
    introduces and describes how to set up and use Toaster. Toaster is an
    Application Programming Interface (API) and web-based interface to
    the :term:`OpenEmbedded Build System`, which uses
    BitBake, that reports build information.
 
--  :yocto_wiki:`FAQ </FAQ>`\ *:* A list of commonly asked
+-  :yocto_wiki:`FAQ </FAQ>`: A list of commonly asked
    questions and their answers.
 
--  *Release Notes:* Features, updates and known issues for the current
-   release of the Yocto Project. To access the Release Notes, go to the
-   :yocto_home:`Downloads </software-overview/downloads>` page on
-   the Yocto Project website and click on the "RELEASE INFORMATION" link
-   for the appropriate release.
+-  :doc:`Release Information </migration-guides/index>`:
+   Migration guides, release notes, new features, updates and known issues
+   for the current and past releases of the Yocto Project.
 
--  :yocto_bugs:`Bugzilla <>`\ *:* The bug tracking application
+-  :yocto_bugs:`Bugzilla <>`: The bug tracking application
    the Yocto Project uses. If you find problems with the Yocto Project,
    you should report them using this application.
 
 -  :yocto_wiki:`Bugzilla Configuration and Bug Tracking Wiki Page
-   </Bugzilla_Configuration_and_Bug_Tracking>`\ *:*
+   </Bugzilla_Configuration_and_Bug_Tracking>`:
    Information on how to get set up and use the Yocto Project
    implementation of Bugzilla for logging and tracking Yocto Project
    defects.
 
--  *Internet Relay Chat (IRC):* Two IRC channels on
+-  Internet Relay Chat (IRC): Two IRC channels on
    `Libera Chat <https://libera.chat/>`__ are
    available for Yocto Project and OpenEmbeddded discussions: ``#yocto`` and
    ``#oe``, respectively.
 
--  `Quick EMUlator (QEMU) <https://wiki.qemu.org/Index.html>`__\ *:* An
+-  `Quick EMUlator (QEMU) <https://wiki.qemu.org/Index.html>`__: An
    open-source machine emulator and virtualizer.
-- 
2.34.1

[kirkstone][PATCH 5/6] manuals: document VSCode extension

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Enguerrand de Ribaucourt <enguerrand.de-ribaucourt@savoirfairelinux.com>

The VSCode extension is now officially maintained and published by the
Yocto Project so it should be referenced in the manuals to help users
discover it.

I located the most relevant places to reference the extension by looking
at how the old Eclipse plugin was documented in the 2.6 manuals as well
as the current Toaster references.

Signed-off-by: Enguerrand de Ribaucourt <enguerrand.de-ribaucourt@savoirfairelinux.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/building.rst         |  4 ++++
 documentation/dev-manual/start.rst            | 15 +++++++++++---
 .../development-environment.rst               |  8 ++++++++
 documentation/overview-manual/yp-intro.rst    | 20 +++++++++++++++++++
 documentation/ref-manual/resources.rst        |  5 +++++
 documentation/what-i-wish-id-known.rst        |  7 +++++++
 6 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst
index a395793493..e964bd1aee 100644
--- a/documentation/dev-manual/building.rst
+++ b/documentation/dev-manual/building.rst
@@ -32,6 +32,10 @@ build host running Linux.
       OpenEmbedded build system, see the
       :doc:`/brief-yoctoprojectqs/index` document.
 
+   -  You can also use the `Yocto Project BitBake
+      <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+      extension for Visual Studio Code to build images.
+
 The build process creates an entire Linux distribution from source and
 places it in your :term:`Build Directory` under ``tmp/deploy/images``. For
 detailed information on the build process using BitBake, see the
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index 5a81506a9b..44503a5183 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -332,7 +332,10 @@ to use the Extensible SDK, see the ":doc:`/sdk-manual/extensible`" Chapter in th
 Project Application Development and the Extensible Software Development
 Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`/kernel-dev/index`. If you are going to use
 Toaster, see the ":doc:`/toaster-manual/setup-and-use`"
-section in the Toaster User Manual.
+section in the Toaster User Manual. If you are a VSCode user, you can configure
+the `Yocto Project BitBake
+<https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+extension accordingly.
 
 Setting Up to Use CROss PlatformS (CROPS)
 -----------------------------------------
@@ -424,7 +427,10 @@ section. If you are going to use the Extensible SDK container, see the
 Project Application Development and the Extensible Software Development
 Kit (eSDK) manual. If you are going to use the Toaster container, see
 the ":doc:`/toaster-manual/setup-and-use`"
-section in the Toaster User Manual.
+section in the Toaster User Manual. If you are a VSCode user, you can configure
+the `Yocto Project BitBake
+<https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+extension accordingly.
 
 Setting Up to Use Windows Subsystem For Linux (WSLv2)
 -----------------------------------------------------
@@ -554,7 +560,10 @@ Extensible SDK container, see the ":doc:`/sdk-manual/extensible`" Chapter in the
 Project Application Development and the Extensible Software Development
 Kit (eSDK) manual. If you are going to use the Toaster container, see
 the ":doc:`/toaster-manual/setup-and-use`"
-section in the Toaster User Manual.
+section in the Toaster User Manual. If you are a VSCode user, you can configure
+the `Yocto Project BitBake
+<https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+extension accordingly.
 
 Locating Yocto Project Source Files
 ===================================
diff --git a/documentation/overview-manual/development-environment.rst b/documentation/overview-manual/development-environment.rst
index 332cea836d..30c7af4531 100644
--- a/documentation/overview-manual/development-environment.rst
+++ b/documentation/overview-manual/development-environment.rst
@@ -132,6 +132,14 @@ are several ways of working in the Yocto Project environment:
    Toaster and on how to use Toaster in general, see the
    :doc:`/toaster-manual/index`.
 
+-  *Using the VSCode Extension:* You can use the `Yocto Project BitBake
+   <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+   extension for Visual Studio Code to start your BitBake builds through a
+   graphical user interface.
+
+   Learn more about the VSCode Extension on the `extension's marketplace page
+   <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__.
+
 Yocto Project Source Repositories
 =================================
 
diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst
index 25dc08b09d..f7cd2486af 100644
--- a/documentation/overview-manual/yp-intro.rst
+++ b/documentation/overview-manual/yp-intro.rst
@@ -340,6 +340,18 @@ the Yocto Project:
    view information about builds. For information on Toaster, see the
    :doc:`/toaster-manual/index`.
 
+-  *VSCode IDE Extension:* The `Yocto Project BitBake
+   <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+   extension for Visual Studio Code provides a rich set of features for working
+   with BitBake recipes. The extension provides syntax highlighting,
+   hover tips, and completion for BitBake files as well as embedded Python and
+   Bash languages. Additional views and commands allow you to efficiently
+   browse, build and edit recipes. It also provides SDK integration for
+   cross-compiling and debugging through ``devtool``.
+
+   Learn more about the VSCode Extension on the `extension's frontpage
+   <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__.
+
 Production Tools
 ----------------
 
@@ -610,6 +622,14 @@ Build Host runs, you have several choices.
    For information about and how to use Toaster, see the
    :doc:`/toaster-manual/index`.
 
+-  *Using the VSCode Extension:* You can use the `Yocto Project BitBake
+   <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+   extension for Visual Studio Code to start your BitBake builds through a
+   graphical user interface.
+
+   Learn more about the VSCode Extension on the `extension's marketplace page
+   <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+
 Reference Embedded Distribution (Poky)
 ======================================
 
diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst
index 8c3726e83b..8e54ac87c9 100644
--- a/documentation/ref-manual/resources.rst
+++ b/documentation/ref-manual/resources.rst
@@ -169,6 +169,11 @@ Here is a list of resources you might find helpful:
    the :term:`OpenEmbedded Build System`, which uses
    BitBake, that reports build information.
 
+-  `Yocto Project BitBake extension for VSCode
+   <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__:
+   This extension provides a rich feature set when working with BitBake recipes
+   within the Visual Studio Code IDE.
+
 -  :yocto_wiki:`FAQ </FAQ>`: A list of commonly asked
    questions and their answers.
 
diff --git a/documentation/what-i-wish-id-known.rst b/documentation/what-i-wish-id-known.rst
index 4843f02276..c21810d49b 100644
--- a/documentation/what-i-wish-id-known.rst
+++ b/documentation/what-i-wish-id-known.rst
@@ -213,6 +213,13 @@ contact us with other suggestions.
      OpenEmbedded build system. If you are interested in using this type of
      interface to create images, see the :doc:`/toaster-manual/index`.
 
+   * **Discover the VSCode extension**: The `Yocto Project BitBake
+     <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
+     extension for the Visual Studio Code IDE provides language features and
+     commands for working with the Yocto Project. If you are interested in using
+     this extension, visit its `marketplace page
+     <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__.
+
    * **Have Available the Yocto Project Reference Manual**: Unlike the rest of
      the Yocto Project manual set, this manual is comprised of material suited
      for reference rather than procedures. You can get build details, a closer
-- 
2.34.1

[kirkstone][PATCH 6/6] documentation: Add UBOOT_BINARY, extend UBOOT_CONFIG

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Jörg Sommer <joerg.sommer@navimatix.de>

UBOOT_CONFIG accepts a third parameter for the UBOOT_BINARY that isn't
documented. To show its usage another example from the meta-freescale layer
was picked.

Signed-off-by: Jörg Sommer <joerg.sommer@navimatix.de>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/classes.rst   |  2 +-
 documentation/ref-manual/variables.rst | 39 +++++++++++++++-----------
 2 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 0677157b3b..216b236e33 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -3131,7 +3131,7 @@ The :ref:`ref-classes-uboot-config` class provides support for U-Boot configurat
 a machine. Specify the machine in your recipe as follows::
 
    UBOOT_CONFIG ??= <default>
-   UBOOT_CONFIG[foo] = "config,images"
+   UBOOT_CONFIG[foo] = "config,images,binary"
 
 You can also specify the machine using this method::
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index fe0b993bd8..ae14c450dd 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8932,23 +8932,30 @@ system and gives an overview of their function and contents.
       See the machine include files in the :term:`Source Directory`
       for these features.
 
+   :term:`UBOOT_BINARY`
+      Specifies the name of the binary build by U-Boot.
+
    :term:`UBOOT_CONFIG`
-      Configures the :term:`UBOOT_MACHINE` and can
-      also define :term:`IMAGE_FSTYPES` for individual
-      cases.
-
-      Following is an example from the ``meta-fsl-arm`` layer. ::
-
-         UBOOT_CONFIG ??= "sd"
-         UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
-         UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
-         UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
-         UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
-
-      In this example, "sd" is selected as the configuration of the possible four for the
-      :term:`UBOOT_MACHINE`. The "sd" configuration defines
-      "mx6qsabreauto_config" as the value for :term:`UBOOT_MACHINE`, while the
-      "sdcard" specifies the :term:`IMAGE_FSTYPES` to use for the U-Boot image.
+      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`.
+
+      Following is an 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[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"
+
+      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.
 
       For more information on how the :term:`UBOOT_CONFIG` is handled, see the
       :ref:`uboot-config <ref-classes-uboot-config>`
-- 
2.34.1