kernel-dev: Updated the "Kernel Metadata Location" section.

Fixes [YOCTO #8272]

I re-wrote the section to basically consider kernel metadata
coming from either inside the recipe (recipe-space) or from
outside the recipe, which would be like a "kernel-cache".
The re-write eliminated the term "in-tree" regarding where
kernel metadata could reside.

(From yocto-docs rev: d358c00fbb779328bd472494023ecb802da15d59)

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

documentation/kernel-dev/kernel-dev-advanced.xml

@@ -29,8 +29,8 @@
         source Git repositories.
         This Metadata defines Board Support Packages (BSPs) that
         correspond to definitions in linux-yocto recipes for the same BSPs.
-        A BSP consists of an aggregation of kernel policy and hardware-specific
+        A BSP consists of an aggregation of kernel policy and enabled
-        feature enablements.
+        hardware-specific features.
         The BSP can be influenced from within the linux-yocto recipe.
         <note>
             Linux kernel source that contains kernel Metadata is said to be
@@ -171,8 +171,8 @@
     <title>Kernel Metadata Location</title>
 
     <para>
-        Kernel Metadata can be defined in either the kernel recipe
+        Kernel Metadata always exists outside of the kernel tree either
-        (recipe-space) or in the kernel tree (in-tree).
+        defined in a kernel recipe (recipe-space) or outside of the recipe.
         Where you choose to define the Metadata depends on what you want
         to do and how you intend to work.
         Regardless of where you define the kernel Metadata, the syntax used
@@ -195,10 +195,10 @@
     <para>
         Conversely, if you are actively developing a kernel and are already
         maintaining a Linux kernel Git repository of your own, you might find
-        it more convenient to work with the kernel Metadata in the same
+        it more convenient to work with kernel Metadata kept outside the
-        repository as the Linux kernel sources.
+        recipe-space.
-        This method can make iterative development of the Linux kernel
+        Working with Metadata in this area can make iterative development of
-        more efficient outside of the BitBake environment.
+        the Linux kernel more efficient outside of the BitBake environment.
     </para>
 
     <section id='recipe-space-metadata'>
@@ -249,38 +249,52 @@
         </para>
     </section>
 
-    <section id='in-tree-metadata'>
+    <section id='metadata-outside-the-recipe-space'>
-        <title>In-Tree Metadata</title>
+        <title>Metadata Outside the Recipe-Space</title>
 
         <para>
-            When stored in-tree, the kernel Metadata files reside in the
+            When stored outside of the recipe-space, the kernel Metadata
-            <filename>meta</filename> directory of the Linux kernel sources.
+            files reside in a separate repository.
-            The <filename>meta</filename> directory can be present in the
+            The OpenEmbedded build system adds the Metadata to the build as
-            same repository branch as the sources,
+            a "ktype=meta" repository through the
-            such as "master", or <filename>meta</filename> can be its own
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
-            orphan branch.
+            variable.
-            <note>
+            As an example, consider the following <filename>SRC_URI</filename>
-                An orphan branch in Git is a branch with unique history and
+            statement from the <filename>linux-yocto_4.4.bb</filename>
-                content to the other branches in the repository.
+            kernel recipe:
-                Orphan branches are useful to track Metadata changes
+            <literallayout class='monospaced'>
-                independently from the sources of the Linux kernel, while
+     SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \
-                still keeping them together in the same repository.
+                git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}"
-            </note>
+            </literallayout>
-            For the purposes of this document, we will discuss all
+            <filename>${KMETA}</filename>, in this context, is simply used to
-            in-tree Metadata as residing below the
+            name the directory into which the Git fetcher places the Metadata.
-            <filename>meta/cfg/kernel-cache</filename> directory.
+            This behavior is no different than any multi-repository
+            <filename>SRC_URI</filename> statement used in a recipe.
         </para>
 
+        <para>
+            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 <filename>SRC_URI</filename> statement with the
+            "type=kmeta" attribute.
+            Doing so makes the kernel Metadata available during the
+            configuration phase.
+        </para>
+
+<!--
+
+
         <para>
             Following is an example that shows how a trivial tree of Metadata
             is stored in a custom Linux kernel Git repository:
             <literallayout class='monospaced'>
      meta/
-     `-- cfg
+     `&dash;&dash; cfg
-         `-- kernel-cache
+         `&dash;&dash; kernel-cache
-             |-- bsp-standard.scc
+             |&dash;&dash; bsp-standard.scc
-             |-- bsp.cfg
+             |&dash;&dash; bsp.cfg
-             `-- standard.cfg
+             `&dash;&dash; standard.cfg
             </literallayout>
         </para>
 
@@ -301,16 +315,15 @@
             orphan <filename>meta</filename> branch, use these commands
             from within your Linux kernel Git repository:
             <literallayout class='monospaced'>
-     $ git checkout --orphan meta
+     $ git checkout &dash;&dash;orphan meta
      $ git rm -rf .
-     $ git commit --allow-empty -m "Create orphan meta branch"
+     $ git commit &dash;&dash;allow-empty -m "Create orphan meta branch"
             </literallayout>
         </para>
+-->
 
         <para>
-            If you modify the Metadata in the linux-yocto
+            If you modify the Metadata, you must not forget to update the
-            <filename>meta</filename> branch, you must not forget to update
-            the
             <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
             statements in the kernel's recipe.
             In particular, you need to update the
@@ -437,7 +450,7 @@
         if you are creating Metadata in
         <link linkend='recipe-space-metadata'>recipe-space</link>,
         or <filename>meta/cfg/kernel-cache/</filename> if you are creating
-        Metadata <link linkend='in-tree-metadata'>in-tree</link>.
+        <link linkend='metadata-outside-the-recipe-space'>Metadata outside of the recipe-space</link>.
     </para>
 
     <section id='configuration'>