initial commit of Enea Linux 3.1HEADmaster

Migrated from the internal git server on the dora-enea branch

Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>

1 files changed, 863 insertions, 0 deletions

diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
new file mode 100644
index 0000000..a152f9f
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -0,0 +1,863 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-common'>
+
+<title>Common Tasks</title>
+
+<para>
+    This chapter presents several common tasks you perform when you
+    work with the Yocto Project Linux kernel.
+    These tasks include preparing a layer, modifying an existing recipe,
+    iterative development, working with your own sources, and incorporating
+    out-of-tree modules.
+    <note>
+        The examples presented in this chapter work with the Yocto Project
+        1.2.2 Release and forward.
+    </note>
+</para>
+
+    <section id='creating-and-preparing-a-layer'>
+        <title>Creating and Preparing a Layer</title>
+
+        <para>
+            If you are going to be modifying kernel recipes, it is recommended
+            that you create and prepare your own layer in which to do your
+            work.
+            Your layer contains its own BitBake append files
+            (<filename>.bbappend</filename>) and provides a convenient
+            mechanism to create your own recipe files
+            (<filename>.bb</filename>).
+            For details on how to create and work with layers, see the following
+            sections in the Yocto Project Development Manual:
+            <itemizedlist>
+                <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for
+                    general information on layers and how to create layers.</para></listitem>
+                <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for
+                    specific instructions on setting up a layer for kernel
+                    development.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='modifying-an-existing-recipe'>
+        <title>Modifying an Existing Recipe</title>
+
+        <para>
+            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 from which you can choose.
+            These are located in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+            in <filename>meta/recipes-kernel/linux</filename>.
+        </para>
+
+        <para>
+            Modifying an existing recipe can consist of the following:
+            <itemizedlist>
+                <listitem><para>Creating the append file</para></listitem>
+                <listitem><para>Applying patches</para></listitem>
+                <listitem><para>Changing the configuration</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <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
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section
+            of the Yocto Project Development Manual for a detailed
+            example.
+        </para>
+
+        <section id='creating-the-append-file'>
+            <title>Creating the Append File</title>
+
+            <para>
+                You create this file in your custom layer.
+                You also name it accordingly based on the linux-yocto recipe
+                you are using.
+                For example, if you are modifying the
+                <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>
+                recipe, the append file will typical be located as follows
+                within your custom layer:
+                <literallayout class='monospaced'>
+     &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto_3.4.bbappend
+                </literallayout>
+                The append file should initially extend the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+                search path by prepending the directory that contains your
+                files to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                variable as follows:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+                </literallayout>
+                The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
+                expands to "linux-yocto" in the current directory for this
+                example.
+                If you add any new files that modify the kernel recipe and you
+                have extended <filename>FILESPATH</filename> as
+                described above, you must place the files in your layer in the
+                following area:
+                <literallayout class='monospaced'>
+     &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto/
+                </literallayout>
+                <note>If you are working on a new machine Board Support Package
+                    (BSP), be sure to refer to the
+                    <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+                </note>
+            </para>
+        </section>
+
+        <section id='applying-patches'>
+            <title>Applying Patches</title>
+
+            <para>
+                If you have a single patch or a small series of patches
+                that you want 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
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                in your <filename>.bbappend</filename> file as described in
+                the previous section, and then reference them in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                statements.
+            </para>
+
+            <para>
+                For example, you can apply a three-patch series by adding the
+                following lines to your linux-yocto <filename>.bbappend</filename>
+                file in your layer:
+                <literallayout class='monospaced'>
+     SRC_URI += "file://0001-first-change.patch"
+     SRC_URI += "file://0002-first-change.patch"
+     SRC_URI += "file://0003-first-change.patch"
+                </literallayout>
+                The next time you run BitBake to build the Linux kernel, BitBake
+                detects the change in the recipe and fetches and applies the patches
+                before building the kernel.
+            </para>
+
+            <para>
+                For a detailed example showing how to patch the kernel, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+
+        <section id='changing-the-configuration'>
+            <title>Changing the Configuration</title>
+
+            <para>
+                You can make wholesale or incremental changes to the Linux
+                kernel <filename>.config</filename> file by including a
+                <filename>defconfig</filename> and by specifying
+                configuration fragments in the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
+            </para>
+
+            <para>
+                If you have a final Linux kernel <filename>.config</filename>
+                file you want to use, copy it to a directory named
+                <filename>files</filename>, which must be in
+                your layer's <filename>recipes-kernel/linux</filename>
+                directory, and name the file "defconfig".
+                Then, add the following lines to your linux-yocto
+                <filename>.bbappend</filename> file in your layer:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
+     SRC_URI += "file://defconfig"
+                </literallayout>
+                The <filename>SRC_URI</filename> tells the build system how to
+                search for the file, while the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                extends the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+                variable (search directories) to include the
+                <filename>files</filename> directory you created for the
+                configuration changes.
+            </para>
+
+            <note>
+                The build system applies the configurations from the
+                <filename>.config</filename> file before applying any
+                subsequent configuration fragments.
+                The final kernel configuration is a combination of the
+                configurations in the <filename>.config</filename> file and
+                any configuration fragments you provide.
+                You need to realize that if you have any configuration
+                fragments, the build system applies these on top of and
+                after applying the existing <filename>.config</filename>
+                file configurations.
+            </note>
+
+            <para>
+                Generally speaking, the preferred approach is to determine the
+                incremental change you want to make and add that as a
+                configuration fragment.
+                For example, if you want to add support for a basic serial
+                console, create a file named <filename>8250.cfg</filename> in
+                the <filename>files</filename> directory with the following
+                content (without indentation):
+                <literallayout class='monospaced'>
+     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
+                </literallayout>
+                Next, include this configuration fragment and extend the
+                <filename>FILESPATH</filename> variable in your
+                <filename>.bbappend</filename> file:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
+     SRC_URI += "file://8250.cfg"
+                </literallayout>
+                The next time you run BitBake to build the Linux kernel, BitBake
+                detects the change in the recipe and fetches and applies the
+                new configuration before building the kernel.
+            </para>
+
+            <para>
+                For a detailed example showing how to configure the kernel,
+                see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+    </section>
+
+    <section id='using-an-iterative-development-process'>
+        <title>Using an Iterative Development Process</title>
+
+        <para>
+            If you do not have existing patches or configuration files,
+            you can iteratively generate them from within the BitBake build
+            environment as described within this section.
+            During an iterative workflow, running a previously completed BitBake
+            task causes BitBake to invalidate the tasks that follow the
+            completed task in the build sequence.
+            Invalidated tasks rebuild the next time you run the build using
+            BitBake.
+        </para>
+
+        <para>
+            As you read this section, be sure to substitute the name
+            of your Linux kernel recipe for the term
+            "linux-yocto".
+        </para>
+
+        <section id='tip-dirty-string'>
+            <title>"-dirty" String</title>
+
+<!--
+            <para>
+                <emphasis>AR - Darrren Hart:</emphasis>  This section
+                originated from the old Yocto Project Kernel Architecture
+                and Use Manual.
+                It was decided we need to put it in this section here.
+                Darren needs to figure out where we want it and what part
+                of it we want (all, revision???)
+            </para>
+-->
+
+            <para>
+                If kernel images are being built with "-dirty" on the
+                end of the version string, this simply means that
+                modifications in the source directory have not been committed.
+                <literallayout class='monospaced'>
+     $ git status
+                </literallayout>
+            </para>
+
+            <para>
+                You can use the above Git command to report modified,
+                removed, or added files.
+                You should commit those changes to the tree regardless of
+                whether they will be saved, exported, or used.
+                Once you commit the changes, you need to rebuild the kernel.
+            </para>
+
+            <para>
+                To force a pickup and commit of all such pending changes,
+                enter the following:
+                <literallayout class='monospaced'>
+     $ git add .
+     $ git commit -s -a -m "getting rid of -dirty"
+                </literallayout>
+            </para>
+
+            <para>
+                Next, rebuild the kernel.
+            </para>
+        </section>
+
+        <section id='generating-configuration-files'>
+            <title>Generating Configuration Files</title>
+
+            <para>
+                You can manipulate the <filename>.config</filename> file
+                used to build a linux-yocto recipe with the
+                <filename>menuconfig</filename> command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c menuconfig
+                </literallayout>
+                This command starts the Linux kernel configuration tool,
+                which allows you to prepare a new
+                <filename>.config</filename> file for the build.
+                When you exit the tool, be sure to save your changes
+                at the prompt.
+            </para>
+
+            <para>
+                The resulting <filename>.config</filename> file is
+                located in
+                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the
+                <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>}-build</filename> directory.
+                You can use the entire <filename>.config</filename> file as the
+                <filename>defconfig</filename> file as described in the
+                "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
+            </para>
+
+            <para>
+                A better method is to create a configuration fragment using the
+                differences between two configuration files: one previously
+                created and saved, and one freshly created using the
+                <filename>menuconfig</filename> tool.
+            </para>
+
+            <para>
+                To create a configuration fragment using this method, follow
+                these steps:
+                <orderedlist>
+                    <listitem><para>Complete a build at least through the kernel
+                        configuration task as follows:
+                        <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configme -f
+                        </literallayout></para></listitem>
+                    <listitem><para>Copy and rename the resulting
+                        <filename>.config</filename> file (e.g.
+                        <filename>config.orig</filename>).
+                        </para></listitem>
+                    <listitem><para>Run the <filename>menuconfig</filename>
+                        command:
+                        <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c menuconfig
+                        </literallayout></para></listitem>
+                    <listitem><para>Prepare a configuration fragment based on
+                        the differences between the two files.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+
+            <para>
+                Ultimately, the configuration fragment file needs to be a
+                list of Linux kernel <filename>CONFIG_</filename> assignments.
+                It cannot be in <filename>diff</filename> format.
+                Here is an example of a command that creates your
+                configuration fragment file.
+                Regardless of the exact command you use, plan on reviewing
+                the output as you can usually remove some of the defaults:
+                <literallayout class='monospaced'>
+     $ diff -Nurp config.orig .config | sed -n "s/^\+//p" > frag.cfg
+                </literallayout>
+                See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
+                section for information on how to use the output as a
+                configuration fragment.
+                <note>
+                    You can also use this method to create configuration
+                    fragments for a BSP.
+                    See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
+                    section for more information.
+                </note>
+            </para>
+
+            <para>
+                The kernel tools also provide configuration validation.
+                You can use these tools to produce warnings for when a
+                requested configuration does not appear in the final
+                <filename>.config</filename> file or when you override a
+                policy configuration in a hardware configuration fragment.
+                Here is an example with some sample output of the command
+                that runs these tools:
+                <literallayout class='monospaced'>
+     $ 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 are not't getting the config you wanted.
+              The full list can be found in your kernel src dir at:
+              meta/cfg/standard/mybsp/mismatch.cfg
+                </literallayout>
+            </para>
+
+            <para>
+                The output describes the various problems that you can
+                encounter along with where to find the offending configuration
+                items.
+                You can use the information in the logs to adjust your
+                configuration files and then repeat the
+                <filename>kernel_configme</filename> and
+                <filename>kernel_configcheck</filename> commands until
+                they produce no warnings.
+            </para>
+
+            <para>
+                For more information on how to use the
+                <filename>menuconfig</filename> tool, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+
+        <section id='modifying-source-code'>
+            <title>Modifying Source Code</title>
+
+            <para>
+                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:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configme -f
+                </literallayout>
+                Taking this step ensures you have the sources prepared
+                and the configuration completed.
+                You can find the sources in the
+                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.
+            </para>
+
+            <para>
+                You can edit the sources as you would any other Linux source
+                tree.
+                However, keep in mind that you will lose changes if you
+                trigger the <filename>fetch</filename> task for the recipe.
+                You can avoid triggering this task by not issuing BitBake's
+                <filename>cleanall</filename>, <filename>cleansstate</filename>,
+                or forced <filename>fetch</filename> commands.
+                Also, do not modify the recipe itself while working
+                with temporary changes or BitBake might run the
+                <filename>fetch</filename> command depending on the
+                changes to the recipe.
+            </para>
+
+            <para>
+                To test your temporary changes, instruct BitBake to run the
+                <filename>compile</filename> again.
+                The <filename>-f</filename> option forces the command to run
+                even though BitBake might think it has already done so:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c compile -f
+                </literallayout>
+                If the compile fails, you can update the sources and repeat
+                the <filename>compile</filename>.
+                Once compilation is successful, you can inspect and test
+                the resulting build (i.e. kernel, modules, and so forth) from
+                the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                <literallayout class='monospaced'>
+     ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build
+                </literallayout>
+                Alternatively, you can run the <filename>deploy</filename>
+                command to place the kernel image in the
+                <filename>tmp/deploy/images</filename> directory:
+                <literallayout class='monospaced'>
+        $ bitbake linux-yocto -c deploy
+                </literallayout>
+                And, of course, you can perform the remaining installation and
+                packaging steps by issuing:
+                <literallayout class='monospaced'>
+        $ bitbake linux-yocto
+                </literallayout>
+            </para>
+
+            <para>
+                For rapid iterative development, the edit-compile-repeat loop
+                described in this section is preferable to rebuilding the
+                entire recipe because the installation and packaging tasks
+                are very time consuming.
+            </para>
+
+            <para>
+                Once you are satisfied with your source code modifications,
+                you can make them permanent by generating patches and
+                applying them to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                statement as described in section
+                "<link linkend='applying-patches'>Applying Patches</link>" section.
+                If you are not familiar with generating patches, refer to the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+    </section>
+
+    <section id='working-with-your-own-sources'>
+        <title>Working With Your Own Sources</title>
+
+        <para>
+            If you cannot 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 by
+            working with your own sources.
+            When you use your own sources, you will not be able to
+            leverage the existing kernel
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and
+            stabilization work of the linux-yocto sources.
+            However, you will be able to manage your own Metadata in the same
+            format as the linux-yocto sources.
+            Maintaining format compatibility facilitates converging with
+            linux-yocto on a future, mutually-supported kernel version.
+        </para>
+
+        <para>
+            To help you use your own sources, the Yocto Project provides a
+            linux-yocto custom recipe
+            (<filename>linux-yocto-custom.bb</filename>) that uses
+            <filename>kernel.org</filename> sources
+            and the Yocto Project Linux kernel tools for managing
+            kernel Metadata.
+            You can find this recipe in the
+            <filename>poky</filename> Git repository of the
+            Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
+            at:
+            <literallayout class="monospaced">
+     poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
+            </literallayout>
+        </para>
+
+        <para>
+            Here are some basic steps you can use to work with your own sources:
+            <orderedlist>
+                <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename>
+                    recipe to your layer and give it a meaningful name.
+                    The name should include the version of the Linux kernel you
+                    are using (e.g. <filename>linux-yocto-myproject_3.5.bb</filename>,
+                    where "3.5" is the base version of the Linux kernel
+                    with which you would be working).</para></listitem>
+                <listitem><para>In the same directory inside your layer,
+                    create a matching directory
+                    to store your patches and configuration files (e.g.
+                    <filename>linux-yocto-myproject</filename>).
+                    </para></listitem>
+                <listitem><para>Edit the following variables in your recipe
+                    as appropriate for your project:
+                    <itemizedlist>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
+                            The <filename>SRC_URI</filename> should be a Git
+                            repository that uses one of the supported Git fetcher
+                            protocols (i.e. <filename>file</filename>,
+                            <filename>git</filename>, <filename>http</filename>,
+                            and so forth).
+                            The skeleton recipe provides an example
+                            <filename>SRC_URI</filename> as a syntax reference.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
+                            The Linux kernel version you are using (e.g.
+                            "3.4").</para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
+                            The Linux kernel <filename>CONFIG_LOCALVERSION</filename>
+                            that is compiled into the resulting kernel and visible
+                            through the <filename>uname</filename> command.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
+                            The commit ID from which you want to build.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
+                            Treat this variable the same as you would in any other
+                            recipe.
+                            Increment the variable to indicate to the OpenEmbedded
+                            build system that the recipe has changed.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
+                            The default <filename>PV</filename> assignment is
+                            typically adequate.
+                            It combines the <filename>LINUX_VERSION</filename>
+                            with the Source Control Manager (SCM) revision
+                            as derived from the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
+                            variable.
+                            The combined results are a string with
+                            the following form:
+                            <literallayout class='monospaced'>
+     3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
+                            </literallayout>
+                            While lengthy, the extra verbosity in <filename>PV</filename>
+                            helps ensure you are using the exact
+                            sources from which you intend to build.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
+                            A list of the machines supported by your new recipe.
+                            This variable in the example recipe is set
+                            by default to a regular expression that matches
+                            only the empty string, "(^$)".
+                            This default setting triggers an explicit build
+                            failure.
+                            You must change it to match a list of the machines
+                            that your new recipe supports.
+                            For example, to support the <filename>qemux86</filename>
+                            and <filename>qemux86-64</filename> machines, use
+                            the following form:
+                            <literallayout class='monospaced'>
+     COMPATIBLE_MACHINE = "qemux86|qemux86-64"
+                            </literallayout></para></listitem>
+                    </itemizedlist></para></listitem>
+                <listitem><para>Provide further customizations to your recipe
+                    as needed just as you would customize an existing
+                    linux-yocto recipe.
+                    See the "<link linkend='modifying-an-existing-recipe'>Modifying
+                    an Existing Recipe</link>" section for information.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='incorporating-out-of-tree-modules'>
+        <title>Incorporating Out-of-Tree Modules</title>
+
+        <para>
+            While it is always preferable to work with sources integrated
+            into the Linux kernel sources, if you need an external kernel
+            module, the <filename>hello-mod.bb</filename> recipe is available
+            as a template from which you can create your own out-of-tree
+            Linux kernel module recipe.
+        </para>
+
+        <para>
+            This template recipe is located in the
+            <filename>poky</filename> Git repository of the
+            Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
+            at:
+            <literallayout class="monospaced">
+     poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
+            </literallayout>
+        </para>
+
+        <para>
+            To get started, copy this recipe to your layer and give it a
+            meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
+            In the same directory, create a directory named
+            <filename>files</filename> where you can store any source files,
+            patches, or other files necessary for building
+            the module that do not come with the sources.
+            Finally, update the recipe as appropriate for the module.
+            Typically you will need to set the following variables:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Depending on the build system used by the module sources, you might
+            need to make some adjustments.
+            For example, a typical module <filename>Makefile</filename> looks
+            much like the one provided with the <filename>hello-mod</filename>
+            template:
+            <literallayout class='monospaced'>
+     obj-m := hello.o
+
+     SRC := $(shell pwd)
+
+     all:
+         $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
+
+     modules_install:
+         $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
+     ...
+            </literallayout>
+        </para>
+
+        <para>
+            The important point to note here is the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
+            variable.
+            The class <filename>module.bbclass</filename> sets this variable,
+            as well as the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
+            variable to
+            <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
+            with the necessary Linux kernel build information to build modules.
+            If your module <filename>Makefile</filename> uses a different
+            variable, you might want to override the
+            <filename>do_compile()</filename> step, or create a patch to
+            the <filename>Makefile</filename> to work with the more typical
+            <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
+            variables.
+        </para>
+
+        <para>
+            After you have prepared your 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 configuration file:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            modules are often not required for boot and can be excluded from
+            certain build configurations.
+            The following allows for the most flexibility:
+            <literallayout class='monospaced'>
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
+            </literallayout>
+            Where the value is derived by appending the module filename without
+            the <filename>.ko</filename> extension to the string
+            "kernel-module-".
+        </para>
+
+        <para>
+            Because the variable is
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
+            and not a
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
+            variable, the build will not fail if this module is not available
+            to include in the image.
+        </para>
+    </section>
+
+    <section id='inspecting-changes-and-commits'>
+        <title>Inspecting Changes and Commits</title>
+
+        <para>
+            A common question when working with a kernel is:
+            "What changes have been applied to this tree?"
+            Rather than using "grep" across directories to see what has
+            changed, you can use Git to inspect or search the kernel tree.
+            Using Git is an efficient way to see what has changed in the tree.
+        </para>
+
+        <section id='what-changed-in-a-kernel'>
+            <title>What Changed in a Kernel?</title>
+
+            <para>
+                Following are a few examples that show how to use Git
+                commands to examine changes.
+                These examples are by no means the only way to see changes.
+                <note>
+                    In the following examples, unless you provide a commit
+                    range, <filename>kernel.org</filename> history is blended
+                    with Yocto Project kernel changes.
+                    You can form ranges by using branch names from the
+                    kernel tree as the upper and lower commit markers with
+                    the Git commands.
+                    You can see the branch names through the web interface
+                    to the Yocto Project source repositories at
+                    <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
+                </note>
+                To see a full range of the changes, use the
+                <filename>git whatchanged</filename> command and specify a
+                commit range for the branch
+                (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
+            </para>
+
+            <para>
+                Here is an example that looks at what has changed in the
+                <filename>emenlow</filename> branch of the
+                <filename>linux-yocto-3.4</filename> kernel.
+                The lower commit range is the commit associated with the
+                <filename>standard/base</filename> branch, while
+                the upper commit range is the commit associated with the
+                <filename>standard/emenlow</filename> branch.
+                <literallayout class='monospaced'>
+     $ git whatchanged origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+
+            <para>
+                To see short, one line summaries of changes use the
+                <filename>git log</filename> command:
+                <literallayout class='monospaced'>
+     $ git log --oneline origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+
+            <para>
+                Use this command to see code differences for the changes:
+                <literallayout class='monospaced'>
+     $ git diff origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+
+            <para>
+                Use this command to see the commit log messages and the
+                text differences:
+                <literallayout class='monospaced'>
+     $ git show origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+
+            <para>
+                Use this command to create individual patches for
+                each change.
+                Here is an example that that creates patch files for each
+                commit and places them in your <filename>Documents</filename>
+                directory:
+                <literallayout class='monospaced'>
+     $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='showing-a-particular-feature-or-branch-change'>
+            <title>Showing a Particular Feature or Branch Change</title>
+
+            <para>
+                Tags in the Yocto Project kernel tree divide changes for
+                significant features or branches.
+                The <filename>git show &lt;tag&gt;</filename> command shows
+                changes based on a tag.
+                Here is an example that shows <filename>systemtap</filename>
+                changes:
+                <literallayout class='monospaced'>
+     $ git show systemtap
+                </literallayout>
+                You can use the
+                <filename>git branch --contains &lt;tag&gt;</filename> command
+                to show the branches that contain a particular feature.
+                This command shows the branches that contain the
+                <filename>systemtap</filename> feature:
+                <literallayout class='monospaced'>
+     $ git branch --contains systemtap
+                </literallayout>
+            </para>
+        </section>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->