2 files changed, 374 insertions, 165 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index 1c1b6366db..434c01fafb 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -524,170 +524,219 @@
        <title>BSP Descriptions</title>
        <para>
-            BSP descriptions combine kernel types with hardware-specific
+            BSP descriptions (i.e. <filename>*.scc</filename> files)
-            features.
+            combine kernel types with hardware-specific features.
-            The hardware-specific portion is typically defined
+            The hardware-specific Metadata is typically defined
-            independently, and then aggregated with each supported kernel
+            independently in the BSP layer, and then aggregated with each
-            type.
+            supported kernel type.
-            Consider this simple BSP description that supports the
-            <replaceable>mybsp</replaceable> machine:
-            <literallayout class='monospaced'>
-     <replaceable>mybsp</replaceable>.scc:
-        define KMACHINE <replaceable>mybsp</replaceable>
-        define KTYPE standard
-        define KARCH i386
-        kconf <replaceable>mybsp</replaceable>.cfg
-            </literallayout>
-            Every BSP description should define the
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
-            and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
-            variables.
-            These variables allow the OpenEmbedded build system to identify
-            the description as meeting the criteria set by the recipe being
-            built.
-            This simple example supports the "mybsp" machine for the "standard"
-            kernel and the "i386" architecture.
-        </para>
-        <para>
-            Be aware that a hard link between the
-            <filename>KTYPE</filename> variable and a kernel type
-            description file does not exist.
-            Thus, if you do not have kernel types defined in your kernel
-            Metadata, you only need to ensure that the kernel recipe's
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
-            variable and the <filename>KTYPE</filename> variable in the
-            BSP description file match.
            <note>
-                Future versions of the tooling make the specification of
+                For BSPs supported by the Yocto Project, the BSP description
-                <filename>KTYPE</filename> in the BSP optional.
+                files are located in the <filename>bsp</filename> directory
+                of the <filename>yocto-kernel-cache</filename> repository
+                organized under the "Yocto Linux Kernel" heading in the
+                <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
            </note>
        </para>
        <para>
-            If you did want to separate your kernel policy from your
+            This section provides a BSP description structural overview along
-            hardware configuration, you could do so by specifying a kernel
+            with aggregation concepts as well as a detailed example using
-            type, such as "standard" and including that description file
+            a BSP supported by the Yocto Project (i.e. Minnow Board).
-            in the BSP description file.
-            See the "<link linkend='kernel-types'>Kernel Types</link>" section
-            for more information.
        </para>
