kernel-dev: Rough text in for new chapter. Makefile edited.

The raw text for the second chapter is in by section.  This has
no formatting whatsoever.  I also edited the Makefile so that
the new "Common Tasks" chapter would make as part of the manual.

(From yocto-docs rev: 68bcc1e977fbdd7b1a4b448171d1149edc72db51)

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

1 files changed, 345 insertions, 353 deletions

diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 1290994257..a94ad6fd85 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -2,388 +2,380 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
 
-<chapter id='kernel-concepts'>
-
-<title>Yocto Project Kernel Concepts</title>
-
-<section id='concepts-org'>
-    <title>Introduction</title>
-    <para>
-        This chapter provides conceptual information about the kernel:
-        <itemizedlist>
-            <listitem><para>Kernel Goals</para></listitem>
-            <listitem><para>Kernel Development and Maintenance Overview</para></listitem>
-            <listitem><para>Kernel Architecture</para></listitem>
-            <listitem><para>Kernel Tools</para></listitem>
-        </itemizedlist>
-    </para>
-</section>
-
-    <section id='kernel-goals'>
-        <title>Kernel Goals</title>
-        <para>
-            The complexity of embedded kernel design has increased dramatically.
-            Whether it is managing multiple implementations of a particular feature or tuning and
-            optimizing board specific features, both flexibility and maintainability are key concerns.
-            The Linux kernels available through the Yocto Project are presented with the embedded
-            developer's needs in mind and have evolved to assist in these key concerns.
-            For example, prior methods such as applying hundreds of patches to an extracted
-            tarball have been replaced with proven techniques that allow easy inspection,
-            bisection and analysis of changes.
-            Application of these techniques also creates a platform for performing integration and
-            collaboration with the thousands of upstream development projects.
-        </para>
-        <para>
-            With all these considerations in mind, the Yocto Project's kernel and development team
-            strives to attain these goals:
-        <itemizedlist>
-            <listitem><para>Allow the end user to leverage community best practices to seamlessly
-            manage the development, build and debug cycles.</para></listitem>
-            <listitem><para>Create a platform for performing integration and collaboration with the
-            thousands of upstream development projects that exist.</para></listitem>
-            <listitem><para>Provide mechanisms that support many different work flows, front-ends and
-            management techniques.</para></listitem>
-            <listitem><para>Deliver the most up-to-date kernel possible while still ensuring that
-            the baseline kernel is the most stable official release.</para></listitem>
-            <listitem><para>Include major technological features as part of the Yocto Project's
-            upward revision strategy.</para></listitem>
-            <listitem><para>Present a kernel Git repository that, similar to the upstream
-            <filename>kernel.org</filename> tree,
-            has a clear and continuous history.</para></listitem>
-            <listitem><para>Deliver a key set of supported kernel types, where each type is tailored
-            to meet a specific use (e.g. networking, consumer, devices, and so forth).</para></listitem>
-            <listitem><para>Employ a Git branching strategy that, from a developer's point of view,
-            results in a linear path from the baseline <filename>kernel.org</filename>,
-            through a select group of features and
-            ends with their BSP-specific commits.</para></listitem>
-        </itemizedlist>
-        </para>
-    </section>
+<chapter id='kernel-dev-common'>
+
+<title>Common Tasks</title>
+
+<para>
+    This chapter describes common tasks you need to do when working
+    on the Yocto Project Linux kernel.
+</para>
+
+    <section id='preparing-a-layer'>
+        <title>Preparing a Layer</title>
 
