documentation/dev-manual/dev-manual-model.xml: Edits to Modifying Kernel

Complete re-write of this section based on feedback from Dave Stewart.
Dave's comments centered around not being able to understand the overall
concepts of the Git repositories, the source areas on the host, etc.
I have added several illustrations and written around them to try and
better explain the kernel storage system in Git used by YP and how
that tranlates into host-resident code that the developer ultimately
uses and the Poky build system uses for the build.

(From yocto-docs rev: 4e37f68f77261f6519426fb81ba407c456f8d1a1)

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

1 files changed, 118 insertions, 44 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 2dfc46e..813c96e 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -172,9 +172,9 @@
         <para>
             You can view a video presentation on "Building Custom Embedded Images with Yocto"
             at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.  
-            You can also find supplemental information in the 
+            You can also find supplemental information in  
             <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
-            Board Support Package (BSP) Development Guide</ulink>.
+            The 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.
@@ -195,9 +195,9 @@
         <para>
             The remainder of this section presents a high-level overview of the Linux Yocto 
             kernel architecture and the steps to modify the Linux Yocto kernel.
-            For a complete discussion of the kernel, see the 
+            For a complete discussion of the kernel, see  
             <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
-            Yocto Project Kernel Architecture and Use Manual</ulink>.
+            The Yocto Project Kernel Architecture and Use Manual</ulink>.
             You can reference <xref linkend='dev-manual-kernel-appendix'>Kernel Modification Example</xref>
             for a detailed example that changes the configuration of a kernel.
         </para>
@@ -208,32 +208,120 @@
             <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
+                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.
+                You can find a web interface to the Linux Yocto kernel source repositories at
+                <ulink url='http://git.yoctoproject.org/'></ulink>.
+                If you look at the interface, you will see to the left a grouping of 
+                Git repositories titled "Yocto Linux Kernel."  
+                Within this group, you will find the four different kernels supported by 
+                the Yocto Project:
+                <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
+                    stable Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
+                    <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The current
+                    Linux Yocto kernel that is based on the Linux 3.0 release.</para></listitem>
+                    <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
+                    kernel based on the latest upstream release candidate available.</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                The kernels are maintained using the Git application that, in a sense, structures
+                them in a "tree" complete with branches and leaves.
+                Branches represent diversions from general code to more specific code, while leaves
+                represent the end-points for a complete and unique kernel whose source files 
+                when gathered from the root of the tree to the leaf accumulate to create the files
+                necessary for a specific piece of hardware and its features.
+                The following figure displays this concept:
+            <para>
+                <imagedata fileref="figures/kernel-overview-1.png" 
+                    width="6in" depth="6in" align="center" scale="100" />
+            </para> 
+
+            <para>
+                Within the figure, the "Kernel.org Branch Point" represents the point in the tree
+                where a supported base kernel diverges from the Linux kernel.
+                For example, this could be the branch point for the <filename>linux-yocto-3.0</filename>
+                kernel.
+                Thus, everything further to the right in the structure is based on the 
+                <filename>linux-yocto-3.0</filename> kernel.
+                Branch points to right in the figure represent where the 
+                <filename>linux-yocto-3.0</filename> kernel is modified for specific hardware 
+                or types of kernels, such as real-time kernels.
+                Each leaf thus represents the end-point for a kernel designed to run on a specific
+                targeted device.
             </para>
-         
+
             <para>
+                The overall result is a Git-maintained repository from which all the supported
+                Yocto Project kernels can be derived for all the supported Yocto Project devices.
                 A big advantage to this scheme is the sharing of common features by keeping them in 
-                "larger" branches that are further up the tree.  
+                "larger" branches within the tree.  
                 This practice eliminates redundant storage of similar features shared among kernels.
             </para>
 
+            <note>
+                Keep in mind the figure does not take into account all four supported Linux Yocto
+                kernel types, but rather shows a single generic kernel just for conceptual purposes.
+                Also keep in mind that this structure represents the Yocto Project source repositories 
+                that are either pulled from during the build or established on the host development system
+                prior to the build by either cloning a particular kernel's Git repository or by 
+                downloading and unpacking a tarball.
+            </note>
+
+            <para>
+                Storage of all the available kernel source code is one thing, while representing the 
+                code on your host development system is another.  
+                Conceptually, you can think of the Yocto Project kernel source repositories as all the 
+                source files necessary for all the supported kernels. 
+                As a developer, you are just interested in the source files for the kernel on 
+                on which you are working.
+                And, furthermore, you need them available on your host system.
+            </para>
+
             <para>
+                You make kernel source code available on your host development system by using 
+                Git to create a bare clone of the Linux Yocto kernel Git repository 
+                in which you are interested.
+                Then, you use Git again to clone a copy of that bare clone.  
+                This copy represents the directory structure on your host system that is particular
+                to the kernel you want.  
+                These are the files you actually modify to change the kernel.
+                See the <link linkend='local-kernel-files'>Linux Yocto Kernel</link> item earlier
+                in this manual for an example of how to set up the kernel source directory
+                structure on your host system.
+            </para>
+
+            <para>
+                This next figure illustrates how the kernel source files might be arranged on 
+                your host system.
+            </para>
+
+            <para>
+                <imagedata fileref="figures/kernel-overview-3.png" 
+                    width="6in" depth="4in" align="center" scale="100" />
+            </para> 
+
+            <para>
+                In the previous figure, the file structure on the left represents the bare clone 
+                set up to track the Yocto Project kernel Git repository. 
+                The structure on the right represents the copy of the bare clone. 
+                When you make modifcations to the kernel source code, this is the area in which 
+                you work.
+                Once you make corrections, you must use Git to push the committed changes to the 
+                bare clone.
+                The example in <xref linkend='modifying-the-kernel-source-code'>
+                Modifying the Kernel Source Code</xref> provides a detailed example.
+            </para>
+
+            <para>
+                What happens during the build?  
                 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
@@ -241,38 +329,24 @@
                 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>  
-                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 following figure shows the temporary file structure
+                created on your host system when the build occurs. 
+                This build directory contains all the source files used during the build.
             </para>
 
             <para>
-                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
-                    stable Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
-                    <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The current
-                    Linux Yocto kernel that is based on the Linux 3.0 release.</para></listitem>
-                    <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
-                    kernel based on the latest upstream release candidate available.</para></listitem>
-                    <listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on 
-                    minimal Linux mainline tracking.
-                    You can find the <filename>.bbappend</filename> for this kernel in the 
-                    <filename>meta-kernel-dev</filename> Git repository.</para></listitem>
-                </itemizedlist>
-            </para>
+                <imagedata fileref="figures/kernel-overview-2.png" 
+                    width="6in" depth="5in" align="center" scale="100" />
+            </para> 
 
             <para>
-                For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
+                Again, 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>.
+                Also, you can reference 
+                <xref linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source Code</xref>
+                for a detailed example that modifies the kernel.
             </para>
         </section>