-        <para>
+        <section id='bsp-description-file-overview'>
-            You might also have multiple hardware configurations that you
+            <title>Overview</title>
-            aggregate into a single hardware description file that you
-            could include in the BSP description file, rather than referencing
-            a single <filename>.cfg</filename> file.
-            Consider the following:
-            <literallayout class='monospaced'>
-     <replaceable>mybsp</replaceable>.scc:
-        define KMACHINE mybsp
-        define KTYPE standard
-        define KARCH i386
-        include standard.scc
-        include <replaceable>mybsp</replaceable>-hw.scc
-            </literallayout>
-        </para>
-        <para>
+            <para>
-            In the above example, <filename>standard.scc</filename>
+                For simplicity, consider the following top-level BSP
-            aggregates all the configuration fragments, patches, and
+                description file.
-            features that make up your standard kernel policy whereas
+                Top-level BSP descriptions files employ both a structure
-            <replaceable>mybsp</replaceable><filename>-hw.scc</filename>
+                and naming convention for consistency.
-            aggregates all those necessary
+                The naming convention for the file is as follows:
-            to support the hardware available on the
+                <literallayout class='monospaced'>
-            <replaceable>mybsp</replaceable> machine.
+     <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
-            For information on how to break a complete
+                </literallayout>
-            <filename>.config</filename> file into the various
+                Here are some example top-level BSP filenames for the
-            configuration fragments, see the
+                Minnow Board BSP, which is supported by the Yocto Project:
-            "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+                <literallayout class='monospaced'>
-            section.
+     minnow-standard.scc
-        </para>
+     minnow-preempt-rt.scc
+     minnow-tiny.scc
+                </literallayout>
+                Each file uses the BSP name followed by the kernel type.
+            </para>
-        <para>
+            <para>
-            Many real-world examples are more complex.
+                is simple BSP description file whose name has the
-            Like any other <filename>.scc</filename> file, BSP
+                form
-            descriptions can aggregate features.
+                <replaceable>mybsp</replaceable><filename>-standard</filename>
-            Consider the Minnow BSP definition from the
+                and supports the <replaceable>mybsp</replaceable> machine using
-            <filename>linux-yocto-3.19</filename>
+                a standard kernel:
-            Git repository:
+                <literallayout class='monospaced'>
-            <literallayout class='monospaced'>
+     define KMACHINE <replaceable>mybsp</replaceable>
-     minnow.scc:
+     define KTYPE standard
-        include cfg/x86.scc
+     define KARCH i386
-        include features/eg20t/eg20t.scc
-        include cfg/dmaengine.scc
+     include ktypes/standard
-        include features/power/intel.scc
-        include cfg/efi.scc
+     include <replaceable>mybsp</replaceable>.scc
-        include features/usb/ehci-hcd.scc
-        include features/usb/ohci-hcd.scc
+     kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
-        include features/usb/usb-gadgets.scc
+                </literallayout>
-        include features/usb/touchscreen-composite.scc
+                Every top-level BSP description file should define the
-        include cfg/timer/hpet.scc
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
-        include cfg/timer/rtc.scc
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
-        include features/leds/leds.scc
+                and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
-        include features/spi/spidev.scc
+                variables.
-        include features/i2c/i2cdev.scc
+                These variables allow the OpenEmbedded build system to identify
+                the description as meeting the criteria set by the recipe being
-        # Earlyprintk and port debug requires 8250
+                built.
-        kconf hardware cfg/8250.cfg
+                This simple example supports the "mybsp" machine for the "standard"
+                kernel and the "i386" architecture.
-        kconf hardware minnow.cfg
+            </para>
-        kconf hardware minnow-dev.cfg
-            </literallayout>
-        </para>
-        <para>
+            <para>
-            The <filename>minnow.scc</filename> description file includes
+                Be aware that a hard link between the
-            a hardware configuration fragment
+                <filename>KTYPE</filename> variable and a kernel type description
-            (<filename>minnow.cfg</filename>) specific to the Minnow
+                file does not exist.
-            BSP as well as several more general configuration
+                Thus, if you do not have kernel types defined in your kernel
-            fragments and features enabling hardware found on the
+                Metadata, you only need to ensure that the kernel recipe's
-            machine.
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
-            This description file is then included in each of the three
+                variable and the <filename>KTYPE</filename> variable in the
-            "minnow" description files for the supported kernel types
+                BSP description file match.
-            (i.e. "standard", "preempt-rt", and "tiny").
+                <note>
-            Consider the "minnow" description for the "standard" kernel
+                    Future versions of the tooling make the specification of
-            type:
+                    <filename>KTYPE</filename> in the BSP optional.
-            <literallayout class='monospaced'>
+                </note>
-     minnow-standard.scc:
+            </para>
-        define KMACHINE minnow
-        define KTYPE standard
-        define KARCH i386
-        include ktypes/standard
+            <para>
+                To separate your kernel policy from your hardware configuration,
+                you include a kernel type (<filename>ktype</filename>), such as
+                "standard".
+                In the previous example, this is done using the following:
+                <literallayout class='monospaced'>
+     include ktypes/standard
+                </literallayout>
+                In the previous example, <filename>ktypes/standard.scc</filename>
+                aggregates all the configuration fragments, patches, and
+                features that make up your standard kernel policy.
+                See the "<link linkend='kernel-types'>Kernel Types</link>" section
+                for more information.
+            </para>
-        include minnow.scc
+            <para>
+                To aggregate common configurations and features specific to the
+                kernel for <replaceable>mybsp</replaceable>, use the following:
+                <literallayout class='monospaced'>
+     include <replaceable>mybsp</replaceable>.scc
+                </literallayout>
+                For information on how to break a complete
+                <filename>.config</filename> file into the various
+                configuration fragments, see the
+                "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+                section.
+            </para>
-        # Extra minnow configs above the minimal defined in minnow.scc
+            <para>
-        include cfg/efi-ext.scc
+                Finally, if you have any configurations specific to the
-        include features/media/media-all.scc
+                hardware that are not in a <filename>*.scc</filename> file,
-        include features/sound/snd_hda_intel.scc
+                you can include them as follows:
+                <literallayout class='monospaced'>
+     kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
+                </literallayout>
+            </para>
+        </section>
-        # The following should really be in standard.scc
+        <section id='bsp-description-file-example-minnow'>
-        # USB live-image support
+            <title>Example</title>
-        include cfg/usb-mass-storage.scc
-        include cfg/boot-live.scc
-        # Basic profiling
+            <para>
-        include features/latencytop/latencytop.scc
+                Many real-world examples are more complex.
-        include features/profiling/profiling.scc
+                Like any other <filename>.scc</filename> file, BSP
+                descriptions can aggregate features.
+                Consider the Minnow BSP definition from the
+                <filename>linux-yocto-4.4</filename> in the
+                Yocto Project
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
+                (i.e.
+                <filename>yocto-kernel-cache/bsp/minnow</filename>):
+                <literallayout class='monospaced'>
+     minnow.scc:
+         include cfg/x86.scc
+         include features/eg20t/eg20t.scc
+         include cfg/dmaengine.scc
+         include features/power/intel.scc
+         include cfg/efi.scc
+         include features/usb/ehci-hcd.scc
+         include features/usb/ohci-hcd.scc
+         include features/usb/usb-gadgets.scc
+         include features/usb/touchscreen-composite.scc
+         include cfg/timer/hpet.scc
+         include features/leds/leds.scc
+         include features/spi/spidev.scc
+         include features/i2c/i2cdev.scc
+         include features/mei/mei-txe.scc
+         # Earlyprintk and port debug requires 8250
+         kconf hardware cfg/8250.cfg
+         kconf hardware minnow.cfg
+         kconf hardware minnow-dev.cfg
+                </literallayout>
+            </para>
-        # Requested drivers that don't have an existing scc
+            <para>
-        kconf hardware minnow-drivers-extra.cfg
+                The <filename>minnow.scc</filename> description file includes
-            </literallayout>
+                a hardware configuration fragment
-            The <filename>include</filename> command midway through the file
+                (<filename>minnow.cfg</filename>) specific to the Minnow
-            includes the <filename>minnow.scc</filename> description that
+                BSP as well as several more general configuration
-            defines all hardware enablements for the BSP that is common to all
+                fragments and features enabling hardware found on the
-            kernel types.
+                machine.
-            Using this command significantly reduces duplication.
+                This <filename>minnow.scc</filename> description file is then
-        </para>
+                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:
+                <literallayout class='monospaced'>
+     minnow-standard.scc:
+         define KMACHINE minnow
+         define KTYPE standard
+         define KARCH i386
+         include ktypes/standard
+         include minnow.scc
+         # Extra minnow configs above the minimal defined in minnow.scc
+         include cfg/efi-ext.scc
+         include features/media/media-all.scc
+         include features/sound/snd_hda_intel.scc
+         # The following should really be in standard.scc
+         # USB live-image support
+         include cfg/usb-mass-storage.scc
+         include cfg/boot-live.scc
+         # Basic profiling
+         include features/latencytop/latencytop.scc
+         include features/profiling/profiling.scc
+         # Requested drivers that don't have an existing scc
+         kconf hardware minnow-drivers-extra.cfg
+                </literallayout>
+                The <filename>include</filename> command midway through the file
+                includes the <filename>minnow.scc</filename> description that
+                defines all enabled hardware for the BSP that is common to
+                all kernel types.
+                Using this command significantly reduces duplication.
+            </para>
-        <para>
+            <para>
-            Now consider the "minnow" description for the "tiny" kernel type:
+                Now consider the "minnow" description for the "tiny" kernel
-            <literallayout class='monospaced'>
+                type:
+                <literallayout class='monospaced'>
     minnow-tiny.scc:
        define KMACHINE minnow
        define KTYPE tiny
