documentation/kernel-manual/kernel-how-to.xml: Updated the create BSP section

This section has been re-written to just include high-level overview of the
steps.  The detailed example that used to be the section is not needed as
there is adequate documentation of this process in the Yocto Project
Development Manual and on the wiki courtesy of Tom Zanussi.

(From yocto-docs rev: 7355734a5ed965401027ba23bfb15fd926a171f7)

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

1 files changed, 49 insertions, 228 deletions

diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
index 8ef9793c60..bce2c2ce44 100644
--- a/documentation/kernel-manual/kernel-how-to.xml
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -1010,240 +1010,60 @@ That's it. Configure and build.
             <title>Creating a BSP Based on an Existing Similar BSP</title>
 
             <para>
-                This section provides an example for creating a BSP that is based on an existing, and hopefully, 
-                similar one.  
-                The example assumes you will be using a local kernel repository and you will be pointing the 
-                kernel recipes at that repository.  
-                Follow the steps in this section and keep in mind your particular situation and differences.
+                This section overviews the process of creating a BSP based on an 
+                existing similar BSP.
+                The information is introductory in nature and does not provide step-by-step examples. 
+                For detailed information on how to create a BSP given an existing similar BSP
+                see the Yocto Project Development Manual [NEED LINK] or the 
+                <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'></ulink>
+                wiki page.
             </para>
 
-
             <para>
