1 files changed, 111 insertions, 148 deletions

diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
index dd0b76bc31..4c463503f6 100644
--- a/documentation/kernel-dev/advanced.rst
+++ b/documentation/kernel-dev/advanced.rst
@@ -21,7 +21,7 @@ is the ``yocto-kernel-cache`` Git repository. You can find this repository
 grouped under the "Yocto Linux Kernel" heading in the
 :yocto_git:`Yocto Project Source Repositories <>`.
 
-Kernel development tools ("kern-tools") exist also in the Yocto Project
+Kernel development tools ("kern-tools") are also available in the Yocto Project
 Source Repositories under the "Yocto Linux Kernel" heading in the
 ``yocto-kernel-tools`` Git repository. The recipe that builds these
 tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in
@@ -46,18 +46,18 @@ linux-yocto recipe.
 
 Every linux-yocto style recipe must define the
 :term:`KMACHINE` variable. This
-variable is typically set to the same value as the ``MACHINE`` variable,
+variable is typically set to the same value as the :term:`MACHINE` variable,
 which is used by :term:`BitBake`.
 However, in some cases, the variable might instead refer to the
-underlying platform of the ``MACHINE``.
+underlying platform of the :term:`MACHINE`.
 
-Multiple BSPs can reuse the same ``KMACHINE`` name if they are built
+Multiple BSPs can reuse the same :term:`KMACHINE` name if they are built
 using the same BSP description. Multiple Corei7-based BSPs could share
-the same "intel-corei7-64" value for ``KMACHINE``. It is important to
-realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE``
+the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to
+realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE`
 is the machine type within a BSP Layer. Even with this distinction,
-however, these two variables can hold the same value. See the `BSP
-Descriptions <#bsp-descriptions>`__ section for more information.
+however, these two variables can hold the same value. See the
+":ref:`kernel-dev/advanced:bsp descriptions`" section for more information.
 
 Every linux-yocto style recipe must also indicate the Linux kernel
 source repository branch used to build the Linux kernel. The
@@ -66,12 +66,10 @@ to indicate the branch.
 
 .. note::
 
-   You can use the ``KBRANCH`` value to define an alternate branch typically
-   with a machine override as shown here from the ``meta-yocto-bsp`` layer:
-   ::
-
-           KBRANCH_edgerouter = "standard/edgerouter"
+   You can use the :term:`KBRANCH` value to define an alternate branch typically
+   with a machine override as shown here from the ``meta-yocto-bsp`` layer::
 
+      KBRANCH:beaglebone-yocto = "standard/beaglebone"
 
 The linux-yocto style recipes can optionally define the following
 variables:
@@ -82,49 +80,47 @@ variables:
 
 :term:`LINUX_KERNEL_TYPE`
 defines the kernel type to be used in assembling the configuration. If
-you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard".
-Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search
+you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard".
+Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` defines the search
 arguments used by the kernel tools to find the appropriate description
 within the kernel Metadata with which to build out the sources and
 configuration. The linux-yocto recipes define "standard", "tiny", and
-"preempt-rt" kernel types. See the "`Kernel Types <#kernel-types>`__"
+"preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
 section for more information on kernel types.
 
 During the build, the kern-tools search for the BSP description file
