documentation: dev-manual - edits to kernel section and compliance

* Edits to get the patching the kernel section more sane.

* A tweak to the opening sentence of the compliance section to
  rid it of the split-infinitives.

(From yocto-docs rev: 8e2ff293e85a602efd98aceb20da5a2ea5f2a34d)

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

2 files changed, 173 insertions, 168 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index fc7a535..ce41a28 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1626,7 +1626,7 @@
         </para>
 
         <para>
-            The example assumes a clean build exists for the <filename>x86qemu</filename>
+            The example assumes a clean build exists for the <filename>qemux86</filename>
             machine in a Source Directory named <filename>poky</filename>.
             Furthermore, the <link linkend='build-directory'>Build Directory</link> is 
             <filename>build</filename> and is located in <filename>poky</filename> and  
@@ -1637,13 +1637,13 @@
             <title>Create a Layer for your Changes</title>
 
             <para>
-                The first step is to isolate your changes into a layer:
+                The first step is to create a layer so you can isolate your changes:
                 <literallayout class='monospaced'>
      $cd ~/poky
      $mkdir meta-mylayer
                 </literallayout>
                 Creating a directory that follows the Yocto Project layer naming 
-                conventions sets up the area for your changes.  
+                conventions sets up the layer for your changes.  
                 The layer is where you place your configuration files, append
                 files, and patch files. 
                 To learn more about creating a layer and filling it with the 
@@ -1657,26 +1657,24 @@
 
             <para>
                 Each time you build a kernel image, the kernel source code is fetched 
-                and unpacked into a temporary location in the <link linkend='build-directory'>Build Directory</link>.
-                See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" 
-                section for a description of where the OpenEmbedded build system places
-                kernel source files during a build.
-                Following is where machine-specific source code is temporarily stored
-                during the build:
+                and unpacked into the following directory:
                 <literallayout class='monospaced'>
-     ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+     ${S}/linux
                 </literallayout>
+                See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" 
+                section and the 
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
+                for more information about where source is kept during a build.
                 For this example, the directory that 
                 holds the temporary source code is here:
                 <literallayout class='monospaced'>
-     ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3
+     ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3/linux
                 </literallayout>
-                Within the <filename>linux</filename> directory, you find directories for 
-                the source.
             </para>
 
             <para>
-                For this example, we are going to patch the <filename>init/calibrate.c</filename> file
+                For this example, we are going to patch the 
+                <filename>init/calibrate.c</filename> file
                 by adding some simple console <filename>printk</filename> statements that we can 
                 see when we boot the image using QEMU.
             </para>
@@ -1686,39 +1684,31 @@
             <title>Creating the Patch</title>
 
             <para>
-                Two methods exist by which you can create the patch: Git workflow and Quilt workflow.
+                Two methods exist by which you can create the patch: 
+                <link linkend='using-a-git-workflow'>Git workflow</link> and 
+                <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
                 For kernel patches, the Git workflow is more appropriate. 