-    <section id='kernel-big-picture'>
-        <title>Yocto Project Kernel Development and Maintenance Overview</title>
-        <para>
-            Kernels available through the Yocto Project, like other kernels, are based off the Linux
-            kernel releases from <ulink url='http://www.kernel.org'></ulink>.
-            At the beginning of a major development cycle, the Yocto Project team
-            chooses its kernel based on factors such as release timing, the anticipated release
-            timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
-            feature requirements.
-            Typically, the kernel chosen is in the
-            final stages of development by the community.
-            In other words, the kernel is in the release
-            candidate or "rc" phase and not yet a final release.
-            But, by being in the final stages of external development, the team knows that the
-            <filename>kernel.org</filename> final release will clearly be within the early stages of
-            the Yocto Project development window.
-        </para>
-        <para>
-            This balance allows the team to deliver the most up-to-date kernel
-            possible, while still ensuring that the team has a stable official release for
-            the baseline Linux kernel version.
-        </para>
-        <para>
-            The ultimate source for kernels available through the Yocto Project are released kernels
-            from <filename>kernel.org</filename>.
-            In addition to a foundational kernel from <filename>kernel.org</filename>, the
-            kernels available contain a mix of important new mainline
-            developments, non-mainline developments (when there is no alternative),
-            Board Support Package (BSP) developments,
-            and custom features.
-            These additions result in a commercially released Yocto Project Linux kernel that caters
-            to specific embedded designer needs for targeted hardware.
-        </para>
-        <para>
-            Once a kernel is officially released, the Yocto Project team goes into
-            their next development cycle, or upward revision (uprev) cycle, while still
-            continuing maintenance on the released kernel.
-            It is important to note that the most sustainable and stable way
-            to include feature development upstream is through a kernel uprev process.
-            Back-porting hundreds of individual fixes and minor features from various
-            kernel versions is not sustainable and can easily compromise quality.
-        </para>
-        <para>
-            During the uprev cycle, the Yocto Project team uses an ongoing analysis of
-            kernel development, BSP support, and release timing to select the best
-            possible <filename>kernel.org</filename> version.
-            The team continually monitors community kernel
-            development to look for significant features of interest.
-            The team does consider back-porting large features if they have a significant advantage.
-            User or community demand can also trigger a back-port or creation of new
-            functionality in the Yocto Project baseline kernel during the uprev cycle.
-        </para>
-        <para>
-            Generally speaking, every new kernel both adds features and introduces new bugs.
-            These consequences are the basic properties of upstream kernel development and are
-            managed by the Yocto Project team's kernel strategy.
-            It is the Yocto Project team's policy to not back-port minor features to the released kernel.
-            They only consider back-porting significant technological jumps - and, that is done
-            after a complete gap analysis.
-            The reason for this policy is that back-porting any small to medium sized change
-            from an evolving kernel can easily create mismatches, incompatibilities and very
-            subtle errors.
-        </para>
         <para>
-            These policies result in both a stable and a cutting
-            edge kernel that mixes forward ports of existing features and significant and critical
-            new functionality.
-            Forward porting functionality in the kernels available through the Yocto Project kernel
-            can be thought of as a "micro uprev."
-            The many “micro uprevs” produce a kernel version with a mix of
-            important new mainline, non-mainline, BSP developments and feature integrations.
-            This kernel gives insight into new features and allows focused
-            amounts of testing to be done on the kernel, which prevents
-            surprises when selecting the next major uprev.
-            The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
-            feature and BSP development.
+        Customizing recipes is best done in a layer with bbappend files. Layers also
+provide a convenient mechanism to create your own recipes. This guide assumes
+you will be working from within a layer independent from those released with the
+Yocto Project. For details on how to create and work with layers, refer to
+section 5.1 Understanding and Creating Layers in the Yocto Project Development
+Manual. 
+
+(Kernel specific directions in 5.7.4)
         </para>
     </section>
 
-    <section id='kernel-architecture'>
-        <title>Kernel Architecture</title>
+    <section id='modifying-an-existing-recipe'>
+        <title>Modifying an Existing Recipe</title>
+
         <para>
-            This section describes the architecture of the kernels available through the
-            Yocto Project and provides information
-            on the mechanisms used to achieve that architecture.
+        In many cases, you can customize an existing linux-yocto recipe to meet the
+needs of your project. Each release of the Yocto Project provides a few Linux
+kernel recipes to choose from. To get started, prepare a layer and a bbappend
+file corresponding to the recipe you wish to modify.
+
+See [New example in Dev Manual] for instructions to create a minimal layer.
+
+The bbappend will typical be located at the following location relative to the
+layer (if modifying the linux-yocto_3.4.bb recipe):
+
+        recipes-kernel/linux/linux-yocto_3.4.bbappend
+
+And should contain the following text initially:
+
+        FILESEXTRAPATHS := "${THISDIR}/${PN}"
+
+The ${PN} will expand to "linux-yocto" in this example. Any new files added to
+modify the recipe should then be added to the following path within the layer:
+
+        recipes-kernel/linux/linux-yocto/
+
+NOTE: If you are working on a new machine BSP, be sure to refer to the Yocto
+Project Board Support Package Developer's Guide.
+
         </para>
 
