documentation: Makefile, dev-manual - edits to patching kernel

Made some general edits to the new "Patching the Kernel" section.
Also had to remove a couple of images no longer used in the section
from the Makefile "TARFILES" variable.

(From yocto-docs rev: ac61e22e2f89926fbbda56fbaa4384c3c5156360)

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

2 files changed, 118 insertions, 88 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 78c1f39e18..0215fcf21a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1625,30 +1625,77 @@
             messages to appear on the emulator's console.
         </para> 
 
-        <section id='creating-the-patch'>
-            <title>Creating the Patch</title>
+        <section id='create-a-layer-for-your-changes'>
+            <title>Create a Layer for your Changes</title>
 
             <para>
-                Describe how to find the source files in the build area.  
-                We are not assuming they are using their own kernel tree.
+                The first step is to isolate your changes into a layer:
+                <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 layer.  
+                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 
+                files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
+                and Creating Layers</link>" section.                
+            </para>
+        </section>
+
+        <section id='finding-the-kernel-source-code'>
+            <title>Finding the Kernel Source Code</title>
+
+            <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:
+                <literallayout class='monospaced'>
+     ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+                </literallayout>
+                Assuming a recent build for the <filename>qemux86</filename> machine 
+                based on the Linux 3.4 kernel, a  
+                <link linkend='source-directory'>Source Directory</link> named <filename>poky</filename>, and
+                the existence of a default <filename>build</filename> directory, the directory that 
+                holds the temporary source code would be here:
+                <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3
+                </literallayout>
+                Within the <filename>linux</filename> directory, you find the source directories.
+            </para>
 
+            <para>
+                For this example, we are going to patch the <filename>init/calibrate.c</filename> file
+                and add some simple console <filename>printk</filename> statements that we can 
+                see when we boot the image using QEMU.
             </para>
         </section> 
 
+        <section id='creating-the-patch'>
+            <title>Creating the Patch</title>
 
-        <section id='changing-the-source-code-and-pushing-it-to-the-bare-clone'>
-            <title>Changing the Source Code and Pushing it to the Bare Clone</title>
+            <para>
+                Two methods exist by which you can create the patch: Git workflow and Quilt workflow.
+                For kernel patches, the Git workflow is more appropriate. 
+                This section assumes the Git workflow.
+            </para>
 
             <para>
-                The file you change in this example is named <filename>calibrate.c</filename>
-                and is located in the <filename>my-linux-yocto-3.4-work</filename> Git repository
-                (the copy of the bare clone) in <filename>init</filename>.
-                This example simply inserts several <filename>printk</filename> statements
-                at the beginning of the <filename>calibrate_delay</filename> function.
+                To create the patch for the <filename>calibrate.c</filename>, follow the steps
+                outlined in the 
+                "<link linkend='using-a-git-workflow'>Using a Git Workflow</link>" 
+                section.
+                For the steps used to edit the source file, do the following:
             </para>
 
             <para>