-that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE``
+that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE`
 variables passed in from the recipe. The tools use the first BSP
 description they find that matches both variables. If the tools cannot find
 a match, they issue a warning.
 
-The tools first search for the ``KMACHINE`` and then for the
-``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they
-will use the sources from the ``KBRANCH`` and any configuration
+The tools first search for the :term:`KMACHINE` and then for the
+:term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they
+will use the sources from the :term:`KBRANCH` and any configuration
 specified in the :term:`SRC_URI`.
 
 You can use the
 :term:`KERNEL_FEATURES`
 variable to include features (configuration fragments, patches, or both)
-that are not already included by the ``KMACHINE`` and
-``LINUX_KERNEL_TYPE`` variable combination. For example, to include a
-feature specified as "features/netfilter/netfilter.scc", specify:
-::
+that are not already included by the :term:`KMACHINE` and
+:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a
+feature specified as "features/netfilter/netfilter.scc", specify::
 
    KERNEL_FEATURES += "features/netfilter/netfilter.scc"
 
 To include a
 feature called "cfg/sound.scc" just for the ``qemux86`` machine,
-specify:
-::
+specify::
 
-   KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc"
+   KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc"
 
 The value of
-the entries in ``KERNEL_FEATURES`` are dependent on their location
+the entries in :term:`KERNEL_FEATURES` are dependent on their location
 within the kernel Metadata itself. The examples here are taken from the
 ``yocto-kernel-cache`` repository. Each branch of this repository
 contains "features" and "cfg" subdirectories at the top-level. For more
-information, see the "`Kernel Metadata
-Syntax <#kernel-metadata-syntax>`__" section.
+information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`"
+section.
 
 Kernel Metadata Syntax
 ======================
@@ -148,7 +144,7 @@ Features aggregate sources in the form of patches and configuration
 fragments into a modular reusable unit. You can use features to
 implement conceptually separate kernel Metadata descriptions such as
 pure configuration fragments, simple patches, complex features, and
-kernel types. `Kernel types <#kernel-types>`__ define general kernel
+kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel
 features and policy to be reused in the BSPs.
 
 BSPs define hardware-specific features and aggregate them with kernel
@@ -157,8 +153,7 @@ types to form the final description of what will be assembled and built.
 While the kernel Metadata syntax does not enforce any logical separation
 of configuration fragments, patches, features or kernel types, best
 practices dictate a logical separation of these types of Metadata. The
-following Metadata file hierarchy is recommended:
-::
+following Metadata file hierarchy is recommended::
 
    base/
       bsp/
@@ -167,10 +162,9 @@ following Metadata file hierarchy is recommended:
       ktypes/
       patches/
 
-The ``bsp`` directory contains the `BSP
-descriptions <#bsp-descriptions>`__. The remaining directories all
-contain "features". Separating ``bsp`` from the rest of the structure
-aids conceptualizing intended usage.
+The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`.
+The remaining directories all contain "features". Separating ``bsp`` from the
+rest of the structure aids conceptualizing intended usage.
 
 Use these guidelines to help place your ``scc`` description files within
 the structure:
@@ -188,7 +182,7 @@ the structure:
    order to define a base kernel policy or major kernel type to be
    reused across multiple BSPs, place the file in ``ktypes`` directory.
 
-These distinctions can easily become blurred - especially as out-of-tree
+These distinctions can easily become blurred --- especially as out-of-tree
 features slowly merge upstream over time. Also, remember that how the
 description files are placed is a purely logical organization and has no
 impact on the functionality of the kernel Metadata. There is no impact
@@ -198,11 +192,12 @@ contain "features" as far as the kernel tools are concerned.
 Paths used in kernel Metadata files are relative to base, which is
 either
 :term:`FILESEXTRAPATHS` if
-you are creating Metadata in `recipe-space <#recipe-space-metadata>`__,
+you are creating Metadata in
+:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`,
 or the top level of
 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>`
-if you are creating `Metadata outside of the
-recipe-space <#metadata-outside-the-recipe-space>`__.
+if you are creating
+:ref:`kernel-dev/advanced:metadata outside the recipe-space`.
 
 .. [1]
    ``scc`` stands for Series Configuration Control, but the naming has
@@ -222,8 +217,7 @@ used with the ``linux-yocto-4.12`` kernel as defined outside of the
 recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
 two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
 ``cfg`` directory of the ``yocto-4.12`` branch in the
-``yocto-kernel-cache`` Git repository:
-::
+``yocto-kernel-cache`` Git repository::
 
    cfg/smp.scc:
       define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
@@ -265,8 +259,7 @@ non-hardware fragment.
 
 As described in the
 ":ref:`kernel-dev/common:validating configuration`" section, you can