-        <section id='architecture-overview'>
-            <title>Overview</title>
-            <para>
-                As mentioned earlier, a key goal of the Yocto Project is to present the
-                developer with
-                a kernel that has a clear and continuous history that is visible to the user.
-                The architecture and mechanisms used achieve that goal in a manner similar to the
-                upstream <filename>kernel.org</filename>.
-            </para>
-            <para>
-                You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
-                added features logically structured on top of the baseline.
-                The features are tagged and organized by way of a branching strategy implemented by the
-                source code manager (SCM) Git.
-                For information on Git as applied to the Yocto Project, see the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
-                Yocto Project Development Manual.
-            </para>
-            <para>
-                The result is that the user has the ability to see the added features and
-                the commits that make up those features.
-                In addition to being able to see added features, the user can also view the history of what
-                made up the baseline kernel.
-            </para>
-            <para>
-                The following illustration shows the conceptual Yocto Project kernel.
-            </para>
-            <para>
-                <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
-            </para>
-            <para>
-                In the illustration, the "Kernel.org Branch Point"
-                marks the specific spot (or release) from
-                which the Yocto Project kernel is created.
-                From this point "up" in the tree, features and differences are organized and tagged.
-            </para>
-            <para>
-                The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
-                type and BSP that is organized further up the tree.
-                Placing these common features in the
-                tree this way means features don't have to be duplicated along individual branches of the
-                structure.
-            </para>
-            <para>
-                From the Yocto Project Baseline Kernel, branch points represent specific functionality
-                for individual BSPs as well as real-time kernels.
-                The illustration represents this through three BSP-specific branches and a real-time
-                kernel branch.
-                Each branch represents some unique functionality for the BSP or a real-time kernel.
-            </para>
-            <para>
-                In this example structure, the real-time kernel branch has common features for all
-                real-time kernels and contains
-                more branches for individual BSP-specific real-time kernels.
-                The illustration shows three branches as an example.
-                Each branch points the way to specific, unique features for a respective real-time
-                kernel as they apply to a given BSP.
-            </para>
+        <section id='applying-patches'>
+            <title>Applying Patches</title>
+
             <para>
-                The resulting tree structure presents a clear path of markers (or branches) to the
-                developer that, for all practical purposes, is the kernel needed for any given set
-                of requirements.
+        If you have a patch, or a small series of patches, to apply to the Linux kernel
+source, you can do so just as you would with any other recipe. You first copy
+the patches to the path added to FILESEXTRAPATHS in the bbappend file as
+described in 2.2 and then reference them in the SRC_URI.
+
+For example, you can apply a three patch series by adding the following lines to
+your linux-yocto bbappend file in your layer:
+
+        SRC_URI += "file://0001-first-change.patch"
+        SRC_URI += "file://0002-first-change.patch"
+        SRC_URI += "file://0003-first-change.patch"
+
+At the next build, bitbake will detect the change in the recipe and fetch and
+apply the patches before rebuilding the Linux kernel.
             </para>
         </section>
 
-        <section id='branching-and-workflow'>
-            <title>Branching Strategy and Workflow</title>
-            <para>
-                The Yocto Project team creates kernel branches at points where functionality is
-                no longer shared and thus, needs to be isolated.
-                For example, board-specific incompatibilities would require different functionality
-                and would require a branch to separate the features.
-                Likewise, for specific kernel features, the same branching strategy is used.
-            </para>
-            <para>
-                This branching strategy results in a tree that has features organized to be specific
-                for particular functionality, single kernel types, or a subset of kernel types.
-                This strategy also results in not having to store the same feature twice
-                internally in the tree.
-                Rather, the kernel team stores the unique differences required to apply the
-                feature onto the kernel type in question.
-                <note>
-                    The Yocto Project team strives to place features in the tree such that they can be
-                    shared by all boards and kernel types where possible.
-                    However, during development cycles or when large features are merged,
-                    the team cannot always follow this practice.
-                    In those cases, the team uses isolated branches to merge features.
-                </note>
-            </para>
-            <para>
-                BSP-specific code additions are handled in a similar manner to kernel-specific additions.
-                Some BSPs only make sense given certain kernel types.
-                So, for these types, the team creates branches off the end of that kernel type for all
-                of the BSPs that are supported on that kernel type.
-                From the perspective of the tools that create the BSP branch, the BSP is really no
-                different than a feature.
-                Consequently, the same branching strategy applies to BSPs as it does to features.
-                So again, rather than store the BSP twice, the team only stores the unique
-                differences for the BSP across the supported multiple kernels.
-            </para>
-            <para>
-                While this strategy can result in a tree with a significant number of branches, it is
-                important to realize that from the developer's point of view, there is a linear
-                path that travels from the baseline <filename>kernel.org</filename>, through a select
-                group of features and ends with their BSP-specific commits.
-                In other words, the divisions of the kernel are transparent and are not relevant
-                to the developer on a day-to-day basis.
-                From the developer's perspective, this path is the "master" branch.
-                The developer does not need to be aware of the existence of any other branches at all.
-                Of course, there is value in the existence of these branches
-                in the tree, should a person decide to explore them.
-                For example, a comparison between two BSPs at either the commit level or at the line-by-line
-                code <filename>diff</filename> level is now a trivial operation.
-            </para>
-            <para>
-                Working with the kernel as a structured tree follows recognized community best practices.
-                In particular, the kernel as shipped with the product, should be
-                considered an "upstream source" and viewed as a series of
-                historical and documented modifications (commits).
-                These modifications represent the development and stabilization done
-                by the Yocto Project kernel development team.
-            </para>
+        <section id='changing-the-configuration'>
+            <title>Changing the Configuration</title>
+
             <para>