-                Here is the unaltered code at the start of this function:
+                Locate the <filename>void __cpuinit calibrate_delay(void)</filename>
+                function:
                 <literallayout class='monospaced'>
      void __cpuinit calibrate_delay(void)
      {
@@ -1660,12 +1707,11 @@
                .
                .
                .
-               </literallayout>
-           </para>
+                </literallayout>
+            </para>
 
-           <para>
-               Here is the altered code showing five new <filename>printk</filename> statements 
-               near the top of the function:
+            <para>
+                Alter the code as follows:
                 <literallayout class='monospaced'>
      void __cpuinit calibrate_delay(void)
      {
@@ -1683,51 +1729,47 @@
                .
                .
                .
-               </literallayout>
-           </para>
+                </literallayout>
+            </para>
+        </section>
 
-           <para>
-               After making and saving your changes, you need to stage them for the push.
-               The following Git commands are one method of staging and committing your changes:
-               <literallayout class='monospaced'>
-     $ git add calibrate.c
-     $ git commit --signoff
-               </literallayout>
-           </para>
+        <section id='get-your-layer-setup-for-the-build'>
+            <title>Get Your Layer Setup for the Build</title>
 
            <para>
-               Once the source code has been modified, you need to use Git to push the changes to 
-               the bare clone.  
-               If you do not push the changes, then the OpenEmbedded build system will not pick 
-               up the changed source files.
+               At this point, you have a patch file in the same directory as your original 
+               <filename>calibrate.c</filename>.
+               Move it to your layer and place it in a separate folder having the same 
+               name as the recipe, which is <filename>linux-yocto</filename> in this case. 
            </para>
 
            <para>
-               The following command pushes the changes to the bare clone:
+               Next, you need to set up your <filename>conf</filename> directory in your layer. 
+               Create the <filename>conf</filename> and 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'>
-     $ git push origin standard-common-pc-base:standard/default/common-pc/base
-               </literallayout>
-           </para>
-       </section>
+     # We have a conf and classes directory, add to BBPATH
+     BBPATH := "${LAYERDIR}:${BBPATH}"
 
-       <section id='changing-build-parameters-for-your-build'>
-           <title>Changing Build Parameters for Your Build</title>
+     # We have a packages directory, add to BBFILES
+     BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
+                 ${LAYERDIR}/recipes-*/*/*.bbappend"
 
-           <para>
-               At this point, the source has been changed and pushed.
-               The example now defines some variables used by the OpenEmbedded build system 
-               to locate your kernel source.
-               You essentially need to identify where to find the kernel recipe and the changed source code.
-               You also need to be sure some basic configurations are in place that identify the 
-               type of machine you are building and to help speed up the build should your host support
-               multiple-core and thread capabilities.
+     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 or you move
-               the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository:
+               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 
@@ -1745,15 +1787,16 @@
                        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-kernel-dev</filename>
+                   <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-kernel-dev</filename> layer.  
+                       <filename>meta-mylayer</filename> layer.  
                        By default, the <filename>BBLAYERS</filename> variable contains paths to  
-                       <filename>meta</filename> and <filename>meta-yocto</filename> in the 
+                       <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-kernel-dev</filename> location.
+                       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'>
@@ -1761,43 +1804,27 @@
        /home/scottrif/poky/meta \
        /home/scottrif/poky/meta-yocto \
        /home/scottrif/poky/meta-yocto-bsp \
-       /home/scottrif/poky/poky-extras/meta-kernel-dev \
+       /home/scottrif/poky/meta-mylayer \
        "
                        </literallayout></para></listitem>
-                   <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the 
-                       <filename>linux-yocto_3.4.bbappend</filename> file located in the 
-                       <filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename>
-                       directory, you need to identify the location of the 
-                       local source code, which in this example is the bare clone named
-                       <filename>linux-yocto-3.4.git</filename>.
-                       To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your
-                       local <filename>linux-yocto-3.4.git</filename> Git repository by adding the 
-                       following statement.
-                       Also, be sure the <filename>SRC_URI</filename> variable is pointing to
-                       your kernel source files by removing the comment.
-                       Finally, be sure to substitute your user information in the statement:
+                   <listitem><para><emphasis>Create a bbappend File:</emphasis> You need to have
+                       an append file to the main 3.4 kernel recipe.
+                       Locate the append file in your <filename>meta-mylayer</filename> layer.
+                       It needs to be in a <filename>meta-mylayer/recipes-kernel/linux</filename> directory.
+                       Create the directory and use the following for the append file.
+                       This example assumes patch file is named <filename>0001-documentation-calibrate.c.patch</filename>:
                        <literallayout class='monospaced'>
-     KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git"
-     SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
-                       </literallayout></para></listitem>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+     SRC_URI += "file://0001-documentation-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>
-
-           <note>
-               <para>Before attempting to build the modified kernel, there is one more set of changes you 
-               need to make in the <filename>meta-kernel-dev</filename> layer.
-               Because all the kernel <filename>.bbappend</filename> files are parsed during the 
-               build process regardless of whether you are using them or not, you should either 
-               comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all 
-               unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files 
-               except the one your are using for the build 
-               (i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para>
-               <para>If you do not make one of these two adjustments, your machine will be compatible
-               with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer. 
-               When your machine is comapatible with all the kernel recipes, the build attempts
-               to build all kernels in the layer.
-               You could end up with build errors blocking your work.</para>
-           </note>            
        </section>
 
         <section id='building-and-booting-the-modified-qemu-kernel-image'>
@@ -1826,7 +1853,7 @@
                         out previous builds.</note></para></listitem>
                     <listitem><para>Next, build the kernel image using this command:
                         <literallayout class='monospaced'>
-     $ bitbake -k core-image-minimal
+     $ bitbake -k linux-yocto
                         </literallayout></para></listitem>
                     <listitem><para>Finally, boot the modified image in the QEMU emulator 
                         using this command:
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 9d73f8e4f5..03bb83096e 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1688,7 +1688,8 @@ 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.</para></listitem>
+                    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
                     that is based on the work directory:
@@ -1739,9 +1740,11 @@ directory.</para></listitem>
                     </literallayout></para></listitem>
                 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
                     Use the <filename>git add</filename> command to stage the changed files so they
-                    can be committed as follows:
+                    can be committed as follows.
+                    Again, for this discussion assume the files changed are in the <filename>linux</filename>
+                    directory:
                     <literallayout class='monospaced'>
-     $ git add file1.c file2.c file3.c
+     $ git add linux/file1.c linux/file2.c linux/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