@@ -696,22 +745,24 @@
        include ktypes/tiny
        include minnow.scc
-            </literallayout>
+                </literallayout>
-            As you might expect, the "tiny" description includes quite a
+                As you might expect, the "tiny" description includes quite a
-            bit less.
+                bit less.
-            In fact, it includes only the minimal policy defined by the
+                In fact, it includes only the minimal policy defined by the
-            "tiny" kernel type and the hardware-specific configuration required
+                "tiny" kernel type and the hardware-specific configuration
-            for booting the machine along with the most basic functionality of
+                required for booting the machine along with the most basic
-            the system as defined in the base "minnow" description file.
+                functionality of the system as defined in the base "minnow"
-        </para>
+                description file.
+            </para>
-        <para>
+            <para>
-            Notice again the three critical variables:
+                Notice again the three critical variables:
-            <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
+                <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
-            and <filename>KARCH</filename>.
+                and <filename>KARCH</filename>.
-            Of these variables, only the <filename>KTYPE</filename> has changed.
+                Of these variables, only the <filename>KTYPE</filename> has changed.
-            It is now set to "tiny".
+                It is now set to "tiny".
-        </para>
+            </para>
+        </section>
    </section>
 </section>
@@ -795,6 +846,18 @@
            value when changing the content of files not explicitly listed
            in the <filename>SRC_URI</filename>.
        </para>