-use the following BitBake command to audit your configuration:
-::
+use the following BitBake command to audit your configuration::
 
    $ bitbake linux-yocto -c kernel_configcheck -f
 
@@ -287,8 +280,7 @@ in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
 ``yocto-kernel-cache`` Git repository.
 
 The following listings show the ``build.scc`` file and part of the
-``modpost-mask-trivial-warnings.patch`` file:
-::
+``modpost-mask-trivial-warnings.patch`` file::
 
    patches/build/build.scc:
       patch arm-serialize-build-targets.patch
@@ -311,8 +303,8 @@ The following listings show the ``build.scc`` file and part of the
                         .
                         .
                         .
-                char *dump_write = NULL, *files_source = NULL;
-                int opt;
+                char *dump_write = NULL, *files_source = NULL;
+                int opt;
       --
       2.10.1
 
@@ -320,7 +312,7 @@ The following listings show the ``build.scc`` file and part of the
 
 The description file can
 include multiple patch statements where each statement handles a single
-patch. In the example ``build.scc`` file, five patch statements exist
+patch. In the example ``build.scc`` file, there are five patch statements
 for the five patches in the directory.
 
 You can create a typical ``.patch`` file using ``diff -Nurp`` or
@@ -334,8 +326,7 @@ Features
 
 Features are complex kernel Metadata types that consist of configuration
 fragments, patches, and possibly other feature description files. As an
-example, consider the following generic listing:
-::
+example, consider the following generic listing::
 
    features/myfeature.scc
       define KFEATURE_DESCRIPTION "Enable myfeature"
@@ -352,34 +343,30 @@ as how an additional feature description file is included with the
 
 Typically, features are less granular than configuration fragments and
 are more likely than configuration fragments and patches to be the types
-of things you want to specify in the ``KERNEL_FEATURES`` variable of the
-Linux kernel recipe. See the "`Using Kernel Metadata in a
-Recipe <#using-kernel-metadata-in-a-recipe>`__" section earlier in the
-manual.
+of things you want to specify in the :term:`KERNEL_FEATURES` variable of the
+Linux kernel recipe. See the
+":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
+in the manual.
 
 Kernel Types
 ------------
 