-                This section assumes the Git workflow.
-            </para>
-
-            <para>
-                To create the patch for the <filename>calibrate.c</filename>, follow steps
-                3 through 12 outlined in the 
-                "<link linkend='using-a-git-workflow'>Using a Git Workflow</link>" 
-                section.
-                For step 6 (Edit the Files), do the following:
-            </para>
-
-            <para>
-                Locate the <filename>void __cpuinit calibrate_delay(void)</filename>
-                function:
-                <literallayout class='monospaced'>
-     void __cpuinit calibrate_delay(void)
-     {
-     	unsigned long lpj;
-     	static bool printed;
-     	int this_cpu = smp_processor_id();
-
-     	if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
-               .
-               .
-               .
-                </literallayout>
-            </para>
-
-            <para>
-                Alter the code as follows:
-                <literallayout class='monospaced'>
+                This section assumes the Git workflow and shows the steps specific to 
+                this example.
+                <orderedlist>
+                    <listitem><para><emphasis>Change the working directory</emphasis>:
+                        Change to where the kernel source code is before making 
+                        your edits to the <filename>calibrate.c</filename> file:
+                        <literallayout class='monospaced'>
+     $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
+                        </literallayout>
+                        Because you are working in an established Git repository, 
+                        you must be in this directory in order to commit your changes
+                        and create the patch file.
+                        <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and 
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
+                            represent the version and revision for the 
+                            <filename>linux-yocto</filename> recipe.
+                        </note></para></listitem>
+                    <listitem><para><emphasis>Edit the source file</emphasis>:
+                        Edit the <filename>init/calibrate.c</filename> file to have the 
+                        following changes:
+                        <literallayout class='monospaced'>
      void __cpuinit calibrate_delay(void)
      {
          unsigned long lpj;
@@ -1735,44 +1725,49 @@
                .
                .
                .
-                </literallayout>
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Stage and commit your changes</emphasis>:
+                        These Git commands list out the changed file, stage it, and then 
+                        commit the files:
+                        <literallayout class='monospaced'>
+     $ git status
+     $ git add init/calibrate.c
+     $ git commit
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Generate the patch file</emphasis>:
+                        This Git command creates the a patch file named
+                        <filename>0001-calibrate.c.patch</filename> in the current directory.
+                        <literallayout class='monospaced'>
+     $ git format-patch HEAD~1
+                        </literallayout>
+                        <note>The name of the patch file is based on your commit summary
+                            line.</note>
+                        </para></listitem>
+                </orderedlist>
             </para>
         </section>
 
         <section id='get-your-layer-setup-for-the-build'>
             <title>Get Your Layer Setup for the Build</title>
 
-           <para>
-               At this point, you have a patch file in the kernel's source code directory.
-               The patch file is named according to the commit's summary line and ends
-               with <filename>.patch</filename>.
-               For this example, it is named <filename>0001-calibrate.c.patch</filename>.
-           </para>
-
-           <para>
-               You need to move the patch file to your layer next. 
-               The patch file needs to reside in the 
-               <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> directory. 
-               Create this directory path within your layer and move the patch file.
-               This directory path mirrors that used by the main kernel recipe in 
-               the Source Directory (<filename>poky</filename>).
-               <literallayout class='monospaced'>
+            <para>These steps get your layer set up for the build:
+                <orderedlist>
+                    <listitem><para><emphasis>Create additional structure</emphasis>:
+                        Create the additional layer structure:
+                        <literallayout class='monospaced'>
      $ cd ~/poky/meta-mylayer
+     $ mkdir conf
      $ mkdir recipes-kernel
      $ mkdir recipes-kernel/linux
      $ mkdir recipes-kernel/linux/linux-yocto
-               </literallayout> 
-           </para>
-
-           <para>
-               Next, you need to create a <filename>conf</filename> directory in your layer 
-               and within it create the <filename>layer.conf</filename> file. 
-               You can find information on this in the 
-               "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>" 
-               section. 
-               Here is what your <filename>layer.conf</filename> should look like for this 
-               example:
-               <literallayout class='monospaced'>
+                         </literallayout>
+                         The <filename>conf</filename> directory holds your configuration files, while the 
+                         <filename>recipes-kernel</filename> directory holds your append file and 
+                         your patch file.</para></listitem>
+                    <listitem><para><emphasis>Create the layer configuration file</emphasis>:
+                        Move to the <filename>meta-mylayer/conf</filename> directory and create
+                        the <filename>layer.conf</filename> file as follows:
+                        <literallayout class='monospaced'>
      # We have a conf and classes directory, add to BBPATH
      BBPATH := "${LAYERDIR}:${BBPATH}"
 
@@ -1783,80 +1778,85 @@
      BBFILE_COLLECTIONS += "mylayer"
      BBFILE_PATTERN_mylayer := "^${LAYERDIR}/"
      BBFILE_PRIORITY_mylayer = "5"
-               </literallayout> 
-           </para>
-
-           <para>
-               Do the following to make sure the build parameters are set up for the example.
-               Once you set up these build parameters, they do not have to change unless you 
-               change the target architecture of the machine you are building:
-               <itemizedlist>
-                   <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The 
-                       <filename>local.conf</filename> file in the build directory defines the build's 
-                       target architecture.
-                       By default, <filename>MACHINE</filename> is set to 
-                       <filename>qemux86</filename>, which specifies a 32-bit 
-                       <trademark class='registered'>Intel</trademark> Architecture 
-                       target machine suitable for the QEMU emulator.  
-                       In this example, <filename>MACHINE</filename> is correctly configured.
-                       </para></listitem>
-                   <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the 
-                       <filename>local.conf</filename> file are two variables that can speed your 
-                       build time if your host supports multi-core and multi-thread capabilities:
-                       <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
-                       If the host system has multiple cores then you can optimize build time 
-                       by setting both these variables to twice the number of 
-                       cores.</para></listitem>
-                   <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
-                       Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the 
-                       <filename>bblayers.conf</filename> file found in the 
-                       <filename>poky/build/conf</filename> directory needs to have the path to your local
-                       <filename>meta-mylayer</filename> layer.  
-                       By default, the <filename>BBLAYERS</filename> variable contains paths to  
-                       <filename>meta</filename>, <filename>meta-yocto</filename>, and 
-                       <filename>meta-yocto-bsp</filename> in the 
-                       <filename>poky</filename> Git repository.
-                       Add the path to your <filename>meta-mylayer</filename> location.
-                       Be sure to substitute your user information in the statement.
-                       Here is an example:
-                       <literallayout class='monospaced'>
-     BBLAYERS = " \
-       /home/scottrif/poky/meta \
-       /home/scottrif/poky/meta-yocto \
-       /home/scottrif/poky/meta-yocto-bsp \
-       /home/scottrif/poky/meta-mylayer \
-       "
-                       </literallayout></para></listitem>
-                   <listitem><para><emphasis>Create a bbappend File:</emphasis> You need to create
-                       an append file for the main 3.4 kernel recipe.
-                       Create the append file in the <filename>linux</filename> directory you  
-                       created earlier within your layer. 
-                       Assuming the patch file is named 
-                       <filename>0001-documentation-calibrate.c.patch</filename>, your append
-                       file, which must be named <filename>linux-yocto_3.4.bbappend</filename>,
-                       has these statements:
-                       <literallayout class='monospaced'>
+                         </literallayout>
+                         Notice <filename>mylayer</filename> as part of the last three 
+                         statements.</para></listitem>
+                    <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
+                        Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
+                        the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
+                        <literallayout class='monospaced'>
      FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
 
-     SRC_URI += "file://0001-documentation-calibrate.c.patch"
+     SRC_URI += "file://0001-calibrate.c.patch"
 
      PRINC := "${@int(PRINC) + 1}"                       
-                       </literallayout>
-                       The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
-                       statements ensure the OpenEmbedded build system picks up the patch file.
-                       </para></listitem>
-               </itemizedlist>
-           </para>
-       </section>
+                        </literallayout>
+                        The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
+                        statements enable the OpenEmbedded build system to find the patch file.
+                        </para></listitem>
+                    <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
+                        Move the <filename>0001-calibrate.c.patch</filename> file to 
+                        the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
+                        directory.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='set-up-for-the-build'>
+            <title>Set Up for the Build</title>
+
+            <para>
+                Do the following to make sure the build parameters are set up for the example.
+                Once you set up these build parameters, they do not have to change unless you 
+                change the target architecture of the machine you are building:
+                <itemizedlist>
+                    <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The 
+                        <filename>local.conf</filename> file in the build directory defines the build's 
+                        target architecture.
+                        By default, <filename>MACHINE</filename> is set to 
+                        <filename>qemux86</filename>, which specifies a 32-bit 
+                        <trademark class='registered'>Intel</trademark> Architecture 
+                        target machine suitable for the QEMU emulator.  
+                        In this example, <filename>MACHINE</filename> is correctly configured.
+                        </para></listitem>
+                    <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the 
+                        <filename>local.conf</filename> file are two variables that can speed your 
+                        build time if your host supports multi-core and multi-thread capabilities:
+                        <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
+                        If the host system has multiple cores then you can optimize build time 
+                        by setting both these variables to twice the number of 
+                        cores.</para></listitem>
+                    <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
+                        Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the 
+                        <filename>bblayers.conf</filename> file found in the 
+                        <filename>poky/build/conf</filename> directory needs to have the path to your local
+                        <filename>meta-mylayer</filename> layer.  
+                        By default, the <filename>BBLAYERS</filename> variable contains paths to  
+                        <filename>meta</filename>, <filename>meta-yocto</filename>, and 
+                        <filename>meta-yocto-bsp</filename> in the 
+                        <filename>poky</filename> Git repository.
+                        Add the path to your <filename>meta-mylayer</filename> location.
+                        Be sure to substitute your user information in the statement:
+                        <literallayout class='monospaced'>
+     BBLAYERS = " \
+       /home/&lt;user&gt;/poky/meta \
+       /home/&lt;user&gt;/poky/meta-yocto \
+       /home/&lt;user&gt;/poky/meta-yocto-bsp \
+       /home/&lt;user&gt;/poky/meta-mylayer \
+       "
+                        </literallayout></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
 
-        <section id='building-and-booting-the-modified-qemu-kernel-image'>
-            <title>Building and Booting the Modified QEMU Kernel Image</title>
+        <section id='build-and-booting-the-modified-qemu-kernel-image'>
+            <title>Build and Booting the Modified QEMU Kernel Image</title>
 
             <para>
-                Next, you need to build the modified image.
-                Do the following:
+                The following steps build and boot your modified kernel image:
                 <orderedlist>
-                    <listitem><para>Your environment should be set up since you previously sourced
+                    <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
+                        Your environment should be set up since you previously sourced
                         the <filename>&OE_INIT_FILE;</filename> script.
                         If it isn't, source the script again from <filename>poky</filename>.
                         <literallayout class='monospaced'>
@@ -1864,7 +1864,8 @@
      $ source &OE_INIT_FILE;
                         </literallayout>
                         </para></listitem>
-                    <listitem><para>Be sure old images are cleaned out by running the 
+                    <listitem><para><emphasis>Clean up</emphasis>:
+                        Be sure old images are cleaned out by running the 
                         <filename>cleanall</filename> BitBake task as follows from your build directory:
                         <literallayout class='monospaced'>
      $ bitbake -c cleanall linux-yocto
@@ -1873,29 +1874,36 @@
                         directory inside the build directory.
                         Always use the BitBake <filename>cleanall</filename> task to clear
                         out previous builds.</note></para></listitem>
-                    <listitem><para>Next, build the kernel image using this command:
+                    <listitem><para><emphasis>Build the image</emphasis>:
+                        Next, build the kernel image using this command:
                         <literallayout class='monospaced'>
      $ bitbake -k linux-yocto
                         </literallayout></para></listitem>
-                    <listitem><para>Finally, boot the modified image in the QEMU emulator 
-                        using this command:
-                        <literallayout class='monospaced'>
-     $ runqemu qemux86
-                        </literallayout></para></listitem>
                 </orderedlist>
             </para>
+        </section>
 
-            <para>
-                Log into the machine using <filename>root</filename> with no password and then 
-                use the following shell command to scroll through the console's boot output.
-                <literallayout class='monospaced'>
-     # dmesg | less
-                </literallayout>
-            </para>
+        <section id='verify-your-changes'>
+            <title>Verify Your Changes</title>
 
             <para>
-                You should see the results of your <filename>printk</filename> statements 
-                as part of the output.
+                These steps boot the image and allow you to see the changes
+                <orderedlist>
+                    <listitem><para><emphasis>Boot the image</emphasis>:
+                        Boot the modified image in the QEMU emulator 
+                        using this command:
+                        <literallayout class='monospaced'>
+     $ runqemu qemux86
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Verify the changes</emphasis>:
+                        Log into the machine using <filename>root</filename> with no password and then 
+                        use the following shell command to scroll through the console's boot output.
+                        <literallayout class='monospaced'>
+     # dmesg | less
+                        </literallayout>
+                        You should see the results of your <filename>printk</filename> statements 
+                        as part of the output.</para></listitem>
+                </orderedlist>
             </para>
         </section>
     </section>
@@ -2625,8 +2633,8 @@
             One of the concerns for a development organization using open source
             software is how to maintain compliance with various open source
             licensing during the lifecycle of the product.
-            While this section is not meant to be legal advice or to 
-            comprehensively cover all scenarios, it is meant to 
+            While this section does not provide legal advice or  
+            comprehensively cover all scenarios, it does 
             present methods that you can use to 
             meet the compliance requirements during a software
             release.
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 436ecb6..b61eeb0 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1688,10 +1688,12 @@ directory.</para></listitem>
                     You need to be in the directory that has the temporary source code.
                     That directory is defined by the 
                     <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
-                    variable.
-                    For this discussion, assume that directory is <filename>linux</filename>.</para></listitem>
-                <listitem><para><emphasis>Initialize a Git Repository:</emphasis>
-                    Use the <filename>git init</filename> command to initialize a new local repository
+                    variable. 
+                    If you are working with a kernel, you need to be in the 
+                    <filename>${S}/linux</filename> directory.</para></listitem>
+                <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis>
+                    If you are not already in a Git repository, use the 
+                    <filename>git init</filename> command to initialize a new local repository
                     that is based on the work directory:
                     <literallayout class='monospaced'>
      $ git init
@@ -1730,11 +1732,6 @@ directory.</para></listitem>
                     "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 
                     section of the Yocto Project Quick Start.
                     </note></para></listitem>
-                <listitem><para><emphasis>Change Your Working Directory:</emphasis>
-                    After making your edits, move back to the directory from which you 
-                    initialized the Git repository.
-                    Returning to this directory ensures you are using the correct branch when 
-                    you go to commit your changes.</para></listitem>
                 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
                     Use the <filename>git status</filename> command to see what files you have actually edited. 
                     The ability to have Git track the files you have changed is an advantage that this
@@ -1749,7 +1746,7 @@ directory.</para></listitem>
                     Again, for this discussion assume the files changed are in the <filename>linux</filename>
                     directory:
                     <literallayout class='monospaced'>
-     $ git add linux/file1.c linux/file2.c linux/file3.c
+     $ git add &lt;somepath&gt;/file1.c &lt;somepath&gt;/file2.c &lt;somepath&gt;/file3.c
                     </literallayout></para></listitem>
                 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
                     Use the <filename>git commit</filename> command to commit the changes to the