-                Because commits only change at significant release points in the product life cycle,
-                developers can work on a branch created
-                from the last relevant commit in the shipped Yocto Project kernel.
-                As mentioned previously, the structure is transparent to the developer
-                because the kernel tree is left in this state after cloning and building the kernel.
+            Making wholesale or incremental changes to the Linux kernel config can be made
+by including a defconfig or configuration fragments in the SRC_URI.
+
+If you have a complete Linux kernel .config file you want to use, copy it as
+"defconfig" to the ${FILES} directory and add the following line to your
+linux-yocto bbappend file in your layer:
+
+        SRC_URI += "file://defconfig"
+
+Generally speaking, the preferred approach is to determine the incremental
+change you want to make and add that as a fragment. For example, if you wanted
+to add support for a basic serial console, create a file named "8250.cfg" in the
+${FILES} directory with the following content (without indentation):
+
+        CONFIG_SERIAL_8250=y
+        CONFIG_SERIAL_8250_CONSOLE=y
+        CONFIG_SERIAL_8250_PCI=y
+        CONFIG_SERIAL_8250_NR_UARTS=4
+        CONFIG_SERIAL_8250_RUNTIME_UARTS=4
+        CONFIG_SERIAL_CORE=y
+        CONFIG_SERIAL_CORE_CONSOLE=y
+
+Then include this configuration fragment in the SRC_URI:
+
+        SRC_URI += "file://8250.cfg"
+
+At the next build, bitbake will detect the change in the recipe and fetch and
+apply the new configuration before rebuilding the Linux kernel.
             </para>
         </section>
+    </section>
+
+    <section id='iterative-development'>
+        <title>Iterative Development</title>
+
+        <para>
+        If you do not have existing patches or configuration files, you can easily
+generate them from within the bitbake build environment, as will be described
+below. As you do, running previously completed bitbake tasks will cause bitbake
+to invalidate the tasks that follow them in the build sequence, causing them to
+rebuild at the next invocation of the build. Throughout this section, be sure to
+substitute "linux-yocto" with the name of the Linux kernel recipe you are
+working with.
+        </para>
+
+        <section id='generating-configuration-files'>
+            <title>Generating Configuration Files</title>
 
-        <section id='source-code-manager-git'>
-            <title>Source Code Manager - Git</title>
             <para>
