3 files changed, 166 insertions, 1 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index 2ee97f48c6..55efb44bf4 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -289,7 +289,8 @@ XSLTOPTS = --stringparam html.stylesheet kernel-dev-style.css \
           --stringparam  section.label.includes.component.label 1 \
           --xinclude
 ALLPREQ = html pdf tarball
-TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png
+TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png \
+           figures/kernel-architecture-overview.png
 MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf
 FIGURES = figures
 STYLESHEET = $(DOC)/*.css
diff --git a/documentation/kernel-dev/figures/kernel-architecture-overview.png b/documentation/kernel-dev/figures/kernel-architecture-overview.png
new file mode 100755
index 0000000000..2aad172db3
--- /dev/null
+++ b/documentation/kernel-dev/figures/kernel-architecture-overview.png
Binary files differ
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index d78d2dc86c..732c0c310a 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -83,6 +83,170 @@
            feature and BSP development.
        </para>
    </section>
+    <section id='kernel-architecture'>
+        <title>Kernel Architecture</title>
+        <para>
+            This section describes the architecture of the kernels available through the
+            Yocto Project 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 the 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 <filename>kernel.org</filename>.
+            </para>
+            <para>
+                You can think of a Yocto Project kernel as consisting of a baseline Linux 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.
+                For information on Git as applied to the Yocto Project, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
+                Yocto Project Development Manual.
+            </para>
+            <para>
+                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.
+            </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>
+                In this example structure, 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
+                developer 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.
+            </para>
+            <para>
+                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 also results in not having to store the same feature twice
+                internally in the tree.
+                Rather, the kernel team stores the unique differences required to apply the
+                feature onto the kernel type in question.
+                <note>
+                    The Yocto Project team strives to place features in the tree such that they can be
+                    shared by all boards and kernel types where possible.
+                    However, during development cycles or when large features are merged,
+                    the team cannot always follow this practice.
+                    In those cases, the team uses isolated branches to merge features.
+                </note>
+            </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, the team creates 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, the team only stores the unique
+                differences for the BSP across the supported multiple kernels.
+            </para>
+            <para>
+                While this strategy can result in a tree with a significant number of branches, it is
+                important to realize that from the developer's point of view, there is a linear
+                path that travels from the baseline <filename>kernel.org</filename>, 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 developer's perspective, this path is the "master" branch.
+                The developer does not need to 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 <filename>diff</filename> 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 developer
+                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.
+                This SCM is the obvious mechanism for meeting the previously mentioned goals.
+                Not only is it the SCM for <filename>kernel.org</filename> but,
+                Git continues to grow in popularity and supports many different work flows,
+                front-ends and management techniques.
+            </para>
+            <para>
+                You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
+                You can also get an introduction to Git as it applies to the Yocto Project in the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
+                section in the Yocto Project Development Manual.
+                These referenced sections overview Git and describe a minimal set of
+                commands that allows you to be functional using Git.
+                <note>
+                    You can use as much, or as little, of what Git has to offer to accomplish what
+                    you need for your project.
+                    You do not have to be a "Git Master" in order to use it with the Yocto Project.
+                </note>
+            </para>
+        </section>
+    </section>
 </appendix>
 <!--
 vim: expandtab tw=80 ts=4

diff --git a/documentation/Makefile b/documentation/Makefile index 2ee97f48c6..55efb44bf4 100644 --- a/documentation/Makefile +++ b/documentation/Makefile
@@ -289,7 +289,8 @@ XSLTOPTS = --stringparam html.stylesheet kernel-dev-style.css \
289	--stringparam section.label.includes.component.label 1 \	289	--stringparam section.label.includes.component.label 1 \
290	--xinclude	290	--xinclude
291	ALLPREQ = html pdf tarball	291	ALLPREQ = html pdf tarball
292	TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png	292	TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png \
		293	figures/kernel-architecture-overview.png
293	MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf	294	MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf
294	FIGURES = figures	295	FIGURES = figures
295	STYLESHEET = $(DOC)/*.css	296	STYLESHEET = $(DOC)/*.css


diff --git a/documentation/kernel-dev/figures/kernel-architecture-overview.png b/documentation/kernel-dev/figures/kernel-architecture-overview.png new file mode 100755 index 0000000000..2aad172db3 --- /dev/null +++ b/documentation/kernel-dev/figures/kernel-architecture-overview.png
Binary files differ


diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml index d78d2dc86c..732c0c310a 100644 --- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -83,6 +83,170 @@
83	feature and BSP development.	83	feature and BSP development.
84	</para>	84	</para>
85	</section>	85	</section>
		86
		87	<section id='kernel-architecture'>
		88	<title>Kernel Architecture</title>
		89	<para>
		90	This section describes the architecture of the kernels available through the
		91	Yocto Project and provides information
		92	on the mechanisms used to achieve that architecture.
		93	</para>
		94
		95	<section id='architecture-overview'>
		96	<title>Overview</title>
		97	<para>
		98	As mentioned earlier, a key goal of the Yocto Project is to present the
		99	developer with
		100	a kernel that has a clear and continuous history that is visible to the user.
		101	The architecture and mechanisms used achieve that goal in a manner similar to the
		102	upstream <filename>kernel.org</filename>.
		103	</para>
		104	<para>
		105	You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
		106	added features logically structured on top of the baseline.
		107	The features are tagged and organized by way of a branching strategy implemented by the
		108	source code manager (SCM) Git.
		109	For information on Git as applied to the Yocto Project, see the
		110	"<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
		111	Yocto Project Development Manual.
		112	</para>
		113	<para>
		114	The result is that the user has the ability to see the added features and
		115	the commits that make up those features.
		116	In addition to being able to see added features, the user can also view the history of what
		117	made up the baseline kernel.
		118	</para>
		119	<para>
		120	The following illustration shows the conceptual Yocto Project kernel.
		121	</para>
		122	<para>
		123	<imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
		124	</para>
		125	<para>
		126	In the illustration, the "Kernel.org Branch Point"
		127	marks the specific spot (or release) from
		128	which the Yocto Project kernel is created.
		129	From this point "up" in the tree, features and differences are organized and tagged.
		130	</para>
		131	<para>
		132	The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
		133	type and BSP that is organized further up the tree.
		134	Placing these common features in the
		135	tree this way means features don't have to be duplicated along individual branches of the
		136	structure.
		137	</para>
		138	<para>
		139	From the Yocto Project Baseline Kernel, branch points represent specific functionality
		140	for individual BSPs as well as real-time kernels.
		141	The illustration represents this through three BSP-specific branches and a real-time
		142	kernel branch.
		143	Each branch represents some unique functionality for the BSP or a real-time kernel.
		144	</para>
		145	<para>
		146	In this example structure, the real-time kernel branch has common features for all
		147	real-time kernels and contains
		148	more branches for individual BSP-specific real-time kernels.
		149	The illustration shows three branches as an example.
		150	Each branch points the way to specific, unique features for a respective real-time
		151	kernel as they apply to a given BSP.
		152	</para>
		153	<para>
		154	The resulting tree structure presents a clear path of markers (or branches) to the
		155	developer that, for all practical purposes, is the kernel needed for any given set
		156	of requirements.
		157	</para>
		158	</section>
		159
		160	<section id='branching-and-workflow'>
		161	<title>Branching Strategy and Workflow</title>
		162	<para>
		163	The Yocto Project team creates kernel branches at points where functionality is
		164	no longer shared and thus, needs to be isolated.
		165	For example, board-specific incompatibilities would require different functionality
		166	and would require a branch to separate the features.
		167	Likewise, for specific kernel features, the same branching strategy is used.
		168	</para>
		169	<para>
		170	This branching strategy results in a tree that has features organized to be specific
		171	for particular functionality, single kernel types, or a subset of kernel types.
		172	This strategy also results in not having to store the same feature twice
		173	internally in the tree.
		174	Rather, the kernel team stores the unique differences required to apply the
		175	feature onto the kernel type in question.
		176	<note>
		177	The Yocto Project team strives to place features in the tree such that they can be
		178	shared by all boards and kernel types where possible.
		179	However, during development cycles or when large features are merged,
		180	the team cannot always follow this practice.
		181	In those cases, the team uses isolated branches to merge features.
		182	</note>
		183	</para>
		184	<para>
		185	BSP-specific code additions are handled in a similar manner to kernel-specific additions.
		186	Some BSPs only make sense given certain kernel types.
		187	So, for these types, the team creates branches off the end of that kernel type for all
		188	of the BSPs that are supported on that kernel type.
		189	From the perspective of the tools that create the BSP branch, the BSP is really no
		190	different than a feature.
		191	Consequently, the same branching strategy applies to BSPs as it does to features.
		192	So again, rather than store the BSP twice, the team only stores the unique
		193	differences for the BSP across the supported multiple kernels.
		194	</para>
		195	<para>
		196	While this strategy can result in a tree with a significant number of branches, it is
		197	important to realize that from the developer's point of view, there is a linear
		198	path that travels from the baseline <filename>kernel.org</filename>, through a select
		199	group of features and ends with their BSP-specific commits.
		200	In other words, the divisions of the kernel are transparent and are not relevant
		201	to the developer on a day-to-day basis.
		202	From the developer's perspective, this path is the "master" branch.
		203	The developer does not need to be aware of the existence of any other branches at all.
		204	Of course, there is value in the existence of these branches
		205	in the tree, should a person decide to explore them.
		206	For example, a comparison between two BSPs at either the commit level or at the line-by-line
		207	code <filename>diff</filename> level is now a trivial operation.
		208	</para>
		209	<para>
		210	Working with the kernel as a structured tree follows recognized community best practices.
		211	In particular, the kernel as shipped with the product, should be
		212	considered an "upstream source" and viewed as a series of
		213	historical and documented modifications (commits).
		214	These modifications represent the development and stabilization done
		215	by the Yocto Project kernel development team.
		216	</para>
		217	<para>
		218	Because commits only change at significant release points in the product life cycle,
		219	developers can work on a branch created
		220	from the last relevant commit in the shipped Yocto Project kernel.
		221	As mentioned previously, the structure is transparent to the developer
		222	because the kernel tree is left in this state after cloning and building the kernel.
		223	</para>
		224	</section>
		225
		226	<section id='source-code-manager-git'>
		227	<title>Source Code Manager - Git</title>
		228	<para>
		229	The Source Code Manager (SCM) is Git.
		230	This SCM is the obvious mechanism for meeting the previously mentioned goals.
		231	Not only is it the SCM for <filename>kernel.org</filename> but,
		232	Git continues to grow in popularity and supports many different work flows,
		233	front-ends and management techniques.
		234	</para>
		235	<para>
		236	You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
		237	You can also get an introduction to Git as it applies to the Yocto Project in the
		238	"<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
		239	section in the Yocto Project Development Manual.
		240	These referenced sections overview Git and describe a minimal set of
		241	commands that allows you to be functional using Git.
		242	<note>
		243	You can use as much, or as little, of what Git has to offer to accomplish what
		244	you need for your project.
		245	You do not have to be a "Git Master" in order to use it with the Yocto Project.
		246	</note>
		247	</para>
		248	</section>
		249	</section>
86	</appendix>	250	</appendix>
87	<!--	251	<!--
88	vim: expandtab tw=80 ts=4	252	vim: expandtab tw=80 ts=4