-A kernel type defines a high-level kernel policy by aggregating
-non-hardware configuration fragments with patches you want to use when
-building a Linux kernel of a specific type (e.g. a real-time kernel).
-Syntactically, kernel types are no different than features as described
-in the "`Features <#features>`__" section. The
-:term:`LINUX_KERNEL_TYPE`
-variable in the kernel recipe selects the kernel type. For example, in
-the ``linux-yocto_4.12.bb`` kernel recipe found in
-``poky/meta/recipes-kernel/linux``, a
-:ref:`require <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directive
-includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
-which has the following statement that defines the default kernel type:
-::
+A kernel type defines a high-level kernel policy by aggregating non-hardware
+configuration fragments with patches you want to use when building a Linux
+kernel of a specific type (e.g. a real-time kernel). Syntactically, kernel
+types are no different than features as described in the
+":ref:`kernel-dev/advanced:features`" section. The :term:`LINUX_KERNEL_TYPE`
+variable in the kernel recipe selects the kernel type. For example, in the
+``linux-yocto_4.12.bb`` kernel recipe found in ``poky/meta/recipes-kernel/linux``, a
+:ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
+directive includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
+which has the following statement that defines the default kernel type::
 
    LINUX_KERNEL_TYPE ??= "standard"
 
 Another example would be the real-time kernel (i.e.
 ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
-type as follows:
-::
+type as follows::
 
    LINUX_KERNEL_TYPE = "preempt-rt"
 
@@ -412,8 +399,7 @@ for Linux Yocto kernels:
 For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
 ``standard.scc``). Here is a partial listing for the ``standard.scc``
 file, which is found in the ``ktypes/standard`` directory of the
-``yocto-kernel-cache`` Git repository:
-::
+``yocto-kernel-cache`` Git repository::
 
    # Include this kernel type fragment to get the standard features and
    # configuration values.
@@ -482,15 +468,13 @@ Description Overview
 For simplicity, consider the following root BSP layer description files
 for the BeagleBone board. These files employ both a structure and naming
 convention for consistency. The naming convention for the file is as
-follows:
-::
+follows::
 
    bsp_root_name-kernel_type.scc
 
 Here are some example root layer
 BSP filenames for the BeagleBone Board BSP, which is supported by the
-Yocto Project:
-::
+Yocto Project::
 
    beaglebone-standard.scc
    beaglebone-preempt-rt.scc
@@ -498,8 +482,7 @@ Yocto Project:
 Each file uses the root name (i.e "beaglebone") BSP name followed by the
 kernel type.
 
-Examine the ``beaglebone-standard.scc`` file:
-::
+Examine the ``beaglebone-standard.scc`` file::
 
    define KMACHINE beaglebone
    define KTYPE standard
@@ -523,34 +506,31 @@ description as meeting the criteria set by the recipe being built. This
 example supports the "beaglebone" machine for the "standard" kernel and
 the "arm" architecture.
 
-Be aware that a hard link between the ``KTYPE`` variable and a kernel
-type description file does not exist. Thus, if you do not have the
+Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel
+type description file. Thus, if you do not have the
 kernel type defined in your kernel Metadata as it is here, you only need
 to ensure that the
 :term:`LINUX_KERNEL_TYPE`
-variable in the kernel recipe and the ``KTYPE`` variable in the BSP
+variable in the kernel recipe and the :term:`KTYPE` variable in the BSP
 description file match.
 
 To separate your kernel policy from your hardware configuration, you
 include a kernel type (``ktype``), such as "standard". In the previous
-example, this is done using the following:
-::
+example, this is done using the following::
 
    include ktypes/standard/standard.scc
 
 This file aggregates all the configuration
 fragments, patches, and features that make up your standard kernel
-policy. See the "`Kernel Types <#kernel-types>`__" section for more
+policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
 information.
 
 To aggregate common configurations and features specific to the kernel
-for `mybsp`, use the following:
-::
+for `mybsp`, use the following::
 
    include mybsp.scc
 
-You can see that in the BeagleBone example with the following:
-::
+You can see that in the BeagleBone example with the following::
 
    include beaglebone.scc
 
@@ -558,15 +538,13 @@ For information on how to break a complete ``.config`` file into the various
 configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section.
 
 Finally, if you have any configurations specific to the hardware that
-are not in a ``*.scc`` file, you can include them as follows:
-::
+are not in a ``*.scc`` file, you can include them as follows::
 
    kconf hardware mybsp-extra.cfg
 
 The BeagleBone example does not include these
 types of configurations. However, the Malta 32-bit board does
-("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:
-::
+("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
 
    define KMACHINE mti-malta32-le
    define KMACHINE qemumipsel
@@ -585,15 +563,7 @@ Example
 Many real-world examples are more complex. Like any other ``.scc`` file,
 BSP descriptions can aggregate features. Consider the Minnow BSP
 definition given the ``linux-yocto-4.4`` branch of the
-``yocto-kernel-cache`` (i.e.
-``yocto-kernel-cache/bsp/minnow/minnow.scc``):
-
-.. note::
-
-   Although the Minnow Board BSP is unused, the Metadata remains and is
-   being used here just as an example.
-
-::
+``yocto-kernel-cache`` (i.e. ``yocto-kernel-cache/bsp/minnow/minnow.scc``)::
 
    include cfg/x86.scc
    include features/eg20t/eg20t.scc
@@ -616,6 +586,11 @@ definition given the ``linux-yocto-4.4`` branch of the
    kconf hardware minnow.cfg
    kconf hardware minnow-dev.cfg
 
+.. note::
+
+   Although the Minnow Board BSP is unused, the Metadata remains and is
+   being used here just as an example.
+
 The ``minnow.scc`` description file includes a hardware configuration
 fragment (``minnow.cfg``) specific to the Minnow BSP as well as several
 more general configuration fragments and features enabling hardware
@@ -623,8 +598,7 @@ found on the machine. This ``minnow.scc`` description file is then
 included in each of the three "minnow" description files for the
 supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
 Consider the "minnow" description for the "standard" kernel type (i.e.
-``minnow-standard.scc``):
-::
+``minnow-standard.scc``)::
 
    define KMACHINE minnow
    define KTYPE standard
@@ -656,8 +630,7 @@ that defines all enabled hardware for the BSP that is common to all
 kernel types. Using this command significantly reduces duplication.
 
 Now consider the "minnow" description for the "tiny" kernel type (i.e.
-``minnow-tiny.scc``):
-::
+``minnow-tiny.scc``)::
 
    define KMACHINE minnow
    define KTYPE tiny
