diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2013-01-28 11:29:51 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-30 14:10:02 +0000 |
commit | a24cb73f398b619e00395949fce73f667f7ca8af (patch) | |
tree | 058f96ca6b474f3b7daa02788b64a8d684c635f1 /documentation | |
parent | 36b5f97e2605853a163ba5094c0712b45832fb26 (diff) | |
download | openembedded-core-contrib-a24cb73f398b619e00395949fce73f667f7ca8af.tar.gz |
kernel-dev: Added "Kernel Architecture" section.
Moved the "Kernel Architecture" section from the YP Kernel
Architecture and Use Manual to this manual. The section
included the kernel-architecture-overview.png figure. So,
I added that PNG file to the "figures" folder. Finally, I
had to also add the PNG file to the Makefile tarfile list
for kernel-dev. Note that because the figure was part of
the old YP Kernel Architecture and Use Manual, I did not have
to add the figure to the mega-manual tarfile list.
(From yocto-docs rev: fbc5508ce162ea7915fd5dce74338b6a5bfd7ce1)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/Makefile | 3 | ||||
-rwxr-xr-x | documentation/kernel-dev/figures/kernel-architecture-overview.png | bin | 0 -> 40748 bytes | |||
-rw-r--r-- | documentation/kernel-dev/kernel-dev-concepts-appx.xml | 164 |
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 Binary files differnew file mode 100755 index 0000000000..2aad172db3 --- /dev/null +++ b/documentation/kernel-dev/figures/kernel-architecture-overview.png 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 |