dev-manual, kernel-dev, sdk-manual: Moved patching kernel section

Moved the "Patching the Kernel" section, which was in the dev-manual to the kernel-dev manual. During the move, renamed the section to "Using devtool to Patch the Kernel". This move bothered a lot of links so I had to fix them in various manuals. (From yocto-docs rev: a000be1eddf33e4d7de8f350e076d48e27ca4b98) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
author: Scott Rifenbark <srifenbark@gmail.com> 2017-08-15 15:52:21 -0700
committer: Richard Purdie <richard.purdie@linuxfoundation.org> 2017-09-02 00:52:48 +0100
commit: a99c2c5581f8847fa3d95696f0f985ea87f9da9d (patch)
tree: 85f1555032abc37a0f016970f13063f0f6ec05f8 /documentation/kernel-dev
parent: 2c0c962dd94513d7bbdf93439613ae926aca1d23 (diff)
download: poky-a99c2c5581f8847fa3d95696f0f985ea87f9da9d.tar.gz
3 files changed, 363 insertions, 14 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index bb50a7def6..c55f68bc24 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -75,9 +75,8 @@
            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
+            "<link linkend='set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</link>"
-            of the Yocto Project Development Manual for a detailed
+            section for a detailed example.
-            example.
        </para>
        <section id='creating-the-append-file'>
@@ -295,9 +294,10 @@
            </para>
            <para>
-                For a detailed example showing how to patch the kernel, see the
+                For a detailed example showing how to patch the kernel using
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
+                <filename>devtool</filename>, see the
-                section in the Yocto Project Development Manual.
+                "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
+                section.
            </para>
        </section>
@@ -449,6 +449,354 @@
        </section>
    </section>