@@ -678,7 +651,7 @@ Notice again the three critical variables:
 :term:`KMACHINE`,
 :term:`KTYPE`, and
 :term:`KARCH`. Of these variables, only
-``KTYPE`` has changed to specify the "tiny" kernel type.
+:term:`KTYPE` has changed to specify the "tiny" kernel type.
 
 Kernel Metadata Location
 ========================
@@ -709,19 +682,17 @@ Recipe-Space Metadata
 ---------------------
 
 When stored in recipe-space, the kernel Metadata files reside in a
-directory hierarchy below
-:term:`FILESEXTRAPATHS`. For
-a linux-yocto recipe or for a Linux kernel recipe derived by copying and
-modifying
-``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to
-a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to
+directory hierarchy below :term:`FILESEXTRAPATHS`. For
+a linux-yocto recipe or for a Linux kernel recipe derived by copying
+:oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
+</openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`
+into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to
 ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
 See the ":ref:`kernel-dev/common:modifying an existing recipe`"
 section for more information.
 
 Here is an example that shows a trivial tree of kernel Metadata stored
-in recipe-space within a BSP layer:
-::
+in recipe-space within a BSP layer::
 
    meta-my_bsp_layer/
    `-- recipes-kernel
@@ -740,14 +711,13 @@ and fetches any files referenced in the ``.scc`` files by the
 ``include``, ``patch``, or ``kconf`` commands. Because of this, it is
 necessary to bump the recipe :term:`PR`
 value when changing the content of files not explicitly listed in the
-``SRC_URI``.
+:term:`SRC_URI`.
 
 If the BSP description is in recipe space, you cannot simply list the
-``*.scc`` in the ``SRC_URI`` statement. You need to use the following
-form from your kernel append file:
-::
+``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
+form from your kernel append file::
 
-   SRC_URI_append_myplatform = " \
+   SRC_URI:append:myplatform = " \
        file://myplatform;type=kmeta;destsuffix=myplatform \
        "
 
@@ -758,37 +728,35 @@ When stored outside of the recipe-space, the kernel Metadata files
 reside in a separate repository. The OpenEmbedded build system adds the
 Metadata to the build as a "type=kmeta" repository through the
 :term:`SRC_URI` variable. As an
-example, consider the following ``SRC_URI`` statement from the
-``linux-yocto_4.12.bb`` kernel recipe:
-::
-
-   SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
-              git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
+example, consider the following :term:`SRC_URI` statement from the
+``linux-yocto_5.15.bb`` kernel recipe::
 
+   SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \
+              git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-5.15;destsuffix=${KMETA};protocol=https"
 
 ``${KMETA}``, in this context, is simply used to name the directory into
 which the Git fetcher places the Metadata. This behavior is no different
-than any multi-repository ``SRC_URI`` statement used in a recipe (e.g.
+than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g.
 see the previous section).
 
 You can keep kernel Metadata in a "kernel-cache", which is a directory
 containing configuration fragments. As with any Metadata kept outside
