documentation/dev-manual/dev-manual-kernel-appendix.xml: Added appendix

New file for the kernel example.  this will be an appendix.

(From yocto-docs rev: fca7e4fbb3d1e738700349d6169d7217c04e4b31)

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

1 files changed, 446 insertions, 0 deletions

diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml
new file mode 100644
index 0000000..fc93b53
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -0,0 +1,446 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id='dev-manual-cases'>
+
+<title>Development Cases</title>
+
+    <section id='modifying-a-kernel-kernel-example'>
+        <title>Modifying a Kernel</title>
+
+        <para>
+            Kernel modification involves changing or adding configurations to an existing kernel, or 
+            adding recipes to the kernel that are needed to support specific hardware features.  
+            The process is similar to creating a Board Support Package (BSP) except that it does not
+            involve a BSP layer.
+        </para>
+
+        <para>
+            This section presents a brief overview of the kernel structure and then provides a simple 
+            example that shows how to modify the kernel.
+        </para>
+
+        <section id='yocto-project-kernel'>
+            <title>Yocto Project Kernel Overview</title>
+
+            <para>
+                When one thinks of the source files for a kernel they usually think of a fixed structure 
+                of files that contain kernel patches.
+                The Yocto Project, however, employs mechanisims that in a sense result in a kernel source
+                generator.
+            </para>
+
+            <para>
+                The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto 
+                Project files.
+                Git employs branching strategies that effectively produce a tree-like structure whose 
+                branches represent diversions from more general code. 
+                For example, suppose two kernels are basically identical with the exception of a couple
+                different features in each.
+                In the Yocto Project source repositories managed by Git a main branch can contain the 
+                common or shared
+                parts of the kernel source and two branches that diverge from that common branch can 
+                each contain the features specific to the respective kernel.
+                The result is a managed tree whose "leaves" represent the end of a specific path that yields
+                a set of kernel source files necessary for a specific piece of hardware and its features.
+            </para>
+         
+            <para>
+                A big advantage to this scheme is the sharing of common features by keeping them in 
+                "larger" branches that are further up the tree.  
+                This practice eliminates redundant storage of similar features shared among kernels.
+            </para>
+
+            <para>
+                When you build the kernel on your development system all files needed for the build
+                are taken from the Yocto Project source repositories pointed to by the 
+                <filename>SRC_URI</filename> variable and gathered in a temporary work area
+                where they are subsequently used to create the unique kernel.
+                Thus, in a sense, the process constructs a local source tree specific to your 
+                kernel to generate the new kernel image - a source generator if you will.
+            </para>
+
+            <para>
+                For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
+                see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
+                The Yocto Project Kernel Architecture and Use Manual</ulink>.
+            </para>
+
+            <para>  
+                You can find a web interface to the Yocto Project source repository at 
+                <ulink url='http://git.yoctoproject.org/'></ulink>.  
+                Within the interface you will see groups of related source code, each of which can 
+                be cloned using Git to result in a working Git repository on your local system 
+                (referred to as the "local Yocto Project files" in this manual).
+                The Yocto Project supports four types of kernels in its source repositories at 
+                <ulink url='http://git.yoctoproject.org/'></ulink>:
+                <itemizedlist>
+                    <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The 
+                    stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
+                    <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The current
+                    Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
+                    <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
+                    kernel based on the Linux 2.6.39-rc1 release.</para></listitem>
+                    <listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on 
+                    minimal Linux mainline tracking.
+                    [WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this
+                    repository on their development system.]</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='modifying-a-kernel-example'>
+            <title>Modifying a Kernel Example</title>
+
+            <para>
+                This section presents a simple example that illustrates kernel modification
+                based on the <filename>linux-yocto-2.6.37</filename> kernel.
+                The example uses the audio and mixer capabilities supported by the 
+                <ulink url='http://www.alsa-project.org/main/index.php/Main_Page'>Advanced Linux 
+                Sound Architecture (ALSA) Project</ulink>.
+                As the example progresses you will see how to do the following:
+                <itemizedlist>
+                    <listitem><para>Iteratively modify a base kernel locally.</para></listitem>      
+                    <listitem><para>Provide a recipe-based solution for your modified kernel.
+                    </para></listitem>
+                    <listitem><para>Proved an "in-tree" solution for your modified kernel
+                    (i.e. make the modifcations part of the Yocto Project).</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                The example flows as follows:
+            </para>
+
+            <para>
+                <itemizedlist>
+                    <listitem><para>Be sure your host development system is set up to support 
+                    development using the Yocto Project. 
+                    See  
+                    <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
+                    The Linux Distributions</ulink> section and  
+                    <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
+                    The Packages</ulink> section both
+                    in the Yocto Project Quick Start for requirements.
+                    You will also need a release of Yocto Project installed on the host.</para></listitem>
+                    <listitem><para>Set up your environment for optimal local kernel development.
+                    </para></listitem>
+                    <listitem><para>Create a layer to isolate your kernel work.</para></listitem>
+                    <listitem><para>Next item.</para></listitem>
+                    <listitem><para>Next item.</para></listitem>
+                    <listitem><para>Next item.</para></listitem>
+                    <listitem><para>Next item.</para></listitem>
+                </itemizedlist>        
+            </para>
+
+            <section id='setting-up-yocto-project-kernel-example'>
+                <title>Setting Up Yocto Project</title>
+
+                <para>
+                    You need to have the Yocto Project files available on your host system.  
+                    The process is identical to that described in the 
+                    <xref linkend='getting-setup'>"Getting Setup"</xref> section earlier in this 
+                    manual.
+                    Be sure to either set up a local Git repository for <filename>poky</filename>
+                    or download and unpack the Yocto Project release tarball.  
+                </para>
+            </section>
+
+            <section id='create-a-git-repository-of-poky-extras'>
+                <title>Create a Git Repository of <filename>poky-extras</filename></title>
+
+                <para>
+                    Everytime you change a configuration or add a recipe to the kernel you need to 
+                    do a fetch from the Linux Yocto kernel source repositories.
+                    This can get tedious and time consuming if you need to fetch the entire 
+                    Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change
+                    to the kernel.  
+                </para>
+
+                <para>
+                    You can get around this by setting up a <filename>meta-kernel-dev</filename>
+                    area on your local system.  
+                    This area contains "append" files for every kernel recipe, which also include
+                    a <filename>KSRC</filename> statement that points to the kernel source files.
+                    You can set up the environment so that the <filename>KSRC</filename> points to the
+                    <filename>meta-kernel-dev</filename>, thus pulling source from a local area.
+                    This setup can speed up development time. 
+                 </para>
+
+                 <para>
+                    To get set up you need to do two things: create a local Git repository 
+                    of the <filename>poky-extras</filename> repository, and create a bare clone of the 
+                    Linux Yocto 2.6.37 kernel Git repository.
+                 </para>
+
+                 <para>
+                    The following transcript shows how to clone the <filename>poky-extras</filename> 
+                    Git repository into the current working directory, which is <filename>poky</filename>
+                    in this example.  
+                    The command creates the repository in a directory named <filename>poky-extras</filename>:
+                    <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/poky-extras
+     Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
+     remote: Counting objects: 532, done.
+     remote: Compressing objects: 100% (472/472), done.
+     remote: Total 532 (delta 138), reused 307 (delta 39)
+     Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done.
+     Resolving deltas: 100% (138/138), done.
+                    </literallayout>
+                </para>
+
+                <para>
+                    This transcript shows how to clone a bare Git repository of the Linux Yocto 
+                    2.6.37 kernel:
+                    <literallayout class='monospaced'>
+     $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37
+     Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/
+     remote: Counting objects: 1886034, done.
+     remote: Compressing objects: 100% (314326/314326), done.
+     remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798)
+     Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done.
+     Resolving deltas: 100% (1570202/1570202), done.
+                    </literallayout>
+                </para>
+
+                <para>
+                    The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors
+                    the upstream repository of the kernel.
+                    You can effectively point to this local clone now during development to avoid 
+                    having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a 
+                    kernel change.
+                </para>
+            </section>
+
+            <section id='create-a-layer-for-your-kernel-work'>
+                <title>Create a Layer for Your Kernel Work</title>
+
+                <para>
+                    It is always good to isolate your work using your own layer.
+                    Doing so allows you to experiment and easily start over should things go wrong. 
+                    This example uses a layer named <filename>meta-amixer</filename>.
+                </para>
+
+                <para>
+                    When you set up a layer for kernel work you should follow the general layout
+                    guidelines as described for BSP layers. 
+                    This layout is described in the
+                    <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
+                    Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
+                    Guide.  
+                    In the standard layout you will notice a suggested structure for recipes and  
+                    configuration information.  
+                    [WRITER'S NOTE: The <filename>meta-elc</filename> example uses an 
+                    <filename>images</filename> directory.
+                    Currently, <filename>images</filename> is not part of the standard BSP layout.
+                    I need to find out from Darren if this directory is required for kernel work.]
+                </para>
+
+                <para>
+                    [WRITER'S NOTE:  I need a paragraph here describing how to set up the layer. 
+                    I am not sure if you should copy an existing BSP layer and modify from there.
+                    Or, if you should just look at a BSP layer and then create your own files.
+                    Email to Darren on this but no answer yet.]
+                </para>
+            </section>
+
+            <section id='making-changes-to-your-kernel-layer'>
+                <title>Making Changes to Your Kernel Layer</title>
+            
+                <para>
+                    In the standard layer structure you have several areas that you need to examine or 
+                    modify.
+                    For this example the layer contains four areas:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>conf</filename></emphasis> - Contains the 
+                        <filename>layer.conf</filename> that identifies the location of the recipe files. 
+                        </para></listitem>
+                        <listitem><para><emphasis><filename>images</filename></emphasis> - Contains the 
+                        image recipe file. 
+                        This recipe includes the base image you will be using and specifies other 
+                        packages the image might need.</para></listitem>
+                        <listitem><para><emphasis><filename>recipes-bsp</filename></emphasis> - Contains 
+                        recipes specific to the hardware for which you are developing the kernel.
+                        </para></listitem>
+                        <listitem><para><emphasis><filename>recipes-kernel</filename></emphasis> - Contains the 
+                        "append" files that add information to the main recipe kernel.  
+                        </para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    Let's take a look at the <filename>layer.conf</filename> in the 
+                    <filename>conf</filename> directory first.
+                    This configuration file enables the Yocto Project build system to locate and 
+                    use the information in your new layer.
+                </para>
+
+                <para>
+                    The variable <filename>BBPATH</filename> needs to include the path to your layer
+                    as follows:
+                    <literallayout class='monospaced'>
+     BBPATH := "${BBPATH}:${LAYERDIR}"
+                    </literallayout>
+                    And, the variable <filename>BBFILES</filename> needs to be modified to include your 
+                    recipe and append files:
+                    <literallayout class='monospaced'>
+     BBFILES := "${BBFILES} ${LAYERDIR}/images/*.bb \ 
+        ${LAYERDIR}/images/*.bbappend \
+        ${LAYERDIR}/recipes-*/*/*.bb \
+        ${LAYERDIR}/recipes-*/*/*.bbappend"
+                    </literallayout>
+                    Finally, you need to be sure to use your layer name in these variables at the 
+                    end of the file:
+                    <literallayout class='monospaced'>
+     BBFILE_COLLECTIONS += "elc"
+     BBFILE_PATTERN_elc := "^${LAYERDIR}/"
+     BBFILE_PRIORITY_elc = "9"
+                   </literallayout>
+                </para>
+
+                <para>
+                    The <filename>images</filename> directory contains an append file that helps 
+                    further define the image.
+                    In our example, the base image is <filename>core-image-minimal</filename>.  
+                    The image does, however, need some additional modules that we are using
+                    for this example.
+                    These modules support the amixer functionality.
+                    Here is the append file:
+                    <literallayout class='monospaced'>
+     require recipes-core/images/poky-image-minimal.bb
+
+     IMAGE_INSTALL += "dropbear alsa-utils-aplay alsa-utils-alsamixer"
+     IMAGE_INSTALL_append_qemux86 += " kernel-module-snd-ens1370 \
+        kernel-module-snd-rawmidi kernel-module-loop kernel-module-nls-cp437 \
+        kernel-module-nls-iso8859-1 qemux86-audio alsa-utils-amixer"
+
+     LICENSE = "MIT"
+                   </literallayout>
+               </para>
+
+               <para>
+                   While the focus of this example is not on the BSP, it is worth mentioning that the
+                   <filename>recipes-bsp</filename> directory has the recipes and append files for 
+                   features that the hardware requires. 
+                   In this example, there is a script and a recipe to support the 
+                   <filename>amixer</filename> functionality in QEMU.
+                   It is beyond the scope of this manual to go too deeply into the script.
+                   Suffice it to say that the script tests for the presence of the mixer, sets up 
+                   default mixer values, enables the mixer, unmutes master and then 
+                   sets the volume to 100.
+               </para>
+
+               <para>
+                   The recipe <filename>qemu86-audio.bb</filename> installs and runs the 
+                   <filename>amixer</filename> when the system boots.
+                   Here is the recipe:
+                   <literallayout class='monospaced'>
+     SUMMARY = "Provide a basic init script to enable audio"
+     DESCRIPTION = "Set the volume and unmute the Front mixer setting during boot."
+     SECTION = "base"
+     LICENSE = "MIT"
+     LIC_FILES_CHKSUM = "file://${POKYBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58"
+
+     PR = "r4"
+
+     inherit update-rc.d
+
+     RDEPENDS = "alsa-utils-amixer"
+
+     SRC_URI = "file://qemux86-audio"
+
+     INITSCRIPT_NAME = "qemux86-audio"
+     INITSCRIPT_PARAMS = "defaults 90"
+
+     do_install() {
+	     install -d ${D}${sysconfdir} \
+     	           ${D}${sysconfdir}/init.d
+     	install -m 0755 ${WORKDIR}/qemux86-audio ${D}${sysconfdir}/init.d
+             cat ${WORKDIR}/${INITSCRIPT_NAME} | \
+                 sed -e 's,/etc,${sysconfdir},g' \
+                     -e 's,/usr/sbin,${sbindir},g' \
+                     -e 's,/var,${localstatedir},g' \
+                     -e 's,/usr/bin,${bindir},g' \
+                     -e 's,/usr,${prefix},g' > ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
+             chmod 755 ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
+     }
+                </literallayout>
+                </para>
+
+                <para>
+                    The last area to look at is <filename>recipes-kernel</filename>.
+                    This area holds configuration fragments and kernel append files.
+                    The append file must have the same name as the kernel recipe, which is 
+                    <filename>linux-yocto-2.6.37</filename> in this example.
+                    The file can <filename>SRC_URI</filename> statements to point to configuration 
+                    fragments you might have in the layer. 
+                    The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify
+                    included kernel configurations that ship with the Yocto Project.
+                </para>
+            </section>
+        </section>
+    </section>
+
+</chapter>
+
+
+                
+            
+
+<!--
+
+
+            <para>
+                [WRITER'S NOTE:  This section is a second example that focuses on just modifying the kernel.
+                I don't have any information on this yet.
+            </para>
+
+            <para>
+                Here are some points to consider though:
+                <itemizedlist>
+                    <listitem><para>Reference Darren's presentation 
+                        <ulink url='http://events.linuxfoundation.org/events/embedded-linux-conference/hart'>
+                        here</ulink></para></listitem>
+                    <listitem><para>Reference <xref linkend='dev-manual-start'>Getting Started with the Yocto Project</xref>
+                        section to get set up at minimum.</para></listitem>
+                    <listitem><para>Are there extra steps I need specific to kernel development to get started?</para></listitem>
+                    <listitem><para>What do I do to get set up?  
+                        Is it a matter of just installing YP and having some pieces together?  
+                        What are the pieces?</para></listitem>
+                    <listitem><para>Where do I get the base kernel to start with?</para></listitem>
+                    <listitem><para>Do I install the appropriate toolchain?</para></listitem>
+                    <listitem><para>What kernel git repository do I use?</para></listitem>
+                    <listitem><para>What is the conversion script?  
+                        What does it do?</para></listitem>
+                    <listitem><para>What do I have to do to integrate the kernel layer?</para></listitem>
+                    <listitem><para>What do I use to integrate the kernel layer?  
+                        HOB? 
+                        Do I just Bitbake it?</para></listitem>
+                    <listitem><para>Using the System Image Creator.]</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+    </section>
+</section>
+
+<section id='user-application-development'>
+    <title>User Application Development</title>
+
+    <para>
+        [WRITER'S NOTE:  This section is the second major development case - developing an application.
+        Here are points to consider:
+        <itemizedlist>
+            <listitem><para>User-space Application Development scenario overview.</para></listitem>
+            <listitem><para>Using the Yocto Eclipse Plug-in.</para></listitem>
+            <listitem><para>Back-door support.</para></listitem>
+            <listitem><para>I feel there is more to this area than we have captured during our two 
+                review meetings.]</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+</chapter>
+-->
+
+<!--
+vim: expandtab tw=80 ts=4
+-->