documentation/dev-manual/dev-manual-bsp-appendix.xml: New appendix for BSP

I decided to take the long detailed example of the BSP creation and
make it an appendix.  This commit represents a simple copy of the existing
dev-manual-cases chapter.  Further commits will change the text to
make it suitable as an appendix.

(From yocto-docs rev: 8c1308c4361f48ce7f7aa104cde7e6f6a820faa4)

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

1 files changed, 1192 insertions, 0 deletions

diff --git a/documentation/dev-manual/dev-manual-bsp-appendix.xml b/documentation/dev-manual/dev-manual-bsp-appendix.xml
new file mode 100644
index 0000000..cf1033e
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-bsp-appendix.xml
@@ -0,0 +1,1192 @@
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<appendix id='dev-manual-bsp-appendix'>
+
+<title>Development Cases</title>
+
+<para>
+    Many development cases exist for which you can use the Yocto Project. 
+    However, for the purposes of this manual we are going to focus on two common development cases or groupings:  
+    System Development and User Application Development.  
+    System Development covers Board Support Package (BSP) development and kernel modification.  
+    User Application Development covers development of applications that you intend to run on some 
+    target hardware.  
+</para>
+
+<para>
+    [WRITERS NOTE:  What is undetermined at this point is how much of the entire development process 
+    we include in this particular chapter.  
+    In other words, do we cover debugging and emulation steps here on a case-specific basis?  
+    Or, do we capture that information in the appropriate subsequent chapter by case?]
+</para>
+
+<section id='system-development-app'>
+    <title>System Development</title>
+
+    <para>
+        System development involves modification or creation of an image that you want to run on 
+        a specific hardware target.  
+        Usually when you want to create an image that runs on embedded hardware the image does 
+        not require the same amount of features that a full-fledged Linux distribution provides.  
+        Thus, you can create a much smaller image that is designed to just use the hardware 
+        features for your particular hardware.
+    </para>
+
+    <para>
+        To help you understand how system development works in the Yocto Project, this section 
+        covers two types of image development:  BSP creation and kernel modification.
+    </para>
+
+    <section id='developing-a-board-support-package-bsp-app'>
+        <title>Developing a Board Support Package (BSP)</title>
+
+        <para>
+            A BSP is a package of recipes that when applied while building an image results in 
+            an image you can run on a particular board.  
+            Thus, the package, when compiled into the new image, supports the operation of the board.  
+        </para>
+
+        <note>
+            For a brief list of terms used when describing the development process in the Yocto Project, 
+            see <xref linkend='yocto-project-terms'>Yocto Project Terms</xref> in this manual.
+        </note>
+
+        <para>
+            Here are the basic steps involved in creating a BSP:
+            <orderedlist>
+                <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>Choose a BSP available with Yocto Project that most closely represents 
+                    your hardware.</para></listitem>
+                <listitem><para>Get set up with a base BSP.</para></listitem>
+                <listitem><para>Make a copy of the existing BSP and isolate your work by creating a layer 
+                    for your recipes.</para></listitem>
+                <listitem><para>Make configuration and recipe changes to your new BSP layer.</para></listitem>
+                <listitem><para>Prepare for the build.</para></listitem>
+                <listitem><para>Select and configure the kernel.</para></listitem>
+                <listitem><para>Identify the machine branch.</para></listitem>
+                <listitem><para>Build the image.</para></listitem>
+            </orderedlist>
+                You can view a video presentation of the BSP creation process 
+                <ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>.  
+                You can also find supplemental information in the 
+                <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
+                Board Support Package (BSP) Development Guide</ulink>.
+                Finally, there is wiki page write up of the example located 
+                <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
+                here</ulink> you might find helpful.
+        </para>
+
+        <section id='setting-up-yocto-project-app'>
+            <title>Setting Up Yocto Project</title>
+
+            <para>
+                You need to have the Yocto Project files available on your host system.  
+                You can get files through tarball extraction or by cloning the <filename>poky</filename>
+                Git repository.  
+                Typically, cloning the Git repository is the method to use.  
+                This allows you to maintain a complete history of changes and facilitates you 
+                contributing back to the Yocto Project.  
+                However, if you just want a hierarchical file structure that contains the recipes
+                and metadata that let you develop you can download tarballs from the 
+                <ulink url='http://yoctoproject.org/download'>download page</ulink>.
+            </para>
+
+            <para>
+                Regardless of the method you use this manual will refer to the resulting 
+                hierarchical set of files as "the local Yocto Project files."
+            </para>
+
+            <para>
+                [WRITER'S NOTE: I need to substitute correct and actual filenames for the 
+                1.1 release throughout this example once they become available.]
+            </para>
+
+            <para>  
+                If you download a tarball you can extract it into any directory you want using the 
+                tar command.  
+                For example, the following command extracts the Yocto Project 1.1 release tarball 
+                into the current working directory and sets up a file structure whose top-level 
+                directory is named <filename>poky-1.1</filename>:
+                <literallayout class='monospaced'>
+     $ tar xfj poky-1.1.tar.bz2
+                </literallayout>
+            </para>
+
+            <para>
+                The following transcript shows how to clone the <filename>poky</filename> Git repository
+                into the current working directory.  
+                The command creates the repository in a directory named <filename>poky</filename>:
+                <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/poky
+     Initialized empty Git repository in /home/scottrif/poky/.git/
+     remote: Counting objects: 107624, done.
+     remote: Compressing objects: 100% (37128/37128), done.
+     remote: Total 107624 (delta 73393), reused 99851 (delta 67287)
+     Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done.
+     Resolving deltas: 100% (73393/73393), done.
+                </literallayout>
+            </para>
+
+            <para>
+                Once you have the local <filename>poky</filename> Git repository set up, 
+                you have many development branches from which you can work. 
+                From inside the repository you can see the branch names and the tag names used 
+                in the Git repository using either of the following two commands:
+                <literallayout class='monospaced'>
+     $ git branch -a
+     $ git tag -l
+                </literallayout> 
+                For this example we are going to use the Yocto Project 1.1 Release, 
+                which maps to the <filename>1.1</filename> branch in the repository. 
+                These commands create a local branch named <filename>1.1</filename>
+                that tracks the remote branch of the same name.
+                <literallayout class='monospaced'>
+     
+     $ cd poky
+     $ git checkout -b 1.1 origin/1.1
+     Switched to a new branch '1.1'
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='choosing-a-base-bsp-app'>
+            <title>Choosing a Base BSP</title>
+
+            <para>
+                The Yocto Project ships with several BSPs that support various hardware.  
+                It is best to base your new BSP on an existing BSP rather than create all the 
+                recipes and configuration files from scratch.  
+                While it is possible to create everything from scratch, basing your new BSP 
+                on something that is close is much easier.  
+                Or, at a minimum, it gives you some structure with which to start.
+            </para>
+
+            <para>
+                At this point you need to understand your target hardware well enough to determine which 
+                existing BSP it most closely matches.  
+                Things to consider are your hardware’s on-board features such as CPU type and graphics support.  
+                You should look at the README files for supported BSPs to get an idea of which one 
+                you could use.  
+                A generic Atom-based BSP to consider is the Crown Bay that does not support
+                the Intel® Embedded Media Graphics Driver (EMGD).  
+                The remainder of this example uses that base BSP. 
+            </para>
+
+            <para>
+                To see the supported BSPs, go to the Yocto Project
+                <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click 
+                on “BSP Downloads.”
+            </para>
+        </section>
+
+        <section id='getting-your-base-bsp-app'>
+            <title>Getting Your Base BSP</title>
+
+            <para>
+                You need to have the base BSP layer on your development system.  
+                Like the local Yocto Project files, you can get the BSP 
+                layer one of two ways:  
+                download the BSP tarball and extract it, or set up a local Git repository that 
+                has the Yocto Project BSP layers.  
+                You should use the same method that you used to get the local Yocto Project files earlier.
+            </para>
+
+            <para>
+                If you are using tarball extraction, simply download the tarball for the base 
+                BSP you chose in the previous step and then extract it into any directory 
+                you choose using the tar command.  
+                Upon extraction, the BSP source directory (layer) will be named 
+                <filename>meta-&lt;BSP_name&gt;</filename>.  
+                The following command extracts the Crown Bay BSP into the current directory and names it 
+                <filename>meta-crownbay</filename>:
+                <literallayout class='monospaced'>
+     $ tar xjf crownbay-noemgd-1.1.tar.bz2
+                </literallayout>
+            </para>
+
+            <para>
+                If you cloned a <filename>poky</filename> Git repository
+                then you need to set up a different local Git repository 
+                (<filename>meta-intel</filename>) for the BSP.  
+                The <filename>meta-intel</filename> Git repository contains all the metadata 
+                that supports BSP creation.
+                When you set up the <filename>meta-intel</filename> Git repository you can 
+                set it up anywhere you want.
+                We will set up the repository inside the 
+                <filename>poky</filename> Git repository in this example.  
+            </para>
+
+            <para>
+                The following transcript shows the steps to clone the <filename>meta-intel</filename>
+                Git repository inside the <filename>poky</filename> Git repository created earlier in this 
+                example.
+                <literallayout class='monospaced'>
+     $cd poky
+     $ git clone git://git.yoctoproject.org/meta-intel.git
+     Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
+     remote: Counting objects: 1325, done.
+     remote: Compressing objects: 100% (1078/1078), done.
+     remote: Total 1325 (delta 546), reused 85 (delta 27)
+     Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done.
+     Resolving deltas: 100% (546/546), done.
+                </literallayout>
+            </para>
+
+            <para>
+                Because <filename>meta-intel</filename> is its own Git repository you will want
+                to be sure you are in the appropriate branch for your work.
+                For this example we are going to use the <filename>1.1</filename> branch. 
+                <literallayout class='monospaced'>
+     $ cd meta-intel
+     $ git checkout -b 1.1 origin/1.1
+     Switched to a new branch 'bernard'
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app'>
+            <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title>
+
+            <para>
+                Now that you have the local Yocto Project files and the base BSP files you need to create a 
+                new layer for your BSP.
+            </para>
+
+            <para>
+                Layers are ideal for isolating and storing work for a given piece of hardware.  
+                A layer is really just a location or area in which you place the recipes for your BSP.  
+                In fact, a BSP is, in itself, a special type of layer.   
+                Consider an application as another example that illustrates a layer.  
+                Suppose you are creating an application that has library or other dependencies in 
+                order for it to compile and run.  
+                The layer, in this case, would be where all the recipes that define those dependencies 
+                are kept.  The key point for a layer is that it is an isolated area that contains 
+                all the relevant information for the project that the Yocto Project build system knows about.
+            </para>
+
+            <note>
+                The Yocto Project supports four BSPs that are part of the 
+                Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
+                <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.  
+                The recipes and configurations for these four BSPs are located and dispersed 
+                within local Yocto Project files.
+                Consequently, they are not totally isolated in the spirit of layers unless you think 
+                of <filename>meta-yocto</filename> as a layer itself.  
+                On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, 
+                N450, and Sugar Bay are isolated.
+            </note>
+
+            <para>
+                When you set up a layer for a new BSP you should follow a standard layout.  
+                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.  
+                You can see the standard layout for the Crown Bay BSP in this example by examining the 
+                directory structure of the <filename>meta-crownbay</filename> layer inside the 
+                local Yocto Project files.
+            </para>
+
+            <para>
+                To create your BSP layer you simply copy the <filename>meta-crownbay</filename>
+                layer to a new layer.  
+                For this example the new layer will be named <filename>meta-mymachine</filename>.  
+                The name must follow the BSP layer naming convention, which is 
+                <filename>meta-&lt;name&gt;</filename>.  
+                The following example assumes your working directory is <filename>meta-intel</filename> 
+                inside the local Yocto Project files.  
+                If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting 
+                <filename>meta-crownbay</filename> directory structure to a location of your choice.
+                Good practice for a Git repository, however, is to just copy the new layer alongside 
+                the existing
+                BSP layers in the <filename>meta-intel</filename> Git repository:
+                <literallayout class='monospaced'>
+     $ cp -a meta-crownbay/ meta-mymachine 
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='making-changes-to-your-bsp-app'>
+            <title>Making Changes to Your BSP</title>
+
+            <para>
+                Right now you have two identical BSP layers with different names:  
+                <filename>meta-crownbay</filename> and <filename>meta-mymachine</filename>.  
+                You need to change your configurations so that they work for your new BSP and 
+                your particular hardware.  
+                We will look first at the configurations, which are all done in the layer’s 
+                <filename>conf</filename> directory.
+            </para>
+
+            <para>
+                First, since in this example the new BSP will not support EMGD we will get rid of the 
+                <filename>crownbay.conf</filename> file and then rename the 
+                <filename>crownbay-noemgd.conf</filename> file to <filename>mymachine.conf</filename>.  
+                Much of what we do in the configuration directory is designed to help the Yocto Project 
+                build system work with the new layer and to be able to find and use the right software.  
+                The following two commands result in a single machine configuration file named 
+                <filename>mymachine.conf</filename>.  
+                <literallayout class='monospaced'>
+     $ rm meta-mymachine/conf/machine/crownbay.conf
+     $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \
+     meta-mymachine/conf/machine/mymachine.conf
+                </literallayout>
+            </para>
+
+            <para>
+                The next step makes changes to <filename>mymachine.conf</filename> itself.  
+                The only changes needed for this example are changes to the comment lines.
+                Here we simply substitute the Crown Bay name with an appropriate name.
+            </para>
+
+            <para>
+                Note that inside the <filename>mymachine.conf</filename> is the 
+                <filename>PREFERRED_PROVIDER_virtual/kernel</filename> statement. 
+                This statement identifies the kernel that the BSP is going to use.
+                In this case the BSP is using <filename>linux-yocto</filename>, which is the 
+                current Linux Yocto kernel based on the Linux 2.6.37 release. 
+            </para>
+
+            <para>
+                The next configuration file in the new BSP layer we need to edit is <filename>layer.conf</filename>.
+                This file identifies build information needed for the new layer.  
+                You can see the 
+                <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout-layer'>
+                Layer Configuration File</ulink> section in the Board Support Packages (BSP) Development Guide
+                for more information on this configuration file.  
+                Basically, we are changing the existing statements to work with our BSP. 
+            </para>
+
+            <para>
+                The file contains these statements that reference the Crown Bay BSP:
+                <literallayout class='monospaced'>
+     BBFILE_COLLECTIONS += "crownbay"
+     BBFILE_PATTERN_crownbay := "^${LAYERDIR}/"
+     BBFILE_PRIORITY_crownbay = "6"
+                </literallayout>
+            </para>
+
+            <para>
+                Simply substitute the machine string name <filename>crownbay</filename>
+                with the new machine name <filename>mymachine</filename> to get the following:
+                <literallayout class='monospaced'>
+     BBFILE_COLLECTIONS_mymachine += "mymachine"
+     BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
+     BBFILE_PRIORITY_mymachine = "6"
+                </literallayout>
+            </para>
+
+            <para>
+                Now we will take a look at the recipes in your new layer.  
+                The standard BSP structure has areas for BSP, graphics, core, and kernel recipes.  
+                When you create a BSP you use these areas for appropriate recipes and append files.  
+                Recipes take the form of <filename>.bb</filename> files.  
+                If you want to leverage the existing recipes the Yocto Project build system uses
+                but change those recipes you can use <filename>.bbappend</filename> files.  
+                All new recipes and append files for your layer must go in the layer’s 
+                <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>, 
+                <filename>recipes-core</filename>, and 
+                <filename>recipes-graphics</filename> directories.    
+            </para>
+
+            <para>
+                First, let's look at <filename>recipes-bsp</filename>.
+                For this example we are not adding any new BSP recipes.  
+                And, we only need to remove the formfactor we do not want and change the name of 
+                the remaining one that doesn't support EMGD.  
+                These commands take care of the <filename>recipes-bsp</filename> recipes:
+                <literallayout class='monospaced'>
+     $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd*
+     $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \
+     meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
+                </literallayout>
+            </para>
+
+            <para>
+                Now let's look at <filename>recipes-graphics</filename>.
+                For this example we want to remove anything that supports EMGD and 
+                be sure to rename remaining directories appropriately.  
+                The following commands clean up the <filename>recipes-graphics</filename> directory:
+                <literallayout class='monospaced'>
+     $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd*
+     $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay
+     $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \
+        meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine   
+                </literallayout>
+            </para>
+
+            <para>
+                At this point the <filename>recipes-graphics</filename> directory just has files that 
+                support Video Electronics Standards Association (VESA) graphics modes and not EMGD.  
+            </para>
+
+            <para>
+                Now let's look at changes in <filename>recipes-core</filename>.
+                The file <filename>task-core-tools.bbappend</filename> in 
+                <filename>recipes-core/tasks</filename> appends the similarly named recipe
+                located in the local Yocto Project files at 
+                <filename>meta/recipes-core/tasks</filename>.
+                The "append" file in our layer right now is Crown Bay-specific and supports 
+                EMGD and non-EMGD.
+                Here are the contents of the file:
+                <literallayout class='monospaced'>
+     RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap"
+     RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap"
+                </literallayout>
+            </para>
+
+            <para>
+                The <filename>RRECOMMENDS</filename> statements list packages that 
+                extend usability.
+                The first <filename>RRECOMMENDS</filename> statement can be removed, while the 
+                second one can be changed to reflect <filename>meta-mymachine</filename>:
+                <literallayout class='monospaced'>
+     RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap"
+                </literallayout>
+            </para>
+
+            <para>
+                Finally, let's look at <filename>recipes-kernel</filename> changes.
+                Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined
+                earlier in the <filename>mymachine.conf</filename>.
+                The recipe for that kernel is not located in the  
+                BSP layer but rather in the local Yocto Project files at 
+                <filename>meta/recipes-kernel/linux</filename> and is 
+                named <filename>linux-yocto-2.6.37.bb</filename>.
+                The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename>
+                statements point to the exact commits used by the Yocto Project development team
+                in their source repositories that identify the right kernel for our hardware.
+            </para>
+ 
+            <para>
+                However, in the <filename>meta-mymachine</filename> layer in 
+                <filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename>
+                file named <filename>linux-yocto-2.6.37.bbappend</filename> that 
+                is appended to the recipe of the same name in <filename>meta/recipes-kernel/link</filename>.
+                Thus, the <filename>SRCREV</filename> statements in the "append" file override
+                the more general statements found in <filename>meta</filename>.
+            </para>
+
+            <para>
+                The <filename>SRCREV</filename> statements in the "append" file currently identify
+                the kernel that supports the Crown Bay BSP with and without EMGD support.
+                Here are the statements: 
+                <literallayout class='monospaced'>
+     SRCREV_machine_pn-linux-yocto_crownbay ?= \
+        "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
+     SRCREV_meta_pn-linux-yocto_crownbay ?= \
+        "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
+
+     SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= \
+        "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
+     SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \
+        "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
+                </literallayout>
+            </para>
+
+            <para>
+                You will notice that there are two pairs of <filename>SRCREV</filename> statements.  
+                The top pair identifies the kernel that supports
+                EMGD, which we don’t care about in this example.  
+                The bottom pair identifies the kernel that we will use:  
+                <filename>linux-yocto</filename>.  
+                At this point though, the unique commit strings all are still associated with 
+                Crown Bay and not <filename>meta-mymachine</filename>.
+            </para>
+
+            <para>  
+                To fix this situation in <filename>linux-yocto-2.6.37.bbappend</filename>
+                we delete the two <filename>SRCREV</filename> statements that support 
+                EMGD (the top pair).
+                We also change the remaining pair to specify <filename>mymachine</filename>
+                and insert the commit identifiers to identify the kernel in which we 
+                are interested, which will be based on the <filename>atom-pc-standard</filename>
+                kernel.
+                Here are the final <filename>SRCREV</filename> statements:
+                <literallayout class='monospaced'>
+     SRCREV_machine_pn-linux-yocto-_mymachine ?= \ 
+        "fce17f046d3756045e4dfb49221d1cf60fcae329"
+     SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \ 
+        "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
+                </literallayout>
+            </para>
+
+            <para>
+                If you are familiar with Git repositories you probably won’t have trouble locating the 
+                exact commit strings in the Yocto Project source repositories you need to change 
+                the <filename>SRCREV</filename> statements.  
+                You can find all the <filename>machine</filename> and <filename>meta</filename> 
+                branch points (commits) for the <filename>linux-yocto-2.6.37</filename> kernel 
+                <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37'>here</ulink>.  
+            </para>
+
+            <para>
+                If you need a little more assistance after going to the link then do the following:
+                <orderedlist>
+                    <listitem><para>Expand the list of branches by clicking <filename>[…]</filename></para></listitem>
+                    <listitem><para>Click on the <filename>yocto/standard/common-pc/atom-pc</filename> 
+                        branch</para></listitem>
+                    <listitem><para>Click on the commit column header to view the top commit</para></listitem>
+                    <listitem><para>Copy the commit string for use in the 
+                        <filename>linux-yocto-2.6.37.bbappend</filename> file</para></listitem>
+                </orderedlist>
+            </para>
+
+            <para>
+                For the <filename>SRCREV</filename> statement that points to the <filename>meta</filename>
+                branch use the same procedure except expand the <filename>meta</filename>
+                branch in step 2 above.
+            </para>
+
+            <para>
+                Also in the <filename>linux-yocto-2.6.37.bbappend</filename> file are 
+                <filename>COMPATIBLE_MACHINE</filename>, <filename>KMACHINE</filename>, 
+                and <filename>KERNEL_FEATURES</filename> statements.  
+                Two sets of these exist: one set supports EMGD and one set does not.
+                Because we are not interested in supporting EMGD those three can be deleted.
+                The remaining three must be changed so that <filename>mymachine</filename> replaces
+                <filename>crownbay-noemgd</filename> and <filename>crownbay</filename>.
+                Here is the final <filename>linux-yocto-2.6.37.bbappend</filename> file after all 
+                the edits:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+     COMPATIBLE_MACHINE_mymachine = "mymachine"
+     KMACHINE_mymachine  = "yocto/standard/mymachine"
+     KERNEL_FEATURES_append_mymachine += " cfg/smp.scc"
+
+     SRCREV_machine_pn-linux-yocto_mymachine ?= \
+        "fce17f046d3756045e4dfb49221d1cf60fcae329"
+     SRCREV_meta_pn-linux-yocto_mymachine ?= \
+        "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
+                </literallayout>
+            </para>
+
+            <para>
+                In summary, the edits to the layer’s recipe files result in removal of any files and 
+                statements that do not support your targeted hardware in addition to the inclusion 
+                of any new recipes you might need.  
+                In this example, it was simply a matter of ridding the new layer 
+                <filename>meta-machine</filename> of any code that supported the EMGD features
+                and making sure we were identifying the kernel that supports our example, which
+                is the <filename>atom-pc-standard</filename> kernel.  
+                We did not introduce any new recipes to the layer. 
+            </para>
+
+            <para>
+                Finally, it is also important to update the layer’s <filename>README</filename>
+                file so that the information in it reflects your BSP.
+            </para>
+        </section>
+
+        <section id='preparing-for-the-build-app'>
+            <title>Preparing for the Build</title>
+
+            <para>
+                Once you have made all the changes to your BSP layer there remains a few things 
+                you need to do for the Yocto Project build system in order for it to create your image.  
+                You need to get the build environment ready by sourcing an environment setup script 
+                and you need to be sure two key configuration files are configured appropriately.
+            </para>
+
+            <para>
+                The entire process for building an image is overviewed in the 
+                <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>
+                Building an Image</ulink> section of the Yocto Project Quick Start.    
+                You might want to reference this information.  
+                The remainder of this section will apply to our example of the 
+                <filename>meta-mymachine</filename> layer.
+            </para>
+
+            <para>
+                To get ready to build your image that uses the new layer you need to do the following:
+               <orderedlist>
+                   <listitem><para>Get the environment ready for the build by sourcing the environment 
+                       script. 
+                       The environment script is in the top-level of the local Yocto Project files
+                       directory structure.
+                       The script has the string 
+                       <filename>init-build-env</filename> in the file’s name.  
+                       For this example, the following command gets the build environment ready:                       
+                       <literallayout class='monospaced'>
+     $ source oe-init-build-env yocto-build
+                       </literallayout>
+                       When you source the script a build directory is created in the current 
+                       working directory.  
+                       In our example we were in the <filename>poky</filename> directory.  
+                       Thus, entering the previous command created the <filename>yocto-build</filename> directory.  
+                       If you do not provide a name for the build directory it defaults to 
+                       <filename>build</filename>.  
+                       The <filename>yocot-build</filename> directory contains a 
+                       <filename>conf</filename> directory that has 
+                       two configuration files you will need to check:  <filename>bblayers.conf</filename>
+                       and <filename>local.conf</filename>.</para></listitem>
+                   <listitem><para>Check and edit the resulting <filename>local.conf</filename> file.
+                       This file minimally identifies the machine for which to build the image by 
+                       configuring the <filename>MACHINE</filename> variable.  
+                       For this example you must set the variable to mymachine as follows:
+                       <literallayout class='monospaced'>
+     MACHINE ??= “mymachine”
+                       </literallayout>
+                       You should also be sure any other variables in which you are interested are set.  
+                       Some variables to consider are <filename>BB_NUMBER_THREADS</filename>
+                       and <filename>PARALLEL_MAKE</filename>, both of which can greatly reduce your build time 
+                       if you are using a multi-threaded development system (e.g. values of 
+                       <filename>8</filename> and <filename>j 6</filename>, respectively are optimal 
+                       for a development machine that has four available cores).</para></listitem>
+                   <listitem><para>Update the <filename>bblayers.conf</filename> file so that it includes 
+                       the path to your new BSP layer.  
+                       In this example you need to include the pathname to <filename>meta-mymachine</filename>.
+                       For this example the 
+                       <filename>BBLAYERS</filename> variable in the file would need to include the following path:
+                       <literallayout class='monospaced'>
+     $HOME/poky/meta-intel/meta-mymachine
+                       </literallayout></para></listitem>
+               </orderedlist>
+            </para>
+
+            <para>
+                The appendix 
+                <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-variables-glos'>
+                Reference: Variables Glossary</ulink> in the Yocto Project Reference Manual has more information 
+                on configuration variables.
+            </para>
+        </section>
+
+        <section id='building-the-image-app'>
+            <title>Building the Image</title>
+
+            <para>
+                The Yocto Project uses the BitBake tool to build images based on the type of image 
+                you want to create.  
+                You can find more information on BitBake 
+                <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.  
+            </para>
+
+            <para>
+                The build process supports several types of images to satisfy different needs.  
+                When you issue the BitBake command you provide a “top-level” recipe that essentially 
+                starts the process off of building the type of image you want.  
+            </para>
+
+            <para>
+                [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]
+            </para>
+
+            <para>
+                You can find these recipes in the <filename>meta/recipes-core/images</filename> and 
+                <filename>meta/recipes-sato/images</filename> directories of your local Yocto Project 
+                file structure (Git repository or extracted release tarball).  
+                Although the recipe names are somewhat explanatory, here is a list that describes them:
+                <itemizedlist>
+                    <listitem><para><emphasis>Base</emphasis> – A foundational basic image without support 
+                        for X that can be reasonably used for customization.</para></listitem>
+                    <listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for 
+                        X that can be reasonably used for customization.</para></listitem>
+                    <listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to 
+                        the disk of the target device.</para></listitem>
+                    <listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from 
+                        a CD without having to first install something.</para></listitem>
+                    <listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI.  
+                        This image is not much more than a kernel with a shell.</para></listitem>
+                    <listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for 
+                        development work.</para></listitem>
+                    <listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct Disk image.</para></listitem>
+                    <listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> – A minimal image 
+                        that has the <filename>initramfs</filename> as part of the kernel, which allows the 
+                        system to find the first “init” program more efficiently.</para></listitem>
+                    <listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem>
+                    <listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support 
+                        for the MTD utilities, which let the user interact with the MTD subsystem in 
+                        the kernel to perform operations on flash devices.</para></listitem>
+                    <listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment 
+                        and visual style that works well with mobile devices.</para></listitem>
+                    <listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for 
+                        development work.</para></listitem>
+                    <listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct Disk image.</para></listitem>
+                    <listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem>
+                    <listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project 
+                        toolchain and development libraries.</para></listitem>
+                    <listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct 
+                        Disk image.</para></listitem>
+                    <listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live image.</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                The remainder of this section applies to our example of the <filename>meta-mymachine</filename> layer.
+            </para>
+
+            <para>
+                To build the image for our <filename>meta-mymachine</filename> BSP enter the following command 
+                from the same shell from which you ran the setup script.  
+                You should run the <filename>bitbake</filename> command without any intervening shell commands.  
+                For example, moving your working directory around could cause problems.  
+                Here is the command for this example:
+                <literallayout class='monospaced'>
+     $ bitbake –k core-image-sato-live
+                </literallayout>
+            </para>
+
+            <para>
+                This command specifies an image that has Sato support and that can be run from a USB device or 
+                from a CD without having to first install anything.  
+                The build process takes significant time and includes thousands of tasks, which are reported 
+                at the console.  
+                If the build results in any type of error you should check for misspellings in the 
+                files you changed or problems with your host development environment such as missing packages.
+            </para>
+        </section>
+    </section>
+
+    <section id='modifying-a-kernel-kernel-example-app'>
+        <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-app'>
+            <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-app'>
+            <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-app'>
+                <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-app'>"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-app'>
+                <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-app'>
+                <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-app'>
+                <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>
+
+</appendix>
+
+
+                
+            
+
+<!--
+
+
+            <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
+-->