summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:46:05 +0100
committerAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:47:32 +0100
commit14b00ff23a912494edc7f146e668c40ca82b8508 (patch)
treef7f4e592ccb935bc312cfa0cfc3c0cbbe444970d /documentation/kernel-dev
downloadyocto-docs-14b00ff23a912494edc7f146e668c40ca82b8508.tar.gz
initial commit of Enea Linux 3.1HEADmaster
Migrated from the internal git server on the dora-enea branch Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>
Diffstat (limited to 'documentation/kernel-dev')
-rwxr-xr-xdocumentation/kernel-dev/figures/kernel-architecture-overview.pngbin0 -> 40748 bytes
-rw-r--r--documentation/kernel-dev/figures/kernel-dev-title.pngbin0 -> 13453 bytes
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml1071
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml863
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml253
-rw-r--r--documentation/kernel-dev/kernel-dev-customization.xsl11
-rw-r--r--documentation/kernel-dev/kernel-dev-eclipse-customization.xsl27
-rw-r--r--documentation/kernel-dev/kernel-dev-examples.xml918
-rw-r--r--documentation/kernel-dev/kernel-dev-faq.xml131
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml147
-rw-r--r--documentation/kernel-dev/kernel-dev-maint-appx.xml220
-rw-r--r--documentation/kernel-dev/kernel-dev-style.css978
-rw-r--r--documentation/kernel-dev/kernel-dev.xml95
13 files changed, 4714 insertions, 0 deletions
diff --git a/documentation/kernel-dev/figures/kernel-architecture-overview.png b/documentation/kernel-dev/figures/kernel-architecture-overview.png
new file mode 100755
index 0000000..2aad172
--- /dev/null
+++ b/documentation/kernel-dev/figures/kernel-architecture-overview.png
Binary files differ
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 0000000..7a8dd54
--- /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 0000000..4589e4b
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -0,0 +1,1071 @@
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-dev-advanced'>
6<title>Working with Advanced Metadata</title>
7
8<section id='kernel-dev-advanced-overview'>
9 <title>Overview</title>
10
11 <para>
12 In addition to supporting configuration fragments and patches, the
13 Yocto Project kernel tools also support rich
14 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> that you can
15 use to define complex policies and Board Support Package (BSP) support.
16 The purpose of the Metadata and the tools that manage it, known as
17 the kern-tools (<filename>kern-tools-native_git.bb</filename>), is
18 to help you manage the complexity of the configuration and sources
19 used to support multiple BSPs and Linux kernel types.
20 </para>
21</section>
22
23<section id='using-kernel-metadata-in-a-recipe'>
24 <title>Using Kernel Metadata in a Recipe</title>
25
26 <para>
27 The kernel sources in the Yocto Project contain kernel Metadata, which is
28 located in the <filename>meta</filename> branches of the kernel source
29 Git repositories.
30 This Metadata defines Board Support Packages (BSPs) that
31 correspond to definitions in linux-yocto recipes for the same BSPs.
32 A BSP consists of an aggregation of kernel policy and hardware-specific
33 feature enablements.
34 The BSP can be influenced from within the linux-yocto recipe.
35 <note>
36 Linux kernel source that contains kernel Metadata is said to be
37 "linux-yocto style" kernel source.
38 A Linux kernel recipe that inherits from the
39 <filename>linux-yocto.inc</filename> include file is said to be a
40 "linux-yocto style" recipe.
41 </note>
42 </para>
43
44 <para>
45 Every linux-yocto style recipe must define the
46 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
47 variable.
48 This variable is typically set to the same value as the
49 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
50 variable, which is used by BitBake (e.g. "routerstationpro" or "fri2").
51 Multiple BSPs can reuse the same <filename>KMACHINE</filename>
52 name if they are built using the same BSP description.
53 The "fri2" and "fri2-noemgd" BSP combination
54 in the <filename>meta-intel</filename>
55 layer is a good example of two BSPs using the same
56 <filename>KMACHINE</filename> value (i.e. "fri2").
57 See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section
58 for more information.
59 </para>
60
61 <para>
62 The linux-yocto style recipes can optionally define the following
63 variables:
64 <literallayout class='monospaced'>
65 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'>KBRANCH</ulink>
66 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink>
67 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH_DEFAULT'>KBRANCH_DEFAULT</ulink>
68 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink>
69 </literallayout>
70 <filename>KBRANCH_DEFAULT</filename> defines the Linux kernel source
71 repository's default branch to use to build the Linux kernel.
72 The value is used as the default for <filename>KBRANCH</filename>, which
73 can define an alternate branch typically with a machine override as
74 follows:
75 <literallayout class='monospaced'>
76 KBRANCH_fri2 = "standard/fri2"
77 </literallayout>
78 Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename>
79 initializes to "master".
80 </para>
81
82 <para>
83 <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be
84 used in assembling the configuration.
85 If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
86 it defaults to "standard".
87 Together with
88 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
89 <filename>LINUX_KERNEL_TYPE</filename> defines the search
90 arguments used by the kernel tools to find the
91 appropriate description within the kernel Metadata with which to
92 build out the sources and configuration.
93 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
94 kernel types.
95 See the <link linkend='kernel-types'>Kernel Types</link> section
96 for more information on kernel types.
97 </para>
98
99 <para>
100 During the build, the kern-tools search for the BSP description
101 file that most closely matches the <filename>KMACHINE</filename>
102 and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the
103 recipe.
104 The tools use the first BSP description it finds that match
105 both variables.
106 If the tools cannot find a match, they issue a warning such as
107 the following:
108 <literallayout class='monospaced'>
109 WARNING: Can't find any BSP hardware or required configuration fragments.
110 WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and
111 meta/cfg/broken/fri2-broken/required_frags.txt in directory:
112 meta/cfg/broken/fri2-broken
113 </literallayout>
114 In this example, <filename>KMACHINE</filename> was set to "fri2-broken"
115 and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken".
116 </para>
117
118 <para>
119 The tools first search for the <filename>KMACHINE</filename> and
120 then for the <filename>LINUX_KERNEL_TYPE</filename>.
121 If the tools cannot find a partial match, they will use the
122 sources from the <filename>KBRANCH</filename> and any configuration
123 specified in the
124 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
125 </para>
126
127 <para>
128 You can use the <filename>KERNEL_FEATURES</filename> variable
129 to include features (configuration fragments, patches, or both) that
130 are not already included by the <filename>KMACHINE</filename> and
131 <filename>LINUX_KERNEL_TYPE</filename> variable combination.
132 For example, to include a feature specified as "features/netfilter.scc",
133 specify:
134 <literallayout class='monospaced'>
135 KERNEL_FEATURES += "features/netfilter.scc"
136 </literallayout>
137 To include a feature called "cfg/sound.scc" just for the
138 <filename>qemux86</filename> machine, specify:
139 <literallayout class='monospaced'>
140 KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"
141 </literallayout>
142 The value of the entries in <filename>KERNEL_FEATURES</filename>
143 are dependent on their location within the kernel Metadata itself.
144 The examples here are taken from the
145 <filename>linux-yocto-3.4</filename> repository where "features"
146 and "cfg" are subdirectories within the
147 <filename>meta/cfg/kernel-cache</filename> directory.
148 For more information, see the
149 "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section.
150 <note>
151 The processing of the these variables has evolved some between the
152 0.9 and 1.3 releases of the Yocto Project and associated
153 kern-tools sources.
154 The descriptions in this section are accurate for 1.3 and later
155 releases of the Yocto Project.
156 </note>
157 </para>
158</section>
159
160<section id='kernel-metadata-location'>
161 <title>Kernel Metadata Location</title>
162
163 <para>
164 Kernel Metadata can be defined in either the kernel recipe
165 (recipe-space) or in the kernel tree (in-tree).
166 Where you choose to define the Metadata depends on what you want
167 to do and how you intend to work.
168 Regardless of where you define the kernel Metadata, the syntax used
169 applies equally.
170 </para>
171
172 <para>
173 If you are unfamiliar with the Linux kernel and only wish
174 to apply a configuration and possibly a couple of patches provided to
175 you by others, the recipe-space method is recommended.
176 This method is also a good approach if you are working with Linux kernel
177 sources you do not control or if you just do not want to maintain a
178 Linux kernel Git repository on your own.
179 For partial information on how you can define kernel Metadata in
180 the recipe-space, see the
181 "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
182 section.
183 </para>
184
185 <para>
186 Conversely, if you are actively developing a kernel and are already
187 maintaining a Linux kernel Git repository of your own, you might find
188 it more convenient to work with the kernel Metadata in the same
189 repository as the Linux kernel sources.
190 This method can make iterative development of the Linux kernel
191 more efficient outside of the BitBake environment.
192 </para>
193
194 <section id='recipe-space-metadata'>
195 <title>Recipe-Space Metadata</title>
196
197 <para>
198 When stored in recipe-space, the kernel Metadata files reside in a
199 directory hierarchy below
200 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
201 For a linux-yocto recipe or for a Linux kernel recipe derived
202 by copying and modifying
203 <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
204 to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
205 is typically set to
206 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>.
207 See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
208 section for more information.
209 </para>
210
211 <para>
212 Here is an example that shows a trivial tree of kernel Metadata
213 stored in recipe-space within a BSP layer:
214 <literallayout class='monospaced'>
215 meta-my_bsp_layer/
216 `-- recipes-kernel
217 `-- linux
218 `-- linux-yocto
219 |-- bsp-standard.scc
220 |-- bsp.cfg
221 `-- standard.cfg
222 </literallayout>
223 </para>
224
225 <para>
226 When the Metadata is stored in recipe-space, you must take
227 steps to ensure BitBake has the necessary information to decide
228 what files to fetch and when they need to be fetched again.
229 It is only necessary to specify the <filename>.scc</filename>
230 files on the
231 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
232 BitBake parses them and fetches any files referenced in the
233 <filename>.scc</filename> files by the <filename>include</filename>,
234 <filename>patch</filename>, or <filename>kconf</filename> commands.
235 Because of this, it is necessary to bump the recipe
236 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
237 value when changing the content of files not explicitly listed
238 in the <filename>SRC_URI</filename>.
239 </para>
240 </section>
241
242 <section id='in-tree-metadata'>
243 <title>In-Tree Metadata</title>
244
245 <para>
246 When stored in-tree, the kernel Metadata files reside in the
247 <filename>meta</filename> directory of the Linux kernel sources.
248 The <filename>meta</filename> directory can be present in the
249 same repository branch as the sources,
250 such as "master", or <filename>meta</filename> can be its own
251 orphan branch.
252 <note>
253 An orphan branch in Git is a branch with unique history and
254 content to the other branches in the repository.
255 Orphan branches are useful to track Metadata changes
256 independently from the sources of the Linux kernel, while
257 still keeping them together in the same repository.
258 </note>
259 For the purposes of this document, we will discuss all
260 in-tree Metadata as residing below the
261 <filename>meta/cfg/kernel-cache</filename> directory.
262 </para>
263
264 <para>
265 Following is an example that shows how a trivial tree of Metadata
266 is stored in a custom Linux kernel Git repository:
267 <literallayout class='monospaced'>
268 meta/
269 `-- cfg
270 `-- kernel-cache
271 |-- bsp-standard.scc
272 |-- bsp.cfg
273 `-- standard.cfg
274 </literallayout>
275 </para>
276
277 <para>
278 To use a branch different from where the sources reside,
279 specify the branch in the <filename>KMETA</filename> variable
280 in your Linux kernel recipe.
281 Here is an example:
282 <literallayout class='monospaced'>
283 KMETA = "meta"
284 </literallayout>
285 To use the same branch as the sources, set
286 <filename>KMETA</filename> to an empty string:
287 <literallayout class='monospaced'>
288 KMETA = ""
289 </literallayout>
290 If you are working with your own sources and want to create an
291 orphan <filename>meta</filename> branch, use these commands
292 from within your Linux kernel Git repository:
293 <literallayout class='monospaced'>
294 $ git checkout --orphan meta
295 $ git rm -rf .
296 $ git commit --allow-empty -m "Create orphan meta branch"
297 </literallayout>
298 </para>
299
300 <para>
301 If you modify the Metadata in the linux-yocto
302 <filename>meta</filename> branch, you must not forget to update
303 the
304 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
305 statements in the kernel's recipe.
306 In particular, you need to update the
307 <filename>SRCREV_meta</filename> variable to match the commit in
308 the <filename>KMETA</filename> branch you wish to use.
309 Changing the data in these branches and not updating the
310 <filename>SRCREV</filename> statements to match will cause the
311 build to fetch an older commit.
312 </para>
313 </section>
314</section>
315
316<section id='kernel-metadata-syntax'>
317 <title>Kernel Metadata Syntax</title>
318
319 <para>
320 The kernel Metadata consists of three primary types of files:
321 <filename>scc</filename>
322 <footnote>
323 <para>
324 <filename>scc</filename> stands for Series Configuration
325 Control, but the naming has less significance in the
326 current implementation of the tooling than it had in the
327 past.
328 Consider <filename>scc</filename> files to be description files.
329 </para>
330 </footnote>
331 description files, configuration fragments, and patches.
332 The <filename>scc</filename> files define variables and include or
333 otherwise reference any of the three file types.
334 The description files are used to aggregate all types of kernel
335 Metadata into
336 what ultimately describes the sources and the configuration required
337 to build a Linux kernel tailored to a specific machine.
338 </para>
339
340 <para>
341 The <filename>scc</filename> description files are used to define two
342 fundamental types of kernel Metadata:
343 <itemizedlist>
344 <listitem><para>Features</para></listitem>
345 <listitem><para>Board Support Packages (BSPs)</para></listitem>
346 </itemizedlist>
347 </para>
348
349 <para>
350 Features aggregate sources in the form of patches and configuration
351 fragments into a modular reusable unit.
352 You can use features to implement conceptually separate kernel
353 Metadata descriptions such as pure configuration fragments,
354 simple patches, complex features, and kernel types.
355 <link linkend='kernel-types'>Kernel types</link> define general
356 kernel features and policy to be reused in the BSPs.
357 </para>
358
359 <para>
360 BSPs define hardware-specific features and aggregate them with kernel
361 types to form the final description of what will be assembled and built.
362 </para>
363
364 <para>
365 While the kernel Metadata syntax does not enforce any logical
366 separation of configuration fragments, patches, features or kernel
367 types, best practices dictate a logical separation of these types
368 of Metadata.
369 The following Metadata file hierarchy is recommended:
370 <literallayout class='monospaced'>
371 &lt;base&gt;/
372 bsp/
373 cfg/
374 features/
375 ktypes/
376 patches/
377 </literallayout>
378 </para>
379
380 <para>
381 The <filename>bsp</filename> directory contains the
382 <link linkend='bsp-descriptions'>BSP descriptions</link>.
383 The remaining directories all contain "features".
384 Separating <filename>bsp</filename> from the rest of the structure
385 aids conceptualizing intended usage.
386 </para>
387
388 <para>
389 Use these guidelines to help place your <filename>scc</filename>
390 description files within the structure:
391 <itemizedlist>
392 <listitem><para>If your file contains
393 only configuration fragments, place the file in the
394 <filename>cfg</filename> directory.</para></listitem>
395 <listitem><para>If your file contains
396 only source-code fixes, place the file in the
397 <filename>patches</filename> directory.</para></listitem>
398 <listitem><para>If your file encapsulates
399 a major feature, often combining sources and configurations,
400 place the file in <filename>features</filename> directory.
401 </para></listitem>
402 <listitem><para>If your file aggregates
403 non-hardware configuration and patches in order to define a
404 base kernel policy or major kernel type to be reused across
405 multiple BSPs, place the file in <filename>ktypes</filename>
406 directory.
407 </para></listitem>
408 </itemizedlist>
409 </para>
410
411 <para>
412 These distinctions can easily become blurred - especially as
413 out-of-tree features slowly merge upstream over time.
414 Also, remember that how the description files are placed is
415 a purely logical organization and has no impact on the functionality
416 of the kernel Metadata.
417 There is no impact because all of <filename>cfg</filename>,
418 <filename>features</filename>, <filename>patches</filename>, and
419 <filename>ktypes</filename>, contain "features" as far as the kernel
420 tools are concerned.
421 </para>
422
423 <para>
424 Paths used in kernel Metadata files are relative to
425 <filename>&lt;base&gt;</filename>, which is either
426 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
427 if you are creating Metadata in
428 <link linkend='recipe-space-metadata'>recipe-space</link>,
429 or <filename>meta/cfg/kernel-cache/</filename> if you are creating
430 Metadata <link linkend='in-tree-metadata'>in-tree</link>.
431 </para>
432
433 <section id='configuration'>
434 <title>Configuration</title>
435
436 <para>
437 The simplest unit of kernel Metadata is the configuration-only
438 feature.
439 This feature consists of one or more Linux kernel configuration
440 parameters in a configuration fragment file
441 (<filename>.cfg</filename>) and an <filename>.scc</filename> file
442 that describes the fragment.
443 </para>
444
445 <para>
446 The Symmetric Multi-Processing (SMP) fragment included in the
447 <filename>linux-yocto-3.4</filename> Git repository
448 consists of the following two files:
449 <literallayout class='monospaced'>
450 cfg/smp.scc:
451 define KFEATURE_DESCRIPTION "Enable SMP"
452 kconf hardware smp.cfg
453
454 cfg/smp.cfg:
455 CONFIG_SMP=y
456 CONFIG_SCHED_SMT=y
457 </literallayout>
458 You can find information on configuration fragment files in the
459 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
460 section of the Yocto Project Development Manual and in
461 the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
462 section earlier in this manual.
463 </para>
464
465 <para>
466 <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>
467 provides a short description of the fragment.
468 Higher level kernel tools use this description.
469 </para>
470
471 <para>
472 The <filename>kconf</filename> command is used to include the
473 actual configuration fragment in an <filename>.scc</filename>
474 file, and the "hardware" keyword identifies the fragment as
475 being hardware enabling, as opposed to general policy,
476 which would use the "non-hardware" keyword.
477 The distinction is made for the benefit of the configuration
478 validation tools, which warn you if a hardware fragment
479 overrides a policy set by a non-hardware fragment.
480 <note>
481 The description file can include multiple
482 <filename>kconf</filename> statements, one per fragment.
483 </note>
484 </para>
485
486 <para>
487 As described in the
488 "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
489 section, you can use the following BitBake command to audit your
490 configuration:
491 <literallayout class='monospaced'>
492 $ bitbake linux-yocto -c kernel_configcheck -f
493 </literallayout>
494 </para>
495 </section>
496
497 <section id='patches'>
498 <title>Patches</title>
499
500 <para>
501 Patch descriptions are very similar to configuration fragment
502 descriptions, which are described in the previous section.
503 However, instead of a <filename>.cfg</filename> file, these
504 descriptions work with source patches.
505 </para>
506
507 <para>
508 A typical patch includes a description file and the patch itself:
509 <literallayout class='monospaced'>
510 patches/mypatch.scc:
511 patch mypatch.patch
512
513 patches/mypatch.patch:
514 &lt;typical-patch&gt;
515 </literallayout>
516 You can create the typical <filename>.patch</filename>
517 file using <filename>diff -Nurp</filename> or
518 <filename>git format-patch</filename>.
519 </para>
520
521 <para>
522 The description file can include multiple patch statements,
523 one per patch.
524 </para>
525 </section>
526
527 <section id='features'>
528 <title>Features</title>
529
530 <para>
531 Features are complex kernel Metadata types that consist
532 of configuration fragments (<filename>kconf</filename>), patches
533 (<filename>patch</filename>), and possibly other feature
534 description files (<filename>include</filename>).
535 </para>
536
537 <para>
538 Here is an example that shows a feature description file:
539 <literallayout class='monospaced'>
540 features/myfeature.scc
541 define KFEATURE_DESCRIPTION "Enable myfeature"
542
543 patch 0001-myfeature-core.patch
544 patch 0002-myfeature-interface.patch
545
546 include cfg/myfeature_dependency.scc
547 kconf non-hardware myfeature.cfg
548 </literallayout>
549 This example shows how the <filename>patch</filename> and
550 <filename>kconf</filename> commands are used as well as
551 how an additional feature description file is included.
552 </para>
553
554 <para>
555 Typically, features are less granular than configuration
556 fragments and are more likely than configuration fragments
557 and patches to be the types of things you want to specify
558 in the <filename>KERNEL_FEATURES</filename> variable of the
559 Linux kernel recipe.
560 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
561 section earlier in the manual.
562 </para>
563 </section>
564
565 <section id='kernel-types'>
566 <title>Kernel Types</title>
567
568 <para>
569 A kernel type defines a high-level kernel policy by
570 aggregating non-hardware configuration fragments with
571 patches you want to use when building a Linux kernels of a
572 specific type.
573 Syntactically, kernel types are no different than features
574 as described in the "<link linkend='features'>Features</link>"
575 section.
576 The <filename>LINUX_KERNEL_TYPE</filename> variable in the kernel
577 recipe selects the kernel type.
578 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
579 section for more information.
580 </para>
581
582 <para>
583 As an example, the <filename>linux-yocto-3.4</filename>
584 tree defines three kernel types: "standard",
585 "tiny", and "preempt-rt":
586 <itemizedlist>
587 <listitem><para>"standard":
588 Includes the generic Linux kernel policy of the Yocto
589 Project linux-yocto kernel recipes.
590 This policy includes, among other things, which file
591 systems, networking options, core kernel features, and
592 debugging and tracing options are supported.
593 </para></listitem>
594 <listitem><para>"preempt-rt":
595 Applies the <filename>PREEMPT_RT</filename>
596 patches and the configuration options required to
597 build a real-time Linux kernel.
598 This kernel type inherits from the "standard" kernel type.
599 </para></listitem>
600 <listitem><para>"tiny":
601 Defines a bare minimum configuration meant to serve as a
602 base for very small Linux kernels.
603 The "tiny" kernel type is independent from the "standard"
604 configuration.
605 Although the "tiny" kernel type does not currently include
606 any source changes, it might in the future.
607 </para></listitem>
608 </itemizedlist>
609 </para>
610
611 <para>
612 The "standard" kernel type is defined by
613 <filename>standard.scc</filename>:
614 <literallayout class='monospaced'>
615 # Include this kernel type fragment to get the standard features and
616 # configuration values.
617
618 # Include all standard features
619 include standard-nocfg.scc
620
621 kconf non-hardware standard.cfg
622
623 # individual cfg block section
624 include cfg/fs/devtmpfs.scc
625 include cfg/fs/debugfs.scc
626 include cfg/fs/btrfs.scc
627 include cfg/fs/ext2.scc
628 include cfg/fs/ext3.scc
629 include cfg/fs/ext4.scc
630
631 include cfg/net/ipv6.scc
632 include cfg/net/ip_nf.scc
633 include cfg/net/ip6_nf.scc
634 include cfg/net/bridge.scc
635 </literallayout>
636 </para>
637
638 <para>
639 As with any <filename>.scc</filename> file, a
640 kernel type definition can aggregate other
641 <filename>.scc</filename> files with
642 <filename>include</filename> commands.
643 These definitions can also directly pull in
644 configuration fragments and patches with the
645 <filename>kconf</filename> and <filename>patch</filename>
646 commands, respectively.
647 </para>
648
649 <note>
650 It is not strictly necessary to create a kernel type
651 <filename>.scc</filename> file.
652 The Board Support Package (BSP) file can implicitly define
653 the kernel type using a <filename>define
654 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename>
655 line.
656 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
657 section for more information.
658 </note>
659 </section>
660
661 <section id='bsp-descriptions'>
662 <title>BSP Descriptions</title>
663
664 <para>
665 BSP descriptions combine kernel types with hardware-specific
666 features.
667 The hardware-specific portion is typically defined
668 independently, and then aggregated with each supported kernel
669 type.
670 Consider this simple BSP description that supports the "mybsp"
671 machine:
672 <literallayout class='monospaced'>
673 mybsp.scc:
674 define KMACHINE mybsp
675 define KTYPE standard
676 define KARCH i386
677
678 kconf mybsp.cfg
679 </literallayout>
680 Every BSP description should define the
681 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
682 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
683 and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
684 variables.
685 These variables allow the OpenEmbedded build system to identify
686 the description as meeting the criteria set by the recipe being
687 built.
688 This simple example supports the "mybsp" machine for the "standard"
689 kernel and the "i386" architecture.
690 </para>
691
692 <para>
693 Be aware that a hard link between the
694 <filename>KTYPE</filename> variable and a kernel type
695 description file does not exist.
696 Thus, if you do not have kernel types defined in your kernel
697 Metadata, you only need to ensure that the kernel recipe's
698 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
699 variable and the <filename>KTYPE</filename> variable in the
700 BSP description file match.
701 <note>
702 Future versions of the tooling make the specification of
703 <filename>KTYPE</filename> in the BSP optional.
704 </note>
705 </para>
706
707 <para>
708 If you did want to separate your kernel policy from your
709 hardware configuration, you could do so by specifying a kernel
710 type, such as "standard" and including that description file
711 in the BSP description file.
712 See the "<link linkend='kernel-types'>Kernel Types</link>" section
713 for more information.
714 </para>
715
716 <para>
717 You might also have multiple hardware configurations that you
718 aggregate into a single hardware description file that you
719 could include in the BSP description file, rather than referencing
720 a single <filename>.cfg</filename> file.
721 Consider the following:
722 <literallayout class='monospaced'>
723 mybsp.scc:
724 define KMACHINE mybsp
725 define KTYPE standard
726 define KARCH i386
727
728 include standard.scc
729 include mybsp-hw.scc
730 </literallayout>
731 </para>
732
733 <para>
734 In the above example, <filename>standard.scc</filename>
735 aggregates all the configuration fragments, patches, and
736 features that make up your standard kernel policy whereas
737 <filename>mybsp-hw.scc</filename> aggregates all those necessary
738 to support the hardware available on the "mybsp" machine.
739 For information on how to break a complete
740 <filename>.config</filename> file into the various
741 configuration fragments, see the
742 "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
743 section.
744 </para>
745
746 <para>
747 Many real-world examples are more complex.
748 Like any other <filename>.scc</filename> file, BSP
749 descriptions can aggregate features.
750 Consider the Fish River Island 2 (fri2)
751 BSP definition from the <filename>linux-yocto-3.4</filename>
752 Git repository:
753 <literallayout class='monospaced'>
754 fri2.scc:
755 kconf hardware fri2.cfg
756
757 include cfg/x86.scc
758 include features/eg20t/eg20t.scc
759 include cfg/dmaengine.scc
760 include features/ericsson-3g/f5521gw.scc
761 include features/power/intel.scc
762 include cfg/efi.scc
763 include features/usb/ehci-hcd.scc
764 include features/usb/ohci-hcd.scc
765 include features/iwlwifi/iwlwifi.scc
766 </literallayout>
767 </para>
768
769 <para>
770 The <filename>fri2.scc</filename> description file includes
771 a hardware configuration fragment
772 (<filename>fri2.cfg</filename>) specific to the Fish River
773 Island 2 BSP as well as several more general configuration
774 fragments and features enabling hardware found on the
775 machine.
776 This description file is then included in each of the three
777 "fri2" description files for the supported kernel types
778 (i.e. "standard", "preempt-rt", and "tiny").
779 Consider the "fri2" description for the "standard" kernel
780 type:
781 <literallayout class='monospaced'>
782 fri2-standard.scc:
783 define KMACHINE fri2
784 define KTYPE standard
785 define KARCH i386
786
787 include ktypes/standard/standard.scc
788 branch fri2
789
790 git merge emgd-1.14
791
792 include fri2.scc
793
794 # Extra fri2 configs above the minimal defined in fri2.scc
795 include cfg/efi-ext.scc
796 include features/drm-emgd/drm-emgd.scc
797 include cfg/vesafb.scc
798
799 # default policy for standard kernels
800 include cfg/usb-mass-storage.scc
801 </literallayout>
802 The <filename>include</filename> command midway through the file
803 includes the <filename>fri2.scc</filename> description that
804 defines all hardware enablements for the BSP that is common to all
805 kernel types.
806 Using this command significantly reduces duplication.
807 </para>
808
809 <para>
810 This "fri2" standard description introduces a few more variables
811 and commands that are worth further discussion.
812 Notice the <filename>branch fri2</filename> command, which creates
813 a machine-specific branch into which source changes are applied.
814 With this branch set up, the <filename>git merge</filename> command
815 uses Git to merge in a feature branch named "emgd-1.14".
816 You could also handle this with the <filename>patch</filename>
817 command.
818 However, for commonly used features such as this, feature branches
819 are a convenient mechanism.
820 See the "<link linkend='feature-branches'>Feature Branches</link>"
821 section for more information.
822 </para>
823
824 <para>
825 Now consider the "fri2" description for the "tiny" kernel type:
826 <literallayout class='monospaced'>
827 fri2-tiny.scc:
828 define KMACHINE fri2
829 define KTYPE tiny
830 define KARCH i386
831
832 include ktypes/tiny/tiny.scc
833 branch fri2
834
835 include fri2.scc
836 </literallayout>
837 As you might expect, the "tiny" description includes quite a
838 bit less.
839 In fact, it includes only the minimal policy defined by the
840 "tiny" kernel type and the hardware-specific configuration required
841 for booting the machine along with the most basic functionality of
842 the system as defined in the base "fri2" description file.
843 </para>
844
845 <para>
846 Notice again the three critical variables:
847 <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
848 and <filename>KARCH</filename>.
849 Of these variables, only the <filename>KTYPE</filename> has changed.
850 It is now set to "tiny".
851 </para>
852 </section>
853</section>
854
855<section id='organizing-your-source'>
856 <title>Organizing Your Source</title>
857
858 <para>
859 Many recipes based on the <filename>linux-yocto-custom.bb</filename>
860 recipe use Linux kernel sources that have only a single
861 branch - "master".
862 This type of repository structure is fine for linear development
863 supporting a single machine and architecture.
864 However, if you work with multiple boards and architectures,
865 a kernel source repository with multiple branches is more
866 efficient.
867 For example, suppose you need a series of patches for one board to boot.
868 Sometimes, these patches are works-in-progress or fundamentally wrong,
869 yet they are still necessary for specific boards.
870 In these situations, you most likely do not want to include these
871 patches in every kernel you build (i.e. have the patches as part of
872 the lone "master" branch).
873 It is situations like these that give rise to multiple branches used
874 within a Linux kernel sources Git repository.
875 </para>
876
877 <para>
878 Repository organization strategies exist that maximize source reuse,
879 remove redundancy, and logically order your changes.
880 This section presents strategies for the following cases:
881 <itemizedlist>
882 <listitem><para>Encapsulating patches in a feature description
883 and only including the patches in the BSP descriptions of
884 the applicable boards.</para></listitem>
885 <listitem><para>Creating a machine branch in your
886 kernel source repository and applying the patches on that
887 branch only.</para></listitem>
888 <listitem><para>Creating a feature branch in your
889 kernel source repository and merging that branch into your
890 BSP when needed.</para></listitem>
891 </itemizedlist>
892 </para>
893
894 <para>
895 The approach you take is entirely up to you
896 and depends on what works best for your development model.
897 </para>
898
899 <section id='encapsulating-patches'>
900 <title>Encapsulating Patches</title>
901
902 <para>
903 if you are reusing patches from an external tree and are not
904 working on the patches, you might find the encapsulated feature
905 to be appropriate.
906 Given this scenario, you do not need to create any branches in the
907 source repository.
908 Rather, you just take the static patches you need and encapsulate
909 them within a feature description.
910 Once you have the feature description, you simply include that into
911 the BSP description as described in the
912 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
913 section.
914 </para>
915
916 <para>
917 You can find information on how to create patches and BSP
918 descriptions in the "<link linkend='patches'>Patches</link>" and
919 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
920 sections.
921 </para>
922 </section>
923
924 <section id='machine-branches'>
925 <title>Machine Branches</title>
926
927 <para>
928 When you have multiple machines and architectures to support,
929 or you are actively working on board support, it is more
930 efficient to create branches in the repository based on
931 individual machines.
932 Having machine branches allows common source to remain in the
933 "master" branch with any features specific to a machine stored
934 in the appropriate machine branch.
935 This organization method frees you from continually reintegrating
936 your patches into a feature.
937 </para>
938
939 <para>
940 Once you have a new branch, you can set up your kernel Metadata
941 to use the branch a couple different ways.
942 In the recipe, you can specify the new branch as the
943 <filename>KBRANCH</filename> to use for the board as
944 follows:
945 <literallayout class='monospaced'>
946 KBRANCH = "mynewbranch"
947 </literallayout>
948 Another method is to use the <filename>branch</filename> command
949 in the BSP description:
950 <literallayout class='monospaced'>
951 mybsp.scc:
952 define KMACHINE mybsp
953 define KTYPE standard
954 define KARCH i386
955 include standard.scc
956
957 branch mynewbranch
958
959 include mybsp-hw.scc
960 </literallayout>
961 </para>
962
963 <para>
964 If you find
965 yourself with numerous branches, you might consider using a
966 hierarchical branching system similar to what the linux-yocto Linux
967 kernel repositories use:
968 <literallayout class='monospaced'>
969 &lt;common&gt;/&lt;kernel_type&gt;/&lt;machine&gt;
970 </literallayout>
971 </para>
972
973 <para>
974 If you had two kernel types, "standard" and "small" for
975 instance, and three machines, the branches in your
976 Git repository might look like this:
977 <literallayout class='monospaced'>
978 common/base
979 common/standard/base
980 common/standard/machine_a
981 common/standard/machine_b
982 common/standard/machine_c
983 common/small/base
984 common/small/machine_a
985 </literallayout>
986 </para>
987
988 <para>
989 This organization can help clarify the branch relationships.
990 In this case, <filename>common/standard/machine_a</filename>
991 includes everything in <filename>common/base</filename> and
992 <filename>common/standard/base</filename>.
993 The "standard" and "small" branches add sources specific to those
994 kernel types that for whatever reason are not appropriate for the
995 other branches.
996 <note>The "base" branches are an artifact of the way Git manages
997 its data internally on the filesystem: Git will not allow you
998 to use <filename>common/standard</filename> and
999 <filename>common/standard/machine_a</filename> because it
1000 would have to create a file and a directory named "standard".
1001 </note>
1002 </para>
1003 </section>
1004
1005 <section id='feature-branches'>
1006 <title>Feature Branches</title>
1007
1008 <para>
1009 When you are actively developing new features, it can be more
1010 efficient to work with that feature as a branch, rather than
1011 as a set of patches that have to be regularly updated.
1012 The Yocto Project Linux kernel tools provide for this with
1013 the <filename>git merge</filename> command.
1014 </para>
1015
1016 <para>
1017 To merge a feature branch into a BSP, insert the
1018 <filename>git merge</filename> command after any
1019 <filename>branch</filename> commands:
1020 <literallayout class='monospaced'>
1021 mybsp.scc:
1022 define KMACHINE mybsp
1023 define KTYPE standard
1024 define KARCH i386
1025 include standard.scc
1026
1027 branch mynewbranch
1028 git merge myfeature
1029
1030 include mybsp-hw.scc
1031 </literallayout>
1032 </para>
1033 </section>
1034</section>
1035
1036<section id='scc-reference'>
1037 <title>SCC Description File Reference</title>
1038
1039 <para>
1040 This section provides a brief reference for the commands you can use
1041 within an SCC description file (<filename>.scc</filename>):
1042 <itemizedlist>
1043 <listitem><para><filename>branch [ref]</filename>:
1044 Creates a new branch relative to the current branch
1045 (typically <filename>${KTYPE}</filename>) using
1046 the currently checked-out branch, or "ref" if specified.
1047 </para></listitem>
1048 <listitem><para><filename>define</filename>:
1049 Defines variables, such as <filename>KMACHINE</filename>,
1050 <filename>KTYPE</filename>, <filename>KARCH</filename>,
1051 and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
1052 <listitem><para><filename>include SCC_FILE</filename>:
1053 Includes an SCC file in the current file.
1054 The file is parsed as if you had inserted it inline.
1055 </para></listitem>
1056 <listitem><para><filename>kconf [hardware|non-hardware] CFG_FILE</filename>:
1057 Queues a configuration fragment for merging into the final
1058 Linux <filename>.config</filename> file.</para></listitem>
1059 <listitem><para><filename>git merge GIT_BRANCH</filename>:
1060 Merges the feature branch into the current branch.
1061 </para></listitem>
1062 <listitem><para><filename>patch PATCH_FILE</filename>:
1063 Applies the patch to the current Git branch.</para></listitem>
1064 </itemizedlist>
1065 </para>
1066</section>
1067
1068</chapter>
1069<!--
1070vim: expandtab tw=80 ts=4
1071-->
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
new file mode 100644
index 0000000..a152f9f
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -0,0 +1,863 @@
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-dev-common'>
6
7<title>Common Tasks</title>
8
9<para>
10 This chapter presents several common tasks you perform when you
11 work with the Yocto Project Linux kernel.
12 These tasks include preparing a layer, modifying an existing recipe,
13 iterative development, working with your own sources, and incorporating
14 out-of-tree modules.
15 <note>
16 The examples presented in this chapter work with the Yocto Project
17 1.2.2 Release and forward.
18 </note>
19</para>
20
21 <section id='creating-and-preparing-a-layer'>
22 <title>Creating and Preparing a Layer</title>
23
24 <para>
25 If you are going to be modifying kernel recipes, it is recommended
26 that you create and prepare your own layer in which to do your
27 work.
28 Your layer contains its own BitBake append files
29 (<filename>.bbappend</filename>) and provides a convenient
30 mechanism to create your own recipe files
31 (<filename>.bb</filename>).
32 For details on how to create and work with layers, see the following
33 sections in the Yocto Project Development Manual:
34 <itemizedlist>
35 <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for
36 general information on layers and how to create layers.</para></listitem>
37 <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for
38 specific instructions on setting up a layer for kernel
39 development.</para></listitem>
40 </itemizedlist>
41 </para>
42 </section>
43
44 <section id='modifying-an-existing-recipe'>
45 <title>Modifying an Existing Recipe</title>
46
47 <para>
48 In many cases, you can customize an existing linux-yocto recipe to
49 meet the needs of your project.
50 Each release of the Yocto Project provides a few Linux
51 kernel recipes from which you can choose.
52 These are located in the
53 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
54 in <filename>meta/recipes-kernel/linux</filename>.
55 </para>
56
57 <para>
58 Modifying an existing recipe can consist of the following:
59 <itemizedlist>
60 <listitem><para>Creating the append file</para></listitem>
61 <listitem><para>Applying patches</para></listitem>
62 <listitem><para>Changing the configuration</para></listitem>
63 </itemizedlist>
64 </para>
65
66 <para>
67 Before modifying an existing recipe, be sure that you have created
68 a minimal, custom layer from which you can work.
69 See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
70 section for some general resources.
71 You can also see the
72 "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section
73 of the Yocto Project Development Manual for a detailed
74 example.
75 </para>
76
77 <section id='creating-the-append-file'>
78 <title>Creating the Append File</title>
79
80 <para>
81 You create this file in your custom layer.
82 You also name it accordingly based on the linux-yocto recipe
83 you are using.
84 For example, if you are modifying the
85 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>
86 recipe, the append file will typical be located as follows
87 within your custom layer:
88 <literallayout class='monospaced'>
89 &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto_3.4.bbappend
90 </literallayout>
91 The append file should initially extend the
92 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
93 search path by prepending the directory that contains your
94 files to the
95 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
96 variable as follows:
97 <literallayout class='monospaced'>
98 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
99 </literallayout>
100 The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
101 expands to "linux-yocto" in the current directory for this
102 example.
103 If you add any new files that modify the kernel recipe and you
104 have extended <filename>FILESPATH</filename> as
105 described above, you must place the files in your layer in the
106 following area:
107 <literallayout class='monospaced'>
108 &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto/
109 </literallayout>
110 <note>If you are working on a new machine Board Support Package
111 (BSP), be sure to refer to the
112 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
113 </note>
114 </para>
115 </section>
116
117 <section id='applying-patches'>
118 <title>Applying Patches</title>
119
120 <para>
121 If you have a single patch or a small series of patches
122 that you want to apply to the Linux kernel source, you
123 can do so just as you would with any other recipe.
124 You first copy the patches to the path added to
125 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
126 in your <filename>.bbappend</filename> file as described in
127 the previous section, and then reference them in
128 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
129 statements.
130 </para>
131
132 <para>
133 For example, you can apply a three-patch series by adding the
134 following lines to your linux-yocto <filename>.bbappend</filename>
135 file in your layer:
136 <literallayout class='monospaced'>
137 SRC_URI += "file://0001-first-change.patch"
138 SRC_URI += "file://0002-first-change.patch"
139 SRC_URI += "file://0003-first-change.patch"
140 </literallayout>
141 The next time you run BitBake to build the Linux kernel, BitBake
142 detects the change in the recipe and fetches and applies the patches
143 before building the kernel.
144 </para>
145
146 <para>
147 For a detailed example showing how to patch the kernel, see the
148 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
149 section in the Yocto Project Development Manual.
150 </para>
151 </section>
152
153 <section id='changing-the-configuration'>
154 <title>Changing the Configuration</title>
155
156 <para>
157 You can make wholesale or incremental changes to the Linux
158 kernel <filename>.config</filename> file by including a
159 <filename>defconfig</filename> and by specifying
160 configuration fragments in the
161 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
162 </para>
163
164 <para>
165 If you have a final Linux kernel <filename>.config</filename>
166 file you want to use, copy it to a directory named
167 <filename>files</filename>, which must be in
168 your layer's <filename>recipes-kernel/linux</filename>
169 directory, and name the file "defconfig".
170 Then, add the following lines to your linux-yocto
171 <filename>.bbappend</filename> file in your layer:
172 <literallayout class='monospaced'>
173 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
174 SRC_URI += "file://defconfig"
175 </literallayout>
176 The <filename>SRC_URI</filename> tells the build system how to
177 search for the file, while the
178 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
179 extends the
180 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
181 variable (search directories) to include the
182 <filename>files</filename> directory you created for the
183 configuration changes.
184 </para>
185
186 <note>
187 The build system applies the configurations from the
188 <filename>.config</filename> file before applying any
189 subsequent configuration fragments.
190 The final kernel configuration is a combination of the
191 configurations in the <filename>.config</filename> file and
192 any configuration fragments you provide.
193 You need to realize that if you have any configuration
194 fragments, the build system applies these on top of and
195 after applying the existing <filename>.config</filename>
196 file configurations.
197 </note>
198
199 <para>
200 Generally speaking, the preferred approach is to determine the
201 incremental change you want to make and add that as a
202 configuration fragment.
203 For example, if you want to add support for a basic serial
204 console, create a file named <filename>8250.cfg</filename> in
205 the <filename>files</filename> directory with the following
206 content (without indentation):
207 <literallayout class='monospaced'>
208 CONFIG_SERIAL_8250=y
209 CONFIG_SERIAL_8250_CONSOLE=y
210 CONFIG_SERIAL_8250_PCI=y
211 CONFIG_SERIAL_8250_NR_UARTS=4
212 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
213 CONFIG_SERIAL_CORE=y
214 CONFIG_SERIAL_CORE_CONSOLE=y
215 </literallayout>
216 Next, include this configuration fragment and extend the
217 <filename>FILESPATH</filename> variable in your
218 <filename>.bbappend</filename> file:
219 <literallayout class='monospaced'>
220 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
221 SRC_URI += "file://8250.cfg"
222 </literallayout>
223 The next time you run BitBake to build the Linux kernel, BitBake
224 detects the change in the recipe and fetches and applies the
225 new configuration before building the kernel.
226 </para>
227
228 <para>
229 For a detailed example showing how to configure the kernel,
230 see the
231 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
232 section in the Yocto Project Development Manual.
233 </para>
234 </section>
235 </section>
236
237 <section id='using-an-iterative-development-process'>
238 <title>Using an Iterative Development Process</title>
239
240 <para>
241 If you do not have existing patches or configuration files,
242 you can iteratively generate them from within the BitBake build
243 environment as described within this section.
244 During an iterative workflow, running a previously completed BitBake
245 task causes BitBake to invalidate the tasks that follow the
246 completed task in the build sequence.
247 Invalidated tasks rebuild the next time you run the build using
248 BitBake.
249 </para>
250
251 <para>
252 As you read this section, be sure to substitute the name
253 of your Linux kernel recipe for the term
254 "linux-yocto".
255 </para>
256
257 <section id='tip-dirty-string'>
258 <title>"-dirty" String</title>
259
260<!--
261 <para>
262 <emphasis>AR - Darrren Hart:</emphasis> This section
263 originated from the old Yocto Project Kernel Architecture
264 and Use Manual.
265 It was decided we need to put it in this section here.
266 Darren needs to figure out where we want it and what part
267 of it we want (all, revision???)
268 </para>
269-->
270
271 <para>
272 If kernel images are being built with "-dirty" on the
273 end of the version string, this simply means that
274 modifications in the source directory have not been committed.
275 <literallayout class='monospaced'>
276 $ git status
277 </literallayout>
278 </para>
279
280 <para>
281 You can use the above Git command to report modified,
282 removed, or added files.
283 You should commit those changes to the tree regardless of
284 whether they will be saved, exported, or used.
285 Once you commit the changes, you need to rebuild the kernel.
286 </para>
287
288 <para>
289 To force a pickup and commit of all such pending changes,
290 enter the following:
291 <literallayout class='monospaced'>
292 $ git add .
293 $ git commit -s -a -m "getting rid of -dirty"
294 </literallayout>
295 </para>
296
297 <para>
298 Next, rebuild the kernel.
299 </para>
300 </section>
301
302 <section id='generating-configuration-files'>
303 <title>Generating Configuration Files</title>
304
305 <para>
306 You can manipulate the <filename>.config</filename> file
307 used to build a linux-yocto recipe with the
308 <filename>menuconfig</filename> command as follows:
309 <literallayout class='monospaced'>
310 $ bitbake linux-yocto -c menuconfig
311 </literallayout>
312 This command starts the Linux kernel configuration tool,
313 which allows you to prepare a new
314 <filename>.config</filename> file for the build.
315 When you exit the tool, be sure to save your changes
316 at the prompt.
317 </para>
318
319 <para>
320 The resulting <filename>.config</filename> file is
321 located in
322 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the
323 <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>}-build</filename> directory.
324 You can use the entire <filename>.config</filename> file as the
325 <filename>defconfig</filename> file as described in the
326 "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
327 </para>
328
329 <para>
330 A better method is to create a configuration fragment using the
331 differences between two configuration files: one previously
332 created and saved, and one freshly created using the
333 <filename>menuconfig</filename> tool.
334 </para>
335
336 <para>
337 To create a configuration fragment using this method, follow
338 these steps:
339 <orderedlist>
340 <listitem><para>Complete a build at least through the kernel
341 configuration task as follows:
342 <literallayout class='monospaced'>
343 $ bitbake linux-yocto -c kernel_configme -f
344 </literallayout></para></listitem>
345 <listitem><para>Copy and rename the resulting
346 <filename>.config</filename> file (e.g.
347 <filename>config.orig</filename>).
348 </para></listitem>
349 <listitem><para>Run the <filename>menuconfig</filename>
350 command:
351 <literallayout class='monospaced'>
352 $ bitbake linux-yocto -c menuconfig
353 </literallayout></para></listitem>
354 <listitem><para>Prepare a configuration fragment based on
355 the differences between the two files.
356 </para></listitem>
357 </orderedlist>
358 </para>
359
360 <para>
361 Ultimately, the configuration fragment file needs to be a
362 list of Linux kernel <filename>CONFIG_</filename> assignments.
363 It cannot be in <filename>diff</filename> format.
364 Here is an example of a command that creates your
365 configuration fragment file.
366 Regardless of the exact command you use, plan on reviewing
367 the output as you can usually remove some of the defaults:
368 <literallayout class='monospaced'>
369 $ diff -Nurp config.orig .config | sed -n "s/^\+//p" > frag.cfg
370 </literallayout>
371 See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
372 section for information on how to use the output as a
373 configuration fragment.
374 <note>
375 You can also use this method to create configuration
376 fragments for a BSP.
377 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
378 section for more information.
379 </note>
380 </para>
381
382 <para>
383 The kernel tools also provide configuration validation.
384 You can use these tools to produce warnings for when a
385 requested configuration does not appear in the final
386 <filename>.config</filename> file or when you override a
387 policy configuration in a hardware configuration fragment.
388 Here is an example with some sample output of the command
389 that runs these tools:
390 <literallayout class='monospaced'>
391 $ bitbake linux-yocto -c kernel_configcheck -f
392
393 ...
394
395 NOTE: validating kernel configuration
396 This BSP sets 3 invalid/obsolete kernel options.
397 These config options are not offered anywhere within this kernel.
398 The full list can be found in your kernel src dir at:
399 meta/cfg/standard/mybsp/invalid.cfg
400
401 This BSP sets 21 kernel options that are possibly non-hardware related.
402 The full list can be found in your kernel src dir at:
403 meta/cfg/standard/mybsp/specified_non_hdw.cfg
404
405 WARNING: There were 2 hardware options requested that do not
406 have a corresponding value present in the final ".config" file.
407 This probably means you are not't getting the config you wanted.
408 The full list can be found in your kernel src dir at:
409 meta/cfg/standard/mybsp/mismatch.cfg
410 </literallayout>
411 </para>
412
413 <para>
414 The output describes the various problems that you can
415 encounter along with where to find the offending configuration
416 items.
417 You can use the information in the logs to adjust your
418 configuration files and then repeat the
419 <filename>kernel_configme</filename> and
420 <filename>kernel_configcheck</filename> commands until
421 they produce no warnings.
422 </para>
423
424 <para>
425 For more information on how to use the
426 <filename>menuconfig</filename> tool, see the
427 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
428 section in the Yocto Project Development Manual.
429 </para>
430 </section>
431
432 <section id='modifying-source-code'>
433 <title>Modifying Source Code</title>
434
435 <para>
436 You can experiment with source code changes and create a
437 simple patch without leaving the BitBake environment.
438 To get started, be sure to complete a build at
439 least through the kernel configuration task:
440 <literallayout class='monospaced'>
441 $ bitbake linux-yocto -c kernel_configme -f
442 </literallayout>
443 Taking this step ensures you have the sources prepared
444 and the configuration completed.
445 You can find the sources in the
446 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.
447 </para>
448
449 <para>
450 You can edit the sources as you would any other Linux source
451 tree.
452 However, keep in mind that you will lose changes if you
453 trigger the <filename>fetch</filename> task for the recipe.
454 You can avoid triggering this task by not issuing BitBake's
455 <filename>cleanall</filename>, <filename>cleansstate</filename>,
456 or forced <filename>fetch</filename> commands.
457 Also, do not modify the recipe itself while working
458 with temporary changes or BitBake might run the
459 <filename>fetch</filename> command depending on the
460 changes to the recipe.
461 </para>
462
463 <para>
464 To test your temporary changes, instruct BitBake to run the
465 <filename>compile</filename> again.
466 The <filename>-f</filename> option forces the command to run
467 even though BitBake might think it has already done so:
468 <literallayout class='monospaced'>
469 $ bitbake linux-yocto -c compile -f
470 </literallayout>
471 If the compile fails, you can update the sources and repeat
472 the <filename>compile</filename>.
473 Once compilation is successful, you can inspect and test
474 the resulting build (i.e. kernel, modules, and so forth) from
475 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
476 <literallayout class='monospaced'>
477 ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build
478 </literallayout>
479 Alternatively, you can run the <filename>deploy</filename>
480 command to place the kernel image in the
481 <filename>tmp/deploy/images</filename> directory:
482 <literallayout class='monospaced'>
483 $ bitbake linux-yocto -c deploy
484 </literallayout>
485 And, of course, you can perform the remaining installation and
486 packaging steps by issuing:
487 <literallayout class='monospaced'>
488 $ bitbake linux-yocto
489 </literallayout>
490 </para>
491
492 <para>
493 For rapid iterative development, the edit-compile-repeat loop
494 described in this section is preferable to rebuilding the
495 entire recipe because the installation and packaging tasks
496 are very time consuming.
497 </para>
498
499 <para>
500 Once you are satisfied with your source code modifications,
501 you can make them permanent by generating patches and
502 applying them to the
503 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
504 statement as described in section
505 "<link linkend='applying-patches'>Applying Patches</link>" section.
506 If you are not familiar with generating patches, refer to the
507 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
508 section in the Yocto Project Development Manual.
509 </para>
510 </section>
511 </section>
512
513 <section id='working-with-your-own-sources'>
514 <title>Working With Your Own Sources</title>
515
516 <para>
517 If you cannot work with one of the Linux kernel
518 versions supported by existing linux-yocto recipes, you can
519 still make use of the Yocto Project Linux kernel tooling by
520 working with your own sources.
521 When you use your own sources, you will not be able to
522 leverage the existing kernel
523 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and
524 stabilization work of the linux-yocto sources.
525 However, you will be able to manage your own Metadata in the same
526 format as the linux-yocto sources.
527 Maintaining format compatibility facilitates converging with
528 linux-yocto on a future, mutually-supported kernel version.
529 </para>
530
531 <para>
532 To help you use your own sources, the Yocto Project provides a
533 linux-yocto custom recipe
534 (<filename>linux-yocto-custom.bb</filename>) that uses
535 <filename>kernel.org</filename> sources
536 and the Yocto Project Linux kernel tools for managing
537 kernel Metadata.
538 You can find this recipe in the
539 <filename>poky</filename> Git repository of the
540 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
541 at:
542 <literallayout class="monospaced">
543 poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
544 </literallayout>
545 </para>
546
547 <para>
548 Here are some basic steps you can use to work with your own sources:
549 <orderedlist>
550 <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename>
551 recipe to your layer and give it a meaningful name.
552 The name should include the version of the Linux kernel you
553 are using (e.g. <filename>linux-yocto-myproject_3.5.bb</filename>,
554 where "3.5" is the base version of the Linux kernel
555 with which you would be working).</para></listitem>
556 <listitem><para>In the same directory inside your layer,
557 create a matching directory
558 to store your patches and configuration files (e.g.
559 <filename>linux-yocto-myproject</filename>).
560 </para></listitem>
561 <listitem><para>Edit the following variables in your recipe
562 as appropriate for your project:
563 <itemizedlist>
564 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
565 The <filename>SRC_URI</filename> should be a Git
566 repository that uses one of the supported Git fetcher
567 protocols (i.e. <filename>file</filename>,
568 <filename>git</filename>, <filename>http</filename>,
569 and so forth).
570 The skeleton recipe provides an example
571 <filename>SRC_URI</filename> as a syntax reference.
572 </para></listitem>
573 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
574 The Linux kernel version you are using (e.g.
575 "3.4").</para></listitem>
576 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
577 The Linux kernel <filename>CONFIG_LOCALVERSION</filename>
578 that is compiled into the resulting kernel and visible
579 through the <filename>uname</filename> command.
580 </para></listitem>
581 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
582 The commit ID from which you want to build.
583 </para></listitem>
584 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
585 Treat this variable the same as you would in any other
586 recipe.
587 Increment the variable to indicate to the OpenEmbedded
588 build system that the recipe has changed.
589 </para></listitem>
590 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
591 The default <filename>PV</filename> assignment is
592 typically adequate.
593 It combines the <filename>LINUX_VERSION</filename>
594 with the Source Control Manager (SCM) revision
595 as derived from the
596 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
597 variable.
598 The combined results are a string with
599 the following form:
600 <literallayout class='monospaced'>
601 3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
602 </literallayout>
603 While lengthy, the extra verbosity in <filename>PV</filename>
604 helps ensure you are using the exact
605 sources from which you intend to build.
606 </para></listitem>
607 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
608 A list of the machines supported by your new recipe.
609 This variable in the example recipe is set
610 by default to a regular expression that matches
611 only the empty string, "(^$)".
612 This default setting triggers an explicit build
613 failure.
614 You must change it to match a list of the machines
615 that your new recipe supports.
616 For example, to support the <filename>qemux86</filename>
617 and <filename>qemux86-64</filename> machines, use
618 the following form:
619 <literallayout class='monospaced'>
620 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
621 </literallayout></para></listitem>
622 </itemizedlist></para></listitem>
623 <listitem><para>Provide further customizations to your recipe
624 as needed just as you would customize an existing
625 linux-yocto recipe.
626 See the "<link linkend='modifying-an-existing-recipe'>Modifying
627 an Existing Recipe</link>" section for information.
628 </para></listitem>
629 </orderedlist>
630 </para>
631 </section>
632
633 <section id='incorporating-out-of-tree-modules'>
634 <title>Incorporating Out-of-Tree Modules</title>
635
636 <para>
637 While it is always preferable to work with sources integrated
638 into the Linux kernel sources, if you need an external kernel
639 module, the <filename>hello-mod.bb</filename> recipe is available
640 as a template from which you can create your own out-of-tree
641 Linux kernel module recipe.
642 </para>
643
644 <para>
645 This template recipe is located in the
646 <filename>poky</filename> Git repository of the
647 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
648 at:
649 <literallayout class="monospaced">
650 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
651 </literallayout>
652 </para>
653
654 <para>
655 To get started, copy this recipe to your layer and give it a
656 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
657 In the same directory, create a directory named
658 <filename>files</filename> where you can store any source files,
659 patches, or other files necessary for building
660 the module that do not come with the sources.
661 Finally, update the recipe as appropriate for the module.
662 Typically you will need to set the following variables:
663 <itemizedlist>
664 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
665 </para></listitem>
666 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
667 </para></listitem>
668 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
669 </para></listitem>
670 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
671 </para></listitem>
672 </itemizedlist>
673 </para>
674
675 <para>
676 Depending on the build system used by the module sources, you might
677 need to make some adjustments.
678 For example, a typical module <filename>Makefile</filename> looks
679 much like the one provided with the <filename>hello-mod</filename>
680 template:
681 <literallayout class='monospaced'>
682 obj-m := hello.o
683
684 SRC := $(shell pwd)
685
686 all:
687 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
688
689 modules_install:
690 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
691 ...
692 </literallayout>
693 </para>
694
695 <para>
696 The important point to note here is the
697 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
698 variable.
699 The class <filename>module.bbclass</filename> sets this variable,
700 as well as the
701 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
702 variable to
703 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
704 with the necessary Linux kernel build information to build modules.
705 If your module <filename>Makefile</filename> uses a different
706 variable, you might want to override the
707 <filename>do_compile()</filename> step, or create a patch to
708 the <filename>Makefile</filename> to work with the more typical
709 <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
710 variables.
711 </para>
712
713 <para>
714 After you have prepared your recipe, you will likely want to
715 include the module in your images.
716 To do this, see the documentation for the following variables in
717 the Yocto Project Reference Manual and set one of them as
718 appropriate in your machine configuration file:
719 <itemizedlist>
720 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
721 </para></listitem>
722 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
723 </para></listitem>
724 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
725 </para></listitem>
726 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
727 </para></listitem>
728 </itemizedlist>
729 </para>
730
731 <para>
732 modules are often not required for boot and can be excluded from
733 certain build configurations.
734 The following allows for the most flexibility:
735 <literallayout class='monospaced'>
736 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
737 </literallayout>
738 Where the value is derived by appending the module filename without
739 the <filename>.ko</filename> extension to the string
740 "kernel-module-".
741 </para>
742
743 <para>
744 Because the variable is
745 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
746 and not a
747 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
748 variable, the build will not fail if this module is not available
749 to include in the image.
750 </para>
751 </section>
752
753 <section id='inspecting-changes-and-commits'>
754 <title>Inspecting Changes and Commits</title>
755
756 <para>
757 A common question when working with a kernel is:
758 "What changes have been applied to this tree?"
759 Rather than using "grep" across directories to see what has
760 changed, you can use Git to inspect or search the kernel tree.
761 Using Git is an efficient way to see what has changed in the tree.
762 </para>
763
764 <section id='what-changed-in-a-kernel'>
765 <title>What Changed in a Kernel?</title>
766
767 <para>
768 Following are a few examples that show how to use Git
769 commands to examine changes.
770 These examples are by no means the only way to see changes.
771 <note>
772 In the following examples, unless you provide a commit
773 range, <filename>kernel.org</filename> history is blended
774 with Yocto Project kernel changes.
775 You can form ranges by using branch names from the
776 kernel tree as the upper and lower commit markers with
777 the Git commands.
778 You can see the branch names through the web interface
779 to the Yocto Project source repositories at
780 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
781 </note>
782 To see a full range of the changes, use the
783 <filename>git whatchanged</filename> command and specify a
784 commit range for the branch
785 (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
786 </para>
787
788 <para>
789 Here is an example that looks at what has changed in the
790 <filename>emenlow</filename> branch of the
791 <filename>linux-yocto-3.4</filename> kernel.
792 The lower commit range is the commit associated with the
793 <filename>standard/base</filename> branch, while
794 the upper commit range is the commit associated with the
795 <filename>standard/emenlow</filename> branch.
796 <literallayout class='monospaced'>
797 $ git whatchanged origin/standard/base..origin/standard/emenlow
798 </literallayout>
799 </para>
800
801 <para>
802 To see short, one line summaries of changes use the
803 <filename>git log</filename> command:
804 <literallayout class='monospaced'>
805 $ git log --oneline origin/standard/base..origin/standard/emenlow
806 </literallayout>
807 </para>
808
809 <para>
810 Use this command to see code differences for the changes:
811 <literallayout class='monospaced'>
812 $ git diff origin/standard/base..origin/standard/emenlow
813 </literallayout>
814 </para>
815
816 <para>
817 Use this command to see the commit log messages and the
818 text differences:
819 <literallayout class='monospaced'>
820 $ git show origin/standard/base..origin/standard/emenlow
821 </literallayout>
822 </para>
823
824 <para>
825 Use this command to create individual patches for
826 each change.
827 Here is an example that that creates patch files for each
828 commit and places them in your <filename>Documents</filename>
829 directory:
830 <literallayout class='monospaced'>
831 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
832 </literallayout>
833 </para>
834 </section>
835
836 <section id='showing-a-particular-feature-or-branch-change'>
837 <title>Showing a Particular Feature or Branch Change</title>
838
839 <para>
840 Tags in the Yocto Project kernel tree divide changes for
841 significant features or branches.
842 The <filename>git show &lt;tag&gt;</filename> command shows
843 changes based on a tag.
844 Here is an example that shows <filename>systemtap</filename>
845 changes:
846 <literallayout class='monospaced'>
847 $ git show systemtap
848 </literallayout>
849 You can use the
850 <filename>git branch --contains &lt;tag&gt;</filename> command
851 to show the branches that contain a particular feature.
852 This command shows the branches that contain the
853 <filename>systemtap</filename> feature:
854 <literallayout class='monospaced'>
855 $ git branch --contains systemtap
856 </literallayout>
857 </para>
858 </section>
859 </section>
860</chapter>
861<!--
862vim: expandtab tw=80 ts=4
863-->
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
new file mode 100644
index 0000000..ac91749
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -0,0 +1,253 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='kernel-dev-concepts-appx'>
6<title>Advanced Kernel Concepts</title>
7
8 <section id='kernel-big-picture'>
9 <title>Yocto Project Kernel Development and Maintenance</title>
10 <para>
11 Kernels available through the Yocto Project, like other kernels, are based off the Linux
12 kernel releases from <ulink url='http://www.kernel.org'></ulink>.
13 At the beginning of a major development cycle, the Yocto Project team
14 chooses its kernel based on factors such as release timing, the anticipated release
15 timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
16 feature requirements.
17 Typically, the kernel chosen is in the
18 final stages of development by the community.
19 In other words, the kernel is in the release
20 candidate or "rc" phase and not yet a final release.
21 But, by being in the final stages of external development, the team knows that the
22 <filename>kernel.org</filename> final release will clearly be within the early stages of
23 the Yocto Project development window.
24 </para>
25 <para>
26 This balance allows the team to deliver the most up-to-date kernel
27 possible, while still ensuring that the team has a stable official release for
28 the baseline Linux kernel version.
29 </para>
30 <para>
31 The ultimate source for kernels available through the Yocto Project are released kernels
32 from <filename>kernel.org</filename>.
33 In addition to a foundational kernel from <filename>kernel.org</filename>, the
34 kernels available contain a mix of important new mainline
35 developments, non-mainline developments (when there is no alternative),
36 Board Support Package (BSP) developments,
37 and custom features.
38 These additions result in a commercially released Yocto Project Linux kernel that caters
39 to specific embedded designer needs for targeted hardware.
40 </para>
41 <para>
42 Once a kernel is officially released, the Yocto Project team goes into
43 their next development cycle, or upward revision (uprev) cycle, while still
44 continuing maintenance on the released kernel.
45 It is important to note that the most sustainable and stable way
46 to include feature development upstream is through a kernel uprev process.
47 Back-porting hundreds of individual fixes and minor features from various
48 kernel versions is not sustainable and can easily compromise quality.
49 </para>
50 <para>
51 During the uprev cycle, the Yocto Project team uses an ongoing analysis of
52 kernel development, BSP support, and release timing to select the best
53 possible <filename>kernel.org</filename> version.
54 The team continually monitors community kernel
55 development to look for significant features of interest.
56 The team does consider back-porting large features if they have a significant advantage.
57 User or community demand can also trigger a back-port or creation of new
58 functionality in the Yocto Project baseline kernel during the uprev cycle.
59 </para>
60 <para>
61 Generally speaking, every new kernel both adds features and introduces new bugs.
62 These consequences are the basic properties of upstream kernel development and are
63 managed by the Yocto Project team's kernel strategy.
64 It is the Yocto Project team's policy to not back-port minor features to the released kernel.
65 They only consider back-porting significant technological jumps - and, that is done
66 after a complete gap analysis.
67 The reason for this policy is that back-porting any small to medium sized change
68 from an evolving kernel can easily create mismatches, incompatibilities and very
69 subtle errors.
70 </para>
71 <para>
72 These policies result in both a stable and a cutting
73 edge kernel that mixes forward ports of existing features and significant and critical
74 new functionality.
75 Forward porting functionality in the kernels available through the Yocto Project kernel
76 can be thought of as a "micro uprev."
77 The many “micro uprevs” produce a kernel version with a mix of
78 important new mainline, non-mainline, BSP developments and feature integrations.
79 This kernel gives insight into new features and allows focused
80 amounts of testing to be done on the kernel, which prevents
81 surprises when selecting the next major uprev.
82 The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
83 feature and BSP development.
84 </para>
85 </section>
86
87 <section id='kernel-architecture'>
88 <title>Kernel Architecture</title>
89 <para>
90 This section describes the architecture of the kernels available through the
91 Yocto Project and provides information
92 on the mechanisms used to achieve that architecture.
93 </para>
94
95 <section id='architecture-overview'>
96 <title>Overview</title>
97 <para>
98 As mentioned earlier, a key goal of the Yocto Project is to present the
99 developer with
100 a kernel that has a clear and continuous history that is visible to the user.
101 The architecture and mechanisms used achieve that goal in a manner similar to the
102 upstream <filename>kernel.org</filename>.
103 </para>
104 <para>
105 You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
106 added features logically structured on top of the baseline.
107 The features are tagged and organized by way of a branching strategy implemented by the
108 source code manager (SCM) Git.
109 For information on Git as applied to the Yocto Project, see the
110 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
111 Yocto Project Development Manual.
112 </para>
113 <para>
114 The result is that the user has the ability to see the added features and
115 the commits that make up those features.
116 In addition to being able to see added features, the user can also view the history of what
117 made up the baseline kernel.
118 </para>
119 <para>
120 The following illustration shows the conceptual Yocto Project kernel.
121 </para>
122 <para>
123 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
124 </para>
125 <para>
126 In the illustration, the "Kernel.org Branch Point"
127 marks the specific spot (or release) from
128 which the Yocto Project kernel is created.
129 From this point "up" in the tree, features and differences are organized and tagged.
130 </para>
131 <para>
132 The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
133 type and BSP that is organized further up the tree.
134 Placing these common features in the
135 tree this way means features do not have to be duplicated along individual branches of the
136 structure.
137 </para>
138 <para>
139 From the Yocto Project Baseline Kernel, branch points represent specific functionality
140 for individual BSPs as well as real-time kernels.
141 The illustration represents this through three BSP-specific branches and a real-time
142 kernel branch.
143 Each branch represents some unique functionality for the BSP or a real-time kernel.
144 </para>
145 <para>
146 In this example structure, the real-time kernel branch has common features for all
147 real-time kernels and contains
148 more branches for individual BSP-specific real-time kernels.
149 The illustration shows three branches as an example.
150 Each branch points the way to specific, unique features for a respective real-time
151 kernel as they apply to a given BSP.
152 </para>
153 <para>
154 The resulting tree structure presents a clear path of markers (or branches) to the
155 developer that, for all practical purposes, is the kernel needed for any given set
156 of requirements.
157 </para>
158 </section>
159
160 <section id='branching-and-workflow'>
161 <title>Branching Strategy and Workflow</title>
162 <para>
163 The Yocto Project team creates kernel branches at points where functionality is
164 no longer shared and thus, needs to be isolated.
165 For example, board-specific incompatibilities would require different functionality
166 and would require a branch to separate the features.
167 Likewise, for specific kernel features, the same branching strategy is used.
168 </para>
169 <para>
170 This branching strategy results in a tree that has features organized to be specific
171 for particular functionality, single kernel types, or a subset of kernel types.
172 This strategy also results in not having to store the same feature twice
173 internally in the tree.
174 Rather, the kernel team stores the unique differences required to apply the
175 feature onto the kernel type in question.
176 <note>
177 The Yocto Project team strives to place features in the tree such that they can be
178 shared by all boards and kernel types where possible.
179 However, during development cycles or when large features are merged,
180 the team cannot always follow this practice.
181 In those cases, the team uses isolated branches to merge features.
182 </note>
183 </para>
184 <para>
185 BSP-specific code additions are handled in a similar manner to kernel-specific additions.
186 Some BSPs only make sense given certain kernel types.
187 So, for these types, the team creates branches off the end of that kernel type for all
188 of the BSPs that are supported on that kernel type.
189 From the perspective of the tools that create the BSP branch, the BSP is really no
190 different than a feature.
191 Consequently, the same branching strategy applies to BSPs as it does to features.
192 So again, rather than store the BSP twice, the team only stores the unique
193 differences for the BSP across the supported multiple kernels.
194 </para>
195 <para>
196 While this strategy can result in a tree with a significant number of branches, it is
197 important to realize that from the developer's point of view, there is a linear
198 path that travels from the baseline <filename>kernel.org</filename>, through a select
199 group of features and ends with their BSP-specific commits.
200 In other words, the divisions of the kernel are transparent and are not relevant
201 to the developer on a day-to-day basis.
202 From the developer's perspective, this path is the "master" branch.
203 The developer does not need to be aware of the existence of any other branches at all.
204 Of course, there is value in the existence of these branches
205 in the tree, should a person decide to explore them.
206 For example, a comparison between two BSPs at either the commit level or at the line-by-line
207 code <filename>diff</filename> level is now a trivial operation.
208 </para>
209 <para>
210 Working with the kernel as a structured tree follows recognized community best practices.
211 In particular, the kernel as shipped with the product, should be
212 considered an "upstream source" and viewed as a series of
213 historical and documented modifications (commits).
214 These modifications represent the development and stabilization done
215 by the Yocto Project kernel development team.
216 </para>
217 <para>
218 Because commits only change at significant release points in the product life cycle,
219 developers can work on a branch created
220 from the last relevant commit in the shipped Yocto Project kernel.
221 As mentioned previously, the structure is transparent to the developer
222 because the kernel tree is left in this state after cloning and building the kernel.
223 </para>
224 </section>
225
226 <section id='source-code-manager-git'>
227 <title>Source Code Manager - Git</title>
228 <para>
229 The Source Code Manager (SCM) is Git.
230 This SCM is the obvious mechanism for meeting the previously mentioned goals.
231 Not only is it the SCM for <filename>kernel.org</filename> but,
232 Git continues to grow in popularity and supports many different work flows,
233 front-ends and management techniques.
234 </para>
235 <para>
236 You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
237 You can also get an introduction to Git as it applies to the Yocto Project in the
238 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
239 section in the Yocto Project Development Manual.
240 These referenced sections overview Git and describe a minimal set of
241 commands that allows you to be functional using Git.
242 <note>
243 You can use as much, or as little, of what Git has to offer to accomplish what
244 you need for your project.
245 You do not have to be a "Git Master" in order to use it with the Yocto Project.
246 </note>
247 </para>
248 </section>
249 </section>
250</appendix>
251<!--
252vim: expandtab tw=80 ts=4
253-->
diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl
new file mode 100644
index 0000000..43e9dad
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-customization.xsl
@@ -0,0 +1,11 @@
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="html.stylesheet" select="'kernel-dev-style.css'" />
7 <xsl:param name="chapter.autolabel" select="1" />
8 <xsl:param name="appendix.autolabel">A</xsl:param>
9 <xsl:param name="section.autolabel" select="1" />
10 <xsl:param name="section.label.includes.component.label" select="1" />
11</xsl:stylesheet>
diff --git a/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl
new file mode 100644
index 0000000..7d1bb8d
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl
@@ -0,0 +1,27 @@
1<?xml version='1.0'?>
2<xsl:stylesheet
3 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4 xmlns="http://www.w3.org/1999/xhtml"
5 xmlns:fo="http://www.w3.org/1999/XSL/Format"
6 version="1.0">
7
8 <xsl:import
9 href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
10
11 <xsl:param name="chunker.output.indent" select="'yes'"/>
12 <xsl:param name="chunk.quietly" select="1"/>
13 <xsl:param name="chunk.first.sections" select="1"/>
14 <xsl:param name="chunk.section.depth" select="10"/>
15 <xsl:param name="use.id.as.filename" select="1"/>
16 <xsl:param name="ulink.target" select="'_self'" />
17 <xsl:param name="base.dir" select="'html/kernel-dev/'"/>
18 <xsl:param name="html.stylesheet" select="'../book.css'"/>
19 <xsl:param name="eclipse.manifest" select="0"/>
20 <xsl:param name="create.plugin.xml" select="0"/>
21 <xsl:param name="suppress.navigation" select="1"/>
22 <xsl:param name="generate.index" select="0"/>
23 <xsl:param name="chapter.autolabel" select="1" />
24 <xsl:param name="appendix.autolabel">A</xsl:param>
25 <xsl:param name="section.autolabel" select="1" />
26 <xsl:param name="section.label.includes.component.label" select="1" />
27</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 0000000..9d9aef6
--- /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 0000000..7389c9c
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-faq.xml
@@ -0,0 +1,131 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='kernel-dev-faq'>
6<title>Kernel Development FAQ</title>
7<qandaset>
8 <qandaentry>
9 <question>
10 <para>
11 How do I use my own Linux kernel <filename>.config</filename>
12 file?
13 </para>
14 </question>
15 <answer>
16 <para>
17 Refer to the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
18 section for information.
19 </para>
20 </answer>
21 </qandaentry>
22
23 <qandaentry>
24 <question>
25 <para>
26 How do I create configuration fragments?
27 </para>
28 </question>
29 <answer>
30 <para>
31 Refer to the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
32 section for information.
33 </para>
34 </answer>
35 </qandaentry>
36
37 <qandaentry>
38 <question>
39 <para>
40 How do I use my own Linux kernel sources?
41 </para>
42 </question>
43 <answer>
44 <para>
45 Refer to the "<link linkend='working-with-your-own-sources'>Working With Your Own Sources</link>"
46 section for information.
47 </para>
48 </answer>
49 </qandaentry>
50
51 <qandaentry>
52 <question>
53 <para>
54 How do I install/not-install the kernel image on the rootfs?
55 </para>
56 </question>
57 <answer>
58 <para>
59 The kernel image (e.g. <filename>vmlinuz</filename>) is provided
60 by the <filename>kernel-image</filename> package.
61 Image recipes depend on <filename>kernel-base</filename>.
62 To specify whether or not the kernel
63 image is installed in the generated root filesystem, override
64 <filename>RDEPENDS_kernel-base</filename> to include or not
65 include "kernel-image".</para>
66 <para>See the
67 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
68 section in the Yocto Project Development Manual for information on
69 how to use an append file to override metadata.
70 </para>
71 </answer>
72 </qandaentry>
73
74 <qandaentry>
75 <question>
76 <para>
77 How do I install a specific kernel module?
78 </para>
79 </question>
80 <answer>
81 <para>
82 Linux kernel modules are packaged individually.
83 To ensure a specific kernel module is included in an image,
84 include it in the appropriate machine
85 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
86 variable.</para>
87 <para>These other variables are useful for installing specific
88 modules:
89 <literallayout class='monospaced'>
90 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
91 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
92 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
93 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
94 </literallayout>
95 For example, set the following in the <filename>qemux86.conf</filename>
96 file to include the <filename>ab123</filename> kernel modules
97 with images built for the <filename>qemux86</filename> machine:
98 <literallayout class='monospaced'>
99 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
100 </literallayout>
101 For more information, see the
102 "<link linkend='incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</link>"
103 section.
104 </para>
105 </answer>
106 </qandaentry>
107
108 <qandaentry>
109 <question>
110 <para>
111 How do I change the Linux kernel command line?
112 </para>
113 </question>
114 <answer>
115 <para>
116 The Linux kernel command line is typically specified in
117 the machine config using the <filename>APPEND</filename> variable.
118 For example, you can add some helpful debug information doing
119 the following:
120 <literallayout class='monospaced'>
121 APPEND += "printk.time=y initcall_debug debug"
122 </literallayout>
123 </para>
124 </answer>
125 </qandaentry>
126
127</qandaset>
128</appendix>
129<!--
130vim: expandtab tw=80 ts=4
131-->
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
new file mode 100644
index 0000000..297696c
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -0,0 +1,147 @@
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-dev-intro'>
6<title>Introduction</title>
7
8<!--
9<para>
10 <emphasis>AR - Darrren Hart:</emphasis> See if the concepts in these
11 three bullets are adequately covered in somewhere in this manual:
12 <itemizedlist>
13 <listitem><para>Do we convey that our kernel Git repositories
14 have a clear and continuous history, similar to the way the
15 kernel Git repositories for <filename>kernel.org</filename>
16 do.
17 </para></listitem>
18 <listitem><para>Does the manual note that Yocto Project delivers
19 a key set of supported kernel types, where
20 each type is tailored to meet a specific use (e.g. networking,
21 consumer, devices, and so forth).</para></listitem>
22 <listitem><para>Do we convey that the Yocto Project uses a
23 Git branching strategy that, from a
24 developer's point of view, results in a linear path from the
25 baseline kernel.org, through a select group of features and
26 ends with their BSP-specific commits.</para></listitem>
27 </itemizedlist>
28</para>
29-->
30
31 <section id='kernel-dev-overview'>
32 <title>Overview</title>
33
34 <para>
35 Regardless of how you intend to make use of the Yocto Project,
36 chances are you will work with the Linux kernel.
37 This manual provides background information on the Yocto Linux kernel
38 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
39 describes common tasks you can perform using the kernel tools,
40 and shows you how to use the kernel Metadata needed to work with
41 the kernel inside the Yocto Project.
42 </para>
43
44 <para>
45 Each Yocto Project release has a set of linux-yocto recipes, whose
46 Git repositories you can view in the Yocto
47 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
48 the "Yocto Linux Kernel" heading.
49 New recipes for the release track the latest upstream developments
50 and introduce newly supported platforms.
51 Previous recipes in the release are refreshed and supported for at
52 least one additional release.
53 As they align, these previous releases are updated to include the
54 latest from the Long Term Support Initiative (LTSI) project.
55 Also included is a linux-yocto development recipe
56 (<filename>linux-yocto-dev.bb</filename>) should you want to work
57 with the very latest in upstream Linux kernel development and
58 kernel Metadata development.
59 </para>
60
61 <para>
62 The Yocto Project also provides a powerful set of kernel
63 tools for managing Linux kernel sources and configuration data.
64 You can use these tools to make a single configuration change,
65 apply multiple patches, or work with your own kernel sources.
66 </para>
67
68 <para>
69 In particular, the kernel tools allow you to generate configuration
70 fragments that specify only what you must, and nothing more.
71 Configuration fragments only need to contain the highest level
72 visible <filename>CONFIG</filename> options as presented by the Linux
73 kernel <filename>menuconfig</filename> system.
74 Contrast this against a complete Linux kernel
75 <filename>.config</filename>, which includes all the automatically
76 selected <filename>CONFIG</filename> options.
77 This efficiency reduces your maintenance effort and allows you
78 to further separate your configuration in ways that make sense for
79 your project.
80 A common split separates policy and hardware.
81 For example, all your kernels might support
82 the <filename>proc</filename> and <filename>sys</filename> filesystems,
83 but only specific boards require sound, USB, or specific drivers.
84 Specifying these configurations individually allows you to aggregate
85 them together as needed, but maintains them in only one place.
86 Similar logic applies to separating source changes.
87 </para>
88
89 <para>
90 If you do not maintain your own kernel sources and need to make
91 only minimal changes to the sources, the released recipes provide a
92 vetted base upon which to layer your changes.
93 Doing so allows you to benefit from the continual kernel
94 integration and testing performed during development of the
95 Yocto Project.
96 </para>
97
98 <para>
99 If, instead, you have a very specific Linux kernel source tree
100 and are unable to align with one of the official linux-yocto
101 recipes, an alternative exists by which you can use the Yocto
102 Project Linux kernel tools with your own kernel sources.
103 </para>
104 </section>
105
106 <section id='kernel-dev-other-resources'>
107 <title>Other Resources</title>
108
109 <para>
110 The sections that follow provide instructions for completing
111 specific Linux kernel development tasks.
112 These instructions assume you are comfortable working with
113 <ulink url='http://developer.berlios.de/projects/bitbake/'>BitBake</ulink>
114 recipes and basic open-source development tools.
115 Understanding these concepts will facilitate the process of working
116 with the kernel recipes.
117 If you find you need some additional background, please be sure to
118 review and understand the following documentation:
119 <itemizedlist>
120 <listitem><para><ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
121 </para></listitem>
122 <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-temporary-source-code'>Modifying Temporary Source Code</ulink>"
123 section in the Yocto Project Development Manual
124 </para></listitem>
125 <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section
126 in the Yocto Project Development Manual</para></listitem>
127 <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section
128 in the Yocto Project Development Manual.</para></listitem>
129 </itemizedlist>
130 </para>
131
132 <para>
133 Finally, while this document focuses on the manual creation of
134 recipes, patches, and configuration files, the Yocto Project
135 Board Support Package (BSP) tools are available to automate
136 this process with existing content and work well to create the
137 initial framework and boilerplate code.
138 For details on these tools, see the
139 "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
140 section in the Yocto Project Board Support Package (BSP) Developer's
141 Guide.
142 </para>
143 </section>
144</chapter>
145<!--
146vim: expandtab tw=80 ts=4
147-->
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml
new file mode 100644
index 0000000..a7c144f
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml
@@ -0,0 +1,220 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='kernel-dev-maint-appx'>
6<title>Kernel Maintenance</title>
7
8 <section id='tree-construction'>
9 <title>Tree Construction</title>
10 <para>
11 This section describes construction of the Yocto Project kernel source repositories
12 as accomplished by the Yocto Project team to create kernel repositories.
13 These kernel repositories are found under the heading "Yocto Linux Kernel" at
14 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
15 and can be shipped as part of a Yocto Project release.
16 The team creates these repositories by
17 compiling and executing the set of feature descriptions for every BSP
18 and feature in the product.
19 Those feature descriptions list all necessary patches,
20 configuration, branching, tagging and feature divisions found in a kernel.
21 Thus, the Yocto Project kernel repository (or tree) is built.
22 </para>
23 <para>
24 The existence of this tree allows you to access and clone a particular
25 Yocto Project kernel repository and use it to build images based on their configurations
26 and features.
27 </para>
28 <para>
29 You can find the files used to describe all the valid features and BSPs
30 in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
31 Git tree.
32 For example, the following command clones the Yocto Project baseline kernel that
33 branched off of <filename>linux.org</filename> version 3.4:
34 <literallayout class='monospaced'>
35 $ git clone git://git.yoctoproject.org/linux-yocto-3.4
36 </literallayout>
37 For another example of how to set up a local Git repository of the Yocto Project
38 kernel files, see the
39 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
40 item in the Yocto Project Development Manual.
41 </para>
42 <para>
43 Once you have cloned the kernel Git repository on your local machine, you can
44 switch to the <filename>meta</filename> branch within the repository.
45 Here is an example that assumes the local Git repository for the kernel is in
46 a top-level directory named <filename>linux-yocto-3.4</filename>:
47 <literallayout class='monospaced'>
48 $ cd linux-yocto-3.4
49 $ git checkout -b meta origin/meta
50 </literallayout>
51 Once you have checked out and switched to the <filename>meta</filename> branch,
52 you can see a snapshot of all the kernel configuration and feature descriptions that are
53 used to build that particular kernel repository.
54 These descriptions are in the form of <filename>.scc</filename> files.
55 </para>
56 <para>
57 You should realize, however, that browsing your local kernel repository
58 for feature descriptions and patches is not an effective way to determine what is in a
59 particular kernel branch.
60 Instead, you should use Git directly to discover the changes in a branch.
61 Using Git is an efficient and flexible way to inspect changes to the kernel.
62 <note>
63 Ground up reconstruction of the complete kernel tree is an action only taken by the
64 Yocto Project team during an active development cycle.
65 When you create a clone of the kernel Git repository, you are simply making it
66 efficiently available for building and development.
67 </note>
68 </para>
69 <para>
70 The following steps describe what happens when the Yocto Project Team constructs
71 the Yocto Project kernel source Git repository (or tree) found at
72 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
73 introduction of a new top-level kernel feature or BSP.
74 These are the actions that effectively create the tree
75 that includes the new feature, patch or BSP:
76 <orderedlist>
77 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
78 Normally, this feature is a BSP for a particular kernel type.</para></listitem>
79 <listitem><para>The file that describes the top-level feature is located by searching
80 these system directories:
81 <itemizedlist>
82 <listitem><para>The in-tree kernel-cache directories, which are located
83 in <filename>meta/cfg/kernel-cache</filename></para></listitem>
84 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
85 found in recipes</para></listitem>
86 </itemizedlist>
87 For a typical build, the target of the search is a
88 feature description in an <filename>.scc</filename> file
89 whose name follows this format:
90 <literallayout class='monospaced'>
91 &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
92 </literallayout>
93 </para></listitem>
94 <listitem><para>Once located, the feature description is either compiled into a simple script
95 of actions, or into an existing equivalent script that is already part of the
96 shipped kernel.</para></listitem>
97 <listitem><para>Extra features are appended to the top-level feature description.
98 These features can come from the
99 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
100 variable in recipes.</para></listitem>
101 <listitem><para>Each extra feature is located, compiled and appended to the script
102 as described in step three.</para></listitem>
103 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
104 directories.
105 These directories are descriptions of all the branches, tags, patches and configurations that
106 need to be applied to the base Git repository to completely create the
107 source (build) branch for the new BSP or feature.</para></listitem>
108 <listitem><para>The base repository is cloned, and the actions
109 listed in the <filename>meta-*</filename> directories are applied to the
110 tree.</para></listitem>
111 <listitem><para>The Git repository is left with the desired branch checked out and any
112 required branching, patching and tagging has been performed.</para></listitem>
113 </orderedlist>
114 </para>
115 <para>
116 The kernel tree is now ready for developer consumption to be locally cloned,
117 configured, and built into a Yocto Project kernel specific to some target hardware.
118 <note><para>The generated <filename>meta-*</filename> directories add to the kernel
119 as shipped with the Yocto Project release.
120 Any add-ons and configuration data are applied to the end of an existing branch.
121 The full repository generation that is found in the
122 official Yocto Project kernel repositories at
123 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
124 is the combination of all supported boards and configurations.</para>
125 <para>The technique the Yocto Project team uses is flexible and allows for seamless
126 blending of an immutable history with additional patches specific to a
127 deployment.
128 Any additions to the kernel become an integrated part of the branches.</para>
129 </note>
130 </para>
131 </section>
132
133 <section id='build-strategy'>
134 <title>Build Strategy</title>
135
136<!--
137 <para>
138 <emphasis>AR - Darrren Hart:</emphasis> Some parts of this section
139 need to be in the
140 "<link linkend='using-an-iterative-development-process'>Using an Iterative Development Process</link>"
141 section.
142 Darren needs to figure out which parts and identify them.
143 </para>
144-->
145
146 <para>
147 Once a local Git repository of the Yocto Project kernel exists on a development system,
148 you can consider the compilation phase of kernel development - building a kernel image.
149 Some prerequisites exist that are validated by the build process before compilation
150 starts:
151 </para>
152
153 <itemizedlist>
154 <listitem><para>The
155 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
156 to the kernel Git repository.</para></listitem>
157 <listitem><para>A BSP build branch exists.
158 This branch has the following form:
159 <literallayout class='monospaced'>
160 &lt;kernel_type&gt;/&lt;bsp_name&gt;
161 </literallayout></para></listitem>
162 </itemizedlist>
163
164 <para>
165 The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
166 Other means, however, do exist, such as as bootstrapping a BSP.
167 </para>
168
169 <para>
170 Before building a kernel, the build process verifies the tree
171 and configures the kernel by processing all of the
172 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
173 files.
174 As the features are compiled, associated kernel configuration fragments are noted
175 and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
176 The fragments are migrated, pre-processed and passed to the Linux Kernel
177 Configuration subsystem (<filename>lkc</filename>) as raw input in the form
178 of a <filename>.config</filename> file.
179 The <filename>lkc</filename> uses its own internal dependency constraints to do the final
180 processing of that information and generates the final <filename>.config</filename> file
181 that is used during compilation.
182 </para>
183
184 <para>
185 Using the board's architecture and other relevant values from the board's template,
186 kernel compilation is started and a kernel image is produced.
187 </para>
188
189 <para>
190 The other thing that you notice once you configure a kernel is that
191 the build process generates a build tree that is separate from your kernel's local Git
192 source repository tree.
193 This build tree has a name that uses the following form, where
194 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
195 of the Yocto Project supported kernel types (e.g. "standard"):
196 <literallayout class='monospaced'>
197 linux-${MACHINE}-&lt;kernel_type&gt;-build
198 </literallayout>
199 </para>
200
201 <para>
202 The existing support in the <filename>kernel.org</filename> tree achieves this
203 default functionality.
204 </para>
205
206 <para>
207 This behavior means that all the generated files for a particular machine or BSP are now in
208 the build tree directory.
209 The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
210 files, the <filename>.a</filename> files, and so forth.
211 Since each machine or BSP has its own separate
212 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
213 in its own separate branch
214 of the Git repository, you can easily switch between different builds.
215 </para>
216 </section>
217</appendix>
218<!--
219vim: expandtab tw=80 ts=4
220-->
diff --git a/documentation/kernel-dev/kernel-dev-style.css b/documentation/kernel-dev/kernel-dev-style.css
new file mode 100644
index 0000000..52be143
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-style.css
@@ -0,0 +1,978 @@
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-dev-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}
diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml
new file mode 100644
index 0000000..f4cddba
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev.xml
@@ -0,0 +1,95 @@
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-dev' 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-dev-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title>
20 Yocto Project Linux Kernel Development Manual
21 </title>
22
23 <authorgroup>
24 <author>
25 <firstname>Darren</firstname> <surname>Hart</surname>
26 <affiliation>
27 <orgname>Intel Corporation</orgname>
28 </affiliation>
29 <email>darren.hart@intel.com</email>
30 </author>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>1.4</revnumber>
36 <date>April 2013</date>
37 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
38 </revision>
39 <revision>
40 <revnumber>1.5</revnumber>
41 <date>October 2013</date>
42 <revremark>Released with the Yocto Project 1.5 Release.</revremark>
43 </revision>
44 <revision>
45 <revnumber>1.5.1</revnumber>
46 <date>Sometime in 2013</date>
47 <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
48 </revision>
49 </revhistory>
50
51 <copyright>
52 <year>&COPYRIGHT_YEAR;</year>
53 <holder>Linux Foundation</holder>
54 </copyright>
55
56 <legalnotice>
57 <para>
58 Permission is granted to copy, distribute and/or modify this document under
59 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.
60 </para>
61 <note>
62 For the latest version of this manual associated with this
63 Yocto Project release, see the
64 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>
65 from the Yocto Project website.
66 </note>
67 </legalnotice>
68
69 </bookinfo>
70
71 <xi:include href="kernel-dev-intro.xml"/>
72
73 <xi:include href="kernel-dev-common.xml"/>
74
75 <xi:include href="kernel-dev-advanced.xml"/>
76
77 <xi:include href="kernel-dev-concepts-appx.xml"/>
78
79 <xi:include href="kernel-dev-maint-appx.xml"/>
80
81<!--
82 <xi:include href="kernel-dev-examples.xml"/>
83-->
84
85 <xi:include href="kernel-dev-faq.xml"/>
86
87<!-- <index id='index'>
88 <title>Index</title>
89 </index>
90-->
91
92</book>
93<!--
94vim: expandtab tw=80 ts=4
95-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 06:11:06 +0000