bsp-guide, kernel-dev: Updates to how kernel metadata is found

Fixes [YOCTO #10946]

There was insufficient information in the combination of the
BSP Guide and the Kernel Development Manual on just how to locate
and use kernel metadata.

 * bsp-guide - Removed the detailed append file example for the
   kernel recipe.  This is moved now to the chapter in the kernel
   manual that describes append files.

 * kernel-dev - Placed the example from the BSP Guide into the
   section that describes kernel append files.  Cleaned up some
   terminology issues throughout chapter 3.  Added information
   about how BitBake picks up kernel metadata when the metadata
   is in a hierarchical directory and not just a simple *.scc
   file.

(From yocto-docs rev: 1048acb7127e77ca9c1f524a208fe25344fcb57c)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 261 insertions, 377 deletions

diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 4d0ace0484..cb9940c77a 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -352,135 +352,139 @@
             </para>
 
             <section id="bsp-filelayout-license">
-            <title>License Files</title>
+                <title>License Files</title>
 
-            <para>
-                You can find these files in the BSP Layer at:
-                <literallayout class='monospaced'>
+                <para>
+                    You can find these files in the BSP Layer at:
+                    <literallayout class='monospaced'>
      meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                These optional files satisfy licensing requirements for the BSP.
-                The type or types of files here can vary depending on the licensing requirements.
-                For example, in the Raspberry Pi BSP all licensing requirements are handled with the
-                <filename>COPYING.MIT</filename> file.
-            </para>
+                <para>
+                    These optional files satisfy licensing requirements for the BSP.
+                    The type or types of files here can vary depending on the licensing requirements.
+                    For example, in the Raspberry Pi BSP all licensing requirements are handled with the
+                    <filename>COPYING.MIT</filename> file.
+                </para>
 
-            <para>
-                Licensing files can be MIT, BSD, GPLv*, and so forth.
-                These files are recommended for the BSP but are optional and totally up to the BSP developer.
-            </para>
+                <para>
+                    Licensing files can be MIT, BSD, GPLv*, and so forth.
+                    These files are recommended for the BSP but are optional and totally up to the BSP developer.
+                </para>
             </section>
 
             <section id="bsp-filelayout-readme">
-            <title>README File</title>
-            <para>
-                You can find this file in the BSP Layer at:
-                <literallayout class='monospaced'>
+                <title>README File</title>
+
+                <para>
+                    You can find this file in the BSP Layer at:
+                    <literallayout class='monospaced'>
      meta-<replaceable>bsp_name</replaceable>/README
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                This file provides information on how to boot the live images that are optionally
-                included in the <filename>binary/</filename> directory.
-                The <filename>README</filename> file also provides special information needed for
-                building the image.
-            </para>
+                <para>
+                    This file provides information on how to boot the live images that are optionally
+                    included in the <filename>binary/</filename> directory.
+                    The <filename>README</filename> file also provides special information needed for
+                    building the image.
+                </para>
 
-            <para>
-                At a minimum, the <filename>README</filename> file must
-                contain a list of dependencies, such as the names of
-                any other layers on which the BSP depends and the name of
-                the BSP maintainer with his or her contact information.
-            </para>
+                <para>
+                    At a minimum, the <filename>README</filename> file must
+                    contain a list of dependencies, such as the names of
+                    any other layers on which the BSP depends and the name of
+                    the BSP maintainer with his or her contact information.
+                </para>
             </section>
 
             <section id="bsp-filelayout-readme-sources">
-            <title>README.sources File</title>
-            <para>
-                You can find this file in the BSP Layer at:
-                <literallayout class='monospaced'>
+                <title>README.sources File</title>
+
+                <para>
+                    You can find this file in the BSP Layer at:
+                    <literallayout class='monospaced'>
      meta-<replaceable>bsp_name</replaceable>/README.sources
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                This file provides information on where to locate the BSP
-                source files used to build the images (if any) that reside in
-                <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
-                Images in the <filename>binary</filename> would be images
-                released with the BSP.
-                The information in the <filename>README.sources</filename>
-                file also helps you find the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
-                used to generate the images that ship with the BSP.
-                <note>
-                    If the BSP's <filename>binary</filename> directory is
-                    missing or the directory has no images, an existing
-                    <filename>README.sources</filename> file is
-                    meaningless.
-                </note>
-            </para>
+                <para>
+                    This file provides information on where to locate the BSP
+                    source files used to build the images (if any) that reside in
+                    <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
+                    Images in the <filename>binary</filename> would be images
+                    released with the BSP.
+                    The information in the <filename>README.sources</filename>
+                    file also helps you find the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+                    used to generate the images that ship with the BSP.
+                    <note>
+                        If the BSP's <filename>binary</filename> directory is
+                        missing or the directory has no images, an existing
+                        <filename>README.sources</filename> file is
+                        meaningless.
+                    </note>
+                </para>
             </section>
 
             <section id="bsp-filelayout-binary">
-            <title>Pre-built User Binaries</title>
-            <para>
-                You can find these files in the BSP Layer at:
-                <literallayout class='monospaced'>
+                <title>Pre-built User Binaries</title>
+
+                <para>
+                    You can find these files in the BSP Layer at:
+                    <literallayout class='monospaced'>
      meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                This optional area contains useful pre-built kernels and
-                user-space filesystem images released with the BSP that are
-                appropriate to the target system.
-                This directory typically contains graphical (e.g. Sato) and
-                minimal live images when the BSP tarball has been created and
-                made available in the
-                <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
-                You can use these kernels and images to get a system running
-                and quickly get started on development tasks.
-            </para>
+                <para>
+                    This optional area contains useful pre-built kernels and
+                    user-space filesystem images released with the BSP that are
+                    appropriate to the target system.
+                    This directory typically contains graphical (e.g. Sato) and
+                    minimal live images when the BSP tarball has been created and
+                    made available in the
+                    <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
+                    You can use these kernels and images to get a system running
+                    and quickly get started on development tasks.
+                </para>
 
-            <para>
-                The exact types of binaries present are highly
-                hardware-dependent.
-                The <filename>README</filename> file should be present in the
-                BSP Layer and it will explain how to use the images with the
-                target hardware.
-                Additionally, the <filename>README.sources</filename> file
-                should be present to locate the sources used to build the
-                images and provide information on the Metadata.
-            </para>
+                <para>
+                    The exact types of binaries present are highly
+                    hardware-dependent.
+                    The <filename>README</filename> file should be present in the
+                    BSP Layer and it will explain how to use the images with the
+                    target hardware.
+                    Additionally, the <filename>README.sources</filename> file
+                    should be present to locate the sources used to build the
+                    images and provide information on the Metadata.
+                </para>
             </section>
 
             <section id='bsp-filelayout-layer'>
-            <title>Layer Configuration File</title>
-            <para>
-                You can find this file in the BSP Layer at:
-                <literallayout class='monospaced'>
+                <title>Layer Configuration File</title>
+
+                <para>
+                    You can find this file in the BSP Layer at:
+                    <literallayout class='monospaced'>
      meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                The <filename>conf/layer.conf</filename> file identifies the file structure as a
-                layer, identifies the
-                contents of the layer, and contains information about how the build
-                system should use it.
-                Generally, a standard boilerplate file such as the following works.
-                In the following example, you would replace "<replaceable>bsp</replaceable>" and
-                "<replaceable>_bsp</replaceable>" with the actual name
-                of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template).
-            </para>
+                <para>
+                    The <filename>conf/layer.conf</filename> file identifies the file structure as a
+                    layer, identifies the
+                    contents of the layer, and contains information about how the build
+                    system should use it.
+                    Generally, a standard boilerplate file such as the following works.
+                    In the following example, you would replace "<replaceable>bsp</replaceable>" and
+                    "<replaceable>_bsp</replaceable>" with the actual name
+                    of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template).
+                </para>
 
