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.xml253
1 files changed, 253 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
new file mode 100644
index 0000000000..ac91749cd6
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -0,0 +1,253 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='kernel-dev-concepts-appx'>
6<title>Advanced Kernel Concepts</title>
7
8 <section id='kernel-big-picture'>
9 <title>Yocto Project Kernel Development and Maintenance</title>
10 <para>
11 Kernels available through the Yocto Project, like other kernels, are based off the Linux
12 kernel releases from <ulink url='http://www.kernel.org'></ulink>.
13 At the beginning of a major development cycle, the Yocto Project team
14 chooses its kernel based on factors such as release timing, the anticipated release
15 timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
16 feature requirements.
17 Typically, the kernel chosen is in the
18 final stages of development by the community.
19 In other words, the kernel is in the release
20 candidate or "rc" phase and not yet a final release.
21 But, by being in the final stages of external development, the team knows that the
22 <filename>kernel.org</filename> final release will clearly be within the early stages of
23 the Yocto Project development window.
24 </para>
25 <para>
26 This balance allows the team to deliver the most up-to-date kernel
27 possible, while still ensuring that the team has a stable official release for
28 the baseline Linux kernel version.
29 </para>
30 <para>
31 The ultimate source for kernels available through the Yocto Project are released kernels
32 from <filename>kernel.org</filename>.
33 In addition to a foundational kernel from <filename>kernel.org</filename>, the
34 kernels available contain a mix of important new mainline
35 developments, non-mainline developments (when there is no alternative),
36 Board Support Package (BSP) developments,
37 and custom features.
38 These additions result in a commercially released Yocto Project Linux kernel that caters
39 to specific embedded designer needs for targeted hardware.
40 </para>
41 <para>
42 Once a kernel is officially released, the Yocto Project team goes into
43 their next development cycle, or upward revision (uprev) cycle, while still
44 continuing maintenance on the released kernel.
45 It is important to note that the most sustainable and stable way
46 to include feature development upstream is through a kernel uprev process.
47 Back-porting hundreds of individual fixes and minor features from various
48 kernel versions is not sustainable and can easily compromise quality.
49 </para>
50 <para>
51 During the uprev cycle, the Yocto Project team uses an ongoing analysis of
52 kernel development, BSP support, and release timing to select the best
53 possible <filename>kernel.org</filename> version.
54 The team continually monitors community kernel
55 development to look for significant features of interest.
56 The team does consider back-porting large features if they have a significant advantage.
57 User or community demand can also trigger a back-port or creation of new
58 functionality in the Yocto Project baseline kernel during the uprev cycle.
59 </para>
60 <para>
61 Generally speaking, every new kernel both adds features and introduces new bugs.
62 These consequences are the basic properties of upstream kernel development and are
63 managed by the Yocto Project team's kernel strategy.
64 It is the Yocto Project team's policy to not back-port minor features to the released kernel.
65 They only consider back-porting significant technological jumps - and, that is done
66 after a complete gap analysis.
67 The reason for this policy is that back-porting any small to medium sized change
68 from an evolving kernel can easily create mismatches, incompatibilities and very
69 subtle errors.
70 </para>
71 <para>
72 These policies result in both a stable and a cutting
73 edge kernel that mixes forward ports of existing features and significant and critical
74 new functionality.
75 Forward porting functionality in the kernels available through the Yocto Project kernel
76 can be thought of as a "micro uprev."
77 The many “micro uprevs” produce a kernel version with a mix of
78 important new mainline, non-mainline, BSP developments and feature integrations.
79 This kernel gives insight into new features and allows focused
80 amounts of testing to be done on the kernel, which prevents
81 surprises when selecting the next major uprev.
82 The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
83 feature and BSP development.
84 </para>
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 do not 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>
250</appendix>
251<!--
252vim: expandtab tw=80 ts=4
253-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-24 17:42:25 +0000