summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
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.xml1073
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml858
-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.xml105
13 files changed, 4721 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..4a6aeb7
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -0,0 +1,1073 @@
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
51 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
52 (e.g. "edgerouter" or "fri2").
53 Multiple BSPs can reuse the same <filename>KMACHINE</filename>
54 name if they are built using the same BSP description.
55 The "fri2" and "fri2-noemgd" BSP combination
56 in the <filename>meta-intel</filename>
57 layer is a good example of two BSPs using the same
58 <filename>KMACHINE</filename> value (i.e. "fri2").
59 See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section
60 for more information.
61 </para>
62
63 <para>
64 The linux-yocto style recipes can optionally define the following
65 variables:
66 <literallayout class='monospaced'>
67 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'>KBRANCH</ulink>
68 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink>
69 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH_DEFAULT'>KBRANCH_DEFAULT</ulink>
70 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink>
71 </literallayout>
72 <filename>KBRANCH_DEFAULT</filename> defines the Linux kernel source
73 repository's default branch to use to build the Linux kernel.
74 The value is used as the default for <filename>KBRANCH</filename>, which
75 can define an alternate branch typically with a machine override as
76 follows:
77 <literallayout class='monospaced'>
78 KBRANCH_fri2 = "standard/fri2"
79 </literallayout>
80 Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename>
81 initializes to "master".
82 </para>
83
84 <para>
85 <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be
86 used in assembling the configuration.
87 If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
88 it defaults to "standard".
89 Together with
90 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
91 <filename>LINUX_KERNEL_TYPE</filename> defines the search
92 arguments used by the kernel tools to find the
93 appropriate description within the kernel Metadata with which to
94 build out the sources and configuration.
95 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
96 kernel types.
97 See the <link linkend='kernel-types'>Kernel Types</link> section
98 for more information on kernel types.
99 </para>
100
101 <para>
102 During the build, the kern-tools search for the BSP description
103 file that most closely matches the <filename>KMACHINE</filename>
104 and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the
105 recipe.
106 The tools use the first BSP description it finds that match
107 both variables.
108 If the tools cannot find a match, they issue a warning such as
109 the following:
110 <literallayout class='monospaced'>
111 WARNING: Can't find any BSP hardware or required configuration fragments.
112 WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and
113 meta/cfg/broken/fri2-broken/required_frags.txt in directory:
114 meta/cfg/broken/fri2-broken
115 </literallayout>
116 In this example, <filename>KMACHINE</filename> was set to "fri2-broken"
117 and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken".
118 </para>
119
120 <para>
121 The tools first search for the <filename>KMACHINE</filename> and
122 then for the <filename>LINUX_KERNEL_TYPE</filename>.
123 If the tools cannot find a partial match, they will use the
124 sources from the <filename>KBRANCH</filename> and any configuration
125 specified in the
126 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
127 </para>
128
129 <para>
130 You can use the <filename>KERNEL_FEATURES</filename> variable
131 to include features (configuration fragments, patches, or both) that
132 are not already included by the <filename>KMACHINE</filename> and
133 <filename>LINUX_KERNEL_TYPE</filename> variable combination.
134 For example, to include a feature specified as "features/netfilter.scc",
135 specify:
136 <literallayout class='monospaced'>
137 KERNEL_FEATURES += "features/netfilter.scc"
138 </literallayout>
139 To include a feature called "cfg/sound.scc" just for the
140 <filename>qemux86</filename> machine, specify:
141 <literallayout class='monospaced'>
142 KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"
143 </literallayout>
144 The value of the entries in <filename>KERNEL_FEATURES</filename>
145 are dependent on their location within the kernel Metadata itself.
146 The examples here are taken from the
147 <filename>linux-yocto-3.4</filename> repository where "features"
148 and "cfg" are subdirectories within the
149 <filename>meta/cfg/kernel-cache</filename> directory.
150 For more information, see the
151 "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section.
152 <note>
153 The processing of the these variables has evolved some between the
154 0.9 and 1.3 releases of the Yocto Project and associated
155 kern-tools sources.
156 The descriptions in this section are accurate for 1.3 and later
157 releases of the Yocto Project.
158 </note>
159 </para>
160</section>
161
162<section id='kernel-metadata-location'>
163 <title>Kernel Metadata Location</title>
164
165 <para>
166 Kernel Metadata can be defined in either the kernel recipe
167 (recipe-space) or in the kernel tree (in-tree).
168 Where you choose to define the Metadata depends on what you want
169 to do and how you intend to work.
170 Regardless of where you define the kernel Metadata, the syntax used
171 applies equally.
172 </para>
173
174 <para>
175 If you are unfamiliar with the Linux kernel and only wish
176 to apply a configuration and possibly a couple of patches provided to
177 you by others, the recipe-space method is recommended.
178 This method is also a good approach if you are working with Linux kernel
179 sources you do not control or if you just do not want to maintain a
180 Linux kernel Git repository on your own.
181 For partial information on how you can define kernel Metadata in
182 the recipe-space, see the
183 "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
184 section.
185 </para>
186
187 <para>
188 Conversely, if you are actively developing a kernel and are already
189 maintaining a Linux kernel Git repository of your own, you might find
190 it more convenient to work with the kernel Metadata in the same
191 repository as the Linux kernel sources.
192 This method can make iterative development of the Linux kernel
193 more efficient outside of the BitBake environment.
194 </para>
195
196 <section id='recipe-space-metadata'>
197 <title>Recipe-Space Metadata</title>
198
199 <para>
200 When stored in recipe-space, the kernel Metadata files reside in a
201 directory hierarchy below
202 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
203 For a linux-yocto recipe or for a Linux kernel recipe derived
204 by copying and modifying
205 <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
206 to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
207 is typically set to
208 <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>.
209 See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
210 section for more information.
211 </para>
212
213 <para>
214 Here is an example that shows a trivial tree of kernel Metadata
215 stored in recipe-space within a BSP layer:
216 <literallayout class='monospaced'>
217 meta-my_bsp_layer/
218 `-- recipes-kernel
219 `-- linux
220 `-- linux-yocto
221 |-- bsp-standard.scc
222 |-- bsp.cfg
223 `-- standard.cfg
224 </literallayout>
225 </para>
226
227 <para>
228 When the Metadata is stored in recipe-space, you must take
229 steps to ensure BitBake has the necessary information to decide
230 what files to fetch and when they need to be fetched again.
231 It is only necessary to specify the <filename>.scc</filename>
232 files on the
233 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
234 BitBake parses them and fetches any files referenced in the
235 <filename>.scc</filename> files by the <filename>include</filename>,
236 <filename>patch</filename>, or <filename>kconf</filename> commands.
237 Because of this, it is necessary to bump the recipe
238 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
239 value when changing the content of files not explicitly listed
240 in the <filename>SRC_URI</filename>.
241 </para>
242 </section>
243
244 <section id='in-tree-metadata'>
245 <title>In-Tree Metadata</title>
246
247 <para>
248 When stored in-tree, the kernel Metadata files reside in the
249 <filename>meta</filename> directory of the Linux kernel sources.
250 The <filename>meta</filename> directory can be present in the
251 same repository branch as the sources,
252 such as "master", or <filename>meta</filename> can be its own
253 orphan branch.
254 <note>
255 An orphan branch in Git is a branch with unique history and
256 content to the other branches in the repository.
257 Orphan branches are useful to track Metadata changes
258 independently from the sources of the Linux kernel, while
259 still keeping them together in the same repository.
260 </note>
261 For the purposes of this document, we will discuss all
262 in-tree Metadata as residing below the
263 <filename>meta/cfg/kernel-cache</filename> directory.
264 </para>
265
266 <para>
267 Following is an example that shows how a trivial tree of Metadata
268 is stored in a custom Linux kernel Git repository:
269 <literallayout class='monospaced'>
270 meta/
271 `-- cfg
272 `-- kernel-cache
273 |-- bsp-standard.scc
274 |-- bsp.cfg
275 `-- standard.cfg
276 </literallayout>
277 </para>
278
279 <para>
280 To use a branch different from where the sources reside,
281 specify the branch in the <filename>KMETA</filename> variable
282 in your Linux kernel recipe.
283 Here is an example:
284 <literallayout class='monospaced'>
285 KMETA = "meta"
286 </literallayout>
287 To use the same branch as the sources, set
288 <filename>KMETA</filename> to an empty string:
289 <literallayout class='monospaced'>
290 KMETA = ""
291 </literallayout>
292 If you are working with your own sources and want to create an
293 orphan <filename>meta</filename> branch, use these commands
294 from within your Linux kernel Git repository:
295 <literallayout class='monospaced'>
296 $ git checkout --orphan meta
297 $ git rm -rf .
298 $ git commit --allow-empty -m "Create orphan meta branch"
299 </literallayout>
300 </para>
301
302 <para>
303 If you modify the Metadata in the linux-yocto
304 <filename>meta</filename> branch, you must not forget to update
305 the
306 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
307 statements in the kernel's recipe.
308 In particular, you need to update the
309 <filename>SRCREV_meta</filename> variable to match the commit in
310 the <filename>KMETA</filename> branch you wish to use.
311 Changing the data in these branches and not updating the
312 <filename>SRCREV</filename> statements to match will cause the
313 build to fetch an older commit.
314 </para>
315 </section>
316</section>
317
318<section id='kernel-metadata-syntax'>
319 <title>Kernel Metadata Syntax</title>
320
321 <para>
322 The kernel Metadata consists of three primary types of files:
323 <filename>scc</filename>
324 <footnote>
325 <para>
326 <filename>scc</filename> stands for Series Configuration
327 Control, but the naming has less significance in the
328 current implementation of the tooling than it had in the
329 past.
330 Consider <filename>scc</filename> files to be description files.
331 </para>
332 </footnote>
333 description files, configuration fragments, and patches.
334 The <filename>scc</filename> files define variables and include or
335 otherwise reference any of the three file types.
336 The description files are used to aggregate all types of kernel
337 Metadata into
338 what ultimately describes the sources and the configuration required
339 to build a Linux kernel tailored to a specific machine.
340 </para>
341
342 <para>
343 The <filename>scc</filename> description files are used to define two
344 fundamental types of kernel Metadata:
345 <itemizedlist>
346 <listitem><para>Features</para></listitem>
347 <listitem><para>Board Support Packages (BSPs)</para></listitem>
348 </itemizedlist>
349 </para>
350
351 <para>
352 Features aggregate sources in the form of patches and configuration
353 fragments into a modular reusable unit.
354 You can use features to implement conceptually separate kernel
355 Metadata descriptions such as pure configuration fragments,
356 simple patches, complex features, and kernel types.
357 <link linkend='kernel-types'>Kernel types</link> define general
358 kernel features and policy to be reused in the BSPs.
359 </para>
360
361 <para>
362 BSPs define hardware-specific features and aggregate them with kernel
363 types to form the final description of what will be assembled and built.
364 </para>
365
366 <para>
367 While the kernel Metadata syntax does not enforce any logical
368 separation of configuration fragments, patches, features or kernel
369 types, best practices dictate a logical separation of these types
370 of Metadata.
371 The following Metadata file hierarchy is recommended:
372 <literallayout class='monospaced'>
373 &lt;base&gt;/
374 bsp/
375 cfg/
376 features/
377 ktypes/
378 patches/
379 </literallayout>
380 </para>
381
382 <para>
383 The <filename>bsp</filename> directory contains the
384 <link linkend='bsp-descriptions'>BSP descriptions</link>.
385 The remaining directories all contain "features".
386 Separating <filename>bsp</filename> from the rest of the structure
387 aids conceptualizing intended usage.
388 </para>
389
390 <para>
391 Use these guidelines to help place your <filename>scc</filename>
392 description files within the structure:
393 <itemizedlist>
394 <listitem><para>If your file contains
395 only configuration fragments, place the file in the
396 <filename>cfg</filename> directory.</para></listitem>
397 <listitem><para>If your file contains
398 only source-code fixes, place the file in the
399 <filename>patches</filename> directory.</para></listitem>
400 <listitem><para>If your file encapsulates
401 a major feature, often combining sources and configurations,
402 place the file in <filename>features</filename> directory.
403 </para></listitem>
404 <listitem><para>If your file aggregates
405 non-hardware configuration and patches in order to define a
406 base kernel policy or major kernel type to be reused across
407 multiple BSPs, place the file in <filename>ktypes</filename>
408 directory.
409 </para></listitem>
410 </itemizedlist>
411 </para>
412
413 <para>
414 These distinctions can easily become blurred - especially as
415 out-of-tree features slowly merge upstream over time.
416 Also, remember that how the description files are placed is
417 a purely logical organization and has no impact on the functionality
418 of the kernel Metadata.
419 There is no impact because all of <filename>cfg</filename>,
420 <filename>features</filename>, <filename>patches</filename>, and
421 <filename>ktypes</filename>, contain "features" as far as the kernel
422 tools are concerned.
423 </para>
424
425 <para>
426 Paths used in kernel Metadata files are relative to
427 <filename>&lt;base&gt;</filename>, which is either
428 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
429 if you are creating Metadata in
430 <link linkend='recipe-space-metadata'>recipe-space</link>,
431 or <filename>meta/cfg/kernel-cache/</filename> if you are creating
432 Metadata <link linkend='in-tree-metadata'>in-tree</link>.
433 </para>
434
435 <section id='configuration'>
436 <title>Configuration</title>
437
438 <para>
439 The simplest unit of kernel Metadata is the configuration-only
440 feature.
441 This feature consists of one or more Linux kernel configuration
442 parameters in a configuration fragment file
443 (<filename>.cfg</filename>) and an <filename>.scc</filename> file
444 that describes the fragment.
445 </para>
446
447 <para>
448 The Symmetric Multi-Processing (SMP) fragment included in the
449 <filename>linux-yocto-3.4</filename> Git repository
450 consists of the following two files:
451 <literallayout class='monospaced'>
452 cfg/smp.scc:
453 define KFEATURE_DESCRIPTION "Enable SMP"
454 kconf hardware smp.cfg
455
456 cfg/smp.cfg:
457 CONFIG_SMP=y
458 CONFIG_SCHED_SMT=y
459 </literallayout>
460 You can find information on configuration fragment files in the
461 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
462 section of the Yocto Project Development Manual and in
463 the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
464 section earlier in this manual.
465 </para>
466
467 <para>
468 <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>
469 provides a short description of the fragment.
470 Higher level kernel tools use this description.
471 </para>
472
473 <para>
474 The <filename>kconf</filename> command is used to include the
475 actual configuration fragment in an <filename>.scc</filename>
476 file, and the "hardware" keyword identifies the fragment as
477 being hardware enabling, as opposed to general policy,
478 which would use the "non-hardware" keyword.
479 The distinction is made for the benefit of the configuration
480 validation tools, which warn you if a hardware fragment
481 overrides a policy set by a non-hardware fragment.
482 <note>
483 The description file can include multiple
484 <filename>kconf</filename> statements, one per fragment.
485 </note>
486 </para>
487
488 <para>
489 As described in the
490 "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
491 section, you can use the following BitBake command to audit your
492 configuration:
493 <literallayout class='monospaced'>
494 $ bitbake linux-yocto -c kernel_configcheck -f
495 </literallayout>
496 </para>
497 </section>
498
499 <section id='patches'>
500 <title>Patches</title>
501
502 <para>
503 Patch descriptions are very similar to configuration fragment
504 descriptions, which are described in the previous section.
505 However, instead of a <filename>.cfg</filename> file, these
506 descriptions work with source patches.
507 </para>
508
509 <para>
510 A typical patch includes a description file and the patch itself:
511 <literallayout class='monospaced'>
512 patches/mypatch.scc:
513 patch mypatch.patch
514
515 patches/mypatch.patch:
516 &lt;typical-patch&gt;
517 </literallayout>
518 You can create the typical <filename>.patch</filename>
519 file using <filename>diff -Nurp</filename> or
520 <filename>git format-patch</filename>.
521 </para>
522
523 <para>
524 The description file can include multiple patch statements,
525 one per patch.
526 </para>
527 </section>
528
529 <section id='features'>
530 <title>Features</title>
531
532 <para>
533 Features are complex kernel Metadata types that consist
534 of configuration fragments (<filename>kconf</filename>), patches
535 (<filename>patch</filename>), and possibly other feature
536 description files (<filename>include</filename>).
537 </para>
538
539 <para>
540 Here is an example that shows a feature description file:
541 <literallayout class='monospaced'>
542 features/myfeature.scc
543 define KFEATURE_DESCRIPTION "Enable myfeature"
544
545 patch 0001-myfeature-core.patch
546 patch 0002-myfeature-interface.patch
547
548 include cfg/myfeature_dependency.scc
549 kconf non-hardware myfeature.cfg
550 </literallayout>
551 This example shows how the <filename>patch</filename> and
552 <filename>kconf</filename> commands are used as well as
553 how an additional feature description file is included.
554 </para>
555
556 <para>
557 Typically, features are less granular than configuration
558 fragments and are more likely than configuration fragments
559 and patches to be the types of things you want to specify
560 in the <filename>KERNEL_FEATURES</filename> variable of the
561 Linux kernel recipe.
562 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
563 section earlier in the manual.
564 </para>
565 </section>
566
567 <section id='kernel-types'>
568 <title>Kernel Types</title>
569
570 <para>
571 A kernel type defines a high-level kernel policy by
572 aggregating non-hardware configuration fragments with
573 patches you want to use when building a Linux kernels of a
574 specific type.
575 Syntactically, kernel types are no different than features
576 as described in the "<link linkend='features'>Features</link>"
577 section.
578 The <filename>LINUX_KERNEL_TYPE</filename> variable in the kernel
579 recipe selects the kernel type.
580 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
581 section for more information.
582 </para>
583
584 <para>
585 As an example, the <filename>linux-yocto-3.4</filename>
586 tree defines three kernel types: "standard",
587 "tiny", and "preempt-rt":
588 <itemizedlist>
589 <listitem><para>"standard":
590 Includes the generic Linux kernel policy of the Yocto
591 Project linux-yocto kernel recipes.
592 This policy includes, among other things, which file
593 systems, networking options, core kernel features, and
594 debugging and tracing options are supported.
595 </para></listitem>
596 <listitem><para>"preempt-rt":
597 Applies the <filename>PREEMPT_RT</filename>
598 patches and the configuration options required to
599 build a real-time Linux kernel.
600 This kernel type inherits from the "standard" kernel type.
601 </para></listitem>
602 <listitem><para>"tiny":
603 Defines a bare minimum configuration meant to serve as a
604 base for very small Linux kernels.
605 The "tiny" kernel type is independent from the "standard"
606 configuration.
607 Although the "tiny" kernel type does not currently include
608 any source changes, it might in the future.
609 </para></listitem>
610 </itemizedlist>
611 </para>
612
613 <para>
614 The "standard" kernel type is defined by
615 <filename>standard.scc</filename>:
616 <literallayout class='monospaced'>
617 # Include this kernel type fragment to get the standard features and
618 # configuration values.
619
620 # Include all standard features
621 include standard-nocfg.scc
622
623 kconf non-hardware standard.cfg
624
625 # individual cfg block section
626 include cfg/fs/devtmpfs.scc
627 include cfg/fs/debugfs.scc
628 include cfg/fs/btrfs.scc
629 include cfg/fs/ext2.scc
630 include cfg/fs/ext3.scc
631 include cfg/fs/ext4.scc
632
633 include cfg/net/ipv6.scc
634 include cfg/net/ip_nf.scc
635 include cfg/net/ip6_nf.scc
636 include cfg/net/bridge.scc
637 </literallayout>
638 </para>
639
640 <para>
641 As with any <filename>.scc</filename> file, a
642 kernel type definition can aggregate other
643 <filename>.scc</filename> files with
644 <filename>include</filename> commands.
645 These definitions can also directly pull in
646 configuration fragments and patches with the
647 <filename>kconf</filename> and <filename>patch</filename>
648 commands, respectively.
649 </para>
650
651 <note>
652 It is not strictly necessary to create a kernel type
653 <filename>.scc</filename> file.
654 The Board Support Package (BSP) file can implicitly define
655 the kernel type using a <filename>define
656 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename>
657 line.
658 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
659 section for more information.
660 </note>
661 </section>
662
663 <section id='bsp-descriptions'>
664 <title>BSP Descriptions</title>
665
666 <para>
667 BSP descriptions combine kernel types with hardware-specific
668 features.
669 The hardware-specific portion is typically defined
670 independently, and then aggregated with each supported kernel
671 type.
672 Consider this simple BSP description that supports the "mybsp"
673 machine:
674 <literallayout class='monospaced'>
675 mybsp.scc:
676 define KMACHINE mybsp
677 define KTYPE standard
678 define KARCH i386
679
680 kconf mybsp.cfg
681 </literallayout>
682 Every BSP description should define the
683 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
684 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
685 and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
686 variables.
687 These variables allow the OpenEmbedded build system to identify
688 the description as meeting the criteria set by the recipe being
689 built.
690 This simple example supports the "mybsp" machine for the "standard"
691 kernel and the "i386" architecture.
692 </para>
693
694 <para>
695 Be aware that a hard link between the
696 <filename>KTYPE</filename> variable and a kernel type
697 description file does not exist.
698 Thus, if you do not have kernel types defined in your kernel
699 Metadata, you only need to ensure that the kernel recipe's
700 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
701 variable and the <filename>KTYPE</filename> variable in the
702 BSP description file match.
703 <note>
704 Future versions of the tooling make the specification of
705 <filename>KTYPE</filename> in the BSP optional.
706 </note>
707 </para>
708
709 <para>
710 If you did want to separate your kernel policy from your
711 hardware configuration, you could do so by specifying a kernel
712 type, such as "standard" and including that description file
713 in the BSP description file.
714 See the "<link linkend='kernel-types'>Kernel Types</link>" section
715 for more information.
716 </para>
717
718 <para>
719 You might also have multiple hardware configurations that you
720 aggregate into a single hardware description file that you
721 could include in the BSP description file, rather than referencing
722 a single <filename>.cfg</filename> file.
723 Consider the following:
724 <literallayout class='monospaced'>
725 mybsp.scc:
726 define KMACHINE mybsp
727 define KTYPE standard
728 define KARCH i386
729
730 include standard.scc
731 include mybsp-hw.scc
732 </literallayout>
733 </para>
734
735 <para>
736 In the above example, <filename>standard.scc</filename>
737 aggregates all the configuration fragments, patches, and
738 features that make up your standard kernel policy whereas
739 <filename>mybsp-hw.scc</filename> aggregates all those necessary
740 to support the hardware available on the "mybsp" machine.
741 For information on how to break a complete
742 <filename>.config</filename> file into the various
743 configuration fragments, see the
744 "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
745 section.
746 </para>
747
748 <para>
749 Many real-world examples are more complex.
750 Like any other <filename>.scc</filename> file, BSP
751 descriptions can aggregate features.
752 Consider the Fish River Island 2 (fri2)
753 BSP definition from the <filename>linux-yocto-3.4</filename>
754 Git repository:
755 <literallayout class='monospaced'>
756 fri2.scc:
757 kconf hardware fri2.cfg
758
759 include cfg/x86.scc
760 include features/eg20t/eg20t.scc
761 include cfg/dmaengine.scc
762 include features/ericsson-3g/f5521gw.scc
763 include features/power/intel.scc
764 include cfg/efi.scc
765 include features/usb/ehci-hcd.scc
766 include features/usb/ohci-hcd.scc
767 include features/iwlwifi/iwlwifi.scc
768 </literallayout>
769 </para>
770
771 <para>
772 The <filename>fri2.scc</filename> description file includes
773 a hardware configuration fragment
774 (<filename>fri2.cfg</filename>) specific to the Fish River
775 Island 2 BSP as well as several more general configuration
776 fragments and features enabling hardware found on the
777 machine.
778 This description file is then included in each of the three
779 "fri2" description files for the supported kernel types
780 (i.e. "standard", "preempt-rt", and "tiny").
781 Consider the "fri2" description for the "standard" kernel
782 type:
783 <literallayout class='monospaced'>
784 fri2-standard.scc:
785 define KMACHINE fri2
786 define KTYPE standard
787 define KARCH i386
788
789 include ktypes/standard/standard.scc
790 branch fri2
791
792 git merge emgd-1.14
793
794 include fri2.scc
795
796 # Extra fri2 configs above the minimal defined in fri2.scc
797 include cfg/efi-ext.scc
798 include features/drm-emgd/drm-emgd.scc
799 include cfg/vesafb.scc
800
801 # default policy for standard kernels
802 include cfg/usb-mass-storage.scc
803 </literallayout>
804 The <filename>include</filename> command midway through the file
805 includes the <filename>fri2.scc</filename> description that
806 defines all hardware enablements for the BSP that is common to all
807 kernel types.
808 Using this command significantly reduces duplication.
809 </para>
810
811 <para>
812 This "fri2" standard description introduces a few more variables
813 and commands that are worth further discussion.
814 Notice the <filename>branch fri2</filename> command, which creates
815 a machine-specific branch into which source changes are applied.
816 With this branch set up, the <filename>git merge</filename> command
817 uses Git to merge in a feature branch named "emgd-1.14".
818 You could also handle this with the <filename>patch</filename>
819 command.
820 However, for commonly used features such as this, feature branches
821 are a convenient mechanism.
822 See the "<link linkend='feature-branches'>Feature Branches</link>"
823 section for more information.
824 </para>
825
826 <para>
827 Now consider the "fri2" description for the "tiny" kernel type:
828 <literallayout class='monospaced'>
829 fri2-tiny.scc:
830 define KMACHINE fri2
831 define KTYPE tiny
832 define KARCH i386
833
834 include ktypes/tiny/tiny.scc
835 branch fri2
836
837 include fri2.scc
838 </literallayout>
839 As you might expect, the "tiny" description includes quite a
840 bit less.
841 In fact, it includes only the minimal policy defined by the
842 "tiny" kernel type and the hardware-specific configuration required
843 for booting the machine along with the most basic functionality of
844 the system as defined in the base "fri2" description file.
845 </para>
846
847 <para>
848 Notice again the three critical variables:
849 <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
850 and <filename>KARCH</filename>.
851 Of these variables, only the <filename>KTYPE</filename> has changed.
852 It is now set to "tiny".
853 </para>
854 </section>
855</section>
856
857<section id='organizing-your-source'>
858 <title>Organizing Your Source</title>
859
860 <para>
861 Many recipes based on the <filename>linux-yocto-custom.bb</filename>
862 recipe use Linux kernel sources that have only a single
863 branch - "master".
864 This type of repository structure is fine for linear development
865 supporting a single machine and architecture.
866 However, if you work with multiple boards and architectures,
867 a kernel source repository with multiple branches is more
868 efficient.
869 For example, suppose you need a series of patches for one board to boot.
870 Sometimes, these patches are works-in-progress or fundamentally wrong,
871 yet they are still necessary for specific boards.
872 In these situations, you most likely do not want to include these
873 patches in every kernel you build (i.e. have the patches as part of
874 the lone "master" branch).
875 It is situations like these that give rise to multiple branches used
876 within a Linux kernel sources Git repository.
877 </para>
878
879 <para>
880 Repository organization strategies exist that maximize source reuse,
881 remove redundancy, and logically order your changes.
882 This section presents strategies for the following cases:
883 <itemizedlist>
884 <listitem><para>Encapsulating patches in a feature description
885 and only including the patches in the BSP descriptions of
886 the applicable boards.</para></listitem>
887 <listitem><para>Creating a machine branch in your
888 kernel source repository and applying the patches on that
889 branch only.</para></listitem>
890 <listitem><para>Creating a feature branch in your
891 kernel source repository and merging that branch into your
892 BSP when needed.</para></listitem>
893 </itemizedlist>
894 </para>
895
896 <para>
897 The approach you take is entirely up to you
898 and depends on what works best for your development model.
899 </para>
900
901 <section id='encapsulating-patches'>
902 <title>Encapsulating Patches</title>
903
904 <para>
905 if you are reusing patches from an external tree and are not
906 working on the patches, you might find the encapsulated feature
907 to be appropriate.
908 Given this scenario, you do not need to create any branches in the
909 source repository.
910 Rather, you just take the static patches you need and encapsulate
911 them within a feature description.
912 Once you have the feature description, you simply include that into
913 the BSP description as described in the
914 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
915 section.
916 </para>
917
918 <para>
919 You can find information on how to create patches and BSP
920 descriptions in the "<link linkend='patches'>Patches</link>" and
921 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
922 sections.
923 </para>
924 </section>
925
926 <section id='machine-branches'>
927 <title>Machine Branches</title>
928
929 <para>
930 When you have multiple machines and architectures to support,
931 or you are actively working on board support, it is more
932 efficient to create branches in the repository based on
933 individual machines.
934 Having machine branches allows common source to remain in the
935 "master" branch with any features specific to a machine stored
936 in the appropriate machine branch.
937 This organization method frees you from continually reintegrating
938 your patches into a feature.
939 </para>
940
941 <para>
942 Once you have a new branch, you can set up your kernel Metadata
943 to use the branch a couple different ways.
944 In the recipe, you can specify the new branch as the
945 <filename>KBRANCH</filename> to use for the board as
946 follows:
947 <literallayout class='monospaced'>
948 KBRANCH = "mynewbranch"
949 </literallayout>
950 Another method is to use the <filename>branch</filename> command
951 in the BSP description:
952 <literallayout class='monospaced'>
953 mybsp.scc:
954 define KMACHINE mybsp
955 define KTYPE standard
956 define KARCH i386
957 include standard.scc
958
959 branch mynewbranch
960
961 include mybsp-hw.scc
962 </literallayout>
963 </para>
964
965 <para>
966 If you find
967 yourself with numerous branches, you might consider using a
968 hierarchical branching system similar to what the linux-yocto Linux
969 kernel repositories use:
970 <literallayout class='monospaced'>
971 &lt;common&gt;/&lt;kernel_type&gt;/&lt;machine&gt;
972 </literallayout>
973 </para>
974
975 <para>
976 If you had two kernel types, "standard" and "small" for
977 instance, and three machines, the branches in your
978 Git repository might look like this:
979 <literallayout class='monospaced'>
980 common/base
981 common/standard/base
982 common/standard/machine_a
983 common/standard/machine_b
984 common/standard/machine_c
985 common/small/base
986 common/small/machine_a
987 </literallayout>
988 </para>
989
990 <para>
991 This organization can help clarify the branch relationships.
992 In this case, <filename>common/standard/machine_a</filename>
993 includes everything in <filename>common/base</filename> and
994 <filename>common/standard/base</filename>.
995 The "standard" and "small" branches add sources specific to those
996 kernel types that for whatever reason are not appropriate for the
997 other branches.
998 <note>The "base" branches are an artifact of the way Git manages
999 its data internally on the filesystem: Git will not allow you
1000 to use <filename>common/standard</filename> and
1001 <filename>common/standard/machine_a</filename> because it
1002 would have to create a file and a directory named "standard".
1003 </note>
1004 </para>
1005 </section>
1006
1007 <section id='feature-branches'>
1008 <title>Feature Branches</title>
1009
1010 <para>
1011 When you are actively developing new features, it can be more
1012 efficient to work with that feature as a branch, rather than
1013 as a set of patches that have to be regularly updated.
1014 The Yocto Project Linux kernel tools provide for this with
1015 the <filename>git merge</filename> command.
1016 </para>
1017
1018 <para>
1019 To merge a feature branch into a BSP, insert the
1020 <filename>git merge</filename> command after any
1021 <filename>branch</filename> commands:
1022 <literallayout class='monospaced'>
1023 mybsp.scc:
1024 define KMACHINE mybsp
1025 define KTYPE standard
1026 define KARCH i386
1027 include standard.scc
1028
1029 branch mynewbranch
1030 git merge myfeature
1031
1032 include mybsp-hw.scc
1033 </literallayout>
1034 </para>
1035 </section>
1036</section>
1037
1038<section id='scc-reference'>
1039 <title>SCC Description File Reference</title>
1040
1041 <para>
1042 This section provides a brief reference for the commands you can use
1043 within an SCC description file (<filename>.scc</filename>):
1044 <itemizedlist>
1045 <listitem><para><filename>branch [ref]</filename>:
1046 Creates a new branch relative to the current branch
1047 (typically <filename>${KTYPE}</filename>) using
1048 the currently checked-out branch, or "ref" if specified.
1049 </para></listitem>
1050 <listitem><para><filename>define</filename>:
1051 Defines variables, such as <filename>KMACHINE</filename>,
1052 <filename>KTYPE</filename>, <filename>KARCH</filename>,
1053 and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
1054 <listitem><para><filename>include SCC_FILE</filename>:
1055 Includes an SCC file in the current file.
1056 The file is parsed as if you had inserted it inline.
1057 </para></listitem>
1058 <listitem><para><filename>kconf [hardware|non-hardware] CFG_FILE</filename>:
1059 Queues a configuration fragment for merging into the final
1060 Linux <filename>.config</filename> file.</para></listitem>
1061 <listitem><para><filename>git merge GIT_BRANCH</filename>:
1062 Merges the feature branch into the current branch.
1063 </para></listitem>
1064 <listitem><para><filename>patch PATCH_FILE</filename>:
1065 Applies the patch to the current Git branch.</para></listitem>
1066 </itemizedlist>
1067 </para>
1068</section>
1069
1070</chapter>
1071<!--
1072vim: expandtab tw=80 ts=4
1073-->
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
new file mode 100644
index 0000000..ef1d0db
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -0,0 +1,858 @@
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
29 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
30 append files
31 (<filename>.bbappend</filename>) and provides a convenient
32 mechanism to create your own recipe files
33 (<filename>.bb</filename>).
34 For details on how to create and work with layers, see the following
35 sections in the Yocto Project Development Manual:
36 <itemizedlist>
37 <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for
38 general information on layers and how to create layers.</para></listitem>
39 <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for
40 specific instructions on setting up a layer for kernel
41 development.</para></listitem>
42 </itemizedlist>
43 </para>
44 </section>
45
46 <section id='modifying-an-existing-recipe'>
47 <title>Modifying an Existing Recipe</title>
48
49 <para>
50 In many cases, you can customize an existing linux-yocto recipe to
51 meet the needs of your project.
52 Each release of the Yocto Project provides a few Linux
53 kernel recipes from which you can choose.
54 These are located in the
55 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
56 in <filename>meta/recipes-kernel/linux</filename>.
57 </para>
58
59 <para>
60 Modifying an existing recipe can consist of the following:
61 <itemizedlist>
62 <listitem><para>Creating the append file</para></listitem>
63 <listitem><para>Applying patches</para></listitem>
64 <listitem><para>Changing the configuration</para></listitem>
65 </itemizedlist>
66 </para>
67
68 <para>
69 Before modifying an existing recipe, be sure that you have created
70 a minimal, custom layer from which you can work.
71 See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
72 section for some general resources.
73 You can also see the
74 "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section
75 of the Yocto Project Development Manual for a detailed
76 example.
77 </para>
78
79 <section id='creating-the-append-file'>
80 <title>Creating the Append File</title>
81
82 <para>
83 You create this file in your custom layer.
84 You also name it accordingly based on the linux-yocto recipe
85 you are using.
86 For example, if you are modifying the
87 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>
88 recipe, the append file will typical be located as follows
89 within your custom layer:
90 <literallayout class='monospaced'>
91 &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto_3.4.bbappend
92 </literallayout>
93 The append file should initially extend the
94 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
95 search path by prepending the directory that contains your
96 files to the
97 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
98 variable as follows:
99 <literallayout class='monospaced'>
100 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
101 </literallayout>
102 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>
103 expands to "linux-yocto" in the current directory for this
104 example.
105 If you add any new files that modify the kernel recipe and you
106 have extended <filename>FILESPATH</filename> as
107 described above, you must place the files in your layer in the
108 following area:
109 <literallayout class='monospaced'>
110 &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto/
111 </literallayout>
112 <note>If you are working on a new machine Board Support Package
113 (BSP), be sure to refer to the
114 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
115 </note>
116 </para>
117 </section>
118
119 <section id='applying-patches'>
120 <title>Applying Patches</title>
121
122 <para>
123 If you have a single patch or a small series of patches
124 that you want to apply to the Linux kernel source, you
125 can do so just as you would with any other recipe.
126 You first copy the patches to the path added to
127 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
128 in your <filename>.bbappend</filename> file as described in
129 the previous section, and then reference them in
130 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
131 statements.
132 </para>
133
134 <para>
135 For example, you can apply a three-patch series by adding the
136 following lines to your linux-yocto <filename>.bbappend</filename>
137 file in your layer:
138 <literallayout class='monospaced'>
139 SRC_URI += "file://0001-first-change.patch"
140 SRC_URI += "file://0002-first-change.patch"
141 SRC_URI += "file://0003-first-change.patch"
142 </literallayout>
143 The next time you run BitBake to build the Linux kernel, BitBake
144 detects the change in the recipe and fetches and applies the patches
145 before building the kernel.
146 </para>
147
148 <para>
149 For a detailed example showing how to patch the kernel, see the
150 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
151 section in the Yocto Project Development Manual.
152 </para>
153 </section>
154
155 <section id='changing-the-configuration'>
156 <title>Changing the Configuration</title>
157
158 <para>
159 You can make wholesale or incremental changes to the Linux
160 kernel <filename>.config</filename> file by including a
161 <filename>defconfig</filename> and by specifying
162 configuration fragments in the
163 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
164 </para>
165
166 <para>
167 If you have a final Linux kernel <filename>.config</filename>
168 file you want to use, copy it to a directory named
169 <filename>files</filename>, which must be in
170 your layer's <filename>recipes-kernel/linux</filename>
171 directory, and name the file "defconfig".
172 Then, add the following lines to your linux-yocto
173 <filename>.bbappend</filename> file in your layer:
174 <literallayout class='monospaced'>
175 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
176 SRC_URI += "file://defconfig"
177 </literallayout>
178 The <filename>SRC_URI</filename> tells the build system how to
179 search for the file, while the
180 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
181 extends the
182 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
183 variable (search directories) to include the
184 <filename>files</filename> directory you created for the
185 configuration changes.
186 </para>
187
188 <note>
189 The build system applies the configurations from the
190 <filename>.config</filename> file before applying any
191 subsequent configuration fragments.
192 The final kernel configuration is a combination of the
193 configurations in the <filename>.config</filename> file and
194 any configuration fragments you provide.
195 You need to realize that if you have any configuration
196 fragments, the build system applies these on top of and
197 after applying the existing <filename>.config</filename>
198 file configurations.
199 </note>
200
201 <para>
202 Generally speaking, the preferred approach is to determine the
203 incremental change you want to make and add that as a
204 configuration fragment.
205 For example, if you want to add support for a basic serial
206 console, create a file named <filename>8250.cfg</filename> in
207 the <filename>files</filename> directory with the following
208 content (without indentation):
209 <literallayout class='monospaced'>
210 CONFIG_SERIAL_8250=y
211 CONFIG_SERIAL_8250_CONSOLE=y
212 CONFIG_SERIAL_8250_PCI=y
213 CONFIG_SERIAL_8250_NR_UARTS=4
214 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
215 CONFIG_SERIAL_CORE=y
216 CONFIG_SERIAL_CORE_CONSOLE=y
217 </literallayout>
218 Next, include this configuration fragment and extend the
219 <filename>FILESPATH</filename> variable in your
220 <filename>.bbappend</filename> file:
221 <literallayout class='monospaced'>
222 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
223 SRC_URI += "file://8250.cfg"
224 </literallayout>
225 The next time you run BitBake to build the Linux kernel, BitBake
226 detects the change in the recipe and fetches and applies the
227 new configuration before building the kernel.
228 </para>
229
230 <para>
231 For a detailed example showing how to configure the kernel,
232 see the
233 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
234 section in the Yocto Project Development Manual.
235 </para>
236 </section>
237 </section>
238
239 <section id='using-an-iterative-development-process'>
240 <title>Using an Iterative Development Process</title>
241
242 <para>
243 If you do not have existing patches or configuration files,
244 you can iteratively generate them from within the BitBake build
245 environment as described within this section.
246 During an iterative workflow, running a previously completed BitBake
247 task causes BitBake to invalidate the tasks that follow the
248 completed task in the build sequence.
249 Invalidated tasks rebuild the next time you run the build using
250 BitBake.
251 </para>
252
253 <para>
254 As you read this section, be sure to substitute the name
255 of your Linux kernel recipe for the term
256 "linux-yocto".
257 </para>
258
259 <section id='tip-dirty-string'>
260 <title>"-dirty" String</title>
261
262<!--
263 <para>
264 <emphasis>AR - Darrren Hart:</emphasis> This section
265 originated from the old Yocto Project Kernel Architecture
266 and Use Manual.
267 It was decided we need to put it in this section here.
268 Darren needs to figure out where we want it and what part
269 of it we want (all, revision???)
270 </para>
271-->
272
273 <para>
274 If kernel images are being built with "-dirty" on the
275 end of the version string, this simply means that
276 modifications in the source directory have not been committed.
277 <literallayout class='monospaced'>
278 $ git status
279 </literallayout>
280 </para>
281
282 <para>
283 You can use the above Git command to report modified,
284 removed, or added files.
285 You should commit those changes to the tree regardless of
286 whether they will be saved, exported, or used.
287 Once you commit the changes, you need to rebuild the kernel.
288 </para>
289
290 <para>
291 To force a pickup and commit of all such pending changes,
292 enter the following:
293 <literallayout class='monospaced'>
294 $ git add .
295 $ git commit -s -a -m "getting rid of -dirty"
296 </literallayout>
297 </para>
298
299 <para>
300 Next, rebuild the kernel.
301 </para>
302 </section>
303
304 <section id='generating-configuration-files'>
305 <title>Generating Configuration Files</title>
306
307 <para>
308 You can manipulate the <filename>.config</filename> file
309 used to build a linux-yocto recipe with the
310 <filename>menuconfig</filename> command as follows:
311 <literallayout class='monospaced'>
312 $ bitbake linux-yocto -c menuconfig
313 </literallayout>
314 This command starts the Linux kernel configuration tool,
315 which allows you to prepare a new
316 <filename>.config</filename> file for the build.
317 When you exit the tool, be sure to save your changes
318 at the prompt.
319 </para>
320
321 <para>
322 The resulting <filename>.config</filename> file is
323 located in
324 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the
325 <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.
326 You can use the entire <filename>.config</filename> file as the
327 <filename>defconfig</filename> file as described in the
328 "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
329 </para>
330
331 <para>
332 A better method is to create a configuration fragment using the
333 differences between two configuration files: one previously
334 created and saved, and one freshly created using the
335 <filename>menuconfig</filename> tool.
336 </para>
337
338 <para>
339 To create a configuration fragment using this method, follow
340 these steps:
341 <orderedlist>
342 <listitem><para>Complete a build at least through the kernel
343 configuration task as follows:
344 <literallayout class='monospaced'>
345 $ bitbake linux-yocto -c kernel_configme -f
346 </literallayout></para></listitem>
347 <listitem><para>Run the <filename>menuconfig</filename>
348 command:
349 <literallayout class='monospaced'>
350 $ bitbake linux-yocto -c menuconfig
351 </literallayout></para></listitem>
352 <listitem><para>Run the <filename>diffconfig</filename>
353 command to prepare a configuration fragment.
354 The resulting file <filename>fragment.cfg</filename>
355 will be placed in the
356 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory:
357 <literallayout class='monospaced'>
358 $ bitbake linux-yocto -c diffconfig
359 </literallayout></para></listitem>
360 </orderedlist>
361 </para>
362
363 <para>
364 The <filename>diffconfig</filename> command creates a file that is a
365 list of Linux kernel <filename>CONFIG_</filename> assignments.
366 See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
367 section for information on how to use the output as a
368 configuration fragment.
369 <note>
370 You can also use this method to create configuration
371 fragments for a BSP.
372 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
373 section for more information.
374 </note>
375 </para>
376
377 <para>
378 The kernel tools also provide configuration validation.
379 You can use these tools to produce warnings for when a
380 requested configuration does not appear in the final
381 <filename>.config</filename> file or when you override a
382 policy configuration in a hardware configuration fragment.
383 Here is an example with some sample output of the command
384 that runs these tools:
385 <literallayout class='monospaced'>
386 $ bitbake linux-yocto -c kernel_configcheck -f
387
388 ...
389
390 NOTE: validating kernel configuration
391 This BSP sets 3 invalid/obsolete kernel options.
392 These config options are not offered anywhere within this kernel.
393 The full list can be found in your kernel src dir at:
394 meta/cfg/standard/mybsp/invalid.cfg
395
396 This BSP sets 21 kernel options that are possibly non-hardware related.
397 The full list can be found in your kernel src dir at:
398 meta/cfg/standard/mybsp/specified_non_hdw.cfg
399
400 WARNING: There were 2 hardware options requested that do not
401 have a corresponding value present in the final ".config" file.
402 This probably means you are not't getting the config you wanted.
403 The full list can be found in your kernel src dir at:
404 meta/cfg/standard/mybsp/mismatch.cfg
405 </literallayout>
406 </para>
407
408 <para>
409 The output describes the various problems that you can
410 encounter along with where to find the offending configuration
411 items.
412 You can use the information in the logs to adjust your
413 configuration files and then repeat the
414 <filename>kernel_configme</filename> and
415 <filename>kernel_configcheck</filename> commands until
416 they produce no warnings.
417 </para>
418
419 <para>
420 For more information on how to use the
421 <filename>menuconfig</filename> tool, see the
422 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
423 section in the Yocto Project Development Manual.
424 </para>
425 </section>
426
427 <section id='modifying-source-code'>
428 <title>Modifying Source Code</title>
429
430 <para>
431 You can experiment with source code changes and create a
432 simple patch without leaving the BitBake environment.
433 To get started, be sure to complete a build at
434 least through the kernel configuration task:
435 <literallayout class='monospaced'>
436 $ bitbake linux-yocto -c kernel_configme -f
437 </literallayout>
438 Taking this step ensures you have the sources prepared
439 and the configuration completed.
440 You can find the sources in the
441 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.
442 </para>
443
444 <para>
445 You can edit the sources as you would any other Linux source
446 tree.
447 However, keep in mind that you will lose changes if you
448 trigger the <filename>fetch</filename> task for the recipe.
449 You can avoid triggering this task by not issuing BitBake's
450 <filename>cleanall</filename>, <filename>cleansstate</filename>,
451 or forced <filename>fetch</filename> commands.
452 Also, do not modify the recipe itself while working
453 with temporary changes or BitBake might run the
454 <filename>fetch</filename> command depending on the
455 changes to the recipe.
456 </para>
457
458 <para>
459 To test your temporary changes, instruct BitBake to run the
460 <filename>compile</filename> again.
461 The <filename>-f</filename> option forces the command to run
462 even though BitBake might think it has already done so:
463 <literallayout class='monospaced'>
464 $ bitbake linux-yocto -c compile -f
465 </literallayout>
466 If the compile fails, you can update the sources and repeat
467 the <filename>compile</filename>.
468 Once compilation is successful, you can inspect and test
469 the resulting build (i.e. kernel, modules, and so forth) from
470 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
471 <literallayout class='monospaced'>
472 ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build
473 </literallayout>
474 Alternatively, you can run the <filename>deploy</filename>
475 command to place the kernel image in the
476 <filename>tmp/deploy/images</filename> directory:
477 <literallayout class='monospaced'>
478 $ bitbake linux-yocto -c deploy
479 </literallayout>
480 And, of course, you can perform the remaining installation and
481 packaging steps by issuing:
482 <literallayout class='monospaced'>
483 $ bitbake linux-yocto
484 </literallayout>
485 </para>
486
487 <para>
488 For rapid iterative development, the edit-compile-repeat loop
489 described in this section is preferable to rebuilding the
490 entire recipe because the installation and packaging tasks
491 are very time consuming.
492 </para>
493
494 <para>
495 Once you are satisfied with your source code modifications,
496 you can make them permanent by generating patches and
497 applying them to the
498 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
499 statement as described in section
500 "<link linkend='applying-patches'>Applying Patches</link>" section.
501 If you are not familiar with generating patches, refer to the
502 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
503 section in the Yocto Project Development Manual.
504 </para>
505 </section>
506 </section>
507
508 <section id='working-with-your-own-sources'>
509 <title>Working With Your Own Sources</title>
510
511 <para>
512 If you cannot work with one of the Linux kernel
513 versions supported by existing linux-yocto recipes, you can
514 still make use of the Yocto Project Linux kernel tooling by
515 working with your own sources.
516 When you use your own sources, you will not be able to
517 leverage the existing kernel
518 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and
519 stabilization work of the linux-yocto sources.
520 However, you will be able to manage your own Metadata in the same
521 format as the linux-yocto sources.
522 Maintaining format compatibility facilitates converging with
523 linux-yocto on a future, mutually-supported kernel version.
524 </para>
525
526 <para>
527 To help you use your own sources, the Yocto Project provides a
528 linux-yocto custom recipe
529 (<filename>linux-yocto-custom.bb</filename>) that uses
530 <filename>kernel.org</filename> sources
531 and the Yocto Project Linux kernel tools for managing
532 kernel Metadata.
533 You can find this recipe in the
534 <filename>poky</filename> Git repository of the
535 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
536 at:
537 <literallayout class="monospaced">
538 poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
539 </literallayout>
540 </para>
541
542 <para>
543 Here are some basic steps you can use to work with your own sources:
544 <orderedlist>
545 <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename>
546 recipe to your layer and give it a meaningful name.
547 The name should include the version of the Linux kernel you
548 are using (e.g. <filename>linux-yocto-myproject_3.5.bb</filename>,
549 where "3.5" is the base version of the Linux kernel
550 with which you would be working).</para></listitem>
551 <listitem><para>In the same directory inside your layer,
552 create a matching directory
553 to store your patches and configuration files (e.g.
554 <filename>linux-yocto-myproject</filename>).
555 </para></listitem>
556 <listitem><para>Edit the following variables in your recipe
557 as appropriate for your project:
558 <itemizedlist>
559 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
560 The <filename>SRC_URI</filename> should be a Git
561 repository that uses one of the supported Git fetcher
562 protocols (i.e. <filename>file</filename>,
563 <filename>git</filename>, <filename>http</filename>,
564 and so forth).
565 The skeleton recipe provides an example
566 <filename>SRC_URI</filename> as a syntax reference.
567 </para></listitem>
568 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
569 The Linux kernel version you are using (e.g.
570 "3.4").</para></listitem>
571 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
572 The Linux kernel <filename>CONFIG_LOCALVERSION</filename>
573 that is compiled into the resulting kernel and visible
574 through the <filename>uname</filename> command.
575 </para></listitem>
576 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
577 The commit ID from which you want to build.
578 </para></listitem>
579 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
580 Treat this variable the same as you would in any other
581 recipe.
582 Increment the variable to indicate to the OpenEmbedded
583 build system that the recipe has changed.
584 </para></listitem>
585 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
586 The default <filename>PV</filename> assignment is
587 typically adequate.
588 It combines the <filename>LINUX_VERSION</filename>
589 with the Source Control Manager (SCM) revision
590 as derived from the
591 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
592 variable.
593 The combined results are a string with
594 the following form:
595 <literallayout class='monospaced'>
596 3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
597 </literallayout>
598 While lengthy, the extra verbosity in <filename>PV</filename>
599 helps ensure you are using the exact
600 sources from which you intend to build.
601 </para></listitem>
602 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
603 A list of the machines supported by your new recipe.
604 This variable in the example recipe is set
605 by default to a regular expression that matches
606 only the empty string, "(^$)".
607 This default setting triggers an explicit build
608 failure.
609 You must change it to match a list of the machines
610 that your new recipe supports.
611 For example, to support the <filename>qemux86</filename>
612 and <filename>qemux86-64</filename> machines, use
613 the following form:
614 <literallayout class='monospaced'>
615 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
616 </literallayout></para></listitem>
617 </itemizedlist></para></listitem>
618 <listitem><para>Provide further customizations to your recipe
619 as needed just as you would customize an existing
620 linux-yocto recipe.
621 See the "<link linkend='modifying-an-existing-recipe'>Modifying
622 an Existing Recipe</link>" section for information.
623 </para></listitem>
624 </orderedlist>
625 </para>
626 </section>
627
628 <section id='incorporating-out-of-tree-modules'>
629 <title>Incorporating Out-of-Tree Modules</title>
630
631 <para>
632 While it is always preferable to work with sources integrated
633 into the Linux kernel sources, if you need an external kernel
634 module, the <filename>hello-mod.bb</filename> recipe is available
635 as a template from which you can create your own out-of-tree
636 Linux kernel module recipe.
637 </para>
638
639 <para>
640 This template recipe is located in the
641 <filename>poky</filename> Git repository of the
642 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
643 at:
644 <literallayout class="monospaced">
645 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
646 </literallayout>
647 </para>
648
649 <para>
650 To get started, copy this recipe to your layer and give it a
651 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
652 In the same directory, create a directory named
653 <filename>files</filename> where you can store any source files,
654 patches, or other files necessary for building
655 the module that do not come with the sources.
656 Finally, update the recipe as appropriate for the module.
657 Typically you will need to set the following variables:
658 <itemizedlist>
659 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
660 </para></listitem>
661 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
662 </para></listitem>
663 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
664 </para></listitem>
665 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
666 </para></listitem>
667 </itemizedlist>
668 </para>
669
670 <para>
671 Depending on the build system used by the module sources, you might
672 need to make some adjustments.
673 For example, a typical module <filename>Makefile</filename> looks
674 much like the one provided with the <filename>hello-mod</filename>
675 template:
676 <literallayout class='monospaced'>
677 obj-m := hello.o
678
679 SRC := $(shell pwd)
680
681 all:
682 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
683
684 modules_install:
685 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
686 ...
687 </literallayout>
688 </para>
689
690 <para>
691 The important point to note here is the
692 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
693 variable.
694 The class <filename>module.bbclass</filename> sets this variable,
695 as well as the
696 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
697 variable to
698 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
699 with the necessary Linux kernel build information to build modules.
700 If your module <filename>Makefile</filename> uses a different
701 variable, you might want to override the
702 <filename>do_compile()</filename> step, or create a patch to
703 the <filename>Makefile</filename> to work with the more typical
704 <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
705 variables.
706 </para>
707
708 <para>
709 After you have prepared your recipe, you will likely want to
710 include the module in your images.
711 To do this, see the documentation for the following variables in
712 the Yocto Project Reference Manual and set one of them as
713 appropriate in your machine configuration file:
714 <itemizedlist>
715 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
716 </para></listitem>
717 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
718 </para></listitem>
719 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
720 </para></listitem>
721 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
722 </para></listitem>
723 </itemizedlist>
724 </para>
725
726 <para>
727 modules are often not required for boot and can be excluded from
728 certain build configurations.
729 The following allows for the most flexibility:
730 <literallayout class='monospaced'>
731 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
732 </literallayout>
733 Where the value is derived by appending the module filename without
734 the <filename>.ko</filename> extension to the string
735 "kernel-module-".
736 </para>
737
738 <para>
739 Because the variable is
740 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
741 and not a
742 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
743 variable, the build will not fail if this module is not available
744 to include in the image.
745 </para>
746 </section>
747
748 <section id='inspecting-changes-and-commits'>
749 <title>Inspecting Changes and Commits</title>
750
751 <para>
752 A common question when working with a kernel is:
753 "What changes have been applied to this tree?"
754 Rather than using "grep" across directories to see what has
755 changed, you can use Git to inspect or search the kernel tree.
756 Using Git is an efficient way to see what has changed in the tree.
757 </para>
758
759 <section id='what-changed-in-a-kernel'>
760 <title>What Changed in a Kernel?</title>
761
762 <para>
763 Following are a few examples that show how to use Git
764 commands to examine changes.
765 These examples are by no means the only way to see changes.
766 <note>
767 In the following examples, unless you provide a commit
768 range, <filename>kernel.org</filename> history is blended
769 with Yocto Project kernel changes.
770 You can form ranges by using branch names from the
771 kernel tree as the upper and lower commit markers with
772 the Git commands.
773 You can see the branch names through the web interface
774 to the Yocto Project source repositories at
775 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
776 </note>
777 To see a full range of the changes, use the
778 <filename>git whatchanged</filename> command and specify a
779 commit range for the branch
780 (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
781 </para>
782
783 <para>
784 Here is an example that looks at what has changed in the
785 <filename>emenlow</filename> branch of the
786 <filename>linux-yocto-3.4</filename> kernel.
787 The lower commit range is the commit associated with the
788 <filename>standard/base</filename> branch, while
789 the upper commit range is the commit associated with the
790 <filename>standard/emenlow</filename> branch.
791 <literallayout class='monospaced'>
792 $ git whatchanged origin/standard/base..origin/standard/emenlow
793 </literallayout>
794 </para>
795
796 <para>
797 To see short, one line summaries of changes use the
798 <filename>git log</filename> command:
799 <literallayout class='monospaced'>
800 $ git log --oneline origin/standard/base..origin/standard/emenlow
801 </literallayout>
802 </para>
803
804 <para>
805 Use this command to see code differences for the changes:
806 <literallayout class='monospaced'>
807 $ git diff origin/standard/base..origin/standard/emenlow
808 </literallayout>
809 </para>
810
811 <para>
812 Use this command to see the commit log messages and the
813 text differences:
814 <literallayout class='monospaced'>
815 $ git show origin/standard/base..origin/standard/emenlow
816 </literallayout>
817 </para>
818
819 <para>
820 Use this command to create individual patches for
821 each change.
822 Here is an example that that creates patch files for each
823 commit and places them in your <filename>Documents</filename>
824 directory:
825 <literallayout class='monospaced'>
826 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
827 </literallayout>
828 </para>
829 </section>
830
831 <section id='showing-a-particular-feature-or-branch-change'>
832 <title>Showing a Particular Feature or Branch Change</title>
833
834 <para>
835 Tags in the Yocto Project kernel tree divide changes for
836 significant features or branches.
837 The <filename>git show &lt;tag&gt;</filename> command shows
838 changes based on a tag.
839 Here is an example that shows <filename>systemtap</filename>
840 changes:
841 <literallayout class='monospaced'>
842 $ git show systemtap
843 </literallayout>
844 You can use the
845 <filename>git branch --contains &lt;tag&gt;</filename> command
846 to show the branches that contain a particular feature.
847 This command shows the branches that contain the
848 <filename>systemtap</filename> feature:
849 <literallayout class='monospaced'>
850 $ git branch --contains systemtap
851 </literallayout>
852 </para>
853 </section>
854 </section>
855</chapter>
856<!--
857vim: expandtab tw=80 ts=4
858-->
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..a2baa12
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev.xml
@@ -0,0 +1,105 @@
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>January 2014</date>
47 <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
48 </revision>
49 <revision>
50 <revnumber>1.6</revnumber>
51 <date>April 2014</date>
52 <revremark>Released with the Yocto Project 1.6 Release.</revremark>
53 </revision>
54 <revision>
55 <revnumber>1.6.1</revnumber>
56 <date>Sometime in 2014</date>
57 <revremark>Released with the Yocto Project 1.6.1 Release.</revremark>
58 </revision>
59 </revhistory>
60
61 <copyright>
62 <year>&COPYRIGHT_YEAR;</year>
63 <holder>Linux Foundation</holder>
64 </copyright>
65
66 <legalnotice>
67 <para>
68 Permission is granted to copy, distribute and/or modify this document under
69 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.
70 </para>
71 <note>
72 For the latest version of this manual associated with this
73 Yocto Project release, see the
74 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>
75 from the Yocto Project website.
76 </note>
77 </legalnotice>
78
79 </bookinfo>
80
81 <xi:include href="kernel-dev-intro.xml"/>
82
83 <xi:include href="kernel-dev-common.xml"/>
84
85 <xi:include href="kernel-dev-advanced.xml"/>
86
87 <xi:include href="kernel-dev-concepts-appx.xml"/>
88
89 <xi:include href="kernel-dev-maint-appx.xml"/>
90
91<!--
92 <xi:include href="kernel-dev-examples.xml"/>
93-->
94
95 <xi:include href="kernel-dev-faq.xml"/>
96
97<!-- <index id='index'>
98 <title>Index</title>
99 </index>
100-->
101
102</book>
103<!--
104vim: expandtab tw=80 ts=4
105-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-05 09:05:45 +0000