-            <para>
-               <literallayout class='monospaced'>
+                <para>
+                   <literallayout class='monospaced'>
      # We have a conf and classes directory, add to BBPATH
      BBPATH .= ":${LAYERDIR}"
 
@@ -493,13 +497,13 @@
      BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
 
      LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                To illustrate the string substitutions, here are the corresponding statements
-                from the Raspberry Pi <filename>conf/layer.conf</filename> file:
-               <literallayout class='monospaced'>
+                <para>
+                    To illustrate the string substitutions, here are the corresponding statements
+                    from the Raspberry Pi <filename>conf/layer.conf</filename> file:
+                   <literallayout class='monospaced'>
      # We have a conf and classes directory, append to BBPATH
      BBPATH .= ":${LAYERDIR}"
 
@@ -513,316 +517,196 @@
 
      # Additional license directories.
      LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                This file simply makes
-                <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
-                aware of the recipes and configuration directories.
-                The file must exist so that the OpenEmbedded build system can recognize the BSP.
-            </para>
+                <para>
+                    This file simply makes
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
+                    aware of the recipes and configuration directories.
+                    The file must exist so that the OpenEmbedded build system can recognize the BSP.
+                </para>
             </section>
 
             <section id="bsp-filelayout-machine">
-            <title>Hardware Configuration Options</title>
-            <para>
-                You can find these files in the BSP Layer at:
-                <literallayout class='monospaced'>
+                <title>Hardware Configuration Options</title>
+
+                <para>
+                    You can find these files in the BSP Layer at:
+                    <literallayout class='monospaced'>
      meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                The machine files bind together all the information contained elsewhere
