kernel-dev: edits to the "Kernel Metadata Syntax" section.

First real re-write of this section.

(From yocto-docs rev: 41c79da0832c0b290b21cc2aff87091d7243fafa)

Signed-off-by: scott-lenovo <scott-lenovo@ubuntu.(none)>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 82 insertions, 65 deletions

diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index 87819903bb..c069ddfb08 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -188,7 +188,7 @@ to source changes.
         and "cfg" are subdirectories within the
         <filename>meta/cfg/kernel-cache</filename> directory.
         For more information, see the
-        "<link linkend='metadata-syntax'>Metadata Syntax</link>" section.
+        "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section.
         <note>
             The processing of the these variables has evolved some between the
                 0.9 and 1.3 releases of the Yocto Project and associated
@@ -421,24 +421,27 @@ value when changing the content of files not explicitly listed in the SRC_URI.
         <title>In-Tree Metadata</title>
 
         <para>
-            When stored in-tree, the metadata files reside in the
-            "meta" directory of the Linux kernel sources.
-            They may be present in the same branch as the sources,
-            such as "master", or in their own orphan branch,
-            typically named "meta".
-            An orphan branch in Git is a branch with unique history and
-            content to the other branches in the repository.
-            This is useful to track metadata changes independently from the
-            sources of the Linux kernel, while still keeping them
-            together in the same repository.
+            When stored in-tree, the kernel Metadata files reside in the
+            <filename>meta</filename> directory of the Linux kernel sources.
+            The <filename>meta</filename> directory can be present in the
+            same repository branch as the sources,
+            such as "master", or <filename>meta</filename> can be its own
+            orphan branch.
+            <note>
+                An orphan branch in Git is a branch with unique history and
+                content to the other branches in the repository.
+                Orphan branches are useful to track Metadata changes
+                independently from the sources of the Linux kernel, while
+                still keeping them together in the same repository.
+            </note>
             For the purposes of this document, we will discuss all
-            in-tree metadata as residing below the
+            in-tree Metadata as residing below the
             <filename>meta/cfg/kernel-cache</filename> directory.
         </para>
 
         <para>
-            By way of example, a trivial tree of metadata stored in a custom
-            Linux kernel Git repository might look like the following:
+            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
@@ -450,20 +453,21 @@ value when changing the content of files not explicitly listed in the SRC_URI.
         </para>
 
         <para>
-            To use a specific branch for the metadata, specify the branch
-            in the <filename>KMETA</filename> variable in your Linux kernel
-            recipe, for example:
+            To use a branch different from where the sources reside,
+            specify the branch in the <filename>KMETA</filename> variable
+            in your Linux kernel recipe.
+            Here is an example:
             <literallayout class='monospaced'>
      KMETA = "meta"
             </literallayout>
             To use the same branch as the sources, set
-            <filename>KMETA</filename> to the empty string:
+            <filename>KMETA</filename> to an empty string:
             <literallayout class='monospaced'>
      KMETA = ""
             </literallayout>
             If you are working with your own sources and want to create an
-            orphan <filename>meta</filename> branch, you can do so using the
-            following commands from within your Linux kernel Git repository:
+            orphan <filename>meta</filename> branch, use these commands
+            from within your Linux kernel Git repository:
             <literallayout class='monospaced'>
      $ git checkout --orphan meta
      $ git rm -rf .
@@ -515,32 +519,33 @@ git repository:
     </section>
 </section>
 
-<section id='metadata-syntax'>
-    <title>Metadata Syntax</title>
+<section id='kernel-metadata-syntax'>
+    <title>Kernel Metadata Syntax</title>
 
     <para>
-        The Yocto Project Linux kernel tools metadata consists of three
-        primary types of files: <filename>scc</filename>
+        The kernel Metadata consists of three primary types of files:
+        <filename>scc</filename>
         <footnote>
             <para>
                 <filename>scc</filename> stands for Series Configuration
                 Control, but the naming has less significance in the
                 current implementation of the tooling than it had in the
                 past.
-                Consider it to be a description file.
+                Consider <filename>scc</filename> files to be description files.
             </para>
         </footnote>
         description files, configuration fragments, and patches.
         The <filename>scc</filename> files define variables and include or
         otherwise reference any of the three file types.