-                The Source Code Manager (SCM) is Git.
-                This SCM is the obvious mechanism for meeting the previously mentioned goals.
-                Not only is it the SCM for <filename>kernel.org</filename> but,
-                Git continues to grow in popularity and supports many different work flows,
-                front-ends and management techniques.
+            You can manipulate the config used to build a linux-yocto recipe with the
+"menuconfig" command.
+
+        $ bitbake linux-yocto -c menuconfig
+
+This will start the Linux kernel configuration tool, allowing you to prepare a
+new .config for the build. When you exit, be sure to save the changes when
+prompted. The resulting .config file will be located in the ${WORKDIR} under
+the linux-${MACHINE}-${KTYPE}-build directory. You can use this in its entirety
+as the defconfig file described in 2.2.2.
+
+Better still, would be to use the "menuconfig" command and take the difference
+of the new .config file with the previous one to generate a configuration
+fragment. To do this, be sure to complete a build at least through the kernel
+configuration task:
+
+        $ bitbake linux-yocto -c kernel_configme -f
+
+Then make a copy of the .config file, calling it "config.orig", for example. Run
+the "menuconfig" command as described above. Finally, prepare a configuration
+fragment from the difference between the files. Ultimately you want a list of
+Linux kernel CONFIG_ assignments, and not something in diff format. Something
+like the following will do that automatically (but plan on reviewing the output
+as you can usually remove some of the defaults):
+
+        $ diff -Nurp config.orig .config | sed -n "s/^\+//p" > frag.cfg
+
+You can use the output as a configuration fragment described in 2.2.2. This
+method can also be used to define a BSP configuration fragment (See 3.3.5).
+
+The Yocto Project kernel tools provide some configuration validation tools which
+will warn when a configuration you requested does not appear in the final
+config, or when you override a policy configuration in a hardware configuration
+fragment. You can run these tools with the following command:
+
+        $ bitbake linux-yocto -c kernel_configcheck -f
+
+        ...
+
+        NOTE: validating kernel configuration
+        This BSP sets 3 invalid/obsolete kernel options.
+        These config options are not offered anywhere within this kernel.
+        The full list can be found in your kernel src dir at:
+        meta/cfg/standard/mybsp/invalid.cfg
+
+        This BSP sets 21 kernel options that are possibly non-hardware related.
+        The full list can be found in your kernel src dir at:
+        meta/cfg/standard/mybsp/specified_non_hdw.cfg
+
+        WARNING: There were 2 hardware options requested that do not
+                 have a corresponding value present in the final ".config" file.
+                 This probably means you aren't getting the config you wanted.
+        The full list can be found in your kernel src dir at:
+        meta/cfg/standard/mybsp/mismatch.cfg
+
+The various problems that you can encounter are described in the output along
+with where to find the offending configuration items. You can use these logs to
+adjust your configuration files and repeat the "kernel_configme" and
+"kernel_configcheck" commands until no warnings are produced.
             </para>
+        </section>
+
+        <section id='modifying-source-code'>
+            <title>Modifying Source Code</title>
+
             <para>
-                You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
-                You can also get an introduction to Git as it applies to the Yocto Project in the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
-                section in the Yocto Project Development Manual.
-                These referenced sections overview Git and describe a minimal set of
-                commands that allows you to be functional using Git.
-                <note>
-                    You can use as much, or as little, of what Git has to offer to accomplish what
-                    you need for your project.
-                    You do not have to be a "Git Master" in order to use it with the Yocto Project.
-                </note>
+            You can experiment with source code changes and create a simple patch without
+leaving the bitbake environment. To get started, be sure to complete a build at
+least through the kernel configuration task:
+
+        $ bitbake linux-yocto -c kernel_configme -f
+
+This step will ensure you have the sources prepared and the configuration
+completed. You will find the sources in the ${WORKDIR}/linux directory.
+
+You can edit the sources as you would any other Linux source tree, but keep in
+mind that your changes will be lost if you trigger the fetch task for the
+recipe. Avoid this by not issuing the "cleanall" or "cleansstate", or forcing
+the "fetch" command. Also be sure not to modify the recipe itself while working
+with temporary changes or bitbake may run the fetch command (depending on the
+changes to the recipe).
+
+To test your temporary changes, instruct bitbake to run the compile again. The
+-f option forces the command to run again even though bitbake may think it has
+already done so:
+
+        $ bitbake linux-yocto -c compile -f
+
+If the compile fails, you can update the sources and repeat the compile
+command. Once it compiles successfully, you can inspect and test the resulting
+build (kernel, modules, etc.) from the build directory at
+${WORKDIR}/linux-${MACHINE}-${KTYPE}-build. Alternatively, you can run the
+deploy command to place the kernel image in the tmp/deploy/images directory:
+
+        $ bitbake linux-yocto -c deploy
+
+And of course, you can run through all the remaining installation and packaging
+steps by issuing:
+
+        $ bitbake linux-yocto
+
+For rapid iterative development, the edit-compile-repeat loop is preferable to
+rebuilding the entire recipe as the installation and packaging tasks are very
+time consuming.
+
+Once you are happy with your modifications, you can make these permanent by
+generating patches and applying them to the SRC_URI as described in section
+2.2.1 Applying Patches. If you are not familiar with generating patches, refer
+to the Yocto Project Development Manual, section 5.7.3 Creating the Patch.
             </para>
         </section>
     </section>
 