-                in the BSP into a format that the build system can understand.
-                If the BSP supports multiple machines, multiple machine configuration files
-                can be present.
-                These filenames correspond to the values to which users have set the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
-            </para>
+                <para>
+                    The machine files bind together all the information contained elsewhere
+                    in the BSP into a format that the build system can understand.
+                    If the BSP supports multiple machines, multiple machine configuration files
+                    can be present.
+                    These filenames correspond to the values to which users have set the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
+                </para>
 
-            <para>
-                These files define things such as the kernel package to use
-                (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
-                of virtual/kernel), the hardware drivers to
-                include in different types of images, any special software components
-                that are needed, any bootloader information, and also any special image
-                format requirements.
-            </para>
+                <para>
+                    These files define things such as the kernel package to use
+                    (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+                    of virtual/kernel), the hardware drivers to
+                    include in different types of images, any special software components
+                    that are needed, any bootloader information, and also any special image
+                    format requirements.
+                </para>
 
-            <para>
-                Each BSP Layer requires at least one machine file.
-                However, you can supply more than one file.
-            </para>
+                <para>
+                    Each BSP Layer requires at least one machine file.
+                    However, you can supply more than one file.
+                </para>
 
-            <para>
-                This configuration file could also include a hardware "tuning"
-                file that is commonly used to define the package architecture
-                and specify optimization flags, which are carefully chosen
-                to give best performance on a given processor.
-            </para>
+                <para>
+                    This configuration file could also include a hardware "tuning"
+                    file that is commonly used to define the package architecture
+                    and specify optimization flags, which are carefully chosen
+                    to give best performance on a given processor.
+                </para>
 
-            <para>
-                Tuning files are found in the <filename>meta/conf/machine/include</filename>
-                directory within the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
-                For example, the <filename>ia32-base.inc</filename> file resides in the
-                <filename>meta/conf/machine/include</filename> directory.
-            </para>
+                <para>
+                    Tuning files are found in the <filename>meta/conf/machine/include</filename>
+                    directory within the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                    For example, the <filename>ia32-base.inc</filename> file resides in the
+                    <filename>meta/conf/machine/include</filename> directory.
+                </para>
 