-                If you are interested in a more detailed example with complete transcripts showing how to 
-                create a BSP that is based on an existing similar BSP, see the information on the wiki 
-                page at <ulink url='https://wiki.yoctoproject.org/wiki/BKM:_starting_a_new_BSP'></ulink>.
+                The basic steps you need to follow are:
+                <orderedlist>
+                    <listitem><para>Make sure you have the Yocto Project source tree available.
+                        You should either create a Yocto Project Git repository (recommended), or 
+                        you should get the Yocto Project release tarball and extract it.</para></listitem>
+                    <listitem><para>Choose an existing BSP available with the Yocto Project.
+                        Try to map your board features as closely to the features of a BSP that is  
+                        already supported and exists in the Yocto Project.  
+                        Starting with something as close as possible to your board makes developing 
+                        your BSP easier.  
+                        You can find all the BSPs that are supported and ship with the Yocto Project 
+                        on the Yocto Project's Download page at 
+                        <ulink url='http://www.yoctoproject.org/download'></ulink>.</para></listitem>
+                    <listitem><para>Be sure you have the Base BSP.
+                        You need to either have the Yocto Project Git repository set up or download
+                        the tarball of the base BSP.
+                        Either method gives you access to the BSP source files.</para></listitem>
+                    <listitem><para>Make a copy of the existing BSP, thus isolating your new BSP work.
+                        Copying the existing BSP structure gives you a new area in which to work.</para></listitem>
+                    <listitem><para>Make configuration and recipe changes to your new BSP.
+                        Configuration changes involve the files in the BSP's <filename>conf</filename>
+                        directory. 
+                        Changes include creating a machine-specific configuration file and editing the 
+                        <filename>layer.conf</filename> file.  
+                        The configuration changes identify the kernel you will be using.
+                        Recipe changes include removing, modifying, or adding new recipe files that 
+                        instruct the build process on what features to include in the image.</para></listitem>
+                    <listitem><para>Prepare for the build.
+                        Before you actually initiate the build you need to set up the build environment
+                        by sourcing the environment initialization script.  
+                        After setting up the environment you need to make some build configuration 
+                        changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
+                        files.</para></listitem>
+                    <listitem><para>Build the image.
+                        The Yocto Project uses the BitBake tool to create the image. 
+                        You need to decide on the type of image you are going to build (e.g. minimal, base, 
+                        core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
+                        command.</para></listitem>
+                </orderedlist>
             </para>
-
-            <orderedlist>
-                <listitem><para>
-                    Identify a machine configuration file that matches your machine.
-                </para>
-                
-                <para>
-                    You can start with a machine configuration file in the Yocto Project source tree
-                    such as the <filename>atom-pc.conf</filename> in <filename>meta-yocto/conf/machine</filename>.
-                    Or, you can start with a machine configuration file from a BSP layer
-                    such as <filename>emenlow.conf</filename> in <filename>meta-emenlow/conf/machine</filename>.
-                </para>
-                
-                <para>
-                    The main difference between these two BSP machine configuration files is that "emenlow" is 
-                    in its own isolated BSP layer, while "atom-pc" is in a more encompassing layer 
-                    named <filename>meta-yocto</filename> that is part of the Yocto Project source tree.
-                    The "emenlow" configuration is in its own BSP layer because the target hardware
-                    needs extra machine-specific packages to support graphics and other features.  
-                    The "atom-pc" configuration file supports more basic hardware that does not need any 
-                    special packages - everything the hardware needs can be specified in the configuration file.  
-                    The "atom-pc" machine also supports all of Asus eee901, Acer Aspire One, Toshiba NB305, 
-                    and the Intel&reg; Embedded Development Board 1-N450 with no changes.
-                </para>
-  
-                <para>
-                    If you want to make minor changes to support a slightly different machine, you can
-                    create a new configuration file for the new machine and add it alongside the 
-                    configuration files.
-                    You might consider keeping common configurations for several machines in a separate file 
-                    and then including the other configuration files that have more specific configurations.
-                </para>
-                
-                <para>
-                    Similarly, you can also use multiple configuration files for different machines even 
-                    when the configuration files come from a separate and different layer.
-                </para>
- 
-                <para>
-                    As an example consider this:
-                    <orderedlist>
-                        <listitem><para>Copy the "emenlow" BSP layer to a new BSP layer named 
-                        <filename>meta-mymachine</filename>.
-                        Now you have two identical BSP layers &dash; but with different names.</para></listitem>
-                        <listitem><para>This example assumes the hardware for your new BSP is very similar to 
-                        the hardware used for <filename>meta-emenlow</filename>.
-                        And, you only need to change some machine configurations and inform the Yocto Project build 
-                        process of the new layer.
-                        Consequently, you just need to modify some files in the the new layer so that the Yocto Project
-                        build process uses the recipes and configurations in the new layer.
-                        Since you are basing your new layer on a copied existing layer you need to be sure to rename 
-                        any directories named "emenlow" to "mymachine".
-                        There is one in the <filename>recipes-bsp</filename> directory and one in the 
-                        <filename>recipes-graphics</filename> directory.</para></listitem>.
-                        <listitem><para>In the <filename>recipes-graphics</filename> directory make sure you locate and
-                        change all occurences of "emenlow" to "mymachine". 
-                        Several instances exist.</para></listitem>                       
-                        <listitem><para>Rename the <filename>emenlow.conf</filename> file to <filename>mymachine.conf</filename>
-                        and fix or remove any configurations.
-                        You need to be sure that "mymachine" replaces "emenlow".
-                        Note also that "linux-yocto" is the kernel specified in the configuration file.</para></listitem>
-                        <listitem><para>Make sure the Yocto Project build process knows about the new BSP
-                        layer by adding the pathname to the new layer to the <filename>bblayers.conf</filename> configuration
-                        file located in the Yocto Project build tree at <filename>build/conf/bblayers.conf</filename>. 
-                        Adding the layer allows BitBake to find the new layer.
-
-                        <note>
-                            The above example creates a BSP layer named <filename>meta-mymachine</filename> that is 
-                            functionally identical to the BSP layer on which it was based - <filename>meta-emenlow</filename>.
-                            In a real-world scenario you would need to differentiate features and configurations to enable 
-                            your "similar" BSP layer to work on your target hardware.
-                        </note></para></listitem>
-                    </orderedlist>
-                </para></listitem>
-
-                <listitem><para>
-                    Create a machine branch for your machine in a the Yocto Project Git repository.
-                </para>
-
-                <para>
-                    For the kernel to compile successfully, you need to create a branch in the 
-                    Yocto Project Git repository that is specifically named for your machine.  
-                    To create this branch, first create a bare clone of the Yocto Project Git repository.
-                    Then, create a local clone of that bare clone.
-                    Here are the commands:
-                    <literallayout class='monospaced'>
-     $ git clone &dash;&dash;bare git://git.yoctoproject.org/linux-yocto-2.6.37.git linux-yocto-2.6.37.git
-     $ git clone linux-yocto-2.6.37.git linux-yocto-2.6.37
-                    </literallayout>
-                </para>
-                
-                <para>
-                    Now be sure you are in the local clone and create a branch and push it to the bare clone:
-                    <literallayout class='monospaced'>
-     $ git checkout -b yocto/standard/mymachine origin/yocto/standard/base
-     $ git push origin yocto/standard/mymachine:yocto/standard/mymachine
-                    </literallayout>
-                </para></listitem>
-               
-                <listitem><para>
-                    In your new layer you need to edit the <filename>linux-yocto_git.bbappend</filename> 
-                    file so that the compatible machine is "mymachine". 
-                    It is also convenient to point to a cloned Yocto Project Git repository that is local 
-                    to your system for development purposes.
-                    Thus, change the <filename>linux-yocto_git.bbappend</filename> file in your 
-                    <filename>meta-mymachine</filename> layer to the following:
-                </para>       
-                
-                <para>
-                    <literallayout class='monospaced'>
-     FILESEXTRAPATHS := "${THISDIR}/${PN}"
-     COMPATIBLE_MACHINE_mymachine = "mymachine"
-
-     # It is often nice to have a clone of the kernel repository, to
-     # allow patches to be staged, branches created, and so forth.  Modify
-     # KSRC to point to your bare clone as appropriate.
-
-     KSRC ?= $MYWORK/linux-yocto-2.6.37.git
-
-     # KMACHINE is the branch to be built, or alternatively 
-     # KBRANCH can be directly set.
-     # KBRANCH is set to KMACHINE in the main linux-yocto_git.bb
-     # KBRANCH ?= "${LINUX_KERNEL_TYPE}/${KMACHINE}"
-
-     KMACHINE_mymachine  = "yocto/standard/mymachine"
-
-     SRC_URI = "git://${KSRC};nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
-                    </literallayout>
-                </para>
-
-                <para>
-                    After updating the <filename>linux-yocto_git.bbappend</filename> file,
-                    edit the <filename>build/conf/local.conf</filename> found
-                    in the Yocto Project build tree so that it selects your machine:
-                    <literallayout class='monospaced'>
-      #
-      MACHINE ?= "mymachine"
-      #
-                    </literallayout>
-                </para>
-               
-                <para>
-                    You should now be able to build and boot an image with the new kernel:
-                    <literallayout class='monospaced'>
-     $ bitbake -k core-image-sato-live
-                    </literallayout>
-                </para></listitem>
-
-                <listitem><para>
-                    Modify the kernel configuration for your machine.
-                </para>
-                
-                <para>
-                    At this point you will build a kernel with the default configuration file, which is probably 
-                    not what you want.
-                    If you just want to set some kernel configuration options, you can do that by 
-                    putting them in a file.
-                    For example, inserting the following into some <filename>.cfg</filename> file:
-                    <literallayout class='monospaced'>
-     CONFIG_NETDEV_1000=y
-     CONFIG_E1000E=y
-                    </literallayout>
-                </para>
-                
-                <para>
-                    And, another <filename>.cfg</filename> file would contain:
-                    <literallayout class='monospaced'>
-     CONFIG_LOG_BUF_SHIFT=18
-                    </literallayout>
-                </para>
-
-                <para>
-                    These configuration fragments could then be picked up and
-                    applied to the kernel .config by appending them to the kernel SRC_URI:
-                    <literallayout class='monospaced'>
-     SRC_URI_append_mymachine = " file://some.cfg \
-                                  file://other.cfg \
-                               "
-                    </literallayout>
-                </para>
-                
-                <para>
-                    You could also add these directly to the git repository <filename>meta</filename>
-                    branch as well.
-                    However, the former method is a simple starting point.
-                </para></listitem>
-                
-                <listitem><para>
-                    If you're also adding patches to the kernel, you can do the same thing.
-                    Put your patches in the SRC_URI as well (plus <filename>.cfg</filename> for their kernel 
-                    configuration options if needed).
-                </para>
-                
-                <para>
-                    Practically speaking, to generate the patches, you'd go to the source in the build tree:
-                    <literallayout class='monospaced'>
-     build/tmp/work/mymachine-poky-linux/linux-yocto-2.6.37+Git0+d1cd5c80ee97e81e130be8c3de3965b770f320d6_0+
-0431115c9d720fee5bb105f6a7411efb4f851d26-r13/linux
-                    </literallayout>
-                </para>
-                
-                <para>
-                    Then, modify the code there, using quilt to save the changes, and recompile until 
-                    it works:
-                    <literallayout class='monospaced'>
-     $ bitbake -c compile -f linux-yocto
-                    </literallayout>
-                </para></listitem>
-                
-                <listitem><para>
-                    Once you have the final patch from quilt, copy it to the 
-                    SRC_URI location.
-                    The patch is applied the next time you do a clean build.
-                    Of course, since you have a branch for the BSP in Git, it would be better to put it there instead.
-                    For example, in this case, commit the patch to the "yocto/standard/mymachine" branch, and during the 
-                    next build it is applied from there.
-                </para></listitem>
-            </orderedlist> 
         </section>
 
 
+<!--
         <section id='bsp-creating-bsp-without-a-local-kernel-repo'>
         <title>Creating a BSP Based on an Existing Similar BSP Without a Local Kernel Repository</title>
 
@@ -1276,7 +1096,8 @@ That's it. Configure and build.
         </section>
 
 
-<!--        <section id='bsp-creating-a-new-bsp'>
+
+        <section id='bsp-creating-a-new-bsp'>
             <title>BSP: Creating a New BSP</title>
 <para>
 Although it is obvious that the structure of a new BSP uses the migrated