kernel-dev: Edits to using metadata in a recipe section.

General edits to clarify the writing.

(From yocto-docs rev: 0510ab0faf81e0ac1c931863337eb217581c66ed)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 43 insertions, 37 deletions

diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index ad46fcc8f0..a951aaec5d 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -77,7 +77,7 @@ to source changes.
         feature enablement.
         The BSP can be influenced from within the linux-yocto recipe.
         <note>
-            Linux kernel source that contains this Metadata is said to be
+            Linux kernel source that contains kernel Metadata is said to be
             "linux-yocto style" kernel source.
             A Linux kernel recipe that inherits from the
             <filename>linux-yocto.inc</filename> include file is said to be a
@@ -91,14 +91,15 @@ to source changes.
         variable.
         This variable is typically set to the same value as the
         <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
-        variable used by BitBake (e.g. "routerstationpro" or "fri2").
-        However, multiple BSPs can reuse the same <filename>KMACHINE</filename>
+        variable, which is used by BitBake (e.g. "routerstationpro" or "fri2").
+        Multiple BSPs can reuse the same <filename>KMACHINE</filename>
         name if they are built using the same BSP description.
+        The "fri2" and "fri2-noemgd" BSP combination
+        in the <filename>meta-intel</filename>
+        layer is a good example of two BSPs using the same
+        <filename>KMACHINE</filename> value (i.e. "fri2").
         See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section
         for more information.
-        The <filename>meta-intel</filename> "fri2" and "fri2-noemgd" are good
-        examples of such a situation where each specifies
-        <filename>KMACHINE</filename> as "fri2".
     </para>
 
     <para>
@@ -110,39 +111,43 @@ to source changes.
      KBRANCH_DEFAULT
      LINUX_KERNEL_TYPE
         </literallayout>
-        <filename>KBRANCH_DEFAULT</filename> defines the default source branch
-        within the Linux kernel source repository to be used to build the
-        Linux kernel.
-        It is used as the default value for <filename>KBRANCH</filename> which
-        may define an alternate branch, typically with a machine override,
-        such as:
+        <filename>KBRANCH_DEFAULT</filename> defines the Linux kernel source
+        repository's default branch to use to build the Linux kernel.
+        The value is used as the default for <filename>KBRANCH</filename>, which
+        can define an alternate branch typically with a machine override as
+        follows:
         <literallayout class='monospaced'>
      KBRANCH_fri2 = "standard/fri2"
         </literallayout>
         Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename>
-        is initialized to "master".
+        initializes to "master".
     </para>
 
     <para>
         <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be
-        used in assembling the configuration and defaults to "standard"
-        if you do not specify otherwise.
-        Together with <filename>KMACHINE</filename>, this defines the search
-        arguments used by the Yocto Project Linux kernel tools to find the
-        appropriate description within the metadata with which to build out
-        the sources and configuration.
+        used in assembling the configuration.
+        If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
+        it defaults to "standard".
+        Together with <filename>KMACHINE</filename>,
+        <filename>LINUX_KERNEL_TYPE</filename> 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 section 3.3.4 for more inforation on kernel types.
+        See the <link linkend='kernel-types'>Kernel Types</link> section
+        for more inforation on kernel types.
     </para>
 
     <para>
-        During the build, the kern-tools will search for the BSP description
+        During the build, the kern-tools search for the BSP description
         file that most closely matches the <filename>KMACHINE</filename>
-        and <filename>LINUX_KERNEL_TYPE</filename> passed in from the
+        and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the
         recipe.
-        It will use the first BSP description it finds matching both variables.
-        Failing that it will issue a warning such as the following:
+        The tools use the first BSP description it finds that match
+        both variables.
+        If the tools cannot find a match, they issue a warning such as
+        the following:
         <literallayout class='monospaced'>
      WARNING: Can't find any BSP hardware or required configuration fragments.
      WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and
@@ -154,19 +159,19 @@ to source changes.
     </para>
 
     <para>
-        It will then search first for the <filename>KMACHINE</filename> and
+        The tools first search for the <filename>KMACHINE</filename> and
         then for the <filename>LINUX_KERNEL_TYPE</filename>.
-        If it cannot find a partial match, it will use the
+        If the tools cannot find a partial match, they will use the
         sources from the <filename>KBRANCH</filename> and any configuration
         specified in the <filename>SRC_URI</filename>.
     </para>
 
     <para>
-        <filename>KERNEL_FEATURES</filename> can be used to include features
-        (configuration fragments, patches, or both) that are not already
-        included by the <filename>KMACHINE</filename> and
-        <filename>LINUX_KERNEL_TYPE</filename> combination.
-        To include a feature specified as "features/netfilter.scc" for example,
+        You can use the <filename>KERNEL_FEATURES</filename> variable
+        to include features (configuration fragments, patches, or both) that
+        are not already included by the <filename>KMACHINE</filename> and
+        <filename>LINUX_KERNEL_TYPE</filename> variable combination.
+        For example, to include a feature specified as "features/netfilter.scc",
         specify:
         <literallayout class='monospaced'>
      KERNEL_FEATURES += "features/netfilter.scc"
@@ -177,12 +182,13 @@ to source changes.
      KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"
         </literallayout>
         The value of the entries in <filename>KERNEL_FEATURES</filename>
-        are dependent on their location within the metadata itself.
+        are dependent on their location within the kernel Metadata itself.
         The examples here are taken from the
         <filename>linux-yocto-3.4</filename> repository where "features"
-        and "cfg" are subdirectories of the <filename>metadata</filename>
-        directory.
-        For details, see section 3.3.
+        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.
         <note>
             The processing of the these variables has evolved some between the
                 0.9 and 1.3 releases of the Yocto Project and associated
@@ -275,8 +281,8 @@ metadata directory. For details, see 3.3.
     </para>
 </section>
 
-<section id='metadata-location'>
-    <title>Metadata Location</title>
+<section id='kernel-metadata-location'>
+    <title>Kernel Metadata Location</title>
 
     <para>
         This metadata can be defined along with the Linux kernel