-            <para>
-                To use an include file, you simply include them in the
-                machine configuration file.
-                For example, the Raspberry Pi BSP
-                <filename>raspberrypi3.conf</filename> contains the
-                following statement:
-                <literallayout class='monospaced'>
+                <para>
+                    To use an include file, you simply include them in the
+                    machine configuration file.
+                    For example, the Raspberry Pi BSP
+                    <filename>raspberrypi3.conf</filename> contains the
+                    following statement:
+                    <literallayout class='monospaced'>
      include conf/machine/raspberrypi2.conf
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
             </section>
 
             <section id='bsp-filelayout-misc-recipes'>
-            <title>Miscellaneous BSP-Specific Recipe Files</title>
-            <para>
-                You can find these files in the BSP Layer at:
-                <literallayout class='monospaced'>
+                <title>Miscellaneous BSP-Specific Recipe Files</title>
+
+                <para>
+                    You can find these files in the BSP Layer at:
+                    <literallayout class='monospaced'>
      meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                This optional directory contains miscellaneous recipe files for
-                the BSP.
-                Most notably would be the formfactor files.
-                For example, in the Raspberry Pi BSP there is the
-                <filename>formfactor_0.0.bbappend</filename> file, which is an
-                append file used to augment the recipe that starts the build.
-                Furthermore, there are machine-specific settings used during
-                the build that are defined by the
-                <filename>machconfig</filename> file further down in the
-                directory.
-                Here is the <filename>machconfig</filename>
-                file for the Raspberry Pi BSP:
-                <literallayout class='monospaced'>
+                <para>
+                    This optional directory contains miscellaneous recipe files for
+                    the BSP.
+                    Most notably would be the formfactor files.
+                    For example, in the Raspberry Pi BSP there is the
+                    <filename>formfactor_0.0.bbappend</filename> file, which is an
+                    append file used to augment the recipe that starts the build.
+                    Furthermore, there are machine-specific settings used during
+                    the build that are defined by the
+                    <filename>machconfig</filename> file further down in the
+                    directory.
+                    Here is the <filename>machconfig</filename>
+                    file for the Raspberry Pi BSP:
+                    <literallayout class='monospaced'>
      HAVE_TOUCHSCREEN=0
      HAVE_KEYBOARD=1
 
      DISPLAY_CAN_ROTATE=0
      DISPLAY_ORIENTATION=0
      DISPLAY_DPI=133
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <note><para>
-                If a BSP does not have a formfactor entry, defaults are established according to
-                the formfactor configuration file that is installed by the main
-                formfactor recipe
-                <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
-                which is found in the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
-            </para></note>
+                <note><para>
+                    If a BSP does not have a formfactor entry, defaults are established according to
+                    the formfactor configuration file that is installed by the main
+                    formfactor recipe
+                    <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
+                    which is found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para></note>
             </section>
 
             <section id='bsp-filelayout-recipes-graphics'>
-            <title>Display Support Files</title>
-            <para>
-                You can find these files in the BSP Layer at:
-                <literallayout class='monospaced'>
+                <title>Display Support Files</title>
+
+                <para>
+                    You can find these files in the BSP Layer at:
+                    <literallayout class='monospaced'>
      meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
-                </literallayout>
-            </para>
+                    </literallayout>
+                </para>
 
-            <para>
-                This optional directory contains recipes for the BSP if it has
-                special requirements for graphics support.
-                All files that are needed for the BSP to support a display are
-                kept here.
-            </para>
+                <para>
+                    This optional directory contains recipes for the BSP if it has
+                    special requirements for graphics support.
+                    All files that are needed for the BSP to support a display are
+                    kept here.
+                </para>
             </section>
 
             <section id='bsp-filelayout-kernel'>