+        <para>
+            If the kernel Metadata is in a layer, you cannot simply list the
+            <filename>*.scc</filename> in the <filename>SRC_URI</filename>
+            statement.
+            You need to use the following form from your kernel append file:
+            <literallayout class='monospaced'>
+     SRC_URI_append_<replaceable>myplatform</replaceable> = " \
+        file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \
+        "
+            </literallayout>
+        </para>
    </section>
    <section id='metadata-outside-the-recipe-space'>
@@ -817,7 +880,8 @@
            <filename>${KMETA}</filename>, 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
-            <filename>SRC_URI</filename> statement used in a recipe.
+            <filename>SRC_URI</filename> statement used in a recipe (e.g.
+            see the previous section).
        </para>
        <para>
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index a9aafd3c21..d49aa3ce17 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -84,11 +84,11 @@
                You also name it accordingly based on the linux-yocto recipe
                you are using.
                For example, if you are modifying the
-                <filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename>
+                <filename>meta/recipes-kernel/linux/linux-yocto_4.4.bb</filename>
                recipe, the append file will typically be located as follows
                within your custom layer:
                <literallayout class='monospaced'>
-     <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend
+     <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.4.bbappend
                </literallayout>
                The append file should initially extend the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
@@ -114,6 +114,151 @@
                    <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
                </note>
            </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    ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
+     SRCREV_machine_genericx86-64 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
+     SRCREV_machine_edgerouter ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
+     SRCREV_machine_beaglebone ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
+     SRCREV_machine_mpc8315e-rdb ?= "06c0dbdcba374ca7f92a53d69292d6bb7bc9b0f3"
+     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.41"
+     LINUX_VERSION_genericx86-64 = "4.4.41"
+     LINUX_VERSION_edgerouter = "4.4.53"
+     LINUX_VERSION_beaglebone = "4.4.53"
+     LINUX_VERSION_mpc8315e-rdb = "4.4.53"
+                </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>
+            <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>
+                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>
+                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>
+            <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.
+                </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.
+                </para>
+            </note>
        </section>
        <section id='applying-patches'>