summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-17 17:17:14 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-16 15:59:04 +0000
commit5cbeb840061fad16524e355c07c518defae62b6e (patch)
treedccbd0db15c5ebcf8e617149080f61f2e08fe5f6 /documentation
parentea50862d40c6542d744408266aef157ce6ed5b63 (diff)
downloadpoky-5cbeb840061fad16524e355c07c518defae62b6e.tar.gz
kernel-dev: Created file structure for new kernel-dev manual.
(From yocto-docs rev: 25be3ebb7713b875c4ec6e3723961b7dd860295d) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/kernel-dev/figures/kernel-dev-title.pngbin0 -> 27810 bytes
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml918
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml392
-rw-r--r--documentation/kernel-dev/kernel-dev-customization.xsl8
-rw-r--r--documentation/kernel-dev/kernel-dev-examples.xml918
-rw-r--r--documentation/kernel-dev/kernel-dev-faq.xml918
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml78
-rw-r--r--documentation/kernel-dev/kernel-dev-style.css979
-rw-r--r--documentation/kernel-dev/kernel-dev.xml104
9 files changed, 4315 insertions, 0 deletions
diff --git a/documentation/kernel-dev/figures/kernel-dev-title.png b/documentation/kernel-dev/figures/kernel-dev-title.png
new file mode 100644
index 0000000000..1cb989f34a
--- /dev/null
+++ b/documentation/kernel-dev/figures/kernel-dev-title.png
Binary files differ
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
new file mode 100644
index 0000000000..9d9aef6d06
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -0,0 +1,918 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='kernel-how-to'>
6
7<title>Working with the Yocto Project Kernel</title>
8
9
10<section id='actions-org'>
11 <title>Introduction</title>
12 <para>
13 This chapter describes how to accomplish tasks involving a kernel's tree structure.
14 The information is designed to help the developer that wants to modify the Yocto
15 Project kernel and contribute changes upstream to the Yocto Project.
16 The information covers the following:
17 <itemizedlist>
18 <listitem><para>Tree construction</para></listitem>
19 <listitem><para>Build strategies</para></listitem>
20 <listitem><para>Workflow examples</para></listitem>
21 </itemizedlist>
22 </para>
23</section>
24
25 <section id='tree-construction'>
26 <title>Tree Construction</title>
27 <para>
28 This section describes construction of the Yocto Project kernel source repositories
29 as accomplished by the Yocto Project team to create kernel repositories.
30 These kernel repositories are found under the heading "Yocto Linux Kernel" at
31 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
32 and can be shipped as part of a Yocto Project release.
33 The team creates these repositories by
34 compiling and executing the set of feature descriptions for every BSP/feature
35 in the product.
36 Those feature descriptions list all necessary patches,
37 configuration, branching, tagging and feature divisions found in a kernel.
38 Thus, the Yocto Project kernel repository (or tree) is built.
39 </para>
40 <para>
41 The existence of this tree allows you to access and clone a particular
42 Yocto Project kernel repository and use it to build images based on their configurations
43 and features.
44 </para>
45 <para>
46 You can find the files used to describe all the valid features and BSPs
47 in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
48 Git tree.
49 For example, the following command clones the Yocto Project baseline kernel that
50 branched off of <filename>linux.org</filename> version 3.4:
51 <literallayout class='monospaced'>
52 $ git clone git://git.yoctoproject.org/linux-yocto-3.4
53 </literallayout>
54 For another example of how to set up a local Git repository of the Yocto Project
55 kernel files, see the
56 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
57 item in the Yocto Project Development Manual.
58 </para>
59 <para>
60 Once you have cloned the kernel Git repository on your local machine, you can
61 switch to the <filename>meta</filename> branch within the repository.
62 Here is an example that assumes the local Git repository for the kernel is in
63 a top-level directory named <filename>linux-yocto-3.4</filename>:
64 <literallayout class='monospaced'>
65 $ cd ~/linux-yocto-3.4
66 $ git checkout -b meta origin/meta
67 </literallayout>
68 Once you have checked out and switched to the <filename>meta</filename> branch,
69 you can see a snapshot of all the kernel configuration and feature descriptions that are
70 used to build that particular kernel repository.
71 These descriptions are in the form of <filename>.scc</filename> files.
72 </para>
73 <para>
74 You should realize, however, that browsing your local kernel repository
75 for feature descriptions and patches is not an effective way to determine what is in a
76 particular kernel branch.
77 Instead, you should use Git directly to discover the changes in a branch.
78 Using Git is an efficient and flexible way to inspect changes to the kernel.
79 For examples showing how to use Git to inspect kernel commits, see the following sections
80 in this chapter.
81 <note>
82 Ground up reconstruction of the complete kernel tree is an action only taken by the
83 Yocto Project team during an active development cycle.
84 When you create a clone of the kernel Git repository, you are simply making it
85 efficiently available for building and development.
86 </note>
87 </para>
88 <para>
89 The following steps describe what happens when the Yocto Project Team constructs
90 the Yocto Project kernel source Git repository (or tree) found at
91 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
92 introduction of a new top-level kernel feature or BSP.
93 These are the actions that effectively create the tree
94 that includes the new feature, patch or BSP:
95 <orderedlist>
96 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
97 Normally, this feature is a BSP for a particular kernel type.</para></listitem>
98 <listitem><para>The file that describes the top-level feature is located by searching
99 these system directories:
100 <itemizedlist>
101 <listitem><para>The in-tree kernel-cache directories, which are located
102 in <filename>meta/cfg/kernel-cache</filename></para></listitem>
103 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
104 found in recipes</para></listitem>
105 </itemizedlist>
106 For a typical build, the target of the search is a
107 feature description in an <filename>.scc</filename> file
108 whose name follows this format:
109 <literallayout class='monospaced'>
110 &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
111 </literallayout>
112 </para></listitem>
113 <listitem><para>Once located, the feature description is either compiled into a simple script
114 of actions, or into an existing equivalent script that is already part of the
115 shipped kernel.</para></listitem>
116 <listitem><para>Extra features are appended to the top-level feature description.
117 These features can come from the
118 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
119 variable in recipes.</para></listitem>
120 <listitem><para>Each extra feature is located, compiled and appended to the script
121 as described in step three.</para></listitem>
122 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
123 directories.
124 These directories are descriptions of all the branches, tags, patches and configurations that
125 need to be applied to the base Git repository to completely create the
126 source (build) branch for the new BSP or feature.</para></listitem>
127 <listitem><para>The base repository is cloned, and the actions
128 listed in the <filename>meta-*</filename> directories are applied to the
129 tree.</para></listitem>
130 <listitem><para>The Git repository is left with the desired branch checked out and any
131 required branching, patching and tagging has been performed.</para></listitem>
132 </orderedlist>
133 </para>
134 <para>
135 The kernel tree is now ready for developer consumption to be locally cloned,
136 configured, and built into a Yocto Project kernel specific to some target hardware.
137 <note><para>The generated <filename>meta-*</filename> directories add to the kernel
138 as shipped with the Yocto Project release.
139 Any add-ons and configuration data are applied to the end of an existing branch.
140 The full repository generation that is found in the
141 official Yocto Project kernel repositories at
142 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
143 is the combination of all supported boards and configurations.</para>
144 <para>The technique the Yocto Project team uses is flexible and allows for seamless
145 blending of an immutable history with additional patches specific to a
146 deployment.
147 Any additions to the kernel become an integrated part of the branches.</para>
148 </note>
149 </para>
150 </section>
151
152 <section id='build-strategy'>
153 <title>Build Strategy</title>
154 <para>
155 Once a local Git repository of the Yocto Project kernel exists on a development system,
156 you can consider the compilation phase of kernel development - building a kernel image.
157 Some prerequisites exist that are validated by the build process before compilation
158 starts:
159 </para>
160
161 <itemizedlist>
162 <listitem><para>The
163 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
164 to the kernel Git repository.</para></listitem>
165 <listitem><para>A BSP build branch exists.
166 This branch has the following form:
167 <literallayout class='monospaced'>
168 &lt;kernel_type&gt;/&lt;bsp_name&gt;
169 </literallayout></para></listitem>
170 </itemizedlist>
171
172 <para>
173 The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
174 Other means, however, do exist, such as as bootstrapping a BSP, see
175 the "<link linkend='workflow-examples'>Workflow Examples</link>".
176 </para>
177
178 <para>
179 Before building a kernel, the build process verifies the tree
180 and configures the kernel by processing all of the
181 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
182 files.
183 As the features are compiled, associated kernel configuration fragments are noted
184 and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
185 The fragments are migrated, pre-processed and passed to the Linux Kernel
186 Configuration subsystem (<filename>lkc</filename>) as raw input in the form
187 of a <filename>.config</filename> file.
188 The <filename>lkc</filename> uses its own internal dependency constraints to do the final
189 processing of that information and generates the final <filename>.config</filename> file
190 that is used during compilation.
191 </para>
192
193 <para>
194 Using the board's architecture and other relevant values from the board's template,
195 kernel compilation is started and a kernel image is produced.
196 </para>
197
198 <para>
199 The other thing that you notice once you configure a kernel is that
200 the build process generates a build tree that is separate from your kernel's local Git
201 source repository tree.
202 This build tree has a name that uses the following form, where
203 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
204 of the Yocto Project supported kernel types (e.g. "standard"):
205 <literallayout class='monospaced'>
206 linux-${MACHINE}-&lt;kernel_type&gt;-build
207 </literallayout>
208 </para>
209
210 <para>
211 The existing support in the <filename>kernel.org</filename> tree achieves this
212 default functionality.
213 </para>
214
215 <para>
216 This behavior means that all the generated files for a particular machine or BSP are now in
217 the build tree directory.
218 The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
219 files, the <filename>.a</filename> files, and so forth.
220 Since each machine or BSP has its own separate build directory in its own separate branch
221 of the Git repository, you can easily switch between different builds.
222 </para>
223 </section>
224
225 <section id='workflow-examples'>
226 <title>Workflow Examples</title>
227
228 <para>
229 As previously noted, the Yocto Project kernel has built-in Git integration.
230 However, these utilities are not the only way to work with the kernel repository.
231 The Yocto Project has not made changes to Git or to other tools that
232 would invalidate alternate workflows.
233 Additionally, the way the kernel repository is constructed results in using
234 only core Git functionality, thus allowing any number of tools or front ends to use the
235 resulting tree.
236 </para>
237
238 <para>
239 This section contains several workflow examples.
240 Many of the examples use Git commands.
241 You can find Git documentation at
242 <ulink url='http://git-scm.com/documentation'></ulink>.
243 You can find a simple overview of using Git with the Yocto Project in the
244 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
245 section of the Yocto Project Development Manual.
246 </para>
247
248 <section id='change-inspection-kernel-changes-commits'>
249 <title>Change Inspection: Changes/Commits</title>
250
251 <para>
252 A common question when working with a kernel is:
253 "What changes have been applied to this tree?"
254 </para>
255
256 <para>
257 In projects that have a collection of directories that
258 contain patches to the kernel, it is possible to inspect or "grep" the contents
259 of the directories to get a general feel for the changes.
260 This sort of patch inspection is not an efficient way to determine what has been
261 done to the kernel.
262 The reason it is inefficient is because there are many optional patches that are
263 selected based on the kernel type and the feature description.
264 Additionally, patches could exist in directories that are not included in the search.
265 </para>
266
267 <para>
268 A more efficient way to determine what has changed in the branch is to use
269 Git and inspect or search the kernel tree.
270 This method gives you a full view of not only the source code modifications,
271 but also provides the reasons for the changes.
272 </para>
273
274 <section id='what-changed-in-a-kernel'>
275 <title>What Changed in a Kernel?</title>
276
277 <para>
278 Following are a few examples that show how to use Git commands to examine changes.
279 Because Git repositories in the Yocto Project do not break existing Git
280 functionality, and because there exists many permutations of these types of
281 Git commands, many methods exist by which you can discover changes.
282 <note>
283 In the following examples, unless you provide a commit range,
284 <filename>kernel.org</filename> history is blended with Yocto Project
285 kernel changes.
286 You can form ranges by using branch names from the kernel tree as the
287 upper and lower commit markers with the Git commands.
288 You can see the branch names through the web interface to the
289 Yocto Project source repositories at
290 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
291 For example, the branch names for the <filename>linux-yocto-3.4</filename>
292 kernel repository can be seen at
293 <ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
294 </note>
295 To see a full range of the changes, use the
296 <filename>git whatchanged</filename> command and specify a commit range
297 for the branch (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
298 </para>
299
300 <para>
301 Here is an example that looks at what has changed in the
302 <filename>emenlow</filename> branch of the
303 <filename>linux-yocto-3.4</filename> kernel.
304 The lower commit range is the commit associated with the
305 <filename>standard/base</filename> branch, while
306 the upper commit range is the commit associated with the
307 <filename>standard/emenlow</filename> branch.
308 <literallayout class='monospaced'>
309 $ git whatchanged origin/standard/base..origin/standard/emenlow
310 </literallayout>
311 </para>
312
313 <para>
314 To see a summary of changes use the <filename>git log</filename> command.
315 Here is an example using the same branches:
316 <literallayout class='monospaced'>
317 $ git log --oneline origin/standard/base..origin/standard/emenlow
318 </literallayout>
319 The <filename>git log</filename> output might be more useful than
320 the <filename>git whatchanged</filename> as you get
321 a short, one-line summary of each change and not the entire commit.
322 </para>
323
324 <para>
325 If you want to see code differences associated with all the changes, use
326 the <filename>git diff</filename> command.
327 Here is an example:
328 <literallayout class='monospaced'>
329 $ git diff origin/standard/base..origin/standard/emenlow
330 </literallayout>
331 </para>
332
333 <para>
334 You can see the commit log messages and the text differences using the
335 <filename>git show</filename> command:
336 Here is an example:
337 <literallayout class='monospaced'>
338 $ git show origin/standard/base..origin/standard/emenlow
339 </literallayout>
340 </para>
341
342 <para>
343 You can create individual patches for each change by using the
344 <filename>git format-patch</filename> command.
345 Here is an example that that creates patch files for each commit and
346 places them in your <filename>Documents</filename> directory:
347 <literallayout class='monospaced'>
348 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
349 </literallayout>
350 </para>
351 </section>
352
353 <section id='show-a-particular-feature-or-branch-change'>
354 <title>Show a Particular Feature or Branch Change</title>
355
356 <para>
357 Developers use tags in the Yocto Project kernel tree to divide changes for significant
358 features or branches.
359 Once you know a particular tag, you can use Git commands
360 to show changes associated with the tag and find the branches that contain
361 the feature.
362 <note>
363 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
364 present, there could be many tags.
365 </note>
366 The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
367 a feature.
368 Here is an example that shows changes tagged by the <filename>systemtap</filename>
369 feature:
370 <literallayout class='monospaced'>
371 $ git show systemtap
372 </literallayout>
373 You can use the <filename>git branch --contains &lt;tag&gt;</filename> command
374 to show the branches that contain a particular feature.
375 This command shows the branches that contain the <filename>systemtap</filename>
376 feature:
377 <literallayout class='monospaced'>
378 $ git branch --contains systemtap
379 </literallayout>
380 </para>
381
382 <para>
383 You can use many other comparisons to isolate BSP and kernel changes.
384 For example, you can compare against <filename>kernel.org</filename> tags
385 such as the <filename>v3.4</filename> tag.
386 </para>
387 </section>
388 </section>
389
390 <section id='development-saving-kernel-modifications'>
391 <title>Development: Saving Kernel Modifications</title>
392
393 <para>
394 Another common operation is to build a BSP supplied by the Yocto Project, make some
395 changes, rebuild, and then test.
396 Those local changes often need to be exported, shared or otherwise maintained.
397 </para>
398
399 <para>
400 Since the Yocto Project kernel source tree is backed by Git, this activity is
401 much easier as compared to with previous releases.
402 Because Git tracks file modifications, additions and deletions, it is easy
403 to modify the code and later realize that you need to save the changes.
404 It is also easy to determine what has changed.
405 This method also provides many tools to commit, undo and export those modifications.
406 </para>
407
408 <para>
409 This section and its sub-sections, describe general application of Git's
410 <filename>push</filename> and <filename>pull</filename> commands, which are used to
411 get your changes upstream or source your code from an upstream repository.
412 The Yocto Project provides scripts that help you work in a collaborative development
413 environment.
414 For information on these scripts, see the
415 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
416 Upstream and Request a Pull</ulink>" and
417 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
418 sections in the Yocto Project Development Manual.
419 </para>
420
421 <para>
422 There are many ways to save kernel modifications.
423 The technique employed
424 depends on the destination for the patches:
425
426 <itemizedlist>
427 <listitem><para>Bulk storage</para></listitem>
428 <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
429 <listitem><para>External submissions</para></listitem>
430 <listitem><para>Exporting for integration into another Source Code
431 Manager (SCM)</para></listitem>
432 </itemizedlist>
433 </para>
434
435 <para>
436 Because of the following list of issues, the destination of the patches also influences
437 the method for gathering them:
438
439 <itemizedlist>
440 <listitem><para>Bisectability</para></listitem>
441 <listitem><para>Commit headers</para></listitem>
442 <listitem><para>Division of subsystems for separate submission or review</para></listitem>
443 </itemizedlist>
444 </para>
445
446 <section id='bulk-export'>
447 <title>Bulk Export</title>
448
449 <para>
450 This section describes how you can "bulk" export changes that have not
451 been separated or divided.
452 This situation works well when you are simply storing patches outside of the kernel
453 source repository, either permanently or temporarily, and you are not committing
454 incremental changes during development.
455 <note>
456 This technique is not appropriate for full integration of upstream submission
457 because changes are not properly divided and do not provide an avenue for per-change
458 commit messages.
459 Therefore, this example assumes that changes have not been committed incrementally
460 during development and that you simply must gather and export them.
461 </note>
462 <literallayout class='monospaced'>
463 # bulk export of ALL modifications without separation or division
464 # of the changes
465
466 $ git add .
467 $ git commit -s -a -m &lt;msg&gt;
468 or
469 $ git commit -s -a # and interact with $EDITOR
470 </literallayout>
471 </para>
472
473 <para>
474 The previous operations capture all the local changes in the project source
475 tree in a single Git commit.
476 And, that commit is also stored in the project's source tree.
477 </para>
478
479 <para>
480 Once the changes are exported, you can restore them manually using a template
481 or through integration with the <filename>default_kernel</filename>.
482 </para>
483
484 </section>
485
486 <section id='incremental-planned-sharing'>
487 <title>Incremental/Planned Sharing</title>
488
489 <para>
490 This section describes how to save modifications when you are making incremental
491 commits or practicing planned sharing.
492 The examples in this section assume that you have incrementally committed
493 changes to the tree during development and now need to export them.
494 The sections that follow
495 describe how you can export your changes internally through either patches or by
496 using Git commands.
497 </para>
498
499 <para>
500 During development, the following commands are of interest.
501 For full Git documentation, refer to the Git documentation at
502 <ulink url='http://github.com'></ulink>.
503
504 <literallayout class='monospaced'>
505 # edit a file
506 $ vi &lt;path&gt;/file
507 # stage the change
508 $ git add &lt;path&gt;/file
509 # commit the change
510 $ git commit -s
511 # remove a file
512 $ git rm &lt;path&gt;/file
513 # commit the change
514 $ git commit -s
515
516 ... etc.
517 </literallayout>
518 </para>
519
520 <para>
521 Distributed development with Git is possible when you use a universally
522 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
523 specific change set with a specific parent.
524 This identifier is created for you when
525 you create a commit, and is re-created when you amend, alter or re-apply
526 a commit.
527 As an individual in isolation, this is of no interest.
528 However, if you
529 intend to share your tree with normal Git <filename>push</filename> and
530 <filename>pull</filename> operations for
531 distributed development, you should consider the ramifications of changing a
532 commit that you have already shared with others.
533 </para>
534
535 <para>
536 Assuming that the changes have not been pushed upstream, or pulled into
537 another repository, you can update both the commit content and commit messages
538 associated with development by using the following commands:
539
540 <literallayout class='monospaced'>
541 $ Git add &lt;path&gt;/file
542 $ Git commit --amend
543 $ Git rebase or Git rebase -i
544 </literallayout>
545 </para>
546
547 <para>
548 Again, assuming that the changes have not been pushed upstream, and that
549 no pending works-in-progress exist (use <filename>git status</filename> to check), then
550 you can revert (undo) commits by using the following commands:
551
552 <literallayout class='monospaced'>
553 # remove the commit, update working tree and remove all
554 # traces of the change
555 $ git reset --hard HEAD^
556 # remove the commit, but leave the files changed and staged for re-commit
557 $ git reset --soft HEAD^
558 # remove the commit, leave file change, but not staged for commit
559 $ git reset --mixed HEAD^
560 </literallayout>
561 </para>
562
563 <para>
564 You can create branches, "cherry-pick" changes, or perform any number of Git
565 operations until the commits are in good order for pushing upstream
566 or for pull requests.
567 After a <filename>push</filename> or <filename>pull</filename> command,
568 commits are normally considered
569 "permanent" and you should not modify them.
570 If the commits need to be changed, you can incrementally do so with new commits.
571 These practices follow standard Git workflow and the <filename>kernel.org</filename> best
572 practices, which is recommended.
573 <note>
574 It is recommended to tag or branch before adding changes to a Yocto Project
575 BSP or before creating a new one.
576 The reason for this recommendation is because the branch or tag provides a
577 reference point to facilitate locating and exporting local changes.
578 </note>
579 </para>
580
581 <section id='export-internally-via-patches'>
582 <title>Exporting Changes Internally by Using Patches</title>
583
584 <para>
585 This section describes how you can extract committed changes from a working directory
586 by exporting them as patches.
587 Once the changes have been extracted, you can use the patches for upstream submission,
588 place them in a Yocto Project template for automatic kernel patching,
589 or apply them in many other common uses.
590 </para>
591
592 <para>
593 This example shows how to create a directory with sequentially numbered patches.
594 Once the directory is created, you can apply it to a repository using the
595 <filename>git am</filename> command to reproduce the original commit and all
596 the related information such as author, date, commit log, and so forth.
597 <note>
598 The new commit identifiers (ID) will be generated upon re-application.
599 This action reflects that the commit is now applied to an underlying commit
600 with a different ID.
601 </note>
602 <literallayout class='monospaced'>
603 # &lt;first-commit&gt; can be a tag if one was created before development
604 # began. It can also be the parent branch if a branch was created
605 # before development began.
606
607 $ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
608 </literallayout>
609 </para>
610
611 <para>
612 In other words:
613 <literallayout class='monospaced'>
614 # Identify commits of interest.
615
616 # If the tree was tagged before development
617 $ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
618
619 # If no tags are available
620 $ git format-patch -o &lt;save dir&gt; HEAD^ # last commit
621 $ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
622 $ git whatchanged # identify last commit
623 $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
624 $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
625 </literallayout>
626 </para>
627 </section>
628
629 <section id='export-internally-via-git'>
630 <title>Exporting Changes Internally by Using Git</title>
631
632 <para>
633 This section describes how you can export changes from a working directory
634 by pushing the changes into a master repository or by making a pull request.
635 Once you have pushed the changes to the master repository, you can then
636 pull those same changes into a new kernel build at a later time.
637 </para>
638
639 <para>
640 Use this command form to push the changes:
641 <literallayout class='monospaced'>
642 $ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
643 &lt;local_branch&gt;:&lt;remote_branch&gt;
644 </literallayout>
645 </para>
646
647 <para>
648 For example, the following command pushes the changes from your local branch
649 <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
650 in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
651 <literallayout class='monospaced'>
652 $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
653 yocto/standard/common-pc/base:yocto/standard/common-pc/base
654 </literallayout>
655 </para>
656
657 <para>
658 A pull request entails using the <filename>git request-pull</filename> command to compose
659 an email to the
660 maintainer requesting that a branch be pulled into the master repository, see
661 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
662 <note>
663 Other commands such as <filename>git stash</filename> or branching can also be used to save
664 changes, but are not covered in this document.
665 </note>
666 </para>
667 </section>
668 </section>
669
670 <section id='export-for-external-upstream-submission'>
671 <title>Exporting Changes for External (Upstream) Submission</title>
672
673 <para>
674 This section describes how to export changes for external upstream submission.
675 If the patch series is large or the maintainer prefers to pull
676 changes, you can submit these changes by using a pull request.
677 However, it is common to send patches as an email series.
678 This method allows easy review and integration of the changes.
679 <note>
680 Before sending patches for review be sure you understand the
681 community standards for submitting and documenting changes and follow their best practices.
682 For example, kernel patches should follow standards such as:
683 <itemizedlist>
684 <listitem><para>
685 <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
686 <listitem><para>Documentation/SubmittingPatches (in any linux
687 kernel source tree)</para></listitem>
688 </itemizedlist>
689 </note>
690 </para>
691
692 <para>
693 The messages used to commit changes are a large part of these standards.
694 Consequently, be sure that the headers for each commit have the required information.
695 For information on how to follow the Yocto Project commit message standards, see the
696 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
697 Change</ulink>" section in the Yocto Project Development Manual.
698 </para>
699
700 <para>
701 If the initial commits were not properly documented or do not meet those standards,
702 you can re-base by using the <filename>git rebase -i</filename> command to
703 manipulate the commits and
704 get them into the required format.
705 Other techniques such as branching and cherry-picking commits are also viable options.
706 </para>
707
708 <para>
709 Once you complete the commits, you can generate the email that sends the patches
710 to the maintainer(s) or lists that review and integrate changes.
711 The command <filename>git send-email</filename> is commonly used to ensure
712 that patches are properly
713 formatted for easy application and avoid mailer-induced patch damage.
714 </para>
715
716 <para>
717 The following is an example of dumping patches for external submission:
718 <literallayout class='monospaced'>
719 # dump the last 4 commits
720 $ git format-patch --thread -n -o ~/rr/ HEAD^^^^
721 $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
722 --to foo@yoctoproject.org --to bar@yoctoproject.org \
723 --cc list@yoctoproject.org ~/rr
724 # the editor is invoked for the 0/N patch, and when complete the entire
725 # series is sent via email for review
726 </literallayout>
727 </para>
728 </section>
729
730 <section id='export-for-import-into-other-scm'>
731 <title>Exporting Changes for Import into Another SCM</title>
732
733 <para>
734 When you want to export changes for import into another
735 Source Code Manager (SCM), you can use any of the previously discussed
736 techniques.
737 However, if the patches are manually applied to a secondary tree and then
738 that tree is checked into the SCM, you can lose change information such as
739 commit logs.
740 This process is not recommended.
741 </para>
742
743 <para>
744 Many SCMs can directly import Git commits, or can translate Git patches so that
745 information is not lost.
746 Those facilities are SCM-dependent and you should use them whenever possible.
747 </para>
748 </section>
749 </section>
750
751 <section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
752 <title>Working with the Yocto Project Kernel in Another SCM</title>
753
754 <para>
755 This section describes kernel development in an SCM other than Git,
756 which is not the same as exporting changes to another SCM described earlier.
757 For this scenario, you use the OpenEmbedded build system to
758 develop the kernel in a different SCM.
759 The following must be true for you to accomplish this:
760 <itemizedlist>
761 <listitem><para>The delivered Yocto Project kernel must be exported into the second
762 SCM.</para></listitem>
763 <listitem><para>Development must be exported from that secondary SCM into a
764 format that can be used by the OpenEmbedded build system.</para></listitem>
765 </itemizedlist>
766 </para>
767
768 <section id='exporting-delivered-kernel-to-scm'>
769 <title>Exporting the Delivered Kernel to the SCM</title>
770
771 <para>
772 Depending on the SCM, it might be possible to export the entire Yocto Project
773 kernel Git repository, branches and all, into a new environment.
774 This method is preferred because it has the most flexibility and potential to maintain
775 the meta data associated with each commit.
776 </para>
777
778 <para>
779 When a direct import mechanism is not available, it is still possible to
780 export a branch (or series of branches) and check them into a new repository.
781 </para>
782
783 <para>
784 The following commands illustrate some of the steps you could use to
785 import the <filename>yocto/standard/common-pc/base</filename>
786 kernel into a secondary SCM:
787 <literallayout class='monospaced'>
788 $ git checkout yocto/standard/common-pc/base
789 $ cd .. ; echo linux/.git &gt; .cvsignore
790 $ cvs import -m "initial import" linux MY_COMPANY start
791 </literallayout>
792 </para>
793
794 <para>
795 You could now relocate the CVS repository and use it in a centralized manner.
796 </para>
797
798 <para>
799 The following commands illustrate how you can condense and merge two BSPs into a
800 second SCM:
801 <literallayout class='monospaced'>
802 $ git checkout yocto/standard/common-pc/base
803 $ git merge yocto/standard/common-pc-64/base
804 # resolve any conflicts and commit them
805 $ cd .. ; echo linux/.git &gt; .cvsignore
806 $ cvs import -m "initial import" linux MY_COMPANY start
807 </literallayout>
808 </para>
809 </section>
810
811 <section id='importing-changes-for-build'>
812 <title>Importing Changes for the Build</title>
813
814 <para>
815 Once development has reached a suitable point in the second development
816 environment, you need to export the changes as patches.
817 To export them, place the changes in a recipe and
818 automatically apply them to the kernel during patching.
819 </para>
820 </section>
821 </section>
822
823 <section id='bsp-creating'>
824 <title>Creating a BSP Based on an Existing Similar BSP</title>
825
826 <para>
827 This section overviews the process of creating a BSP based on an
828 existing similar BSP.
829 The information is introductory in nature and does not provide step-by-step examples.
830 For detailed information on how to create a new BSP, see
831 the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
832 Yocto Project Board Support Package (BSP) Developer's Guide, or see the
833 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
834 wiki page.
835 </para>
836
837 <para>
838 The basic steps you need to follow are:
839 <orderedlist>
840 <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
841 You must create a local
842 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
843 by either creating a Git repository (recommended) or
844 extracting a Yocto Project release tarball.</para></listitem>
845 <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
846 Try to map your board features as closely to the features of a BSP that is
847 already supported and exists in the Yocto Project.
848 Starting with something as close as possible to your board makes developing
849 your BSP easier.
850 You can find all the BSPs that are supported and ship with the Yocto Project
851 on the Yocto Project's Download page at
852 <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
853 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
854 You need to either have a local Git repository of the base BSP set up or
855 have downloaded and extracted the files from a release BSP tarball.
856 Either method gives you access to the BSP source files.</para></listitem>
857 <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
858 BSP work:</emphasis>
859 Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
860 <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
861 Configuration changes involve the files in the BSP's <filename>conf</filename>
862 directory.
863 Changes include creating a machine-specific configuration file and editing the
864 <filename>layer.conf</filename> file.
865 The configuration changes identify the kernel you will be using.
866 Recipe changes include removing, modifying, or adding new recipe files that
867 instruct the build process on what features to include in the image.</para></listitem>
868 <listitem><para><emphasis>Prepare for the build:</emphasis>
869 Before you actually initiate the build, you need to set up the build environment
870 by sourcing the environment initialization script.
871 After setting up the environment, you need to make some build configuration
872 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
873 files.</para></listitem>
874 <listitem><para><emphasis>Build the image:</emphasis>
875 The OpenEmbedded build system uses BitBake to create the image.
876 You need to decide on the type of image you are going to build (e.g. minimal, base,
877 core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
878 command.</para></listitem>
879 </orderedlist>
880 </para>
881 </section>
882
883 <section id='tip-dirty-string'>
884 <title>"-dirty" String</title>
885
886 <para>
887 If kernel images are being built with "-dirty" on the end of the version
888 string, this simply means that modifications in the source
889 directory have not been committed.
890 <literallayout class='monospaced'>
891 $ git status
892 </literallayout>
893 </para>
894
895 <para>
896 You can use the above Git command to report modified, removed, or added files.
897 You should commit those changes to the tree regardless of whether they will be saved,
898 exported, or used.
899 Once you commit the changes you need to rebuild the kernel.
900 </para>
901
902 <para>
903 To brute force pickup and commit all such pending changes, enter the following:
904 <literallayout class='monospaced'>
905 $ git add .
906 $ git commit -s -a -m "getting rid of -dirty"
907 </literallayout>
908 </para>
909
910 <para>
911 Next, rebuild the kernel.
912 </para>
913 </section>
914 </section>
915</chapter>
916<!--
917vim: expandtab tw=80 ts=4
918-->
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
new file mode 100644
index 0000000000..1290994257
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -0,0 +1,392 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='kernel-concepts'>
6
7<title>Yocto Project Kernel Concepts</title>
8
9<section id='concepts-org'>
10 <title>Introduction</title>
11 <para>
12 This chapter provides conceptual information about the kernel:
13 <itemizedlist>
14 <listitem><para>Kernel Goals</para></listitem>
15 <listitem><para>Kernel Development and Maintenance Overview</para></listitem>
16 <listitem><para>Kernel Architecture</para></listitem>
17 <listitem><para>Kernel Tools</para></listitem>
18 </itemizedlist>
19 </para>
20</section>
21
22 <section id='kernel-goals'>
23 <title>Kernel Goals</title>
24 <para>
25 The complexity of embedded kernel design has increased dramatically.
26 Whether it is managing multiple implementations of a particular feature or tuning and
27 optimizing board specific features, both flexibility and maintainability are key concerns.
28 The Linux kernels available through the Yocto Project are presented with the embedded
29 developer's needs in mind and have evolved to assist in these key concerns.
30 For example, prior methods such as applying hundreds of patches to an extracted
31 tarball have been replaced with proven techniques that allow easy inspection,
32 bisection and analysis of changes.
33 Application of these techniques also creates a platform for performing integration and
34 collaboration with the thousands of upstream development projects.
35 </para>
36 <para>
37 With all these considerations in mind, the Yocto Project's kernel and development team
38 strives to attain these goals:
39 <itemizedlist>
40 <listitem><para>Allow the end user to leverage community best practices to seamlessly
41 manage the development, build and debug cycles.</para></listitem>
42 <listitem><para>Create a platform for performing integration and collaboration with the
43 thousands of upstream development projects that exist.</para></listitem>
44 <listitem><para>Provide mechanisms that support many different work flows, front-ends and
45 management techniques.</para></listitem>
46 <listitem><para>Deliver the most up-to-date kernel possible while still ensuring that
47 the baseline kernel is the most stable official release.</para></listitem>
48 <listitem><para>Include major technological features as part of the Yocto Project's
49 upward revision strategy.</para></listitem>
50 <listitem><para>Present a kernel Git repository that, similar to the upstream
51 <filename>kernel.org</filename> tree,
52 has a clear and continuous history.</para></listitem>
53 <listitem><para>Deliver a key set of supported kernel types, where each type is tailored
54 to meet a specific use (e.g. networking, consumer, devices, and so forth).</para></listitem>
55 <listitem><para>Employ a Git branching strategy that, from a developer's point of view,
56 results in a linear path from the baseline <filename>kernel.org</filename>,
57 through a select group of features and
58 ends with their BSP-specific commits.</para></listitem>
59 </itemizedlist>
60 </para>
61 </section>
62
63 <section id='kernel-big-picture'>
64 <title>Yocto Project Kernel Development and Maintenance Overview</title>
65 <para>
66 Kernels available through the Yocto Project, like other kernels, are based off the Linux
67 kernel releases from <ulink url='http://www.kernel.org'></ulink>.
68 At the beginning of a major development cycle, the Yocto Project team
69 chooses its kernel based on factors such as release timing, the anticipated release
70 timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
71 feature requirements.
72 Typically, the kernel chosen is in the
73 final stages of development by the community.
74 In other words, the kernel is in the release
75 candidate or "rc" phase and not yet a final release.
76 But, by being in the final stages of external development, the team knows that the
77 <filename>kernel.org</filename> final release will clearly be within the early stages of
78 the Yocto Project development window.
79 </para>
80 <para>
81 This balance allows the team to deliver the most up-to-date kernel
82 possible, while still ensuring that the team has a stable official release for
83 the baseline Linux kernel version.
84 </para>
85 <para>
86 The ultimate source for kernels available through the Yocto Project are released kernels
87 from <filename>kernel.org</filename>.
88 In addition to a foundational kernel from <filename>kernel.org</filename>, the
89 kernels available contain a mix of important new mainline
90 developments, non-mainline developments (when there is no alternative),
91 Board Support Package (BSP) developments,
92 and custom features.
93 These additions result in a commercially released Yocto Project Linux kernel that caters
94 to specific embedded designer needs for targeted hardware.
95 </para>
96 <para>
97 Once a kernel is officially released, the Yocto Project team goes into
98 their next development cycle, or upward revision (uprev) cycle, while still
99 continuing maintenance on the released kernel.
100 It is important to note that the most sustainable and stable way
101 to include feature development upstream is through a kernel uprev process.
102 Back-porting hundreds of individual fixes and minor features from various
103 kernel versions is not sustainable and can easily compromise quality.
104 </para>
105 <para>
106 During the uprev cycle, the Yocto Project team uses an ongoing analysis of
107 kernel development, BSP support, and release timing to select the best
108 possible <filename>kernel.org</filename> version.
109 The team continually monitors community kernel
110 development to look for significant features of interest.
111 The team does consider back-porting large features if they have a significant advantage.
112 User or community demand can also trigger a back-port or creation of new
113 functionality in the Yocto Project baseline kernel during the uprev cycle.
114 </para>
115 <para>
116 Generally speaking, every new kernel both adds features and introduces new bugs.
117 These consequences are the basic properties of upstream kernel development and are
118 managed by the Yocto Project team's kernel strategy.
119 It is the Yocto Project team's policy to not back-port minor features to the released kernel.
120 They only consider back-porting significant technological jumps - and, that is done
121 after a complete gap analysis.
122 The reason for this policy is that back-porting any small to medium sized change
123 from an evolving kernel can easily create mismatches, incompatibilities and very
124 subtle errors.
125 </para>
126 <para>
127 These policies result in both a stable and a cutting
128 edge kernel that mixes forward ports of existing features and significant and critical
129 new functionality.
130 Forward porting functionality in the kernels available through the Yocto Project kernel
131 can be thought of as a "micro uprev."
132 The many “micro uprevs” produce a kernel version with a mix of
133 important new mainline, non-mainline, BSP developments and feature integrations.
134 This kernel gives insight into new features and allows focused
135 amounts of testing to be done on the kernel, which prevents
136 surprises when selecting the next major uprev.
137 The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
138 feature and BSP development.
139 </para>
140 </section>
141
142 <section id='kernel-architecture'>
143 <title>Kernel Architecture</title>
144 <para>
145 This section describes the architecture of the kernels available through the
146 Yocto Project and provides information
147 on the mechanisms used to achieve that architecture.
148 </para>
149
150 <section id='architecture-overview'>
151 <title>Overview</title>
152 <para>
153 As mentioned earlier, a key goal of the Yocto Project is to present the
154 developer with
155 a kernel that has a clear and continuous history that is visible to the user.
156 The architecture and mechanisms used achieve that goal in a manner similar to the
157 upstream <filename>kernel.org</filename>.
158 </para>
159 <para>
160 You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
161 added features logically structured on top of the baseline.
162 The features are tagged and organized by way of a branching strategy implemented by the
163 source code manager (SCM) Git.
164 For information on Git as applied to the Yocto Project, see the
165 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
166 Yocto Project Development Manual.
167 </para>
168 <para>
169 The result is that the user has the ability to see the added features and
170 the commits that make up those features.
171 In addition to being able to see added features, the user can also view the history of what
172 made up the baseline kernel.
173 </para>
174 <para>
175 The following illustration shows the conceptual Yocto Project kernel.
176 </para>
177 <para>
178 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
179 </para>
180 <para>
181 In the illustration, the "Kernel.org Branch Point"
182 marks the specific spot (or release) from
183 which the Yocto Project kernel is created.
184 From this point "up" in the tree, features and differences are organized and tagged.
185 </para>
186 <para>
187 The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
188 type and BSP that is organized further up the tree.
189 Placing these common features in the
190 tree this way means features don't have to be duplicated along individual branches of the
191 structure.
192 </para>
193 <para>
194 From the Yocto Project Baseline Kernel, branch points represent specific functionality
195 for individual BSPs as well as real-time kernels.
196 The illustration represents this through three BSP-specific branches and a real-time
197 kernel branch.
198 Each branch represents some unique functionality for the BSP or a real-time kernel.
199 </para>
200 <para>
201 In this example structure, the real-time kernel branch has common features for all
202 real-time kernels and contains
203 more branches for individual BSP-specific real-time kernels.
204 The illustration shows three branches as an example.
205 Each branch points the way to specific, unique features for a respective real-time
206 kernel as they apply to a given BSP.
207 </para>
208 <para>
209 The resulting tree structure presents a clear path of markers (or branches) to the
210 developer that, for all practical purposes, is the kernel needed for any given set
211 of requirements.
212 </para>
213 </section>
214
215 <section id='branching-and-workflow'>
216 <title>Branching Strategy and Workflow</title>
217 <para>
218 The Yocto Project team creates kernel branches at points where functionality is
219 no longer shared and thus, needs to be isolated.
220 For example, board-specific incompatibilities would require different functionality
221 and would require a branch to separate the features.
222 Likewise, for specific kernel features, the same branching strategy is used.
223 </para>
224 <para>
225 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.
227 This strategy also results in not having to store the same feature twice
228 internally in the tree.
229 Rather, the kernel team stores the unique differences required to apply the
230 feature onto the kernel type in question.
231 <note>
232 The Yocto Project team strives to place features in the tree such that they can be
233 shared by all boards and kernel types where possible.
234 However, during development cycles or when large features are merged,
235 the team cannot always follow this practice.
236 In those cases, the team uses isolated branches to merge features.
237 </note>
238 </para>
239 <para>
240 BSP-specific code additions are handled in a similar manner to kernel-specific additions.
241 Some BSPs only make sense given certain kernel types.
242 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.
244 From the perspective of the tools that create the BSP branch, the BSP is really no
245 different than a feature.
246 Consequently, the same branching strategy applies to BSPs as it does to features.
247 So again, rather than store the BSP twice, the team only stores the unique
248 differences for the BSP across the supported multiple kernels.
249 </para>
250 <para>
251 While this strategy can result in a tree with a significant number of branches, it is
252 important to realize that from the developer's point of view, there is a linear
253 path that travels from the baseline <filename>kernel.org</filename>, through a select
254 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
256 to the developer on a day-to-day basis.
257 From the developer's perspective, this path is the "master" branch.
258 The developer does not need to be aware of the existence of any other branches at all.
259 Of course, there is value in the existence of these branches
260 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
262 code <filename>diff</filename> level is now a trivial operation.
263 </para>
264 <para>
265 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
267 considered an "upstream source" and viewed as a series of
268 historical and documented modifications (commits).
269 These modifications represent the development and stabilization done
270 by the Yocto Project kernel development team.
271 </para>
272 <para>
273 Because commits only change at significant release points in the product life cycle,
274 developers can work on a branch created
275 from the last relevant commit in the shipped Yocto Project kernel.
276 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.
278 </para>
279 </section>
280
281 <section id='source-code-manager-git'>
282 <title>Source Code Manager - Git</title>
283 <para>
284 The Source Code Manager (SCM) is Git.
285 This SCM is the obvious mechanism for meeting the previously mentioned goals.
286 Not only is it the SCM for <filename>kernel.org</filename> but,
287 Git continues to grow in popularity and supports many different work flows,
288 front-ends and management techniques.
289 </para>
290 <para>
291 You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
292 You can also get an introduction to Git as it applies to the Yocto Project in the
293 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
294 section in the Yocto Project Development Manual.
295 These referenced sections overview Git and describe a minimal set of
296 commands that allows you to be functional using Git.
297 <note>
298 You can use as much, or as little, of what Git has to offer to accomplish what
299 you need for your project.
300 You do not have to be a "Git Master" in order to use it with the Yocto Project.
301 </note>
302 </para>
303 </section>
304 </section>
305
306 <section id='kernel-configuration'>
307 <title>Kernel Configuration</title>
308 <para>
309 Kernel configuration, along with kernel features, defines how a kernel
310 image is built for the Yocto Project.
311 Through configuration settings, you can customize a Yocto Project kernel to be
312 specific to particular hardware.
313 For example, you can specify sound support or networking support.
314 This section describes basic concepts behind Kernel configuration within the
315 Yocto Project and references you to other areas for specific configuration
316 applications.
317 </para>
318
319 <para>
320 Conceptually, configuration of a Yocto Project kernel occurs similarly to that needed for any
321 Linux kernel.
322 The build process for a Yocto Project kernel uses a <filename>.config</filename> file, which
323 is created through the Linux Kernel Configuration (LKC) tool.
324 You can directly set various configurations in the
325 <filename>.config</filename> file by using the <filename>menuconfig</filename>
326 tool as built by BitBake.
327 You can also define configurations in the file by using configuration fragments.
328 <note>
329 It is not recommended that you edit the <filename>.config</filename> file directly.
330 </note>
331 Here are some brief descriptions of the ways you can affect the
332 <filename>.config</filename> file:
333 <itemizedlist>
334 <listitem><para><emphasis>The <filename>menuconfig</filename> Tool:</emphasis>
335 One of many front-ends that allows you to define kernel configurations.
336 Some others are <filename>make config</filename>,
337 <filename>make nconfig</filename>, and <filename>make gconfig</filename>.
338 In the Yocto Project environment, you must use BitBake to build the
339 <filename>menuconfig</filename> tool before you can use it to define
340 configurations:
341 <literallayout class='monospaced'>
342 $ bitbake linux-yocto -c menuconfig
343 </literallayout>
344 After the tool is built, you can interact with it normally.
345 You can see how <filename>menuconfig</filename> is used to change a simple
346 kernel configuration in the
347 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
348 section of the Yocto Project Development Manual.
349 For general information on <filename>menuconfig</filename>, see
350 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
351 </para></listitem>
352 <listitem><para><emphasis>Configuration Fragments:</emphasis> A file with a
353 list of kernel options just as they would appear syntactically in the
354 <filename>.config</filename> file.
355 Configuration fragments are typically logical groupings and are assembled
356 by the OpenEmbedded build system to produce input used by the LKC
357 that ultimately generates the <filename>.config</filename> file.</para>
358 <para>The
359 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink></filename>
360 variable can be used to list configuration fragments.
361 For further discussion on applying configuration fragments, see the
362 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-kernel'>Linux Kernel Configuration</ulink>"
363 section in the Yocto Project Board Support Package (BSP) Guide.
364 </para></listitem>
365 </itemizedlist>
366 </para>
367 </section>
368
369 <section id='kernel-tools'>
370 <title>Kernel Tools</title>
371 <para>
372 Since most standard workflows involve moving forward with an existing tree by
373 continuing to add and alter the underlying baseline, the tools that manage
374 the Yocto Project's kernel construction are largely hidden from the developer to
375 present a simplified view of the kernel for ease of use.
376 </para>
377 <para>
378 Fundamentally, the kernel tools that manage and construct the
379 Yocto Project kernel accomplish the following:
380 <itemizedlist>
381 <listitem><para>Group patches into named, reusable features.</para></listitem>
382 <listitem><para>Allow top-down control of included features.</para></listitem>
383 <listitem><para>Bind kernel configurations to kernel patches and features.</para></listitem>
384 <listitem><para>Present a seamless Git repository that blends Yocto Project value
385 with the <filename>kernel.org</filename> history and development.</para></listitem>
386 </itemizedlist>
387 </para>
388 </section>
389</chapter>
390<!--
391vim: expandtab tw=80 ts=4
392-->
diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl
new file mode 100644
index 0000000000..8eb69050ba
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-customization.xsl
@@ -0,0 +1,8 @@
1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
3
4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
5
6<!-- <xsl:param name="generate.toc" select="'article nop'"></xsl:param> -->
7
8</xsl:stylesheet>
diff --git a/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml
new file mode 100644
index 0000000000..9d9aef6d06
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-examples.xml
@@ -0,0 +1,918 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='kernel-how-to'>
6
7<title>Working with the Yocto Project Kernel</title>
8
9
10<section id='actions-org'>
11 <title>Introduction</title>
12 <para>
13 This chapter describes how to accomplish tasks involving a kernel's tree structure.
14 The information is designed to help the developer that wants to modify the Yocto
15 Project kernel and contribute changes upstream to the Yocto Project.
16 The information covers the following:
17 <itemizedlist>
18 <listitem><para>Tree construction</para></listitem>
19 <listitem><para>Build strategies</para></listitem>
20 <listitem><para>Workflow examples</para></listitem>
21 </itemizedlist>
22 </para>
23</section>
24
25 <section id='tree-construction'>
26 <title>Tree Construction</title>
27 <para>
28 This section describes construction of the Yocto Project kernel source repositories
29 as accomplished by the Yocto Project team to create kernel repositories.
30 These kernel repositories are found under the heading "Yocto Linux Kernel" at
31 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
32 and can be shipped as part of a Yocto Project release.
33 The team creates these repositories by
34 compiling and executing the set of feature descriptions for every BSP/feature
35 in the product.
36 Those feature descriptions list all necessary patches,
37 configuration, branching, tagging and feature divisions found in a kernel.
38 Thus, the Yocto Project kernel repository (or tree) is built.
39 </para>
40 <para>
41 The existence of this tree allows you to access and clone a particular
42 Yocto Project kernel repository and use it to build images based on their configurations
43 and features.
44 </para>
45 <para>
46 You can find the files used to describe all the valid features and BSPs
47 in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
48 Git tree.
49 For example, the following command clones the Yocto Project baseline kernel that
50 branched off of <filename>linux.org</filename> version 3.4:
51 <literallayout class='monospaced'>
52 $ git clone git://git.yoctoproject.org/linux-yocto-3.4
53 </literallayout>
54 For another example of how to set up a local Git repository of the Yocto Project
55 kernel files, see the
56 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
57 item in the Yocto Project Development Manual.
58 </para>
59 <para>
60 Once you have cloned the kernel Git repository on your local machine, you can
61 switch to the <filename>meta</filename> branch within the repository.
62 Here is an example that assumes the local Git repository for the kernel is in
63 a top-level directory named <filename>linux-yocto-3.4</filename>:
64 <literallayout class='monospaced'>
65 $ cd ~/linux-yocto-3.4
66 $ git checkout -b meta origin/meta
67 </literallayout>
68 Once you have checked out and switched to the <filename>meta</filename> branch,
69 you can see a snapshot of all the kernel configuration and feature descriptions that are
70 used to build that particular kernel repository.
71 These descriptions are in the form of <filename>.scc</filename> files.
72 </para>
73 <para>
74 You should realize, however, that browsing your local kernel repository
75 for feature descriptions and patches is not an effective way to determine what is in a
76 particular kernel branch.
77 Instead, you should use Git directly to discover the changes in a branch.
78 Using Git is an efficient and flexible way to inspect changes to the kernel.
79 For examples showing how to use Git to inspect kernel commits, see the following sections
80 in this chapter.
81 <note>
82 Ground up reconstruction of the complete kernel tree is an action only taken by the
83 Yocto Project team during an active development cycle.
84 When you create a clone of the kernel Git repository, you are simply making it
85 efficiently available for building and development.
86 </note>
87 </para>
88 <para>
89 The following steps describe what happens when the Yocto Project Team constructs
90 the Yocto Project kernel source Git repository (or tree) found at
91 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
92 introduction of a new top-level kernel feature or BSP.
93 These are the actions that effectively create the tree
94 that includes the new feature, patch or BSP:
95 <orderedlist>
96 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
97 Normally, this feature is a BSP for a particular kernel type.</para></listitem>
98 <listitem><para>The file that describes the top-level feature is located by searching
99 these system directories:
100 <itemizedlist>
101 <listitem><para>The in-tree kernel-cache directories, which are located
102 in <filename>meta/cfg/kernel-cache</filename></para></listitem>
103 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
104 found in recipes</para></listitem>
105 </itemizedlist>
106 For a typical build, the target of the search is a
107 feature description in an <filename>.scc</filename> file
108 whose name follows this format:
109 <literallayout class='monospaced'>
110 &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
111 </literallayout>
112 </para></listitem>
113 <listitem><para>Once located, the feature description is either compiled into a simple script
114 of actions, or into an existing equivalent script that is already part of the
115 shipped kernel.</para></listitem>
116 <listitem><para>Extra features are appended to the top-level feature description.
117 These features can come from the
118 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
119 variable in recipes.</para></listitem>
120 <listitem><para>Each extra feature is located, compiled and appended to the script
121 as described in step three.</para></listitem>
122 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
123 directories.
124 These directories are descriptions of all the branches, tags, patches and configurations that
125 need to be applied to the base Git repository to completely create the
126 source (build) branch for the new BSP or feature.</para></listitem>
127 <listitem><para>The base repository is cloned, and the actions
128 listed in the <filename>meta-*</filename> directories are applied to the
129 tree.</para></listitem>
130 <listitem><para>The Git repository is left with the desired branch checked out and any
131 required branching, patching and tagging has been performed.</para></listitem>
132 </orderedlist>
133 </para>
134 <para>
135 The kernel tree is now ready for developer consumption to be locally cloned,
136 configured, and built into a Yocto Project kernel specific to some target hardware.
137 <note><para>The generated <filename>meta-*</filename> directories add to the kernel
138 as shipped with the Yocto Project release.
139 Any add-ons and configuration data are applied to the end of an existing branch.
140 The full repository generation that is found in the
141 official Yocto Project kernel repositories at
142 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
143 is the combination of all supported boards and configurations.</para>
144 <para>The technique the Yocto Project team uses is flexible and allows for seamless
145 blending of an immutable history with additional patches specific to a
146 deployment.
147 Any additions to the kernel become an integrated part of the branches.</para>
148 </note>
149 </para>
150 </section>
151
152 <section id='build-strategy'>
153 <title>Build Strategy</title>
154 <para>
155 Once a local Git repository of the Yocto Project kernel exists on a development system,
156 you can consider the compilation phase of kernel development - building a kernel image.
157 Some prerequisites exist that are validated by the build process before compilation
158 starts:
159 </para>
160
161 <itemizedlist>
162 <listitem><para>The
163 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
164 to the kernel Git repository.</para></listitem>
165 <listitem><para>A BSP build branch exists.
166 This branch has the following form:
167 <literallayout class='monospaced'>
168 &lt;kernel_type&gt;/&lt;bsp_name&gt;
169 </literallayout></para></listitem>
170 </itemizedlist>
171
172 <para>
173 The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
174 Other means, however, do exist, such as as bootstrapping a BSP, see
175 the "<link linkend='workflow-examples'>Workflow Examples</link>".
176 </para>
177
178 <para>
179 Before building a kernel, the build process verifies the tree
180 and configures the kernel by processing all of the
181 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
182 files.
183 As the features are compiled, associated kernel configuration fragments are noted
184 and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
185 The fragments are migrated, pre-processed and passed to the Linux Kernel
186 Configuration subsystem (<filename>lkc</filename>) as raw input in the form
187 of a <filename>.config</filename> file.
188 The <filename>lkc</filename> uses its own internal dependency constraints to do the final
189 processing of that information and generates the final <filename>.config</filename> file
190 that is used during compilation.
191 </para>
192
193 <para>
194 Using the board's architecture and other relevant values from the board's template,
195 kernel compilation is started and a kernel image is produced.
196 </para>
197
198 <para>
199 The other thing that you notice once you configure a kernel is that
200 the build process generates a build tree that is separate from your kernel's local Git
201 source repository tree.
202 This build tree has a name that uses the following form, where
203 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
204 of the Yocto Project supported kernel types (e.g. "standard"):
205 <literallayout class='monospaced'>
206 linux-${MACHINE}-&lt;kernel_type&gt;-build
207 </literallayout>
208 </para>
209
210 <para>
211 The existing support in the <filename>kernel.org</filename> tree achieves this
212 default functionality.
213 </para>
214
215 <para>
216 This behavior means that all the generated files for a particular machine or BSP are now in
217 the build tree directory.
218 The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
219 files, the <filename>.a</filename> files, and so forth.
220 Since each machine or BSP has its own separate build directory in its own separate branch
221 of the Git repository, you can easily switch between different builds.
222 </para>
223 </section>
224
225 <section id='workflow-examples'>
226 <title>Workflow Examples</title>
227
228 <para>
229 As previously noted, the Yocto Project kernel has built-in Git integration.
230 However, these utilities are not the only way to work with the kernel repository.
231 The Yocto Project has not made changes to Git or to other tools that
232 would invalidate alternate workflows.
233 Additionally, the way the kernel repository is constructed results in using
234 only core Git functionality, thus allowing any number of tools or front ends to use the
235 resulting tree.
236 </para>
237
238 <para>
239 This section contains several workflow examples.
240 Many of the examples use Git commands.
241 You can find Git documentation at
242 <ulink url='http://git-scm.com/documentation'></ulink>.
243 You can find a simple overview of using Git with the Yocto Project in the
244 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
245 section of the Yocto Project Development Manual.
246 </para>
247
248 <section id='change-inspection-kernel-changes-commits'>
249 <title>Change Inspection: Changes/Commits</title>
250
251 <para>
252 A common question when working with a kernel is:
253 "What changes have been applied to this tree?"
254 </para>
255
256 <para>
257 In projects that have a collection of directories that
258 contain patches to the kernel, it is possible to inspect or "grep" the contents
259 of the directories to get a general feel for the changes.
260 This sort of patch inspection is not an efficient way to determine what has been
261 done to the kernel.
262 The reason it is inefficient is because there are many optional patches that are
263 selected based on the kernel type and the feature description.
264 Additionally, patches could exist in directories that are not included in the search.
265 </para>
266
267 <para>
268 A more efficient way to determine what has changed in the branch is to use
269 Git and inspect or search the kernel tree.
270 This method gives you a full view of not only the source code modifications,
271 but also provides the reasons for the changes.
272 </para>
273
274 <section id='what-changed-in-a-kernel'>
275 <title>What Changed in a Kernel?</title>
276
277 <para>
278 Following are a few examples that show how to use Git commands to examine changes.
279 Because Git repositories in the Yocto Project do not break existing Git
280 functionality, and because there exists many permutations of these types of
281 Git commands, many methods exist by which you can discover changes.
282 <note>
283 In the following examples, unless you provide a commit range,
284 <filename>kernel.org</filename> history is blended with Yocto Project
285 kernel changes.
286 You can form ranges by using branch names from the kernel tree as the
287 upper and lower commit markers with the Git commands.
288 You can see the branch names through the web interface to the
289 Yocto Project source repositories at
290 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
291 For example, the branch names for the <filename>linux-yocto-3.4</filename>
292 kernel repository can be seen at
293 <ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
294 </note>
295 To see a full range of the changes, use the
296 <filename>git whatchanged</filename> command and specify a commit range
297 for the branch (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
298 </para>
299
300 <para>
301 Here is an example that looks at what has changed in the
302 <filename>emenlow</filename> branch of the
303 <filename>linux-yocto-3.4</filename> kernel.
304 The lower commit range is the commit associated with the
305 <filename>standard/base</filename> branch, while
306 the upper commit range is the commit associated with the
307 <filename>standard/emenlow</filename> branch.
308 <literallayout class='monospaced'>
309 $ git whatchanged origin/standard/base..origin/standard/emenlow
310 </literallayout>
311 </para>
312
313 <para>
314 To see a summary of changes use the <filename>git log</filename> command.
315 Here is an example using the same branches:
316 <literallayout class='monospaced'>
317 $ git log --oneline origin/standard/base..origin/standard/emenlow
318 </literallayout>
319 The <filename>git log</filename> output might be more useful than
320 the <filename>git whatchanged</filename> as you get
321 a short, one-line summary of each change and not the entire commit.
322 </para>
323
324 <para>
325 If you want to see code differences associated with all the changes, use
326 the <filename>git diff</filename> command.
327 Here is an example:
328 <literallayout class='monospaced'>
329 $ git diff origin/standard/base..origin/standard/emenlow
330 </literallayout>
331 </para>
332
333 <para>
334 You can see the commit log messages and the text differences using the
335 <filename>git show</filename> command:
336 Here is an example:
337 <literallayout class='monospaced'>
338 $ git show origin/standard/base..origin/standard/emenlow
339 </literallayout>
340 </para>
341
342 <para>
343 You can create individual patches for each change by using the
344 <filename>git format-patch</filename> command.
345 Here is an example that that creates patch files for each commit and
346 places them in your <filename>Documents</filename> directory:
347 <literallayout class='monospaced'>
348 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
349 </literallayout>
350 </para>
351 </section>
352
353 <section id='show-a-particular-feature-or-branch-change'>
354 <title>Show a Particular Feature or Branch Change</title>
355
356 <para>
357 Developers use tags in the Yocto Project kernel tree to divide changes for significant
358 features or branches.
359 Once you know a particular tag, you can use Git commands
360 to show changes associated with the tag and find the branches that contain
361 the feature.
362 <note>
363 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
364 present, there could be many tags.
365 </note>
366 The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
367 a feature.
368 Here is an example that shows changes tagged by the <filename>systemtap</filename>
369 feature:
370 <literallayout class='monospaced'>
371 $ git show systemtap
372 </literallayout>
373 You can use the <filename>git branch --contains &lt;tag&gt;</filename> command
374 to show the branches that contain a particular feature.
375 This command shows the branches that contain the <filename>systemtap</filename>
376 feature:
377 <literallayout class='monospaced'>
378 $ git branch --contains systemtap
379 </literallayout>
380 </para>
381
382 <para>
383 You can use many other comparisons to isolate BSP and kernel changes.
384 For example, you can compare against <filename>kernel.org</filename> tags
385 such as the <filename>v3.4</filename> tag.
386 </para>
387 </section>
388 </section>
389
390 <section id='development-saving-kernel-modifications'>
391 <title>Development: Saving Kernel Modifications</title>
392
393 <para>
394 Another common operation is to build a BSP supplied by the Yocto Project, make some
395 changes, rebuild, and then test.
396 Those local changes often need to be exported, shared or otherwise maintained.
397 </para>
398
399 <para>
400 Since the Yocto Project kernel source tree is backed by Git, this activity is
401 much easier as compared to with previous releases.
402 Because Git tracks file modifications, additions and deletions, it is easy
403 to modify the code and later realize that you need to save the changes.
404 It is also easy to determine what has changed.
405 This method also provides many tools to commit, undo and export those modifications.
406 </para>
407
408 <para>
409 This section and its sub-sections, describe general application of Git's
410 <filename>push</filename> and <filename>pull</filename> commands, which are used to
411 get your changes upstream or source your code from an upstream repository.
412 The Yocto Project provides scripts that help you work in a collaborative development
413 environment.
414 For information on these scripts, see the
415 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
416 Upstream and Request a Pull</ulink>" and
417 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
418 sections in the Yocto Project Development Manual.
419 </para>
420
421 <para>
422 There are many ways to save kernel modifications.
423 The technique employed
424 depends on the destination for the patches:
425
426 <itemizedlist>
427 <listitem><para>Bulk storage</para></listitem>
428 <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
429 <listitem><para>External submissions</para></listitem>
430 <listitem><para>Exporting for integration into another Source Code
431 Manager (SCM)</para></listitem>
432 </itemizedlist>
433 </para>
434
435 <para>
436 Because of the following list of issues, the destination of the patches also influences
437 the method for gathering them:
438
439 <itemizedlist>
440 <listitem><para>Bisectability</para></listitem>
441 <listitem><para>Commit headers</para></listitem>
442 <listitem><para>Division of subsystems for separate submission or review</para></listitem>
443 </itemizedlist>
444 </para>
445
446 <section id='bulk-export'>
447 <title>Bulk Export</title>
448
449 <para>
450 This section describes how you can "bulk" export changes that have not
451 been separated or divided.
452 This situation works well when you are simply storing patches outside of the kernel
453 source repository, either permanently or temporarily, and you are not committing
454 incremental changes during development.
455 <note>
456 This technique is not appropriate for full integration of upstream submission
457 because changes are not properly divided and do not provide an avenue for per-change
458 commit messages.
459 Therefore, this example assumes that changes have not been committed incrementally
460 during development and that you simply must gather and export them.
461 </note>
462 <literallayout class='monospaced'>
463 # bulk export of ALL modifications without separation or division
464 # of the changes
465
466 $ git add .
467 $ git commit -s -a -m &lt;msg&gt;
468 or
469 $ git commit -s -a # and interact with $EDITOR
470 </literallayout>
471 </para>
472
473 <para>
474 The previous operations capture all the local changes in the project source
475 tree in a single Git commit.
476 And, that commit is also stored in the project's source tree.
477 </para>
478
479 <para>
480 Once the changes are exported, you can restore them manually using a template
481 or through integration with the <filename>default_kernel</filename>.
482 </para>
483
484 </section>
485
486 <section id='incremental-planned-sharing'>
487 <title>Incremental/Planned Sharing</title>
488
489 <para>
490 This section describes how to save modifications when you are making incremental
491 commits or practicing planned sharing.
492 The examples in this section assume that you have incrementally committed
493 changes to the tree during development and now need to export them.
494 The sections that follow
495 describe how you can export your changes internally through either patches or by
496 using Git commands.
497 </para>
498
499 <para>
500 During development, the following commands are of interest.
501 For full Git documentation, refer to the Git documentation at
502 <ulink url='http://github.com'></ulink>.
503
504 <literallayout class='monospaced'>
505 # edit a file
506 $ vi &lt;path&gt;/file
507 # stage the change
508 $ git add &lt;path&gt;/file
509 # commit the change
510 $ git commit -s
511 # remove a file
512 $ git rm &lt;path&gt;/file
513 # commit the change
514 $ git commit -s
515
516 ... etc.
517 </literallayout>
518 </para>
519
520 <para>
521 Distributed development with Git is possible when you use a universally
522 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
523 specific change set with a specific parent.
524 This identifier is created for you when
525 you create a commit, and is re-created when you amend, alter or re-apply
526 a commit.
527 As an individual in isolation, this is of no interest.
528 However, if you
529 intend to share your tree with normal Git <filename>push</filename> and
530 <filename>pull</filename> operations for
531 distributed development, you should consider the ramifications of changing a
532 commit that you have already shared with others.
533 </para>
534
535 <para>
536 Assuming that the changes have not been pushed upstream, or pulled into
537 another repository, you can update both the commit content and commit messages
538 associated with development by using the following commands:
539
540 <literallayout class='monospaced'>
541 $ Git add &lt;path&gt;/file
542 $ Git commit --amend
543 $ Git rebase or Git rebase -i
544 </literallayout>
545 </para>
546
547 <para>
548 Again, assuming that the changes have not been pushed upstream, and that
549 no pending works-in-progress exist (use <filename>git status</filename> to check), then
550 you can revert (undo) commits by using the following commands:
551
552 <literallayout class='monospaced'>
553 # remove the commit, update working tree and remove all
554 # traces of the change
555 $ git reset --hard HEAD^
556 # remove the commit, but leave the files changed and staged for re-commit
557 $ git reset --soft HEAD^
558 # remove the commit, leave file change, but not staged for commit
559 $ git reset --mixed HEAD^
560 </literallayout>
561 </para>
562
563 <para>
564 You can create branches, "cherry-pick" changes, or perform any number of Git
565 operations until the commits are in good order for pushing upstream
566 or for pull requests.
567 After a <filename>push</filename> or <filename>pull</filename> command,
568 commits are normally considered
569 "permanent" and you should not modify them.
570 If the commits need to be changed, you can incrementally do so with new commits.
571 These practices follow standard Git workflow and the <filename>kernel.org</filename> best
572 practices, which is recommended.
573 <note>
574 It is recommended to tag or branch before adding changes to a Yocto Project
575 BSP or before creating a new one.
576 The reason for this recommendation is because the branch or tag provides a
577 reference point to facilitate locating and exporting local changes.
578 </note>
579 </para>
580
581 <section id='export-internally-via-patches'>
582 <title>Exporting Changes Internally by Using Patches</title>
583
584 <para>
585 This section describes how you can extract committed changes from a working directory
586 by exporting them as patches.
587 Once the changes have been extracted, you can use the patches for upstream submission,
588 place them in a Yocto Project template for automatic kernel patching,
589 or apply them in many other common uses.
590 </para>
591
592 <para>
593 This example shows how to create a directory with sequentially numbered patches.
594 Once the directory is created, you can apply it to a repository using the
595 <filename>git am</filename> command to reproduce the original commit and all
596 the related information such as author, date, commit log, and so forth.
597 <note>
598 The new commit identifiers (ID) will be generated upon re-application.
599 This action reflects that the commit is now applied to an underlying commit
600 with a different ID.
601 </note>
602 <literallayout class='monospaced'>
603 # &lt;first-commit&gt; can be a tag if one was created before development
604 # began. It can also be the parent branch if a branch was created
605 # before development began.
606
607 $ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
608 </literallayout>
609 </para>
610
611 <para>
612 In other words:
613 <literallayout class='monospaced'>
614 # Identify commits of interest.
615
616 # If the tree was tagged before development
617 $ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
618
619 # If no tags are available
620 $ git format-patch -o &lt;save dir&gt; HEAD^ # last commit
621 $ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
622 $ git whatchanged # identify last commit
623 $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
624 $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
625 </literallayout>
626 </para>
627 </section>
628
629 <section id='export-internally-via-git'>
630 <title>Exporting Changes Internally by Using Git</title>
631
632 <para>
633 This section describes how you can export changes from a working directory
634 by pushing the changes into a master repository or by making a pull request.
635 Once you have pushed the changes to the master repository, you can then
636 pull those same changes into a new kernel build at a later time.
637 </para>
638
639 <para>
640 Use this command form to push the changes:
641 <literallayout class='monospaced'>
642 $ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
643 &lt;local_branch&gt;:&lt;remote_branch&gt;
644 </literallayout>
645 </para>
646
647 <para>
648 For example, the following command pushes the changes from your local branch
649 <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
650 in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
651 <literallayout class='monospaced'>
652 $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
653 yocto/standard/common-pc/base:yocto/standard/common-pc/base
654 </literallayout>
655 </para>
656
657 <para>
658 A pull request entails using the <filename>git request-pull</filename> command to compose
659 an email to the
660 maintainer requesting that a branch be pulled into the master repository, see
661 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
662 <note>
663 Other commands such as <filename>git stash</filename> or branching can also be used to save
664 changes, but are not covered in this document.
665 </note>
666 </para>
667 </section>
668 </section>
669
670 <section id='export-for-external-upstream-submission'>
671 <title>Exporting Changes for External (Upstream) Submission</title>
672
673 <para>
674 This section describes how to export changes for external upstream submission.
675 If the patch series is large or the maintainer prefers to pull
676 changes, you can submit these changes by using a pull request.
677 However, it is common to send patches as an email series.
678 This method allows easy review and integration of the changes.
679 <note>
680 Before sending patches for review be sure you understand the
681 community standards for submitting and documenting changes and follow their best practices.
682 For example, kernel patches should follow standards such as:
683 <itemizedlist>
684 <listitem><para>
685 <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
686 <listitem><para>Documentation/SubmittingPatches (in any linux
687 kernel source tree)</para></listitem>
688 </itemizedlist>
689 </note>
690 </para>
691
692 <para>
693 The messages used to commit changes are a large part of these standards.
694 Consequently, be sure that the headers for each commit have the required information.
695 For information on how to follow the Yocto Project commit message standards, see the
696 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
697 Change</ulink>" section in the Yocto Project Development Manual.
698 </para>
699
700 <para>
701 If the initial commits were not properly documented or do not meet those standards,
702 you can re-base by using the <filename>git rebase -i</filename> command to
703 manipulate the commits and
704 get them into the required format.
705 Other techniques such as branching and cherry-picking commits are also viable options.
706 </para>
707
708 <para>
709 Once you complete the commits, you can generate the email that sends the patches
710 to the maintainer(s) or lists that review and integrate changes.
711 The command <filename>git send-email</filename> is commonly used to ensure
712 that patches are properly
713 formatted for easy application and avoid mailer-induced patch damage.
714 </para>
715
716 <para>
717 The following is an example of dumping patches for external submission:
718 <literallayout class='monospaced'>
719 # dump the last 4 commits
720 $ git format-patch --thread -n -o ~/rr/ HEAD^^^^
721 $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
722 --to foo@yoctoproject.org --to bar@yoctoproject.org \
723 --cc list@yoctoproject.org ~/rr
724 # the editor is invoked for the 0/N patch, and when complete the entire
725 # series is sent via email for review
726 </literallayout>
727 </para>
728 </section>
729
730 <section id='export-for-import-into-other-scm'>
731 <title>Exporting Changes for Import into Another SCM</title>
732
733 <para>
734 When you want to export changes for import into another
735 Source Code Manager (SCM), you can use any of the previously discussed
736 techniques.
737 However, if the patches are manually applied to a secondary tree and then
738 that tree is checked into the SCM, you can lose change information such as
739 commit logs.
740 This process is not recommended.
741 </para>
742
743 <para>
744 Many SCMs can directly import Git commits, or can translate Git patches so that
745 information is not lost.
746 Those facilities are SCM-dependent and you should use them whenever possible.
747 </para>
748 </section>
749 </section>
750
751 <section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
752 <title>Working with the Yocto Project Kernel in Another SCM</title>
753
754 <para>
755 This section describes kernel development in an SCM other than Git,
756 which is not the same as exporting changes to another SCM described earlier.
757 For this scenario, you use the OpenEmbedded build system to
758 develop the kernel in a different SCM.
759 The following must be true for you to accomplish this:
760 <itemizedlist>
761 <listitem><para>The delivered Yocto Project kernel must be exported into the second
762 SCM.</para></listitem>
763 <listitem><para>Development must be exported from that secondary SCM into a
764 format that can be used by the OpenEmbedded build system.</para></listitem>
765 </itemizedlist>
766 </para>
767
768 <section id='exporting-delivered-kernel-to-scm'>
769 <title>Exporting the Delivered Kernel to the SCM</title>
770
771 <para>
772 Depending on the SCM, it might be possible to export the entire Yocto Project
773 kernel Git repository, branches and all, into a new environment.
774 This method is preferred because it has the most flexibility and potential to maintain
775 the meta data associated with each commit.
776 </para>
777
778 <para>
779 When a direct import mechanism is not available, it is still possible to
780 export a branch (or series of branches) and check them into a new repository.
781 </para>
782
783 <para>
784 The following commands illustrate some of the steps you could use to
785 import the <filename>yocto/standard/common-pc/base</filename>
786 kernel into a secondary SCM:
787 <literallayout class='monospaced'>
788 $ git checkout yocto/standard/common-pc/base
789 $ cd .. ; echo linux/.git &gt; .cvsignore
790 $ cvs import -m "initial import" linux MY_COMPANY start
791 </literallayout>
792 </para>
793
794 <para>
795 You could now relocate the CVS repository and use it in a centralized manner.
796 </para>
797
798 <para>
799 The following commands illustrate how you can condense and merge two BSPs into a
800 second SCM:
801 <literallayout class='monospaced'>
802 $ git checkout yocto/standard/common-pc/base
803 $ git merge yocto/standard/common-pc-64/base
804 # resolve any conflicts and commit them
805 $ cd .. ; echo linux/.git &gt; .cvsignore
806 $ cvs import -m "initial import" linux MY_COMPANY start
807 </literallayout>
808 </para>
809 </section>
810
811 <section id='importing-changes-for-build'>
812 <title>Importing Changes for the Build</title>
813
814 <para>
815 Once development has reached a suitable point in the second development
816 environment, you need to export the changes as patches.
817 To export them, place the changes in a recipe and
818 automatically apply them to the kernel during patching.
819 </para>
820 </section>
821 </section>
822
823 <section id='bsp-creating'>
824 <title>Creating a BSP Based on an Existing Similar BSP</title>
825
826 <para>
827 This section overviews the process of creating a BSP based on an
828 existing similar BSP.
829 The information is introductory in nature and does not provide step-by-step examples.
830 For detailed information on how to create a new BSP, see
831 the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
832 Yocto Project Board Support Package (BSP) Developer's Guide, or see the
833 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
834 wiki page.
835 </para>
836
837 <para>
838 The basic steps you need to follow are:
839 <orderedlist>
840 <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
841 You must create a local
842 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
843 by either creating a Git repository (recommended) or
844 extracting a Yocto Project release tarball.</para></listitem>
845 <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
846 Try to map your board features as closely to the features of a BSP that is
847 already supported and exists in the Yocto Project.
848 Starting with something as close as possible to your board makes developing
849 your BSP easier.
850 You can find all the BSPs that are supported and ship with the Yocto Project
851 on the Yocto Project's Download page at
852 <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
853 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
854 You need to either have a local Git repository of the base BSP set up or
855 have downloaded and extracted the files from a release BSP tarball.
856 Either method gives you access to the BSP source files.</para></listitem>
857 <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
858 BSP work:</emphasis>
859 Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
860 <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
861 Configuration changes involve the files in the BSP's <filename>conf</filename>
862 directory.
863 Changes include creating a machine-specific configuration file and editing the
864 <filename>layer.conf</filename> file.
865 The configuration changes identify the kernel you will be using.
866 Recipe changes include removing, modifying, or adding new recipe files that
867 instruct the build process on what features to include in the image.</para></listitem>
868 <listitem><para><emphasis>Prepare for the build:</emphasis>
869 Before you actually initiate the build, you need to set up the build environment
870 by sourcing the environment initialization script.
871 After setting up the environment, you need to make some build configuration
872 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
873 files.</para></listitem>
874 <listitem><para><emphasis>Build the image:</emphasis>
875 The OpenEmbedded build system uses BitBake to create the image.
876 You need to decide on the type of image you are going to build (e.g. minimal, base,
877 core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
878 command.</para></listitem>
879 </orderedlist>
880 </para>
881 </section>
882
883 <section id='tip-dirty-string'>
884 <title>"-dirty" String</title>
885
886 <para>
887 If kernel images are being built with "-dirty" on the end of the version
888 string, this simply means that modifications in the source
889 directory have not been committed.
890 <literallayout class='monospaced'>
891 $ git status
892 </literallayout>
893 </para>
894
895 <para>
896 You can use the above Git command to report modified, removed, or added files.
897 You should commit those changes to the tree regardless of whether they will be saved,
898 exported, or used.
899 Once you commit the changes you need to rebuild the kernel.
900 </para>
901
902 <para>
903 To brute force pickup and commit all such pending changes, enter the following:
904 <literallayout class='monospaced'>
905 $ git add .
906 $ git commit -s -a -m "getting rid of -dirty"
907 </literallayout>
908 </para>
909
910 <para>
911 Next, rebuild the kernel.
912 </para>
913 </section>
914 </section>
915</chapter>
916<!--
917vim: expandtab tw=80 ts=4
918-->
diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml
new file mode 100644
index 0000000000..9d9aef6d06
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-faq.xml
@@ -0,0 +1,918 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='kernel-how-to'>
6
7<title>Working with the Yocto Project Kernel</title>
8
9
10<section id='actions-org'>
11 <title>Introduction</title>
12 <para>
13 This chapter describes how to accomplish tasks involving a kernel's tree structure.
14 The information is designed to help the developer that wants to modify the Yocto
15 Project kernel and contribute changes upstream to the Yocto Project.
16 The information covers the following:
17 <itemizedlist>
18 <listitem><para>Tree construction</para></listitem>
19 <listitem><para>Build strategies</para></listitem>
20 <listitem><para>Workflow examples</para></listitem>
21 </itemizedlist>
22 </para>
23</section>
24
25 <section id='tree-construction'>
26 <title>Tree Construction</title>
27 <para>
28 This section describes construction of the Yocto Project kernel source repositories
29 as accomplished by the Yocto Project team to create kernel repositories.
30 These kernel repositories are found under the heading "Yocto Linux Kernel" at
31 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
32 and can be shipped as part of a Yocto Project release.
33 The team creates these repositories by
34 compiling and executing the set of feature descriptions for every BSP/feature
35 in the product.
36 Those feature descriptions list all necessary patches,
37 configuration, branching, tagging and feature divisions found in a kernel.
38 Thus, the Yocto Project kernel repository (or tree) is built.
39 </para>
40 <para>
41 The existence of this tree allows you to access and clone a particular
42 Yocto Project kernel repository and use it to build images based on their configurations
43 and features.
44 </para>
45 <para>
46 You can find the files used to describe all the valid features and BSPs
47 in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
48 Git tree.
49 For example, the following command clones the Yocto Project baseline kernel that
50 branched off of <filename>linux.org</filename> version 3.4:
51 <literallayout class='monospaced'>
52 $ git clone git://git.yoctoproject.org/linux-yocto-3.4
53 </literallayout>
54 For another example of how to set up a local Git repository of the Yocto Project
55 kernel files, see the
56 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
57 item in the Yocto Project Development Manual.
58 </para>
59 <para>
60 Once you have cloned the kernel Git repository on your local machine, you can
61 switch to the <filename>meta</filename> branch within the repository.
62 Here is an example that assumes the local Git repository for the kernel is in
63 a top-level directory named <filename>linux-yocto-3.4</filename>:
64 <literallayout class='monospaced'>
65 $ cd ~/linux-yocto-3.4
66 $ git checkout -b meta origin/meta
67 </literallayout>
68 Once you have checked out and switched to the <filename>meta</filename> branch,
69 you can see a snapshot of all the kernel configuration and feature descriptions that are
70 used to build that particular kernel repository.
71 These descriptions are in the form of <filename>.scc</filename> files.
72 </para>
73 <para>
74 You should realize, however, that browsing your local kernel repository
75 for feature descriptions and patches is not an effective way to determine what is in a
76 particular kernel branch.
77 Instead, you should use Git directly to discover the changes in a branch.
78 Using Git is an efficient and flexible way to inspect changes to the kernel.
79 For examples showing how to use Git to inspect kernel commits, see the following sections
80 in this chapter.
81 <note>
82 Ground up reconstruction of the complete kernel tree is an action only taken by the
83 Yocto Project team during an active development cycle.
84 When you create a clone of the kernel Git repository, you are simply making it
85 efficiently available for building and development.
86 </note>
87 </para>
88 <para>
89 The following steps describe what happens when the Yocto Project Team constructs
90 the Yocto Project kernel source Git repository (or tree) found at
91 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
92 introduction of a new top-level kernel feature or BSP.
93 These are the actions that effectively create the tree
94 that includes the new feature, patch or BSP:
95 <orderedlist>
96 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
97 Normally, this feature is a BSP for a particular kernel type.</para></listitem>
98 <listitem><para>The file that describes the top-level feature is located by searching
99 these system directories:
100 <itemizedlist>
101 <listitem><para>The in-tree kernel-cache directories, which are located
102 in <filename>meta/cfg/kernel-cache</filename></para></listitem>
103 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
104 found in recipes</para></listitem>
105 </itemizedlist>
106 For a typical build, the target of the search is a
107 feature description in an <filename>.scc</filename> file
108 whose name follows this format:
109 <literallayout class='monospaced'>
110 &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
111 </literallayout>
112 </para></listitem>
113 <listitem><para>Once located, the feature description is either compiled into a simple script
114 of actions, or into an existing equivalent script that is already part of the
115 shipped kernel.</para></listitem>
116 <listitem><para>Extra features are appended to the top-level feature description.
117 These features can come from the
118 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
119 variable in recipes.</para></listitem>
120 <listitem><para>Each extra feature is located, compiled and appended to the script
121 as described in step three.</para></listitem>
122 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
123 directories.
124 These directories are descriptions of all the branches, tags, patches and configurations that
125 need to be applied to the base Git repository to completely create the
126 source (build) branch for the new BSP or feature.</para></listitem>
127 <listitem><para>The base repository is cloned, and the actions
128 listed in the <filename>meta-*</filename> directories are applied to the
129 tree.</para></listitem>
130 <listitem><para>The Git repository is left with the desired branch checked out and any
131 required branching, patching and tagging has been performed.</para></listitem>
132 </orderedlist>
133 </para>
134 <para>
135 The kernel tree is now ready for developer consumption to be locally cloned,
136 configured, and built into a Yocto Project kernel specific to some target hardware.
137 <note><para>The generated <filename>meta-*</filename> directories add to the kernel
138 as shipped with the Yocto Project release.
139 Any add-ons and configuration data are applied to the end of an existing branch.
140 The full repository generation that is found in the
141 official Yocto Project kernel repositories at
142 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
143 is the combination of all supported boards and configurations.</para>
144 <para>The technique the Yocto Project team uses is flexible and allows for seamless
145 blending of an immutable history with additional patches specific to a
146 deployment.
147 Any additions to the kernel become an integrated part of the branches.</para>
148 </note>
149 </para>
150 </section>
151
152 <section id='build-strategy'>
153 <title>Build Strategy</title>
154 <para>
155 Once a local Git repository of the Yocto Project kernel exists on a development system,
156 you can consider the compilation phase of kernel development - building a kernel image.
157 Some prerequisites exist that are validated by the build process before compilation
158 starts:
159 </para>
160
161 <itemizedlist>
162 <listitem><para>The
163 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
164 to the kernel Git repository.</para></listitem>
165 <listitem><para>A BSP build branch exists.
166 This branch has the following form:
167 <literallayout class='monospaced'>
168 &lt;kernel_type&gt;/&lt;bsp_name&gt;
169 </literallayout></para></listitem>
170 </itemizedlist>
171
172 <para>
173 The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
174 Other means, however, do exist, such as as bootstrapping a BSP, see
175 the "<link linkend='workflow-examples'>Workflow Examples</link>".
176 </para>
177
178 <para>
179 Before building a kernel, the build process verifies the tree
180 and configures the kernel by processing all of the
181 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
182 files.
183 As the features are compiled, associated kernel configuration fragments are noted
184 and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
185 The fragments are migrated, pre-processed and passed to the Linux Kernel
186 Configuration subsystem (<filename>lkc</filename>) as raw input in the form
187 of a <filename>.config</filename> file.
188 The <filename>lkc</filename> uses its own internal dependency constraints to do the final
189 processing of that information and generates the final <filename>.config</filename> file
190 that is used during compilation.
191 </para>
192
193 <para>
194 Using the board's architecture and other relevant values from the board's template,
195 kernel compilation is started and a kernel image is produced.
196 </para>
197
198 <para>
199 The other thing that you notice once you configure a kernel is that
200 the build process generates a build tree that is separate from your kernel's local Git
201 source repository tree.
202 This build tree has a name that uses the following form, where
203 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
204 of the Yocto Project supported kernel types (e.g. "standard"):
205 <literallayout class='monospaced'>
206 linux-${MACHINE}-&lt;kernel_type&gt;-build
207 </literallayout>
208 </para>
209
210 <para>
211 The existing support in the <filename>kernel.org</filename> tree achieves this
212 default functionality.
213 </para>
214
215 <para>
216 This behavior means that all the generated files for a particular machine or BSP are now in
217 the build tree directory.
218 The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
219 files, the <filename>.a</filename> files, and so forth.
220 Since each machine or BSP has its own separate build directory in its own separate branch
221 of the Git repository, you can easily switch between different builds.
222 </para>
223 </section>
224
225 <section id='workflow-examples'>
226 <title>Workflow Examples</title>
227
228 <para>
229 As previously noted, the Yocto Project kernel has built-in Git integration.
230 However, these utilities are not the only way to work with the kernel repository.
231 The Yocto Project has not made changes to Git or to other tools that
232 would invalidate alternate workflows.
233 Additionally, the way the kernel repository is constructed results in using
234 only core Git functionality, thus allowing any number of tools or front ends to use the
235 resulting tree.
236 </para>
237
238 <para>
239 This section contains several workflow examples.
240 Many of the examples use Git commands.
241 You can find Git documentation at
242 <ulink url='http://git-scm.com/documentation'></ulink>.
243 You can find a simple overview of using Git with the Yocto Project in the
244 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
245 section of the Yocto Project Development Manual.
246 </para>
247
248 <section id='change-inspection-kernel-changes-commits'>
249 <title>Change Inspection: Changes/Commits</title>
250
251 <para>
252 A common question when working with a kernel is:
253 "What changes have been applied to this tree?"
254 </para>
255
256 <para>
257 In projects that have a collection of directories that
258 contain patches to the kernel, it is possible to inspect or "grep" the contents
259 of the directories to get a general feel for the changes.
260 This sort of patch inspection is not an efficient way to determine what has been
261 done to the kernel.
262 The reason it is inefficient is because there are many optional patches that are
263 selected based on the kernel type and the feature description.
264 Additionally, patches could exist in directories that are not included in the search.
265 </para>
266
267 <para>
268 A more efficient way to determine what has changed in the branch is to use
269 Git and inspect or search the kernel tree.
270 This method gives you a full view of not only the source code modifications,
271 but also provides the reasons for the changes.
272 </para>
273
274 <section id='what-changed-in-a-kernel'>
275 <title>What Changed in a Kernel?</title>
276
277 <para>
278 Following are a few examples that show how to use Git commands to examine changes.
279 Because Git repositories in the Yocto Project do not break existing Git
280 functionality, and because there exists many permutations of these types of
281 Git commands, many methods exist by which you can discover changes.
282 <note>
283 In the following examples, unless you provide a commit range,
284 <filename>kernel.org</filename> history is blended with Yocto Project
285 kernel changes.
286 You can form ranges by using branch names from the kernel tree as the
287 upper and lower commit markers with the Git commands.
288 You can see the branch names through the web interface to the
289 Yocto Project source repositories at
290 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
291 For example, the branch names for the <filename>linux-yocto-3.4</filename>
292 kernel repository can be seen at
293 <ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
294 </note>
295 To see a full range of the changes, use the
296 <filename>git whatchanged</filename> command and specify a commit range
297 for the branch (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
298 </para>
299
300 <para>
301 Here is an example that looks at what has changed in the
302 <filename>emenlow</filename> branch of the
303 <filename>linux-yocto-3.4</filename> kernel.
304 The lower commit range is the commit associated with the
305 <filename>standard/base</filename> branch, while
306 the upper commit range is the commit associated with the
307 <filename>standard/emenlow</filename> branch.
308 <literallayout class='monospaced'>
309 $ git whatchanged origin/standard/base..origin/standard/emenlow
310 </literallayout>
311 </para>
312
313 <para>
314 To see a summary of changes use the <filename>git log</filename> command.
315 Here is an example using the same branches:
316 <literallayout class='monospaced'>
317 $ git log --oneline origin/standard/base..origin/standard/emenlow
318 </literallayout>
319 The <filename>git log</filename> output might be more useful than
320 the <filename>git whatchanged</filename> as you get
321 a short, one-line summary of each change and not the entire commit.
322 </para>
323
324 <para>
325 If you want to see code differences associated with all the changes, use
326 the <filename>git diff</filename> command.
327 Here is an example:
328 <literallayout class='monospaced'>
329 $ git diff origin/standard/base..origin/standard/emenlow
330 </literallayout>
331 </para>
332
333 <para>
334 You can see the commit log messages and the text differences using the
335 <filename>git show</filename> command:
336 Here is an example:
337 <literallayout class='monospaced'>
338 $ git show origin/standard/base..origin/standard/emenlow
339 </literallayout>
340 </para>
341
342 <para>
343 You can create individual patches for each change by using the
344 <filename>git format-patch</filename> command.
345 Here is an example that that creates patch files for each commit and
346 places them in your <filename>Documents</filename> directory:
347 <literallayout class='monospaced'>
348 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
349 </literallayout>
350 </para>
351 </section>
352
353 <section id='show-a-particular-feature-or-branch-change'>
354 <title>Show a Particular Feature or Branch Change</title>
355
356 <para>
357 Developers use tags in the Yocto Project kernel tree to divide changes for significant
358 features or branches.
359 Once you know a particular tag, you can use Git commands
360 to show changes associated with the tag and find the branches that contain
361 the feature.
362 <note>
363 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
364 present, there could be many tags.
365 </note>
366 The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
367 a feature.
368 Here is an example that shows changes tagged by the <filename>systemtap</filename>
369 feature:
370 <literallayout class='monospaced'>
371 $ git show systemtap
372 </literallayout>
373 You can use the <filename>git branch --contains &lt;tag&gt;</filename> command
374 to show the branches that contain a particular feature.
375 This command shows the branches that contain the <filename>systemtap</filename>
376 feature:
377 <literallayout class='monospaced'>
378 $ git branch --contains systemtap
379 </literallayout>
380 </para>
381
382 <para>
383 You can use many other comparisons to isolate BSP and kernel changes.
384 For example, you can compare against <filename>kernel.org</filename> tags
385 such as the <filename>v3.4</filename> tag.
386 </para>
387 </section>
388 </section>
389
390 <section id='development-saving-kernel-modifications'>
391 <title>Development: Saving Kernel Modifications</title>
392
393 <para>
394 Another common operation is to build a BSP supplied by the Yocto Project, make some
395 changes, rebuild, and then test.
396 Those local changes often need to be exported, shared or otherwise maintained.
397 </para>
398
399 <para>
400 Since the Yocto Project kernel source tree is backed by Git, this activity is
401 much easier as compared to with previous releases.
402 Because Git tracks file modifications, additions and deletions, it is easy
403 to modify the code and later realize that you need to save the changes.
404 It is also easy to determine what has changed.
405 This method also provides many tools to commit, undo and export those modifications.
406 </para>
407
408 <para>
409 This section and its sub-sections, describe general application of Git's
410 <filename>push</filename> and <filename>pull</filename> commands, which are used to
411 get your changes upstream or source your code from an upstream repository.
412 The Yocto Project provides scripts that help you work in a collaborative development
413 environment.
414 For information on these scripts, see the
415 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
416 Upstream and Request a Pull</ulink>" and
417 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
418 sections in the Yocto Project Development Manual.
419 </para>
420
421 <para>
422 There are many ways to save kernel modifications.
423 The technique employed
424 depends on the destination for the patches:
425
426 <itemizedlist>
427 <listitem><para>Bulk storage</para></listitem>
428 <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
429 <listitem><para>External submissions</para></listitem>
430 <listitem><para>Exporting for integration into another Source Code
431 Manager (SCM)</para></listitem>
432 </itemizedlist>
433 </para>
434
435 <para>
436 Because of the following list of issues, the destination of the patches also influences
437 the method for gathering them:
438
439 <itemizedlist>
440 <listitem><para>Bisectability</para></listitem>
441 <listitem><para>Commit headers</para></listitem>
442 <listitem><para>Division of subsystems for separate submission or review</para></listitem>
443 </itemizedlist>
444 </para>
445
446 <section id='bulk-export'>
447 <title>Bulk Export</title>
448
449 <para>
450 This section describes how you can "bulk" export changes that have not
451 been separated or divided.
452 This situation works well when you are simply storing patches outside of the kernel
453 source repository, either permanently or temporarily, and you are not committing
454 incremental changes during development.
455 <note>
456 This technique is not appropriate for full integration of upstream submission
457 because changes are not properly divided and do not provide an avenue for per-change
458 commit messages.
459 Therefore, this example assumes that changes have not been committed incrementally
460 during development and that you simply must gather and export them.
461 </note>
462 <literallayout class='monospaced'>
463 # bulk export of ALL modifications without separation or division
464 # of the changes
465
466 $ git add .
467 $ git commit -s -a -m &lt;msg&gt;
468 or
469 $ git commit -s -a # and interact with $EDITOR
470 </literallayout>
471 </para>
472
473 <para>
474 The previous operations capture all the local changes in the project source
475 tree in a single Git commit.
476 And, that commit is also stored in the project's source tree.
477 </para>
478
479 <para>
480 Once the changes are exported, you can restore them manually using a template
481 or through integration with the <filename>default_kernel</filename>.
482 </para>
483
484 </section>
485
486 <section id='incremental-planned-sharing'>
487 <title>Incremental/Planned Sharing</title>
488
489 <para>
490 This section describes how to save modifications when you are making incremental
491 commits or practicing planned sharing.
492 The examples in this section assume that you have incrementally committed
493 changes to the tree during development and now need to export them.
494 The sections that follow
495 describe how you can export your changes internally through either patches or by
496 using Git commands.
497 </para>
498
499 <para>
500 During development, the following commands are of interest.
501 For full Git documentation, refer to the Git documentation at
502 <ulink url='http://github.com'></ulink>.
503
504 <literallayout class='monospaced'>
505 # edit a file
506 $ vi &lt;path&gt;/file
507 # stage the change
508 $ git add &lt;path&gt;/file
509 # commit the change
510 $ git commit -s
511 # remove a file
512 $ git rm &lt;path&gt;/file
513 # commit the change
514 $ git commit -s
515
516 ... etc.
517 </literallayout>
518 </para>
519
520 <para>
521 Distributed development with Git is possible when you use a universally
522 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
523 specific change set with a specific parent.
524 This identifier is created for you when
525 you create a commit, and is re-created when you amend, alter or re-apply
526 a commit.
527 As an individual in isolation, this is of no interest.
528 However, if you
529 intend to share your tree with normal Git <filename>push</filename> and
530 <filename>pull</filename> operations for
531 distributed development, you should consider the ramifications of changing a
532 commit that you have already shared with others.
533 </para>
534
535 <para>
536 Assuming that the changes have not been pushed upstream, or pulled into
537 another repository, you can update both the commit content and commit messages
538 associated with development by using the following commands:
539
540 <literallayout class='monospaced'>
541 $ Git add &lt;path&gt;/file
542 $ Git commit --amend
543 $ Git rebase or Git rebase -i
544 </literallayout>
545 </para>
546
547 <para>
548 Again, assuming that the changes have not been pushed upstream, and that
549 no pending works-in-progress exist (use <filename>git status</filename> to check), then
550 you can revert (undo) commits by using the following commands:
551
552 <literallayout class='monospaced'>
553 # remove the commit, update working tree and remove all
554 # traces of the change
555 $ git reset --hard HEAD^
556 # remove the commit, but leave the files changed and staged for re-commit
557 $ git reset --soft HEAD^
558 # remove the commit, leave file change, but not staged for commit
559 $ git reset --mixed HEAD^
560 </literallayout>
561 </para>
562
563 <para>
564 You can create branches, "cherry-pick" changes, or perform any number of Git
565 operations until the commits are in good order for pushing upstream
566 or for pull requests.
567 After a <filename>push</filename> or <filename>pull</filename> command,
568 commits are normally considered
569 "permanent" and you should not modify them.
570 If the commits need to be changed, you can incrementally do so with new commits.
571 These practices follow standard Git workflow and the <filename>kernel.org</filename> best
572 practices, which is recommended.
573 <note>
574 It is recommended to tag or branch before adding changes to a Yocto Project
575 BSP or before creating a new one.
576 The reason for this recommendation is because the branch or tag provides a
577 reference point to facilitate locating and exporting local changes.
578 </note>
579 </para>
580
581 <section id='export-internally-via-patches'>
582 <title>Exporting Changes Internally by Using Patches</title>
583
584 <para>
585 This section describes how you can extract committed changes from a working directory
586 by exporting them as patches.
587 Once the changes have been extracted, you can use the patches for upstream submission,
588 place them in a Yocto Project template for automatic kernel patching,
589 or apply them in many other common uses.
590 </para>
591
592 <para>
593 This example shows how to create a directory with sequentially numbered patches.
594 Once the directory is created, you can apply it to a repository using the
595 <filename>git am</filename> command to reproduce the original commit and all
596 the related information such as author, date, commit log, and so forth.
597 <note>
598 The new commit identifiers (ID) will be generated upon re-application.
599 This action reflects that the commit is now applied to an underlying commit
600 with a different ID.
601 </note>
602 <literallayout class='monospaced'>
603 # &lt;first-commit&gt; can be a tag if one was created before development
604 # began. It can also be the parent branch if a branch was created
605 # before development began.
606
607 $ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
608 </literallayout>
609 </para>
610
611 <para>
612 In other words:
613 <literallayout class='monospaced'>
614 # Identify commits of interest.
615
616 # If the tree was tagged before development
617 $ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
618
619 # If no tags are available
620 $ git format-patch -o &lt;save dir&gt; HEAD^ # last commit
621 $ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
622 $ git whatchanged # identify last commit
623 $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
624 $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
625 </literallayout>
626 </para>
627 </section>
628
629 <section id='export-internally-via-git'>
630 <title>Exporting Changes Internally by Using Git</title>
631
632 <para>
633 This section describes how you can export changes from a working directory
634 by pushing the changes into a master repository or by making a pull request.
635 Once you have pushed the changes to the master repository, you can then
636 pull those same changes into a new kernel build at a later time.
637 </para>
638
639 <para>
640 Use this command form to push the changes:
641 <literallayout class='monospaced'>
642 $ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
643 &lt;local_branch&gt;:&lt;remote_branch&gt;
644 </literallayout>
645 </para>
646
647 <para>
648 For example, the following command pushes the changes from your local branch
649 <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
650 in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
651 <literallayout class='monospaced'>
652 $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
653 yocto/standard/common-pc/base:yocto/standard/common-pc/base
654 </literallayout>
655 </para>
656
657 <para>
658 A pull request entails using the <filename>git request-pull</filename> command to compose
659 an email to the
660 maintainer requesting that a branch be pulled into the master repository, see
661 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
662 <note>
663 Other commands such as <filename>git stash</filename> or branching can also be used to save
664 changes, but are not covered in this document.
665 </note>
666 </para>
667 </section>
668 </section>
669
670 <section id='export-for-external-upstream-submission'>
671 <title>Exporting Changes for External (Upstream) Submission</title>
672
673 <para>
674 This section describes how to export changes for external upstream submission.
675 If the patch series is large or the maintainer prefers to pull
676 changes, you can submit these changes by using a pull request.
677 However, it is common to send patches as an email series.
678 This method allows easy review and integration of the changes.
679 <note>
680 Before sending patches for review be sure you understand the
681 community standards for submitting and documenting changes and follow their best practices.
682 For example, kernel patches should follow standards such as:
683 <itemizedlist>
684 <listitem><para>
685 <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
686 <listitem><para>Documentation/SubmittingPatches (in any linux
687 kernel source tree)</para></listitem>
688 </itemizedlist>
689 </note>
690 </para>
691
692 <para>
693 The messages used to commit changes are a large part of these standards.
694 Consequently, be sure that the headers for each commit have the required information.
695 For information on how to follow the Yocto Project commit message standards, see the
696 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
697 Change</ulink>" section in the Yocto Project Development Manual.
698 </para>
699
700 <para>
701 If the initial commits were not properly documented or do not meet those standards,
702 you can re-base by using the <filename>git rebase -i</filename> command to
703 manipulate the commits and
704 get them into the required format.
705 Other techniques such as branching and cherry-picking commits are also viable options.
706 </para>
707
708 <para>
709 Once you complete the commits, you can generate the email that sends the patches
710 to the maintainer(s) or lists that review and integrate changes.
711 The command <filename>git send-email</filename> is commonly used to ensure
712 that patches are properly
713 formatted for easy application and avoid mailer-induced patch damage.
714 </para>
715
716 <para>
717 The following is an example of dumping patches for external submission:
718 <literallayout class='monospaced'>
719 # dump the last 4 commits
720 $ git format-patch --thread -n -o ~/rr/ HEAD^^^^
721 $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
722 --to foo@yoctoproject.org --to bar@yoctoproject.org \
723 --cc list@yoctoproject.org ~/rr
724 # the editor is invoked for the 0/N patch, and when complete the entire
725 # series is sent via email for review
726 </literallayout>
727 </para>
728 </section>
729
730 <section id='export-for-import-into-other-scm'>
731 <title>Exporting Changes for Import into Another SCM</title>
732
733 <para>
734 When you want to export changes for import into another
735 Source Code Manager (SCM), you can use any of the previously discussed
736 techniques.
737 However, if the patches are manually applied to a secondary tree and then
738 that tree is checked into the SCM, you can lose change information such as
739 commit logs.
740 This process is not recommended.
741 </para>
742
743 <para>
744 Many SCMs can directly import Git commits, or can translate Git patches so that
745 information is not lost.
746 Those facilities are SCM-dependent and you should use them whenever possible.
747 </para>
748 </section>
749 </section>
750
751 <section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
752 <title>Working with the Yocto Project Kernel in Another SCM</title>
753
754 <para>
755 This section describes kernel development in an SCM other than Git,
756 which is not the same as exporting changes to another SCM described earlier.
757 For this scenario, you use the OpenEmbedded build system to
758 develop the kernel in a different SCM.
759 The following must be true for you to accomplish this:
760 <itemizedlist>
761 <listitem><para>The delivered Yocto Project kernel must be exported into the second
762 SCM.</para></listitem>
763 <listitem><para>Development must be exported from that secondary SCM into a
764 format that can be used by the OpenEmbedded build system.</para></listitem>
765 </itemizedlist>
766 </para>
767
768 <section id='exporting-delivered-kernel-to-scm'>
769 <title>Exporting the Delivered Kernel to the SCM</title>
770
771 <para>
772 Depending on the SCM, it might be possible to export the entire Yocto Project
773 kernel Git repository, branches and all, into a new environment.
774 This method is preferred because it has the most flexibility and potential to maintain
775 the meta data associated with each commit.
776 </para>
777
778 <para>
779 When a direct import mechanism is not available, it is still possible to
780 export a branch (or series of branches) and check them into a new repository.
781 </para>
782
783 <para>
784 The following commands illustrate some of the steps you could use to
785 import the <filename>yocto/standard/common-pc/base</filename>
786 kernel into a secondary SCM:
787 <literallayout class='monospaced'>
788 $ git checkout yocto/standard/common-pc/base
789 $ cd .. ; echo linux/.git &gt; .cvsignore
790 $ cvs import -m "initial import" linux MY_COMPANY start
791 </literallayout>
792 </para>
793
794 <para>
795 You could now relocate the CVS repository and use it in a centralized manner.
796 </para>
797
798 <para>
799 The following commands illustrate how you can condense and merge two BSPs into a
800 second SCM:
801 <literallayout class='monospaced'>
802 $ git checkout yocto/standard/common-pc/base
803 $ git merge yocto/standard/common-pc-64/base
804 # resolve any conflicts and commit them
805 $ cd .. ; echo linux/.git &gt; .cvsignore
806 $ cvs import -m "initial import" linux MY_COMPANY start
807 </literallayout>
808 </para>
809 </section>
810
811 <section id='importing-changes-for-build'>
812 <title>Importing Changes for the Build</title>
813
814 <para>
815 Once development has reached a suitable point in the second development
816 environment, you need to export the changes as patches.
817 To export them, place the changes in a recipe and
818 automatically apply them to the kernel during patching.
819 </para>
820 </section>
821 </section>
822
823 <section id='bsp-creating'>
824 <title>Creating a BSP Based on an Existing Similar BSP</title>
825
826 <para>
827 This section overviews the process of creating a BSP based on an
828 existing similar BSP.
829 The information is introductory in nature and does not provide step-by-step examples.
830 For detailed information on how to create a new BSP, see
831 the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
832 Yocto Project Board Support Package (BSP) Developer's Guide, or see the
833 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
834 wiki page.
835 </para>
836
837 <para>
838 The basic steps you need to follow are:
839 <orderedlist>
840 <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
841 You must create a local
842 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
843 by either creating a Git repository (recommended) or
844 extracting a Yocto Project release tarball.</para></listitem>
845 <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
846 Try to map your board features as closely to the features of a BSP that is
847 already supported and exists in the Yocto Project.
848 Starting with something as close as possible to your board makes developing
849 your BSP easier.
850 You can find all the BSPs that are supported and ship with the Yocto Project
851 on the Yocto Project's Download page at
852 <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
853 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
854 You need to either have a local Git repository of the base BSP set up or
855 have downloaded and extracted the files from a release BSP tarball.
856 Either method gives you access to the BSP source files.</para></listitem>
857 <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
858 BSP work:</emphasis>
859 Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
860 <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
861 Configuration changes involve the files in the BSP's <filename>conf</filename>
862 directory.
863 Changes include creating a machine-specific configuration file and editing the
864 <filename>layer.conf</filename> file.
865 The configuration changes identify the kernel you will be using.
866 Recipe changes include removing, modifying, or adding new recipe files that
867 instruct the build process on what features to include in the image.</para></listitem>
868 <listitem><para><emphasis>Prepare for the build:</emphasis>
869 Before you actually initiate the build, you need to set up the build environment
870 by sourcing the environment initialization script.
871 After setting up the environment, you need to make some build configuration
872 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
873 files.</para></listitem>
874 <listitem><para><emphasis>Build the image:</emphasis>
875 The OpenEmbedded build system uses BitBake to create the image.
876 You need to decide on the type of image you are going to build (e.g. minimal, base,
877 core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
878 command.</para></listitem>
879 </orderedlist>
880 </para>
881 </section>
882
883 <section id='tip-dirty-string'>
884 <title>"-dirty" String</title>
885
886 <para>
887 If kernel images are being built with "-dirty" on the end of the version
888 string, this simply means that modifications in the source
889 directory have not been committed.
890 <literallayout class='monospaced'>
891 $ git status
892 </literallayout>
893 </para>
894
895 <para>
896 You can use the above Git command to report modified, removed, or added files.
897 You should commit those changes to the tree regardless of whether they will be saved,
898 exported, or used.
899 Once you commit the changes you need to rebuild the kernel.
900 </para>
901
902 <para>
903 To brute force pickup and commit all such pending changes, enter the following:
904 <literallayout class='monospaced'>
905 $ git add .
906 $ git commit -s -a -m "getting rid of -dirty"
907 </literallayout>
908 </para>
909
910 <para>
911 Next, rebuild the kernel.
912 </para>
913 </section>
914 </section>
915</chapter>
916<!--
917vim: expandtab tw=80 ts=4
918-->
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
new file mode 100644
index 0000000000..c1cc22bb7a
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -0,0 +1,78 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='kernel-doc-intro'>
6
7<title>Yocto Project Kernel Architecture and Use Manual</title>
8
9<section id='kernel-intro-section'>
10 <title>Introduction</title>
11 <para>
12 The Yocto Project presents kernels as a fully patched, history-clean Git
13 repositories.
14 Each repository represents selected features, board support,
15 and configurations extensively tested by the Yocto Project.
16 Yocto Project kernels allow the end user to leverage community
17 best practices to seamlessly manage the development, build and debug cycles.
18 </para>
19 <para>
20 This manual describes Yocto Project kernels by providing information
21 on history, organization, benefits, and use.
22 The manual consists of two sections:
23 <itemizedlist>
24 <listitem><para><emphasis>Concepts:</emphasis> Describes concepts behind a kernel.
25 You will understand how a kernel is organized and why it is organized in
26 the way it is. You will understand the benefits of a kernel's organization
27 and the mechanisms used to work with the kernel and how to apply it in your
28 design process.</para></listitem>
29 <listitem><para><emphasis>Using a Kernel:</emphasis> Describes best practices
30 and "how-to" information
31 that lets you put a kernel to practical use.
32 Some examples are how to examine changes in a branch and how to
33 save kernel modifications.</para></listitem>
34 </itemizedlist>
35 </para>
36
37 <para>
38 For more information on the Linux kernel, see the following links:
39 <itemizedlist>
40 <listitem><para>The Linux Foundation's guide for kernel development
41 process - <ulink url='http://www.linuxfoundation.org/content/1-guide-kernel-development-process'></ulink></para></listitem>
42 <listitem><para>A fairly encompassing guide on Linux kernel development -
43 <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>
44 </itemizedlist>
45 </para>
46
47 <para>
48 For more discussion on the Yocto Project kernel, you can see these sections
49 in the Yocto Project Development Manual:
50 <itemizedlist>
51 <listitem><para>
52 "<ulink url='&YOCTO_DOCS_DEV_URL;#kernel-overview'>Kernel Overview</ulink>"</para></listitem>
53 <listitem><para>
54 "<ulink url='&YOCTO_DOCS_DEV_URL;#kernel-modification-workflow'>Kernel Modification Workflow</ulink>"
55 </para></listitem>
56 <listitem><para>
57 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"</para></listitem>
58 <listitem><para>
59 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"</para></listitem>
60 </itemizedlist>
61 </para>
62
63 <para>
64 For general information on the Yocto Project, visit the website at
65 <ulink url='&YOCTO_HOME_URL;'></ulink>.
66 </para>
67</section>
68
69
70
71
72
73
74
75</chapter>
76<!--
77vim: expandtab tw=80 ts=4
78-->
diff --git a/documentation/kernel-dev/kernel-dev-style.css b/documentation/kernel-dev/kernel-dev-style.css
new file mode 100644
index 0000000000..a90d4af291
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-style.css
@@ -0,0 +1,979 @@
1/*
2 Generic XHTML / DocBook XHTML CSS Stylesheet.
3
4 Browser wrangling and typographic design by
5 Oyvind Kolas / pippin@gimp.org
6
7 Customised for Poky by
8 Matthew Allum / mallum@o-hand.com
9
10 Thanks to:
11 Liam R. E. Quin
12 William Skaggs
13 Jakub Steiner
14
15 Structure
16 ---------
17
18 The stylesheet is divided into the following sections:
19
20 Positioning
21 Margins, paddings, width, font-size, clearing.
22 Decorations
23 Borders, style
24 Colors
25 Colors
26 Graphics
27 Graphical backgrounds
28 Nasty IE tweaks
29 Workarounds needed to make it work in internet explorer,
30 currently makes the stylesheet non validating, but up until
31 this point it is validating.
32 Mozilla extensions
33 Transparency for footer
34 Rounded corners on boxes
35
36*/
37
38
39 /*************** /
40 / Positioning /
41/ ***************/
42
43body {
44 font-family: Verdana, Sans, sans-serif;
45
46 min-width: 640px;
47 width: 80%;
48 margin: 0em auto;
49 padding: 2em 5em 5em 5em;
50 color: #333;
51}
52
53h1,h2,h3,h4,h5,h6,h7 {
54 font-family: Arial, Sans;
55 color: #00557D;
56 clear: both;
57}
58
59h1 {
60 font-size: 2em;
61 text-align: left;
62 padding: 0em 0em 0em 0em;
63 margin: 2em 0em 0em 0em;
64}
65
66h2.subtitle {
67 margin: 0.10em 0em 3.0em 0em;
68 padding: 0em 0em 0em 0em;
69 font-size: 1.8em;
70 padding-left: 20%;
71 font-weight: normal;
72 font-style: italic;
73}
74
75h2 {
76 margin: 2em 0em 0.66em 0em;
77 padding: 0.5em 0em 0em 0em;
78 font-size: 1.5em;
79 font-weight: bold;
80}
81
82h3.subtitle {
83 margin: 0em 0em 1em 0em;
84 padding: 0em 0em 0em 0em;
85 font-size: 142.14%;
86 text-align: right;
87}
88
89h3 {
90 margin: 1em 0em 0.5em 0em;
91 padding: 1em 0em 0em 0em;
92 font-size: 140%;
93 font-weight: bold;
94}
95
96h4 {
97 margin: 1em 0em 0.5em 0em;
98 padding: 1em 0em 0em 0em;
99 font-size: 120%;
100 font-weight: bold;
101}
102
103h5 {
104 margin: 1em 0em 0.5em 0em;
105 padding: 1em 0em 0em 0em;
106 font-size: 110%;
107 font-weight: bold;
108}
109
110h6 {
111 margin: 1em 0em 0em 0em;
112 padding: 1em 0em 0em 0em;
113 font-size: 110%;
114 font-weight: bold;
115}
116
117.authorgroup {
118 background-color: transparent;
119 background-repeat: no-repeat;
120 padding-top: 256px;
121 background-image: url("figures/kernel-title.png");
122 background-position: left top;
123 margin-top: -256px;
124 padding-right: 50px;
125 margin-left: 0px;
126 text-align: right;
127 width: 740px;
128}
129
130h3.author {
131 margin: 0em 0me 0em 0em;
132 padding: 0em 0em 0em 0em;
133 font-weight: normal;
134 font-size: 100%;
135 color: #333;
136 clear: both;
137}
138
139.author tt.email {
140 font-size: 66%;
141}
142
143.titlepage hr {
144 width: 0em;
145 clear: both;
146}
147
148.revhistory {
149 padding-top: 2em;
150 clear: both;
151}
152
153.toc,
154.list-of-tables,
155.list-of-examples,
156.list-of-figures {
157 padding: 1.33em 0em 2.5em 0em;
158 color: #00557D;
159}
160
161.toc p,
162.list-of-tables p,
163.list-of-figures p,
164.list-of-examples p {
165 padding: 0em 0em 0em 0em;
166 padding: 0em 0em 0.3em;
167 margin: 1.5em 0em 0em 0em;
168}
169
170.toc p b,
171.list-of-tables p b,
172.list-of-figures p b,
173.list-of-examples p b{
174 font-size: 100.0%;
175 font-weight: bold;
176}
177
178.toc dl,
179.list-of-tables dl,
180.list-of-figures dl,
181.list-of-examples dl {
182 margin: 0em 0em 0.5em 0em;
183 padding: 0em 0em 0em 0em;
184}
185
186.toc dt {
187 margin: 0em 0em 0em 0em;
188 padding: 0em 0em 0em 0em;
189}
190
191.toc dd {
192 margin: 0em 0em 0em 2.6em;
193 padding: 0em 0em 0em 0em;
194}
195
196div.glossary dl,
197div.variablelist dl {
198}
199
200.glossary dl dt,
201.variablelist dl dt,
202.variablelist dl dt span.term {
203 font-weight: normal;
204 width: 20em;
205 text-align: right;
206}
207
208.variablelist dl dt {
209 margin-top: 0.5em;
210}
211
212.glossary dl dd,
213.variablelist dl dd {
214 margin-top: -1em;
215 margin-left: 25.5em;
216}
217
218.glossary dd p,
219.variablelist dd p {
220 margin-top: 0em;
221 margin-bottom: 1em;
222}
223
224
225div.calloutlist table td {
226 padding: 0em 0em 0em 0em;
227 margin: 0em 0em 0em 0em;
228}
229
230div.calloutlist table td p {
231 margin-top: 0em;
232 margin-bottom: 1em;
233}
234
235div p.copyright {
236 text-align: left;
237}
238
239div.legalnotice p.legalnotice-title {
240 margin-bottom: 0em;
241}
242
243p {
244 line-height: 1.5em;
245 margin-top: 0em;
246
247}
248
249dl {
250 padding-top: 0em;
251}
252
253hr {
254 border: solid 1px;
255}
256
257
258.mediaobject,
259.mediaobjectco {
260 text-align: center;
261}
262
263img {
264 border: none;
265}
266
267ul {
268 padding: 0em 0em 0em 1.5em;
269}
270
271ul li {
272 padding: 0em 0em 0em 0em;
273}
274
275ul li p {
276 text-align: left;
277}
278
279table {
280 width :100%;
281}
282
283th {
284 padding: 0.25em;
285 text-align: left;
286 font-weight: normal;
287 vertical-align: top;
288}
289
290td {
291 padding: 0.25em;
292 vertical-align: top;
293}
294
295p a[id] {
296 margin: 0px;
297 padding: 0px;
298 display: inline;
299 background-image: none;
300}
301
302a {
303 text-decoration: underline;
304 color: #444;
305}
306
307pre {
308 overflow: auto;
309}
310
311a:hover {
312 text-decoration: underline;
313 /*font-weight: bold;*/
314}
315
316
317div.informalfigure,
318div.informalexample,
319div.informaltable,
320div.figure,
321div.table,
322div.example {
323 margin: 1em 0em;
324 padding: 1em;
325 page-break-inside: avoid;
326}
327
328
329div.informalfigure p.title b,
330div.informalexample p.title b,
331div.informaltable p.title b,
332div.figure p.title b,
333div.example p.title b,
334div.table p.title b{
335 padding-top: 0em;
336 margin-top: 0em;
337 font-size: 100%;
338 font-weight: normal;
339}
340
341.mediaobject .caption,
342.mediaobject .caption p {
343 text-align: center;
344 font-size: 80%;
345 padding-top: 0.5em;
346 padding-bottom: 0.5em;
347}
348
349.epigraph {
350 padding-left: 55%;
351 margin-bottom: 1em;
352}
353
354.epigraph p {
355 text-align: left;
356}
357
358.epigraph .quote {
359 font-style: italic;
360}
361.epigraph .attribution {
362 font-style: normal;
363 text-align: right;
364}
365
366span.application {
367 font-style: italic;
368}
369
370.programlisting {
371 font-family: monospace;
372 font-size: 80%;
373 white-space: pre;
374 margin: 1.33em 0em;
375 padding: 1.33em;
376}
377
378.tip,
379.warning,
380.caution,
381.note {
382 margin-top: 1em;
383 margin-bottom: 1em;
384
385}
386
387/* force full width of table within div */
388.tip table,
389.warning table,
390.caution table,
391.note table {
392 border: none;
393 width: 100%;
394}
395
396
397.tip table th,
398.warning table th,
399.caution table th,
400.note table th {
401 padding: 0.8em 0.0em 0.0em 0.0em;
402 margin : 0em 0em 0em 0em;
403}
404
405.tip p,
406.warning p,
407.caution p,
408.note p {
409 margin-top: 0.5em;
410 margin-bottom: 0.5em;
411 padding-right: 1em;
412 text-align: left;
413}
414
415.acronym {
416 text-transform: uppercase;
417}
418
419b.keycap,
420.keycap {
421 padding: 0.09em 0.3em;
422 margin: 0em;
423}
424
425.itemizedlist li {
426 clear: none;
427}
428
429.filename {
430 font-size: medium;
431 font-family: Courier, monospace;
432}
433
434
435div.navheader, div.heading{
436 position: absolute;
437 left: 0em;
438 top: 0em;
439 width: 100%;
440 background-color: #cdf;
441 width: 100%;
442}
443
444div.navfooter, div.footing{
445 position: fixed;
446 left: 0em;
447 bottom: 0em;
448 background-color: #eee;
449 width: 100%;
450}
451
452
453div.navheader td,
454div.navfooter td {
455 font-size: 66%;
456}
457
458div.navheader table th {
459 /*font-family: Georgia, Times, serif;*/
460 /*font-size: x-large;*/
461 font-size: 80%;
462}
463
464div.navheader table {
465 border-left: 0em;
466 border-right: 0em;
467 border-top: 0em;
468 width: 100%;
469}
470
471div.navfooter table {
472 border-left: 0em;
473 border-right: 0em;
474 border-bottom: 0em;
475 width: 100%;
476}
477
478div.navheader table td a,
479div.navfooter table td a {
480 color: #777;
481 text-decoration: none;
482}
483
484/* normal text in the footer */
485div.navfooter table td {
486 color: black;
487}
488
489div.navheader table td a:visited,
490div.navfooter table td a:visited {
491 color: #444;
492}
493
494
495/* links in header and footer */
496div.navheader table td a:hover,
497div.navfooter table td a:hover {
498 text-decoration: underline;
499 background-color: transparent;
500 color: #33a;
501}
502
503div.navheader hr,
504div.navfooter hr {
505 display: none;
506}
507
508
509.qandaset tr.question td p {
510 margin: 0em 0em 1em 0em;
511 padding: 0em 0em 0em 0em;
512}
513
514.qandaset tr.answer td p {
515 margin: 0em 0em 1em 0em;
516 padding: 0em 0em 0em 0em;
517}
518.answer td {
519 padding-bottom: 1.5em;
520}
521
522.emphasis {
523 font-weight: bold;
524}
525
526
527 /************* /
528 / decorations /
529/ *************/
530
531.titlepage {
532}
533
534.part .title {
535}
536
537.subtitle {
538 border: none;
539}
540
541/*
542h1 {
543 border: none;
544}
545
546h2 {
547 border-top: solid 0.2em;
548 border-bottom: solid 0.06em;
549}
550
551h3 {
552 border-top: 0em;
553 border-bottom: solid 0.06em;
554}
555
556h4 {
557 border: 0em;
558 border-bottom: solid 0.06em;
559}
560
561h5 {
562 border: 0em;
563}
564*/
565
566.programlisting {
567 border: solid 1px;
568}
569
570div.figure,
571div.table,
572div.informalfigure,
573div.informaltable,
574div.informalexample,
575div.example {
576 border: 1px solid;
577}
578
579
580
581.tip,
582.warning,
583.caution,
584.note {
585 border: 1px solid;
586}
587
588.tip table th,
589.warning table th,
590.caution table th,
591.note table th {
592 border-bottom: 1px solid;
593}
594
595.question td {
596 border-top: 1px solid black;
597}
598
599.answer {
600}
601
602
603b.keycap,
604.keycap {
605 border: 1px solid;
606}
607
608
609div.navheader, div.heading{
610 border-bottom: 1px solid;
611}
612
613
614div.navfooter, div.footing{
615 border-top: 1px solid;
616}
617
618 /********* /
619 / colors /
620/ *********/
621
622body {
623 color: #333;
624 background: white;
625}
626
627a {
628 background: transparent;
629}
630
631a:hover {
632 background-color: #dedede;
633}
634
635
636h1,
637h2,
638h3,
639h4,
640h5,
641h6,
642h7,
643h8 {
644 background-color: transparent;
645}
646
647hr {
648 border-color: #aaa;
649}
650
651
652.tip, .warning, .caution, .note {
653 border-color: #fff;
654}
655
656
657.tip table th,
658.warning table th,
659.caution table th,
660.note table th {
661 border-bottom-color: #fff;
662}
663
664
665.warning {
666 background-color: #f0f0f2;
667}
668
669.caution {
670 background-color: #f0f0f2;
671}
672
673.tip {
674 background-color: #f0f0f2;
675}
676
677.note {
678 background-color: #f0f0f2;
679}
680
681.glossary dl dt,
682.variablelist dl dt,
683.variablelist dl dt span.term {
684 color: #044;
685}
686
687div.figure,
688div.table,
689div.example,
690div.informalfigure,
691div.informaltable,
692div.informalexample {
693 border-color: #aaa;
694}
695
696pre.programlisting {
697 color: black;
698 background-color: #fff;
699 border-color: #aaa;
700 border-width: 2px;
701}
702
703.guimenu,
704.guilabel,
705.guimenuitem {
706 background-color: #eee;
707}
708
709
710b.keycap,
711.keycap {
712 background-color: #eee;
713 border-color: #999;
714}
715
716
717div.navheader {
718 border-color: black;
719}
720
721
722div.navfooter {
723 border-color: black;
724}
725
726
727 /*********** /
728 / graphics /
729/ ***********/
730
731/*
732body {
733 background-image: url("images/body_bg.jpg");
734 background-attachment: fixed;
735}
736
737.navheader,
738.note,
739.tip {
740 background-image: url("images/note_bg.jpg");
741 background-attachment: fixed;
742}
743
744.warning,
745.caution {
746 background-image: url("images/warning_bg.jpg");
747 background-attachment: fixed;
748}
749
750.figure,
751.informalfigure,
752.example,
753.informalexample,
754.table,
755.informaltable {
756 background-image: url("images/figure_bg.jpg");
757 background-attachment: fixed;
758}
759
760*/
761h1,
762h2,
763h3,
764h4,
765h5,
766h6,
767h7{
768}
769
770/*
771Example of how to stick an image as part of the title.
772
773div.article .titlepage .title
774{
775 background-image: url("figures/white-on-black.png");
776 background-position: center;
777 background-repeat: repeat-x;
778}
779*/
780
781div.preface .titlepage .title,
782div.colophon .title,
783div.chapter .titlepage .title,
784div.article .titlepage .title
785{
786}
787
788div.section div.section .titlepage .title,
789div.sect2 .titlepage .title {
790 background: none;
791}
792
793
794h1.title {
795 background-color: transparent;
796 background-image: url("figures/yocto-project-bw.png");
797 background-repeat: no-repeat;
798 height: 256px;
799 text-indent: -9000px;
800 overflow:hidden;
801}
802
803h2.subtitle {
804 background-color: transparent;
805 text-indent: -9000px;
806 overflow:hidden;
807 width: 0px;
808 display: none;
809}
810
811 /*************************************** /
812 / pippin.gimp.org specific alterations /
813/ ***************************************/
814
815/*
816div.heading, div.navheader {
817 color: #777;
818 font-size: 80%;
819 padding: 0;
820 margin: 0;
821 text-align: left;
822 position: absolute;
823 top: 0px;
824 left: 0px;
825 width: 100%;
826 height: 50px;
827 background: url('/gfx/heading_bg.png') transparent;
828 background-repeat: repeat-x;
829 background-attachment: fixed;
830 border: none;
831}
832
833div.heading a {
834 color: #444;
835}
836
837div.footing, div.navfooter {
838 border: none;
839 color: #ddd;
840 font-size: 80%;
841 text-align:right;
842
843 width: 100%;
844 padding-top: 10px;
845 position: absolute;
846 bottom: 0px;
847 left: 0px;
848
849 background: url('/gfx/footing_bg.png') transparent;
850}
851*/
852
853
854
855 /****************** /
856 / nasty ie tweaks /
857/ ******************/
858
859/*
860div.heading, div.navheader {
861 width:expression(document.body.clientWidth + "px");
862}
863
864div.footing, div.navfooter {
865 width:expression(document.body.clientWidth + "px");
866 margin-left:expression("-5em");
867}
868body {
869 padding:expression("4em 5em 0em 5em");
870}
871*/
872
873 /**************************************** /
874 / mozilla vendor specific css extensions /
875/ ****************************************/
876/*
877div.navfooter, div.footing{
878 -moz-opacity: 0.8em;
879}
880
881div.figure,
882div.table,
883div.informalfigure,
884div.informaltable,
885div.informalexample,
886div.example,
887.tip,
888.warning,
889.caution,
890.note {
891 -moz-border-radius: 0.5em;
892}
893
894b.keycap,
895.keycap {
896 -moz-border-radius: 0.3em;
897}
898*/
899
900table tr td table tr td {
901 display: none;
902}
903
904
905hr {
906 display: none;
907}
908
909table {
910 border: 0em;
911}
912
913 .photo {
914 float: right;
915 margin-left: 1.5em;
916 margin-bottom: 1.5em;
917 margin-top: 0em;
918 max-width: 17em;
919 border: 1px solid gray;
920 padding: 3px;
921 background: white;
922}
923 .seperator {
924 padding-top: 2em;
925 clear: both;
926 }
927
928 #validators {
929 margin-top: 5em;
930 text-align: right;
931 color: #777;
932 }
933 @media print {
934 body {
935 font-size: 8pt;
936 }
937 .noprint {
938 display: none;
939 }
940 }
941
942
943.tip,
944.note {
945 background: #f0f0f2;
946 color: #333;
947 padding: 20px;
948 margin: 20px;
949}
950
951.tip h3,
952.note h3 {
953 padding: 0em;
954 margin: 0em;
955 font-size: 2em;
956 font-weight: bold;
957 color: #333;
958}
959
960.tip a,
961.note a {
962 color: #333;
963 text-decoration: underline;
964}
965
966.footnote {
967 font-size: small;
968 color: #333;
969}
970
971/* Changes the announcement text */
972.tip h3,
973.warning h3,
974.caution h3,
975.note h3 {
976 font-size:large;
977 color: #00557D;
978}
979
diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml
new file mode 100644
index 0000000000..8714c07744
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev.xml
@@ -0,0 +1,104 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<book id='kernel-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/kernel-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title></title>
20
21 <authorgroup>
22 <author>
23 <firstname>Bruce</firstname> <surname>Ashfield</surname>
24 <affiliation>
25 <orgname>Wind River Corporation</orgname>
26 </affiliation>
27 <email>bruce.ashfield@windriver.com</email>
28 </author>
29 </authorgroup>
30
31 <revhistory>
32 <revision>
33 <revnumber>0.9</revnumber>
34 <date>24 November 2010</date>
35 <revremark>The initial document draft released with the Yocto Project 0.9 Release.</revremark>
36 </revision>
37 <revision>
38 <revnumber>1.0</revnumber>
39 <date>6 April 2011</date>
40 <revremark>Released with the Yocto Project 1.0 Release.</revremark>
41 </revision>
42 <revision>
43 <revnumber>1.0.1</revnumber>
44 <date>23 May 2011</date>
45 <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
46 </revision>
47 <revision>
48 <revnumber>1.1</revnumber>
49 <date>6 October 2011</date>
50 <revremark>Released with the Yocto Project 1.1 Release.</revremark>
51 </revision>
52 <revision>
53 <revnumber>1.2</revnumber>
54 <date>April 2012</date>
55 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
56 </revision>
57 <revision>
58 <revnumber>1.3</revnumber>
59 <date>October 2012</date>
60 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
61 </revision>
62 <revision>
63 <revnumber>1.4</revnumber>
64 <date>Sometime in 2013</date>
65 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
66 </revision>
67 </revhistory>
68
69 <copyright>
70 <year>&COPYRIGHT_YEAR;</year>
71 <holder>Linux Foundation</holder>
72 </copyright>
73
74 <legalnotice>
75 <para>
76 Permission is granted to copy, distribute and/or modify this document under
77 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
78 </para>
79 <note>
80 Due to production processes, there could be differences between the Yocto Project
81 documentation bundled in the release tarball and the
82 <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink> on
83 the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
84 For the latest version of this manual, see the manual on the website.
85 </note>
86 </legalnotice>
87
88 </bookinfo>
89
90 <xi:include href="kernel-doc-intro.xml"/>
91
92 <xi:include href="kernel-concepts.xml"/>
93
94 <xi:include href="kernel-how-to.xml"/>
95
96<!-- <index id='index'>
97 <title>Index</title>
98 </index>
99-->
100
101</book>
102<!--
103vim: expandtab tw=80 ts=4
104-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-20 07:34:54 +0000