summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-01-28 11:29:51 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-30 14:10:02 +0000
commita24cb73f398b619e00395949fce73f667f7ca8af (patch)
tree058f96ca6b474f3b7daa02788b64a8d684c635f1 /documentation
parent36b5f97e2605853a163ba5094c0712b45832fb26 (diff)
downloadpoky-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/Makefile3
-rwxr-xr-xdocumentation/kernel-dev/figures/kernel-architecture-overview.pngbin0 -> 40748 bytes
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml164
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 \
289 --stringparam section.label.includes.component.label 1 \ 289 --stringparam section.label.includes.component.label 1 \
290 --xinclude 290 --xinclude
291ALLPREQ = html pdf tarball 291ALLPREQ = html pdf tarball
292TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png 292TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png \
293 figures/kernel-architecture-overview.png
293MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf 294MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf
294FIGURES = figures 295FIGURES = figures
295STYLESHEET = $(DOC)/*.css 296STYLESHEET = $(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<!--
88vim: expandtab tw=80 ts=4 252vim: expandtab tw=80 ts=4