-    <section id='kernel-configuration'>
-        <title>Kernel Configuration</title>
-        <para>
-            Kernel configuration, along with kernel features, defines how a kernel
-            image is built for the Yocto Project.
-            Through configuration settings, you can customize a Yocto Project kernel to be
-            specific to particular hardware.
-            For example, you can specify sound support or networking support.
-            This section describes basic concepts behind Kernel configuration within the
-            Yocto Project and references you to other areas for specific configuration
-            applications.
-        </para>
+    <section id='working-with-your-own-sources'>
+        <title>Working With Your Own Sources</title>
 
         <para>
-            Conceptually, configuration of a Yocto Project kernel occurs similarly to that needed for any
-            Linux kernel.
-            The build process for a Yocto Project kernel uses a <filename>.config</filename> file, which
-            is created through the Linux Kernel Configuration (LKC) tool.
-            You can directly set various configurations in the
-            <filename>.config</filename> file by using the <filename>menuconfig</filename>
-            tool as built by BitBake.
-            You can also define configurations in the file by using configuration fragments.
-            <note>
-                It is not recommended that you edit the <filename>.config</filename> file directly.
-            </note>
-            Here are some brief descriptions of the ways you can affect the
-            <filename>.config</filename> file:
-            <itemizedlist>
-                <listitem><para><emphasis>The <filename>menuconfig</filename> Tool:</emphasis>
-                    One of many front-ends that allows you to define kernel configurations.
-                    Some others are <filename>make config</filename>,
-                    <filename>make nconfig</filename>, and <filename>make gconfig</filename>.
-                    In the Yocto Project environment, you must use BitBake to build the
-                    <filename>menuconfig</filename> tool before you can use it to define
-                    configurations:
-                    <literallayout class='monospaced'>
-     $ bitbake linux-yocto -c menuconfig
-                    </literallayout>
-                    After the tool is built, you can interact with it normally.
-                    You can see how <filename>menuconfig</filename> is used to change a simple
-                    kernel configuration in the
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
-                    section of the Yocto Project Development Manual.
-                    For general information on <filename>menuconfig</filename>, see
-                    <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
-                    </para></listitem>
-                <listitem><para><emphasis>Configuration Fragments:</emphasis> A file with a
-                    list of kernel options just as they would appear syntactically in the
-                    <filename>.config</filename> file.
-                    Configuration fragments are typically logical groupings and are assembled
-                    by the OpenEmbedded build system to produce input used by the LKC
-                    that ultimately generates the <filename>.config</filename> file.</para>
-                    <para>The
-                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink></filename>
-                    variable can be used to list configuration fragments.
-                    For further discussion on applying configuration fragments, see the
-                    "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-kernel'>Linux Kernel Configuration</ulink>"
-                    section in the Yocto Project Board Support Package (BSP) Guide.
-                    </para></listitem>
-            </itemizedlist>
+        If you find yourself unable to work with one of the Linux kernel versions
+supported by existing linux-yocto recipes, you can still make use of the Yocto
+Project Linux kernel tooling while working with your own sources. You will not
+be able to leverage the existing meta-data and stabilization work of the
+linux-yocto sources, but you will be able to manage your own meta-data in the
+same format as the linux-yocto sources which will facilitate converging with
+linux-yocto on a future mutually-supported kernel version.
+
+The linux-yocto-custom recipe, located in the poky repository at:
+
+        meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
+
+is provided as an example recipe which uses kernel.org sources and the Yocto
+Project Linux kernel tools for managing meta-data. To get started, copy this
+recipe to your layer and provide it with a meaningful name, such as
+linux-yocto-myproject_3.5.bb, where 3.5 is the base version of the Linux kernel
+you will be working with. In the same directory, create a matching directory,
+e.g. linux-yocto-myproject to store your patches and configuration files.
+
+Edit the following variables in the recipe as appropriate for your project:
+
+        o SRC_URI
+        o LINUX_VERSION
+        o LINUX_VERSION_EXTENSION
+        o SRCREV
+        o PR
+        o PV
+        o COMPATIBLE_MACHINE
+
+The SRC_URI should be a git repository, using one of the supported git fetcher
+protocols (file, git, http, etc.). The skeleton recipe provides an example
+SRC_URI as a syntax reference.
+
+Set LINUX_VERSION to the Linux kernel version you are using, such as "3.6.3".
+
+LINUX_VERSION_EXTENSION is used to define the Linux kernel CONFIG_LOCALVERSION
+which will be compiled in to the resulting kernel and visible via the uname
+command.
+
+Set SRCREV to the commit ID you wish to build from. 
+
+Treat the PR as you would the PR of any other recipe. Increment it to indicate
+to the build system that the recipe has changed.
+
+The default PV assignment is typically adequate. It combines the LINUX_VERSION
+with the SCM revision (from the SRCPV variable) and results in a string
+something like:
+
+"3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2"
+
+While lengthy, this extra verbosity helps ensure you are building from the exact
+sources you intend.
+
+Finally, the default COMPATIBLE_MACHINE assignment for linux-yocto-custom is set
+to a regular expression matching only the empty string, "(^$)". This will
+trigger an explicit build failure. You must change it to match a list of the
+machines supported by your new recipe, such as "(qemux86|qemux86-64)"
+
+With that in place, you can continue to customize this recipe as you would the
+existing linux-yocto recipes. See Section 2.2 Modifying an Existing Recipe for
+details.
         </para>
     </section>
 
