documentation/dev-manual/dev-manual-cases.xml: partial - kernel section added

added the start of the kernel example.  It is not complete.
There are other various edits made throughout the chapter as well.

(From yocto-docs rev: 39ba857b71aa643593a539d979186753fb7a9049)

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

1 files changed, 305 insertions, 13 deletions

diff --git a/documentation/dev-manual/dev-manual-cases.xml b/documentation/dev-manual/dev-manual-cases.xml
index 610412d166..28d48d0c9e 100644
--- a/documentation/dev-manual/dev-manual-cases.xml
+++ b/documentation/dev-manual/dev-manual-cases.xml
@@ -750,7 +750,7 @@
         </section>
     </section>
 
-    <section id='modifying-a-kernel'>
+    <section id='modifying-a-kernel-kernel-example'>
         <title>Modifying a Kernel</title>
 
         <para>
@@ -765,7 +765,7 @@
             example that shows how to modify the kernel.
         </para>
 
-        <section id='yocto-project-kernel-overview'>
+        <section id='yocto-project-kernel'>
             <title>Yocto Project Kernel Overview</title>
 
             <para>
@@ -782,10 +782,11 @@
                 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 kernel Git repository a main branch can contain the common or shared
+                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 tree whose "leaves" represent the end of a specific path that yields
+                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>
          
@@ -797,11 +798,11 @@
 
             <para>
                 When you build the kernel on your development system all files needed for the build
-                are taken from the local tree (the Git repository) and gathered in a temporary work area
+                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 uses a local, all-inclusive source tree to generate 
-                (or choose) the specific kernel source files you need for the build - a source 
-                generator if you will.
+                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>
@@ -814,7 +815,8 @@
                 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.
+                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>
@@ -836,15 +838,303 @@
             <title>Modifying a Kernel Example</title>
 
             <para>
-                The remainder of this section presents a simple example that modifies a kernel.
-                For the purpose of this example we are going to base our new kernel on the current
-                Linux Yocto 2.6.37 release.
+                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 getting the files in section
+                    <xref linkend='setting-up-yocto-project'>"Setting Up Yocto Project"</xref> for
+                    the BSP development case.
+                    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>
+</section>
 
+</chapter>
 
 
+                
+            
+
+<!--
+
 
             <para>
                 [WRITER'S NOTE:  This section is a second example that focuses on just modifying the kernel.
@@ -895,6 +1185,8 @@
     </para>
 </section>
 </chapter>
+-->
+
 <!--
 vim: expandtab tw=80 ts=4
 -->