-        The description files are used to aggregate all types of metadata into
+        The description files are used to aggregate all types of kernel
+        Metadata into
         what ultimately describes the sources and the configuration required
         to build a Linux kernel tailored to a specific machine.
     </para>
 
     <para>
         The <filename>scc</filename> description files are used to define two
-        fundamental types of metadata:
+        fundamental types of kernel Metadata:
         <itemizedlist>
             <listitem><para>Features</para></listitem>
             <listitem><para>Board Support Packages (BSPs)</para></listitem>
@@ -549,12 +554,12 @@ git repository:
 
     <para>
         Features aggregate sources in the form of patches and configuration
-        in the form of configuration fragments into a modular reusable unit.
-        Features are used to implement conceptually separate metadata
-        descriptions like pure configuration fragments, simple patches,
-        complex features, and kernel types (ktypes).
-        Kernel types define general kernel features and policy to be reused
-        in the BSPs.
+        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.
+        <link linkend='kernel-types'>Kernel types</link> define general
+        kernel features and policy to be reused in the BSPs.
     </para>
 
     <para>
@@ -563,10 +568,11 @@ git repository:
     </para>
 
     <para>
-        While the 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 meta-data.
-        The following metadata file hierarchy is recommended:
+        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:
         <literallayout class='monospaced'>
      &lt;base&gt;/
         bsp/
@@ -578,44 +584,55 @@ git repository:
     </para>
 
     <para>
-        The <filename>bsp</filename> directory should contain the
-        BSP descriptions, described in detail in section 3.3.5.
-        The remaining directories all contain "features"; the separation
-        is meant to aid in conceptualizing their intended usage.
-        A simple guide to determine where your <filename>scc</filename>
-        description file should go is as follows.
-        If it contains only configuration fragments, it belongs in
-        <filename>cfg</filename>.
-        If it contains only source-code fixes, it belongs in
-        <filename>patches</filename>.
-        If it encapsulates a major feature, often combining sources and
-        configurations, it belongs in <filename>features</filename>.
-        If it aggregates non-hardware configuration and patches
-        in order to define a base kernel policy or major kernel type to
-        be reused across multiple BSPs, it belongs in
-        <filename>ktypes</filename>.
+        The <filename>bsp</filename> directory contains the
+        <link linkend='bsp-descriptions'>BSP descriptions</link>.
+        The remaining directories all contain "features".
+        Separating <filename>bsp</filename> from the rest of the structure
+        aids conceptualizing intended usage.
+    </para>
+
+    <para>
+        Use these guidelines to help place your <filename>scc</filename>
+        description files within the structure:
+        <itemizedlist>
+            <listitem><para>If your file contains
+                only configuration fragments, place the file in
+                <filename>cfg</filename>.</para></listitem>
+            <listitem><para>If your file contains
+                only source-code fixes, place the file in
+                <filename>patches</filename>.</para></listitem>
+            <listitem><para>If your file encapsulates
+                a major feature, often combining sources and configurations,
+                place the file in <filename>features</filename>.
+                </para></listitem>
+            <listitem><para>If your file aggregates
+                non-hardware configuration and patches in order to define a
+                base kernel policy or major kernel type to be reused across
+                multiple BSPs, place the file in <filename>ktypes</filename>.
+                </para></listitem>
+        </itemizedlist>
     </para>
 
     <para>
-        The lines between these can easily become blurred, especially as
-        out-of-tree features are slowly merged upstream over time.
-        Also remember that this is purely logical organization and has
-        no impact on the functionality of the metadata as
-        all of <filename>cfg</filename>, <filename>features</filename>,
-        <filename>patches</filename>, and <filename>ktypes</filename>,
-        contain "features" as far as the Yocto Project Linux kernel
+        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 because all of <filename>cfg</filename>,
+        <filename>features</filename>, <filename>patches</filename>, and
+        <filename>ktypes</filename>, contain "features" as far as the kernel
         tools are concerned.
     </para>
 
     <para>
-        Paths used in metadata files are relative to
+        Paths used in kernel Metadata files are relative to
         <filename>&lt;base&gt;</filename>, which is either
         <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
-        if you are creating metadata in recipe-space as described in
-        section "<link linkend='recipe-space-metadata'>Recipe-Space Metadata</link>",
+        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 in-tree as described in
-        the "<link linkend='in-tree-metadata'>In-Tree Metadata</link>" section.
+        Metadata <link linkend='in-tree-metadata'>in-tree</link>.
     </para>
 
     <para>