-the recipe-space, you simply need to use the ``SRC_URI`` statement with
+the recipe-space, you simply need to use the :term:`SRC_URI` statement with
 the "type=kmeta" attribute. Doing so makes the kernel Metadata available
 during the configuration phase.
 
-If you modify the Metadata, you must not forget to update the ``SRCREV``
+If you modify the Metadata, you must not forget to update the :term:`SRCREV`
 statements in the kernel's recipe. In particular, you need to update the
 ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
 wish to use. Changing the data in these branches and not updating the
-``SRCREV`` statements to match will cause the build to fetch an older
+:term:`SRCREV` statements to match will cause the build to fetch an older
 commit.
 
 Organizing Your Source
 ======================
 
 Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
-kernel sources that have only a single branch - "master". This type of
+kernel sources that have only a single branch. This type of
 repository structure is fine for linear development supporting a single
 machine and architecture. However, if you work with multiple boards and
 architectures, a kernel source repository with multiple branches is more
@@ -797,11 +765,11 @@ board to boot. Sometimes, these patches are works-in-progress or
 fundamentally wrong, yet they are still necessary for specific boards.
 In these situations, you most likely do not want to include these
 patches in every kernel you build (i.e. have the patches as part of the
-lone "master" branch). It is situations like these that give rise to
+default branch). It is situations like these that give rise to
 multiple branches used within a Linux kernel sources Git repository.
 
-Repository organization strategies exist that maximize source reuse,
-remove redundancy, and logically order your changes. This section
+Here are repository organization strategies maximizing source reuse,
+removing redundancy, and logically ordering your changes. This section
 presents strategies for the following cases:
 
 -  Encapsulating patches in a feature description and only including the
@@ -825,11 +793,11 @@ Given this scenario, you do not need to create any branches in the
 source repository. Rather, you just take the static patches you need and
 encapsulate them within a feature description. Once you have the feature
 description, you simply include that into the BSP description as
-described in the "`BSP Descriptions <#bsp-descriptions>`__" section.
+described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section.
 
 You can find information on how to create patches and BSP descriptions
-in the "`Patches <#patches>`__" and "`BSP
-Descriptions <#bsp-descriptions>`__" sections.
+in the ":ref:`kernel-dev/advanced:patches`" and
+":ref:`kernel-dev/advanced:bsp descriptions`" sections.
 
 Machine Branches
 ----------------
@@ -837,21 +805,19 @@ Machine Branches
 When you have multiple machines and architectures to support, or you are
 actively working on board support, it is more efficient to create
 branches in the repository based on individual machines. Having machine
-branches allows common source to remain in the "master" branch with any
+branches allows common source to remain in the development branch with any
 features specific to a machine stored in the appropriate machine branch.
 This organization method frees you from continually reintegrating your
 patches into a feature.
 
 Once you have a new branch, you can set up your kernel Metadata to use
 the branch a couple different ways. In the recipe, you can specify the
-new branch as the ``KBRANCH`` to use for the board as follows:
-::
+new branch as the :term:`KBRANCH` to use for the board as follows::
 
    KBRANCH = "mynewbranch"
 
 Another method is to use the ``branch`` command in the BSP
-description:
-::
+description::
 
    mybsp.scc:
       define KMACHINE mybsp
@@ -865,15 +831,13 @@ description:
 
 If you find yourself with numerous branches, you might consider using a
 hierarchical branching system similar to what the Yocto Linux Kernel Git
-repositories use:
-::
+repositories use::
 
    common/kernel_type/machine
 
 If you had two kernel types, "standard" and "small" for instance, three
 machines, and common as ``mydir``, the branches in your Git repository
-might look like this:
-::
+might look like this::
 
    mydir/base
    mydir/standard/base
@@ -905,8 +869,7 @@ that have to be regularly updated. The Yocto Project Linux kernel tools
 provide for this with the ``git merge`` command.
 
 To merge a feature branch into a BSP, insert the ``git merge`` command
-after any ``branch`` commands:
-::
+after any ``branch`` commands::
 
    mybsp.scc:
       define KMACHINE mybsp