summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-09-29 10:31:42 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-10-04 13:46:41 +0100
commitd546b8f79342ed17e71cfb2132fff7c78a6918b0 (patch)
tree9f4809984faa6552b6ada9ac4f20dc445ca570db /documentation/kernel-manual
parentc47f8ed57d7f9c9665e8559615c9a02d6d5303f7 (diff)
downloadpoky-d546b8f79342ed17e71cfb2132fff7c78a6918b0.tar.gz
documentation/kernel-manual: Scrub for 1.1
I went through and made sure examples are relevant, wording is correct, large blocks of unused text was removed, and some references included to other YP documents. (From yocto-docs rev: 2231082530dd9cecc234f5f024c4e246afb2968d) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-manual')
-rw-r--r--documentation/kernel-manual/kernel-concepts.xml194
-rw-r--r--documentation/kernel-manual/kernel-doc-intro.xml28
-rw-r--r--documentation/kernel-manual/kernel-how-to.xml1691
3 files changed, 351 insertions, 1562 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:
diff --git a/documentation/kernel-manual/kernel-doc-intro.xml b/documentation/kernel-manual/kernel-doc-intro.xml
index e119068393..a9e51725da 100644
--- a/documentation/kernel-manual/kernel-doc-intro.xml
+++ b/documentation/kernel-manual/kernel-doc-intro.xml
@@ -20,17 +20,20 @@
20 on its history, organization, benefits, and use. 20 on its history, organization, benefits, and use.
21 The manual consists of two sections: 21 The manual consists of two sections:
22 <itemizedlist> 22 <itemizedlist>
23 <listitem><para>Concepts - Describes concepts behind the kernel. 23 <listitem><para><emphasis>Concepts:</emphasis> Describes concepts behind the kernel.
24 You will understand how the kernel is organized and why it is organized in 24 You will understand how the kernel is organized and why it is organized in
25 the way it is. You will understand the benefits of the kernel's organization 25 the way it is. You will understand the benefits of the kernel's organization
26 and the mechanisms used to work with the kernel and how to apply it in your 26 and the mechanisms used to work with the kernel and how to apply it in your
27 design process.</para></listitem> 27 design process.</para></listitem>
28 <listitem><para>Using the Kernel - Describes best practices and "how-to" information 28 <listitem><para><emphasis>Using the Kernel:</emphasis> Describes best practices
29 that lets you put the kernel to practical use. Some examples are "How to Build a 29 and "how-to" information
30 Project Specific Tree", "How to Examine Changes in a Branch", and "Saving Kernel 30 that lets you put the kernel to practical use.
31 Modifications."</para></listitem> 31 Some examples are "How to Build a
32 Project Specific Tree", "How to Examine Changes in a Branch", and "How to
33 Save Kernel Modifications."</para></listitem>
32 </itemizedlist> 34 </itemizedlist>
33 </para> 35 </para>
36
34 <para> 37 <para>
35 For more information on the kernel, see the following links: 38 For more information on the kernel, see the following links:
36 <itemizedlist> 39 <itemizedlist>
@@ -38,10 +41,19 @@
38 <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem> 41 <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem>
39 <listitem><para><ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem> 42 <listitem><para><ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem>
40 </itemizedlist> 43 </itemizedlist>
41 <para> 44 </para>
42 You can find more information on Yocto Project by visiting the website at 45
46 <para>
47 For more discussion on the Yocto Project kernel, you can also see the
48 "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#kernel-overview'>Kernel Overview</ulink>",
49 "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#kernel-modification-workflow'>Kernel Modification Workflow</ulink>", and
50 "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#dev-manual-kernel-appendix'>Kernel Modification Example</ulink>" sections all in
51 <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The Yocto Project Development Manual</ulink>.
52 </para>
53
54 <para>
55 For general information on the Yocto Project, visit the website at
43 <ulink url='http://www.yoctoproject.org'></ulink>. 56 <ulink url='http://www.yoctoproject.org'></ulink>.
44 </para>
45 </para> 57 </para>
46</section> 58</section>
47 59
diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
index 86e455357a..e62cfad655 100644
--- a/documentation/kernel-manual/kernel-how-to.xml
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -16,18 +16,7 @@
16 <itemizedlist> 16 <itemizedlist>
17 <listitem><para>Tree construction</para></listitem> 17 <listitem><para>Tree construction</para></listitem>
18 <listitem><para>Build strategies</para></listitem> 18 <listitem><para>Build strategies</para></listitem>
19<!-- <listitem><para>Series &amp; Configuration Compiler</para></listitem>
20 <listitem><para>kgit</para></listitem> -->
21 <listitem><para>Workflow examples</para></listitem> 19 <listitem><para>Workflow examples</para></listitem>
22<!-- <listitem><para>Source Code Manager (SCM)</para></listitem>
23 <listitem><para>Board Support Package (BSP) template migration</para></listitem>
24 <listitem><para>BSP creation</para></listitem>
25 <listitem><para>Patching</para></listitem>
26 <listitem><para>Updating BSP patches and configuration</para></listitem>
27 <listitem><para>guilt</para></listitem>
28 <listitem><para>scc file example</para></listitem>
29 <listitem><para>"dirty" string</para></listitem>
30 <listitem><para>Transition kernel layer</para></listitem> -->
31 </itemizedlist> 20 </itemizedlist>
32 </para> 21 </para>
33</section> 22</section>
@@ -35,65 +24,73 @@
35 <section id='tree-construction'> 24 <section id='tree-construction'>
36 <title>Tree Construction</title> 25 <title>Tree Construction</title>
37 <para> 26 <para>
38 The Yocto Project kernel repository, as shipped with the product, is created by 27 This section describes construction of the Yocto Project kernel repositories as accomplished
28 by the Yocto Project team to create kernel repositories, which are found at
29 <ulink url='http://git.yoctoproject.org/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>,
30 that can be shipped as part of a Yocto Project release.
31 The team creates these repositories by
39 compiling and executing the set of feature descriptions for every BSP/feature 32 compiling and executing the set of feature descriptions for every BSP/feature
40 in the product. 33 in the product.
41 Those feature descriptions list all necessary patches, 34 Those feature descriptions list all necessary patches,
42 configuration, branching, tagging and feature divisions found in the kernel. 35 configuration, branching, tagging and feature divisions found in the kernel.
43 Thus, the Yocto Project kernel repository (or tree) is built. 36 Thus, the Yocto Project kernel repository (or tree) is built.
44 The existence of this tree allows you to build images based on your configurations 37 </para>
38 <para>
39 The existence of this tree allows you to access and clone a particular
40 Linux Yocto kernel repository and use it to build images based on their configurations
45 and features. 41 and features.
46 </para> 42 </para>
47 <para> 43 <para>
48 You can find the files used to describe all the valid features and BSPs in the Yocto Project 44 You can find the files used to describe all the valid features and BSPs
49 kernel in any clone of the kernel Git tree. 45 in the Yocto Project kernel in any clone of the Linux Yocto kernel source repository Git tree.
50 For example, the following command clones the Yocto Project baseline kernel that 46 For example, the following command clones the Yocto Project baseline kernel that
51 branched off of linux.org version 2.6.37: 47 branched off of <filename>linux.org</filename> version 3.0:
52 <literallayout class='monospaced'> 48 <literallayout class='monospaced'>
53 $ git clone http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37 49 $ git clone git://git.yoctoproject.org/linux-yocto-3.0
54 </literallayout> 50 </literallayout>
55 After you switch to the <filename>meta</filename> branch within the repository 51 For another example of how to set up a local Git repository of the Linux Yocto
56 you can see a snapshot of all the kernel configuration and feature descriptions that are 52 kernel files, see the
53 "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#local-kernel-files'>Linux Yocto Kernel</ulink>" bulleted item in
54 <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The Yocto Project Development Manual</ulink>.
55 </para>
56 <para>
57 Once the Git repository is set up on your local machine, you can switch to the
58 <filename>meta</filename> branch within the repository.
59 Here, you can see a snapshot of all the kernel configuration and feature descriptions that are
57 used to build the kernel repository. 60 used to build the kernel repository.
58 These descriptions are in the form of <filename>.scc</filename> files. 61 These descriptions are in the form of <filename>.scc</filename> files.
59 </para> 62 </para>
60 <para> 63 <para>
61 You should realize, however, that browsing the snapshot of feature 64 You should realize, however, that browsing your local snapshot of feature
62 descriptions and patches is not an effective way to determine what is in a 65 descriptions and patches is not an effective way to determine what is in a
63 particular kernel branch. 66 particular kernel branch.
64 Instead, you should use Git directly to discover the changes 67 Instead, you should use Git directly to discover the changes in a branch.
65 in a branch.
66 Using Git is an efficient and flexible way to inspect changes to the kernel. 68 Using Git is an efficient and flexible way to inspect changes to the kernel.
67 For examples showing how to use Git to inspect kernel commits, see the following sections 69 For examples showing how to use Git to inspect kernel commits, see the following sections
68 in this chapter. 70 in this chapter.
71 <note>
72 Ground up reconstruction of the complete kernel tree is an action only taken by the
73 Yocto Project team during an active development cycle.
74 When you create a clone of the kernel Git repository, you are simply making it
75 efficiently available for building and development.
76 </note>
69 </para> 77 </para>
70 <note><para>
71 Ground up reconstruction of the complete kernel tree is an action only taken by the
72 Yocto Project team during an active development cycle.
73 Creating a project simply clones this tree to make it efficiently available for building
74 and development.
75 </para></note>
76 <para> 78 <para>
77 The following steps describe what happens during tree construction given the introduction 79 The following steps describe what happens when the Yocto kernel team constructs
78 of a new top-level kernel feature or BSP. 80 the kernel tree given the introduction of a new top-level kernel feature or BSP.
79 These are the actions that effectively create the tree that includes the new feature, patch, 81 These are the actions that effectively create the tree that includes the new feature, patch,
80 or BSP: 82 or BSP:
81 <orderedlist> 83 <orderedlist>
82 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem. 84 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
83 Normally, this is a BSP for a particular kernel type.</para></listitem> 85 Normally, this feature is a BSP for a particular kernel type.</para></listitem>
84
85 <listitem><para>The file that describes the top-level feature is located by searching 86 <listitem><para>The file that describes the top-level feature is located by searching
86 these system directories: 87 these system directories:
87
88 <itemizedlist> 88 <itemizedlist>
89 <listitem><para>The in-tree kernel-cache directories, which are located 89 <listitem><para>The in-tree kernel-cache directories, which are located
90 in <filename>meta/cfg/kernel-cache</filename></para></listitem> 90 in <filename>meta/cfg/kernel-cache</filename></para></listitem>
91<!-- <listitem><para>kernel-*-cache directories in layers</para></listitem> -->
92 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements 91 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
93 found in recipes</para></listitem> 92 found in recipes</para></listitem>
94<!-- <listitem><para>configured and default templates</para></listitem> -->
95 </itemizedlist> 93 </itemizedlist>
96
97 For a typical build, the target of the search is a 94 For a typical build, the target of the search is a
98 feature description in an <filename>.scc</filename> file 95 feature description in an <filename>.scc</filename> file
99 whose name follows this format: 96 whose name follows this format:
@@ -101,85 +98,60 @@
101 &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc 98 &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
102 </literallayout> 99 </literallayout>
103 </para></listitem> 100 </para></listitem>
104
105 <listitem><para>Once located, the feature description is either compiled into a simple script 101 <listitem><para>Once located, the feature description is either compiled into a simple script
106 of actions, or into an existing equivalent script that is already part of the 102 of actions, or into an existing equivalent script that is already part of the
107 shipped kernel.</para></listitem> 103 shipped kernel.</para></listitem>
108
109 <listitem><para>Extra features are appended to the top-level feature description. 104 <listitem><para>Extra features are appended to the top-level feature description.
110 These features can come from the <filename>KERNEL_FEATURES</filename> variable in 105 These features can come from the <filename>KERNEL_FEATURES</filename> variable in
111 recipes.</para></listitem> 106 recipes.</para></listitem>
112
113 <listitem><para>Each extra feature is located, compiled and appended to the script 107 <listitem><para>Each extra feature is located, compiled and appended to the script
114 as described in step three.</para></listitem> 108 as described in step three.</para></listitem>
115 109 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
116 <listitem><para>The script is executed to produce a meta-series. 110 directories.
117 The meta-series is a description of all the branches, tags, patches and configurations that 111 These directories are descriptions of all the branches, tags, patches and configurations that
118 need to be applied to the base Git repository to completely create the 112 need to be applied to the base Git repository to completely create the
119 source (build) branch for the new BSP or feature.</para></listitem> 113 source (build) branch for the new BSP or feature.</para></listitem>
120
121 <listitem><para>The base repository is cloned, and the actions 114 <listitem><para>The base repository is cloned, and the actions
122 listed in the meta-series are applied to the tree.</para></listitem> 115 listed in the <filename>meta-*</filename> directories are applied to the
123 116 tree.</para></listitem>
124 <listitem><para>The Git repository is left with the desired branch checked out and any 117 <listitem><para>The Git repository is left with the desired branch checked out and any
125 required branching, patching and tagging has been performed.</para></listitem> 118 required branching, patching and tagging has been performed.</para></listitem>
126 </orderedlist> 119 </orderedlist>
127 </para> 120 </para>
128
129 <para> 121 <para>
130 The tree is now ready for configuration and compilation. 122 The kernel tree is now ready for developer consumption to be locally cloned,
123 configured, and built into a Linux Yocto kernel specific to some target hardware.
124 <note><para>The generated <filename>meta-*</filename> directories add to the kernel
125 as shipped with the Yocto Project release.
126 Any add-ons and configuration data are applied to the end of an existing branch.
127 The full repository generation that is found in the
128 official Yocto Project kernel repositories at
129 <ulink url='http://git.yoctoproject.org/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
130 is the combination of all supported boards and configurations.</para>
131 <para>The technique the Yocto Project team uses is flexible and allows for seamless
132 blending of an immutable history with additional deployment specific patches.
133 Any additions to the kernel become an integrated part of the branches.</para>
134 </note>
131 </para> 135 </para>
132
133 <note><para>The end-user generated meta-series adds to the kernel as shipped with
134 the Yocto Project release.
135 Any add-ons and configuration data are applied to the end of an existing branch.
136 The full repository generation that is found in the
137 official Yocto Project kernel repositories is the combination of all
138 supported boards and configurations.</para>
139
140 <para>This technique is flexible and allows for seamless blending of an immutable
141 history with additional deployment specific patches.
142 Any additions to the kernel become an integrated part of the branches.
143 </para></note>
144
145<!-- <note><para>It is key that feature descriptions indicate if any branches are
146 required, since the build system cannot automatically decide where a
147 BSP should branch or if that branch point needs a name with
148 significance. There is a single restriction enforced by the compilation
149 phase:
150 </para>
151 <para>A BSP must create a branch of the format &lt;bsp name&gt;-&lt;kernel type&gt;.</para>
152
153 <para>This means that all merged/support BSPs must indicate where to start
154 its branch from, with the right name, in its .scc files. The scc
155 section describes the available branching commands in more detail.
156 </para>
157</note> -->
158
159<!-- <para>
160A summary of end user tree construction activities follow:
161<itemizedlist>
162 <listitem><para>compile and link a full top-down kernel description from feature descriptions</para></listitem>
163 <listitem><para>execute the complete description to generate a meta-series</para></listitem>
164 <listitem><para>interpret the meta-series to create a customized Git repository for the
165 board</para></listitem>
166 <listitem><para>migrate configuration fragments and configure the kernel</para></listitem>
167 <listitem><para>checkout the BSP branch and build</para></listitem>
168</itemizedlist>
169</para> -->
170 </section> 136 </section>
171 137
172 <section id='build-strategy'> 138 <section id='build-strategy'>
173 <title>Build Strategy</title> 139 <title>Build Strategy</title>
174 <para> 140 <para>
175 There are some prerequisites that must be met before starting the compilation 141 Once a local Git repository of the Linux Yocto kernel exists on a development system,
142 you can consider the compilation phase of kernel development - building a kernel image.
143 Some prerequisites exist that must be met before starting the compilation
176 phase of the kernel build system: 144 phase of the kernel build system:
177 </para> 145 </para>
178 146
179 <itemizedlist> 147 <itemizedlist>
180 <listitem><para>There must be a kernel Git repository indicated in the SRC_URI.</para></listitem> 148 <listitem><para>The <filename>SRC_URI</filename> must point to the kernel Git
181 <listitem><para>There must be a BSP build branch - &lt;bsp name&gt;-&lt;kernel type&gt; in 0.9 or 149 repository.</para></listitem>
182 &lt;kernel type&gt;/&lt;bsp name&gt; in 1.0.</para></listitem> 150 <listitem><para>A BSP build branch must exist.
151 This branch has the following form:
152 <literallayout class='monospaced'>
153 &lt;kernel_type&gt;/&lt;bsp_name&gt;
154 </literallayout></para></listitem>
183 </itemizedlist> 155 </itemizedlist>
184 156
185 <para> 157 <para>
@@ -187,15 +159,15 @@ A summary of end user tree construction activities follow:
187 of the build system. 159 of the build system.
188 However, other means do exist. 160 However, other means do exist.
189 For examples of alternate workflows such as bootstrapping a BSP, see 161 For examples of alternate workflows such as bootstrapping a BSP, see
190 the<link linkend='workflow-examples'> Workflow Examples</link> section in this manual. 162 the "<link linkend='workflow-examples'>Workflow Examples</link>".
191 </para> 163 </para>
192 164
193 <para> 165 <para>
194 Before building a kernel it is configured by processing all of the 166 Before building a kernel, the build process configures the kernel by processing all of the
195 configuration "fragments" specified by feature descriptions in the <filename>scc</filename> 167 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
196 files. 168 files.
197 As the features are compiled, associated kernel configuration fragments are noted 169 As the features are compiled, associated kernel configuration fragments are noted
198 and recorded in the meta-series in their compilation order. 170 and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
199 The fragments are migrated, pre-processed and passed to the Linux Kernel 171 The fragments are migrated, pre-processed and passed to the Linux Kernel
200 Configuration subsystem (<filename>lkc</filename>) as raw input in the form 172 Configuration subsystem (<filename>lkc</filename>) as raw input in the form
201 of a <filename>.config</filename> file. 173 of a <filename>.config</filename> file.
@@ -205,201 +177,47 @@ A summary of end user tree construction activities follow:
205 </para> 177 </para>
206 178
207 <para> 179 <para>
208 Using the board's architecture and other relevant values from the board's template 180 Using the board's architecture and other relevant values from the board's template,
209 the Kernel compilation is started and a kernel image is produced. 181 kernel compilation is started and a kernel image is produced.
210 </para> 182 </para>
211 183
212 <para>The other thing that you will first see once you configure a kernel is that 184 <para>
213 it will generate a build tree that is separate from your Git source tree. 185 The other thing that you notice once you configure a kernel is that
214 This build tree has the name using the following form: 186 the build process generates a build tree that is separate from your kernel's local Git
187 source repository tree.
188 This build tree has a name that uses the following form, where
189 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
190 of the Yocto Project supported kernel types (e.g. "standard"):
215 <literallayout class='monospaced'> 191 <literallayout class='monospaced'>
216 linux-&lt;BSPname&gt;-&lt;kerntype&gt;-build 192 linux-${MACHINE}-&lt;kernel_type&gt;-build
217 </literallayout> 193 </literallayout>
218 "kerntype" is one of the standard kernel types.
219 </para> 194 </para>
220 195
221 <para> 196 <para>
222 The existing support in the kernel.org tree achieves this default functionality. 197 The existing support in the <filename>kernel.org</filename> tree achieves this
198 default functionality.
223 </para> 199 </para>
224 200
225 <para> 201 <para>
226 What this means, is that all the generated files for a particular BSP are now in this directory. 202 What this means, is that all the generated files for a particular machine or BSP are now in
227 The files include the final <filename>.config</filename>, all the <filename>.o</filename> 203 the build tree directory.
204 The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
228 files, the <filename>.a</filename> files, and so forth. 205 files, the <filename>.a</filename> files, and so forth.
229 Since each BSP has its own separate build directory in its own separate branch 206 Since each machine or BSP has its own separate build directory in its own separate branch
230 of the Git tree you can easily switch between different BSP builds. 207 of the Git repository, you can easily switch between different builds.
231 </para> 208 </para>
232 </section> 209 </section>
233 210
234<!-- <section id='scc'>
235 <title>Series &amp; Configuration Compiler (SCC)</title>
236<para>
237In early versions of the product, kernel patches were simply listed in a flat
238file called "patches.list", and then quilt was added as a tool to help
239traverse this list, which in quilt terms was called a "series" file.
240</para>
241<para>
242Before the 2.0 release, it was already apparent that a static series file was
243too inflexible, and that the series file had to become more dynamic and rely
244on certain state (like kernel type) in order to determine whether a patch was
245to be used or not. The 2.0 release already made use of some stateful
246construction of series files, but since the delivery mechanism was unchanged
247(tar + patches + series files), most people were not aware of anything really
248different. The 3.0 release continues with this stateful construction of
249series files, but since the delivery mechanism is changed (Git + branches) it
250now is more apparent to people.
251</para>
252<para>
253As was previously mentioned, scc is a "series and configuration
254compiler". Its role is to combine feature descriptions into a format that can
255be used to generate a meta-series. A meta series contains all the required
256information to construct a complete set of branches that are required to
257build a desired board and feature set. The meta series is interpreted by the
258kgit tools to create a Git repository that could be built.
259</para>
260<para>
261To illustrate how scc works, a feature description must first be understood.
262A feature description is simply a small bash shell script that is executed by
263scc in a controlled environment. Each feature description describes a set of
264operations that add patches, modify existing patches or configure the
265kernel. It is key that feature descriptions can include other features, and
266hence allow the division of patches and configuration into named, reusable
267containers.
268</para>
269<para>
270Each feature description can use any of the following valid scc commands:
271<itemizedlist>
272 <listitem><para>shell constructs: bash conditionals and other utilities can be used in a feature
273 description. During compilation, the working directory is the feature
274 description itself, so any command that is "raw shell" and not from the
275 list of supported commands, can not directly modify a Git repository.</para></listitem>
276
277 <listitem><para>patch &lt;relative path&gt;/&lt;patch name&gt;: outputs a patch to be included in a feature's patch set. Only the name of
278 the patch is supplied, the path is calculated from the currently set
279 patch directory, which is normally the feature directory itself.</para></listitem>
280
281 <listitem><para>patch_trigger &gt;condition&lt; &gt;action&lt; &lt;tgt&gt;: indicate that a trigger should be set to perform an action on a
282 patch.</para>
283
284<para>The conditions can be:
285
286 <itemizedlist>
287 <listitem><para>arch:&lt;comma separated arch list or "all"&gt;</para></listitem>
288 <listitem><para>plat:&lt;comma separated platform list or "all"&gt;</para></listitem>
289 </itemizedlist></para>
290<para>The action can be:
291 <itemizedlist>
292 <listitem><para>exclude: This is used in exceptional situations where a patch
293 cannot be applied for certain reasons (arch or platform).
294 When the trigger is satisfied the patch will be removed from
295 the patch list.</para></listitem>
296 <listitem><para>include: This is used to include a patch only for a specific trigger.
297 Like exclude, this should only be used when necessary.
298 It takes 1 argument, the patch to include.</para></listitem>
299 </itemizedlist></para></listitem>
300
301 <listitem><para>include &lt;feature name&gt; [after &lt;feature&gt;]: includes a feature for processing. The feature is "expanded" at the
302 position of the include directive. This means that any patches,
303 configuration or sub-includes of the feature will appear in the final
304 series before the commands that follow the include.</para>
305 <para>
306 include searches the include directories for a matching feature name,
307 include directories are passed to scc by the caller using -I &lt;path&gt; and
308 is transparent to the feature script. This means that &lt;feature name&gt; must
309 be relative to one of the search paths. For example, if
310 /opt/kernel-cache/feat/sched.scc is to be included and scc is invoked
311 with -I /opt/kernel-cache, then a feature would issue "include
312 feat/sched.scc" to include the feature.
313</para>
314<para>
315 The optional "after" directive allows a feature to modify the existing
316 order of includes and insert a feature after the named feature is
317 processed. Note: the "include foo after bar" must be issued before "bar"
318 is processed, so is normally only used by a new top level feature to
319 modify the order of features in something it is including.</para></listitem>
320
321 <listitem><para>exclude &lt;feature name&gt;: Indicates that a particular feature should *not* be included even if an
322 'include' directive is found. The exclude must be issued before the
323 include is processed, so is normally only used by a new top level feature
324 to modify the order of features in something it is including.</para></listitem>
325
326 <listitem><para>git &lt;command&gt;: Issues any Git command during tree construction. Note: this command is
327 not validated/sanitized so care must be taken to not damage the
328 tree. This can be used to script branching, tagging, pulls or other Git
329 operations.</para></listitem>
330
331 <listitem><para>dir &lt;directory&gt;: changes the working directory for "patch" directives. This can be used to
332 shorten a long sequence of patches by not requiring a common relative
333 directory to be issued each time.</para></listitem>
334
335 <listitem><para>kconf &lt;type&gt; &lt;fragment name&gt;: associates a kernel config frag with the feature.
336 &lt;type&gt; can be
337 "hardware" or "non-hardware" and is used by the kernel configuration
338 subsystem to audit configuration. &lt;fragment name&gt; is the name of a file
339 in the current feature directory that contains a series of kernel
340 configuration options. There is no restriction on the chosen fragment
341 name, although a suffix of ".cfg" is recommended. Multiple fragment
342 specifications are supported.</para></listitem>
343
344 <listitem><para>branch &lt;branch name&gt;: creates a branch in the tree. All subsequent patch commands will be
345 applied to the new branch and changes isolated from the rest of the
346 repository.</para></listitem>
347
348 <listitem><para>scc_leaf &lt;base feature&gt; &lt;branch name&gt;: Performs a combination feature include and branch. This is mainly a
349 convenience directive, but has significance to some build system bindings
350 as a sentinel to indicate that this intends to create a branch that is
351 valid for kernel compilation.</para></listitem>
352
353 <listitem><para>tag &lt;tag name&gt;: Tags the tree. The tag will be applied in processing order, so will
354 be after already applied patches and precede patches yet to be applied.</para></listitem>
355
356 <listitem><para>define &lt;var&gt; &lt;value&gt;: Creates a variable with a particular value that can be used in subsequent
357 feature descriptions.</para></listitem>
358</itemizedlist>
359
360</para>
361 </section> -->
362
363<!-- <section id='kgit-tools'>
364 <title>kgit Tools</title>
365<para>
366The kgit tools are responsible for constructing and maintaining the Wind
367River kernel repository. These activities include importing, exporting, and
368applying patches as well as sanity checking and branch management. From the
369developers perspective, the kgit tools are hidden and rarely require
370interactive use. But one tool in particular that warrants further description
371is "kgit-meta".
372</para>
373<para>
374kgit-meta is the actual application of feature description(s) to a kernel repo.
375In other words, it is responsible for interpreting the meta series generated
376from a scc compiled script. As a result, kgit-meta is coupled to the set of
377commands permitted in a .scc feature description (listed in the scc section).
378kgit-meta understands both the meta series format and how to use Git and
379guilt to modify a base Git repository. It processes a meta-series line by
380line, branching, tagging, patching and tracking changes that are made to the
381base Git repository.
382</para>
383<para>
384Once kgit-meta has processed a meta-series, it leaves the repository with the
385last branch checked out, and creates the necessary guilt infrastructure to
386inspect the tree, or add to it via using guilt. As was previously mentioned,
387guilt is not required, but is provided as a convenience. Other utilities such
388as quilt, stgit, Git or others can also be used to manipulate the Git
389repository.
390</para>
391 </section> -->
392
393 <section id='workflow-examples'> 211 <section id='workflow-examples'>
394 <title>Workflow Examples</title> 212 <title>Workflow Examples</title>
395 213
396 <para> 214 <para>
397 As previously noted, the Yocto Project kernel has built in Git integration. 215 As previously noted, the Yocto Project kernel has built in Git integration.
398 However, these utilities are not the only way to work with the kernel repository. 216 However, these utilities are not the only way to work with the kernel repository.
399 Yocto Project has not made changes to Git or to other tools that 217 The Yocto Project has not made changes to Git or to other tools that
400 would invalidate alternate workflows. 218 would invalidate alternate workflows.
401 Additionally, the way the kernel repository is constructed results in using 219 Additionally, the way the kernel repository is constructed results in using
402 only core Git functionality thus allowing any number of tools or front ends to use the 220 only core Git functionality, thus allowing any number of tools or front ends to use the
403 resulting tree. 221 resulting tree.
404 </para> 222 </para>
405 223
@@ -417,7 +235,7 @@ repository.
417 235
418 <para> 236 <para>
419 In projects that have a collection of directories that 237 In projects that have a collection of directories that
420 contain patches to the kernel it is possible to inspect or "grep" the contents 238 contain patches to the kernel, it is possible to inspect or "grep" the contents
421 of the directories to get a general feel for the changes. 239 of the directories to get a general feel for the changes.
422 This sort of patch inspection is not an efficient way to determine what has been done to the 240 This sort of patch inspection is not an efficient way to determine what has been done to the
423 kernel. 241 kernel.
@@ -441,15 +259,12 @@ repository.
441 Note that because the Yocto Project Git repository does not break existing Git 259 Note that because the Yocto Project Git repository does not break existing Git
442 functionality and because there exists many permutations of these types of 260 functionality and because there exists many permutations of these types of
443 commands there are many more methods to discover changes. 261 commands there are many more methods to discover changes.
444 </para> 262 <note>
445 263 Unless you provide a commit range
446 <note><para> 264 (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), <filename>kernel.org</filename> history
447 Unless you provide a commit range 265 is blended with Yocto Project changes.
448 (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), kernel.org history 266 </note>
449 is blended with Yocto Project changes. 267 <literallayout class='monospaced'>
450 </para></note>
451
452 <literallayout class='monospaced'>
453 # full description of the changes 268 # full description of the changes
454 &gt; git whatchanged &lt;kernel type&gt;..&lt;kernel type&gt;/&lt;bsp&gt; 269 &gt; git whatchanged &lt;kernel type&gt;..&lt;kernel type&gt;/&lt;bsp&gt;
455 &gt; eg: git whatchanged yocto/standard/base..yocto/standard/common-pc/base 270 &gt; eg: git whatchanged yocto/standard/base..yocto/standard/common-pc/base
@@ -469,7 +284,8 @@ repository.
469 284
470 # determine the commits which touch each line in a file 285 # determine the commits which touch each line in a file
471 &gt; git blame &lt;path to file&gt; 286 &gt; git blame &lt;path to file&gt;
472 </literallayout> 287 </literallayout>
288 </para>
473 </section> 289 </section>
474 290
475 <section id='show-a-particular-feature-or-branch-change'> 291 <section id='show-a-particular-feature-or-branch-change'>
@@ -479,13 +295,11 @@ repository.
479 Significant features or branches are tagged in the Yocto Project tree to divide 295 Significant features or branches are tagged in the Yocto Project tree to divide
480 changes. 296 changes.
481 Remember to first determine (or add) the tag of interest. 297 Remember to first determine (or add) the tag of interest.
482 </para> 298 <note>
483 299 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
484 <note><para> 300 present, there could be many tags.
485 Because BSP branch, kernel.org, and feature tags are all present, there are many tags. 301 </note>
486 </para></note> 302 <literallayout class='monospaced'>
487
488 <literallayout class='monospaced'>
489 # show the changes tagged by a feature 303 # show the changes tagged by a feature
490 &gt; git show &lt;tag&gt; 304 &gt; git show &lt;tag&gt;
491 &gt; eg: git show yaffs2 305 &gt; eg: git show yaffs2
@@ -496,11 +310,13 @@ repository.
496 # show the changes in a kernel type 310 # show the changes in a kernel type
497 &gt; git whatchanged yocto/base..&lt;kernel type&gt; 311 &gt; git whatchanged yocto/base..&lt;kernel type&gt;
498 &gt; eg: git whatchanged yocto/base..yocto/standard/base 312 &gt; eg: git whatchanged yocto/base..yocto/standard/base
499 </literallayout> 313 </literallayout>
314 </para>
500 315
501 <para> 316 <para>
502 You can use many other comparisons to isolate BSP changes. 317 You can use many other comparisons to isolate BSP changes.
503 For example, you can compare against kernel.org tags (e.g. v2.6.27.18, etc), or 318 For example, you can compare against <filename>kernel.org</filename> tags
319 (e.g. v2.6.27.18, etc), or
504 you can compare against subsystems (e.g. <filename>git whatchanged mm</filename>). 320 you can compare against subsystems (e.g. <filename>git whatchanged mm</filename>).
505 </para> 321 </para>
506 </section> 322 </section>
@@ -510,8 +326,8 @@ repository.
510 <title>Development: Saving Kernel Modifications</title> 326 <title>Development: Saving Kernel Modifications</title>
511 327
512 <para> 328 <para>
513 Another common operation is to build a BSP supplied by Yocto Project, make some 329 Another common operation is to build a BSP supplied by the Yocto Project, make some
514 changes, rebuild and then test. 330 changes, rebuild, and then test.
515 Those local changes often need to be exported, shared or otherwise maintained. 331 Those local changes often need to be exported, shared or otherwise maintained.
516 </para> 332 </para>
517 333
@@ -519,7 +335,7 @@ repository.
519 Since the Yocto Project kernel source tree is backed by Git, this activity is 335 Since the Yocto Project kernel source tree is backed by Git, this activity is
520 much easier as compared to with previous releases. 336 much easier as compared to with previous releases.
521 Because Git tracks file modifications, additions and deletions, it is easy 337 Because Git tracks file modifications, additions and deletions, it is easy
522 to modify the code and later realize that the changes should be saved. 338 to modify the code and later realize that you need to save the changes.
523 It is also easy to determine what has changed. 339 It is also easy to determine what has changed.
524 This method also provides many tools to commit, undo and export those modifications. 340 This method also provides many tools to commit, undo and export those modifications.
525 </para> 341 </para>
@@ -529,45 +345,43 @@ repository.
529 The technique employed 345 The technique employed
530 depends on the destination for the patches: 346 depends on the destination for the patches:
531 347
532 <itemizedlist> 348 <itemizedlist>
533 <listitem><para>Bulk storage</para></listitem> 349 <listitem><para>Bulk storage</para></listitem>
534 <listitem><para>Internal sharing either through patches or by using Git</para></listitem> 350 <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
535 <listitem><para>External submissions</para></listitem> 351 <listitem><para>External submissions</para></listitem>
536 <listitem><para>Exporting for integration into another SCM</para></listitem> 352 <listitem><para>Exporting for integration into another Source Code
537 </itemizedlist> 353 Manager (SCM)</para></listitem>
354 </itemizedlist>
538 </para> 355 </para>
539 356
540 <para> 357 <para>
541 Because of the following list of issues, the destination of the patches also influences 358 Because of the following list of issues, the destination of the patches also influences
542 the method for gathering them: 359 the method for gathering them:
543 360
544 <itemizedlist> 361 <itemizedlist>
545 <listitem><para>Bisectability</para></listitem> 362 <listitem><para>Bisectability</para></listitem>
546 <listitem><para>Commit headers</para></listitem> 363 <listitem><para>Commit headers</para></listitem>
547 <listitem><para>Division of subsystems for separate submission or review</para></listitem> 364 <listitem><para>Division of subsystems for separate submission or review</para></listitem>
548 </itemizedlist> 365 </itemizedlist>
549 </para> 366 </para>
550 367
551 <section id='bulk-export'> 368 <section id='bulk-export'>
552 <title>Bulk Export</title> 369 <title>Bulk Export</title>
553 370
554 <para> 371 <para>
555 This section describes how you can export in "bulk" changes that have not 372 This section describes how you can "bulk" export changes that have not
556 been separated or divided. 373 been separated or divided.
557 This situation works well when you are simply storing patches outside of the kernel 374 This situation works well when you are simply storing patches outside of the kernel
558 source repository, either permanently or temporarily, and you are not committing 375 source repository, either permanently or temporarily, and you are not committing
559 incremental changes during development. 376 incremental changes during development.
560 </para> 377 <note>
561 378 This technique is not appropriate for full integration of upstream submission
562 <note><para> 379 because changes are not properly divided and do not provide an avenue for per-change
563 This technique is not appropriate for full integration of upstream submission 380 commit messages.
564 because changes are not properly divided and do not provide an avenue for per-change 381 Therefore, this example assumes that changes have not been committed incrementally
565 commit messages. 382 during development and that you simply must gather and export them.
566 Therefore, this example assumes that changes have not been committed incrementally 383 </note>
567 during development and that you simply must gather and export them. 384 <literallayout class='monospaced'>
568 </para></note>
569
570 <literallayout class='monospaced'>
571 # bulk export of ALL modifications without separation or division 385 # bulk export of ALL modifications without separation or division
572 # of the changes 386 # of the changes
573 387
@@ -575,7 +389,8 @@ repository.
575 &gt; git commit -s -a -m &gt;commit message&lt; 389 &gt; git commit -s -a -m &gt;commit message&lt;
576 or 390 or
577 &gt; git commit -s -a # and interact with $EDITOR 391 &gt; git commit -s -a # and interact with $EDITOR
578 </literallayout> 392 </literallayout>
393 </para>
579 394
580 <para> 395 <para>
581 The previous operations capture all the local changes in the project source 396 The previous operations capture all the local changes in the project source
@@ -596,18 +411,19 @@ repository.
596 <para> 411 <para>
597 This section describes how to save modifications when you are making incremental 412 This section describes how to save modifications when you are making incremental
598 commits or practicing planned sharing. 413 commits or practicing planned sharing.
599 The examples in this section assume that changes have been incrementally committed 414 The examples in this section assume that you have incrementally committed
600 to the tree during development and now need to be exported. The sections that follow 415 changes to the tree during development and now need to export them.
416 The sections that follow
601 describe how you can export your changes internally through either patches or by 417 describe how you can export your changes internally through either patches or by
602 using Git commands. 418 using Git commands.
603 </para> 419 </para>
604 420
605 <para> 421 <para>
606 During development the following commands are of interest. 422 During development, the following commands are of interest.
607 For full Git documentation, refer to the Git man pages or to an online resource such 423 For full Git documentation, refer to the Git documentation at
608 as <ulink url='http://github.com'></ulink>. 424 <ulink url='http://github.com'></ulink>.
609 425
610 <literallayout class='monospaced'> 426 <literallayout class='monospaced'>
611 # edit a file 427 # edit a file
612 &gt; vi &gt;path&lt;/file 428 &gt; vi &gt;path&lt;/file
613 # stage the change 429 # stage the change
@@ -620,11 +436,11 @@ repository.
620 &gt; git commit -s 436 &gt; git commit -s
621 437
622 ... etc. 438 ... etc.
623 </literallayout> 439 </literallayout>
624 </para> 440 </para>
625 441
626 <para> 442 <para>
627 Distributed development with git is possible when you use a universally 443 Distributed development with Git is possible when you use a universally
628 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a 444 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
629 specific change set with a specific parent. 445 specific change set with a specific parent.
630 This identifier is created for you when 446 This identifier is created for you when
@@ -632,7 +448,8 @@ repository.
632 a commit. 448 a commit.
633 As an individual in isolation, this is of no interest. 449 As an individual in isolation, this is of no interest.
634 However, if you 450 However, if you
635 intend to share your tree with normal git push and pull operations for 451 intend to share your tree with normal Git <filename>push</filename> and
452 <filename>pull</filename> operations for
636 distributed development, you should consider the ramifications of changing a 453 distributed development, you should consider the ramifications of changing a
637 commit that you have already shared with others. 454 commit that you have already shared with others.
638 </para> 455 </para>
@@ -642,19 +459,19 @@ repository.
642 another repository, you can update both the commit content and commit messages 459 another repository, you can update both the commit content and commit messages
643 associated with development by using the following commands: 460 associated with development by using the following commands:
644 461
645 <literallayout class='monospaced'> 462 <literallayout class='monospaced'>
646 &gt; Git add &gt;path&lt;/file 463 &gt; Git add &gt;path&lt;/file
647 &gt; Git commit --amend 464 &gt; Git commit --amend
648 &gt; Git rebase or Git rebase -i 465 &gt; Git rebase or Git rebase -i
649 </literallayout> 466 </literallayout>
650 </para> 467 </para>
651 468
652 <para> 469 <para>
653 Again, assuming that the changes have not been pushed upstream, and that 470 Again, assuming that the changes have not been pushed upstream, and that
654 no pending works-in-progress exist (use <filename>git status</filename> to check) then 471 no pending works-in-progress exists (use <filename>git status</filename> to check), then
655 you can revert (undo) commits by using the following commands: 472 you can revert (undo) commits by using the following commands:
656 473
657 <literallayout class='monospaced'> 474 <literallayout class='monospaced'>
658 # remove the commit, update working tree and remove all 475 # remove the commit, update working tree and remove all
659 # traces of the change 476 # traces of the change
660 &gt; git reset --hard HEAD^ 477 &gt; git reset --hard HEAD^
@@ -662,26 +479,26 @@ repository.
662 &gt; git reset --soft HEAD^ 479 &gt; git reset --soft HEAD^
663 # remove the commit, leave file change, but not staged for commit 480 # remove the commit, leave file change, but not staged for commit
664 &gt; git reset --mixed HEAD^ 481 &gt; git reset --mixed HEAD^
665 </literallayout> 482 </literallayout>
666 </para> 483 </para>
667 484
668 <para> 485 <para>
669 You can create branches, "cherry-pick" changes or perform any number of Git 486 You can create branches, "cherry-pick" changes, or perform any number of Git
670 operations until the commits are in good order for pushing upstream 487 operations until the commits are in good order for pushing upstream
671 or for pull requests. 488 or for pull requests.
672 After a push or pull, commits are normally considered 489 After a <filename>push</filename> or <filename>pull</filename> command,
490 commits are normally considered
673 "permanent" and you should not modify them. 491 "permanent" and you should not modify them.
674 If they need to be changed you can incrementally do so with new commits. 492 If the commits need to be changed, you can incrementally do so with new commits.
675 These practices follow the standard Git workflow and the kernel.org best 493 These practices follow standard Git workflow and the <filename>kernel.org</filename> best
676 practices, which Yocto Project recommends. 494 practices, which Yocto Project recommends.
495 <note>
496 It is recommended to tag or branch before adding changes to a Yocto Project
497 BSP or before creating a new one.
498 The reason for this recommendation is because the branch or tag provides a
499 reference point to facilitate locating and exporting local changes.
500 </note>
677 </para> 501 </para>
678
679 <note><para>
680 It is recommended to tag or branch before adding changes to a Yocto Project
681 BSP or before creating a new one.
682 The reason for this recommendation is because the branch or tag provides a
683 reference point to facilitate locating and exporting local changes.
684 </para></note>
685 502
686 <section id='export-internally-via-patches'> 503 <section id='export-internally-via-patches'>
687 <title>Exporting Changes Internally by Using Patches</title> 504 <title>Exporting Changes Internally by Using Patches</title>
@@ -699,27 +516,23 @@ repository.
699 Once the directory is created, you can apply it to a repository using the 516 Once the directory is created, you can apply it to a repository using the
700 <filename>git am</filename> command to reproduce the original commit and all 517 <filename>git am</filename> command to reproduce the original commit and all
701 the related information such as author, date, commit log, and so forth. 518 the related information such as author, date, commit log, and so forth.
702 </para> 519 <note>
703 520 The new commit identifiers (ID) will be generated upon re-application.
704 <note><para> 521 This action reflects that the commit is now applied to an underlying commit
705 The new commit identifiers (ID) will be generated upon re-application. 522 with a different ID.
706 This action reflects that the commit is now applied to an underlying commit 523 </note>
707 with a different ID. 524 <literallayout class='monospaced'>
708 </para></note>
709
710 <para>
711 <literallayout class='monospaced'>
712 # &lt;first-commit&gt; can be a tag if one was created before development 525 # &lt;first-commit&gt; can be a tag if one was created before development
713 # began. It can also be the parent branch if a branch was created 526 # began. It can also be the parent branch if a branch was created
714 # before development began. 527 # before development began.
715 528
716 &gt; git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt; 529 &gt; git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
717 </literallayout> 530 </literallayout>
718 </para> 531 </para>
719 532
720 <para> 533 <para>
721 In other words: 534 In other words:
722 <literallayout class='monospaced'> 535 <literallayout class='monospaced'>
723 # Identify commits of interest. 536 # Identify commits of interest.
724 537
725 # If the tree was tagged before development 538 # If the tree was tagged before development
@@ -731,13 +544,8 @@ repository.
731 &gt; git whatchanged # identify last commit 544 &gt; git whatchanged # identify last commit
732 &gt; git format-patch -o &lt;save dir&gt; &lt;commit id&gt; 545 &gt; git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
733 &gt; git format-patch -o &lt;save dir&gt; &lt;rev-list&gt; 546 &gt; git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
734 </literallayout> 547 </literallayout>
735 </para> 548 </para>
736
737 <!--<para>
738 See the "template patching" example for how to use the patches to
739 automatically apply to a new kernel build.
740 </para>-->
741 </section> 549 </section>
742 550
743 <section id='export-internally-via-git'> 551 <section id='export-internally-via-git'>
@@ -746,44 +554,38 @@ repository.
746 <para> 554 <para>
747 This section describes how you can export changes from a working directory 555 This section describes how you can export changes from a working directory
748 by pushing the changes into a master repository or by making a pull request. 556 by pushing the changes into a master repository or by making a pull request.
749 Once you have pushed the changes in the master repository you can then 557 Once you have pushed the changes in the master repository, you can then
750 pull those same changes into a new kernel build at a later time. 558 pull those same changes into a new kernel build at a later time.
751 </para> 559 </para>
752 560
753 <para> 561 <para>
754 Use this command form to push the changes: 562 Use this command form to push the changes:
755 <literallayout class='monospaced'> 563 <literallayout class='monospaced'>
756 &gt; git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt; 564 &gt; git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
757 &lt;local_branch&gt;:&lt;remote_branch&gt; 565 &lt;local_branch&gt;:&lt;remote_branch&gt;
758 </literallayout> 566 </literallayout>
759 </para> 567 </para>
760 568
761 <para> 569 <para>
762 For example, the following command pushes the changes from your local branch 570 For example, the following command pushes the changes from your local branch
763 <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name 571 <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
764 in the master repository <filename>//git.mycompany.com/pub/git/kernel-2.6.37</filename>. 572 in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.0</filename>.
765 <literallayout class='monospaced'> 573 <literallayout class='monospaced'>
766 &gt; git push ssh://git.mycompany.com/pub/git/kernel-2.6.37 \ 574 &gt; git push ssh://git.mycompany.com/pub/git/kernel-3.0 \
767 yocto/standard/common-pc/base:yocto/standard/common-pc/base 575 yocto/standard/common-pc/base:yocto/standard/common-pc/base
768 </literallayout> 576 </literallayout>
769 </para> 577 </para>
770 578
771 <para> 579 <para>
772 A pull request entails using <filename>git request-pull</filename> to compose an email to the 580 A pull request entails using <filename>git request-pull</filename> to compose
581 an email to the
773 maintainer requesting that a branch be pulled into the master repository, see 582 maintainer requesting that a branch be pulled into the master repository, see
774 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example. 583 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
584 <note>
585 Other commands such as <filename>git stash</filename> or branching can also be used to save
586 changes, but are not covered in this document.
587 </note>
775 </para> 588 </para>
776
777 <note><para>
778 Other commands such as <filename>git stash</filename> or branching can also be used to save
779 changes, but are not covered in this document.
780 </para></note>
781
782 <!--<para>
783 See the section "importing from another SCM" for how a Git push to the
784 default_kernel, can be used to automatically update the builds of all users
785 of a central Git repository.
786 </para>-->
787 </section> 589 </section>
788 </section> 590 </section>
789 591
@@ -794,26 +596,29 @@ repository.
794 This section describes how to export changes for external upstream submission. 596 This section describes how to export changes for external upstream submission.
795 If the patch series is large or the maintainer prefers to pull 597 If the patch series is large or the maintainer prefers to pull
796 changes, you can submit these changes by using a pull request. 598 changes, you can submit these changes by using a pull request.
797 However, it is common to sent patches as an email series. 599 However, it is common to send patches as an email series.
798 This method allows easy review and integration of the changes. 600 This method allows easy review and integration of the changes.
601 <note>
602 Before sending patches for review be sure you understand the
603 community standards for submitting and documenting changes and follow their best practices.
604 For example, kernel patches should follow standards such as:
605 <itemizedlist>
606 <listitem><para>
607 <ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem>
608 <listitem><para>
609 <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
610 <listitem><para>Documentation/SubmittingPatches (in any linux
611 kernel source tree)</para></listitem>
612 </itemizedlist>
613 </note>
799 </para> 614 </para>
800 615
801 <note><para>
802 Before sending patches for review be sure you understand the
803 community standards for submitting and documenting changes and follow their best practices.
804 For example, kernel patches should follow standards such as:
805 <itemizedlist>
806 <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem>
807 <listitem><para><ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
808 <listitem><para>Documentation/SubmittingPatches (in any linux kernel source tree)</para></listitem>
809 </itemizedlist>
810 </para></note>
811
812 <para> 616 <para>
813 The messages used to commit changes are a large part of these standards. 617 The messages used to commit changes are a large part of these standards.
814 Consequently, be sure that the headers for each commit have the required information. 618 Consequently, be sure that the headers for each commit have the required information.
815 If the initial commits were not properly documented or do not meet those standards, 619 If the initial commits were not properly documented or do not meet those standards,
816 you can re-base by using the <filename>git rebase -i</filename> command to manipulate the commits and 620 you can re-base by using the <filename>git rebase -i</filename> command to
621 manipulate the commits and
817 get them into the required format. 622 get them into the required format.
818 Other techniques such as branching and cherry-picking commits are also viable options. 623 Other techniques such as branching and cherry-picking commits are also viable options.
819 </para> 624 </para>
@@ -821,13 +626,14 @@ repository.
821 <para> 626 <para>
822 Once you complete the commits, you can generate the email that sends the patches 627 Once you complete the commits, you can generate the email that sends the patches
823 to the maintainer(s) or lists that review and integrate changes. 628 to the maintainer(s) or lists that review and integrate changes.
824 The command <filename>git send-email</filename> is commonly used to ensure that patches are properly 629 The command <filename>git send-email</filename> is commonly used to ensure
630 that patches are properly
825 formatted for easy application and avoid mailer-induced patch damage. 631 formatted for easy application and avoid mailer-induced patch damage.
826 </para> 632 </para>
827 633
828 <para> 634 <para>
829 The following is an example of dumping patches for external submission: 635 The following is an example of dumping patches for external submission:
830 <literallayout class='monospaced'> 636 <literallayout class='monospaced'>
831 # dump the last 4 commits 637 # dump the last 4 commits
832 &gt; git format-patch --thread -n -o ~/rr/ HEAD^^^^ 638 &gt; git format-patch --thread -n -o ~/rr/ HEAD^^^^
833 &gt; git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \ 639 &gt; git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
@@ -835,7 +641,7 @@ repository.
835 --cc list@yoctoproject.org ~/rr 641 --cc list@yoctoproject.org ~/rr
836 # the editor is invoked for the 0/N patch, and when complete the entire 642 # the editor is invoked for the 0/N patch, and when complete the entire
837 # series is sent via email for review 643 # series is sent via email for review
838 </literallayout> 644 </literallayout>
839 </para> 645 </para>
840 </section> 646 </section>
841 647
@@ -844,12 +650,12 @@ repository.
844 650
845 <para> 651 <para>
846 When you want to export changes for import into another 652 When you want to export changes for import into another
847 Source Code Manager (SCM) you can use any of the previously discussed 653 Source Code Manager (SCM), you can use any of the previously discussed
848 techniques. 654 techniques.
849 However, if the patches are manually applied to a secondary tree and then 655 However, if the patches are manually applied to a secondary tree and then
850 that tree is checked into the SCM you can lose change information such as 656 that tree is checked into the SCM, you can lose change information such as
851 commit logs. 657 commit logs.
852 Yocto Project does not recommend this process. 658 The Yocto Project does not recommend this process.
853 </para> 659 </para>
854 660
855 <para> 661 <para>
@@ -864,16 +670,16 @@ repository.
864 <title>Working with the Yocto Project Kernel in Another SCM</title> 670 <title>Working with the Yocto Project Kernel in Another SCM</title>
865 671
866 <para> 672 <para>
867 This section describes kernel development in another SCM, which is not the same 673 This section describes kernel development in an SCM other than Git,
868 as exporting changes to another SCM. 674 which is not the same as exporting changes to another SCM described earlier.
869 For this scenario you use the Yocto Project build system to 675 For this scenario, you use the Yocto Project build system to
870 develop the kernel in a different SCM. 676 develop the kernel in a different SCM.
871 The following must be true for you to accomplish this: 677 The following must be true for you to accomplish this:
872 <itemizedlist> 678 <itemizedlist>
873 <listitem><para>The delivered Yocto Project kernel must be exported into the second 679 <listitem><para>The delivered Yocto Project kernel must be exported into the second
874 SCM.</para></listitem> 680 SCM.</para></listitem>
875 <listitem><para>Development must be exported from that secondary SCM into a 681 <listitem><para>Development must be exported from that secondary SCM into a
876 format that can be used by the Yocto Project build system.</para></listitem> 682 format that can be used by the Yocto Project build system.</para></listitem>
877 </itemizedlist> 683 </itemizedlist>
878 </para> 684 </para>
879 685
@@ -881,7 +687,7 @@ repository.
881 <title>Exporting the Delivered Kernel to the SCM</title> 687 <title>Exporting the Delivered Kernel to the SCM</title>
882 688
883 <para> 689 <para>
884 Depending on the SCM it might be possible to export the entire Yocto Project 690 Depending on the SCM, it might be possible to export the entire Yocto Project
885 kernel Git repository, branches and all, into a new environment. 691 kernel Git repository, branches and all, into a new environment.
886 This method is preferred because it has the most flexibility and potential to maintain 692 This method is preferred because it has the most flexibility and potential to maintain
887 the meta data associated with each commit. 693 the meta data associated with each commit.
@@ -894,12 +700,13 @@ repository.
894 700
895 <para> 701 <para>
896 The following commands illustrate some of the steps you could use to 702 The following commands illustrate some of the steps you could use to
897 import the yocto/standard/common-pc/base kernel into a secondary SCM: 703 import the <filename>yocto/standard/common-pc/base</filename>
898 <literallayout class='monospaced'> 704 kernel into a secondary SCM:
705 <literallayout class='monospaced'>
899 &gt; git checkout yocto/standard/common-pc/base 706 &gt; git checkout yocto/standard/common-pc/base
900 &gt; cd .. ; echo linux/.git &gt; .cvsignore 707 &gt; cd .. ; echo linux/.git &gt; .cvsignore
901 &gt; cvs import -m "initial import" linux MY_COMPANY start 708 &gt; cvs import -m "initial import" linux MY_COMPANY start
902 </literallayout> 709 </literallayout>
903 </para> 710 </para>
904 711
905 <para> 712 <para>
@@ -908,13 +715,13 @@ repository.
908 715
909 <para> 716 <para>
910 The following commands illustrate how you can condense and merge two BSPs into a second SCM: 717 The following commands illustrate how you can condense and merge two BSPs into a second SCM:
911 <literallayout class='monospaced'> 718 <literallayout class='monospaced'>
912 &gt; git checkout yocto/standard/common-pc/base 719 &gt; git checkout yocto/standard/common-pc/base
913 &gt; git merge yocto/standard/common-pc-64/base 720 &gt; git merge yocto/standard/common-pc-64/base
914 # resolve any conflicts and commit them 721 # resolve any conflicts and commit them
915 &gt; cd .. ; echo linux/.git &gt; .cvsignore 722 &gt; cd .. ; echo linux/.git &gt; .cvsignore
916 &gt; cvs import -m "initial import" linux MY_COMPANY start 723 &gt; cvs import -m "initial import" linux MY_COMPANY start
917 </literallayout> 724 </literallayout>
918 </para> 725 </para>
919 </section> 726 </section>
920 727
@@ -924,112 +731,12 @@ repository.
924 <para> 731 <para>
925 Once development has reached a suitable point in the second development 732 Once development has reached a suitable point in the second development
926 environment, you need to export the changes as patches. 733 environment, you need to export the changes as patches.
927 To export them place the changes in a recipe and 734 To export them, place the changes in a recipe and
928 automatically apply them to the kernel during patching. 735 automatically apply them to the kernel during patching.
929 </para> 736 </para>
930<!--<para>
931If changes are imported directly into Git, they must be propagated to the
932wrll-linux-2.6.27/git/default_kernel bare clone of each individual build
933to be present when the kernel is checked out.
934</para>
935<para>
936The following example illustrates one variant of this workflow:
937<literallayout class='monospaced'>
938 # on master Git repository
939 &gt; cd linux-2.6.27
940 &gt; git tag -d common_pc-standard-mark
941 &gt; git pull ssh://&lt;foo&gt;@&lt;bar&gt;/pub/git/kernel-2.6.27 common_pc-standard:common_pc-standard
942 &gt; git tag common_pc-standard-mark
943
944 # on each build machine (or NFS share, etc)
945 &gt; cd wrll-linux-2.6.27/git/default_kernel
946 &gt; git fetch ssh://&lt;foo&gt;@&lt;master server&gt;/pub/git/kernel-2.6.27
947
948 # in the build, perform a from-scratch build of Linux and the new changes
949 # will be checked out and built.
950 &gt; make linux
951</literallayout>
952</para> -->
953 </section> 737 </section>
954 </section> 738 </section>
955 739
956<!-- <section id='bsp-template-migration-from-2'>
957 <title>BSP: Template Migration from 2.0</title>
958<para>
959The move to a Git-backed kernel build system in 3.0 introduced a small new
960requirement for any BSP that is not integrated into the GA release of the
961product: branching information.
962</para>
963<para>
964As was previously mentioned in the background sections, branching information
965is always required, since the kernel build system cannot make intelligent
966branching decisions and must rely on the developer. This branching
967information is provided via a .scc file.
968</para>
969<para>
970A BSP template in 2.0 contained build system information (config.sh, etc) and
971kernel patching information in the 'linux' subdirectory. The same holds true
972in 3.0, with only minor changes in the kernel patching directory.
973The ".smudge" files are now ".scc" files and now contain a full description
974 of the kernel branching, patching and configuration for the BSP. Where in
975 2.0, they only contained kernel patching information.
976</para>
977<para>
978The following illustrates the migration of a simple 2.0 BSP template to the
979new 3.0 kernel build system.
980</para>
981<note><para>
982Note: all operations are from the root of a customer layer.
983</para></note>
984<literallayout class='monospaced'>
985 templates/
986 `&dash;&dash; board
987 `&dash;&dash; my_board
988 |&dash;&dash; config.sh
989 |&dash;&dash; include
990 `&dash;&dash; linux
991 `&dash;&dash; 2.6.x
992 |&dash;&dash; knl-base.cfg
993 |&dash;&dash; bsp.patch
994 `&dash;&dash; my_bsp.smudge
995
996 &gt; mv templates/board/my_board/linux/2.6.x/* templates/board/my_board/linux
997 &gt; rm -rf templates/board/my_board/linux/2.6.x/
998 &gt; mv templates/board/my_board/linux/my_bsp.smudge \
999 templates/board/my_board/linux/my_bsp-standard.scc
1000 &gt; echo "kconf hardware knl-base.cfg" &gt;&gt; \
1001 templates/board/my_board/linux/my_bsp-standard.scc
1002 &gt; vi templates/board/my_board/linux/my_bsp-standard.scc
1003 # add the following at the top of the file
1004 scc_leaf ktypes/standard my_bsp-standard
1005
1006 templates/
1007 `&dash;&dash; board
1008 `&dash;&dash; my_board
1009 |&dash;&dash; config.sh
1010 |&dash;&dash; include
1011 `&dash;&dash; linux
1012 |&dash;&dash; knl-base.cfg
1013 |&dash;&dash; bsp.patch
1014 `&dash;&dash; my_bsp-standard.scc
1015</literallayout>
1016<para>
1017That's it. Configure and build.
1018</para>
1019<note><para>There is a naming convention for the .scc file, which allows the build
1020 system to locate suitable feature descriptions for a board:
1021</para></note>
1022<literallayout class='monospaced'>
1023 &lt;bsp name&gt;-&lt;kernel type&gt;.scc
1024</literallayout>
1025<para>
1026 if this naming convention isn't followed your feature description will
1027 not be located and a build error thrown.
1028</para>
1029 </section> -->
1030
1031
1032
1033 <section id='bsp-creating'> 740 <section id='bsp-creating'>
1034 <title>Creating a BSP Based on an Existing Similar BSP</title> 741 <title>Creating a BSP Based on an Existing Similar BSP</title>
1035 742
@@ -1037,19 +744,21 @@ That's it. Configure and build.
1037 This section overviews the process of creating a BSP based on an 744 This section overviews the process of creating a BSP based on an
1038 existing similar BSP. 745 existing similar BSP.
1039 The information is introductory in nature and does not provide step-by-step examples. 746 The information is introductory in nature and does not provide step-by-step examples.
1040 For detailed information on how to create a BSP given an existing similar BSP 747 For detailed information on how to create a BSP given an existing similar BSP, see
1041 see the Yocto Project Development Manual [NEED LINK] or the 748 the "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#dev-manual-bsp-appendix'>BSP Development Example</ulink>" appendix in
1042 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'></ulink> 749 <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The
750 Yocto Project Development Manual</ulink>, or see the
751 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
1043 wiki page. 752 wiki page.
1044 </para> 753 </para>
1045 754
1046 <para> 755 <para>
1047 The basic steps you need to follow are: 756 The basic steps you need to follow are:
1048 <orderedlist> 757 <orderedlist>
1049 <listitem><para>Make sure you have the Yocto Project source tree available. 758 <listitem><para><emphasis>Make sure you have the Yocto Project source tree available:</emphasis>
1050 You should either create a Yocto Project Git repository (recommended), or 759 You should either create a Yocto Project Git repository (recommended), or
1051 you should get the Yocto Project release tarball and extract it.</para></listitem> 760 you should get the Yocto Project release tarball and extract it.</para></listitem>
1052 <listitem><para>Choose an existing BSP available with the Yocto Project. 761 <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
1053 Try to map your board features as closely to the features of a BSP that is 762 Try to map your board features as closely to the features of a BSP that is
1054 already supported and exists in the Yocto Project. 763 already supported and exists in the Yocto Project.
1055 Starting with something as close as possible to your board makes developing 764 Starting with something as close as possible to your board makes developing
@@ -1057,13 +766,14 @@ That's it. Configure and build.
1057 You can find all the BSPs that are supported and ship with the Yocto Project 766 You can find all the BSPs that are supported and ship with the Yocto Project
1058 on the Yocto Project's Download page at 767 on the Yocto Project's Download page at
1059 <ulink url='http://www.yoctoproject.org/download'></ulink>.</para></listitem> 768 <ulink url='http://www.yoctoproject.org/download'></ulink>.</para></listitem>
1060 <listitem><para>Be sure you have the Base BSP. 769 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
1061 You need to either have the Yocto Project Git repository set up or download 770 You need to either have the Yocto Project Git repository set up or download
1062 the tarball of the base BSP. 771 the tarball of the base BSP.
1063 Either method gives you access to the BSP source files.</para></listitem> 772 Either method gives you access to the BSP source files.</para></listitem>
1064 <listitem><para>Make a copy of the existing BSP, thus isolating your new BSP work. 773 <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
774 BSP work:</emphasis>
1065 Copying the existing BSP structure gives you a new area in which to work.</para></listitem> 775 Copying the existing BSP structure gives you a new area in which to work.</para></listitem>
1066 <listitem><para>Make configuration and recipe changes to your new BSP. 776 <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
1067 Configuration changes involve the files in the BSP's <filename>conf</filename> 777 Configuration changes involve the files in the BSP's <filename>conf</filename>
1068 directory. 778 directory.
1069 Changes include creating a machine-specific configuration file and editing the 779 Changes include creating a machine-specific configuration file and editing the
@@ -1071,13 +781,13 @@ That's it. Configure and build.
1071 The configuration changes identify the kernel you will be using. 781 The configuration changes identify the kernel you will be using.
1072 Recipe changes include removing, modifying, or adding new recipe files that 782 Recipe changes include removing, modifying, or adding new recipe files that
1073 instruct the build process on what features to include in the image.</para></listitem> 783 instruct the build process on what features to include in the image.</para></listitem>
1074 <listitem><para>Prepare for the build. 784 <listitem><para><emphasis>Prepare for the build:</emphasis>
1075 Before you actually initiate the build you need to set up the build environment 785 Before you actually initiate the build, you need to set up the build environment
1076 by sourcing the environment initialization script. 786 by sourcing the environment initialization script.
1077 After setting up the environment you need to make some build configuration 787 After setting up the environment, you need to make some build configuration
1078 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename> 788 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
1079 files.</para></listitem> 789 files.</para></listitem>
1080 <listitem><para>Build the image. 790 <listitem><para><emphasis>Build the image:</emphasis>
1081 The Yocto Project uses the BitBake tool to create the image. 791 The Yocto Project uses the BitBake tool to create the image.
1082 You need to decide on the type of image you are going to build (e.g. minimal, base, 792 You need to decide on the type of image you are going to build (e.g. minimal, base,
1083 core, sato, and so forth) and then start the build using the <filename>bitbake</filename> 793 core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
@@ -1086,746 +796,6 @@ That's it. Configure and build.
1086 </para> 796 </para>
1087 </section> 797 </section>
1088 798
1089
1090<!--
1091 <section id='bsp-creating-bsp-without-a-local-kernel-repo'>
1092 <title>Creating a BSP Based on an Existing Similar BSP Without a Local Kernel Repository</title>
1093
1094 <para>
1095 If you are creating a BSP based on an existing similar BSP but you do not have
1096 a local kernel repository, the process is very similar to the process in
1097 the previous section (<xref linkend='bsp-creating'/>).
1098 </para>
1099
1100 <para>
1101 Follow the exact same process as described in the previous section with
1102 these slight modifications:
1103 </para>
1104 <orderedlist>
1105 <listitem><para>Perform Step 1 as is from the previous section.</para></listitem>
1106 <listitem><para>Perform Step 2 as is from the previous section.</para></listitem>
1107 <listitem><para>Perform Step 3 but do not modify the
1108 KSRC line in the bbappend file.</para></listitem>
1109 <listitem><para>Edit the <filename>local.conf</filename> so
1110 that it contains the following:
1111 <literallayout class='monospaced'>
1112 YOCTO_KERNEL_EXTERNAL_BRANCH="&lt;your-machine&gt;-standard
1113 </literallayout></para>
1114 <para>Adding this statement to the file triggers BSP bootstrapping
1115 to occur and the correct branches and base configuration to be used.
1116 </para></listitem>
1117 <listitem><para>Perform Step 4 as is from the previous section.</para></listitem>
1118 <listitem><para>Perform Step 5 as is from the previous section.</para></listitem>
1119 </orderedlist>
1120 </section>
1121
1122
1123
1124 <section id='bsp-creating-a-new-bsp'>
1125 <title>BSP: Creating a New BSP</title>
1126<para>
1127Although it is obvious that the structure of a new BSP uses the migrated
1128directory structure from the previous example,the first question is whether
1129or not the BSP is started from scratch.
1130</para>
1131<para>
1132If Yocto Project has a similar BSP, it is often easier to clone and update,
1133rather than start from scratch. If the mainline kernel has support, it is
1134easier to branch from the -standard kernel and begin development (and not be
1135concerned with undoing existing changes). This section covers both options.
1136</para>
1137<para>
1138In almost every scenario, the LDAT build system bindings must be completed
1139before either cloning or starting a new BSP from scratch. This is simply
1140because the board template files are required to configure a project/build
1141and create the necessary environment to begin working directly with the
1142kernel. If it is desired to start immediately with kernel development and
1143then add LDAT bindings, see the "bootstrapping a BSP" section.
1144</para>
1145 <section id='creating-from-scratch'>
1146 <title>Creating the BSP from Scratch</title>
1147<para>
1148To create the BSP from scratch you need to do the following:
1149<orderedlist>
1150 <listitem><para>Create a board template for the new BSP in a layer.</para></listitem>
1151 <listitem><para>Configure a build with the board.</para></listitem>
1152 <listitem><para>Configure a kernel.</para></listitem>
1153</orderedlist>
1154</para>
1155<para>
1156Following is an example showing all three steps. You start by creating a board template for the new BSP in a layer.
1157<literallayout class='monospaced'>
1158 templates/
1159 `&dash;&dash; board
1160 `&dash;&dash; my_bsp
1161 |&dash;&dash; include
1162 |&dash;&dash; config.sh
1163 `&dash;&dash; linux
1164 |&dash;&dash; my_bsp.cfg
1165 `&dash;&dash; my_bsp-standard.scc
1166
1167 &gt; cat config.sh
1168 TARGET_BOARD="my_bsp"
1169 TARGET_LINUX_LINKS="bzImage"
1170 TARGET_SUPPORTED_KERNEL="standard"
1171 TARGET_SUPPORTED_ROOTFS="glibc_std"
1172 BANNER="This BSP is *NOT* supported"
1173 TARGET_PROCFAM="pentium4"
1174 TARGET_PLATFORMS="GPP"
1175
1176 &gt; cat include
1177 cpu/x86_32_i686
1178 karch/i386
1179
1180 &gt; cat linux/my_bsp-standard.scc
1181 scc_leaf ktypes/standard/standard.scc my_bsp-standard
1182
1183 &gt; cat linux/my_bsp.cfg
1184 CONFIG_X86=y
1185 CONFIG_SMP=y
1186 CONFIG_VT=y
1187 # etc, etc, etc
1188</literallayout>
1189</para>
1190<para>
1191Something like the following can now be added to a board build, and
1192a project can be started:
1193<literallayout class='monospaced'>
1194 &dash;&dash;enable-board=my_bsp \
1195 &dash;&dash;with-layer=custom_bsp
1196</literallayout>
1197</para>
1198<para>
1199Now you can configure a kernel:
1200<literallayout class='monospaced'>
1201 &gt; make -C build linux.config
1202</literallayout>
1203</para>
1204<para>
1205You now have a kernel tree, which is branched and has no patches, ready for
1206development.
1207</para>
1208 </section> -->
1209
1210<!-- <section id='cloning-an-existing-bsp'>
1211 <title>Cloning an Existing BSP</title>
1212<para>
1213Cloning an existing BSP from the shipped product is similar to the "from
1214scratch" option and there are two distinct ways to achieve this goal:
1215<itemizedlist>
1216 <listitem><para>Create a board template for the new BSP in a layer.</para></listitem>
1217 <listitem><para>Clone the .scc and board config.</para></listitem>
1218</itemizedlist>
1219</para>
1220<para>
1221The first method is similar to the from scratch BSP where you create a board template for the new
1222BSP. Although in this case, copying an existing board template from
1223wrll-wrlinux/templates/board would be appropriate, since we are cloning an
1224existing BSP. Edit the config.sh, include and other board options for the new
1225BSP.
1226</para>
1227<para>
1228The second method is to clone the .scc and board config.
1229To do this, in the newly created board template, create a linux subdirectory and export
1230the .scc and configuration from the source BSP in the published Yocto Project
1231kernel. During construction, all of the configuration and patches were
1232captured, so it is simply a matter of extracting them.
1233</para>
1234<para>
1235Extraction can be accomplished using four different techniques:
1236<itemizedlist>
1237 <listitem><para>Config and patches from the bare default_kernel.</para></listitem>
1238 <listitem><para>Clone default_kernel and checkout wrs_base.</para></listitem>
1239 <listitem><para>Clone default_kernel and checkout BSP branch.</para></listitem>
1240 <listitem><para>Branch from the Yocto Project BSP.</para></listitem>
1241</itemizedlist>
1242</para>
1243<para>
1244Technique 1: config and patches from the bare default_kernel
1245<literallayout class='monospaced'>
1246 &gt; cd layers/wrll-linux-2.6.27/git/default_kernel
1247 &gt; git show checkpoint_end | filterdiff -i '*common_pc*' | patch -s -p2 -d /tmp
1248
1249 # This will create two directories: cfg and patches.
1250
1251 &gt; cd /tmp/cfg/kernel-cache/bsp/common_pc/
1252
1253 # This directory contains all the patches and .scc files used to construct
1254 # the BSP in the shipped tree. Copy the patches to the new BSP template,
1255 # and add them to the .scc file created above. See "template patching" if
1256 # more details are required.
1257</literallayout>
1258</para>
1259<para>
1260Technique 2: clone default_kernel and checkout wrs_base
1261<literallayout class='monospaced'>
1262 &gt; git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27
1263 &gt; cd windriver-2.6.27
1264 &gt; git checkout wrs_base
1265 &gt; cd wrs/cfg/kernel-cache/bsp/common_pc
1266
1267# again, this directory has all the patches and .scc files used to construct
1268# the BSP
1269</literallayout>
1270</para>
1271<para>
1272Technique 3: clone default_kernel and checkout BSP branch
1273<literallayout class='monospaced'>
1274 &gt; git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27
1275 &gt; cd windriver-2.6.27
1276 &gt; git checkout common_pc-standard
1277 &gt; git whatchanged
1278 # browse patches and determine which ones are of interest, say there are
1279 # 3 patches of interest
1280 &gt; git format-patch -o &lt;path to BSP template&gt;/linux HEAD^^^
1281 # update the .scc file to add the patches, see "template patches" if
1282 # more details are required
1283</literallayout>
1284</para>
1285<para>
1286Technique #4: branch from the Yocto Project BSP
1287<note><para>This is potentially the most "different" technique, but is actually
1288 the easiest to support and leverages the infrastructure. rtcore BSPs
1289 are created in a similar manner to this.
1290</para></note>
1291</para>
1292<para>
1293In this technique the .scc file in the board template is slightly different
1294 and indicates that the BSP should branch after the base Yocto Project BSP
1295 of the correct kernel type, so to start a new BSP that inherits the
1296 kernel patches of the common_pc-standard, the following would be done:
1297<literallayout class='monospaced'>
1298 &gt; cat linux/my_bsp-standard.scc
1299 scc_leaf bsp/common_pc/common_pc-standard.scc my_bsp-standard
1300</literallayout>
1301</para>
1302<para>
1303 And only kernel configuration (not patches) need be contained in the
1304 board template.
1305</para>
1306<para>
1307 This has the advantage of automatically picking up updates to the BSP
1308 and not duplicating any patches for a similar board.
1309</para>
1310 </section> -->
1311
1312 <!-- <section id='bsp-bootstrapping'>
1313 <title>BSP: Bootstrapping</title>
1314<para>
1315The previous examples created the board templates and configured a build
1316before beginning work on a new BSP. It is also possible for advanced users to
1317simply treat the Yocto Project Git repository as an upstream source and begin
1318BSP development directly on the repository. This is the closest match to how
1319the kernel community at large would operate.
1320</para>
1321<para>
1322Two techniques exist to accomplish this:
1323</para>
1324<para>
1325Technique 1: upstream workflow
1326<literallayout class='monospaced'>
1327 &gt; git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27
1328 &gt; cd windriver-2.6.27
1329 &gt; git checkout -b my_bsp-standard common_pc-standard
1330
1331 # edit files, import patches, generally do BSP development
1332
1333 # at this point we can create the BSP template, and export the kernel
1334 # changes using one of the techniques discussed in that section. For
1335 # example, It is possible to push these changes, directly into the
1336 # default_kernel and never directly manipulate or export patch files
1337</literallayout>
1338</para>
1339<para>
1340Technique 2: Yocto Project kernel build workflow
1341</para>
1342<para>
1343 Create the BSP branch from the appropriate kernel type
1344<literallayout class='monospaced'>
1345 &gt; cd linux
1346 # the naming convention for auto-build is &lt;bsp&gt;-&lt;kernel type&gt;
1347 &gt; git checkout -b my_bsp-standard standard
1348</literallayout>
1349</para>
1350<para>
1351Make changes, import patches, etc.
1352<literallayout class='monospaced'>
1353 &gt; ../../host-cross/bin/guilt init
1354 # 'wrs/patches/my_bsp-standard' has now been created to
1355 # manage the branches patches
1356
1357 # option 1: edit files, guilt import
1358 &gt; ../../host-cross/bin/guilt new extra-version.patch
1359 &gt; vi Makefile
1360 &gt; ../../host-cross/bin/guilt refresh
1361 # add a header
1362 &gt; ../../host-cross/bin/guilt header -e
1363 # describe the patch using best practices, like the example below:
1364
1365 &dash;&dash;&dash;&gt;&dash;&dash;&dash;&gt;&dash;&dash;&dash;&gt; cut here
1366 From: Bruce Ashfield &lt;bruce.ashfield@windriver.com&gt;
1367
1368 Adds an extra version to the kernel
1369
1370 Modify the main EXTRAVERSION to show our bsp name
1371
1372 Signed-off-by: Bruce Ashfield &lt;bruce.ashfield@windriver.com&gt;
1373 &dash;&dash;&dash;&gt;&dash;&dash;&dash;&gt;&dash;&dash;&dash;&gt; cut here
1374
1375 # option 2: import patches
1376 &gt; git am &lt;patch&gt;
1377 or
1378 &gt; git apply &lt;patch&gt;
1379 &gt; git add &lt;files&gt;
1380 &gt; git commit -s
1381
1382 # configure the board, save relevant options
1383 &gt; make ARCH=&lt;arch&gt; menuconfig
1384
1385 # save the cfg changes for reconfiguration
1386 &gt; mkdir wrs/cfg/&lt;cache&gt;/my_bsp
1387 &gt; vi wrs/cfg/&lt;cache&gt;/my_bsp/my_bsp.cfg
1388
1389 # classify the patches
1390 &gt; ../../host-cross/bin/kgit classify create &lt;kernel-foo-cache&gt;/my_bsp/my_bsp
1391 # test build
1392 &gt; cd ..
1393 &gt; make linux TARGET_BOARD=my_bsp kprofile=my_bsp use_current_branch=1
1394</literallayout>
1395</para>
1396<para>
1397 Assuming the patches have been exported to the correct location, Future
1398 builds will now find the board, apply the patches to the base tree and make
1399 the relevant branches and structures and the special build options are no
1400 longer required.
1401</para>
1402 </section>
1403 </section> -->
1404
1405<!-- <section id='patching'>
1406 <title>Patching</title>
1407<para>
1408The most common way to apply patches to the kernel is via a template.
1409However, for more advanced applications (such as the sharing of patches between
1410multiple sub-features) it is possible to patch the kernel-cache.
1411This section covers both scenarios.
1412</para>
1413 <section id='patching-template'>
1414 <title>Patching: Template</title>
1415<para>
1416kernel
1417templates follow the same rules as any LDAT template. A directory should be
1418created in a recognized template location, with a 'linux' subdirectory. The
1419'linux' directory triggers LDAT to pass the dir as a potential patch location
1420to the kernel build system. Any .scc files found in that directory, will be
1421automatically appended to the end of the BSP branch (for the configured
1422board).
1423</para>
1424<para>
1425This behavior is essentially the same since previous product
1426releases. The only exception is the use of ".scc", which allows kernel
1427configuration AND patches to be applied in a template.
1428</para>
1429<note><para>
1430If creating a full template is not required, a .scc file can be placed at
1431the top of the build, along with configuration and patches. The build
1432system will pickup the .scc and add it onto the patch list automatically
1433</para></note>
1434<para>
1435As an example, consider a simple template to update a BP:
1436<literallayout class='monospaced'>
1437 &gt; cat templates/feature/extra_version/linux/extra_version.scc
1438 patch 0001-extraversion-add-Wind-River-identifier.patch
1439</literallayout>
1440</para>
1441<para>
1442To illustrate how the previous template patch was created, the following
1443steps were performed:
1444<literallayout class='monospaced'>
1445 &gt; cd &lt;board build&gt;/build/linux
1446 &gt; vi Makefile
1447 # modify EXTRAVERSION to have a unique string
1448 &gt; git commit -s -m "extraversion: add Yocto Project identifier" Makefile
1449 &gt; git format-patch -o &lt;path to layer&gt;/templates/feature/extra_version/linux/
1450 &gt; echo "patch 0001-extraversion-add-Wind-River-identifier.patch" &gt; \
1451 &lt;path to layer&gt;/templates/feature/extra_version/linux/extra_version.scc
1452</literallayout>
1453</para>
1454<para>
1455This next example creates a template with a linux subdirectory, just as we
1456 always have for previous releases.
1457<literallayout class='monospaced'>
1458 &gt; mkdir templates/features/my_feature/linux
1459</literallayout>
1460</para>
1461<para>
1462 In that directory place your feature description, your
1463 patch and configuration (if required).
1464<literallayout class='monospaced'>
1465 &gt; ls templates/features/my_feature/linux
1466
1467 version.patch
1468 my_feature.scc
1469 my_feature.cfg
1470</literallayout>
1471</para>
1472<para>
1473 The .scc file describes the patches, configuration and
1474 where in the patch order the feature should be inserted.
1475<literallayout class='monospaced'>
1476 patch version.patch
1477 kconf non-hardware my_feature.cfg
1478</literallayout>
1479</para>
1480<para>
1481 Configure your build with the new template
1482<literallayout class='monospaced'>
1483 &dash;&dash;with-template=features/my_feature
1484</literallayout>
1485</para>
1486<para>
1487Build the kernel
1488<literallayout class='monospaced'>
1489 &gt; make linux
1490</literallayout>
1491</para>
1492 </section>
1493
1494 <section id='patching-kernel-cache'>
1495 <title>Patching: Kernel Cache</title>
1496<para>
1497As previously mentioned, this example is included for completeness, and is for more advanced
1498applications (such as the sharing of patches between multiple sub-features).
1499Most patching should be done via templates, since that interface is
1500guaranteed not to change and the kernel-cache interface carries no such
1501guarantee.
1502</para>
1503<para>
1504At the top of a layer, create a kernel cache. The build system will recognize
1505any directory of the name 'kernel-*-cache' as a kernel cache.
1506<literallayout class='monospaced'>
1507 &gt; cd &lt;my layer&gt;
1508 &gt;mkdir kernel-temp-cache
1509</literallayout>
1510</para>
1511<para>
1512Make a directory with the BSP
1513<literallayout class='monospaced'>
1514 &gt; mkdir kernel-temp-cache
1515 &gt; mkdir kernel-temp-cache/my_feat
1516</literallayout>
1517</para>
1518<para>
1519Create the feature files as they were in technique #1
1520<literallayout class='monospaced'>
1521 &gt; echo "patch my_patch.path" &gt; kernel-temp-cache/my_feat/my_feature.scc
1522</literallayout>
1523</para>
1524<para>
1525Configure the build with the feature added to the kernel type
1526<literallayout class='monospaced'>
1527 &dash;&dash;with-kernel=standard+my_feat/my_feature.scc
1528</literallayout>
1529</para>
1530<para>
1531Build the kernel
1532<literallayout class='monospaced'>
1533 &gt; make linux
1534</literallayout>
1535</para>
1536 </section>
1537 </section>
1538
1539 <section id='bsp-updating-patches-and-configuration'>
1540 <title>BSP: Updating Patches and Configuration</title>
1541<para>
1542As was described in the "template patching" example, it is simple
1543to add patches to a BSP via a template, but often, it is desirable
1544to experiment and test patches before committing them to a template.
1545You can do this by modifying the BSP source.
1546</para>
1547<para>
1548Start as follows:
1549<literallayout class='monospaced'>
1550 &gt; cd linux
1551 &gt; git checkout &lt;bspname&gt;-&lt;kernel name&gt;
1552
1553 &gt; git am &lt;patch&gt;
1554</literallayout>
1555</para>
1556<para>
1557Or you can do this:
1558<literallayout class='monospaced'>
1559 &gt; kgit-import -t patch &lt;patch&gt;
1560
1561 &gt; cd ..
1562 &gt; make linux
1563</literallayout>
1564</para>
1565<para>
1566For details on conflict resolution and patch application, see the
1567Git manual, or other suitable online references.
1568<literallayout class='monospaced'>
1569 &gt; git am &lt;mbox&gt;
1570 # conflict
1571 &gt; git apply &dash;&dash;reject .git/rebase-apply/0001
1572 # resolve conflict
1573 &gt; git am &dash;&dash;resolved (or git am &dash;&dash;skip, git am &dash;&dash;abort)
1574 # continue until complete
1575</literallayout>
1576</para>
1577<para>
1578Here is another example:
1579<literallayout class='monospaced'>
1580 # merge the patches
1581 # 1) single patch
1582 &gt; git am &lt;mbox&gt;
1583 &gt; git apply &lt;patch&lt;
1584 &gt; kgit import -t patch &lt;patch&gt;
1585
1586 # 2) multiple patches
1587 &gt; git am &lt;mbox&gt;
1588 &gt; kgit import -t dir &lt;dir&gt;
1589
1590 # if kgit -t dir is used, a patch resolution cycle such
1591 # as this can be used:
1592
1593 &gt; kgit import -t dir &lt;dir&gt;
1594 # locate rejects and resolve
1595 # options:
1596 &gt; wiggle &dash;&dash;replace &lt;path to file&gt; &lt;path to reject&gt;
1597 &gt; guilt refresh
1598 or
1599 &gt; # manual resolution
1600 &gt; git add &lt;files&gt;
1601 &gt; git commit -s
1602 or
1603 &gt; git apply &dash;&dash;reject .git/rebase-apply/0001
1604 &gt; git add &lt;files&gt;
1605 &gt; git am &dash;&dash;resolved
1606 or
1607 &gt; # merge tool of choice
1608
1609 # continue series:
1610
1611 &gt; kgit import -t dir &lt;dir&gt;
1612 or
1613 &gt; git am &dash;&dash;continue
1614</literallayout>
1615</para>
1616<para>
1617Once all the patches have been tested and are satisfactory, they
1618should be exported via the techniques described in "saving kernel
1619modifications."
1620</para>
1621<para>
1622Once the kernel has been patched and configured for a BSP, it's
1623configuration commonly needs to be modified. This can be done by
1624running [menu|x]config on the kernel tree, or working with
1625configuration fragments.
1626</para>
1627<para>
1628Using menuconfig, the operation is as follows:
1629<literallayout class='monospaced'>
1630 &gt; make linux.menuconfig
1631 &gt; make linux.rebuild
1632</literallayout>
1633</para>
1634<para>
1635Once complete, the changes are in linux-&lt;bsp&gt;-&lt;kernel type&gt;-build/.config.
1636To permanently save these changes, compare the .config before and after the
1637menuconfig, and place those changes in a configuration fragment in the
1638template of your choice.
1639</para>
1640<para>
1641Using configuration fragments, the operation is as follows (using the
1642si_is8620 as an example BSP):
1643<literallayout class='monospaced'>
1644 &gt; vi linux/wrs/cfg/kernel-cache/bsp/si_is8620/si_is8620.cfg
1645 &gt; make linux.reconfig
1646 &gt; make linux.rebuild
1647</literallayout>
1648</para>
1649<para>
1650The modified configuration fragment can simply be copied out of the
1651linux/wrs/.. directory and placed in the appropriate template for future
1652application.
1653</para>
1654 </section>
1655
1656 <section id='tools-guilt'>
1657 <title>Tools: guilt</title>
1658<para>
1659Yocto Project has guilt integrated as a kernel tool; therefore users that are
1660familiar with quilt may wish to use this tool to pop, push and refresh
1661their patches. Note: guilt should only be used for local operations, once
1662a set of changes has been pushed or pulled, they should no longer be popped
1663or refresh by guilt, since popping, refreshing and re-pushing patches
1664changes their commit IDs and creating non-fast forward branches.
1665</para>
1666<para>
1667The following example illustrates how to add patches a Yocto Project
1668BSP branch via guilt:
1669<literallayout class='monospaced'>
1670 &gt; cd build/linux
1671 &gt; git checkout common_pc-standard
1672 &gt; guilt new extra.patch
1673 # edit files, make changes, etc
1674 &gt; guilt refresh
1675 &gt; guilt top
1676 extra.patch
1677
1678 # export that patch to an external location
1679 &gt; kgit export -p top /tmp
1680</literallayout>
1681</para>
1682<para>
1683Other guilt operations of interest are:
1684<literallayout class='monospaced'>
1685 > guilt push, guilt push -a
1686 > guilt pop
1687 > guilt applied, guilt unapplied
1688 > guilt top
1689 > guilt refresh
1690 > guilt header -e
1691 > guilt next
1692</literallayout>
1693</para>
1694<note><para>
1695Guilt only uses Git commands and Git plumbing to perform its operations,
1696anything that guilt does can also be done using Git directly. It is provided
1697as a convenience utility, but is not required and the developer can use whatever
1698tools or workflow they wish.
1699</para></note>
1700<para>
1701The following builds from the above instructions to show how guilt can be
1702used to assist in getting your BSP kernel patches ready. You should follow
1703the above instructions up to and including 'make linux.config'. In this
1704example I will create a new commit (patch) from scratch and import another
1705fictitious patch from some external public Git tree (ie, a commit with full
1706message, signoff etc.). Please ensure you have host-cross/bin in your path.
1707<literallayout class='monospaced'>
1708 %> cd linux
1709 %> guilt-init
1710 %> guilt-new -m fill_me_in_please first_one.patch
1711 %> touch somefile.txt
1712 %> guilt-add somefile.txt
1713 %> guilt-header -e
1714 %> guilt-refresh
1715 %> guilt-import path_to_some_patch/patch_filename
1716 %> guilt-push
1717</literallayout>
1718</para>
1719<para>
1720Here are a few notes about the above:
1721<itemizedlist>
1722 <listitem><para>guilt-header -e &dash;&dash; this will open editing of the patch header in
1723 EDITOR. As with a Git commit the first line is the short log and
1724 should be just that short and concise message about the commit. Follow
1725 the short log with lines of text that will be the long description but
1726 note Do not put a blank line after the short log. As usual you will
1727 want to follow this with a blank line and then a signoff line.</para></listitem>
1728
1729 <listitem><para>The last line in the example above has 2 dots on the end. If you
1730 don't add the 2 periods on the end guilt will think you are sending
1731 just one patch. The wrong one!</para></listitem>
1732
1733 <listitem><para>The advantage to using guilt over not using guilt is that if you have a
1734 review comment in the first patch (first_one.patch in the case of this
1735 example) it is very easy to use guilt to pop the other patches off
1736 allowing you to make the necessary changes without having to use more
1737 inventive Git type strategies.</para></listitem>
1738</itemizedlist>
1739</para>
1740 </section>
1741
1742 <section id='tools-scc-file-example'>
1743 <title>Tools: scc File Example</title>
1744<para>
1745This section provides some scc file examples: leaf node, 'normal' mode, and transforms.
1746</para>
1747 <section id='leaf-node'>
1748 <title>Leaf Node</title>
1749<para>
1750The following example is a BSP branch with no child branches - a leaf on the tree.
1751<literallayout class='monospaced'>
1752 # these are optional, but allow standalone tree construction
1753 define WRS_BOARD &lt;name&gt;
1754 define WRS_KERNEL &lt;kern type&gt;
1755 define WRS_ARCH &lt;arch&gt;
1756
1757 scc_leaf ktypes/standard common_pc-standard
1758 # ^ ^
1759 # +&dash;&dash; parent + branch name
1760
1761 include common_pc.scc
1762 # ^
1763 # +&dash;&dash;&dash; include another feature
1764</literallayout>
1765</para>
1766 </section>
1767
1768 <section id='normal-mode'>
1769 <title>'Normal' Mode</title>
1770<para>
1771Here is an example of 'normal' mode:
1772<literallayout class='monospaced'>
1773 # +&dash;&dash;&dash;&dash; name of file to read
1774 # v
1775 kconf hardware common_pc.cfg
1776 # ^ ^
1777 # | +&dash;&dash; 'type: hardware or non-hardware
1778 # |
1779 # +&dash;&dash;&dash; kernel config
1780
1781 # patches
1782 patch 0002-atl2-add-atl2-driver.patch
1783 patch 0003-net-remove-LLTX-in-atl2-driver.patch
1784 patch 0004-net-add-net-poll-support-for-atl2-driver.patch
1785</literallayout>
1786</para>
1787
1788 </section>
1789
1790 <section id='transforms'>
1791 <title>Transforms</title>
1792<para>
1793This section shows an example of transforms:
1794<literallayout class='monospaced'>
1795 # either of the next two options will trigger an 'auto'
1796 # branch from existing ones, since they change the commit
1797 # order and hence must construct their own branch
1798
1799 # this changes the order of future includes, if the
1800 # passed feature is detected, the first feature is
1801 # included AFTER it
1802 include features/rt/rt.scc after features/kgdb/kgdb
1803 # this also changes the order of existing branches
1804 # this prevents the named feature from ever being
1805 # included
1806 exclude features/dynamic_ftrace/dynamic_ftrace.scc
1807
1808 # inherit the standard kernel
1809 include ktypes/standard/standard
1810
1811
1812 # LTT supplies this, so we don't want the sub-chunk from RT.
1813 patch_trigger arch:all exclude ftrace-upstream-tracepoints.patch
1814 # ...but we still want the one unique tracepoint it added.
1815 patch tracepoint-add-for-sched_resched_task.patch
1816
1817 # these will change the named patches in the series into
1818 # &lt;patch name&gt;.patch.&lt;feature name&gt;
1819 # where the substituted patch is in this directory
1820 patch_trigger arch:all ctx_mod dynamic_printk.patch
1821 patch_trigger arch:all ctx_mod 0001-Implement-futex-macros-for-ARM.patch
1822 # unconditionally exclude a patch
1823 patch_trigger arch:all exclude ftrace-fix-ARM-crash.patch
1824</literallayout>
1825</para>
1826 </section>
1827 </section> -->
1828
1829 <section id='tip-dirty-string'> 799 <section id='tip-dirty-string'>
1830 <title>"-dirty" String</title> 800 <title>"-dirty" String</title>
1831 801
@@ -1839,14 +809,14 @@ This section shows an example of transforms:
1839 </para> 809 </para>
1840 810
1841 <para> 811 <para>
1842 You can use the Git command above to report modified, removed, or added files. 812 You can use the above Git command to report modified, removed, or added files.
1843 You should commit those changes to the tree regardless of whether they will be saved, 813 You should commit those changes to the tree regardless of whether they will be saved,
1844 exported, or used. 814 exported, or used.
1845 Once you commit the changes you need to rebuild the kernel. 815 Once you commit the changes you need to rebuild the kernel.
1846 </para> 816 </para>
1847 817
1848 <para> 818 <para>
1849 To brute force pickup and commit all such pending changes enter the following: 819 To brute force pickup and commit all such pending changes, enter the following:
1850 <literallayout class='monospaced'> 820 <literallayout class='monospaced'>
1851 &gt; git add . 821 &gt; git add .
1852 &gt; git commit -s -a -m "getting rid of -dirty" 822 &gt; git commit -s -a -m "getting rid of -dirty"
@@ -1857,206 +827,7 @@ This section shows an example of transforms:
1857 Next, rebuild the kernel. 827 Next, rebuild the kernel.
1858 </para> 828 </para>
1859 </section> 829 </section>
1860
1861<!-- <section id='kernel-transition-kernel-layer'>
1862 <title>Creating a Transition Kernel Layer</title>
1863
1864 <para>
1865 You can temporarily use a different base kernel in Yocto Project by doing the following:
1866
1867 <orderedlist>
1868 <listitem><para>Create a custom kernel layer.</para></listitem>
1869 <listitem><para>Create a Git repository of the transition kernel.</para></listitem>
1870 </orderedlist>
1871 </para>
1872
1873 <para>
1874 Once you meet those requirements you can build multiple boards and kernels.
1875 You pay the setup cost only once.
1876 You can then add additional BSPs and options.
1877 </para>
1878
1879 <para>
1880 Once you have the transition kernel layer in place you can evaluate
1881 another kernel's functionality with the goal of easing transition to an integrated and validated
1882 Yocto Project kernel.
1883 </para> -->
1884
1885<!--<para>
1886The next few sections describe the process:
1887</para> -->
1888 <!-- <section id='creating-a-custom-kernel-layer'>
1889 <title>Creating a Custom Kernel Layer</title>
1890<para>
1891The custom kernel layer must have the following minimum
1892elements:
1893<itemizedlist>
1894 <listitem><para>An include of the shipped Yocto Project kernel layer.</para></listitem>
1895 <listitem><para>A kernel-cache with an override of the standard kernel type.</para></listitem>
1896</itemizedlist>
1897</para>
1898<para>
1899This allows the inheritance of the kernel build infrastructure,
1900while overriding the list of patches that should be applied to
1901the base kernel.
1902</para>
1903<para>
1904The kernel layer can optionally include an override to the base
1905Yocto Project Linux BSP to inhibit the application of BSP specific
1906patches. If a custom BSP is being used, this is not required.
1907</para>
1908 </section> -->
1909
1910 <!-- <section id='git-repo-of-the-transition-kernel'>
1911 <title>Git Repo of the Transition Kernel</title>
1912<para>
1913The kernel build system requires a base kernel repository to
1914seed the build process. This repository must be found in the
1915same layer as the build infrastructure (i.e wrll-linux-2.6.27)
1916in the <filename>.git</filename> subdir, with the name 'default_kernel'
1917</para>
1918<para>Since Yocto Project Linux ships with a default_kernel
1919(the validated Yocto Project kernel) in the wrll-linux-2.6.27
1920kernel layer, that must be removed and replaced with the
1921transition kernel.
1922</para>
1923<para>If the Yocto Project install cannot be directly modified
1924with the new default kernel, then the path to the transition
1925kernel layer's <filename>.git</filename> subdir must be passed to the build
1926process via:
1927<programlisting>
1928linux_GIT_BASE=&lt;absolute path to layer&gt;/git
1929</programlisting>
1930</para>
1931<para>
1932If the transition kernel has not been delivered via Git,
1933then a Git repo should be created, and bare cloned into
1934place. Creating this repository is as simple as:
1935<literallayout class='monospaced'>
1936 &gt; tar zxvf temp_kernel.tgz
1937 &gt; cd temp_kernel
1938 &gt; git init
1939 &gt; git add .
1940 &gt; git commit -a -m "Transition kernel baseline"
1941
1942 'temp_kernel' can now be cloned into place via:
1943
1944 &gt; cd &lt;path to git base&gt;/git
1945 &gt; git clone &dash;&dash;bare &lt;path to temp_kernel/temp_kernel default_kernel
1946</literallayout>
1947</para>
1948 </section> -->
1949
1950 <!-- <section id='building-the-kernel'>
1951 <title>Building the Kernel</title>
1952<para>
1953Once these prerequisites have been met, the kernel can be
1954built with:
1955<literallayout class='monospaced'>
1956 &gt; make linux
1957</literallayout>
1958</para>
1959<para>
1960The new base kernel will be cloned into place and have any patches
1961indicated in the transition kernel's cache (or templates) applied.
1962The kernel build will detect the non-Yocto Project base repo and
1963use the HEAD of the tree for the build.
1964</para>
1965 </section> -->
1966
1967 <!-- <section id='example'>
1968 <title>Example</title>
1969<para>
1970This example creates a kernel layer to build the latest
1971kernel.org tree as the 'common_pc' BSP.
1972<literallayout class='monospaced'>
1973 &gt; cd &lt;path to layers&gt;
1974 &gt; mkdir wrll-linux-my_version
1975 &gt; cd wrll-linux-my_version
1976 &gt; echo "wrll-linux-2.6.27" &gt; include
1977 &gt; mkdir -p kernel-cache/ktypes/standard
1978 &gt; mkdir -p kernel-cache/bsp/common_pc
1979 &gt; echo "v2.6.29" &gt; kernel-cache/kver
1980 &gt; echo "branch common_pc-standard" &gt; kernel-cache/bsp/common_pc/common_pc.scc
1981 &gt; echo "kconf hardware common_pc.cfg" &gt;&gt; kernel-cache/bsp/common_pc/common_pc.scc
1982 &gt; echo "CONFIG_FOO=y" &gt; kernel-cache/bsp/common_pc/common_pc.cfg
1983 &gt; mkdir git
1984 &gt; cd git
1985 &gt; git clone &dash;&dash;bare git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git default_kernel
1986</literallayout>
1987</para>
1988<para>
1989Configure a build to use the new layer. This means that:
1990<literallayout class='monospaced'>
1991 &dash;&dash;enable-kernel-version=my_version
1992</literallayout>
1993</para>
1994<para>
1995Should be used to override the shipped default.
1996</para>
1997<para>
1998To build the kernel:
1999<literallayout class='monospaced'>
2000 &gt; cd build
2001 &gt; make linux_GIT_BASE=&lt;layer path&gt;/wrll-linux-my_version/git linux
2002</literallayout>
2003</para>
2004<para>
2005If this is to build without some user intervention (passing of the
2006GIT_BASE), you must do the clone into the <filename>wrll-linux-2.6.27/.git</filename> directory.
2007</para>
2008<note><para>Unless you define valid "hardware.kcf" and "non-hardware.kcf" some
2009non fatal warnings will be seen. They can be fixed by populating these
2010files in the kernel-cache with valid hardware and non hardware config
2011options.
2012</para></note>
2013 </section> -->
2014<!-- </section> -->
2015 </section> 830 </section>
2016
2017
2018
2019
2020
2021<!-- <itemizedlist>
2022 <listitem><para>Introduction to this section.</para></listitem>
2023 <listitem><para>Constructing a project-specific kernel tree.</para></listitem>
2024 <listitem><para>Building the kernel.</para></listitem>
2025 <listitem><para>Seeing what has changed.</para></listitem>
2026 <listitem><para>Seeing what has changed in a particular branch.</para></listitem>
2027 <listitem><para>Modifying the kernel.</para></listitem>
2028 <listitem><para>Saving modifications.</para></listitem>
2029 <listitem><para>Storing patches outside of the kernel source repository (bulk export).</para></listitem>
2030 <listitem><para>Working with incremental changes.</para></listitem>
2031 <listitem><para>Extracting commited changes from a working directory (exporting internally through
2032 patches.</para></listitem>
2033 <listitem><para>Pushing commited changes.</para></listitem>
2034 <listitem><para>Exporting for external (upstream) submission.</para></listitem>
2035 <listitem><para>Exporting for import into another Source Control Manager (SCM).</para></listitem>
2036 <listitem><para>Working with the Yocto Project kernel in another SCM.</para>
2037 <itemizedlist>
2038 <listitem><para>Exporting the delivered kernel to an SCM.</para></listitem>
2039 <listitem><para>Importing changed for the build.</para></listitem>
2040 </itemizedlist></listitem>
2041 <listitem><para>Migrating templates from version 2.0.</para></listitem>
2042 <listitem><para>Creating a new Board Support Package (BSP).</para>
2043 <itemizedlist>
2044 <listitem><para>Creating from scratch.</para></listitem>
2045 <listitem><para>Cloning.</para></listitem>
2046 </itemizedlist></listitem>
2047 <listitem><para>BSP bootstrapping.</para></listitem>
2048 <listitem><para>Applying patches to the kernel through a template.</para></listitem>
2049 <listitem><para>Applying patches to the kernel without using a template.</para></listitem>
2050 <listitem><para>Updating patches and configurations for a BSP.</para></listitem>
2051 <listitem><para>Using guilt to add and export patches.</para></listitem>
2052 <listitem><para>Using scc.</para></listitem>
2053 <listitem><para>Building a 'dirty' image.</para></listitem>
2054 <listitem><para>Temporarily using a different base kernel.</para></listitem>
2055 <listitem><para>Creating a custom kernel layer.</para></listitem>
2056 <listitem><para>Creating the Git repository of the transition kernel.</para></listitem>
2057 </itemizedlist> -->
2058
2059
2060</chapter> 831</chapter>
2061<!-- 832<!--
2062vim: expandtab tw=80 ts=4 833vim: expandtab tw=80 ts=4