dev-manual, kernel-dev: Working kernel flow process using devtool

A work-in-progress of an example that modifies the kernel
using the devtool.  The procedure is not complete yet as it
does not run properly.

(From yocto-docs rev: 462ba2e46f237c294f05805ad5044291a085975d)

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

3 files changed, 408 insertions, 369 deletions

diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 94595756b8..aa03d85c56 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -123,6 +123,19 @@
                     section in the Yocto Project Reference Manual.
                     </para></listitem>
             </orderedlist>
+            Once you have completed the previous steps, you are ready to
+            continue using a given development path on your native Linux
+            machine.
+            If you are going to use BitBake, see the
+            "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+            section.
+            If you are going to use the Extensible SDK, see the
+            "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
+            Chapter in the Yocto Project Software Development Kit (SDK)
+            Developer's Guide.
+            If you are going to use Toaster, see the
+            "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
+            section in the Toaster User Manual.
         </para>
     </section>
 
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index cb50912ea4..14381afefc 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -45,6 +45,67 @@
                 information.
             </note>
         </para>
+
+        <para>
+            Following is a detailed example showing how to create a layer
+            without the aid of tools for building the kernel:
+            <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>
+                    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}"
+
+     # We have recipes-* directories, add to BBFILES
+     BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+                 ${LAYERDIR}/recipes-*/*/*.bbappend"
+
+     BBFILE_COLLECTIONS += "mylayer"
+     BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
+     BBFILE_PRIORITY_mylayer = "5"
+                    </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-calibrate-Add-printk-example.patch"
+                    </literallayout>
+                    The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                    and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                    statements enable the OpenEmbedded build system to find the patch file.
+                    For more information on using append files, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
+                    section in the Yocto Project Development Manual.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Put the patch file in your layer</emphasis>:
+                    Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
+                    the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
+                    directory.</para></listitem>
+            </orderedlist>
+        </para>
     </section>
 
     <section id='modifying-an-existing-recipe'>
@@ -72,11 +133,9 @@
         <para>
             Before modifying an existing recipe, be sure that you have created
             a minimal, custom layer from which you can work.
-            See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
-            section for some general resources.
-            You can also see the
-            "<link linkend='set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</link>"
-            section for a detailed example.
+            See the
+            "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
+            section for information.
         </para>
 
         <section id='creating-the-append-file'>
@@ -452,63 +511,51 @@
     <section id="using-devtool-to-patch-the-kernel">
         <title>Using <filename>devtool</filename> to Patch the Kernel</title>
 
-
         <para role='writernotes'>
-            Some stuff here for the using devtool from the wiki.
-            This whole section is WIP.
-            <orderedlist>
-                <listitem><para role='writernotes'>
-                    If you are dealing with real hardware, you can flash the
-                    new kernel image to a USB stick and boot the hardware to
-                    see it run.
-                    </para></listitem>
-                <listitem><para role='writernotes'>
-                    Checkout and modify the kernel source.
-                    This is where you make your changes to the image.
-                    </para></listitem>
-                <listitem><para role='writernotes'>
-                    Create a new image that uses the altered kernel.
-                    </para></listitem>
-                <listitem><para role='writernotes'>
-                    If you are working with actual hardware, you can flash
-                    the new image to a USB stick and use it to boot up the
-                    hardware.
-                    You can see your changes in action.
-                    </para></listitem>
-            </orderedlist>
+            This procedure currently does not work.
+            It is WIP.
+        </para>
+
+        <para>
+            The steps in this procedure show you how you can patch the
+            kernel using the extensible SDK and <filename>devtool</filename>.
+            <note>
+                Before attempting this procedure, be sure you have performed
+                the steps to get ready for updating the kernel as described
+                in the
+                "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
+                section.
+            </note>
         </para>
 
         <para>
-            Patching the kernel involves changing or adding configurations to an existing kernel,
-            changing or adding recipes to the kernel that are needed to support specific hardware features,
-            or even altering the source code itself.
+            Patching the kernel involves changing or adding configurations
+            to an existing kernel, changing or adding recipes to the kernel
+            that are needed to support specific hardware features, or even
+            altering the source code itself.
             <note>
-                You can use the <filename>yocto-kernel</filename> script
+                You can also use the <filename>yocto-kernel</filename> script
                 found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
                 under <filename>scripts</filename> to manage kernel patches and configuration.
                 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
-                section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
-                more information.</note>
+                section in the Yocto Project Board Support Packages (BSP)
+                Developer's Guide for more information.
+            </note>
         </para>
 
         <para>
-            This example creates a simple patch by adding some QEMU emulator console
-            output at boot time through <filename>printk</filename> statements in the kernel's
-            <filename>calibrate.c</filename> source code file.
+            This example creates a simple patch by adding some QEMU emulator
+            console output at boot time through <filename>printk</filename>
+            statements in the kernel's <filename>calibrate.c</filename> source
+            code file.
             Applying the patch and booting the modified image causes the added
             messages to appear on the emulator's console.
-        </para>
-
-        <para>
-            The example builds an extensible SDK, which is then used to
-            build, using <filename>devtool</filename>, a clean image for the
-            default <filename>qemux86</filename> machine in a
-            <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-            named <filename>poky</filename>.
-            In the example, the
-            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
-            is <filename>build</filename> and is located in the default
-            <filename>poky_sdk</filename> directory.
+            <note>
+                The example is a continuation of the setup procedure found in
+                the
+                "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop using <filename>devtool</filename></link>"
+                Section.
+            </note>
         </para>
 
         <para>
@@ -517,159 +564,93 @@
             section.
         </para>
 
-        <section id='patch-kernel-set-up-the-build-host'>
-            <title>Set Up the Build Host</title>
-
-            <para>
-                Prior to creating any actual patches for your kernel, you
-                need to prepare the build host.
-                This example builds an extensible SDK.
-                Follow these steps:
-                <itemizedlist>
-                    <listitem><para>
-                        <emphasis>Set Up the Build Environment:</emphasis>
-                        Be sure you are set up to use BitBake in a shell.
-                        See the
-                        "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
-                        section in the Yocto Project Development Manual for information
-                        on how to get a build host ready that is either a native
-                        Linux machine or a machine that uses CROPS.
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
-                        You need to have a local copy of the Yocto Project
-                        <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-                        (i.e. a local <filename>poky</filename> repository).
-                        See the
-                        "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
-                        and possibly the
-                        "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
-                        and
-                        "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
-                        sections all in the Yocto Project Development Manual for
-                        information on how to clone the <filename>poky</filename>
-                        repository and check out the appropriate branch for your work.
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>Initialize the Build Environment:</emphasis>
-                        While in the root directory of the Source Directory (i.e.
-                        <filename>poky</filename>), run the
-                        <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
-                        environment setup script to define the OpenEmbedded
-                        build environment on your build host.
-                        <literallayout class='monospaced'>
-     $ source &OE_INIT_FILE;
-                        </literallayout>
-                        Among other things, the script creates the
-                        <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
-                        which is <filename>build</filename> in this case
-                        and is located in the
-                        <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
-                        After the script runs, your current working directory
-                        is set to the <filename>build</filename> directory.
-                        <note>
-                            For information on running a memory-resident
-                            <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>,
-                            see the
-                            <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
-                            setup script.
-                        </note>
-                        </para></listitem>
-                </itemizedlist>
-            </para>
-        </section>
-
-        <section id='create-a-layer-for-your-changes'>
-            <title>Create a Layer for your Changes</title>
-
-            <para>
-                The first step is to create a layer so you can isolate your
-                changes to the kernel.
-                Rather than use the <filename>yocto-layer</filename> script
-                to create the layer, this example steps through the process
-                by hand.
-                If you want information on the script that creates a general
-                layer, see the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
-                section in the Yocto Project Development Manual.
-            </para>
-
-            <para>
-                These two commands create a directory you can use for your
-                layer:
-                <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ mkdir meta-mylayer
-                </literallayout>
-                Creating a directory that follows the Yocto Project layer naming
-                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
-                files you need, see the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
-                section in the Yocto Project Development Manual.
-            </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 the following directory:
+        <orderedlist>
+            <listitem><para>
+                <emphasis>Check Out the Kernel Source Files:</emphasis>
+                First you must use <filename>devtool</filename> to checkout
+                the kernel source code in its workspace.
+                Be sure you are in the terminal set up to do work
+                with the extensible SDK.
+                <note>
+                    See this
+                    <link linkend='setting-up-the-esdk-terminal'>step</link>
+                    in the
+                    "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
+                    section for more information.
+                </note>
+                Use the following <filename>devtool</filename> command
+                to check out the code:
                 <literallayout class='monospaced'>
-     ${S}/linux
+     $ devtool modify linux-yocto
+     Loading cache: 100% |#######################################################################| Time: 0:00:00
+     Loaded 1300 entries from dependency cache.
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+
+     Summary: There was 1 WARNING message shown.
+     Loading cache: 100% |########################################################################| Time: 0:00:00
+     Loaded 1300 entries from dependency cache.
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+
+     Summary: There was 1 WARNING message shown.
+     NOTE: Executing RunQueue Tasks
+     NOTE: Executing do_fetch...
+     NOTE: Executing do_unpack...
+     NOTE: Tasks Summary: Attempted 2 tasks of which 0 didn't need to be rerun and all succeeded.
+     NOTE: Executing RunQueue Tasks
+     NOTE: Executing do_kernel_checkout...
+     NOTE: Tasks Summary: Attempted 3 tasks of which 2 didn't need to be rerun and all succeeded.
+     NOTE: Patching...
+     NOTE: Executing RunQueue Tasks
+     NOTE: Executing do_validate_branches...
+     NOTE: Executing do_kernel_metadata...
+     NOTE: Executing do_patch...
+     NOTE: Tasks Summary: Attempted 6 tasks of which 3 didn't need to be rerun and all succeeded.
+     NOTE: Generating kernel config
+     NOTE: Executing RunQueue Tasks
+     NOTE: Executing do_kernel_configme...
+     NOTE: Executing do_prepare_recipe_sysroot...
+     NOTE: Executing do_configure...
+     NOTE: Tasks Summary: Attempted 9 tasks of which 6 didn't need to be rerun and all succeeded.
+     NOTE: Copying kernel config to srctree
+     NOTE: Source tree extracted to /home/scottrif/poky_sdk/workspace/sources/linux-yocto
+     NOTE: Recipe linux-yocto now set up to build from /home/scottrif/poky_sdk/workspace/sources/linux-yocto
                 </literallayout>
-                See the "<ulink url='&YOCTO_DOCS_DEV_URL;#finding-the-temporary-source-code'>Finding Temporary Source Code</ulink>"
-                section in the Yocto Project Development Manual 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.
-            </para>
-
-            <para>
-                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>
-        </section>
-
-        <section id='creating-the-patch'>
-            <title>Creating the Patch</title>
-
-            <para>
-                Two methods exist by which you can create the patch:
-                <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
-                and
-                <ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Quilt</ulink>.
-                For kernel patches, the Git workflow is more appropriate.
-                This section assumes the Git workflow and shows the steps
-                specific to this example.
+                <note>
+                    During the checkout operation, a bug exists that could
+                    cause errors such as the following to appear:
+                    <literallayout class='monospaced'>
+     ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
+            be3a89ce7c47178880ba7bf6293d7404 for
+            /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
+                    </literallayout>
+                    You can safely ignore these messages.
+                    The source code is correctly checked out.
+                </note>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Edit the Source Files</emphasis>
+                Follow these steps to make some simple changes to the source
+                files:
                 <orderedlist>
                     <listitem><para>
                         <emphasis>Change the working directory</emphasis>:
+                        In the previous step, the output noted where you can find
+                        the source files (e.g.
+                        <filename>~/poky_sdk/workspace/sources/linux-yocto</filename>).
                         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
+     $ cd ~/poky_sdk/workspace/sources/linux-yocto
                         </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.
-                            The <filename>PV</filename> variable includes the Git meta and machine
-                            hashes, which make the directory name longer than you might
-                            expect.
-                        </note></para></listitem>
+                        </para></listitem>
                     <listitem><para>
                         <emphasis>Edit the source file</emphasis>:
-                        Edit the <filename>init/calibrate.c</filename> file to have the
-                        following changes:
+                        Edit the <filename>init/calibrate.c</filename> file to have
+                        the following changes:
                         <literallayout class='monospaced'>
      void calibrate_delay(void)
      {
@@ -687,202 +668,239 @@
                .
                .
                .
-                        </literallayout></para></listitem>
-                    <listitem><para><emphasis>Stage and commit your changes</emphasis>:
-                        These Git commands display the modified file, stage it, and then
-                        commit the file:
-                        <literallayout class='monospaced'>
-     $ git status
-     $ git add init/calibrate.c
-     $ git commit -m "calibrate: Add printk example"
-                        </literallayout></para></listitem>
-                    <listitem><para><emphasis>Generate the patch file</emphasis>:
-                        This Git command creates the a patch file named
-                        <filename>0001-calibrate-Add-printk-example.patch</filename>
-                        in the current directory.
-                        <literallayout class='monospaced'>
-     $ git format-patch -1
                         </literallayout>
                         </para></listitem>
                 </orderedlist>
-            </para>
-        </section>
-
-        <section id='set-up-your-layer-for-the-build'>
-            <title>Set Up Your Layer for the Build</title>
-
-            <para>These steps get your layer set up for the build:
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Build the Updated Kernel Source:</emphasis>
+                To build the updated kernel source, use
+                <filename>devtool</filename>:
+                <literallayout class='monospaced'>
+     $ devtool build linux-yocto
+     Parsing recipes: 100% |####################################################################################| Time: 0:00:31
+     Parsing of 831 .bb files complete (0 cached, 831 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+     NOTE: There are 1 recipes to be removed from sysroot qemux86, removing...
+     NOTE: Resolving any missing task queue dependencies
+     Initialising tasks: 100% |#################################################################################| Time: 0:00:00
+     Checking sstate mirror object availability: 100% |#########################################################| Time: 0:00:00
+     NOTE: Executing SetScene Tasks
+     NOTE: Executing RunQueue Tasks
+     linux-yocto-4.10.17+git999-r0 do_compile: NOTE: linux-yocto: compiling from external source tree /home/scottrif/poky_sdk/workspace/sources/linux-yocto
+     NOTE: Tasks Summary: Attempted 471 tasks of which 454 didn't need to be rerun and all succeeded.
+
+     Summary: There was 1 WARNING message shown.
+                </literallayout>
+                </para></listitem>
+<!--
+            <listitem><para>
+
+NOTE: This stuff is how it would have been if a *.wic file was created
+      when the image was built earlier.  That is the method used by the
+      example in the wiki (https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk).
+      I am leaving it here for now.
+
+                <emphasis>Create the Image With the New Kernel:</emphasis>
+                Normally, you would create a new image using the
+                <filename>devtool build-image</filename> command.
+                However, this method can take some time and alters the
+                kernel source folder.
+                A faster option is to use
+                <ulink url='https://linux.die.net/man/8/kpartx'><filename>kpartx</filename></ulink>
+                to splice the new kernel into the image you have already built.
+                <note>
+                    You might have to install <filename>kpartx</filename>
+                    onto your build host.
+                </note>
+                Follow these steps to create the image with the new kernel:
                 <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>
-                         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}"
-
-     # We have recipes-* directories, add to BBFILES
-     BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
-                 ${LAYERDIR}/recipes-*/*/*.bbappend"
-
-     BBFILE_COLLECTIONS += "mylayer"
-     BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
-     BBFILE_PRIORITY_mylayer = "5"
-                         </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:
+                    <listitem><para>
+                        <emphasis>Make a Copy of Your Wic File:</emphasis>
+                        Create a copy of your Wic from into the
+                        <filename>/tmp</filename> directory:
                         <literallayout class='monospaced'>
-     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
-
-     SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
+     $ cp tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic /tmp
                         </literallayout>
-                        The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
-                        and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
-                        statements enable the OpenEmbedded build system to find the patch file.
-                        For more information on using append files, see the
-                        "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
-                        section in the Yocto Project Development Manual.
                         </para></listitem>
                     <listitem><para>
-                        <emphasis>Put the patch file in your layer</emphasis>:
-                        Move the <filename>0001-calibrate-Add-printk-example.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> Your
-                        selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
-                        definition within the <filename>local.conf</filename> file in the
-                        <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
-                        specifies the target architecture used when building the Linux kernel.
-                        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.</para></listitem>
-                    <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
-                        layer:</emphasis> The
-                        <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
-                        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-poky</filename>, and
-                        <filename>meta-yocto-bsp</filename> in the
-                        <filename>poky</filename> Git repository.
-                        Add the path to your <filename>meta-mylayer</filename> location:
+                        <emphasis>Create Loopback Devices for Partitions:</emphasis>
+                        Next, create loopback devices for each partition in
+                        the Wic file.
+                        <note>
+                            The first unused loopback device is automatically
+                            allocated.
+                        </note>
+                        In this example, the command's output uses a variable
+                        "<replaceable>X</replaceable>" to indicate the loopback
+                        device.
+                        The actual output you get when you run the command lists
+                        the actual loopback devices (e.g. "loop0p1", "loop0p2",
+                        and "loop0p3"):
                         <literallayout class='monospaced'>
-     BBLAYERS ?= " \
-       $HOME/poky/meta \
-       $HOME/poky/meta-poky \
-       $HOME/poky/meta-yocto-bsp \
-       $HOME/poky/meta-mylayer \
-       "
-                        </literallayout></para></listitem>
-                </itemizedlist>
-            </para>
-        </section>
-
-        <section id='build-the-modified-qemu-kernel-image'>
-            <title>Build the Modified QEMU Kernel Image</title>
-
-            <para>
-                The following steps build your modified kernel image:
-                <orderedlist>
-                    <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
-                        Your environment should be set up since you previously sourced
-                        the
-                        <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
-                        script.
-                        If it is not, source the script again from <filename>poky</filename>.
+     $ sudo kpartx -v -a /tmp/core-image-minimal-qemux86.wic
+     add map loop<replaceable>X</replaceable>p1 (253:6): 0 47446 linear /dev/loopX 2048
+     add map loop<replaceable>X</replaceable>p2 (253:7): 0 119356 linear /dev/loopX 51200
+     add map loop<replaceable>X</replaceable>p3 (253:8): 0 90112 linear /dev/loopX 170556
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Mount the First Device:</emphasis>
+                        The kernel is in the first device, so mount
+                        <filename>/dev/mapper/loop</filename><replaceable>X</replaceable><filename>p1</filename>:
+                        <note>
+                            Be sure to replace the "<replaceable>X</replaceable>"
+                            in "loop<replaceable>X</replaceable>p1" with the
+                            automatically allocated loopback device
+                            (e.g loop0p1).
+                        </note>
                         <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ source &OE_INIT_FILE;
+     $ sudo mkdir /mnt/wic-p1
+     $ sudo mount /dev/mapper/loop<replaceable>X</replaceable>p1 /mnt/wic-p1
                         </literallayout>
                         </para></listitem>
                     <listitem><para>
-                        <emphasis>Clean up</emphasis>:
-                        Be sure to clean the shared state out by using BitBake
-                        to run from within the Build Directory the
-                        <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>
-                        task as follows:
+                        <emphasis>Copy Over the New Kernel:</emphasis>
+                        Now copy over new kernel using the following:
                         <literallayout class='monospaced'>
-     $ bitbake -c cleansstate linux-yocto
-                        </literallayout></para>
-                        <para>
-                           <note>
-                               Never remove any files by hand from the
-                               <filename>tmp/deploy</filename>
-                               directory inside the
-                               <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
-                               Always use the various BitBake clean tasks to
-                               clear out previous build artifacts.
-                               For information on the clean tasks, see the
-                               "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>",
-                               "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>",
-                               and
-                               "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>"
-                               sections all in the Yocto Project Reference
-                               Manual.
-                           </note>
+     $ sudo cp workspace/sources/linux-yocto/arch/x86/boot/bzImage /mnt/wic-p1
+                        </literallayout>
                         </para></listitem>
                     <listitem><para>
-                        <emphasis>Build the image</emphasis>:
-                        Next, build the kernel image using this command:
+                        Finally, unmount the device and use
+                        <filename>kpartx</filename> to delete the partition
+                        mappings:
+                        <note>
+                            Replace the "<replaceable>X</replaceable>" in
+                            "loop<replaceable>X</replaceable>" with the
+                            automatically allocated loopback device from
+                            earlier (e.g "loop0").
+                        </note>
                         <literallayout class='monospaced'>
-     $ bitbake -k linux-yocto
-                        </literallayout></para></listitem>
+     $ sudo umount /mnt/wic-p1
+     $ sudo kpartx -d /dev/loop<replaceable>X</replaceable>
+                        </literallayout>
+                        </para></listitem>
                 </orderedlist>
-            </para>
-        </section>
-
-        <section id='boot-the-image-and-verify-your-changes'>
-            <title>Boot the Image and Verify Your Changes</title>
-
-            <para>
-                These steps boot the image and allow you to see the changes
+                </para></listitem>
+-->
+            <listitem><para>
+                <emphasis>Create the Image With the New Kernel:</emphasis>
+                Use the <filename>devtool build-image</filename> command
+                to create a new image that has the new kernel.
+                <note>
+                    If the image you originally created resulted in a Wic
+                    file, you can use an alternate method to create the new
+                    image with the updated kernel.
+                    For an example, see the steps in the
+                    <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
+                    Wiki Page.
+                </note>
+                <literallayout class='monospaced'>
+     $ cd ~
+     $ devtool build-image core-image-minimal
+     Loading cache: 100% |###########################################################################| Time: 0:00:00
+     Loaded 1299 entries from dependency cache.
+     Parsing recipes: 100% |#########################################################################| Time: 0:00:00
+     Parsing of 831 .bb files complete (830 cached, 1 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+
+     Summary: There was 1 WARNING message shown.
+     WARNING: Skipping recipe linux-yocto as it doesn't produce a package with the same name
+     WARNING: No recipes in workspace, building image core-image-minimal unmodified
+     Loading cache: 100% |###########################################################################| Time: 0:00:00
+     Loaded 1299 entries from dependency cache.
+     Parsing recipes: 100% |#########################################################################| Time: 0:00:00
+     Parsing of 831 .bb files complete (830 cached, 1 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors.
+     WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/'
+     NOTE: Resolving any missing task queue dependencies
+     Initialising tasks: 100% |######################################################################| Time: 0:00:06
+     Checking sstate mirror object availability: 100% |##############################################| Time: 0:00:00
+     NOTE: Executing SetScene Tasks
+     NOTE: Executing RunQueue Tasks
+     NOTE: Tasks Summary: Attempted 2393 tasks of which 2375 didn't need to be rerun and all succeeded.
+
+     Summary: There was 1 WARNING message shown.
+     NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
+                </literallayout>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Test the New Image:</emphasis>
+                For this example, you can run the new image using QEMU
+                to verify your changes:
                 <orderedlist>
-                    <listitem><para><emphasis>Boot the image</emphasis>:
+                    <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>
+                        </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>
+                        You should see the results of your
+                        <filename>printk</filename> statements
+                        as part of the output when you scroll down the
+                        console window.
+                        </para></listitem>
                 </orderedlist>
-            </para>
-        </section>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Stage and commit your changes</emphasis>:
+                Within your eSDK terminal, change your working directory to
+                where you modified the <filename>calibrate.c</filename>
+                file and use these Git commands to stage and commit your
+                changes:
+                <literallayout class='monospaced'>
+     $ cd ~/poky_sdk/workspace/sources/linux-yocto
+     $ git status
+     $ git add init/calibrate.c
+     $ git commit -m "calibrate: Add printk example"
+                </literallayout>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Export the Patches and Create a <filename>.bbappend</filename>:</emphasis>
+                To export your commits as patches and create a
+                <filename>.bbappend</filename> file, use the following
+                command in the terminal used to work with the extensible
+                SDK.
+                This example uses the previously established layer named
+                <filename>meta-my-kernel</filename>.
+                <note>
+                    See Step 3 of the
+                    "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop using devtool</link>"
+                    section for information on setting up this layer.
+                </note>
+                <literallayout class='monospaced'>
+     $ devtool finish linux-yocto /path/to/meta-my-kernel
+                </literallayout>
+                Once the command finishes, the patches and the
+                <filename>.bbappend</filename> file are located in the
+                <filename>~/meta-my-kernel/recipes-kernel/linux</filename>
+                directory.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Build the Image With Your Modified Kernel:</emphasis>
+                You can now build an image that includes your kernel
+                patches.
+                Execute the following command from your
+                <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+                in the terminal set up to run BitBake:
+                <literallayout class='monospaced'>
+     $ cd ~/poky/build
+     $ bitbake core-image-minimal
+                </literallayout>
+                </para></listitem>
+        </orderedlist>
     </section>
 
     <section id='using-an-iterative-development-process'>
@@ -1174,7 +1192,7 @@
                 are very time consuming.
             </para>
 
-            <para>
+            <para role='writernotes'>
                 Once you are satisfied with your source code modifications,
                 you can make them permanent by generating patches and
                 applying them to the
@@ -1183,7 +1201,7 @@
                 "<link linkend='applying-patches'>Applying Patches</link>"
                 section.
                 If you are not familiar with generating patches, refer to the
-                "<link linkend='creating-the-patch'>Creating the Patch</link>"
+                "I need a linked section here for the patch stuff"
                 section.
             </para>
         </section>
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index a2644aaa13..ce8e0fcb6d 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -108,6 +108,16 @@
         "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
         section in the Yocto Project Development Manual to set up your
         Source Directory.
+        <note>
+            Be sure you check out the appropriate development branch or
+            by tag to get the version of Yocto Project you want.
+            See the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
+            and
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
+            sections in the Yocto Project Development Manual for more
+            information.
+        </note>
     </para>
 
     <para>
@@ -156,7 +166,7 @@
                     building for the QEMU emulator in 32-bit mode.
                     However, if you are not, you need to set the
                     <filename>MACHINE</filename> variable appropriately in
-                    your <filename>local.conf</filename> file found in the
+                    your <filename>conf/local.conf</filename> file found in the
                     <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
                     (i.e. <filename>~/poky/build</filename> in this example).
                     </para>
@@ -208,6 +218,7 @@
                     Use BitBake to build the extensible SDK specifically for
                     the Minnowboard:
                     <literallayout class='monospaced'>
+     $ cd ~/poky/build
      $ bitbake core-image-minimal -c populate_sdk_ext
                     </literallayout>
                     Once the build finishes, you can find the SDK installer
@@ -290,12 +301,9 @@
                     If you were building for actual hardware and not for
                     emulation, you could flash the image to a USB stick
                     on <filename>/dev/sdd</filename> and boot your device.
-                    Use a command similar to the following command to flash
-                    the image:
-                    <literallayout class='monospaced'>
-     $ sudo dd if=tmp/deploy/images/<replaceable>architecture</replaceable>/core-image-minimal-<replaceable>architecture</replaceable>.wic of=/dev/sdd bs=1MB
-     $ sync
-                    </literallayout>
+                    For an example that uses a Minnowboard, see the
+                    <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
+                    Wiki page.
                     </para></listitem>
             </orderedlist>
         </para>