-            <title>Linux Kernel Configuration</title>
-            <para>
-                You can find these files in the BSP Layer at:
-                <literallayout class='monospaced'>
-     meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
-                </literallayout>
-            </para>
-
-            <para>
-                These files append your specific changes to the main kernel recipe you are using.
-            </para>
-            <para>
-                For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
-                at <filename>meta/recipes-kernel/linux</filename>.
-                You can append your specific changes to the kernel recipe by using a
-                similarly named append file, which is located in the BSP Layer (e.g.
-                the <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
-            </para>
-            <para>
-                Suppose you are using the <filename>linux-yocto_4.4.bb</filename> recipe to build
-                the kernel.
-                In other words, you have selected the kernel in your
-                <replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types
-                of statements:
-                <literallayout class='monospaced'>
-     PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
-     PREFERRED_VERSION_linux-yocto ?= "4.4%"
-                </literallayout>
-                <note>
-                    When the preferred provider is assumed by default, the
-                    <filename>PREFERRED_PROVIDER</filename> statement does not appear in the
-                    <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
-                </note>
-                You would use the <filename>linux-yocto_4.4.bbappend</filename>
-                file to append specific BSP settings to the kernel, thus
-                configuring the kernel for your particular BSP.
-            </para>
-
-            <para>
-                As an example, consider the following append file
-                used by the BSPs in <filename>meta-yocto-bsp</filename>:
-                <literallayout class='monospaced'>
-     meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend
-                </literallayout>
-                The following listing shows the file.
-                Be aware that the actual commit ID strings in this
-                example listing might be different than the actual strings
-                in the file from the <filename>meta-yocto-bsp</filename>
-                layer upstream.
-                <literallayout class='monospaced'>
-     KBRANCH_genericx86  = "standard/base"
-     KBRANCH_genericx86-64  = "standard/base"
-
-     KMACHINE_genericx86 ?= "common-pc"
-     KMACHINE_genericx86-64 ?= "common-pc-64"
-     KBRANCH_edgerouter = "standard/edgerouter"
-     KBRANCH_beaglebone = "standard/beaglebone"
-     KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
-
-     SRCREV_machine_genericx86    ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
-     SRCREV_machine_genericx86-64 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
-     SRCREV_machine_edgerouter ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
-     SRCREV_machine_beaglebone ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
-     SRCREV_machine_mpc8315e-rdb ?= "df00877ef9387b38b9601c82db57de2a1b23ce53"
-
-     COMPATIBLE_MACHINE_genericx86 = "genericx86"
-     COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
-     COMPATIBLE_MACHINE_edgerouter = "edgerouter"
-     COMPATIBLE_MACHINE_beaglebone = "beaglebone"
-     COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
-
-     LINUX_VERSION_genericx86 = "4.4.3"
-     LINUX_VERSION_genericx86-64 = "4.4.3"
-                </literallayout>
-                This append file contains statements used to support
-                several BSPs that ship with the Yocto Project.
-                The file defines machines using the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
-                variable and uses the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
-                variable to ensure the machine name used by the OpenEmbedded
-                build system maps to the machine name used by the Linux Yocto
-                kernel.
-                The file also uses the optional
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
-                variable to ensure the build process uses the
-                appropriate kernel branch.
-            </para>
-
-            <para>
-                Although this particular example does not use it, the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
-                variable could be used to enable features specific to
-                the kernel.
-                The append file points to specific commits in the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
-                Git repository and the <filename>meta</filename> Git repository
-                branches to identify the exact kernel needed to build the
-                BSP.
-            </para>
-
-            <para>
-                One thing missing in this particular BSP, which you will
-                typically need when developing a BSP, is the kernel configuration
-                file (<filename>.config</filename>) for your BSP.
-                When developing a BSP, you probably have a kernel configuration
-                file or a set of kernel configuration files that, when taken
-                together, define the kernel configuration for your BSP.
-                You can accomplish this definition by putting the configurations
-                in a file or a set of files inside a directory located at the
-                same level as your kernel's append file and having the same
-                name as the kernel's main recipe file.
-                With all these conditions met, simply reference those files in the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
-                statement in the append file.
-            </para>
+                <title>Linux Kernel Configuration</title>
 
-            <para>
-                For example, suppose you had some configuration options
-                in a file called <filename>network_configs.cfg</filename>.
-                You can place that file inside a directory named
-                <filename>linux-yocto</filename> and then add
-                a <filename>SRC_URI</filename> statement such as the
-                following to the append file.
-                When the OpenEmbedded build system builds the kernel, the
-                configuration options are picked up and applied.
-                <literallayout class='monospaced'>
-     SRC_URI += "file://network_configs.cfg"
-                </literallayout>
-            </para>
+                <para>
+                    You can find these files in the BSP Layer at:
+                    <literallayout class='monospaced'>
+     meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
+                    </literallayout>
+                </para>
 
-            <para>
-                To group related configurations into multiple files, you
-                perform a similar procedure.
-                Here is an example that groups separate configurations
-                specifically for Ethernet and graphics into their own
-                files and adds the configurations by using a
-                <filename>SRC_URI</filename> statement like the following
-                in your append file:
-                <literallayout class='monospaced'>
-     SRC_URI += "file://myconfig.cfg \
-                 file://eth.cfg \
-                 file://gfx.cfg"
-                </literallayout>
-            </para>
+                <para>
+                    These files append machine-specific changes to the main
+                    kernel recipe you are using.
+                </para>
 
-            <para>
-                Another variable you can use in your kernel recipe append
-                file is the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
-                variable.
-                When you use this statement, you are extending the locations
-                used by the OpenEmbedded system to look for files and
-                patches as the recipe is processed.
-            </para>
+                <para>
+                    For your BSP, you typically want to use an existing Yocto
+                    Project kernel recipe found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                    at <filename>meta/recipes-kernel/linux</filename>.
+                    You can append machine-specific changes to the kernel recipe
+                    by using a similarly named append file, which is located in
+                    the BSP Layer for your target device (e.g. the
+                    <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
+                </para>
 
-            <note>
                 <para>
-                    Other methods exist to accomplish grouping and defining configuration options.
-                    For example, if you are working with a local clone of the kernel repository,
-                    you could checkout the kernel's <filename>meta</filename> branch, make your changes,
-                    and then push the changes to the local bare clone of the kernel.
-                    The result is that you directly add configuration options to the
-                    <filename>meta</filename> branch for your BSP.
-                    The configuration options will likely end up in that location anyway if the BSP gets
-                    added to the Yocto Project.
+                    Suppose you are using the <filename>linux-yocto_4.4.bb</filename>
+                    recipe to build the kernel.
+                    In other words, you have selected the kernel in your
+                    <replaceable>bsp_name</replaceable><filename>.conf</filename>
+                    file by adding
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+                    and
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
+                    statements as follows:
+                    <literallayout class='monospaced'>
+     PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+     PREFERRED_VERSION_linux-yocto ?= "4.4%"
+                    </literallayout>
+                    <note>
+                        When the preferred provider is assumed by default, the
+                        <filename>PREFERRED_PROVIDER</filename>
+                        statement does not appear in the
+                        <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
+                    </note>
+                    You would use the <filename>linux-yocto_4.4.bbappend</filename>
+                    file to append specific BSP settings to the kernel, thus
+                    configuring the kernel for your particular BSP.
                 </para>
 
                 <para>
-                    In general, however, the Yocto Project maintainers take care of moving the
-                    <filename>SRC_URI</filename>-specified
-                    configuration options to the kernel's <filename>meta</filename> branch.
-                    Not only is it easier for BSP developers to not have to worry about putting those
-                   configurations in the branch, but having the maintainers do it allows them to apply
-                    'global' knowledge about the kinds of common configuration options multiple BSPs in
-                    the tree are typically using.
-                    This allows for promotion of common configurations into common features.
+                    You can find more information on what your append file
+                    should contain in the
+                    "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
+                    section in the Yocto Project Linux Kernel Development
+                    Manual.
                 </para>
-            </note>
             </section>
         </section>