-    <section id='kernel-tools'>
-        <title>Kernel Tools</title>
-        <para>
-            Since most standard workflows involve moving forward with an existing tree by
-            continuing to add and alter the underlying baseline, the tools that manage
-            the Yocto Project's kernel construction are largely hidden from the developer to
-            present a simplified view of the kernel for ease of use.
-        </para>
+    <section id='incorporating-out-of-tree-modules'>
+        <title>Incorporating Out-of-Tree Modules</title>
+
         <para>
-            Fundamentally, the kernel tools that manage and construct the
-            Yocto Project kernel accomplish the following:
-            <itemizedlist>
-                <listitem><para>Group patches into named, reusable features.</para></listitem>
-                <listitem><para>Allow top-down control of included features.</para></listitem>
-                <listitem><para>Bind kernel configurations to kernel patches and features.</para></listitem>
-                <listitem><para>Present a seamless Git repository that blends Yocto Project value
-                    with the <filename>kernel.org</filename> history and development.</para></listitem>
-            </itemizedlist>
+        While it is always preferable to work with sources integrated into the Linux
+kernel sources, if you have need of an external kernel module, the hello-mod
+recipe is available as a template to create your own out-of-tree Linux kernel
+module recipe. It is available in the poky repository at:
+
+        meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
+
+To get started, copy this recipe to your layer and provide it with a meaningful name, such as
+mymodule_1.0.bb. In the same directory, create a directory named "files" where
+you can store any source files, patches, or other files necessary for building
+the module which do not come with the sources. Finally, update the recipe as
+appropriate for the module. Typically you will need to set the following
+variables:
+
+        o DESCRIPTION
+        o LICENSE*
+        o SRC_URI
+        o PV
+
+Depending on the build system used by the module sources, you may need to make
+adjustments. For example, a typical module Makefile will look much like that
+provided with hello-mod:
+
+        obj-m := hello.o
+        
+        SRC := $(shell pwd)
+        
+        all:
+                $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
+        
+        modules_install:
+                $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
+        ...
+
+The important point to note here is the KERNEL_SRC variable. The module bbclass
+class sets this, as well as KERNEL_PATH, to ${STAGING_KERNEL_DIR} with the
+necessary Linux kernel build information to build modules. If your module
+Makefile uses a different variable, you may want to override the do_compile()
+step, or create a patch to the Makefile to work with the more typical KERNEL_SRC
+or KERNEL_PATH variables.
+
+After you have prepared the recipe, you will likely want to include the module
+in your images. To do this, see the documentation for the following variables in
+the Yocto Project Reference Manual and set one of them as appropriate in your
+machine config file:
+
+        MACHINE_ESSENTIAL_EXTRA_RDEPENDS
+        MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS
+        MACHINE_EXTRA_RDEPENDS
+        MACHINE_EXTRA_RRECOMMENDS
+
+As modules are often not required for boot and may be excluded from certain
+build configurations, the following allows for the most flexibility:
+
+        MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
+
+Where the value is derived by appending the module filename without the .ko
+extension to the string "kernel-module-".
+
+As it is an RRECOMMENDS (and not an RDEPENDS) variable, the build will not fail
+if this module is not available to include in the image.
         </para>
     </section>
 </chapter>