+    <section id="using-devtool-to-patch-the-kernel">
+        <title>Using <filename>devtool</filename> to Patch the Kernel</title>
+        <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.
+            <note>
+                You can 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>
+        </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.
+            Applying the patch and booting the modified image causes the added
+            messages to appear on the emulator's console.
+        </para>
+        <para>
+            The example assumes a clean build exists for the <filename>qemux86</filename>
+            machine in a
+            <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+            named <filename>poky</filename>.
+            Furthermore, the
+            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+            is <filename>build</filename> and is located in
+            <filename>poky</filename> and the kernel is based on the
+            Linux 3.4 kernel.
+        </para>
+        <para>
+            Also, for more information on patching the kernel, see the
+            "<link linkend='applying-patches'>Applying Patches</link>"
+            section.
+        </para>
+        <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.
+                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:
+                <literallayout class='monospaced'>
+     ${S}/linux
+                </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.
+                <orderedlist>
+                    <listitem><para>
+                        <emphasis>Change the working directory</emphasis>:
+                        Change to where the kernel source code is before making
+                        your edits to the <filename>calibrate.c</filename> file:
+                        <literallayout class='monospaced'>
+     $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
+                        </literallayout>
+                        Because you are working in an established Git repository,
+                        you must be in this directory in order to commit your changes
+                        and create the patch file.
+                        <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
+                            represent the version and revision for the
+                            <filename>linux-yocto</filename> recipe.
+                            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>
+                    <listitem><para>
+                        <emphasis>Edit the source file</emphasis>:
+                        Edit the <filename>init/calibrate.c</filename> file to have the
+                        following changes:
+                        <literallayout class='monospaced'>
+     void calibrate_delay(void)
+     {
+         unsigned long lpj;
+         static bool printed;
+         int this_cpu = smp_processor_id();
+         printk("*************************************\n");
+         printk("*                                   *\n");
+         printk("*        HELLO YOCTO KERNEL         *\n");
+         printk("*                                   *\n");
+         printk("*************************************\n");
+        if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
+               .
+               .
+               .
+                        </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:
+                <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='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:
+                        <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>.
+                        <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ source &OE_INIT_FILE;
+                        </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:
+                        <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>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Build the image</emphasis>:
+                        Next, build the kernel image using this command:
+                        <literallayout class='monospaced'>
+     $ bitbake -k linux-yocto
+                        </literallayout></para></listitem>
+                </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
+                <orderedlist>
+                    <listitem><para><emphasis>Boot the image</emphasis>:
+                        Boot the modified image in the QEMU emulator
+                        using this command:
+                        <literallayout class='monospaced'>
+     $ runqemu qemux86
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Verify the changes</emphasis>:
+                        Log into the machine using <filename>root</filename> with no password and then
+                        use the following shell command to scroll through the console's boot output.
+                        <literallayout class='monospaced'>
+     # dmesg | less
+                        </literallayout>
+                        You should see the results of your <filename>printk</filename> statements
+                        as part of the output.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+    </section>
    <section id='using-an-iterative-development-process'>
        <title>Using an Iterative Development Process</title>
@@ -747,8 +1095,8 @@
                "<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>"
+                "<link linkend='creating-the-patch'>Creating the Patch</link>"
-                section in the Yocto Project Development Manual.
+                section.
            </para>
        </section>
    </section>
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 7f6b82fee5..60d67d64fe 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -461,9 +461,8 @@
            "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>"
            section.
            You can also reference the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
+            "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
-            section in the Yocto Project Development Manual for a detailed
+            section for a detailed example that modifies the kernel.
-            example that modifies the kernel.
        </para>
    </section>
 </appendix>
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index 95c50e4691..899ed65db2 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -108,12 +108,14 @@
        You can find additional information here:
        <itemizedlist>
            <listitem><para>
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
+                The
-                in the Yocto Project Development Manual.
+                "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
+                section.
                </para></listitem>
            <listitem><para>
+                The
                "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
-                in the Yocto Project Development Manual.
+                section in the Yocto Project Development Manual.
                </para></listitem>
        </itemizedlist>
        This illustration and the following list summarizes the kernel
author	Scott Rifenbark <srifenbark@gmail.com>	2017-08-15 15:52:21 -0700
committer	Richard Purdie <richard.purdie@linuxfoundation.org>	2017-09-02 00:52:48 +0100
commit	a99c2c5581f8847fa3d95696f0f985ea87f9da9d (patch)
tree	85f1555032abc37a0f016970f13063f0f6ec05f8 /documentation/kernel-dev
parent	2c0c962dd94513d7bbdf93439613ae926aca1d23 (diff)
download	poky-a99c2c5581f8847fa3d95696f0f985ea87f9da9d.tar.gz

diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index bb50a7def6..c55f68bc24 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -75,9 +75,8 @@
75	See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"	75	See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
76	section for some general resources.	76	section for some general resources.
77	You can also see the	77	You can also see the
78	"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section	78	"<link linkend='set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</link>"
79	of the Yocto Project Development Manual for a detailed	79	section for a detailed example.
80	example.
81	</para>	80	</para>
82		81
83	<section id='creating-the-append-file'>	82	<section id='creating-the-append-file'>
@@ -295,9 +294,10 @@
295	</para>	294	</para>
296		295
297	<para>	296	<para>
298	For a detailed example showing how to patch the kernel, see the	297	For a detailed example showing how to patch the kernel using
299	"<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"	298	<filename>devtool</filename>, see the
300	section in the Yocto Project Development Manual.	299	"<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
		300	section.
301	</para>	301	</para>
302	</section>	302	</section>
303		303
@@ -449,6 +449,354 @@
449	</section>	449	</section>
450	</section>	450	</section>
451		451
		452	<section id="using-devtool-to-patch-the-kernel">
		453	<title>Using <filename>devtool</filename> to Patch the Kernel</title>
		454
		455	<para>
		456	Patching the kernel involves changing or adding configurations to an existing kernel,
		457	changing or adding recipes to the kernel that are needed to support specific hardware features,
		458	or even altering the source code itself.
		459	<note>
		460	You can use the <filename>yocto-kernel</filename> script
		461	found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
		462	under <filename>scripts</filename> to manage kernel patches and configuration.
		463	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>"
		464	section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
		465	more information.</note>
		466	</para>
		467
		468	<para>
		469	This example creates a simple patch by adding some QEMU emulator console
		470	output at boot time through <filename>printk</filename> statements in the kernel's
		471	<filename>calibrate.c</filename> source code file.
		472	Applying the patch and booting the modified image causes the added
		473	messages to appear on the emulator's console.
		474	</para>
		475
		476	<para>
		477	The example assumes a clean build exists for the <filename>qemux86</filename>
		478	machine in a
		479	<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
		480	named <filename>poky</filename>.
		481	Furthermore, the
		482	<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
		483	is <filename>build</filename> and is located in
		484	<filename>poky</filename> and the kernel is based on the
		485	Linux 3.4 kernel.
		486	</para>
		487
		488	<para>
		489	Also, for more information on patching the kernel, see the
		490	"<link linkend='applying-patches'>Applying Patches</link>"
		491	section.
		492	</para>
		493
		494	<section id='create-a-layer-for-your-changes'>
		495	<title>Create a Layer for your Changes</title>
		496
		497	<para>
		498	The first step is to create a layer so you can isolate your
		499	changes.
		500	Rather than use the <filename>yocto-layer</filename> script
		501	to create the layer, this example steps through the process
		502	by hand.
		503	If you want information on the script that creates a general
		504	layer, see the
		505	"<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>"
		506	section in the Yocto Project Development Manual.
		507	</para>
		508
		509	<para>
		510	These two commands create a directory you can use for your
		511	layer:
		512	<literallayout class='monospaced'>
		513	$ cd ~/poky
		514	$ mkdir meta-mylayer
		515	</literallayout>
		516	Creating a directory that follows the Yocto Project layer naming
		517	conventions sets up the layer for your changes.
		518	The layer is where you place your configuration files, append
		519	files, and patch files.
		520	To learn more about creating a layer and filling it with the
		521	files you need, see the
		522	"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
		523	section in the Yocto Project Development Manual.
		524	</para>
		525	</section>
		526
		527	<section id='finding-the-kernel-source-code'>
		528	<title>Finding the Kernel Source Code</title>
		529
		530	<para>
		531	Each time you build a kernel image, the kernel source code
		532	is fetched and unpacked into the following directory:
		533	<literallayout class='monospaced'>
		534	${S}/linux
		535	</literallayout>
		536	See the "<ulink url='&YOCTO_DOCS_DEV_URL;#finding-the-temporary-source-code'>Finding Temporary Source Code</ulink>"
		537	section in the Yocto Project Development Manual and the
		538	<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
		539	variable for more information about where source is kept
		540	during a build.
		541	</para>
		542
		543	<para>
		544	For this example, we are going to patch the
		545	<filename>init/calibrate.c</filename> file
		546	by adding some simple console <filename>printk</filename> statements that we can
		547	see when we boot the image using QEMU.
		548	</para>
		549	</section>
		550
		551	<section id='creating-the-patch'>
		552	<title>Creating the Patch</title>
		553
		554	<para>
		555	Two methods exist by which you can create the patch:
		556	<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
		557	and
		558	<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Quilt</ulink>.
		559	For kernel patches, the Git workflow is more appropriate.
		560	This section assumes the Git workflow and shows the steps
		561	specific to this example.
		562	<orderedlist>
		563	<listitem><para>
		564	<emphasis>Change the working directory</emphasis>:
		565	Change to where the kernel source code is before making
		566	your edits to the <filename>calibrate.c</filename> file:
		567	<literallayout class='monospaced'>
		568	$ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
		569	</literallayout>
		570	Because you are working in an established Git repository,
		571	you must be in this directory in order to commit your changes
		572	and create the patch file.
		573	<note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
		574	<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
		575	represent the version and revision for the
		576	<filename>linux-yocto</filename> recipe.
		577	The <filename>PV</filename> variable includes the Git meta and machine
		578	hashes, which make the directory name longer than you might
		579	expect.
		580	</note></para></listitem>
		581	<listitem><para>
		582	<emphasis>Edit the source file</emphasis>:
		583	Edit the <filename>init/calibrate.c</filename> file to have the
		584	following changes:
		585	<literallayout class='monospaced'>
		586	void calibrate_delay(void)
		587	{
		588	unsigned long lpj;
		589	static bool printed;
		590	int this_cpu = smp_processor_id();
		591
		592	printk("*************************************\n");
		593	printk("* *\n");
		594	printk("* HELLO YOCTO KERNEL *\n");
		595	printk("* *\n");
		596	printk("*************************************\n");
		597
		598	if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
		599	.
		600	.
		601	.
		602	</literallayout></para></listitem>
		603	<listitem><para><emphasis>Stage and commit your changes</emphasis>:
		604	These Git commands display the modified file, stage it, and then
		605	commit the file:
		606	<literallayout class='monospaced'>
		607	$ git status
		608	$ git add init/calibrate.c
		609	$ git commit -m "calibrate: Add printk example"
		610	</literallayout></para></listitem>
		611	<listitem><para><emphasis>Generate the patch file</emphasis>:
		612	This Git command creates the a patch file named
		613	<filename>0001-calibrate-Add-printk-example.patch</filename>
		614	in the current directory.
		615	<literallayout class='monospaced'>
		616	$ git format-patch -1
		617	</literallayout>
		618	</para></listitem>
		619	</orderedlist>
		620	</para>
		621	</section>
		622
		623	<section id='set-up-your-layer-for-the-build'>
		624	<title>Set Up Your Layer for the Build</title>
		625
		626	<para>These steps get your layer set up for the build:
		627	<orderedlist>
		628	<listitem><para><emphasis>Create additional structure</emphasis>:
		629	Create the additional layer structure:
		630	<literallayout class='monospaced'>
		631	$ cd ~/poky/meta-mylayer
		632	$ mkdir conf
		633	$ mkdir recipes-kernel
		634	$ mkdir recipes-kernel/linux
		635	$ mkdir recipes-kernel/linux/linux-yocto
		636	</literallayout>
		637	The <filename>conf</filename> directory holds your configuration files, while the
		638	<filename>recipes-kernel</filename> directory holds your append file and
		639	your patch file.</para></listitem>
		640	<listitem><para><emphasis>Create the layer configuration file</emphasis>:
		641	Move to the <filename>meta-mylayer/conf</filename> directory and create
		642	the <filename>layer.conf</filename> file as follows:
		643	<literallayout class='monospaced'>
		644	# We have a conf and classes directory, add to BBPATH
		645	BBPATH .= ":${LAYERDIR}"
		646
		647	# We have recipes-* directories, add to BBFILES
		648	BBFILES += "${LAYERDIR}/recipes-//*.bb \
		649	${LAYERDIR}/recipes-//*.bbappend"
		650
		651	BBFILE_COLLECTIONS += "mylayer"
		652	BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
		653	BBFILE_PRIORITY_mylayer = "5"
		654	</literallayout>
		655	Notice <filename>mylayer</filename> as part of the last three
		656	statements.</para></listitem>
		657	<listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
		658	Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
		659	the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
		660	<literallayout class='monospaced'>
		661	FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
		662
		663	SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
		664	</literallayout>
		665	The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
		666	and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
		667	statements enable the OpenEmbedded build system to find the patch file.
		668	For more information on using append files, see the
		669	"<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
		670	section in the Yocto Project Development Manual.
		671	</para></listitem>
		672	<listitem><para>
		673	<emphasis>Put the patch file in your layer</emphasis>:
		674	Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
		675	the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
		676	directory.</para></listitem>
		677	</orderedlist>
		678	</para>
		679	</section>
		680
		681	<section id='set-up-for-the-build'>
		682	<title>Set Up for the Build</title>
		683
		684	<para>
		685	Do the following to make sure the build parameters are set up for the example.
		686	Once you set up these build parameters, they do not have to change unless you
		687	change the target architecture of the machine you are building:
		688	<itemizedlist>
		689	<listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
		690	selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
		691	definition within the <filename>local.conf</filename> file in the
		692	<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
		693	specifies the target architecture used when building the Linux kernel.
		694	By default, <filename>MACHINE</filename> is set to
		695	<filename>qemux86</filename>, which specifies a 32-bit
		696	<trademark class='registered'>Intel</trademark> Architecture
		697	target machine suitable for the QEMU emulator.</para></listitem>
		698	<listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
		699	layer:</emphasis> The
		700	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
		701	variable in the
		702	<filename>bblayers.conf</filename> file found in the
		703	<filename>poky/build/conf</filename> directory needs to have the path to your local
		704	<filename>meta-mylayer</filename> layer.
		705	By default, the <filename>BBLAYERS</filename> variable contains paths to
		706	<filename>meta</filename>, <filename>meta-poky</filename>, and
		707	<filename>meta-yocto-bsp</filename> in the
		708	<filename>poky</filename> Git repository.
		709	Add the path to your <filename>meta-mylayer</filename> location:
		710	<literallayout class='monospaced'>
		711	BBLAYERS ?= " \
		712	$HOME/poky/meta \
		713	$HOME/poky/meta-poky \
		714	$HOME/poky/meta-yocto-bsp \
		715	$HOME/poky/meta-mylayer \
		716	"
		717	</literallayout></para></listitem>
		718	</itemizedlist>
		719	</para>
		720	</section>
		721
		722	<section id='build-the-modified-qemu-kernel-image'>
		723	<title>Build the Modified QEMU Kernel Image</title>
		724
		725	<para>
		726	The following steps build your modified kernel image:
		727	<orderedlist>
		728	<listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
		729	Your environment should be set up since you previously sourced
		730	the
		731	<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
		732	script.
		733	If it is not, source the script again from <filename>poky</filename>.
		734	<literallayout class='monospaced'>
		735	$ cd ~/poky
		736	$ source &OE_INIT_FILE;
		737	</literallayout>
		738	</para></listitem>
		739	<listitem><para>
		740	<emphasis>Clean up</emphasis>:
		741	Be sure to clean the shared state out by using BitBake
		742	to run from within the Build Directory the
		743	<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>
		744	task as follows:
		745	<literallayout class='monospaced'>
		746	$ bitbake -c cleansstate linux-yocto
		747	</literallayout></para>
		748	<para>
		749	<note>
		750	Never remove any files by hand from the
		751	<filename>tmp/deploy</filename>
		752	directory inside the
		753	<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
		754	Always use the various BitBake clean tasks to
		755	clear out previous build artifacts.
		756	For information on the clean tasks, see the
		757	"<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>",
		758	"<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>",
		759	and
		760	"<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>"
		761	sections all in the Yocto Project Reference
		762	Manual.
		763	</note>
		764	</para></listitem>
		765	<listitem><para>
		766	<emphasis>Build the image</emphasis>:
		767	Next, build the kernel image using this command:
		768	<literallayout class='monospaced'>
		769	$ bitbake -k linux-yocto
		770	</literallayout></para></listitem>
		771	</orderedlist>
		772	</para>
		773	</section>
		774
		775	<section id='boot-the-image-and-verify-your-changes'>
		776	<title>Boot the Image and Verify Your Changes</title>
		777
		778	<para>
		779	These steps boot the image and allow you to see the changes
		780	<orderedlist>
		781	<listitem><para><emphasis>Boot the image</emphasis>:
		782	Boot the modified image in the QEMU emulator
		783	using this command:
		784	<literallayout class='monospaced'>
		785	$ runqemu qemux86
		786	</literallayout></para></listitem>
		787	<listitem><para><emphasis>Verify the changes</emphasis>:
		788	Log into the machine using <filename>root</filename> with no password and then
		789	use the following shell command to scroll through the console's boot output.
		790	<literallayout class='monospaced'>
		791	# dmesg \| less
		792	</literallayout>
		793	You should see the results of your <filename>printk</filename> statements
		794	as part of the output.</para></listitem>
		795	</orderedlist>
		796	</para>
		797	</section>
		798	</section>
		799
452	<section id='using-an-iterative-development-process'>	800	<section id='using-an-iterative-development-process'>
453	<title>Using an Iterative Development Process</title>	801	<title>Using an Iterative Development Process</title>
454		802
@@ -747,8 +1095,8 @@
747	"<link linkend='applying-patches'>Applying Patches</link>"	1095	"<link linkend='applying-patches'>Applying Patches</link>"
748	section.	1096	section.
749	If you are not familiar with generating patches, refer to the	1097	If you are not familiar with generating patches, refer to the
750	"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"	1098	"<link linkend='creating-the-patch'>Creating the Patch</link>"
751	section in the Yocto Project Development Manual.	1099	section.
752	</para>	1100	</para>
753	</section>	1101	</section>
754	</section>	1102	</section>


diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml index 7f6b82fee5..60d67d64fe 100644 --- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -461,9 +461,8 @@
461	"<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>"	461	"<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>"
462	section.	462	section.
463	You can also reference the	463	You can also reference the
464	"<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"	464	"<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
465	section in the Yocto Project Development Manual for a detailed	465	section for a detailed example that modifies the kernel.
466	example that modifies the kernel.
467	</para>	466	</para>
468	</section>	467	</section>
469	</appendix>	468	</appendix>


diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index 95c50e4691..899ed65db2 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -108,12 +108,14 @@
108	You can find additional information here:	108	You can find additional information here:
109	<itemizedlist>	109	<itemizedlist>
110	<listitem><para>	110	<listitem><para>
111	"<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"	111	The
112	in the Yocto Project Development Manual.	112	"<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
		113	section.
113	</para></listitem>	114	</para></listitem>
114	<listitem><para>	115	<listitem><para>
		116	The
115	"<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"	117	"<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
116	in the Yocto Project Development Manual.	118	section in the Yocto Project Development Manual.
117	</para></listitem>	119	</para></listitem>
118	</itemizedlist>	120	</itemizedlist>
119	This illustration and the following list summarizes the kernel	121	This illustration and the following list summarizes the kernel