summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-manual/kernel-concepts.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-manual/kernel-concepts.xml')
-rw-r--r--documentation/kernel-manual/kernel-concepts.xml194
1 files changed, 100 insertions, 94 deletions
diff --git a/documentation/kernel-manual/kernel-concepts.xml b/documentation/kernel-manual/kernel-concepts.xml
index eede5a2e59..bcda78c4e1 100644
--- a/documentation/kernel-manual/kernel-concepts.xml
+++ b/documentation/kernel-manual/kernel-concepts.xml
@@ -46,12 +46,14 @@
46 the baseline kernel is the most stable official release.</para></listitem> 46 the baseline kernel is the most stable official release.</para></listitem>
47 <listitem><para>Include major technological features as part of Yocto Project's up-rev 47 <listitem><para>Include major technological features as part of Yocto Project's up-rev
48 strategy.</para></listitem> 48 strategy.</para></listitem>
49 <listitem><para>Present a Git tree, that just like the upstream kernel.org tree, has a 49 <listitem><para>Present a kernel Git repository that, similar to the upstream
50 clear and continuous history.</para></listitem> 50 <filename>kernel.org</filename> tree,
51 has a clear and continuous history.</para></listitem>
51 <listitem><para>Deliver a key set of supported kernel types, where each type is tailored 52 <listitem><para>Deliver a key set of supported kernel types, where each type is tailored
52 to a specific use case (i.e. networking, consumer, devices, and so forth).</para></listitem> 53 to a specific use case (e.g. networking, consumer, devices, and so forth).</para></listitem>
53 <listitem><para>Employ a Git branching strategy that from a customer's point of view 54 <listitem><para>Employ a Git branching strategy that, from a developer's point of view,
54 results in a linear path from the baseline kernel.org, through a select group of features and 55 results in a linear path from the baseline <filename>kernel.org</filename>,
56 through a select group of features and
55 ends with their BSP-specific commits.</para></listitem> 57 ends with their BSP-specific commits.</para></listitem>
56 </itemizedlist> 58 </itemizedlist>
57 </para> 59 </para>
@@ -60,27 +62,29 @@
60 <section id='kernel-big-picture'> 62 <section id='kernel-big-picture'>
61 <title>Yocto Project Kernel Development and Maintenance Overview</title> 63 <title>Yocto Project Kernel Development and Maintenance Overview</title>
62 <para> 64 <para>
63 Yocto Project kernel, like other kernels, is based off the Linux kernel release 65 The Yocto Project kernel, like other kernels, is based off the Linux kernel release
64 from <ulink url='http://www.kernel.org'></ulink>. 66 from <ulink url='http://www.kernel.org'></ulink>.
65 At the beginning of our major development cycle, we choose our Yocto Project kernel 67 At the beginning of a major development cycle, the Yocto Project team
66 based on factors like release timing, the anticipated release timing of "final" (i.e. non "rc") 68 chooses its Yocto Project kernel
67 upstream kernel.org versions, and Yocto Project feature requirements. 69 based on factors like release timing, the anticipated release timing of final
68 Typically this will be a kernel that is in the 70 upstream <filename>kernel.org</filename> versions, and Yocto Project feature requirements.
69 final stages of development by the community (i.e. still in the release 71 Typically, the kernel chosen is in the
70 candidate or "rc" phase) and not yet a final release. 72 final stages of development by the community.
71 But by being in the final stages of external development, we know that the 73 In other words, the kernel is in the release
72 kernel.org final release will clearly land within the early stages of 74 candidate or "rc" phase and not yet a final release.
75 But, by being in the final stages of external development, the team knows that the
76 <filename>kernel.org</filename> final release will clearly be within the early stages of
73 the Yocto Project development window. 77 the Yocto Project development window.
74 </para> 78 </para>
75 <para> 79 <para>
76 This balance allows us to deliver the most up-to-date kernel 80 This balance allows the team to deliver the most up-to-date kernel
77 as possible, while still ensuring that we have a stable official release as 81 as possible, while still ensuring that the team has a stable official release as
78 our baseline kernel version. 82 the baseline kernel version.
79 </para> 83 </para>
80 <para> 84 <para>
81 The ultimate source for the Yocto Project kernel is a released kernel 85 The ultimate source for the Yocto Project kernel is a released kernel
82 from kernel.org. 86 from <filename>kernel.org</filename>.
83 In addition to a foundational kernel from kernel.org the released 87 In addition to a foundational kernel from <filename>kernel.org</filename>, the released
84 Yocto Project kernel contains a mix of important new mainline 88 Yocto Project kernel contains a mix of important new mainline
85 developments, non-mainline developments (when there is no alternative), 89 developments, non-mainline developments (when there is no alternative),
86 Board Support Package (BSP) developments, 90 Board Support Package (BSP) developments,
@@ -88,37 +92,21 @@
88 These additions result in a commercially released Yocto Project kernel that caters 92 These additions result in a commercially released Yocto Project kernel that caters
89 to specific embedded designer needs for targeted hardware. 93 to specific embedded designer needs for targeted hardware.
90 </para> 94 </para>
91<!-- <para>
92 The following figure represents the overall place the Yocto Project kernel fills.
93 </para>
94 <para>
95 <imagedata fileref="figures/kernel-big-picture.png" width="6in" depth="6in" align="center" scale="100" />
96 </para>
97 <para>
98 In the figure the ultimate source for the Yocto Project kernel is a released kernel
99 from kernel.org.
100 In addition to a foundational kernel from kernel.org the commercially released
101 Yocto Project kernel contains a mix of important new mainline
102 developments, non-mainline developments, Board Support Package (BSP) developments,
103 and custom features.
104 These additions result in a commercially released Yocto Project kernel that caters
105 to specific embedded designer needs for targeted hardware.
106 </para> -->
107 <para> 95 <para>
108 Once a Yocto Project kernel is officially released the Yocto Project team goes into 96 Once a Yocto Project kernel is officially released, the Yocto Project team goes into
109 their next development cycle, or "uprev" cycle while continuing maintenance on the 97 their next development cycle, or "uprev" cycle, while still continuing maintenance on the
110 released kernel. 98 released kernel.
111 It is important to note that the most sustainable and stable way 99 It is important to note that the most sustainable and stable way
112 to include feature development upstream is through a kernel uprev process. 100 to include feature development upstream is through a kernel uprev process.
113 Back-porting of hundreds of individual fixes and minor features from various 101 Back-porting hundreds of individual fixes and minor features from various
114 kernel versions is not sustainable and can easily compromise quality. 102 kernel versions is not sustainable and can easily compromise quality.
103 </para>
104 <para>
115 During the uprev cycle, the Yocto Project team uses an ongoing analysis of 105 During the uprev cycle, the Yocto Project team uses an ongoing analysis of
116 kernel development, BSP support, and release timing to select the best 106 kernel development, BSP support, and release timing to select the best
117 possible kernel.org version. 107 possible <filename>kernel.org</filename> version.
118 The team continually monitors community kernel 108 The team continually monitors community kernel
119 development to look for significant features of interest. 109 development to look for significant features of interest.
120<!-- The illustration depicts this by showing the team looking back to kernel.org for new features,
121 BSP features, and significant bug fixes. -->
122 The team does consider back-porting large features if they have a significant advantage. 110 The team does consider back-porting large features if they have a significant advantage.
123 User or community demand can also trigger a back-port or creation of new 111 User or community demand can also trigger a back-port or creation of new
124 functionality in the Yocto Project baseline kernel during the uprev cycle. 112 functionality in the Yocto Project baseline kernel during the uprev cycle.
@@ -130,7 +118,7 @@
130 It is the Yocto Project team's policy to not back-port minor features to the released kernel. 118 It is the Yocto Project team's policy to not back-port minor features to the released kernel.
131 They only consider back-porting significant technological jumps - and, that is done 119 They only consider back-porting significant technological jumps - and, that is done
132 after a complete gap analysis. 120 after a complete gap analysis.
133 The reason for this policy is that simply back-porting any small to medium sized change 121 The reason for this policy is that back-porting any small to medium sized change
134 from an evolving kernel can easily create mismatches, incompatibilities and very 122 from an evolving kernel can easily create mismatches, incompatibilities and very
135 subtle errors. 123 subtle errors.
136 </para> 124 </para>
@@ -163,18 +151,23 @@
163 As mentioned earlier, a key goal of Yocto Project is to present the developer with 151 As mentioned earlier, a key goal of Yocto Project is to present the developer with
164 a kernel that has a clear and continuous history that is visible to the user. 152 a kernel that has a clear and continuous history that is visible to the user.
165 The architecture and mechanisms used achieve that goal in a manner similar to the 153 The architecture and mechanisms used achieve that goal in a manner similar to the
166 upstream kernel.org. 154 upstream <filename>kernel.org</filename>.
167
168 </para> 155 </para>
169 <para> 156 <para>
170 You can think of the Yocto Project kernel as consisting of a baseline kernel with 157 You can think of the Yocto Project kernel as consisting of a baseline kernel with
171 added features logically structured on top of the baseline. 158 added features logically structured on top of the baseline.
172 The features are tagged and organized by way of a branching strategy implemented by the 159 The features are tagged and organized by way of a branching strategy implemented by the
173 source code manager (SCM) Git. 160 source code manager (SCM) Git.
161 For information on Git as applied to the Yocto Project, see the
162 "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#git'>Git</ulink>"
163 section in <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The
164 Yocto Project Development Manual</ulink>.
165 </para>
166 <para>
174 The result is that the user has the ability to see the added features and 167 The result is that the user has the ability to see the added features and
175 the commits that make up those features. 168 the commits that make up those features.
176 In addition to being able to see added features, the user can also view the history of what 169 In addition to being able to see added features, the user can also view the history of what
177 made up the baseline kernel as well. 170 made up the baseline kernel.
178 </para> 171 </para>
179 <para> 172 <para>
180 The following illustration shows the conceptual Yocto Project kernel. 173 The following illustration shows the conceptual Yocto Project kernel.
@@ -183,18 +176,20 @@
183 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" /> 176 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
184 </para> 177 </para>
185 <para> 178 <para>
186 In the illustration, the "kernel.org Branch Point" marks the specific spot (or release) from 179 In the illustration, the "<filename>kernel.org</filename> Branch Point"
187 which the Yocto Project kernel is created. From this point "up" in the tree features and 180 marks the specific spot (or release) from
188 differences are organized and tagged. 181 which the Yocto Project kernel is created.
182 From this point "up" in the tree, features and differences are organized and tagged.
189 </para> 183 </para>
190 <para> 184 <para>
191 The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel 185 The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
192 type and BSP that is organized further up the tree. Placing these common features in the 186 type and BSP that is organized further up the tree.
187 Placing these common features in the
193 tree this way means features don't have to be duplicated along individual branches of the 188 tree this way means features don't have to be duplicated along individual branches of the
194 structure. 189 structure.
195 </para> 190 </para>
196 <para> 191 <para>
197 From the Yocto Project Baseline Kernel branch points represent specific functionality 192 From the Yocto Project Baseline Kernel, branch points represent specific functionality
198 for individual BSPs as well as real-time kernels. 193 for individual BSPs as well as real-time kernels.
199 The illustration represents this through three BSP-specific branches and a real-time 194 The illustration represents this through three BSP-specific branches and a real-time
200 kernel branch. 195 kernel branch.
@@ -209,8 +204,9 @@
209 kernel as they apply to a given BSP. 204 kernel as they apply to a given BSP.
210 </para> 205 </para>
211 <para> 206 <para>
212 The resulting tree structure presents a clear path of markers (or branches) to the user 207 The resulting tree structure presents a clear path of markers (or branches) to the
213 that for all practical purposes is the kernel needed for any given set of requirements. 208 developer that, for all practical purposes, is the kernel needed for any given set
209 of requirements.
214 </para> 210 </para>
215 </section> 211 </section>
216 212
@@ -221,50 +217,52 @@
221 no longer shared and thus, needs to be isolated. 217 no longer shared and thus, needs to be isolated.
222 For example, board-specific incompatibilities would require different functionality 218 For example, board-specific incompatibilities would require different functionality
223 and would require a branch to separate the features. 219 and would require a branch to separate the features.
224 Likewise, for specific kernel features the same branching strategy is used. 220 Likewise, for specific kernel features, the same branching strategy is used.
221 </para>
222 <para>
225 This branching strategy results in a tree that has features organized to be specific 223 This branching strategy results in a tree that has features organized to be specific
226 for particular functionality, single kernel types, or a subset of kernel types. 224 for particular functionality, single kernel types, or a subset of kernel types.
227 This strategy results in not having to store the same feature twice internally in the 225 This strategy also results in not having to store the same feature twice
228 tree. 226 internally in the tree.
229 Rather we store the unique differences required to apply the feature onto the kernel type 227 Rather, the kernel team stores the unique differences required to apply the
230 in question. 228 feature onto the kernel type in question.
229 <note>
230 The Yocto Project team strives to place features in the tree such that they can be
231 shared by all boards and kernel types where possible.
232 However, during development cycles or when large features are merged,
233 the team cannot always follow this practice.
234 In those cases, the team uses isolated branches to merge features.
235 </note>
231 </para> 236 </para>
232 <note><para>
233 The Yocto Project team strives to place features in the tree such that they can be
234 shared by all boards and kernel types where possible.
235 However, during development cycles or when large features are merged this practice
236 cannot always be followed.
237 In those cases isolated branches are used for feature merging.
238 </para></note>
239 <para> 237 <para>
240 BSP-specific code additions are handled in a similar manner to kernel-specific additions. 238 BSP-specific code additions are handled in a similar manner to kernel-specific additions.
241 Some BSPs only make sense given certain kernel types. 239 Some BSPs only make sense given certain kernel types.
242 So, for these types, we create branches off the end of that kernel type for all 240 So, for these types, the team creates branches off the end of that kernel type for all
243 of the BSPs that are supported on that kernel type. 241 of the BSPs that are supported on that kernel type.
244 From the perspective of the tools that create the BSP branch, the BSP is really no 242 From the perspective of the tools that create the BSP branch, the BSP is really no
245 different than a feature. 243 different than a feature.
246 Consequently, the same branching strategy applies to BSPs as it does to features. 244 Consequently, the same branching strategy applies to BSPs as it does to features.
247 So again, rather than store the BSP twice, only the unique differences for the BSP across 245 So again, rather than store the BSP twice, the team only stores the unique
248 the supported multiple kernels are uniquely stored. 246 differences for the BSP across the supported multiple kernels.
249 </para> 247 </para>
250 <para> 248 <para>
251 While this strategy can result in a tree with a significant number of branches, it is 249 While this strategy can result in a tree with a significant number of branches, it is
252 important to realize that from the user's point of view, there is a linear 250 important to realize that from the developer's point of view, there is a linear
253 path that travels from the baseline kernel.org, through a select group of features and 251 path that travels from the baseline <filename>kernel.org</filename>, through a select
254 ends with their BSP-specific commits. 252 group of features and ends with their BSP-specific commits.
255 In other words, the divisions of the kernel are transparent and are not relevant 253 In other words, the divisions of the kernel are transparent and are not relevant
256 to the developer on a day-to-day basis. 254 to the developer on a day-to-day basis.
257 From the user's perspective, this is the "master" branch. 255 From the developer's perspective, this path is the "master" branch.
258 They do not need not be aware of the existence of any other branches at all. 256 The developer does not need not be aware of the existence of any other branches at all.
259 Of course there is value in the existence of these branches 257 Of course, there is value in the existence of these branches
260 in the tree, should a person decide to explore them. 258 in the tree, should a person decide to explore them.
261 For example, a comparison between two BSPs at either the commit level or at the line-by-line 259 For example, a comparison between two BSPs at either the commit level or at the line-by-line
262 code diff level is now a trivial operation. 260 code <filename>diff</filename> level is now a trivial operation.
263 </para> 261 </para>
264 <para> 262 <para>
265 Working with the kernel as a structured tree follows recognized community best practices. 263 Working with the kernel as a structured tree follows recognized community best practices.
266 In particular, the kernel as shipped with the product should be 264 In particular, the kernel as shipped with the product, should be
267 considered an 'upstream source' and viewed as a series of 265 considered an "upstream source" and viewed as a series of
268 historical and documented modifications (commits). 266 historical and documented modifications (commits).
269 These modifications represent the development and stabilization done 267 These modifications represent the development and stabilization done
270 by the Yocto Project kernel development team. 268 by the Yocto Project kernel development team.
@@ -273,7 +271,7 @@
273 Because commits only change at significant release points in the product life cycle, 271 Because commits only change at significant release points in the product life cycle,
274 developers can work on a branch created 272 developers can work on a branch created
275 from the last relevant commit in the shipped Yocto Project kernel. 273 from the last relevant commit in the shipped Yocto Project kernel.
276 As mentioned previously, the structure is transparent to the user 274 As mentioned previously, the structure is transparent to the developer
277 because the kernel tree is left in this state after cloning and building the kernel. 275 because the kernel tree is left in this state after cloning and building the kernel.
278 </para> 276 </para>
279 </section> 277 </section>
@@ -281,20 +279,26 @@
281 <section id='source-code-manager-git'> 279 <section id='source-code-manager-git'>
282 <title>Source Code Manager - Git</title> 280 <title>Source Code Manager - Git</title>
283 <para> 281 <para>
284 The Source Code Manager (SCM) is Git and it is the obvious mechanism for meeting the 282 The Source Code Manager (SCM) is Git.
285 previously mentioned goals. 283 This SCM is the obvious mechanism for meeting the previously mentioned goals.
286 Not only is it the SCM for kernel.org but Git continues to grow in popularity and 284 Not only is it the SCM for <filename>kernel.org</filename> but,
287 supports many different work flows, front-ends and management techniques. 285 Git continues to grow in popularity and supports many different work flows,
286 front-ends and management techniques.
288 </para> 287 </para>
289 <para> 288 <para>
290 You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>. 289 You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
291 Also, the Yocto Project Development manual has an introduction to Git and describes a 290 You can also get an introduction to Git as it applies to the Yocto Project in the
292 minimal set of commands that allow you to be functional with Git. 291 "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#git'>Git</ulink>"
292 section in <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The
293 Yocto Project Development Manual</ulink>.
294 This section overviews Git and describes a minimal set of commands that allow you to be
295 functional using Git.
296 <note>
297 You can use as much, or as little, of what Git has to offer to accomplish what
298 you need for your project.
299 You do not have to be a "Git Master" in order to use it with the Yocto Project.
300 </note>
293 </para> 301 </para>
294 <note><para>
295 It should be noted that you can use as much, or as little, of what Git has to offer
296 as is appropriate to your project.
297 </para></note>
298 </section> 302 </section>
299 </section> 303 </section>
300 304
@@ -307,17 +311,19 @@
307 present a simplified view of the kernel for ease of use. 311 present a simplified view of the kernel for ease of use.
308 </para> 312 </para>
309 <para> 313 <para>
310 The fundamental properties of the tools that manage and construct the 314 Fundamentally, the kernel tools that manage and construct the
311 Yocto Project kernel are: 315 Yocto Project kernel accomplish the following:
312 <itemizedlist> 316 <itemizedlist>
313 <listitem><para>Group patches into named, reusable features.</para></listitem> 317 <listitem><para>Group patches into named, reusable features.</para></listitem>
314 <listitem><para>Allow top down control of included features.</para></listitem> 318 <listitem><para>Allow top-down control of included features.</para></listitem>
315 <listitem><para>Bind kernel configuration to kernel patches and features.</para></listitem> 319 <listitem><para>Bind kernel configurations to kernel patches and features.</para></listitem>
316 <listitem><para>Present a seamless Git repository that blends Yocto Project value 320 <listitem><para>Present a seamless Git repository that blends Yocto Project value
317 with the kernel.org history and development.</para></listitem> 321 with the <filename>kernel.org</filename> history and development.</para></listitem>
318 </itemizedlist> 322 </itemizedlist>
319 </para> 323 </para>
320<!--<para> 324<!--<para>
325WRITER NOTE: Put this in for post 1.1 if possible:
326
321The tools that construct a kernel tree will be discussed later in this 327The tools that construct a kernel tree will be discussed later in this
322document. The following tools form the foundation of the Yocto Project 328document. The following tools form the foundation of the Yocto Project
323kernel toolkit: 329kernel toolkit: