summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-concepts-appx.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-concepts-appx.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml374
1 files changed, 192 insertions, 182 deletions
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 21f7c2c686..7c9f34c729 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -173,202 +173,212 @@
173 </para> 173 </para>
174 </section> 174 </section>
175 175
176 <section id='kernel-architecture'> 176 <section id='yocto-linux-kernel-architecture-and-branching-strategies'>
177 <title>Kernel Architecture</title> 177 <title>Yocto Linux Kernel Architecture and Branching Strategies</title>
178 178
179 <para> 179 <para>
180 This section describes the architecture of the Yocto Linux kernels 180 As mentioned earlier, a key goal of the Yocto Project is
181 available through the Yocto Project and provides information 181 to present the developer with a kernel that has a clear and
182 on the mechanisms used to achieve that architecture. 182 continuous history that is visible to the user.
183 The architecture and mechanisms, in particular the branching
184 strategies, used achieve that goal in a manner similar to
185 upstream Linux kernel development in
186 <filename>kernel.org</filename>.
183 </para> 187 </para>
184 188
185 <section id='architecture-overview'> 189 <para>
186 <title>Overview</title> 190 You can think of a Yocto Linux kernel as consisting of a
191 baseline Linux kernel with added features logically structured
192 on top of the baseline.
193 The features are tagged and organized by way of a branching
194 strategy implemented by the Yocto Project team using the
195 Source Code Manager (SCM) Git.
196 <note><title>Notes</title>
197 <itemizedlist>
198 <listitem><para>
199 Git is the obvious SCM for meeting the Yocto Linux
200 kernel organizational and structural goals
201 described in this section.
202 Not only is Git the SCM for Linux kernel
203 development in <filename>kernel.org</filename> but,
204 Git continues to grow in popularity and supports
205 many different work flows, front-ends and
206 management techniques.
207 </para></listitem>
208 <listitem><para>
209 You can find documentation on Git at
210 <ulink url='http://git-scm.com/documentation'></ulink>.
211 You can also get an introduction to Git as it
212 applies to the Yocto Project in the
213 "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
214 section in the Yocto Project Reference Manual.
215 The latter reference provides an overview of
216 Git and presents a minimal set of Git commands
217 that allows you to be functional using Git.
218 You can use as much, or as little, of what Git
219 has to offer to accomplish what you need for your
220 project.
221 You do not have to be a "Git Expert" in order to
222 use it with the Yocto Project.
223 </para></listitem>
224 </itemizedlist>
225 </note>
226 </para>
187 227
188 <para> 228 <para>
189 As mentioned earlier, a key goal of the Yocto Project is 229 Using Git's tagging and branching features, the Yocto Project
190 to present the developer with a kernel that has a clear and 230 team creates kernel branches at points where functionality is
191 continuous history that is visible to the user. 231 no longer shared and thus, needs to be isolated.
192 The architecture and mechanisms used achieve that goal in a 232 For example, board-specific incompatibilities would require
193 manner similar to upstream Linux kernel development in 233 different functionality and would require a branch to
194 <filename>kernel.org</filename>. 234 separate the features.
195 </para> 235 Likewise, for specific kernel features, the same branching
236 strategy is used.
237 </para>
196 238
197 <para> 239 <para>
198 You can think of a Yocto Linux kernel as consisting of a 240 This "tree-like" architecture results in a tree that has
199 baseline Linux kernel with added features logically structured 241 features organized to be specific for particular
200 on top of the baseline. 242 functionality, single kernel types, or a subset of kernel
201 The features are tagged and organized by way of a branching 243 types.
202 strategy implemented by the Yocto Project team using the 244 Thus, the user has the ability to see the added
203 Source Code Manager (SCM) Git. 245 features and the commits that make up those features.
204 <note><title>Notes</title> 246 In addition to being able to see added features, the user
205 <itemizedlist> 247 can also view the history of what made up the baseline
206 <listitem><para> 248 Linux kernel.
207 Git is the obvious SCM for meeting the Yocto Linux 249 </para>
208 kernel organizational and structural goals
209 described in this section.
210 Not only is Git the SCM for Linux kernel
211 development in <filename>kernel.org</filename> but,
212 Git continues to grow in popularity and supports
213 many different work flows, front-ends and
214 management techniques.
215 </para></listitem>
216 <listitem><para>
217 You can find documentation on Git at
218 <ulink url='http://git-scm.com/documentation'></ulink>.
219 You can also get an introduction to Git as it
220 applies to the Yocto Project in the
221 "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
222 section in the Yocto Project Reference Manual.
223 The latter reference provides an overview of
224 Git and presents a minimal set of Git commands
225 that allows you to be functional using Git.
226 You can use as much, or as little, of what Git
227 has to offer to accomplish what you need for your
228 project.
229 You do not have to be a "Git Expert" in order to
230 use it with the Yocto Project.
231 </para></listitem>
232 </itemizedlist>
233 </note>
234 </para>
235 250
236 <para> 251 <para>
237 The result is that the user has the ability to see the added 252 Another consequence of this strategy results in not having to
238 features and the commits that make up those features. 253 store the same feature twice internally in the tree.
239 In addition to being able to see added features, the user 254 Rather, the kernel team stores the unique differences required
240 can also view the history of what made up the baseline 255 to apply the feature onto the kernel type in question.
241 Linux kernel. 256 <note>
242 </para> 257 The Yocto Project team strives to place features in the tree
258 such that features can be shared by all boards and kernel
259 types where possible.
260 However, during development cycles or when large features
261 are merged, the team cannot always follow this practice.
262 In those cases, the team uses isolated branches to merge
263 features.
264 </note>
265 </para>
243 266
244 <para> 267 <para>
245 The following illustration shows the conceptual Yocto 268 BSP-specific code additions are handled in a similar manner to
246 Linux kernel. 269 kernel-specific additions.
247 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" /> 270 Some BSPs only make sense given certain kernel types.
248 </para> 271 So, for these types, the team creates branches off the end
272 of that kernel type for all of the BSPs that are supported on
273 that kernel type.
274 From the perspective of the tools that create the BSP branch,
275 the BSP is really no different than a feature.
276 Consequently, the same branching strategy applies to BSPs as
277 it does to kernel features.
278 So again, rather than store the BSP twice, the team only
279 stores the unique differences for the BSP across the supported
280 multiple kernels.
281 </para>
249 282
250 <para> 283 <para>
251 In the illustration, the "Kernel.org Branch Point" marks the 284 While this strategy can result in a tree with a significant number
252 specific spot (or Linux kernel release) from which the 285 of branches, it is important to realize that from the developer's
253 Yocto Linux kernel is created. 286 point of view, there is a linear path that travels from the
254 From this point forward in the tree, features and differences 287 baseline <filename>kernel.org</filename>, through a select
255 are organized and tagged. 288 group of features and ends with their BSP-specific commits.
256 </para> 289 In other words, the divisions of the kernel are transparent and
290 are not relevant to the developer on a day-to-day basis.
291 From the developer's perspective, this path is the "master" branch
292 in Git terms.
293 The developer does not need to be aware of the existence of any
294 other branches at all.
295 Of course, value exists in the having these branches in the tree,
296 should a person decide to explore them.
297 For example, a comparison between two BSPs at either the commit
298 level or at the line-by-line code <filename>diff</filename> level
299 is now a trivial operation.
300 </para>
257 301
258 <para> 302 <para>
259 The "Yocto Project Baseline Kernel" contains functionality that 303 The following illustration shows the conceptual Yocto
260 is common to every kernel type and BSP that is organized 304 Linux kernel.
261 further along in the tree. 305 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
262 Placing these common features in the tree this way means 306 </para>
263 features do not have to be duplicated along individual 307
264 branches of the tree structure. 308 <para>
265 </para> 309 In the illustration, the "Kernel.org Branch Point" marks the
310 specific spot (or Linux kernel release) from which the
311 Yocto Linux kernel is created.
312 From this point forward in the tree, features and differences
313 are organized and tagged.
314 </para>
315
316 <para>
317 The "Yocto Project Baseline Kernel" contains functionality that
318 is common to every kernel type and BSP that is organized
319 further along in the tree.
320 Placing these common features in the tree this way means
321 features do not have to be duplicated along individual
322 branches of the tree structure.
323 </para>
324
325 <para>
326 From the "Yocto Project Baseline Kernel", branch points represent
327 specific functionality for individual Board Support Packages
328 (BSPs) as well as real-time kernels.
329 The illustration represents this through three BSP-specific
330 branches and a real-time kernel branch.
331 Each branch represents some unique functionality for the BSP
332 or for a real-time Yocto Linux kernel.
333 </para>
266 334
267 <para> 335 <para>
268 From the Yocto Project Baseline Kernel, branch points represent 336 In this example structure, the "Real-time (rt) Kernel" branch has
269 specific functionality for individual Board Support Packages 337 common features for all real-time Yocto Linux kernels and
270 (BSPs) as well as real-time kernels. 338 contains more branches for individual BSP-specific real-time
271 The illustration represents this through three BSP-specific 339 kernels.
272 branches and a real-time kernel branch. 340 The illustration shows three branches as an example.
273 Each branch represents some unique functionality for the BSP 341 Each branch points the way to specific, unique features for a
274 or for a real-time Yocto Linux kernel. 342 respective real-time kernel as they apply to a given BSP.
275 </para> 343 </para>
276 344
277 <para> 345 <para>
278 In this example structure, the real-time kernel branch has 346 The resulting tree structure presents a clear path of markers
279 common features for all real-time Yocto Linux kernels and 347 (or branches) to the developer that, for all practical
280 contains more branches for individual BSP-specific real-time 348 purposes, is the Yocto Linux kernel needed for any given set of
281 kernels. 349 requirements.
282 The illustration shows three branches as an example. 350 <note>
283 Each branch points the way to specific, unique features for a 351 Keep in mind the figure does not take into account all the
284 respective real-time kernel as they apply to a given BSP. 352 supported Yocto Linux kernels, but rather shows a single
285 </para> 353 generic kernel just for conceptual purposes.
354 Also keep in mind that this structure represents the Yocto
355 Project
356 <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
357 that are either pulled from during the build or established
358 on the host development system prior to the build by either
359 cloning a particular kernel's Git repository or by
360 downloading and unpacking a tarball.
361 </note>
362 </para>
286 363
287 <para> 364 <para>
288 The resulting tree structure presents a clear path of markers 365 Working with the kernel as a structured tree follows recognized
289 (or branches) to the developer that, for all practical 366 community best practices.
290 purposes, is the Yocto Linux kernel needed for any given set of 367 In particular, the kernel as shipped with the product, should be
291 requirements. 368 considered an "upstream source" and viewed as a series of
292 <note> 369 historical and documented modifications (commits).
293 Keep in mind the figure does not take into account all the 370 These modifications represent the development and stabilization
294 supported Yocto Linux kernels, but rather shows a single 371 done by the Yocto Project kernel development team.
295 generic kernel just for conceptual purposes. 372 </para>
296 Also keep in mind that this structure represents the Yocto
297 Project
298 <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
299 that are either pulled from during the build or established
300 on the host development system prior to the build by either
301 cloning a particular kernel's Git repository or by
302 downloading and unpacking a tarball.
303 </note>
304 </para>
305 </section>
306 373
307 <section id='branching-and-workflow'> 374 <para>
308 <title>Branching Strategy and Workflow</title> 375 Because commits only change at significant release points in the
309 <para> 376 product life cycle, developers can work on a branch created
310 The Yocto Project team creates kernel branches at points where functionality is 377 from the last relevant commit in the shipped Yocto Project kernel.
311 no longer shared and thus, needs to be isolated. 378 As mentioned previously, the structure is transparent to the
312 For example, board-specific incompatibilities would require different functionality 379 developer because the kernel tree is left in this state after
313 and would require a branch to separate the features. 380 cloning and building the kernel.
314 Likewise, for specific kernel features, the same branching strategy is used. 381 </para>
315 </para>
316 <para>
317 This branching strategy results in a tree that has features organized to be specific
318 for particular functionality, single kernel types, or a subset of kernel types.
319 This strategy also results in not having to store the same feature twice
320 internally in the tree.
321 Rather, the kernel team stores the unique differences required to apply the
322 feature onto the kernel type in question.
323 <note>
324 The Yocto Project team strives to place features in the tree such that they can be
325 shared by all boards and kernel types where possible.
326 However, during development cycles or when large features are merged,
327 the team cannot always follow this practice.
328 In those cases, the team uses isolated branches to merge features.
329 </note>
330 </para>
331 <para>
332 BSP-specific code additions are handled in a similar manner to kernel-specific additions.
333 Some BSPs only make sense given certain kernel types.
334 So, for these types, the team creates branches off the end of that kernel type for all
335 of the BSPs that are supported on that kernel type.
336 From the perspective of the tools that create the BSP branch, the BSP is really no
337 different than a feature.
338 Consequently, the same branching strategy applies to BSPs as it does to features.
339 So again, rather than store the BSP twice, the team only stores the unique
340 differences for the BSP across the supported multiple kernels.
341 </para>
342 <para>
343 While this strategy can result in a tree with a significant number of branches, it is
344 important to realize that from the developer's point of view, there is a linear
345 path that travels from the baseline <filename>kernel.org</filename>, through a select
346 group of features and ends with their BSP-specific commits.
347 In other words, the divisions of the kernel are transparent and are not relevant
348 to the developer on a day-to-day basis.
349 From the developer's perspective, this path is the "master" branch.
350 The developer does not need to be aware of the existence of any other branches at all.
351 Of course, there is value in the existence of these branches
352 in the tree, should a person decide to explore them.
353 For example, a comparison between two BSPs at either the commit level or at the line-by-line
354 code <filename>diff</filename> level is now a trivial operation.
355 </para>
356 <para>
357 Working with the kernel as a structured tree follows recognized community best practices.
358 In particular, the kernel as shipped with the product, should be
359 considered an "upstream source" and viewed as a series of
360 historical and documented modifications (commits).
361 These modifications represent the development and stabilization done
362 by the Yocto Project kernel development team.
363 </para>
364 <para>
365 Because commits only change at significant release points in the product life cycle,
366 developers can work on a branch created
367 from the last relevant commit in the shipped Yocto Project kernel.
368 As mentioned previously, the structure is transparent to the developer
369 because the kernel tree is left in this state after cloning and building the kernel.
370 </para>
371 </section>
372 </section> 382 </section>
373</appendix> 383</appendix>
374<!-- 384<!--