documentation/kernel-manual: Added these files so the book could have chapters.

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>

3 files changed, 2326 insertions, 0 deletions

diff --git a/documentation/kernel-manual/kernel-concepts.xml b/documentation/kernel-manual/kernel-concepts.xml
new file mode 100644
index 0000000000..b884f138e0
--- /dev/null
+++ b/documentation/kernel-manual/kernel-concepts.xml
@@ -0,0 +1,315 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id='kernel-concepts'>
+
+<title>Yocto Project Kernel Concepts</title>
+
+<section id='concepts-org'>
+    <title>Introduction</title>
+    <para>
+        This chapter provides conceptual information about the Yocto Project kernel:
+        <itemizedlist>
+            <listitem><para>Kernel Goals</para></listitem>
+            <listitem><para>Yocto Project Kernel Development and Maintenance Overview</para></listitem>
+            <listitem><para>Kernel Architecture</para></listitem>
+            <listitem><para>Kernel Tools</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+    <section id='kernel-goals'>
+        <title>Kernel Goals</title>
+        <para>
+            The complexity of embedded kernel design has increased dramatically. 
+            Whether it is managing multiple implementations of a particular feature or tuning and
+            optimizing board specific features, flexibility and maintainability are key concerns. 
+            The Yocto Project Linux kernel is presented with the embedded
+            developer's needs in mind and has evolved to assist in these key concerns. 
+            For example, prior methods such as applying hundreds of patches to an extracted
+            tarball have been replaced with proven techniques that allow easy inspection,
+            bisection and analysis of changes. 
+            Application of these techniques also creates a platform for performing integration and 
+            collaboration with the thousands of upstream development projects.
+        </para>
+        <para>
+            With all these considerations in mind, the Yocto Project kernel and development team
+            strives to attain these goals:
+        <itemizedlist>
+            <listitem><para>Allow the end user to leverage community best practices to seamlessly 
+            manage the development, build and debug cycles.</para></listitem>
+            <listitem><para>Create a platform for performing integration and collaboration with the 
+            thousands of upstream development projects that exist.</para></listitem>
+            <listitem><para>Provide mechanisms that support many different work flows, front-ends and 
+            management techniques.</para></listitem>
+            <listitem><para>Deliver the most up-to-date kernel possible while still ensuring that 
+            the baseline kernel is the the most stable official release.</para></listitem>
+            <listitem><para>Include major technological features as part of Yocto Project's up-rev 
+            strategy.</para></listitem>
+            <listitem><para>Present a git tree, that just like the upstream kernel.org tree, has a 
+            clear and continuous history.</para></listitem>
+            <listitem><para>Deliver a key set of supported kernel types, where each type is tailored 
+            to a specific use case (i.g. networking, consumer, devices, and so forth).</para></listitem>
+            <listitem><para>Employ a git branching strategy that from a customer's point of view
+            results in a linear path from the baseline kernel.org, through a select group of features and
+            ends with their BSP-specific commits.</para></listitem>
+        </itemizedlist>
+        </para>
+    </section>
+
+    <section id='kernel-big-picture'>
+        <title>Yocto Project Kernel Development and Maintenance Overview</title>
+        <para>
+            Yocto Project kernel, like other kernels, is based off the Linux kernel release
+            from <ulink url='http://www.kernel.org'></ulink>.  
+            At the beginning of our major development cycle, we choose our Yocto Project kernel 
+            based on factors like release timing, the anticipated release timing of "final" (i.e. non "rc")
+            upstream kernel.org versions, and Yocto Project feature requirements.
+            Typically this will be a kernel that is in the
+            final stages of development by the community (i.e. still in the release
+            candidate or "rc" phase) and not yet a final release. 
+            But by being in the final stages of external development, we know that the 
+            kernel.org final release will clearly land within the early stages of 
+            the Yocto Project development window.
+        </para>
+        <para>
+            This balance allows us to deliver the most up-to-date kernel
+            as possible, while still ensuring that we have a stable official release as
+            our baseline kernel version.
+        </para>
+        <para>
+            The following figure represents the overall place the Yocto Project kernel fills.
+        </para>
+        <para>
+        <imagedata fileref="figures/kernel-big-picture.png" width="6in" depth="6in" align="center" scale="100" />
+        </para>
+        <para>
+            In the figure the ultimate source for the Yocto Project kernel is a released kernel 
+            from kernel.org.
+            In addition to a foundational kernel from kernel.org the commercially released 
+            Yocto Project kernel contains a mix of important new mainline
+            developments, non-mainline developments, Board Support Package (BSP) developments,
+            and custom features.
+            These additions result in a commercially released Yocto Project kernel that caters 
+            to specific embedded designer needs for targeted hardware. 
+        </para>
+        <para>
+            Once a Yocto Project kernel is officially released the Yocto Project team goes into 
+            their next development cycle, or "uprev" cycle.
+            It is important to note that the most sustainable and stable way
+            to include feature development upstream is through a kernel uprev process.
+            Back-porting of hundreds of individual fixes and minor features from various
+            kernel versions is not sustainable and can easily compromise quality. 
+            During the uprev cycle, the Yocto Project team uses an ongoing analysis of
+            kernel development, BSP support, and release timing to select the best
+            possible kernel.org version.
+            The team continually monitors community kernel
+            development to look for significant features of interest.
+            The illustration depicts this by showing the team looking back to kernel.org for new features, 
+            BSP features, and significant bug fixes.
+            The team does consider back-porting large features if they have a significant advantage. 
+            User or community demand can also trigger a back-port or creation of new
+            functionality in the Yocto Project baseline kernel during the uprev cycle. 
+        </para>
+        <para>
+            Generally speaking, every new kernel both adds features and introduces new bugs.
+            These consequences are the basic properties of upstream kernel development and are
+            managed by the Yocto Project team's kernel strategy. 
+            It is the Yocto Project team's policy to not back-port minor features to the released kernel. 
+            They only consider back-porting significant technological jumps - and, that is done 
+            after a complete gap analysis. 
+            The reason for this policy is that simply back-porting any small to medium sized change 
+            from an evolving kernel can easily create mismatches, incompatibilities and very 
+            subtle errors.
+        </para>
+        <para>
+            These policies result in both a stable and a cutting
+            edge kernel that mixes forward ports of existing features and significant and critical 
+            new functionality. 
+            Forward porting functionality in the Yocto Project kernel can be thought of as a
+            "micro uprev."
+            The many “micro uprevs” produce a kernel version with a mix of 
+            important new mainline, non-mainline, BSP developments and feature integrations. 
+            This kernel gives insight into new features and allows focused
+            amounts of testing to be done on the kernel, which prevents
+            surprises when selecting the next major uprev. 
+            The quality of these cutting edge kernels is evolving and the kernels are used in very special 
+            cases for BSP and feature development.
+        </para>
+    </section>
+
+    <section id='kernel-architecture'>
+        <title>Kernel Architecture</title>
+        <para>
+            This section describes the architecture of the Yocto Project kernel and provides information
+            on the mechanisms used to achieve that architecture.
+        </para>
+        
+        <section id='architecture-overview'>
+            <title>Overview</title>
+            <para>
+                As mentioned earlier, a key goal of Yocto Project is to present the developer with 
+                a kernel that has a clear and continuous history that is visible to the user. 
+                The architecture and mechanisms used achieve that goal in a manner similar to the 
+                upstream kernel.org.
+                
+            </para>
+            <para>
+                You can think of the Yocto Project kernel as consisting of a baseline kernel with
+                added features logically structured on top of the baseline.
+                The features are tagged and organized by way of a branching strategy implemented by the 
+                source code manager (SCM) git. 
+                The result is that the user has the ability to see the added features and 
+                the commits that make up those features.
+                In addition to being able to see added features, the user can also view the history of what 
+                made up the baseline kernel as well.
+            </para>
+            <para>
+                The following illustration shows the conceptual Yocto Project kernel.
+            </para>
+            <para>
+                <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
+            </para>
+            <para>
+                In the illustration, the "kernel.org Branch Point" marks the specific spot (or release) from 
+                which the Yocto Project kernel is created.  From this point "up" in the tree features and 
+                differences are organized and tagged.
+            </para>
+            <para>
+                The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
+                type and BSP that is organized further up the tree.  Placing these common features in the 
+                tree this way means features don't have to be duplicated along individual branches of the 
+                structure.
+            </para>
+            <para>
+                From the Yocto Project Baseline Kernel branch points represent specific functionality
+                for individual BSPs as well as real-time kernels.
+                The illustration represents this through three BSP-specific branches and a real-time 
+                kernel branch.  
+                Each branch represents some unique functionality for the BSP or a real-time kernel.
+            </para>
+            <para>
+                The real-time kernel branch has common features for all real-time kernels and contains
+                more branches for individual BSP-specific real-time kernels.  
+                The illustration shows three branches as an example. 
+                Each branch points the way to specific, unique features for a respective real-time
+                kernel as they apply to a given BSP.
+            </para>
+            <para>
+                The resulting tree structure presents a clear path of markers (or branches) to the user
+                that for all practical purposes is the kernel needed for any given set of requirements.
+            </para>
+        </section>
+ 
+        <section id='branching-and-workflow'>
+            <title>Branching Strategy and Workflow</title>
+            <para>
+                The Yocto Project team creates kernel branches at points where functionality is 
+                no longer shared and thus, needs to be isolated.
+                For example, board-specific incompatibilities would require different functionality
+                and would require a branch to separate the features. 
+                Likewise, for specific kernel features the same branching strategy is used.
+                This branching strategy results in a tree that has features organized to be specific 
+                for particular functionality, single kernel types, or a subset of kernel types.  
+                This strategy results in not having to store the same feature twice internally in the 
+                tree.
+                Rather we store the unique differences required to apply the feature onto the kernel type 
+                in question.
+            </para>
+            <para>
+                BSP-specific code additions are handled in a similar manner to kernel-specific additions. 
+                Some BSPs only make sense given certain kernel types.
+                So, for these types, we create branches off the end of that kernel type for all 
+                of the BSPs that are supported on that kernel type.  
+                From the perspective of the tools that create the BSP branch, the BSP is really no 
+                different than a feature.
+                Consequently, the same branching strategy applies to BSPs as it does to features.
+                So again, rather than store the BSP twice, only the unique differences for the BSP across
+                the supported multiple kernels are uniquely stored.
+            </para>
+            <para>
+                While this strategy results in a tree with a significant number of branches, it is
+                important to realize that from the customer's point of view, there is a linear
+                path that travels from the baseline kernel.org, through a select group of features and
+                ends with their BSP-specific commits.
+                In other words, the divisions of the kernel are transparent and are not relevant 
+                to the developer on a day-to-day basis.  
+                From the customer's perspective, this is the "master" branch.
+                They do not need not be aware of the existence of any other branches at all.  
+                Of course there is value in the existence of these branches
+                in the tree, should a person decide to explore them. 
+                For example, a comparison between two BSPs at either the commit level or at the line-by-line 
+                code diff level is now a trivial operation.
+            </para>
+            <para>
+                Working with the kernel as a structured tree follows recognized community best practices. 
+                In particular, the kernel as shipped with the product should be
+                considered an 'upstream source' and viewed as a series of
+                historical and documented modifications (commits). 
+                These modifications represent the development and stabilization done
+                by the Yocto Project kernel development team.
+            </para>
+            <para>
+                Because commits only change at significant release points in the product life cycle,
+                developers can work on a branch created
+                from the last relevant commit in the shipped Yocto Project kernel. 
+                As mentioned previously, the structure is transparent to the user
+                because the kernel tree is left in this state after cloning and building the kernel.
+            </para>
+        </section>
+     
+        <section id='source-code-manager-git'>
+            <title>Source Code Manager - git</title>
+            <para>
+                The Source Code Manager (SCM) is git and it is the obvious mechanism for meeting the 
+                previously mentioned goals.  
+                Not only is it the SCM for kernel.org but git continues to grow in popularity and
+                supports many different work flows, front-ends and management techniques.
+            </para>
+            <note><para> 
+                It should be noted that you can use as much, or as little, of what git has to offer 
+                as is appropriate to your project.
+            </para></note>
+        </section>
+    </section>
+
+    <section id='kernel-tools'>
+        <title>Kernel Tools</title>
+        <para>
+Since most standard workflows involve moving forward with an existing tree by
+continuing to add and alter the underlying baseline, the tools that manage
+Yocto Project's kernel construction are largely hidden from the developer to
+present a simplified view of the kernel for ease of use.
+</para>
+<para>
+The fundamental properties of the tools that manage and construct the
+kernel are:
+<itemizedlist>
+    <listitem><para>the ability to group patches into named, reusable features</para></listitem>
+    <listitem><para>to allow top down control of included features</para></listitem>
+    <listitem><para>the binding of kernel configuration to kernel patches/features</para></listitem>
+    <listitem><para>the presentation of a seamless git repository that blends Yocto Project value with the kernel.org history and development</para></listitem>
+</itemizedlist>
+</para>
+<!--<para>
+The tools that construct a kernel tree will be discussed later in this 
+document. The following tools form the foundation of the Yocto Project 
+kernel toolkit:
+<itemizedlist>
+    <listitem><para>git  : distributed revision control system created by Linus Torvalds</para></listitem>
+    <listitem><para>guilt: quilt on top of git</para></listitem>
+    <listitem><para>*cfg : kernel configuration management and classification</para></listitem>
+    <listitem><para>kgit*: Yocto Project kernel tree creation and management tools</para></listitem>
+    <listitem><para>scc  : series &amp; configuration compiler</para></listitem>
+</itemizedlist>
+</para> -->
+    </section> 
+
+
+
+
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-manual/kernel-doc-intro.xml b/documentation/kernel-manual/kernel-doc-intro.xml
new file mode 100644
index 0000000000..c9715d4bff
--- /dev/null
+++ b/documentation/kernel-manual/kernel-doc-intro.xml
@@ -0,0 +1,57 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id='kernel-doc-intro'>
+
+<title>Yocto Project Kernel Architecture and Use Manual</title>
+
+<section id='book-intro'>
+    <title>Introduction</title>
+    <para>
+        Yocto Project presents the kernel as a fully patched, history-clean git
+        repository. 
+        The git tree represents the selected features, board support,
+        and configurations extensively tested by Yocto Project. 
+        The Yocto Project kernel allows the end user to leverage community
+        best practices to seamlessly manage the development, build and debug cycles.
+    </para>
+    <para>
+        This manual describes the Yocto Project kernel by providing information
+        on its history, organization, benefits, and use.
+        The manual consists of two sections:
+        <itemizedlist>
+            <listitem><para>Concepts - Describes concepts behind the kernel.
+                You will understand how the kernel is organized and why it is organized in 
+                the way it is.  You will understand the benefits of the kernel's organization 
+                and the mechanisms used to work with the kernel and how to apply it in your 
+                design process.</para></listitem>
+            <listitem><para>Using the Kernel - Describes best practices and "how-to" information
+                that lets you put the kernel to practical use.  Some examples are "How to Build a 
+                Project Specific Tree", "How to Examine Changes in a Branch", and "Saving Kernel
+                Modifications."</para></listitem>
+        </itemizedlist>
+    </para>
+    <para>
+        For more information on the kernel, see the following links:
+        <itemizedlist>
+            <listitem><para><ulink url='http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process'></ulink></para></listitem>
+            <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem>
+            <listitem><para><ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem> 
+        </itemizedlist>
+        <para> 
+        You can find more information on Yocto Project by visiting the website at
+        <ulink url='http://www.yoctoproject.org'></ulink>.
+        </para>
+    </para>
+</section>
+
+
+
+
+
+
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
new file mode 100644
index 0000000000..7f3eac3d3b
--- /dev/null
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -0,0 +1,1954 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id='kernel-how-to'>
+
+<title>Working with the Yocto Project Kernel</title>
+
+
+<section id='actions-org'>
+    <title>Introduction</title>
+    <para>
+        This chapter describes how to accomplish tasks involving the kernel's tree structure. 
+        The information covers the following:
+        <itemizedlist> 
+            <listitem><para>Tree construction</para></listitem>
+            <listitem><para>Build strategies</para></listitem>
+<!--            <listitem><para>Series &amp; Configuration Compiler</para></listitem> 
+            <listitem><para>kgit</para></listitem> -->
+            <listitem><para>Workflow examples</para></listitem>
+            <listitem><para>Source Code Manager (SCM)</para></listitem>
+<!--            <listitem><para>Board Support Package (BSP) template migration</para></listitem> -->
+            <listitem><para>BSP creation</para></listitem>
+            <listitem><para>Patching</para></listitem>
+            <listitem><para>Updating BSP patches and configuration</para></listitem>
+<!--            <listitem><para>guilt</para></listitem>
+            <listitem><para>scc file example</para></listitem> -->
+            <listitem><para>"dirty" string</para></listitem>
+<!--            <listitem><para>Transition kernel layer</para></listitem> -->
+        </itemizedlist>
+    </para>
+</section>
+
+    <section id='tree-construction'>
+        <title>Tree Construction</title>
+        <para>
+The Yocto Project kernel repository, as shipped with the product, is created by
+compiling and executing the set of feature descriptions for every BSP/feature
+in the product. Those feature descriptions list all necessary patches,
+configuration, branching, tagging and feature divisions found in the kernel.
+</para>
+<para>
+The files used to describe all the valid features and BSPs in the Yocto Project
+kernel can be found in any clone of the kernel git tree. The directory
+wrs/cfg/kernel-cache/ is a snapshot of all the kernel configuration and
+feature descriptions (.scc) that were used to build the kernel repository.
+It should however be noted, that browsing the snapshot of feature
+descriptions and patches is not an effective way to determine what is in a
+particular kernel branch. Using git directly to get insight into the changes
+in a branch is more efficient and a more flexible way to inspect changes to
+the kernel.  Examples of using git to inspect kernel commits are in the
+following sections.
+</para>
+<para>
+As a reminder, it is envisioned that a ground up reconstruction of the
+complete kernel tree is an action only taken by Yocto Project team during an
+active development cycle.  When an end user creates a project, it takes
+advantage of this complete tree in order to efficiently place a git tree
+within their project.
+</para>
+<para>
+The general flow of the project specific kernel tree construction is as follows:
+<orderedlist>
+    <listitem><para>a top level kernel feature is passed to the kernel build subsystem,
+     normally this is a BSP for a particular kernel type.</para></listitem>
+
+    <listitem><para>the file that describes the top level feature is located by searching
+     system directories:</para>
+      
+       <itemizedlist>
+            <listitem><para>the kernel-cache under linux/wrs/cfg/kernel-cache</para></listitem>
+<!--            <listitem><para>kernel-*-cache directories in layers</para></listitem> -->
+            <listitem><para>recipe SRC_URIs</para></listitem>
+<!--            <listitem><para>configured and default templates</para></listitem> -->
+        </itemizedlist>
+
+     <para>In a typical build a feature description of the format:
+          &lt;bsp name&gt;-&lt;kernel type&gt;.scc is the target of the search.
+     </para></listitem>
+
+     <listitem><para>once located, the feature description is compiled into a simple script
+     of actions, or an existing equivalent script which was part of the
+     shipped kernel is located.</para></listitem>
+
+     <listitem><para>extra features are appended to the top level feature description. Extra
+     features can come from the KERNEL_FEATURES variable in recipes.</para></listitem>
+
+     <listitem><para>each extra feature is located, compiled and appended to the script from
+     step #3</para></listitem>
+
+     <listitem><para>the script is executed, and a meta-series is produced. The meta-series
+     is  a description of all the branches, tags, patches and configuration that
+     need to be applied to the base git repository to completely create the
+     "bsp_name-kernel_type".</para></listitem>
+
+     <listitem><para>the base repository is cloned, and the actions
+     listed in the meta-series are applied to the tree.</para></listitem>
+
+     <listitem><para>the git repository is left with the desired branch checked out and any
+     required branching, patching and tagging has been performed.</para></listitem>
+</orderedlist>
+</para>
+
+<para>
+The tree is now ready for configuration and compilation. Those two topics will
+be covered below.
+</para>
+
+<note><para>The end user generated meta-series adds to the kernel as shipped with
+      the Yocto Project release. Any add-ons and configuration data are applied
+      to the end of an existing branch. The full repository generation that
+      is found in the linux-2.6-windriver.git is the combination of all
+      supported boards and configurations.
+</para></note>
+
+<para>
+This technique is flexible and allows the seamless blending of an immutable
+history with additional deployment specific patches. Any additions to the
+kernel become an integrated part of the branches.
+</para>
+
+<!-- <note><para>It is key that feature descriptions indicate if any branches are
+      required, since the build system cannot automatically decide where a
+      BSP should branch or if that branch point needs a name with
+      significance. There is a single restriction enforced by the compilation
+      phase:
+    </para>
+    <para>A BSP must create a branch of the format &lt;bsp name&gt;-&lt;kernel type&gt;.</para>
+
+    <para>This means that all merged/support BSPs must indicate where to start
+      its branch from, with the right name, in its .scc files. The scc
+      section describes the available branching commands in more detail.
+    </para>
+</note> -->
+
+<para>
+A summary of end user tree construction activities follow:
+<itemizedlist>
+    <listitem><para>compile and link a full top-down kernel description from feature descriptions</para></listitem>
+    <listitem><para>execute the complete description to generate a meta-series</para></listitem>
+    <listitem><para>interpret the meta-series to create a customized git repository for the
+    board</para></listitem>
+    <listitem><para>migrate configuration fragments and configure the kernel</para></listitem>
+    <listitem><para>checkout the BSP branch and build</para></listitem>
+</itemizedlist>
+</para>
+    </section>
+
+    <section id='build-strategy'>
+        <title>Build Strategy</title>
+<para>
+There are some prerequisites that must be met before starting the compilation
+phase of the kernel build system:
+</para>
+<itemizedlist>
+    <listitem><para>There must be a kernel git repository indicated in the SRC_URI.</para></listitem>
+    <listitem><para>There must be a branch &lt;bsp name&gt;-&lt;kernel type&gt;.</para></listitem>
+</itemizedlist>
+
+<para>
+These are typically met by running tree construction/patching phase of the
+build system, but can be achieved by other means. Examples of alternate work
+flows such as bootstrapping a BSP are provided below.
+</para>
+<para>
+Before building a kernel it is configured by processing all of the
+configuration "fragments" specified by the scc feature descriptions. As the
+features are compiled, associated kernel configuration fragments are noted
+and recorded in the meta-series in their compilation order. The 
+fragments are migrated, pre-processed and passed to the Linux Kernel
+Configuration subsystem (lkc) as raw input in the form of a .config file.
+The lkc uses its own internal dependency constraints to do the final
+processing of that information and generates the final .config that will
+be used during compilation.
+</para>
+<para>
+Kernel compilation is started, using the board's architecture and other
+relevant values from the board template, and a kernel image is produced.
+</para>
+<para>
+The other thing that you will first see once you configure a kernel is that
+it will generate a build tree that is separate from your git source tree.
+This build dir will be called "linux-&lt;BSPname&gt;-&lt;kerntype&gt;-build" where
+kerntype is one of standard kernel types.  This functionality is done by making
+use of the existing support that is within the kernel.org tree by default.
+</para>
+<para>
+What this means, is that all the generated files (that includes the final
+".config" itself, all ".o" and ".a" etc) are now in this directory.  Since
+the git source tree can contain any number of BSPs, all on their own branch,
+you now can easily switch between builds of BSPs as well, since each one also
+has their own separate build directory.
+</para>
+    </section>
+
+<!--    <section id='scc'>
+        <title>Series &amp; Configuration Compiler (SCC)</title>
+<para>
+In early versions of the product, kernel patches were simply listed in a flat
+file called "patches.list", and then quilt was added as a tool to help
+traverse this list, which in quilt terms was called a "series" file.
+</para>
+<para>
+Before the 2.0 release, it was already apparent that a static series file was
+too inflexible, and that the series file had to become more dynamic and rely
+on certain state (like kernel type) in order to determine whether a patch was
+to be used or not.  The 2.0 release already made use of some stateful
+construction of series files, but since the delivery mechanism was unchanged
+(tar + patches + series files), most people were not aware of anything really
+different.  The 3.0 release continues with this stateful construction of
+series files, but since the delivery mechanism is changed (git + branches) it
+now is more apparent to people.
+</para>
+<para>
+As was previously mentioned, scc is a "series and configuration
+compiler". Its role is to combine feature descriptions into a format that can
+be used to generate a meta-series. A meta series contains all the required
+information to construct a complete set of branches that are required to
+build a desired board and feature set. The meta series is interpreted by the
+kgit tools to create a git repository that could be built.
+</para>
+<para>
+To illustrate how scc works, a feature description must first be understood.
+A feature description is simply a small bash shell script that is executed by
+scc in a controlled environment. Each feature description describes a set of
+operations that add patches, modify existing patches or configure the
+kernel. It is key that feature descriptions can include other features, and
+hence allow the division of patches and configuration into named, reusable
+containers.
+</para>
+<para>
+Each feature description can use any of the following valid scc commands:
+<itemizedlist>
+    <listitem><para>shell constructs: bash conditionals and other utilities can be used in a feature
+    description. During compilation, the working directory is the feature
+    description itself, so any command that is "raw shell" and not from the
+    list of supported commands, can not directly modify a git repository.</para></listitem>
+
+    <listitem><para>patch &lt;relative path&gt;/&lt;patch name&gt;: outputs a patch to be included in a feature's patch set. Only the name of
+    the patch is supplied, the path is calculated from the currently set
+    patch directory, which is normally the feature directory itself.</para></listitem>
+
+    <listitem><para>patch_trigger &gt;condition&lt; &gt;action&lt; &lt;tgt&gt;: indicate that a trigger should be set to perform an action on a 
+    patch.</para>
+
+<para>The conditions can be:
+
+         <itemizedlist>
+             <listitem><para>arch:&lt;comma separated arch list or "all"&gt;</para></listitem>
+             <listitem><para>plat:&lt;comma separated platform list or "all"&gt;</para></listitem>
+         </itemizedlist></para>
+<para>The action can be:
+         <itemizedlist>
+             <listitem><para>exclude: This is used in exceptional situations where a patch
+                         cannot be applied for certain reasons (arch or platform).
+                         When the trigger is satisfied the patch will be removed from
+                         the patch list.</para></listitem>
+             <listitem><para>include: This is used to include a patch only for a specific trigger.
+                         Like exclude, this should only be used when necessary.
+                         It takes 1 argument, the patch to include.</para></listitem>
+         </itemizedlist></para></listitem>
+
+         <listitem><para>include &lt;feature name&gt; [after &lt;feature&gt;]: includes a feature for processing. The feature is "expanded" at the
+    position of the include directive. This means that any patches,
+    configuration or sub-includes of the feature will appear in the final
+    series before the commands that follow the include.</para>
+    <para>
+    include searches the include directories for a matching feature name,
+    include directories are passed to scc by the caller using -I &lt;path&gt; and
+    is transparent to the feature script. This means that &lt;feature name&gt; must
+    be relative to one of the search paths. For example, if
+    /opt/kernel-cache/feat/sched.scc is to be included and scc is invoked
+    with -I /opt/kernel-cache, then a feature would issue "include
+    feat/sched.scc" to include the feature.
+</para>
+<para>
+    The optional "after" directive allows a feature to modify the existing
+    order of includes and insert a feature after the named feature is
+    processed. Note: the "include foo after bar" must be issued before "bar"
+    is processed, so is normally only used by a new top level feature to
+    modify the order of features in something it is including.</para></listitem>
+
+  <listitem><para>exclude &lt;feature name&gt;: Indicates that a particular feature should *not* be included even if an
+    'include' directive is found. The exclude must be issued before the
+    include is processed, so is normally only used by a new top level feature
+    to modify the order of features in something it is including.</para></listitem>
+
+  <listitem><para>git &lt;command&gt;: Issues any git command during tree construction. Note: this command is
+    not validated/sanitized so care must be taken to not damage the
+    tree. This can be used to script branching, tagging, pulls or other git
+    operations.</para></listitem>
+
+  <listitem><para>dir &lt;directory&gt;: changes the working directory for "patch" directives. This can be used to
+    shorten a long sequence of patches by not requiring a common relative
+    directory to be issued each time.</para></listitem>
+
+  <listitem><para>kconf &lt;type&gt; &lt;fragment name&gt;: associates a kernel config frag with the feature. 
+     &lt;type&gt; can be
+    "hardware" or "non-hardware" and is used by the kernel configuration
+    subsystem to audit configuration. &lt;fragment name&gt; is the name of a file
+    in the current feature directory that contains a series of kernel
+    configuration options.  There is no restriction on the chosen fragment
+    name, although a suffix of ".cfg" is recommended.  Multiple fragment
+    specifications are supported.</para></listitem>
+
+  <listitem><para>br