summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/kernel-dev
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml1257
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml2730
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml622
-rw-r--r--documentation/kernel-dev/kernel-dev-customization.xsl28
-rw-r--r--documentation/kernel-dev/kernel-dev-faq.xml143
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml260
-rw-r--r--documentation/kernel-dev/kernel-dev-maint-appx.xml357
-rw-r--r--documentation/kernel-dev/kernel-dev-style.css991
-rwxr-xr-xdocumentation/kernel-dev/kernel-dev.xml187
9 files changed, 0 insertions, 6575 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
deleted file mode 100644
index 37177966bf..0000000000
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ /dev/null
@@ -1,1257 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='kernel-dev-advanced'>
7<title>Working with Advanced Metadata (<filename>yocto-kernel-cache</filename>)</title>
8
9<section id='kernel-dev-advanced-overview'>
10 <title>Overview</title>
11
12 <para>
13 In addition to supporting configuration fragments and patches, the
14 Yocto Project kernel tools also support rich
15 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> that you can
16 use to define complex policies and Board Support Package (BSP) support.
17 The purpose of the Metadata and the tools that manage it 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
22 <para>
23 Kernel Metadata exists in many places.
24 One area in the Yocto Project
25 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
26 is the <filename>yocto-kernel-cache</filename> Git repository.
27 You can find this repository grouped under the "Yocto Linux Kernel"
28 heading in the
29 <ulink url='&YOCTO_GIT_URL;'>Yocto Project Source Repositories</ulink>.
30 </para>
31
32 <para>
33 Kernel development tools ("kern-tools") exist also in the Yocto
34 Project Source Repositories under the "Yocto Linux Kernel" heading
35 in the <filename>yocto-kernel-tools</filename> Git repository.
36 The recipe that builds these tools is
37 <filename>meta/recipes-kernel/kern-tools/kern-tools-native_git.bb</filename>
38 in the
39 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
40 (e.g. <filename>poky</filename>).
41 </para>
42</section>
43
44<section id='using-kernel-metadata-in-a-recipe'>
45 <title>Using Kernel Metadata in a Recipe</title>
46
47 <para>
48 As mentioned in the introduction, the Yocto Project contains kernel
49 Metadata, which is located in the
50 <filename>yocto-kernel-cache</filename> Git repository.
51 This Metadata defines Board Support Packages (BSPs) that
52 correspond to definitions in linux-yocto recipes for corresponding BSPs.
53 A BSP consists of an aggregation of kernel policy and enabled
54 hardware-specific features.
55 The BSP can be influenced from within the linux-yocto recipe.
56 <note>
57 A Linux kernel recipe that contains kernel Metadata (e.g.
58 inherits from the <filename>linux-yocto.inc</filename> file)
59 is said to be a "linux-yocto style" recipe.
60 </note>
61 </para>
62
63 <para>
64 Every linux-yocto style recipe must define the
65 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
66 variable.
67 This variable is typically set to the same value as the
68 <filename>MACHINE</filename> variable, which is used by
69 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
70 However, in some cases, the variable might instead refer to the
71 underlying platform of the <filename>MACHINE</filename>.
72 </para>
73
74 <para>
75 Multiple BSPs can reuse the same <filename>KMACHINE</filename>
76 name if they are built using the same BSP description.
77 Multiple Corei7-based BSPs could share the same "intel-corei7-64"
78 value for <filename>KMACHINE</filename>.
79 It is important to realize that <filename>KMACHINE</filename> is
80 just for kernel mapping, while <filename>MACHINE</filename>
81 is the machine type within a BSP Layer.
82 Even with this distinction, however, these two variables can hold
83 the same value.
84 See the <link linkend='bsp-descriptions'>BSP Descriptions</link>
85 section for more information.
86 </para>
87
88 <para>
89 Every linux-yocto style recipe must also indicate the Linux kernel
90 source repository branch used to build the Linux kernel.
91 The <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
92 variable must be set to indicate the branch.
93 <note>
94 You can use the <filename>KBRANCH</filename> value to define an
95 alternate branch typically with a machine override as shown here
96 from the <filename>meta-yocto-bsp</filename> layer:
97 <literallayout class='monospaced'>
98 KBRANCH_edgerouter = "standard/edgerouter"
99 </literallayout>
100 </note>
101 </para>
102
103 <para>
104 The linux-yocto style recipes can optionally define the following
105 variables:
106 <literallayout class='monospaced'>
107 KERNEL_FEATURES
108 LINUX_KERNEL_TYPE
109 </literallayout>
110 </para>
111
112 <para>
113 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
114 defines the kernel type to be
115 used in assembling the configuration.
116 If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
117 it defaults to "standard".
118 Together with <filename>KMACHINE</filename>,
119 <filename>LINUX_KERNEL_TYPE</filename> defines the search
120 arguments used by the kernel tools to find the
121 appropriate description within the kernel Metadata with which to
122 build out the sources and configuration.
123 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
124 kernel types.
125 See the "<link linkend='kernel-types'>Kernel Types</link>" section
126 for more information on kernel types.
127 </para>
128
129 <para>
130 During the build, the kern-tools search for the BSP description
131 file that most closely matches the <filename>KMACHINE</filename>
132 and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the
133 recipe.
134 The tools use the first BSP description it finds that match
135 both variables.
136 If the tools cannot find a match, they issue a warning.
137 </para>
138
139 <para>
140 The tools first search for the <filename>KMACHINE</filename> and
141 then for the <filename>LINUX_KERNEL_TYPE</filename>.
142 If the tools cannot find a partial match, they will use the
143 sources from the <filename>KBRANCH</filename> and any configuration
144 specified in the
145 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
146 </para>
147
148 <para>
149 You can use the
150 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
151 variable
152 to include features (configuration fragments, patches, or both) that
153 are not already included by the <filename>KMACHINE</filename> and
154 <filename>LINUX_KERNEL_TYPE</filename> variable combination.
155 For example, to include a feature specified as
156 "features/netfilter/netfilter.scc",
157 specify:
158 <literallayout class='monospaced'>
159 KERNEL_FEATURES += "features/netfilter/netfilter.scc"
160 </literallayout>
161 To include a feature called "cfg/sound.scc" just for the
162 <filename>qemux86</filename> machine, specify:
163 <literallayout class='monospaced'>
164 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc"
165 </literallayout>
166 The value of the entries in <filename>KERNEL_FEATURES</filename>
167 are dependent on their location within the kernel Metadata itself.
168 The examples here are taken from the
169 <filename>yocto-kernel-cache</filename> repository.
170 Each branch of this repository contains "features" and "cfg"
171 subdirectories at the top-level.
172 For more information, see the
173 "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>"
174 section.
175 </para>
176</section>
177
178<section id='kernel-metadata-syntax'>
179 <title>Kernel Metadata Syntax</title>
180
181 <para>
182 The kernel Metadata consists of three primary types of files:
183 <filename>scc</filename>
184 <footnote>
185 <para>
186 <filename>scc</filename> stands for Series Configuration
187 Control, but the naming has less significance in the
188 current implementation of the tooling than it had in the
189 past.
190 Consider <filename>scc</filename> files to be description files.
191 </para>
192 </footnote>
193 description files, configuration fragments, and patches.
194 The <filename>scc</filename> files define variables and include or
195 otherwise reference any of the three file types.
196 The description files are used to aggregate all types of kernel
197 Metadata into
198 what ultimately describes the sources and the configuration required
199 to build a Linux kernel tailored to a specific machine.
200 </para>
201
202 <para>
203 The <filename>scc</filename> description files are used to define two
204 fundamental types of kernel Metadata:
205 <itemizedlist>
206 <listitem><para>Features</para></listitem>
207 <listitem><para>Board Support Packages (BSPs)</para></listitem>
208 </itemizedlist>
209 </para>
210
211 <para>
212 Features aggregate sources in the form of patches and configuration
213 fragments into a modular reusable unit.
214 You can use features to implement conceptually separate kernel
215 Metadata descriptions such as pure configuration fragments,
216 simple patches, complex features, and kernel types.
217 <link linkend='kernel-types'>Kernel types</link> define general
218 kernel features and policy to be reused in the BSPs.
219 </para>
220
221 <para>
222 BSPs define hardware-specific features and aggregate them with kernel
223 types to form the final description of what will be assembled and built.
224 </para>
225
226 <para>
227 While the kernel Metadata syntax does not enforce any logical
228 separation of configuration fragments, patches, features or kernel
229 types, best practices dictate a logical separation of these types
230 of Metadata.
231 The following Metadata file hierarchy is recommended:
232 <literallayout class='monospaced'>
233 <replaceable>base</replaceable>/
234 bsp/
235 cfg/
236 features/
237 ktypes/
238 patches/
239 </literallayout>
240 </para>
241
242 <para>
243 The <filename>bsp</filename> directory contains the
244 <link linkend='bsp-descriptions'>BSP descriptions</link>.
245 The remaining directories all contain "features".
246 Separating <filename>bsp</filename> from the rest of the structure
247 aids conceptualizing intended usage.
248 </para>
249
250 <para>
251 Use these guidelines to help place your <filename>scc</filename>
252 description files within the structure:
253 <itemizedlist>
254 <listitem><para>If your file contains
255 only configuration fragments, place the file in the
256 <filename>cfg</filename> directory.</para></listitem>
257 <listitem><para>If your file contains
258 only source-code fixes, place the file in the
259 <filename>patches</filename> directory.</para></listitem>
260 <listitem><para>If your file encapsulates
261 a major feature, often combining sources and configurations,
262 place the file in <filename>features</filename> directory.
263 </para></listitem>
264 <listitem><para>If your file aggregates
265 non-hardware configuration and patches in order to define a
266 base kernel policy or major kernel type to be reused across
267 multiple BSPs, place the file in <filename>ktypes</filename>
268 directory.
269 </para></listitem>
270 </itemizedlist>
271 </para>
272
273 <para>
274 These distinctions can easily become blurred - especially as
275 out-of-tree features slowly merge upstream over time.
276 Also, remember that how the description files are placed is
277 a purely logical organization and has no impact on the functionality
278 of the kernel Metadata.
279 There is no impact because all of <filename>cfg</filename>,
280 <filename>features</filename>, <filename>patches</filename>, and
281 <filename>ktypes</filename>, contain "features" as far as the kernel
282 tools are concerned.
283 </para>
284
285 <para>
286 Paths used in kernel Metadata files are relative to
287 <replaceable>base</replaceable>, which is either
288 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
289 if you are creating Metadata in
290 <link linkend='recipe-space-metadata'>recipe-space</link>,
291 or the top level of
292 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/'><filename>yocto-kernel-cache</filename></ulink>
293 if you are creating
294 <link linkend='metadata-outside-the-recipe-space'>Metadata outside of the recipe-space</link>.
295 </para>
296
297 <section id='configuration'>
298 <title>Configuration</title>
299
300 <para>
301 The simplest unit of kernel Metadata is the configuration-only
302 feature.
303 This feature consists of one or more Linux kernel configuration
304 parameters in a configuration fragment file
305 (<filename>.cfg</filename>) and a <filename>.scc</filename> file
306 that describes the fragment.
307 </para>
308
309 <para>
310 As an example, consider the Symmetric Multi-Processing (SMP)
311 fragment used with the <filename>linux-yocto-4.12</filename>
312 kernel as defined outside of the recipe space (i.e.
313 <filename>yocto-kernel-cache</filename>).
314 This Metadata consists of two files: <filename>smp.scc</filename>
315 and <filename>smp.cfg</filename>.
316 You can find these files in the <filename>cfg</filename> directory
317 of the <filename>yocto-4.12</filename> branch in the
318 <filename>yocto-kernel-cache</filename> Git repository:
319 <literallayout class='monospaced'>
320 cfg/smp.scc:
321 define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
322 define KFEATURE_COMPATIBILITY all
323
324 kconf hardware smp.cfg
325
326 cfg/smp.cfg:
327 CONFIG_SMP=y
328 CONFIG_SCHED_SMT=y
329 # Increase default NR_CPUS from 8 to 64 so that platform with
330 # more than 8 processors can be all activated at boot time
331 CONFIG_NR_CPUS=64
332 # The following is needed when setting NR_CPUS to something
333 # greater than 8 on x86 architectures, it should be automatically
334 # disregarded by Kconfig when using a different arch
335 CONFIG_X86_BIGSMP=y
336 </literallayout>
337 You can find general information on configuration fragment files in
338 the
339 "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
340 section.
341 </para>
342
343 <para>
344 Within the <filename>smp.scc</filename> file, the
345 <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>
346 statement provides a short description of the fragment.
347 Higher level kernel tools use this description.
348 </para>
349
350 <para>
351 Also within the <filename>smp.scc</filename> file, the
352 <filename>kconf</filename> command includes the
353 actual configuration fragment in an <filename>.scc</filename>
354 file, and the "hardware" keyword identifies the fragment as
355 being hardware enabling, as opposed to general policy,
356 which would use the "non-hardware" keyword.
357 The distinction is made for the benefit of the configuration
358 validation tools, which warn you if a hardware fragment
359 overrides a policy set by a non-hardware fragment.
360 <note>
361 The description file can include multiple
362 <filename>kconf</filename> statements, one per fragment.
363 </note>
364 </para>
365
366 <para>
367 As described in the
368 "<link linkend='validating-configuration'>Validating Configuration</link>"
369 section, you can use the following BitBake command to audit your
370 configuration:
371 <literallayout class='monospaced'>
372 $ bitbake linux-yocto -c kernel_configcheck -f
373 </literallayout>
374 </para>
375 </section>
376
377 <section id='patches'>
378 <title>Patches</title>
379
380 <para>
381 Patch descriptions are very similar to configuration fragment
382 descriptions, which are described in the previous section.
383 However, instead of a <filename>.cfg</filename> file, these
384 descriptions work with source patches (i.e.
385 <filename>.patch</filename> files).
386 </para>
387
388 <para>
389 A typical patch includes a description file and the patch itself.
390 As an example, consider the build patches used with the
391 <filename>linux-yocto-4.12</filename> kernel as defined outside of
392 the recipe space (i.e. <filename>yocto-kernel-cache</filename>).
393 This Metadata consists of several files:
394 <filename>build.scc</filename> and a set of
395 <filename>*.patch</filename> files.
396 You can find these files in the <filename>patches/build</filename>
397 directory of the <filename>yocto-4.12</filename> branch in the
398 <filename>yocto-kernel-cache</filename> Git repository.
399 </para>
400
401 <para>
402 The following listings show the <filename>build.scc</filename>
403 file and part of the
404 <filename>modpost-mask-trivial-warnings.patch</filename> file:
405 <literallayout class='monospaced'>
406 patches/build/build.scc:
407 patch arm-serialize-build-targets.patch
408 patch powerpc-serialize-image-targets.patch
409 patch kbuild-exclude-meta-directory-from-distclean-processi.patch
410
411 # applied by kgit
412 # patch kbuild-add-meta-files-to-the-ignore-li.patch
413
414 patch modpost-mask-trivial-warnings.patch
415 patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
416
417 patches/build/modpost-mask-trivial-warnings.patch:
418 From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
419 From: Paul Gortmaker &lt;paul.gortmaker@windriver.com&gt;
420 Date: Sun, 25 Jan 2009 17:58:09 -0500
421 Subject: [PATCH] modpost: mask trivial warnings
422
423 Newer HOSTCC will complain about various stdio fcns because
424 .
425 .
426 .
427 char *dump_write = NULL, *files_source = NULL;
428 int opt;
429 --
430 2.10.1
431
432 generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
433 </literallayout>
434 The description file can include multiple patch statements where
435 each statement handles a single patch.
436 In the example <filename>build.scc</filename> file, five patch
437 statements exist for the five patches in the directory.
438 </para>
439
440 <para>
441 You can create a typical <filename>.patch</filename> file using
442 <filename>diff -Nurp</filename> or
443 <filename>git format-patch</filename> commands.
444 For information on how to create patches, see the
445 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
446 and
447 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
448 sections.
449 </para>
450 </section>
451
452 <section id='features'>
453 <title>Features</title>
454
455 <para>
456 Features are complex kernel Metadata types that consist
457 of configuration fragments, patches, and possibly other feature
458 description files.
459 As an example, consider the following generic listing:
460 <literallayout class='monospaced'>
461 features/<replaceable>myfeature</replaceable>.scc
462 define KFEATURE_DESCRIPTION "Enable <replaceable>myfeature</replaceable>"
463
464 patch 0001-<replaceable>myfeature</replaceable>-core.patch
465 patch 0002-<replaceable>myfeature</replaceable>-interface.patch
466
467 include cfg/<replaceable>myfeature</replaceable>_dependency.scc
468 kconf non-hardware <replaceable>myfeature</replaceable>.cfg
469 </literallayout>
470 This example shows how the <filename>patch</filename> and
471 <filename>kconf</filename> commands are used as well as
472 how an additional feature description file is included with
473 the <filename>include</filename> command.
474 </para>
475
476 <para>
477 Typically, features are less granular than configuration
478 fragments and are more likely than configuration fragments
479 and patches to be the types of things you want to specify
480 in the <filename>KERNEL_FEATURES</filename> variable of the
481 Linux kernel recipe.
482 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
483 section earlier in the manual.
484 </para>
485 </section>
486
487 <section id='kernel-types'>
488 <title>Kernel Types</title>
489
490 <para>
491 A kernel type defines a high-level kernel policy by
492 aggregating non-hardware configuration fragments with
493 patches you want to use when building a Linux kernel of a
494 specific type (e.g. a real-time kernel).
495 Syntactically, kernel types are no different than features
496 as described in the "<link linkend='features'>Features</link>"
497 section.
498 The
499 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
500 variable in the kernel recipe selects the kernel type.
501 For example, in the <filename>linux-yocto_4.12.bb</filename>
502 kernel recipe found in
503 <filename>poky/meta/recipes-kernel/linux</filename>, a
504 <ulink url='&YOCTO_DOCS_BB_URL;#require-inclusion'><filename>require</filename></ulink>
505 directive includes the
506 <filename>poky/meta/recipes-kernel/linux/linux-yocto.inc</filename>
507 file, which has the following statement that defines the default
508 kernel type:
509 <literallayout class='monospaced'>
510 LINUX_KERNEL_TYPE ??= "standard"
511 </literallayout>
512 </para>
513
514 <para>
515 Another example would be the real-time kernel (i.e.
516 <filename>linux-yocto-rt_4.12.bb</filename>).
517 This kernel recipe directly sets the kernel type as follows:
518 <literallayout class='monospaced'>
519 LINUX_KERNEL_TYPE = "preempt-rt"
520 </literallayout>
521 <note>
522 You can find kernel recipes in the
523 <filename>meta/recipes-kernel/linux</filename> directory of the
524 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
525 (e.g. <filename>poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>).
526 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
527 section for more information.
528 </note>
529 </para>
530
531 <para>
532 Three kernel types ("standard", "tiny", and "preempt-rt") are
533 supported for Linux Yocto kernels:
534 <itemizedlist>
535 <listitem><para>"standard":
536 Includes the generic Linux kernel policy of the Yocto
537 Project linux-yocto kernel recipes.
538 This policy includes, among other things, which file
539 systems, networking options, core kernel features, and
540 debugging and tracing options are supported.
541 </para></listitem>
542 <listitem><para>"preempt-rt":
543 Applies the <filename>PREEMPT_RT</filename>
544 patches and the configuration options required to
545 build a real-time Linux kernel.
546 This kernel type inherits from the "standard" kernel type.
547 </para></listitem>
548 <listitem><para>"tiny":
549 Defines a bare minimum configuration meant to serve as a
550 base for very small Linux kernels.
551 The "tiny" kernel type is independent from the "standard"
552 configuration.
553 Although the "tiny" kernel type does not currently include
554 any source changes, it might in the future.
555 </para></listitem>
556 </itemizedlist>
557 </para>
558
559 <para>
560 For any given kernel type, the Metadata is defined by the
561 <filename>.scc</filename> (e.g. <filename>standard.scc</filename>).
562 Here is a partial listing for the <filename>standard.scc</filename>
563 file, which is found in the <filename>ktypes/standard</filename>
564 directory of the <filename>yocto-kernel-cache</filename> Git
565 repository:
566 <literallayout class='monospaced'>
567 # Include this kernel type fragment to get the standard features and
568 # configuration values.
569
570 # Note: if only the features are desired, but not the configuration
571 # then this should be included as:
572 # include ktypes/standard/standard.scc nocfg
573 # if no chained configuration is desired, include it as:
574 # include ktypes/standard/standard.scc nocfg inherit
575
576
577
578 include ktypes/base/base.scc
579 branch standard
580
581 kconf non-hardware standard.cfg
582
583 include features/kgdb/kgdb.scc
584 .
585 .
586 .
587
588 include cfg/net/ip6_nf.scc
589 include cfg/net/bridge.scc
590
591 include cfg/systemd.scc
592
593 include features/rfkill/rfkill.scc
594 </literallayout>
595 </para>
596
597 <para>
598 As with any <filename>.scc</filename> file, a
599 kernel type definition can aggregate other
600 <filename>.scc</filename> files with
601 <filename>include</filename> commands.
602 These definitions can also directly pull in
603 configuration fragments and patches with the
604 <filename>kconf</filename> and <filename>patch</filename>
605 commands, respectively.
606 </para>
607
608 <note>
609 It is not strictly necessary to create a kernel type
610 <filename>.scc</filename> file.
611 The Board Support Package (BSP) file can implicitly define
612 the kernel type using a <filename>define
613 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename>
614 line.
615 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
616 section for more information.
617 </note>
618 </section>
619
620 <section id='bsp-descriptions'>
621 <title>BSP Descriptions</title>
622
623 <para>
624 BSP descriptions (i.e. <filename>*.scc</filename> files)
625 combine kernel types with hardware-specific features.
626 The hardware-specific Metadata is typically defined
627 independently in the BSP layer, and then aggregated with each
628 supported kernel type.
629 <note>
630 For BSPs supported by the Yocto Project, the BSP description
631 files are located in the <filename>bsp</filename> directory
632 of the
633 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink>
634 repository organized under the "Yocto Linux Kernel" heading
635 in the
636 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
637 </note>
638 </para>
639
640 <para>
641 This section overviews the BSP description structure, the
642 aggregation concepts, and presents a detailed example using
643 a BSP supported by the Yocto Project (i.e. BeagleBone Board).
644 For complete information on BSP layer file hierarchy, see the
645 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
646 </para>
647
648 <section id='bsp-description-file-overview'>
649 <title>Overview</title>
650
651 <para>
652 For simplicity, consider the following root BSP layer
653 description files for the BeagleBone board.
654 These files employ both a structure and naming convention
655 for consistency.
656 The naming convention for the file is as follows:
657 <literallayout class='monospaced'>
658 <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
659 </literallayout>
660 Here are some example root layer BSP filenames for the
661 BeagleBone Board BSP, which is supported by the Yocto Project:
662 <literallayout class='monospaced'>
663 beaglebone-standard.scc
664 beaglebone-preempt-rt.scc
665 </literallayout>
666 Each file uses the root name (i.e "beaglebone") BSP name
667 followed by the kernel type.
668 </para>
669
670 <para>
671 Examine the <filename>beaglebone-standard.scc</filename>
672 file:
673 <literallayout class='monospaced'>
674 define KMACHINE beaglebone
675 define KTYPE standard
676 define KARCH arm
677
678 include ktypes/standard/standard.scc
679 branch beaglebone
680
681 include beaglebone.scc
682
683 # default policy for standard kernels
684 include features/latencytop/latencytop.scc
685 include features/profiling/profiling.scc
686 </literallayout>
687 Every top-level BSP description file should define the
688 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
689 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
690 and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
691 variables.
692 These variables allow the OpenEmbedded build system to identify
693 the description as meeting the criteria set by the recipe being
694 built.
695 This example supports the "beaglebone" machine for the
696 "standard" kernel and the "arm" architecture.
697 </para>
698
699 <para>
700 Be aware that a hard link between the
701 <filename>KTYPE</filename> variable and a kernel type
702 description file does not exist.
703 Thus, if you do not have the kernel type defined in your kernel
704 Metadata as it is here, you only need to ensure that the
705 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
706 variable in the kernel recipe and the
707 <filename>KTYPE</filename> variable in the BSP description
708 file match.
709 </para>
710
711 <para>
712 To separate your kernel policy from your hardware configuration,
713 you include a kernel type (<filename>ktype</filename>), such as
714 "standard".
715 In the previous example, this is done using the following:
716 <literallayout class='monospaced'>
717 include ktypes/standard/standard.scc
718 </literallayout>
719 This file aggregates all the configuration fragments, patches,
720 and features that make up your standard kernel policy.
721 See the "<link linkend='kernel-types'>Kernel Types</link>"
722 section for more information.
723 </para>
724
725 <para>
726 To aggregate common configurations and features specific to the
727 kernel for <replaceable>mybsp</replaceable>, use the following:
728 <literallayout class='monospaced'>
729 include <replaceable>mybsp</replaceable>.scc
730 </literallayout>
731 You can see that in the BeagleBone example with the following:
732 <literallayout class='monospaced'>
733 include beaglebone.scc
734 </literallayout>
735 For information on how to break a complete
736 <filename>.config</filename> file into the various
737 configuration fragments, see the
738 "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
739 section.
740 </para>
741
742 <para>
743 Finally, if you have any configurations specific to the
744 hardware that are not in a <filename>*.scc</filename> file,
745 you can include them as follows:
746 <literallayout class='monospaced'>
747 kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
748 </literallayout>
749 The BeagleBone example does not include these types of
750 configurations.
751 However, the Malta 32-bit board does ("mti-malta32").
752 Here is the <filename>mti-malta32-le-standard.scc</filename>
753 file:
754 <literallayout class='monospaced'>
755 define KMACHINE mti-malta32-le
756 define KMACHINE qemumipsel
757 define KTYPE standard
758 define KARCH mips
759
760 include ktypes/standard/standard.scc
761 branch mti-malta32
762
763 include mti-malta32.scc
764 kconf hardware mti-malta32-le.cfg
765 </literallayout>
766 </para>
767 </section>
768
769 <section id='bsp-description-file-example-minnow'>
770 <title>Example</title>
771
772 <para>
773 Many real-world examples are more complex.
774 Like any other <filename>.scc</filename> file, BSP
775 descriptions can aggregate features.
776 Consider the Minnow BSP definition given the
777 <filename>linux-yocto-4.4</filename> branch of the
778 <filename>yocto-kernel-cache</filename> (i.e.
779 <filename>yocto-kernel-cache/bsp/minnow/minnow.scc</filename>):
780 <note>
781 Although the Minnow Board BSP is unused, the Metadata
782 remains and is being used here just as an example.
783 </note>
784 <literallayout class='monospaced'>
785 include cfg/x86.scc
786 include features/eg20t/eg20t.scc
787 include cfg/dmaengine.scc
788 include features/power/intel.scc
789 include cfg/efi.scc
790 include features/usb/ehci-hcd.scc
791 include features/usb/ohci-hcd.scc
792 include features/usb/usb-gadgets.scc
793 include features/usb/touchscreen-composite.scc
794 include cfg/timer/hpet.scc
795 include features/leds/leds.scc
796 include features/spi/spidev.scc
797 include features/i2c/i2cdev.scc
798 include features/mei/mei-txe.scc
799
800 # Earlyprintk and port debug requires 8250
801 kconf hardware cfg/8250.cfg
802
803 kconf hardware minnow.cfg
804 kconf hardware minnow-dev.cfg
805 </literallayout>
806 </para>
807
808 <para>
809 The <filename>minnow.scc</filename> description file includes
810 a hardware configuration fragment
811 (<filename>minnow.cfg</filename>) specific to the Minnow
812 BSP as well as several more general configuration
813 fragments and features enabling hardware found on the
814 machine.
815 This <filename>minnow.scc</filename> description file is then
816 included in each of the three
817 "minnow" description files for the supported kernel types
818 (i.e. "standard", "preempt-rt", and "tiny").
819 Consider the "minnow" description for the "standard" kernel
820 type (i.e. <filename>minnow-standard.scc</filename>:
821 <literallayout class='monospaced'>
822 define KMACHINE minnow
823 define KTYPE standard
824 define KARCH i386
825
826 include ktypes/standard
827
828 include minnow.scc
829
830 # Extra minnow configs above the minimal defined in minnow.scc
831 include cfg/efi-ext.scc
832 include features/media/media-all.scc
833 include features/sound/snd_hda_intel.scc
834
835 # The following should really be in standard.scc
836 # USB live-image support
837 include cfg/usb-mass-storage.scc
838 include cfg/boot-live.scc
839
840 # Basic profiling
841 include features/latencytop/latencytop.scc
842 include features/profiling/profiling.scc
843
844 # Requested drivers that don't have an existing scc
845 kconf hardware minnow-drivers-extra.cfg
846 </literallayout>
847 The <filename>include</filename> command midway through the file
848 includes the <filename>minnow.scc</filename> description that
849 defines all enabled hardware for the BSP that is common to
850 all kernel types.
851 Using this command significantly reduces duplication.
852 </para>
853
854 <para>
855 Now consider the "minnow" description for the "tiny" kernel
856 type (i.e. <filename>minnow-tiny.scc</filename>):
857 <literallayout class='monospaced'>
858 define KMACHINE minnow
859 define KTYPE tiny
860 define KARCH i386
861
862 include ktypes/tiny
863
864 include minnow.scc
865 </literallayout>
866 As you might expect, the "tiny" description includes quite a
867 bit less.
868 In fact, it includes only the minimal policy defined by the
869 "tiny" kernel type and the hardware-specific configuration
870 required for booting the machine along with the most basic
871 functionality of the system as defined in the base "minnow"
872 description file.
873 </para>
874
875 <para>
876 Notice again the three critical variables:
877 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
878 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
879 and
880 <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>.
881 Of these variables, only <filename>KTYPE</filename>
882 has changed to specify the "tiny" kernel type.
883 </para>
884 </section>
885 </section>
886</section>
887
888<section id='kernel-metadata-location'>
889 <title>Kernel Metadata Location</title>
890
891 <para>
892 Kernel Metadata always exists outside of the kernel tree either
893 defined in a kernel recipe (recipe-space) or outside of the recipe.
894 Where you choose to define the Metadata depends on what you want
895 to do and how you intend to work.
896 Regardless of where you define the kernel Metadata, the syntax used
897 applies equally.
898 </para>
899
900 <para>
901 If you are unfamiliar with the Linux kernel and only wish
902 to apply a configuration and possibly a couple of patches provided to
903 you by others, the recipe-space method is recommended.
904 This method is also a good approach if you are working with Linux kernel
905 sources you do not control or if you just do not want to maintain a
906 Linux kernel Git repository on your own.
907 For partial information on how you can define kernel Metadata in
908 the recipe-space, see the
909 "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
910 section.
911 </para>
912
913 <para>
914 Conversely, if you are actively developing a kernel and are already
915 maintaining a Linux kernel Git repository of your own, you might find
916 it more convenient to work with kernel Metadata kept outside the
917 recipe-space.
918 Working with Metadata in this area can make iterative development of
919 the Linux kernel more efficient outside of the BitBake environment.
920 </para>
921
922 <section id='recipe-space-metadata'>
923 <title>Recipe-Space Metadata</title>
924
925 <para>
926 When stored in recipe-space, the kernel Metadata files reside in a
927 directory hierarchy below
928 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
929 For a linux-yocto recipe or for a Linux kernel recipe derived
930 by copying and modifying
931 <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
932 to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
933 is typically set to
934 <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>.
935 See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
936 section for more information.
937 </para>
938
939 <para>
940 Here is an example that shows a trivial tree of kernel Metadata
941 stored in recipe-space within a BSP layer:
942 <literallayout class='monospaced'>
943 meta-<replaceable>my_bsp_layer</replaceable>/
944 `-- recipes-kernel
945 `-- linux
946 `-- linux-yocto
947 |-- bsp-standard.scc
948 |-- bsp.cfg
949 `-- standard.cfg
950 </literallayout>
951 </para>
952
953 <para>
954 When the Metadata is stored in recipe-space, you must take
955 steps to ensure BitBake has the necessary information to decide
956 what files to fetch and when they need to be fetched again.
957 It is only necessary to specify the <filename>.scc</filename>
958 files on the
959 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
960 BitBake parses them and fetches any files referenced in the
961 <filename>.scc</filename> files by the <filename>include</filename>,
962 <filename>patch</filename>, or <filename>kconf</filename> commands.
963 Because of this, it is necessary to bump the recipe
964 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
965 value when changing the content of files not explicitly listed
966 in the <filename>SRC_URI</filename>.
967 </para>
968
969 <para>
970 If the BSP description is in recipe space, you cannot simply list
971 the <filename>*.scc</filename> in the <filename>SRC_URI</filename>
972 statement.
973 You need to use the following form from your kernel append file:
974 <literallayout class='monospaced'>
975 SRC_URI_append_<replaceable>myplatform</replaceable> = " \
976 file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \
977 "
978 </literallayout>
979 </para>
980 </section>
981
982 <section id='metadata-outside-the-recipe-space'>
983 <title>Metadata Outside the Recipe-Space</title>
984
985 <para>
986 When stored outside of the recipe-space, the kernel Metadata
987 files reside in a separate repository.
988 The OpenEmbedded build system adds the Metadata to the build as
989 a "type=kmeta" repository through the
990 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
991 variable.
992 As an example, consider the following <filename>SRC_URI</filename>
993 statement from the <filename>linux-yocto_4.12.bb</filename>
994 kernel recipe:
995 <literallayout class='monospaced'>
996 SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
997 git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
998 </literallayout>
999 <filename>${KMETA}</filename>, in this context, is simply used to
1000 name the directory into which the Git fetcher places the Metadata.
1001 This behavior is no different than any multi-repository
1002 <filename>SRC_URI</filename> statement used in a recipe (e.g.
1003 see the previous section).
1004 </para>
1005
1006 <para>
1007 You can keep kernel Metadata in a "kernel-cache", which is a
1008 directory containing configuration fragments.
1009 As with any Metadata kept outside the recipe-space, you simply
1010 need to use the <filename>SRC_URI</filename> statement with the
1011 "type=kmeta" attribute.
1012 Doing so makes the kernel Metadata available during the
1013 configuration phase.
1014 </para>
1015
1016 <para>
1017 If you modify the Metadata, you must not forget to update the
1018 <filename>SRCREV</filename> statements in the kernel's recipe.
1019 In particular, you need to update the
1020 <filename>SRCREV_meta</filename> variable to match the commit in
1021 the <filename>KMETA</filename> branch you wish to use.
1022 Changing the data in these branches and not updating the
1023 <filename>SRCREV</filename> statements to match will cause the
1024 build to fetch an older commit.
1025 </para>
1026 </section>
1027</section>
1028
1029<section id='organizing-your-source'>
1030 <title>Organizing Your Source</title>
1031
1032 <para>
1033 Many recipes based on the <filename>linux-yocto-custom.bb</filename>
1034 recipe use Linux kernel sources that have only a single
1035 branch - "master".
1036 This type of repository structure is fine for linear development
1037 supporting a single machine and architecture.
1038 However, if you work with multiple boards and architectures,
1039 a kernel source repository with multiple branches is more
1040 efficient.
1041 For example, suppose you need a series of patches for one board to boot.
1042 Sometimes, these patches are works-in-progress or fundamentally wrong,
1043 yet they are still necessary for specific boards.
1044 In these situations, you most likely do not want to include these
1045 patches in every kernel you build (i.e. have the patches as part of
1046 the lone "master" branch).
1047 It is situations like these that give rise to multiple branches used
1048 within a Linux kernel sources Git repository.
1049 </para>
1050
1051 <para>
1052 Repository organization strategies exist that maximize source reuse,
1053 remove redundancy, and logically order your changes.
1054 This section presents strategies for the following cases:
1055 <itemizedlist>
1056 <listitem><para>Encapsulating patches in a feature description
1057 and only including the patches in the BSP descriptions of
1058 the applicable boards.</para></listitem>
1059 <listitem><para>Creating a machine branch in your
1060 kernel source repository and applying the patches on that
1061 branch only.</para></listitem>
1062 <listitem><para>Creating a feature branch in your
1063 kernel source repository and merging that branch into your
1064 BSP when needed.</para></listitem>
1065 </itemizedlist>
1066 </para>
1067
1068 <para>
1069 The approach you take is entirely up to you
1070 and depends on what works best for your development model.
1071 </para>
1072
1073 <section id='encapsulating-patches'>
1074 <title>Encapsulating Patches</title>
1075
1076 <para>
1077 if you are reusing patches from an external tree and are not
1078 working on the patches, you might find the encapsulated feature
1079 to be appropriate.
1080 Given this scenario, you do not need to create any branches in the
1081 source repository.
1082 Rather, you just take the static patches you need and encapsulate
1083 them within a feature description.
1084 Once you have the feature description, you simply include that into
1085 the BSP description as described in the
1086 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
1087 section.
1088 </para>
1089
1090 <para>
1091 You can find information on how to create patches and BSP
1092 descriptions in the "<link linkend='patches'>Patches</link>" and
1093 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
1094 sections.
1095 </para>
1096 </section>
1097
1098 <section id='machine-branches'>
1099 <title>Machine Branches</title>
1100
1101 <para>
1102 When you have multiple machines and architectures to support,
1103 or you are actively working on board support, it is more
1104 efficient to create branches in the repository based on
1105 individual machines.
1106 Having machine branches allows common source to remain in the
1107 "master" branch with any features specific to a machine stored
1108 in the appropriate machine branch.
1109 This organization method frees you from continually reintegrating
1110 your patches into a feature.
1111 </para>
1112
1113 <para>
1114 Once you have a new branch, you can set up your kernel Metadata
1115 to use the branch a couple different ways.
1116 In the recipe, you can specify the new branch as the
1117 <filename>KBRANCH</filename> to use for the board as
1118 follows:
1119 <literallayout class='monospaced'>
1120 KBRANCH = "mynewbranch"
1121 </literallayout>
1122 Another method is to use the <filename>branch</filename> command
1123 in the BSP description:
1124 <literallayout class='monospaced'>
1125 mybsp.scc:
1126 define KMACHINE mybsp
1127 define KTYPE standard
1128 define KARCH i386
1129 include standard.scc
1130
1131 branch mynewbranch
1132
1133 include mybsp-hw.scc
1134 </literallayout>
1135 </para>
1136
1137 <para>
1138 If you find yourself with numerous branches, you might consider
1139 using a hierarchical branching system similar to what the
1140 Yocto Linux Kernel Git repositories use:
1141 <literallayout class='monospaced'>
1142 <replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable>
1143 </literallayout>
1144 </para>
1145
1146 <para>
1147 If you had two kernel types, "standard" and "small" for
1148 instance, three machines, and <replaceable>common</replaceable>
1149 as <filename>mydir</filename>, the branches in your
1150 Git repository might look like this:
1151 <literallayout class='monospaced'>
1152 mydir/base
1153 mydir/standard/base
1154 mydir/standard/machine_a
1155 mydir/standard/machine_b
1156 mydir/standard/machine_c
1157 mydir/small/base
1158 mydir/small/machine_a
1159 </literallayout>
1160 </para>
1161
1162 <para>
1163 This organization can help clarify the branch relationships.
1164 In this case, <filename>mydir/standard/machine_a</filename>
1165 includes everything in <filename>mydir/base</filename> and
1166 <filename>mydir/standard/base</filename>.
1167 The "standard" and "small" branches add sources specific to those
1168 kernel types that for whatever reason are not appropriate for the
1169 other branches.
1170 <note>
1171 The "base" branches are an artifact of the way Git manages
1172 its data internally on the filesystem: Git will not allow you
1173 to use <filename>mydir/standard</filename> and
1174 <filename>mydir/standard/machine_a</filename> because it
1175 would have to create a file and a directory named "standard".
1176 </note>
1177 </para>
1178 </section>
1179
1180 <section id='feature-branches'>
1181 <title>Feature Branches</title>
1182
1183 <para>
1184 When you are actively developing new features, it can be more
1185 efficient to work with that feature as a branch, rather than
1186 as a set of patches that have to be regularly updated.
1187 The Yocto Project Linux kernel tools provide for this with
1188 the <filename>git merge</filename> command.
1189 </para>
1190
1191 <para>
1192 To merge a feature branch into a BSP, insert the
1193 <filename>git merge</filename> command after any
1194 <filename>branch</filename> commands:
1195 <literallayout class='monospaced'>
1196 mybsp.scc:
1197 define KMACHINE mybsp
1198 define KTYPE standard
1199 define KARCH i386
1200 include standard.scc
1201
1202 branch mynewbranch
1203 git merge myfeature
1204
1205 include mybsp-hw.scc
1206 </literallayout>
1207 </para>
1208 </section>
1209</section>
1210
1211<section id='scc-reference'>
1212 <title>SCC Description File Reference</title>
1213
1214 <para>
1215 This section provides a brief reference for the commands you can use
1216 within an SCC description file (<filename>.scc</filename>):
1217 <itemizedlist>
1218 <listitem><para>
1219 <filename>branch [ref]</filename>:
1220 Creates a new branch relative to the current branch
1221 (typically <filename>${KTYPE}</filename>) using
1222 the currently checked-out branch, or "ref" if specified.
1223 </para></listitem>
1224 <listitem><para>
1225 <filename>define</filename>:
1226 Defines variables, such as
1227 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
1228 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
1229 <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>,
1230 and
1231 <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>.
1232 </para></listitem>
1233 <listitem><para>
1234 <filename>include SCC_FILE</filename>:
1235 Includes an SCC file in the current file.
1236 The file is parsed as if you had inserted it inline.
1237 </para></listitem>
1238 <listitem><para>
1239 <filename>kconf [hardware|non-hardware] CFG_FILE</filename>:
1240 Queues a configuration fragment for merging into the final
1241 Linux <filename>.config</filename> file.</para></listitem>
1242 <listitem><para>
1243 <filename>git merge GIT_BRANCH</filename>:
1244 Merges the feature branch into the current branch.
1245 </para></listitem>
1246 <listitem><para>
1247 <filename>patch PATCH_FILE</filename>:
1248 Applies the patch to the current Git branch.
1249 </para></listitem>
1250 </itemizedlist>
1251 </para>
1252</section>
1253
1254</chapter>
1255<!--
1256vim: expandtab tw=80 ts=4
1257-->
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
deleted file mode 100644
index 8e8a6dbed4..0000000000
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ /dev/null
@@ -1,2730 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='kernel-dev-common'>
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 your host development system for
13 kernel development, preparing a layer, modifying an existing recipe,
14 patching the kernel, configuring the kernel, iterative development,
15 working with your own sources, and incorporating out-of-tree modules.
16 <note>
17 The examples presented in this chapter work with the Yocto Project
18 2.4 Release and forward.
19 </note>
20 </para>
21
22 <section id='preparing-the-build-host-to-work-on-the-kernel'>
23 <title>Preparing the Build Host to Work on the Kernel</title>
24
25 <para>
26 Before you can do any kernel development, you need to be
27 sure your build host is set up to use the Yocto Project.
28 For information on how to get set up, see the
29 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
30 section in the Yocto Project Development Tasks Manual.
31 Part of preparing the system is creating a local Git
32 repository of the
33 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
34 (<filename>poky</filename>) on your system.
35 Follow the steps in the
36 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
37 section in the Yocto Project Development Tasks Manual to set up your
38 Source Directory.
39 <note>
40 Be sure you check out the appropriate development branch or
41 you create your local branch by checking out a specific tag
42 to get the desired version of Yocto Project.
43 See the
44 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
45 and
46 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
47 sections in the Yocto Project Development Tasks Manual for more
48 information.
49 </note>
50 </para>
51
52 <para>
53 Kernel development is best accomplished using
54 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
55 and not through traditional kernel workflow methods.
56 The remainder of this section provides information for both
57 scenarios.
58 </para>
59
60 <section id='getting-ready-to-develop-using-devtool'>
61 <title>Getting Ready to Develop Using <filename>devtool</filename></title>
62
63 <para>
64 Follow these steps to prepare to update the kernel image using
65 <filename>devtool</filename>.
66 Completing this procedure leaves you with a clean kernel image
67 and ready to make modifications as described in the
68 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
69 section:
70 <orderedlist>
71 <listitem><para>
72 <emphasis>Initialize the BitBake Environment:</emphasis>
73 Before building an extensible SDK, you need to
74 initialize the BitBake build environment by sourcing the
75 build environment script
76 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>):
77 <literallayout class='monospaced'>
78 $ cd ~/poky
79 $ source oe-init-build-env
80 </literallayout>
81 <note>
82 The previous commands assume the
83 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
84 (i.e. <filename>poky</filename>) have been cloned
85 using Git and the local repository is named
86 "poky".
87 </note>
88 </para></listitem>
89 <listitem><para>
90 <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis>
91 By default, the
92 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
93 variable is set to "qemux86-64", which is fine if you are
94 building for the QEMU emulator in 64-bit mode.
95 However, if you are not, you need to set the
96 <filename>MACHINE</filename> variable appropriately in
97 your <filename>conf/local.conf</filename> file found in
98 the
99 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
100 (i.e. <filename>~/poky/build</filename> in this
101 example).</para>
102
103 <para>Also, since you are preparing to work on the
104 kernel image, you need to set the
105 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
106 variable to include kernel modules.</para>
107
108 <para>In this example we wish to build for qemux86 so
109 we must set the <filename>MACHINE</filename> variable
110 to "qemux86" and also add the "kernel-modules". As described
111 we do this by appending to <filename>conf/local.conf</filename>:
112 <literallayout class='monospaced'>
113 MACHINE = "qemux86"
114 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
115 </literallayout>
116 </para></listitem>
117 <listitem><para>
118 <emphasis>Create a Layer for Patches:</emphasis>
119 You need to create a layer to hold patches created
120 for the kernel image.
121 You can use the
122 <filename>bitbake-layers create-layer</filename>
123 command as follows:
124 <literallayout class='monospaced'>
125 $ cd ~/poky/build
126 $ bitbake-layers create-layer ../../meta-mylayer
127 NOTE: Starting bitbake server...
128 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
129 $
130 </literallayout>
131 <note>
132 For background information on working with
133 common and BSP layers, see the
134 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
135 section in the Yocto Project Development Tasks
136 Manual and the
137 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
138 section in the Yocto Project Board Support (BSP)
139 Developer's Guide, respectively.
140 For information on how to use the
141 <filename>bitbake-layers create-layer</filename>
142 command to quickly set up a layer, see the
143 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
144 section in the Yocto Project Development Tasks
145 Manual.
146 </note>
147 </para></listitem>
148 <listitem><para>
149 <emphasis>Inform the BitBake Build Environment About
150 Your Layer:</emphasis>
151 As directed when you created your layer, you need to
152 add the layer to the
153 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
154 variable in the <filename>bblayers.conf</filename> file
155 as follows:
156 <literallayout class='monospaced'>
157 $ cd ~/poky/build
158 $ bitbake-layers add-layer ../../meta-mylayer
159 NOTE: Starting bitbake server...
160 $
161 </literallayout>
162 </para></listitem>
163 <listitem><para>
164 <emphasis>Build the Extensible SDK:</emphasis>
165 Use BitBake to build the extensible SDK specifically
166 for use with images to be run using QEMU:
167 <literallayout class='monospaced'>
168 $ cd ~/poky/build
169 $ bitbake core-image-minimal -c populate_sdk_ext
170 </literallayout>
171 Once the build finishes, you can find the SDK installer
172 file (i.e. <filename>*.sh</filename> file) in the
173 following directory:
174 <literallayout class='monospaced'>
175 ~/poky/build/tmp/deploy/sdk
176 </literallayout>
177 For this example, the installer file is named
178 <filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename>
179 </para></listitem>
180 <listitem><para>
181 <emphasis>Install the Extensible SDK:</emphasis>
182 Use the following command to install the SDK.
183 For this example, install the SDK in the default
184 <filename>~/poky_sdk</filename> directory:
185 <literallayout class='monospaced'>
186 $ cd ~/poky/build/tmp/deploy/sdk
187 $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
188 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
189 ============================================================================
190 Enter target directory for SDK (default: ~/poky_sdk):
191 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
192 Extracting SDK......................................done
193 Setting it up...
194 Extracting buildtools...
195 Preparing build system...
196 Parsing recipes: 100% |#################################################################| Time: 0:00:52
197 Initializing tasks: 100% |############## ###############################################| Time: 0:00:04
198 Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00
199 Parsing recipes: 100% |#################################################################| Time: 0:00:33
200 Initializing tasks: 100% |##############################################################| Time: 0:00:00
201 done
202 SDK has been successfully set up and is ready to be used.
203 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
204 $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
205 </literallayout>
206 </para></listitem>
207 <listitem><para id='setting-up-the-esdk-terminal'>
208 <emphasis>Set Up a New Terminal to Work With the
209 Extensible SDK:</emphasis>
210 You must set up a new terminal to work with the SDK.
211 You cannot use the same BitBake shell used to build the
212 installer.</para>
213
214 <para>After opening a new shell, run the SDK environment
215 setup script as directed by the output from installing
216 the SDK:
217 <literallayout class='monospaced'>
218 $ source ~/poky_sdk/environment-setup-i586-poky-linux
219 "SDK environment now set up; additionally you may now run devtool to perform development tasks.
220 Run devtool --help for further details.
221 </literallayout>
222 <note>
223 If you get a warning about attempting to use the
224 extensible SDK in an environment set up to run
225 BitBake, you did not use a new shell.
226 </note>
227 </para></listitem>
228 <listitem><para>
229 <emphasis>Build the Clean Image:</emphasis>
230 The final step in preparing to work on the kernel is to
231 build an initial image using
232 <filename>devtool</filename> in the new terminal you
233 just set up and initialized for SDK work:
234 <literallayout class='monospaced'>
235 $ devtool build-image
236 Parsing recipes: 100% |##########################################| Time: 0:00:05
237 Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
238 WARNING: No packages to add, building image core-image-minimal unmodified
239 Loading cache: 100% |############################################| Time: 0:00:00
240 Loaded 1299 entries from dependency cache.
241 NOTE: Resolving any missing task queue dependencies
242 Initializing tasks: 100% |#######################################| Time: 0:00:07
243 Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
244 NOTE: Executing SetScene Tasks
245 NOTE: Executing RunQueue Tasks
246 NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
247 NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
248 </literallayout>
249 If you were building for actual hardware and not for
250 emulation, you could flash the image to a USB stick
251 on <filename>/dev/sdd</filename> and boot your device.
252 For an example that uses a Minnowboard, see the
253 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
254 Wiki page.
255 </para></listitem>
256 </orderedlist>
257 </para>
258
259 <para>
260 At this point you have set up to start making modifications to
261 the kernel by using the extensible SDK.
262 For a continued example, see the
263 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
264 section.
265 </para>
266 </section>
267
268 <section id='getting-ready-for-traditional-kernel-development'>
269 <title>Getting Ready for Traditional Kernel Development</title>
270
271 <para>
272 Getting ready for traditional kernel development using the Yocto
273 Project involves many of the same steps as described in the
274 previous section.
275 However, you need to establish a local copy of the kernel source
276 since you will be editing these files.
277 </para>
278
279 <para>
280 Follow these steps to prepare to update the kernel image using
281 traditional kernel development flow with the Yocto Project.
282 Completing this procedure leaves you ready to make modifications
283 to the kernel source as described in the
284 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
285 section:
286 <orderedlist>
287 <listitem><para>
288 <emphasis>Initialize the BitBake Environment:</emphasis>
289 Before you can do anything using BitBake, you need to
290 initialize the BitBake build environment by sourcing the
291 build environment script
292 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>).
293 Also, for this example, be sure that the local branch
294 you have checked out for <filename>poky</filename> is
295 the Yocto Project &DISTRO_NAME; branch.
296 If you need to checkout out the &DISTRO_NAME; branch,
297 see the
298 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking out by Branch in Poky</ulink>"
299 section in the Yocto Project Development Tasks Manual.
300 <literallayout class='monospaced'>
301 $ cd ~/poky
302 $ git branch
303 master
304 * &DISTRO_NAME;
305 $ source oe-init-build-env
306 </literallayout>
307 <note>
308 The previous commands assume the
309 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
310 (i.e. <filename>poky</filename>) have been cloned
311 using Git and the local repository is named
312 "poky".
313 </note>
314 </para></listitem>
315 <listitem><para>
316 <emphasis>Prepare Your <filename>local.conf</filename>
317 File:</emphasis>
318 By default, the
319 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
320 variable is set to "qemux86-64", which is fine if you are
321 building for the QEMU emulator in 64-bit mode.
322 However, if you are not, you need to set the
323 <filename>MACHINE</filename> variable appropriately in
324 your <filename>conf/local.conf</filename> file found
325 in the
326 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
327 (i.e. <filename>~/poky/build</filename> in this
328 example).</para>
329
330 <para>Also, since you are preparing to work on the
331 kernel image, you need to set the
332 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
333 variable to include kernel modules.</para>
334
335 <para>In this example we wish to build for qemux86 so
336 we must set the <filename>MACHINE</filename> variable
337 to "qemux86" and also add the "kernel-modules". As described
338 we do this by appending to <filename>conf/local.conf</filename>:
339 <literallayout class='monospaced'>
340 MACHINE = "qemux86"
341 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
342 </literallayout>
343 </para></listitem>
344 <listitem><para>
345 <emphasis>Create a Layer for Patches:</emphasis>
346 You need to create a layer to hold patches created
347 for the kernel image.
348 You can use the
349 <filename>bitbake-layers create-layer</filename>
350 command as follows:
351 <literallayout class='monospaced'>
352 $ cd ~/poky/build
353 $ bitbake-layers create-layer ../../meta-mylayer
354 NOTE: Starting bitbake server...
355 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
356 </literallayout>
357 <note>
358 For background information on working with
359 common and BSP layers, see the
360 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
361 section in the Yocto Project Development Tasks
362 Manual and the
363 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
364 section in the Yocto Project Board Support (BSP)
365 Developer's Guide, respectively.
366 For information on how to use the
367 <filename>bitbake-layers create-layer</filename>
368 command to quickly set up a layer, see the
369 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
370 section in the Yocto Project Development Tasks
371 Manual.
372 </note>
373 </para></listitem>
374 <listitem><para>
375 <emphasis>Inform the BitBake Build Environment About
376 Your Layer:</emphasis>
377 As directed when you created your layer, you need to add
378 the layer to the
379 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
380 variable in the <filename>bblayers.conf</filename> file
381 as follows:
382 <literallayout class='monospaced'>
383 $ cd ~/poky/build
384 $ bitbake-layers add-layer ../../meta-mylayer
385 NOTE: Starting bitbake server ...
386 $
387 </literallayout>
388 </para></listitem>
389 <listitem><para>
390 <emphasis>Create a Local Copy of the Kernel Git
391 Repository:</emphasis>
392 You can find Git repositories of supported Yocto Project
393 kernels organized under "Yocto Linux Kernel" in the
394 Yocto Project Source Repositories at
395 <ulink url='&YOCTO_GIT_URL;'></ulink>.
396 </para>
397
398 <para>
399 For simplicity, it is recommended that you create your
400 copy of the kernel Git repository outside of the
401 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
402 which is usually named <filename>poky</filename>.
403 Also, be sure you are in the
404 <filename>standard/base</filename> branch.
405 </para>
406
407 <para>
408 The following commands show how to create a local copy
409 of the <filename>linux-yocto-4.12</filename> kernel and
410 be in the <filename>standard/base</filename> branch.
411 <note>
412 The <filename>linux-yocto-4.12</filename> kernel
413 can be used with the Yocto Project 2.4 release
414 and forward.
415 You cannot use the
416 <filename>linux-yocto-4.12</filename> kernel with
417 releases prior to Yocto Project 2.4:
418 </note>
419 <literallayout class='monospaced'>
420 $ cd ~
421 $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base
422 Cloning into 'linux-yocto-4.12'...
423 remote: Counting objects: 6097195, done.
424 remote: Compressing objects: 100% (901026/901026), done.
425 remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256)
426 Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done.
427 Resolving deltas: 100% (5152604/5152604), done.
428 Checking connectivity... done.
429 Checking out files: 100% (59846/59846), done.
430 </literallayout>
431 </para></listitem>
432 <listitem><para>
433 <emphasis>Create a Local Copy of the Kernel Cache Git
434 Repository:</emphasis>
435 For simplicity, it is recommended that you create your
436 copy of the kernel cache Git repository outside of the
437 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
438 which is usually named <filename>poky</filename>.
439 Also, for this example, be sure you are in the
440 <filename>yocto-4.12</filename> branch.
441 </para>
442
443 <para>
444 The following commands show how to create a local copy
445 of the <filename>yocto-kernel-cache</filename> and
446 be in the <filename>yocto-4.12</filename> branch:
447 <literallayout class='monospaced'>
448 $ cd ~
449 $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
450 Cloning into 'yocto-kernel-cache'...
451 remote: Counting objects: 22639, done.
452 remote: Compressing objects: 100% (9761/9761), done.
453 remote: Total 22639 (delta 12400), reused 22586 (delta 12347)
454 Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done.
455 Resolving deltas: 100% (12400/12400), done.
456 Checking connectivity... done.
457 </literallayout>
458 </para></listitem>
459 </orderedlist>
460 </para>
461
462 <para>
463 At this point, you are ready to start making modifications to
464 the kernel using traditional kernel development steps.
465 For a continued example, see the
466 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
467 section.
468 </para>
469 </section>
470 </section>
471
472 <section id='creating-and-preparing-a-layer'>
473 <title>Creating and Preparing a Layer</title>
474
475 <para>
476 If you are going to be modifying kernel recipes, it is recommended
477 that you create and prepare your own layer in which to do your
478 work.
479 Your layer contains its own
480 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
481 append files (<filename>.bbappend</filename>) and provides a
482 convenient mechanism to create your own recipe files
483 (<filename>.bb</filename>) as well as store and use kernel
484 patch files.
485 For background information on working with layers, see the
486 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
487 section in the Yocto Project Development Tasks Manual.
488 <note><title>Tip</title>
489 The Yocto Project comes with many tools that simplify
490 tasks you need to perform.
491 One such tool is the
492 <filename>bitbake-layers create-layer</filename>
493 command, which simplifies creating a new layer.
494 See the
495 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
496 section in the Yocto Project Development Tasks Manual for
497 information on how to use this script to quick set up a
498 new layer.
499 </note>
500 </para>
501
502 <para>
503 To better understand the layer you create for kernel development,
504 the following section describes how to create a layer
505 without the aid of tools.
506 These steps assume creation of a layer named
507 <filename>mylayer</filename> in your home directory:
508 <orderedlist>
509 <listitem><para>
510 <emphasis>Create Structure</emphasis>:
511 Create the layer's structure:
512 <literallayout class='monospaced'>
513 $ cd $HOME
514 $ mkdir meta-mylayer
515 $ mkdir meta-mylayer/conf
516 $ mkdir meta-mylayer/recipes-kernel
517 $ mkdir meta-mylayer/recipes-kernel/linux
518 $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto
519 </literallayout>
520 The <filename>conf</filename> directory holds your
521 configuration files, while the
522 <filename>recipes-kernel</filename> directory holds your
523 append file and eventual patch files.
524 </para></listitem>
525 <listitem><para>
526 <emphasis>Create the Layer Configuration File</emphasis>:
527 Move to the <filename>meta-mylayer/conf</filename>
528 directory and create the <filename>layer.conf</filename>
529 file as follows:
530 <literallayout class='monospaced'>
531 # We have a conf and classes directory, add to BBPATH
532 BBPATH .= ":${LAYERDIR}"
533
534 # We have recipes-* directories, add to BBFILES
535 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
536 ${LAYERDIR}/recipes-*/*/*.bbappend"
537
538 BBFILE_COLLECTIONS += "mylayer"
539 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
540 BBFILE_PRIORITY_mylayer = "5"
541 </literallayout>
542 Notice <filename>mylayer</filename> as part of the last
543 three statements.
544 </para></listitem>
545 <listitem><para>
546 <emphasis>Create the Kernel Recipe Append File</emphasis>:
547 Move to the
548 <filename>meta-mylayer/recipes-kernel/linux</filename>
549 directory and create the kernel's append file.
550 This example uses the
551 <filename>linux-yocto-4.12</filename> kernel.
552 Thus, the name of the append file is
553 <filename>linux-yocto_4.12.bbappend</filename>:
554 <literallayout class='monospaced'>
555 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
556
557 SRC_URI_append = " file://<replaceable>patch-file-one</replaceable>"
558 SRC_URI_append = " file://<replaceable>patch-file-two</replaceable>"
559 SRC_URI_append = " file://<replaceable>patch-file-three</replaceable>"
560 </literallayout>
561 The
562 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
563 and
564 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
565 statements enable the OpenEmbedded build system to find
566 patch files.
567 For more information on using append files, see the
568 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
569 section in the Yocto Project Development Tasks Manual.
570 </para></listitem>
571 </orderedlist>
572 </para>
573 </section>
574
575 <section id='modifying-an-existing-recipe'>
576 <title>Modifying an Existing Recipe</title>
577
578 <para>
579 In many cases, you can customize an existing linux-yocto recipe to
580 meet the needs of your project.
581 Each release of the Yocto Project provides a few Linux
582 kernel recipes from which you can choose.
583 These are located in the
584 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
585 in <filename>meta/recipes-kernel/linux</filename>.
586 </para>
587
588 <para>
589 Modifying an existing recipe can consist of the following:
590 <itemizedlist>
591 <listitem><para>Creating the append file</para></listitem>
592 <listitem><para>Applying patches</para></listitem>
593 <listitem><para>Changing the configuration</para></listitem>
594 </itemizedlist>
595 </para>
596
597 <para>
598 Before modifying an existing recipe, be sure that you have created
599 a minimal, custom layer from which you can work.
600 See the
601 "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
602 section for information.
603 </para>
604
605 <section id='creating-the-append-file'>
606 <title>Creating the Append File</title>
607
608 <para>
609 You create this file in your custom layer.
610 You also name it accordingly based on the linux-yocto recipe
611 you are using.
612 For example, if you are modifying the
613 <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
614 recipe, the append file will typically be located as follows
615 within your custom layer:
616 <literallayout class='monospaced'>
617 <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.12.bbappend
618 </literallayout>
619 The append file should initially extend the
620 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
621 search path by prepending the directory that contains your
622 files to the
623 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
624 variable as follows:
625 <literallayout class='monospaced'>
626 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
627 </literallayout>
628 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>
629 expands to "linux-yocto" in the current directory for this
630 example.
631 If you add any new files that modify the kernel recipe and you
632 have extended <filename>FILESPATH</filename> as
633 described above, you must place the files in your layer in the
634 following area:
635 <literallayout class='monospaced'>
636 <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/
637 </literallayout>
638 <note>If you are working on a new machine Board Support Package
639 (BSP), be sure to refer to the
640 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
641 </note>
642 </para>
643
644 <para>
645 As an example, consider the following append file
646 used by the BSPs in <filename>meta-yocto-bsp</filename>:
647 <literallayout class='monospaced'>
648 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
649 </literallayout>
650 The following listing shows the file.
651 Be aware that the actual commit ID strings in this
652 example listing might be different than the actual strings
653 in the file from the <filename>meta-yocto-bsp</filename>
654 layer upstream.
655 <literallayout class='monospaced'>
656 KBRANCH_genericx86 = "standard/base"
657 KBRANCH_genericx86-64 = "standard/base"
658
659 KMACHINE_genericx86 ?= "common-pc"
660 KMACHINE_genericx86-64 ?= "common-pc-64"
661 KBRANCH_edgerouter = "standard/edgerouter"
662 KBRANCH_beaglebone = "standard/beaglebone"
663
664 SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
665 SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
666 SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
667 SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
668
669
670 COMPATIBLE_MACHINE_genericx86 = "genericx86"
671 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
672 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
673 COMPATIBLE_MACHINE_beaglebone = "beaglebone"
674
675 LINUX_VERSION_genericx86 = "4.12.7"
676 LINUX_VERSION_genericx86-64 = "4.12.7"
677 LINUX_VERSION_edgerouter = "4.12.10"
678 LINUX_VERSION_beaglebone = "4.12.10"
679 </literallayout>
680 This append file contains statements used to support
681 several BSPs that ship with the Yocto Project.
682 The file defines machines using the
683 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
684 variable and uses the
685 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
686 variable to ensure the machine name used by the OpenEmbedded
687 build system maps to the machine name used by the Linux Yocto
688 kernel.
689 The file also uses the optional
690 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
691 variable to ensure the build process uses the
692 appropriate kernel branch.
693 </para>
694
695 <para>
696 Although this particular example does not use it, the
697 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
698 variable could be used to enable features specific to
699 the kernel.
700 The append file points to specific commits in the
701 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
702 Git repository and the <filename>meta</filename> Git repository
703 branches to identify the exact kernel needed to build the
704 BSP.
705 </para>
706
707 <para>
708 One thing missing in this particular BSP, which you will
709 typically need when developing a BSP, is the kernel
710 configuration file (<filename>.config</filename>) for your BSP.
711 When developing a BSP, you probably have a kernel configuration
712 file or a set of kernel configuration files that, when taken
713 together, define the kernel configuration for your BSP.
714 You can accomplish this definition by putting the configurations
715 in a file or a set of files inside a directory located at the
716 same level as your kernel's append file and having the same
717 name as the kernel's main recipe file.
718 With all these conditions met, simply reference those files in
719 the
720 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
721 statement in the append file.
722 </para>
723
724 <para>
725 For example, suppose you had some configuration options
726 in a file called <filename>network_configs.cfg</filename>.
727 You can place that file inside a directory named
728 <filename>linux-yocto</filename> and then add
729 a <filename>SRC_URI</filename> statement such as the
730 following to the append file.
731 When the OpenEmbedded build system builds the kernel, the
732 configuration options are picked up and applied.
733 <literallayout class='monospaced'>
734 SRC_URI += "file://network_configs.cfg"
735 </literallayout>
736 </para>
737
738 <para>
739 To group related configurations into multiple files, you
740 perform a similar procedure.
741 Here is an example that groups separate configurations
742 specifically for Ethernet and graphics into their own
743 files and adds the configurations by using a
744 <filename>SRC_URI</filename> statement like the following
745 in your append file:
746 <literallayout class='monospaced'>
747 SRC_URI += "file://myconfig.cfg \
748 file://eth.cfg \
749 file://gfx.cfg"
750 </literallayout>
751 </para>
752
753 <para>
754 Another variable you can use in your kernel recipe append
755 file is the
756 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
757 variable.
758 When you use this statement, you are extending the locations
759 used by the OpenEmbedded system to look for files and
760 patches as the recipe is processed.
761 </para>
762
763 <note>
764 <para>
765 Other methods exist to accomplish grouping and defining
766 configuration options.
767 For example, if you are working with a local clone of the
768 kernel repository, you could checkout the kernel's
769 <filename>meta</filename> branch, make your changes, and
770 then push the changes to the local bare clone of the
771 kernel.
772 The result is that you directly add configuration options
773 to the <filename>meta</filename> branch for your BSP.
774 The configuration options will likely end up in that
775 location anyway if the BSP gets added to the Yocto Project.
776 </para>
777
778 <para>
779 In general, however, the Yocto Project maintainers take
780 care of moving the <filename>SRC_URI</filename>-specified
781 configuration options to the kernel's
782 <filename>meta</filename> branch.
783 Not only is it easier for BSP developers to not have to
784 worry about putting those configurations in the branch,
785 but having the maintainers do it allows them to apply
786 'global' knowledge about the kinds of common configuration
787 options multiple BSPs in the tree are typically using.
788 This allows for promotion of common configurations into
789 common features.
790 </para>
791 </note>
792 </section>
793
794 <section id='applying-patches'>
795 <title>Applying Patches</title>
796
797 <para>
798 If you have a single patch or a small series of patches
799 that you want to apply to the Linux kernel source, you
800 can do so just as you would with any other recipe.
801 You first copy the patches to the path added to
802 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
803 in your <filename>.bbappend</filename> file as described in
804 the previous section, and then reference them in
805 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
806 statements.
807 </para>
808
809 <para>
810 For example, you can apply a three-patch series by adding the
811 following lines to your linux-yocto
812 <filename>.bbappend</filename> file in your layer:
813 <literallayout class='monospaced'>
814 SRC_URI += "file://0001-first-change.patch"
815 SRC_URI += "file://0002-second-change.patch"
816 SRC_URI += "file://0003-third-change.patch"
817 </literallayout>
818 The next time you run BitBake to build the Linux kernel,
819 BitBake detects the change in the recipe and fetches and
820 applies the patches before building the kernel.
821 </para>
822
823 <para>
824 For a detailed example showing how to patch the kernel using
825 <filename>devtool</filename>, see the
826 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
827 and
828 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
829 sections.
830 </para>
831 </section>
832
833 <section id='changing-the-configuration'>
834 <title>Changing the Configuration</title>
835
836 <para>
837 You can make wholesale or incremental changes to the final
838 <filename>.config</filename> file used for the eventual
839 Linux kernel configuration by including a
840 <filename>defconfig</filename> file and by specifying
841 configuration fragments in the
842 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
843 to be applied to that file.
844 </para>
845
846 <para>
847 If you have a complete, working Linux kernel
848 <filename>.config</filename>
849 file you want to use for the configuration, as before, copy
850 that file to the appropriate <filename>${PN}</filename>
851 directory in your layer's
852 <filename>recipes-kernel/linux</filename> directory,
853 and rename the copied file to "defconfig".
854 Then, add the following lines to the linux-yocto
855 <filename>.bbappend</filename> file in your layer:
856 <literallayout class='monospaced'>
857 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
858 SRC_URI += "file://defconfig"
859 </literallayout>
860 The <filename>SRC_URI</filename> tells the build system how to
861 search for the file, while the
862 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
863 extends the
864 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
865 variable (search directories) to include the
866 <filename>${PN}</filename> directory you created to hold the
867 configuration changes.
868 </para>
869
870 <note>
871 The build system applies the configurations from the
872 <filename>defconfig</filename> file before applying any
873 subsequent configuration fragments.
874 The final kernel configuration is a combination of the
875 configurations in the <filename>defconfig</filename> file and
876 any configuration fragments you provide.
877 You need to realize that if you have any configuration
878 fragments, the build system applies these on top of and
879 after applying the existing <filename>defconfig</filename>
880 file configurations.
881 </note>
882
883 <para>
884 Generally speaking, the preferred approach is to determine the
885 incremental change you want to make and add that as a
886 configuration fragment.
887 For example, if you want to add support for a basic serial
888 console, create a file named <filename>8250.cfg</filename> in
889 the <filename>${PN}</filename> directory with the following
890 content (without indentation):
891 <literallayout class='monospaced'>
892 CONFIG_SERIAL_8250=y
893 CONFIG_SERIAL_8250_CONSOLE=y
894 CONFIG_SERIAL_8250_PCI=y
895 CONFIG_SERIAL_8250_NR_UARTS=4
896 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
897 CONFIG_SERIAL_CORE=y
898 CONFIG_SERIAL_CORE_CONSOLE=y
899 </literallayout>
900 Next, include this configuration fragment and extend the
901 <filename>FILESPATH</filename> variable in your
902 <filename>.bbappend</filename> file:
903 <literallayout class='monospaced'>
904 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
905 SRC_URI += "file://8250.cfg"
906 </literallayout>
907 The next time you run BitBake to build the Linux kernel, BitBake
908 detects the change in the recipe and fetches and applies the
909 new configuration before building the kernel.
910 </para>
911
912 <para>
913 For a detailed example showing how to configure the kernel,
914 see the
915 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
916 section.
917 </para>
918 </section>
919
920 <section id='using-an-in-tree-defconfig-file'>
921 <title>Using an "In-Tree"&nbsp;&nbsp;<filename>defconfig</filename> File</title>
922
923 <para>
924 It might be desirable to have kernel configuration fragment
925 support through a <filename>defconfig</filename> file that
926 is pulled from the kernel source tree for the configured
927 machine.
928 By default, the OpenEmbedded build system looks for
929 <filename>defconfig</filename> files in the layer used for
930 Metadata, which is "out-of-tree", and then configures them
931 using the following:
932 <literallayout class='monospaced'>
933 SRC_URI += "file://defconfig"
934 </literallayout>
935 If you do not want to maintain copies of
936 <filename>defconfig</filename> files in your layer but would
937 rather allow users to use the default configuration from the
938 kernel tree and still be able to add configuration fragments
939 to the
940 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
941 through, for example, append files, you can direct the
942 OpenEmbedded build system to use a
943 <filename>defconfig</filename> file that is "in-tree".
944 </para>
945
946 <para>
947 To specify an "in-tree" <filename>defconfig</filename> file,
948 use the following statement form:
949 <literallayout class='monospaced'>
950 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
951 </literallayout>
952 Here is an example that assigns the
953 <filename>KBUILD_DEFCONFIG</filename> variable based on
954 "raspberrypi2" and provides the path to the "in-tree"
955 <filename>defconfig</filename> file
956 to be used for a Raspberry Pi 2,
957 which is based on the Broadcom 2708/2709 chipset:
958 <literallayout class='monospaced'>
959 KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig"
960 </literallayout>
961 </para>
962
963 <para>
964 Aside from modifying your kernel recipe and providing your own
965 <filename>defconfig</filename> file, you need to be sure no
966 files or statements set <filename>SRC_URI</filename> to use a
967 <filename>defconfig</filename> other than your "in-tree"
968 file (e.g. a kernel's
969 <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename>
970 file).
971 In other words, if the build system detects a statement
972 that identifies an "out-of-tree"
973 <filename>defconfig</filename> file, that statement
974 will override your
975 <filename>KBUILD_DEFCONFIG</filename> variable.
976 </para>
977
978 <para>
979 See the
980 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink>
981 variable description for more information.
982 </para>
983 </section>
984 </section>
985
986 <section id="using-devtool-to-patch-the-kernel">
987 <title>Using <filename>devtool</filename> to Patch the Kernel</title>
988
989 <para>
990 The steps in this procedure show you how you can patch the
991 kernel using the extensible SDK and <filename>devtool</filename>.
992 <note>
993 Before attempting this procedure, be sure you have performed
994 the steps to get ready for updating the kernel as described
995 in the
996 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
997 section.
998 </note>
999 </para>
1000
1001 <para>
1002 Patching the kernel involves changing or adding configurations
1003 to an existing kernel, changing or adding recipes to the kernel
1004 that are needed to support specific hardware features, or even
1005 altering the source code itself.
1006 </para>
1007
1008 <para>
1009 This example creates a simple patch by adding some QEMU emulator
1010 console output at boot time through <filename>printk</filename>
1011 statements in the kernel's <filename>calibrate.c</filename> source
1012 code file.
1013 Applying the patch and booting the modified image causes the added
1014 messages to appear on the emulator's console.
1015 The example is a continuation of the setup procedure found in
1016 the
1017 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
1018 Section.
1019 <orderedlist>
1020 <listitem><para>
1021 <emphasis>Check Out the Kernel Source Files:</emphasis>
1022 First you must use <filename>devtool</filename> to checkout
1023 the kernel source code in its workspace.
1024 Be sure you are in the terminal set up to do work
1025 with the extensible SDK.
1026 <note>
1027 See this
1028 <link linkend='setting-up-the-esdk-terminal'>step</link>
1029 in the
1030 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
1031 section for more information.
1032 </note>
1033 Use the following <filename>devtool</filename> command
1034 to check out the code:
1035 <literallayout class='monospaced'>
1036 $ devtool modify linux-yocto
1037 </literallayout>
1038 <note>
1039 During the checkout operation, a bug exists that could
1040 cause errors such as the following to appear:
1041 <literallayout class='monospaced'>
1042 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
1043 be3a89ce7c47178880ba7bf6293d7404 for
1044 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
1045 </literallayout>
1046 You can safely ignore these messages.
1047 The source code is correctly checked out.
1048 </note>
1049 </para></listitem>
1050 <listitem><para>
1051 <emphasis>Edit the Source Files</emphasis>
1052 Follow these steps to make some simple changes to the source
1053 files:
1054 <orderedlist>
1055 <listitem><para>
1056 <emphasis>Change the working directory</emphasis>:
1057 In the previous step, the output noted where you can find
1058 the source files (e.g.
1059 <filename>~/poky_sdk/workspace/sources/linux-yocto</filename>).
1060 Change to where the kernel source code is before making
1061 your edits to the <filename>calibrate.c</filename> file:
1062 <literallayout class='monospaced'>
1063 $ cd ~/poky_sdk/workspace/sources/linux-yocto
1064 </literallayout>
1065 </para></listitem>
1066 <listitem><para>
1067 <emphasis>Edit the source file</emphasis>:
1068 Edit the <filename>init/calibrate.c</filename> file to have
1069 the following changes:
1070 <literallayout class='monospaced'>
1071 void calibrate_delay(void)
1072 {
1073 unsigned long lpj;
1074 static bool printed;
1075 int this_cpu = smp_processor_id();
1076
1077 printk("*************************************\n");
1078 printk("* *\n");
1079 printk("* HELLO YOCTO KERNEL *\n");
1080 printk("* *\n");
1081 printk("*************************************\n");
1082
1083 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
1084 .
1085 .
1086 .
1087 </literallayout>
1088 </para></listitem>
1089 </orderedlist>
1090 </para></listitem>
1091 <listitem><para>
1092 <emphasis>Build the Updated Kernel Source:</emphasis>
1093 To build the updated kernel source, use
1094 <filename>devtool</filename>:
1095 <literallayout class='monospaced'>
1096 $ devtool build linux-yocto
1097 </literallayout>
1098 </para></listitem>
1099 <listitem><para>
1100 <emphasis>Create the Image With the New Kernel:</emphasis>
1101 Use the <filename>devtool build-image</filename> command
1102 to create a new image that has the new kernel.
1103 <note>
1104 If the image you originally created resulted in a Wic
1105 file, you can use an alternate method to create the new
1106 image with the updated kernel.
1107 For an example, see the steps in the
1108 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
1109 Wiki Page.
1110 </note>
1111 <literallayout class='monospaced'>
1112 $ cd ~
1113 $ devtool build-image core-image-minimal
1114 </literallayout>
1115 </para></listitem>
1116 <listitem><para>
1117 <emphasis>Test the New Image:</emphasis>
1118 For this example, you can run the new image using QEMU
1119 to verify your changes:
1120 <orderedlist>
1121 <listitem><para>
1122 <emphasis>Boot the image</emphasis>:
1123 Boot the modified image in the QEMU emulator
1124 using this command:
1125 <literallayout class='monospaced'>
1126 $ runqemu qemux86
1127 </literallayout>
1128 </para></listitem>
1129 <listitem><para>
1130 <emphasis>Verify the changes</emphasis>:
1131 Log into the machine using <filename>root</filename>
1132 with no password and then use the following shell
1133 command to scroll through the console's boot output.
1134 <literallayout class='monospaced'>
1135 # dmesg | less
1136 </literallayout>
1137 You should see the results of your
1138 <filename>printk</filename> statements
1139 as part of the output when you scroll down the
1140 console window.
1141 </para></listitem>
1142 </orderedlist>
1143 </para></listitem>
1144 <listitem><para>
1145 <emphasis>Stage and commit your changes</emphasis>:
1146 Within your eSDK terminal, change your working directory to
1147 where you modified the <filename>calibrate.c</filename>
1148 file and use these Git commands to stage and commit your
1149 changes:
1150 <literallayout class='monospaced'>
1151 $ cd ~/poky_sdk/workspace/sources/linux-yocto
1152 $ git status
1153 $ git add init/calibrate.c
1154 $ git commit -m "calibrate: Add printk example"
1155 </literallayout>
1156 </para></listitem>
1157 <listitem><para>
1158 <emphasis>Export the Patches and Create an Append File:</emphasis>
1159 To export your commits as patches and create a
1160 <filename>.bbappend</filename> file, use the following
1161 command in the terminal used to work with the extensible
1162 SDK.
1163 This example uses the previously established layer named
1164 <filename>meta-mylayer</filename>.
1165 <note>
1166 See Step 3 of the
1167 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using devtool</link>"
1168 section for information on setting up this layer.
1169 </note>
1170 <literallayout class='monospaced'>
1171 $ devtool finish linux-yocto ~/meta-mylayer
1172 </literallayout>
1173 Once the command finishes, the patches and the
1174 <filename>.bbappend</filename> file are located in the
1175 <filename>~/meta-mylayer/recipes-kernel/linux</filename>
1176 directory.
1177 </para></listitem>
1178 <listitem><para>
1179 <emphasis>Build the Image With Your Modified Kernel:</emphasis>
1180 You can now build an image that includes your kernel
1181 patches.
1182 Execute the following command from your
1183 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
1184 in the terminal set up to run BitBake:
1185 <literallayout class='monospaced'>
1186 $ cd ~/poky/build
1187 $ bitbake core-image-minimal
1188 </literallayout>
1189 </para></listitem>
1190 </orderedlist>
1191 </para>
1192 </section>
1193
1194 <section id="using-traditional-kernel-development-to-patch-the-kernel">
1195 <title>Using Traditional Kernel Development to Patch the Kernel</title>
1196
1197 <para>
1198 The steps in this procedure show you how you can patch the
1199 kernel using traditional kernel development (i.e. not using
1200 <filename>devtool</filename> and the extensible SDK as
1201 described in the
1202 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
1203 section).
1204 <note>
1205 Before attempting this procedure, be sure you have performed
1206 the steps to get ready for updating the kernel as described
1207 in the
1208 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
1209 section.
1210 </note>
1211 </para>
1212
1213 <para>
1214 Patching the kernel involves changing or adding configurations
1215 to an existing kernel, changing or adding recipes to the kernel
1216 that are needed to support specific hardware features, or even
1217 altering the source code itself.
1218 </para>
1219
1220 <para>
1221 The example in this section creates a simple patch by adding some
1222 QEMU emulator console output at boot time through
1223 <filename>printk</filename> statements in the kernel's
1224 <filename>calibrate.c</filename> source code file.
1225 Applying the patch and booting the modified image causes the added
1226 messages to appear on the emulator's console.
1227 The example is a continuation of the setup procedure found in
1228 the
1229 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
1230 Section.
1231 <orderedlist>
1232 <listitem><para>
1233 <emphasis>Edit the Source Files</emphasis>
1234 Prior to this step, you should have used Git to create a
1235 local copy of the repository for your kernel.
1236 Assuming you created the repository as directed in the
1237 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
1238 section, use the following commands to edit the
1239 <filename>calibrate.c</filename> file:
1240 <orderedlist>
1241 <listitem><para>
1242 <emphasis>Change the working directory</emphasis>:
1243 You need to locate the source files in the
1244 local copy of the kernel Git repository:
1245 Change to where the kernel source code is before making
1246 your edits to the <filename>calibrate.c</filename> file:
1247 <literallayout class='monospaced'>
1248 $ cd ~/linux-yocto-4.12/init
1249 </literallayout>
1250 </para></listitem>
1251 <listitem><para>
1252 <emphasis>Edit the source file</emphasis>:
1253 Edit the <filename>calibrate.c</filename> file to have
1254 the following changes:
1255 <literallayout class='monospaced'>
1256 void calibrate_delay(void)
1257 {
1258 unsigned long lpj;
1259 static bool printed;
1260 int this_cpu = smp_processor_id();
1261
1262 printk("*************************************\n");
1263 printk("* *\n");
1264 printk("* HELLO YOCTO KERNEL *\n");
1265 printk("* *\n");
1266 printk("*************************************\n");
1267
1268 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
1269 .
1270 .
1271 .
1272 </literallayout>
1273 </para></listitem>
1274 </orderedlist>
1275 </para></listitem>
1276 <listitem><para>
1277 <emphasis>Stage and Commit Your Changes:</emphasis>
1278 Use standard Git commands to stage and commit the changes
1279 you just made:
1280 <literallayout class='monospaced'>
1281 $ git add calibrate.c
1282 $ git commit -m "calibrate.c - Added some printk statements"
1283 </literallayout>
1284 If you do not stage and commit your changes, the OpenEmbedded
1285 Build System will not pick up the changes.
1286 </para></listitem>
1287 <listitem><para>
1288 <emphasis>Update Your <filename>local.conf</filename> File
1289 to Point to Your Source Files:</emphasis>
1290 In addition to your <filename>local.conf</filename> file
1291 specifying to use "kernel-modules" and the "qemux86"
1292 machine, it must also point to the updated kernel source
1293 files.
1294 Add
1295 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1296 and
1297 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1298 statements similar to the following to your
1299 <filename>local.conf</filename>:
1300 <literallayout class='monospaced'>
1301 $ cd ~/poky/build/conf
1302 </literallayout>
1303 Add the following to the <filename>local.conf</filename>:
1304 <literallayout class='monospaced'>
1305 SRC_URI_pn-linux-yocto = "git:///<replaceable>path-to</replaceable>/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
1306 git:///<replaceable>path-to</replaceable>/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
1307 SRCREV_meta_qemux86 = "${AUTOREV}"
1308 SRCREV_machine_qemux86 = "${AUTOREV}"
1309 </literallayout>
1310 <note>
1311 Be sure to replace
1312 <replaceable>path-to</replaceable> with the pathname
1313 to your local Git repositories.
1314 Also, you must be sure to specify the correct branch
1315 and machine types.
1316 For this example, the branch is
1317 <filename>standard/base</filename> and the machine is
1318 "qemux86".
1319 </note>
1320 </para></listitem>
1321 <listitem><para>
1322 <emphasis>Build the Image:</emphasis>
1323 With the source modified, your changes staged and
1324 committed, and the <filename>local.conf</filename> file
1325 pointing to the kernel files, you can now use BitBake to
1326 build the image:
1327 <literallayout class='monospaced'>
1328 $ cd ~/poky/build
1329 $ bitbake core-image-minimal
1330 </literallayout>
1331 </para></listitem>
1332 <listitem><para>
1333 <emphasis>Boot the image</emphasis>:
1334 Boot the modified image in the QEMU emulator
1335 using this command.
1336 When prompted to login to the QEMU console, use "root"
1337 with no password:
1338 <literallayout class='monospaced'>
1339 $ cd ~/poky/build
1340 $ runqemu qemux86
1341 </literallayout>
1342 </para></listitem>
1343 <listitem><para>
1344 <emphasis>Look for Your Changes:</emphasis>
1345 As QEMU booted, you might have seen your changes rapidly
1346 scroll by.
1347 If not, use these commands to see your changes:
1348 <literallayout class='monospaced'>
1349 # dmesg | less
1350 </literallayout>
1351 You should see the results of your
1352 <filename>printk</filename> statements
1353 as part of the output when you scroll down the
1354 console window.
1355 </para></listitem>
1356 <listitem><para>
1357 <emphasis>Generate the Patch File:</emphasis>
1358 Once you are sure that your patch works correctly, you
1359 can generate a <filename>*.patch</filename> file in the
1360 kernel source repository:
1361 <literallayout class='monospaced'>
1362 $ cd ~/linux-yocto-4.12/init
1363 $ git format-patch -1
1364 0001-calibrate.c-Added-some-printk-statements.patch
1365 </literallayout>
1366 </para></listitem>
1367 <listitem><para>
1368 <emphasis>Move the Patch File to Your Layer:</emphasis>
1369 In order for subsequent builds to pick up patches, you
1370 need to move the patch file you created in the previous
1371 step to your layer <filename>meta-mylayer</filename>.
1372 For this example, the layer created earlier is located
1373 in your home directory as <filename>meta-mylayer</filename>.
1374 When the layer was created using the
1375 <filename>yocto-create</filename> script, no additional
1376 hierarchy was created to support patches.
1377 Before moving the patch file, you need to add additional
1378 structure to your layer using the following commands:
1379 <literallayout class='monospaced'>
1380 $ cd ~/meta-mylayer
1381 $ mkdir recipes-kernel
1382 $ mkdir recipes-kernel/linux
1383 $ mkdir recipes-kernel/linux/linux-yocto
1384 </literallayout>
1385 Once you have created this hierarchy in your layer, you can
1386 move the patch file using the following command:
1387 <literallayout class='monospaced'>
1388 $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
1389 </literallayout>
1390 </para></listitem>
1391 <listitem><para>
1392 <emphasis>Create the Append File:</emphasis>
1393 Finally, you need to create the
1394 <filename>linux-yocto_4.12.bbappend</filename> file and
1395 insert statements that allow the OpenEmbedded build
1396 system to find the patch.
1397 The append file needs to be in your layer's
1398 <filename>recipes-kernel/linux</filename>
1399 directory and it must be named
1400 <filename>linux-yocto_4.12.bbappend</filename> and have
1401 the following contents:
1402 <literallayout class='monospaced'>
1403 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1404
1405 SRC_URI_append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
1406 </literallayout>
1407 The
1408 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1409 and
1410 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1411 statements enable the OpenEmbedded build system to find
1412 the patch file.</para>
1413
1414 <para>For more information on append files and patches,
1415 see the
1416 "<link linkend='creating-the-append-file'>Creating the Append File</link>"
1417 and
1418 "<link linkend='applying-patches'>Applying Patches</link>"
1419 sections.
1420 You can also see the
1421 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer"</ulink>"
1422 section in the Yocto Project Development Tasks Manual.
1423 <note>
1424 To build <filename>core-image-minimal</filename>
1425 again and see the effects of your patch, you can
1426 essentially eliminate the temporary source files
1427 saved in <filename>poky/build/tmp/work/...</filename>
1428 and residual effects of the build by entering the
1429 following sequence of commands:
1430 <literallayout class='monospaced'>
1431 $ cd ~/poky/build
1432 $ bitbake -c cleanall yocto-linux
1433 $ bitbake core-image-minimal -c cleanall
1434 $ bitbake core-image-minimal
1435 $ runqemu qemux86
1436 </literallayout>
1437 </note>
1438 </para></listitem>
1439 </orderedlist>
1440 </para>
1441 </section>
1442
1443 <section id='configuring-the-kernel'>
1444 <title>Configuring the Kernel</title>
1445
1446 <para>
1447 Configuring the Yocto Project kernel consists of making sure the
1448 <filename>.config</filename> file has all the right information
1449 in it for the image you are building.
1450 You can use the <filename>menuconfig</filename> tool and
1451 configuration fragments to make sure your
1452 <filename>.config</filename> file is just how you need it.
1453 You can also save known configurations in a
1454 <filename>defconfig</filename> file that the build system can use
1455 for kernel configuration.
1456 </para>
1457
1458 <para>
1459 This section describes how to use <filename>menuconfig</filename>,
1460 create and use configuration fragments, and how to interactively
1461 modify your <filename>.config</filename> file to create the
1462 leanest kernel configuration file possible.
1463 </para>
1464
1465 <para>
1466 For more information on kernel configuration, see the
1467 "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
1468 section.
1469 </para>
1470
1471 <section id='using-menuconfig'>
1472 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
1473
1474 <para>
1475 The easiest way to define kernel configurations is to set
1476 them through the <filename>menuconfig</filename> tool.
1477 This tool provides an interactive method with which
1478 to set kernel configurations.
1479 For general information on <filename>menuconfig</filename>, see
1480 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
1481 </para>
1482
1483 <para>
1484 To use the <filename>menuconfig</filename> tool in the Yocto
1485 Project development environment, you must do the following:
1486 <itemizedlist>
1487 <listitem><para>
1488 Because you launch <filename>menuconfig</filename>
1489 using BitBake, you must be sure to set up your
1490 environment by running the
1491 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1492 script found in the
1493 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1494 </para></listitem>
1495 <listitem><para>
1496 You must be sure of the state of your build's
1497 configuration in the
1498 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1499 </para></listitem>
1500 <listitem><para>
1501 Your build host must have the following two packages
1502 installed:
1503 <literallayout class='monospaced'>
1504 libncurses5-dev
1505 libtinfo-dev
1506 </literallayout>
1507 </para></listitem>
1508 </itemizedlist>
1509 </para>
1510
1511 <para>
1512 The following commands initialize the BitBake environment,
1513 run the
1514 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink>
1515 task, and launch <filename>menuconfig</filename>.
1516 These commands assume the Source Directory's top-level folder
1517 is <filename>~/poky</filename>:
1518 <literallayout class='monospaced'>
1519 $ cd poky
1520 $ source oe-init-build-env
1521 $ bitbake linux-yocto -c kernel_configme -f
1522 $ bitbake linux-yocto -c menuconfig
1523 </literallayout>
1524 Once <filename>menuconfig</filename> comes up, its standard
1525 interface allows you to interactively examine and configure
1526 all the kernel configuration parameters.
1527 After making your changes, simply exit the tool and save your
1528 changes to create an updated version of the
1529 <filename>.config</filename> configuration file.
1530 <note>
1531 You can use the entire <filename>.config</filename> file
1532 as the <filename>defconfig</filename> file.
1533 For information on <filename>defconfig</filename> files,
1534 see the
1535 "<link linkend='changing-the-configuration'>Changing the Configuration</link>",
1536 "<link linkend='using-an-in-tree-defconfig-file'>Using an In-Tree <filename>defconfig</filename> File</link>,
1537 and
1538 "<link linkend='creating-a-defconfig-file'>Creating a <filename>defconfig</filename> File</link>"
1539 sections.
1540 </note>
1541 </para>
1542
1543 <para>
1544 Consider an example that configures the "CONFIG_SMP" setting
1545 for the <filename>linux-yocto-4.12</filename> kernel.
1546 <note>
1547 The OpenEmbedded build system recognizes this kernel as
1548 <filename>linux-yocto</filename> through Metadata (e.g.
1549 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink><filename>_linux-yocto ?= "12.4%"</filename>).
1550 </note>
1551 Once <filename>menuconfig</filename> launches, use the
1552 interface to navigate through the selections to find the
1553 configuration settings in which you are interested.
1554 For this example, you deselect "CONFIG_SMP" by clearing the
1555 "Symmetric Multi-Processing Support" option.
1556 Using the interface, you can find the option under
1557 "Processor Type and Features".
1558 To deselect "CONFIG_SMP", use the arrow keys to
1559 highlight "Symmetric Multi-Processing Support" and enter "N"
1560 to clear the asterisk.
1561 When you are finished, exit out and save the change.
1562 </para>
1563
1564 <para>
1565 Saving the selections updates the <filename>.config</filename>
1566 configuration file.
1567 This is the file that the OpenEmbedded build system uses to
1568 configure the kernel during the build.
1569 You can find and examine this file in the Build Directory in
1570 <filename>tmp/work/</filename>.
1571 The actual <filename>.config</filename> is located in the
1572 area where the specific kernel is built.
1573 For example, if you were building a Linux Yocto kernel based
1574 on the <filename>linux-yocto-4.12</filename> kernel and you
1575 were building a QEMU image targeted for
1576 <filename>x86</filename> architecture, the
1577 <filename>.config</filename> file would be:
1578 <literallayout class='monospaced'>
1579 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1580 ...967-r0/linux-qemux86-standard-build/.config
1581 </literallayout>
1582 <note>
1583 The previous example directory is artificially split and
1584 many of the characters in the actual filename are omitted
1585 in order to make it more readable.
1586 Also, depending on the kernel you are using, the exact
1587 pathname might differ.
1588 </note>
1589 </para>
1590
1591 <para>
1592 Within the <filename>.config</filename> file, you can see the
1593 kernel settings.
1594 For example, the following entry shows that symmetric
1595 multi-processor support is not set:
1596 <literallayout class='monospaced'>
1597 # CONFIG_SMP is not set
1598 </literallayout>
1599 </para>
1600
1601 <para>
1602 A good method to isolate changed configurations is to use a
1603 combination of the <filename>menuconfig</filename> tool and
1604 simple shell commands.
1605 Before changing configurations with
1606 <filename>menuconfig</filename>, copy the existing
1607 <filename>.config</filename> and rename it to something else,
1608 use <filename>menuconfig</filename> to make as many changes as
1609 you want and save them, then compare the renamed configuration
1610 file against the newly created file.
1611 You can use the resulting differences as your base to create
1612 configuration fragments to permanently save in your kernel
1613 layer.
1614 <note>
1615 Be sure to make a copy of the <filename>.config</filename>
1616 file and do not just rename it.
1617 The build system needs an existing
1618 <filename>.config</filename> file from which to work.
1619 </note>
1620 </para>
1621 </section>
1622
1623 <section id='creating-a-defconfig-file'>
1624 <title>Creating a&nbsp;&nbsp;<filename>defconfig</filename> File</title>
1625
1626 <para>
1627 A <filename>defconfig</filename> file in the context of
1628 the Yocto Project is often a <filename>.config</filename>
1629 file that is copied from a build or a
1630 <filename>defconfig</filename> taken from the kernel tree
1631 and moved into recipe space.
1632 You can use a <filename>defconfig</filename> file
1633 to retain a known set of kernel configurations from which the
1634 OpenEmbedded build system can draw to create the final
1635 <filename>.config</filename> file.
1636 <note>
1637 Out-of-the-box, the Yocto Project never ships a
1638 <filename>defconfig</filename> or
1639 <filename>.config</filename> file.
1640 The OpenEmbedded build system creates the final
1641 <filename>.config</filename> file used to configure the
1642 kernel.
1643 </note>
1644 </para>
1645
1646 <para>
1647 To create a <filename>defconfig</filename>, start with a
1648 complete, working Linux kernel <filename>.config</filename>
1649 file.
1650 Copy that file to the appropriate
1651 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1652 directory in your layer's
1653 <filename>recipes-kernel/linux</filename> directory, and rename
1654 the copied file to "defconfig" (e.g.
1655 <filename>~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig</filename>).
1656 Then, add the following lines to the linux-yocto
1657 <filename>.bbappend</filename> file in your layer:
1658 <literallayout class='monospaced'>
1659 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1660 SRC_URI += "file://defconfig"
1661 </literallayout>
1662 The
1663 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1664 tells the build system how to search for the file, while the
1665 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1666 extends the
1667 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1668 variable (search directories) to include the
1669 <filename>${PN}</filename> directory you created to hold the
1670 configuration changes.
1671 <note>
1672 The build system applies the configurations from the
1673 <filename>defconfig</filename> file before applying any
1674 subsequent configuration fragments.
1675 The final kernel configuration is a combination of the
1676 configurations in the <filename>defconfig</filename>
1677 file and any configuration fragments you provide.
1678 You need to realize that if you have any configuration
1679 fragments, the build system applies these on top of and
1680 after applying the existing defconfig file configurations.
1681 </note>
1682 For more information on configuring the kernel, see the
1683 "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
1684 section.
1685 </para>
1686 </section>
1687
1688 <section id='creating-config-fragments'>
1689 <title>Creating Configuration Fragments</title>
1690
1691 <para>
1692 Configuration fragments are simply kernel options that
1693 appear in a file placed where the OpenEmbedded build system
1694 can find and apply them.
1695 The build system applies configuration fragments after
1696 applying configurations from a <filename>defconfig</filename>
1697 file.
1698 Thus, the final kernel configuration is a combination of the
1699 configurations in the <filename>defconfig</filename>
1700 file and then any configuration fragments you provide.
1701 The build system applies fragments on top of and
1702 after applying the existing defconfig file configurations.
1703 </para>
1704
1705 <para>
1706 Syntactically, the configuration statement is identical to
1707 what would appear in the <filename>.config</filename> file,
1708 which is in the
1709 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1710 <note>
1711 For more information about where the
1712 <filename>.config</filename> file is located, see the
1713 example in the
1714 "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
1715 section.
1716 </note>
1717 </para>
1718
1719 <para>
1720 It is simple to create a configuration fragment.
1721 One method is to use shell commands.
1722 For example, issuing the following from the shell creates a
1723 configuration fragment file named
1724 <filename>my_smp.cfg</filename> that enables multi-processor
1725 support within the kernel:
1726 <literallayout class='monospaced'>
1727 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1728 </literallayout>
1729 <note>
1730 All configuration fragment files must use the
1731 <filename>.cfg</filename> extension in order for the
1732 OpenEmbedded build system to recognize them as a
1733 configuration fragment.
1734 </note>
1735 </para>
1736
1737 <para>
1738 Another method is to create a configuration fragment using the
1739 differences between two configuration files: one previously
1740 created and saved, and one freshly created using the
1741 <filename>menuconfig</filename> tool.
1742 </para>
1743
1744 <para>
1745 To create a configuration fragment using this method, follow
1746 these steps:
1747 <orderedlist>
1748 <listitem><para>
1749 <emphasis>Complete a Build Through Kernel Configuration:</emphasis>
1750 Complete a build at least through the kernel
1751 configuration task as follows:
1752 <literallayout class='monospaced'>
1753 $ bitbake linux-yocto -c kernel_configme -f
1754 </literallayout>
1755 This step ensures that you create a
1756 <filename>.config</filename> file from a known state.
1757 Because situations exist where your build state might
1758 become unknown, it is best to run this task prior
1759 to starting <filename>menuconfig</filename>.
1760 </para></listitem>
1761 <listitem><para>
1762 <emphasis>Launch <filename>menuconfig</filename>:</emphasis>
1763 Run the <filename>menuconfig</filename> command:
1764 <literallayout class='monospaced'>
1765 $ bitbake linux-yocto -c menuconfig
1766 </literallayout>
1767 </para></listitem>
1768 <listitem><para>
1769 <emphasis>Create the Configuration Fragment:</emphasis>
1770 Run the <filename>diffconfig</filename>
1771 command to prepare a configuration fragment.
1772 The resulting file <filename>fragment.cfg</filename>
1773 is placed in the
1774 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory:
1775 <literallayout class='monospaced'>
1776 $ bitbake linux-yocto -c diffconfig
1777 </literallayout>
1778 </para></listitem>
1779 </orderedlist>
1780 </para>
1781
1782 <para>
1783 The <filename>diffconfig</filename> command creates a file
1784 that is a list of Linux kernel <filename>CONFIG_</filename>
1785 assignments.
1786 See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
1787 section for additional information on how to use the output
1788 as a configuration fragment.
1789 <note>
1790 You can also use this method to create configuration
1791 fragments for a BSP.
1792 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
1793 section for more information.
1794 </note>
1795 </para>
1796
1797 <para>
1798 Where do you put your configuration fragment files?
1799 You can place these files in an area pointed to by
1800 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1801 as directed by your <filename>bblayers.conf</filename> file,
1802 which is located in your layer.
1803 The OpenEmbedded build system picks up the configuration and
1804 adds it to the kernel's configuration.
1805 For example, suppose you had a set of configuration options
1806 in a file called <filename>myconfig.cfg</filename>.
1807 If you put that file inside a directory named
1808 <filename>linux-yocto</filename> that resides in the same
1809 directory as the kernel's append file within your layer
1810 and then add the following statements to the kernel's append
1811 file, those configuration options will be picked up and applied
1812 when the kernel is built:
1813 <literallayout class='monospaced'>
1814 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1815 SRC_URI += "file://myconfig.cfg"
1816 </literallayout>
1817 </para>
1818
1819 <para>
1820 As mentioned earlier, you can group related configurations
1821 into multiple files and name them all in the
1822 <filename>SRC_URI</filename> statement as well.
1823 For example, you could group separate configurations
1824 specifically for Ethernet and graphics into their own files
1825 and add those by using a <filename>SRC_URI</filename> statement
1826 like the following in your append file:
1827 <literallayout class='monospaced'>
1828 SRC_URI += "file://myconfig.cfg \
1829 file://eth.cfg \
1830 file://gfx.cfg"
1831 </literallayout>
1832 </para>
1833 </section>
1834
1835 <section id='validating-configuration'>
1836 <title>Validating Configuration</title>
1837
1838 <para>
1839 You can use the
1840 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink>
1841 task to provide configuration validation:
1842 <literallayout class='monospaced'>
1843 $ bitbake linux-yocto -c kernel_configcheck -f
1844 </literallayout>
1845 Running this task produces warnings for when a
1846 requested configuration does not appear in the final
1847 <filename>.config</filename> file or when you override a
1848 policy configuration in a hardware configuration fragment.
1849 </para>
1850
1851 <para>
1852 In order to run this task, you must have an existing
1853 <filename>.config</filename> file.
1854 See the
1855 "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
1856 section for information on how to create a configuration file.
1857 </para>
1858
1859 <para>
1860 Following is sample output from the
1861 <filename>do_kernel_configcheck</filename> task:
1862 <literallayout class='monospaced'>
1863 Loading cache: 100% |########################################################| Time: 0:00:00
1864 Loaded 1275 entries from dependency cache.
1865 NOTE: Resolving any missing task queue dependencies
1866
1867 Build Configuration:
1868 .
1869 .
1870 .
1871
1872 NOTE: Executing SetScene Tasks
1873 NOTE: Executing RunQueue Tasks
1874 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
1875 [kernel config]: specified values did not make it into the kernel's final configuration:
1876
1877 ---------- CONFIG_X86_TSC -----------------
1878 Config: CONFIG_X86_TSC
1879 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
1880 Requested value: CONFIG_X86_TSC=y
1881 Actual value:
1882
1883
1884 ---------- CONFIG_X86_BIGSMP -----------------
1885 Config: CONFIG_X86_BIGSMP
1886 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1887 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1888 Requested value: # CONFIG_X86_BIGSMP is not set
1889 Actual value:
1890
1891
1892 ---------- CONFIG_NR_CPUS -----------------
1893 Config: CONFIG_NR_CPUS
1894 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1895 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
1896 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1897 Requested value: CONFIG_NR_CPUS=8
1898 Actual value: CONFIG_NR_CPUS=1
1899
1900
1901 ---------- CONFIG_SCHED_SMT -----------------
1902 Config: CONFIG_SCHED_SMT
1903 From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1904 /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1905 Requested value: CONFIG_SCHED_SMT=y
1906 Actual value:
1907
1908
1909
1910 NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded.
1911
1912 Summary: There were 3 WARNING messages shown.
1913 </literallayout>
1914 <note>
1915 The previous output example has artificial line breaks
1916 to make it more readable.
1917 </note>
1918 </para>
1919
1920 <para>
1921 The output describes the various problems that you can
1922 encounter along with where to find the offending configuration
1923 items.
1924 You can use the information in the logs to adjust your
1925 configuration files and then repeat the
1926 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink>
1927 and
1928 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink>
1929 tasks until they produce no warnings.
1930 </para>
1931
1932 <para>
1933 For more information on how to use the
1934 <filename>menuconfig</filename> tool, see the
1935 "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
1936 section.
1937 </para>
1938 </section>
1939
1940 <section id='fine-tuning-the-kernel-configuration-file'>
1941 <title>Fine-Tuning the Kernel Configuration File</title>
1942
1943 <para>
1944 You can make sure the <filename>.config</filename> file is as
1945 lean or efficient as possible by reading the output of the
1946 kernel configuration fragment audit, noting any issues, making
1947 changes to correct the issues, and then repeating.
1948 </para>
1949
1950 <para>
1951 As part of the kernel build process, the
1952 <filename>do_kernel_configcheck</filename> task runs.
1953 This task validates the kernel configuration by checking the
1954 final <filename>.config</filename> file against the input
1955 files.
1956 During the check, the task produces warning messages for the
1957 following issues:
1958 <itemizedlist>
1959 <listitem><para>
1960 Requested options that did not make the final
1961 <filename>.config</filename> file.
1962 </para></listitem>
1963 <listitem><para>
1964 Configuration items that appear twice in the same
1965 configuration fragment.
1966 </para></listitem>
1967 <listitem><para>
1968 Configuration items tagged as "required" that were
1969 overridden.
1970 </para></listitem>
1971 <listitem><para>
1972 A board overrides a non-board specific option.
1973 </para></listitem>
1974 <listitem><para>
1975 Listed options not valid for the kernel being
1976 processed.
1977 In other words, the option does not appear anywhere.
1978 </para></listitem>
1979 </itemizedlist>
1980 <note>
1981 The <filename>do_kernel_configcheck</filename> task can
1982 also optionally report if an option is overridden during
1983 processing.
1984 </note>
1985 </para>
1986
1987 <para>
1988 For each output warning, a message points to the file
1989 that contains a list of the options and a pointer to the
1990 configuration fragment that defines them.
1991 Collectively, the files are the key to streamlining the
1992 configuration.
1993 </para>
1994
1995 <para>
1996 To streamline the configuration, do the following:
1997 <orderedlist>
1998 <listitem><para>
1999 <emphasis>Use a Working Configuration:</emphasis>
2000 Start with a full configuration that you
2001 know works.
2002 Be sure the configuration builds and boots
2003 successfully.
2004 Use this configuration file as your baseline.
2005 </para></listitem>
2006 <listitem><para>
2007 <emphasis>Run Configure and Check Tasks:</emphasis>
2008 Separately run the
2009 <filename>do_kernel_configme</filename> and
2010 <filename>do_kernel_configcheck</filename> tasks:
2011 <literallayout class='monospaced'>
2012 $ bitbake linux-yocto -c kernel_configme -f
2013 $ bitbake linux-yocto -c kernel_configcheck -f
2014 </literallayout>
2015 </para></listitem>
2016 <listitem><para>
2017 <emphasis>Process the Results:</emphasis>
2018 Take the resulting list of files from the
2019 <filename>do_kernel_configcheck</filename> task
2020 warnings and do the following:
2021 <itemizedlist>
2022 <listitem><para>
2023 Drop values that are redefined in the fragment
2024 but do not change the final
2025 <filename>.config</filename> file.
2026 </para></listitem>
2027 <listitem><para>
2028 Analyze and potentially drop values from the
2029 <filename>.config</filename> file that override
2030 required configurations.
2031 </para></listitem>
2032 <listitem><para>
2033 Analyze and potentially remove non-board
2034 specific options.
2035 </para></listitem>
2036 <listitem><para>
2037 Remove repeated and invalid options.
2038 </para></listitem>
2039 </itemizedlist>
2040 </para></listitem>
2041 <listitem><para>
2042 <emphasis>Re-Run Configure and Check Tasks:</emphasis>
2043 After you have worked through the output of the kernel
2044 configuration audit, you can re-run the
2045 <filename>do_kernel_configme</filename> and
2046 <filename>do_kernel_configcheck</filename> tasks to
2047 see the results of your changes.
2048 If you have more issues, you can deal with them as
2049 described in the previous step.
2050 </para></listitem>
2051 </orderedlist>
2052 </para>
2053
2054 <para>
2055 Iteratively working through steps two through four eventually
2056 yields a minimal, streamlined configuration file.
2057 Once you have the best <filename>.config</filename>, you can
2058 build the Linux Yocto kernel.
2059 </para>
2060 </section>
2061 </section>
2062
2063 <section id='expanding-variables'>
2064 <title>Expanding Variables</title>
2065
2066 <para>
2067 Sometimes it is helpful to determine what a variable expands
2068 to during a build.
2069 You can do examine the values of variables by examining the
2070 output of the <filename>bitbake -e</filename> command.
2071 The output is long and is more easily managed in a text file,
2072 which allows for easy searches:
2073 <literallayout class='monospaced'>
2074 $ bitbake -e virtual/kernel > <replaceable>some_text_file</replaceable>
2075 </literallayout>
2076 Within the text file, you can see exactly how each variable is
2077 expanded and used by the OpenEmbedded build system.
2078 </para>
2079 </section>
2080
2081 <section id='working-with-a-dirty-kernel-version-string'>
2082 <title>Working with a "Dirty" Kernel Version String</title>
2083
2084 <para>
2085 If you build a kernel image and the version string has a
2086 "+" or a "-dirty" at the end, uncommitted modifications exist
2087 in the kernel's source directory.
2088 Follow these steps to clean up the version string:
2089 <orderedlist>
2090 <listitem><para>
2091 <emphasis>Discover the Uncommitted Changes:</emphasis>
2092 Go to the kernel's locally cloned Git repository
2093 (source directory) and use the following Git command
2094 to list the files that have been changed, added, or
2095 removed:
2096 <literallayout class='monospaced'>
2097 $ git status
2098 </literallayout>
2099 </para></listitem>
2100 <listitem><para>
2101 <emphasis>Commit the Changes:</emphasis>
2102 You should commit those changes to the kernel source
2103 tree regardless of whether or not you will save,
2104 export, or use the changes:
2105 <literallayout class='monospaced'>
2106 $ git add
2107 $ git commit -s -a -m "getting rid of -dirty"
2108 </literallayout>
2109 </para></listitem>
2110 <listitem><para>
2111 <emphasis>Rebuild the Kernel Image:</emphasis>
2112 Once you commit the changes, rebuild the kernel.</para>
2113
2114 <para>Depending on your particular kernel development
2115 workflow, the commands you use to rebuild the
2116 kernel might differ.
2117 For information on building the kernel image when
2118 using <filename>devtool</filename>, see the
2119 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
2120 section.
2121 For information on building the kernel image when
2122 using Bitbake, see the
2123 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
2124 section.
2125 </para></listitem>
2126 </orderedlist>
2127 </para>
2128 </section>
2129
2130 <section id='working-with-your-own-sources'>
2131 <title>Working With Your Own Sources</title>
2132
2133 <para>
2134 If you cannot work with one of the Linux kernel
2135 versions supported by existing linux-yocto recipes, you can
2136 still make use of the Yocto Project Linux kernel tooling by
2137 working with your own sources.
2138 When you use your own sources, you will not be able to
2139 leverage the existing kernel
2140 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> and
2141 stabilization work of the linux-yocto sources.
2142 However, you will be able to manage your own Metadata in the same
2143 format as the linux-yocto sources.
2144 Maintaining format compatibility facilitates converging with
2145 linux-yocto on a future, mutually-supported kernel version.
2146 </para>
2147
2148 <para>
2149 To help you use your own sources, the Yocto Project provides a
2150 linux-yocto custom recipe
2151 (<filename>linux-yocto-custom.bb</filename>) that uses
2152 <filename>kernel.org</filename> sources
2153 and the Yocto Project Linux kernel tools for managing
2154 kernel Metadata.
2155 You can find this recipe in the
2156 <filename>poky</filename> Git repository of the
2157 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
2158 at:
2159 <literallayout class="monospaced">
2160 poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
2161 </literallayout>
2162 </para>
2163
2164 <para>
2165 Here are some basic steps you can use to work with your own
2166 sources:
2167 <orderedlist>
2168 <listitem><para>
2169 <emphasis>Create a Copy of the Kernel Recipe:</emphasis>
2170 Copy the <filename>linux-yocto-custom.bb</filename>
2171 recipe to your layer and give it a meaningful name.
2172 The name should include the version of the Yocto Linux
2173 kernel you are using (e.g.
2174 <filename>linux-yocto-myproject_4.12.bb</filename>,
2175 where "4.12" is the base version of the Linux kernel
2176 with which you would be working).
2177 </para></listitem>
2178 <listitem><para>
2179 <emphasis>Create a Directory for Your Patches:</emphasis>
2180 In the same directory inside your layer, create a matching
2181 directory to store your patches and configuration files
2182 (e.g. <filename>linux-yocto-myproject</filename>).
2183 </para></listitem>
2184 <listitem><para>
2185 <emphasis>Ensure You Have Configurations:</emphasis>
2186 Make sure you have either a <filename>defconfig</filename>
2187 file or configuration fragment files in your layer.
2188 When you use the <filename>linux-yocto-custom.bb</filename>
2189 recipe, you must specify a configuration.
2190 If you do not have a <filename>defconfig</filename> file,
2191 you can run the following:
2192 <literallayout class='monospaced'>
2193 $ make defconfig
2194 </literallayout>
2195 After running the command, copy the resulting
2196 <filename>.config</filename> file to the
2197 <filename>files</filename> directory in your layer
2198 as "defconfig" and then add it to the
2199 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2200 variable in the recipe.</para>
2201
2202 <para>Running the <filename>make defconfig</filename>
2203 command results in the default configuration for your
2204 architecture as defined by your kernel.
2205 However, no guarantee exists that this configuration is
2206 valid for your use case, or that your board will even boot.
2207 This is particularly true for non-x86 architectures.</para>
2208
2209 <para>To use non-x86 <filename>defconfig</filename> files,
2210 you need to be more specific and find one that matches your
2211 board (i.e. for arm, you look in
2212 <filename>arch/arm/configs</filename> and use the one that
2213 is the best starting point for your board).
2214 </para></listitem>
2215 <listitem><para>
2216 <emphasis>Edit the Recipe:</emphasis>
2217 Edit the following variables in your recipe as appropriate
2218 for your project:
2219 <itemizedlist>
2220 <listitem><para>
2221 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
2222 The <filename>SRC_URI</filename> should specify
2223 a Git repository that uses one of the supported Git
2224 fetcher protocols (i.e. <filename>file</filename>,
2225 <filename>git</filename>, <filename>http</filename>,
2226 and so forth).
2227 The <filename>SRC_URI</filename> variable should
2228 also specify either a <filename>defconfig</filename>
2229 file or some configuration fragment files.
2230 The skeleton recipe provides an example
2231 <filename>SRC_URI</filename> as a syntax reference.
2232 </para></listitem>
2233 <listitem><para>
2234 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
2235 The Linux kernel version you are using (e.g.
2236 "4.12").
2237 </para></listitem>
2238 <listitem><para>
2239 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
2240 The Linux kernel
2241 <filename>CONFIG_LOCALVERSION</filename> that is
2242 compiled into the resulting kernel and visible
2243 through the <filename>uname</filename> command.
2244 </para></listitem>
2245 <listitem><para>
2246 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
2247 The commit ID from which you want to build.
2248 </para></listitem>
2249 <listitem><para>
2250 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
2251 Treat this variable the same as you would in any
2252 other recipe.
2253 Increment the variable to indicate to the
2254 OpenEmbedded build system that the recipe has
2255 changed.
2256 </para></listitem>
2257 <listitem><para>
2258 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
2259 The default <filename>PV</filename> assignment is
2260 typically adequate.
2261 It combines the <filename>LINUX_VERSION</filename>
2262 with the Source Control Manager (SCM) revision
2263 as derived from the
2264 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
2265 variable.
2266 The combined results are a string with the
2267 following form:
2268 <literallayout class='monospaced'>
2269 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
2270 </literallayout>
2271 While lengthy, the extra verbosity in
2272 <filename>PV</filename> helps ensure you are using
2273 the exact sources from which you intend to build.
2274 </para></listitem>
2275 <listitem><para>
2276 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
2277 A list of the machines supported by your new recipe.
2278 This variable in the example recipe is set
2279 by default to a regular expression that matches
2280 only the empty string, "(^$)".
2281 This default setting triggers an explicit build
2282 failure.
2283 You must change it to match a list of the machines
2284 that your new recipe supports.
2285 For example, to support the
2286 <filename>qemux86</filename> and
2287 <filename>qemux86-64</filename> machines, use
2288 the following form:
2289 <literallayout class='monospaced'>
2290 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
2291 </literallayout>
2292 </para></listitem>
2293 </itemizedlist>
2294 </para></listitem>
2295 <listitem><para>
2296 <emphasis>Customize Your Recipe as Needed:</emphasis>
2297 Provide further customizations to your recipe
2298 as needed just as you would customize an existing
2299 linux-yocto recipe.
2300 See the
2301 "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
2302 section for information.
2303 </para></listitem>
2304 </orderedlist>
2305 </para>
2306 </section>
2307
2308 <section id='working-with-out-of-tree-modules'>
2309 <title>Working with Out-of-Tree Modules</title>
2310
2311 <para>
2312 This section describes steps to build out-of-tree modules on
2313 your target and describes how to incorporate out-of-tree modules
2314 in the build.
2315 </para>
2316
2317 <section id='building-out-of-tree-modules-on-the-target'>
2318 <title>Building Out-of-Tree Modules on the Target</title>
2319
2320 <para>
2321 While the traditional Yocto Project development model would be
2322 to include kernel modules as part of the normal build
2323 process, you might find it useful to build modules on the
2324 target.
2325 This could be the case if your target system is capable
2326 and powerful enough to handle the necessary compilation.
2327 Before deciding to build on your target, however, you should
2328 consider the benefits of using a proper cross-development
2329 environment from your build host.
2330 </para>
2331
2332 <para>
2333 If you want to be able to build out-of-tree modules on
2334 the target, there are some steps you need to take
2335 on the target that is running your SDK image.
2336 Briefly, the <filename>kernel-dev</filename> package
2337 is installed by default on all
2338 <filename>*.sdk</filename> images and the
2339 <filename>kernel-devsrc</filename> package is installed
2340 on many of the <filename>*.sdk</filename> images.
2341 However, you need to create some scripts prior to
2342 attempting to build the out-of-tree modules on the target
2343 that is running that image.
2344 </para>
2345
2346 <para>
2347 Prior to attempting to build the out-of-tree modules,
2348 you need to be on the target as root and you need to
2349 change to the <filename>/usr/src/kernel</filename> directory.
2350 Next, <filename>make</filename> the scripts:
2351 <literallayout class='monospaced'>
2352 # cd /usr/src/kernel
2353 # make scripts
2354 </literallayout>
2355 Because all SDK image recipes include
2356 <filename>dev-pkgs</filename>, the
2357 <filename>kernel-dev</filename> packages will be installed
2358 as part of the SDK image and the
2359 <filename>kernel-devsrc</filename> packages will be installed
2360 as part of applicable SDK images.
2361 The SDK uses the scripts when building out-of-tree
2362 modules.
2363 Once you have switched to that directory and created the
2364 scripts, you should be able to build your out-of-tree modules
2365 on the target.
2366 </para>
2367 </section>
2368
2369 <section id='incorporating-out-of-tree-modules'>
2370 <title>Incorporating Out-of-Tree Modules</title>
2371
2372 <para>
2373 While it is always preferable to work with sources integrated
2374 into the Linux kernel sources, if you need an external kernel
2375 module, the <filename>hello-mod.bb</filename> recipe is
2376 available as a template from which you can create your
2377 own out-of-tree Linux kernel module recipe.
2378 </para>
2379
2380 <para>
2381 This template recipe is located in the
2382 <filename>poky</filename> Git repository of the
2383 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
2384 at:
2385 <literallayout class="monospaced">
2386 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
2387 </literallayout>
2388 </para>
2389
2390 <para>
2391 To get started, copy this recipe to your layer and give it a
2392 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
2393 In the same directory, create a new directory named
2394 <filename>files</filename> where you can store any source files,
2395 patches, or other files necessary for building
2396 the module that do not come with the sources.
2397 Finally, update the recipe as needed for the module.
2398 Typically, you will need to set the following variables:
2399 <itemizedlist>
2400 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
2401 </para></listitem>
2402 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
2403 </para></listitem>
2404 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2405 </para></listitem>
2406 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
2407 </para></listitem>
2408 </itemizedlist>
2409 </para>
2410
2411 <para>
2412 Depending on the build system used by the module sources,
2413 you might need to make some adjustments.
2414 For example, a typical module <filename>Makefile</filename>
2415 looks much like the one provided with the
2416 <filename>hello-mod</filename> template:
2417 <literallayout class='monospaced'>
2418 obj-m := hello.o
2419
2420 SRC := $(shell pwd)
2421
2422 all:
2423 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
2424
2425 modules_install:
2426 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
2427 ...
2428 </literallayout>
2429 </para>
2430
2431 <para>
2432 The important point to note here is the
2433 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
2434 variable.
2435 The
2436 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink>
2437 class sets this variable and the
2438 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
2439 variable to
2440 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
2441 with the necessary Linux kernel build information to build
2442 modules.
2443 If your module <filename>Makefile</filename> uses a different
2444 variable, you might want to override the
2445 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
2446 step, or create a patch to
2447 the <filename>Makefile</filename> to work with the more typical
2448 <filename>KERNEL_SRC</filename> or
2449 <filename>KERNEL_PATH</filename> variables.
2450 </para>
2451
2452 <para>
2453 After you have prepared your recipe, you will likely want to
2454 include the module in your images.
2455 To do this, see the documentation for the following variables in
2456 the Yocto Project Reference Manual and set one of them
2457 appropriately for your machine configuration file:
2458 <itemizedlist>
2459 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
2460 </para></listitem>
2461 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
2462 </para></listitem>
2463 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
2464 </para></listitem>
2465 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
2466 </para></listitem>
2467 </itemizedlist>
2468 </para>
2469
2470 <para>
2471 Modules are often not required for boot and can be excluded from
2472 certain build configurations.
2473 The following allows for the most flexibility:
2474 <literallayout class='monospaced'>
2475 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
2476 </literallayout>
2477 The value is derived by appending the module filename without
2478 the <filename>.ko</filename> extension to the string
2479 "kernel-module-".
2480 </para>
2481
2482 <para>
2483 Because the variable is
2484 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
2485 and not a
2486 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
2487 variable, the build will not fail if this module is not
2488 available to include in the image.
2489 </para>
2490 </section>
2491 </section>
2492
2493
2494 <section id='inspecting-changes-and-commits'>
2495 <title>Inspecting Changes and Commits</title>
2496
2497 <para>
2498 A common question when working with a kernel is:
2499 "What changes have been applied to this tree?"
2500 Rather than using "grep" across directories to see what has
2501 changed, you can use Git to inspect or search the kernel tree.
2502 Using Git is an efficient way to see what has changed in the tree.
2503 </para>
2504
2505 <section id='what-changed-in-a-kernel'>
2506 <title>What Changed in a Kernel?</title>
2507
2508 <para>
2509 Following are a few examples that show how to use Git
2510 commands to examine changes.
2511 These examples are by no means the only way to see changes.
2512 <note>
2513 In the following examples, unless you provide a commit
2514 range, <filename>kernel.org</filename> history is blended
2515 with Yocto Project kernel changes.
2516 You can form ranges by using branch names from the
2517 kernel tree as the upper and lower commit markers with
2518 the Git commands.
2519 You can see the branch names through the web interface
2520 to the Yocto Project source repositories at
2521 <ulink url='&YOCTO_GIT_URL;'></ulink>.
2522 </note>
2523 To see a full range of the changes, use the
2524 <filename>git whatchanged</filename> command and specify a
2525 commit range for the branch
2526 (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>).
2527 </para>
2528
2529 <para>
2530 Here is an example that looks at what has changed in the
2531 <filename>emenlow</filename> branch of the
2532 <filename>linux-yocto-3.19</filename> kernel.
2533 The lower commit range is the commit associated with the
2534 <filename>standard/base</filename> branch, while
2535 the upper commit range is the commit associated with the
2536 <filename>standard/emenlow</filename> branch.
2537 <literallayout class='monospaced'>
2538 $ git whatchanged origin/standard/base..origin/standard/emenlow
2539 </literallayout>
2540 </para>
2541
2542 <para>
2543 To see short, one line summaries of changes use the
2544 <filename>git log</filename> command:
2545 <literallayout class='monospaced'>
2546 $ git log --oneline origin/standard/base..origin/standard/emenlow
2547 </literallayout>
2548 </para>
2549
2550 <para>
2551 Use this command to see code differences for the changes:
2552 <literallayout class='monospaced'>
2553 $ git diff origin/standard/base..origin/standard/emenlow
2554 </literallayout>
2555 </para>
2556
2557 <para>
2558 Use this command to see the commit log messages and the
2559 text differences:
2560 <literallayout class='monospaced'>
2561 $ git show origin/standard/base..origin/standard/emenlow
2562 </literallayout>
2563 </para>
2564
2565 <para>
2566 Use this command to create individual patches for
2567 each change.
2568 Here is an example that that creates patch files for each
2569 commit and places them in your <filename>Documents</filename>
2570 directory:
2571 <literallayout class='monospaced'>
2572 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
2573 </literallayout>
2574 </para>
2575 </section>
2576
2577 <section id='showing-a-particular-feature-or-branch-change'>
2578 <title>Showing a Particular Feature or Branch Change</title>
2579
2580 <para>
2581 Tags in the Yocto Project kernel tree divide changes for
2582 significant features or branches.
2583 The <filename>git show</filename>&nbsp;<replaceable>tag</replaceable>
2584 command shows changes based on a tag.
2585 Here is an example that shows <filename>systemtap</filename>
2586 changes:
2587 <literallayout class='monospaced'>
2588 $ git show systemtap
2589 </literallayout>
2590 You can use the
2591 <filename>git branch --contains</filename>&nbsp;<replaceable>tag</replaceable>
2592 command to show the branches that contain a particular feature.
2593 This command shows the branches that contain the
2594 <filename>systemtap</filename> feature:
2595 <literallayout class='monospaced'>
2596 $ git branch --contains systemtap
2597 </literallayout>
2598 </para>
2599 </section>
2600 </section>
2601
2602 <section id='adding-recipe-space-kernel-features'>
2603 <title>Adding Recipe-Space Kernel Features</title>
2604
2605 <para>
2606 You can add kernel features in the
2607 <link linkend='recipe-space-metadata'>recipe-space</link> by
2608 using the
2609 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
2610 variable and by specifying the feature's <filename>.scc</filename>
2611 file path in the
2612 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2613 statement.
2614 When you add features using this method, the OpenEmbedded build
2615 system checks to be sure the features are present.
2616 If the features are not present, the build stops.
2617 Kernel features are the last elements processed for configuring
2618 and patching the kernel.
2619 Therefore, adding features in this manner is a way
2620 to enforce specific features are present and enabled
2621 without needing to do a full audit of any other layer's additions
2622 to the <filename>SRC_URI</filename> statement.
2623 </para>
2624
2625 <para>
2626 You add a kernel feature by providing the feature as part of the
2627 <filename>KERNEL_FEATURES</filename> variable and by providing the
2628 path to the feature's <filename>.scc</filename> file, which is
2629 relative to the root of the kernel Metadata.
2630 The OpenEmbedded build system searches all forms of kernel
2631 Metadata on the <filename>SRC_URI</filename> statement regardless
2632 of whether the Metadata is in the "kernel-cache", system kernel
2633 Metadata, or a recipe-space Metadata (i.e. part of the kernel
2634 recipe).
2635 See the
2636 "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>"
2637 section for additional information.
2638 </para>
2639
2640 <para>
2641 When you specify the feature's <filename>.scc</filename> file
2642 on the <filename>SRC_URI</filename> statement, the OpenEmbedded
2643 build system adds the directory of that
2644 <filename>.scc</filename> file along with all its subdirectories
2645 to the kernel feature search path.
2646 Because subdirectories are searched, you can reference a single
2647 <filename>.scc</filename> file in the
2648 <filename>SRC_URI</filename> statement to reference multiple kernel
2649 features.
2650 </para>
2651
2652 <para>
2653 Consider the following example that adds the "test.scc" feature
2654 to the build.
2655 <orderedlist>
2656 <listitem><para>
2657 <emphasis>Create the Feature File:</emphasis>
2658 Create a <filename>.scc</filename> file and locate it
2659 just as you would any other patch file,
2660 <filename>.cfg</filename> file, or fetcher item
2661 you specify in the <filename>SRC_URI</filename>
2662 statement.
2663 <note><title>Notes</title>
2664 <itemizedlist>
2665 <listitem><para>
2666 You must add the directory of the
2667 <filename>.scc</filename> file to the fetcher's
2668 search path in the same manner as you would
2669 add a <filename>.patch</filename> file.
2670 </para></listitem>
2671 <listitem><para>
2672 You can create additional
2673 <filename>.scc</filename> files beneath the
2674 directory that contains the file you are
2675 adding.
2676 All subdirectories are searched during the
2677 build as potential feature directories.
2678 </para></listitem>
2679 </itemizedlist>
2680 </note>
2681 Continuing with the example, suppose the "test.scc"
2682 feature you are adding has a
2683 <filename>test.scc</filename> file in the following
2684 directory:
2685 <literallayout class='monospaced'>
2686 <replaceable>my_recipe</replaceable>
2687 |
2688 +-linux-yocto
2689 |
2690 +-test.cfg
2691 +-test.scc
2692 </literallayout>
2693 In this example, the <filename>linux-yocto</filename>
2694 directory has both the feature
2695 <filename>test.scc</filename> file and a similarly
2696 named configuration fragment file
2697 <filename>test.cfg</filename>.
2698 </para></listitem>
2699 <listitem><para>
2700 <emphasis>Add the Feature File to <filename>SRC_URI</filename>:</emphasis>
2701 Add the <filename>.scc</filename> file to the
2702 recipe's <filename>SRC_URI</filename> statement:
2703 <literallayout class='monospaced'>
2704 SRC_URI_append = " file://test.scc"
2705 </literallayout>
2706 The leading space before the path is important as the
2707 path is appended to the existing path.
2708 </para></listitem>
2709 <listitem><para>
2710 <emphasis>Specify the Feature as a Kernel Feature:</emphasis>
2711 Use the <filename>KERNEL_FEATURES</filename> statement
2712 to specify the feature as a kernel feature:
2713 <literallayout class='monospaced'>
2714 KERNEL_FEATURES_append = " test.scc"
2715 </literallayout>
2716 The OpenEmbedded build system processes the kernel feature
2717 when it builds the kernel.
2718 <note>
2719 If other features are contained below "test.scc",
2720 then their directories are relative to the directory
2721 containing the <filename>test.scc</filename> file.
2722 </note>
2723 </para></listitem>
2724 </orderedlist>
2725 </para>
2726 </section>
2727</chapter>
2728<!--
2729vim: expandtab tw=80 ts=4
2730-->
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
deleted file mode 100644
index bf0c525caf..0000000000
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ /dev/null
@@ -1,622 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<appendix id='kernel-dev-concepts-appx'>
7<title>Advanced Kernel Concepts</title>
8
9 <section id='kernel-big-picture'>
10 <title>Yocto Project Kernel Development and Maintenance</title>
11
12 <para>
13 Kernels available through the Yocto Project (Yocto Linux kernels),
14 like other kernels, are based off the Linux kernel releases from
15 <ulink url='http://www.kernel.org'></ulink>.
16 At the beginning of a major Linux kernel development cycle, the
17 Yocto Project team chooses a Linux kernel based on factors such as
18 release timing, the anticipated release timing of final upstream
19 <filename>kernel.org</filename> versions, and Yocto Project
20 feature requirements.
21 Typically, the Linux kernel chosen is in the final stages of
22 development by the Linux community.
23 In other words, the Linux kernel is in the release candidate
24 or "rc" phase and has yet to reach final release.
25 But, by being in the final stages of external development, the
26 team knows that the <filename>kernel.org</filename> final release
27 will clearly be within the early stages of the Yocto Project
28 development window.
29 </para>
30
31 <para>
32 This balance allows the Yocto Project team to deliver the most
33 up-to-date Yocto Linux kernel possible, while still ensuring that
34 the team has a stable official release for the baseline Linux
35 kernel version.
36 </para>
37
38 <para>
39 As implied earlier, the ultimate source for Yocto Linux kernels
40 are released kernels from <filename>kernel.org</filename>.
41 In addition to a foundational kernel from
42 <filename>kernel.org</filename>, the available Yocto Linux kernels
43 contain a mix of important new mainline developments, non-mainline
44 developments (when no alternative exists), Board Support Package
45 (BSP) developments, and custom features.
46 These additions result in a commercially released Yocto
47 Project Linux kernel that caters to specific embedded designer
48 needs for targeted hardware.
49 </para>
50
51 <para>
52 You can find a web interface to the Yocto Linux kernels in the
53 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
54 at
55 <ulink url='&YOCTO_GIT_URL;'></ulink>.
56 If you look at the interface, you will see to the left a
57 grouping of Git repositories titled "Yocto Linux Kernel".
58 Within this group, you will find several Linux Yocto kernels
59 developed and included with Yocto Project releases:
60 <itemizedlist>
61 <listitem><para>
62 <emphasis><filename>linux-yocto-4.1</filename>:</emphasis>
63 The stable Yocto Project kernel to use with the Yocto
64 Project Release 2.0.
65 This kernel is based on the Linux 4.1 released kernel.
66 </para></listitem>
67 <listitem><para>
68 <emphasis><filename>linux-yocto-4.4</filename>:</emphasis>
69 The stable Yocto Project kernel to use with the Yocto
70 Project Release 2.1.
71 This kernel is based on the Linux 4.4 released kernel.
72 </para></listitem>
73 <listitem><para>
74 <emphasis><filename>linux-yocto-4.6</filename>:</emphasis>
75 A temporary kernel that is not tied to any Yocto Project
76 release.
77 </para></listitem>
78 <listitem><para>
79 <emphasis><filename>linux-yocto-4.8</filename>:</emphasis>
80 The stable yocto Project kernel to use with the Yocto
81 Project Release 2.2.
82 </para></listitem>
83 <listitem><para>
84 <emphasis><filename>linux-yocto-4.9</filename>:</emphasis>
85 The stable Yocto Project kernel to use with the Yocto
86 Project Release 2.3.
87 This kernel is based on the Linux 4.9 released kernel.
88 </para></listitem>
89 <listitem><para>
90 <emphasis><filename>linux-yocto-4.10</filename>:</emphasis>
91 The default stable Yocto Project kernel to use with the
92 Yocto Project Release 2.3.
93 This kernel is based on the Linux 4.10 released kernel.
94 </para></listitem>
95 <listitem><para>
96 <emphasis><filename>linux-yocto-4.12</filename>:</emphasis>
97 The default stable Yocto Project kernel to use with the
98 Yocto Project Release 2.4.
99 This kernel is based on the Linux 4.12 released kernel.
100 </para></listitem>
101 <listitem><para>
102 <emphasis><filename>yocto-kernel-cache</filename>:</emphasis>
103 The <filename>linux-yocto-cache</filename> contains
104 patches and configurations for the linux-yocto kernel
105 tree.
106 This repository is useful when working on the linux-yocto
107 kernel.
108 For more information on this "Advanced Kernel Metadata",
109 see the
110 "<link linkend='kernel-dev-advanced'>Working With Advanced Metadata (<filename>yocto-kernel-cache</filename>)</link>"
111 Chapter.
112 </para></listitem>
113 <listitem><para>
114 <emphasis><filename>linux-yocto-dev</filename>:</emphasis>
115 A development kernel based on the latest upstream release
116 candidate available.
117 </para></listitem>
118 </itemizedlist>
119 <note><title>Notes</title>
120 Long Term Support Initiative (LTSI) for Yocto Linux
121 kernels is as follows:
122 <itemizedlist>
123 <listitem><para>
124 For Yocto Project releases 1.7, 1.8, and 2.0,
125 the LTSI kernel is
126 <filename>linux-yocto-3.14</filename>.
127 </para></listitem>
128 <listitem><para>
129 For Yocto Project releases 2.1, 2.2, and 2.3,
130 the LTSI kernel is <filename>linux-yocto-4.1</filename>.
131 </para></listitem>
132 <listitem><para>
133 For Yocto Project release 2.4, the LTSI kernel is
134 <filename>linux-yocto-4.9</filename>
135 </para></listitem>
136 <listitem><para>
137 <filename>linux-yocto-4.4</filename> is an LTS
138 kernel.
139 </para></listitem>
140 </itemizedlist>
141 </note>
142 </para>
143
144 <para>
145 Once a Yocto Linux kernel is officially released, the Yocto
146 Project team goes into their next development cycle, or upward
147 revision (uprev) cycle, while still continuing maintenance on the
148 released kernel.
149 It is important to note that the most sustainable and stable way
150 to include feature development upstream is through a kernel uprev
151 process.
152 Back-porting hundreds of individual fixes and minor features from
153 various kernel versions is not sustainable and can easily
154 compromise quality.
155 </para>
156
157 <para>
158 During the uprev cycle, the Yocto Project team uses an ongoing
159 analysis of Linux kernel development, BSP support, and release
160 timing to select the best possible <filename>kernel.org</filename>
161 Linux kernel version on which to base subsequent Yocto Linux
162 kernel development.
163 The team continually monitors Linux community kernel development
164 to look for significant features of interest.
165 The team does consider back-porting large features if they have a
166 significant advantage.
167 User or community demand can also trigger a back-port or creation
168 of new functionality in the Yocto Project baseline kernel during
169 the uprev cycle.
170 </para>
171
172 <para>
173 Generally speaking, every new Linux kernel both adds features and
174 introduces new bugs.
175 These consequences are the basic properties of upstream
176 Linux kernel development and are managed by the Yocto Project
177 team's Yocto Linux kernel development strategy.
178 It is the Yocto Project team's policy to not back-port minor
179 features to the released Yocto Linux kernel.
180 They only consider back-porting significant technological
181 jumps &dash; and, that is done after a complete gap analysis.
182 The reason for this policy is that back-porting any small to
183 medium sized change from an evolving Linux kernel can easily
184 create mismatches, incompatibilities and very subtle errors.
185 </para>
186
187 <para>
188 The policies described in this section result in both a stable
189 and a cutting edge Yocto Linux kernel that mixes forward ports of
190 existing Linux kernel features and significant and critical new
191 functionality.
192 Forward porting Linux kernel functionality into the Yocto Linux
193 kernels available through the Yocto Project can be thought of as
194 a "micro uprev."
195 The many "micro uprevs" produce a Yocto Linux kernel version with
196 a mix of important new mainline, non-mainline, BSP developments
197 and feature integrations.
198 This Yocto Linux kernel gives insight into new features and
199 allows focused amounts of testing to be done on the kernel,
200 which prevents surprises when selecting the next major uprev.
201 The quality of these cutting edge Yocto Linux kernels is evolving
202 and the kernels are used in leading edge feature and BSP
203 development.
204 </para>
205 </section>
206
207 <section id='yocto-linux-kernel-architecture-and-branching-strategies'>
208 <title>Yocto Linux Kernel Architecture and Branching Strategies</title>
209
210 <para>
211 As mentioned earlier, a key goal of the Yocto Project is
212 to present the developer with a kernel that has a clear and
213 continuous history that is visible to the user.
214 The architecture and mechanisms, in particular the branching
215 strategies, used achieve that goal in a manner similar to
216 upstream Linux kernel development in
217 <filename>kernel.org</filename>.
218 </para>
219
220 <para>
221 You can think of a Yocto Linux kernel as consisting of a
222 baseline Linux kernel with added features logically structured
223 on top of the baseline.
224 The features are tagged and organized by way of a branching
225 strategy implemented by the Yocto Project team using the
226 Source Code Manager (SCM) Git.
227 <note><title>Notes</title>
228 <itemizedlist>
229 <listitem><para>
230 Git is the obvious SCM for meeting the Yocto Linux
231 kernel organizational and structural goals described
232 in this section.
233 Not only is Git the SCM for Linux kernel development in
234 <filename>kernel.org</filename> but, Git continues to
235 grow in popularity and supports many different work
236 flows, front-ends and management techniques.
237 </para></listitem>
238 <listitem><para>
239 You can find documentation on Git at
240 <ulink url='http://git-scm.com/documentation'></ulink>.
241 You can also get an introduction to Git as it
242 applies to the Yocto Project in the
243 "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
244 section in the Yocto Project Overview and Concepts
245 Manual.
246 The latter reference provides an overview of
247 Git and presents a minimal set of Git commands
248 that allows you to be functional using Git.
249 You can use as much, or as little, of what Git
250 has to offer to accomplish what you need for your
251 project.
252 You do not have to be a "Git Expert" in order to
253 use it with the Yocto Project.
254 </para></listitem>
255 </itemizedlist>
256 </note>
257 </para>
258
259 <para>
260 Using Git's tagging and branching features, the Yocto Project
261 team creates kernel branches at points where functionality is
262 no longer shared and thus, needs to be isolated.
263 For example, board-specific incompatibilities would require
264 different functionality and would require a branch to
265 separate the features.
266 Likewise, for specific kernel features, the same branching
267 strategy is used.
268 </para>
269
270 <para>
271 This "tree-like" architecture results in a structure that has
272 features organized to be specific for particular functionality,
273 single kernel types, or a subset of kernel types.
274 Thus, the user has the ability to see the added features and the
275 commits that make up those features.
276 In addition to being able to see added features, the user
277 can also view the history of what made up the baseline
278 Linux kernel.
279 </para>
280
281 <para>
282 Another consequence of this strategy results in not having to
283 store the same feature twice internally in the tree.
284 Rather, the kernel team stores the unique differences required
285 to apply the feature onto the kernel type in question.
286 <note>
287 The Yocto Project team strives to place features in the tree
288 such that features can be shared by all boards and kernel
289 types where possible.
290 However, during development cycles or when large features
291 are merged, the team cannot always follow this practice.
292 In those cases, the team uses isolated branches to merge
293 features.
294 </note>
295 </para>
296
297 <para>
298 BSP-specific code additions are handled in a similar manner to
299 kernel-specific additions.
300 Some BSPs only make sense given certain kernel types.
301 So, for these types, the team creates branches off the end
302 of that kernel type for all of the BSPs that are supported on
303 that kernel type.
304 From the perspective of the tools that create the BSP branch,
305 the BSP is really no different than a feature.
306 Consequently, the same branching strategy applies to BSPs as
307 it does to kernel features.
308 So again, rather than store the BSP twice, the team only
309 stores the unique differences for the BSP across the supported
310 multiple kernels.
311 </para>
312
313 <para>
314 While this strategy can result in a tree with a significant number
315 of branches, it is important to realize that from the developer's
316 point of view, there is a linear path that travels from the
317 baseline <filename>kernel.org</filename>, through a select
318 group of features and ends with their BSP-specific commits.
319 In other words, the divisions of the kernel are transparent and
320 are not relevant to the developer on a day-to-day basis.
321 From the developer's perspective, this path is the "master" branch
322 in Git terms.
323 The developer does not need to be aware of the existence of any
324 other branches at all.
325 Of course, value exists in the having these branches in the tree,
326 should a person decide to explore them.
327 For example, a comparison between two BSPs at either the commit
328 level or at the line-by-line code <filename>diff</filename> level
329 is now a trivial operation.
330 </para>
331
332 <para>
333 The following illustration shows the conceptual Yocto
334 Linux kernel.
335 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
336 </para>
337
338 <para>
339 In the illustration, the "Kernel.org Branch Point" marks the
340 specific spot (or Linux kernel release) from which the
341 Yocto Linux kernel is created.
342 From this point forward in the tree, features and differences
343 are organized and tagged.
344 </para>
345
346 <para>
347 The "Yocto Project Baseline Kernel" contains functionality that
348 is common to every kernel type and BSP that is organized
349 further along in the tree.
350 Placing these common features in the tree this way means
351 features do not have to be duplicated along individual
352 branches of the tree structure.
353 </para>
354
355 <para>
356 From the "Yocto Project Baseline Kernel", branch points represent
357 specific functionality for individual Board Support Packages
358 (BSPs) as well as real-time kernels.
359 The illustration represents this through three BSP-specific
360 branches and a real-time kernel branch.
361 Each branch represents some unique functionality for the BSP
362 or for a real-time Yocto Linux kernel.
363 </para>
364
365 <para>
366 In this example structure, the "Real-time (rt) Kernel" branch has
367 common features for all real-time Yocto Linux kernels and
368 contains more branches for individual BSP-specific real-time
369 kernels.
370 The illustration shows three branches as an example.
371 Each branch points the way to specific, unique features for a
372 respective real-time kernel as they apply to a given BSP.
373 </para>
374
375 <para>
376 The resulting tree structure presents a clear path of markers
377 (or branches) to the developer that, for all practical
378 purposes, is the Yocto Linux kernel needed for any given set of
379 requirements.
380 <note>
381 Keep in mind the figure does not take into account all the
382 supported Yocto Linux kernels, but rather shows a single
383 generic kernel just for conceptual purposes.
384 Also keep in mind that this structure represents the Yocto
385 Project
386 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
387 that are either pulled from during the build or established
388 on the host development system prior to the build by either
389 cloning a particular kernel's Git repository or by
390 downloading and unpacking a tarball.
391 </note>
392 </para>
393
394 <para>
395 Working with the kernel as a structured tree follows recognized
396 community best practices.
397 In particular, the kernel as shipped with the product, should be
398 considered an "upstream source" and viewed as a series of
399 historical and documented modifications (commits).
400 These modifications represent the development and stabilization
401 done by the Yocto Project kernel development team.
402 </para>
403
404 <para>
405 Because commits only change at significant release points in the
406 product life cycle, developers can work on a branch created
407 from the last relevant commit in the shipped Yocto Project Linux
408 kernel.
409 As mentioned previously, the structure is transparent to the
410 developer because the kernel tree is left in this state after
411 cloning and building the kernel.
412 </para>
413 </section>
414
415 <section id='kernel-build-file-hierarchy'>
416 <title>Kernel Build File Hierarchy</title>
417
418 <para>
419 Upstream storage of all the available kernel source code is
420 one thing, while representing and using the code on your host
421 development system is another.
422 Conceptually, you can think of the kernel source repositories
423 as all the source files necessary for all the supported
424 Yocto Linux kernels.
425 As a developer, you are just interested in the source files
426 for the kernel on which you are working.
427 And, furthermore, you need them available on your host system.
428 </para>
429
430 <para>
431 Kernel source code is available on your host system several
432 different ways:
433 <itemizedlist>
434 <listitem><para>
435 <emphasis>Files Accessed While using <filename>devtool</filename>:</emphasis>
436 <filename>devtool</filename>, which is available with the
437 Yocto Project, is the preferred method by which to
438 modify the kernel.
439 See the
440 "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
441 section.
442 </para></listitem>
443 <listitem><para>
444 <emphasis>Cloned Repository:</emphasis>
445 If you are working in the kernel all the time, you probably
446 would want to set up your own local Git repository of the
447 Yocto Linux kernel tree.
448 For information on how to clone a Yocto Linux kernel
449 Git repository, see the
450 "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
451 section.
452 </para></listitem>
453 <listitem><para>
454 <emphasis>Temporary Source Files from a Build:</emphasis>
455 If you just need to make some patches to the kernel using
456 a traditional BitBake workflow (i.e. not using the
457 <filename>devtool</filename>), you can access temporary
458 kernel source files that were extracted and used during
459 a kernel build.
460 </para></listitem>
461 </itemizedlist>
462 </para>
463
464 <para>
465 The temporary kernel source files resulting from a build using
466 BitBake have a particular hierarchy.
467 When you build the kernel on your development system, all files
468 needed for the build are taken from the source repositories
469 pointed to by the
470 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
471 variable and gathered in a temporary work area where they are
472 subsequently used to create the unique kernel.
473 Thus, in a sense, the process constructs a local source tree
474 specific to your kernel from which to generate the new kernel
475 image.
476 </para>
477
478 <para>
479 The following figure shows the temporary file structure
480 created on your host system when you build the kernel using
481 Bitbake.
482 This
483 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
484 contains all the source files used during the build.
485 <imagedata fileref="figures/kernel-overview-2-generic.png"
486 width="6in" depth="5in" align="center" scale="100" />
487 </para>
488
489 <para>
490 Again, for additional information on the Yocto Project kernel's
491 architecture and its branching strategy, see the
492 "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>"
493 section.
494 You can also reference the
495 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
496 and
497 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
498 sections for detailed example that modifies the kernel.
499 </para>
500 </section>
501
502 <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'>
503 <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title>
504
505 <para>
506 This section describes part of the kernel configuration audit
507 phase that most developers can ignore.
508 For general information on kernel configuration including
509 <filename>menuconfig</filename>, <filename>defconfig</filename>
510 files, and configuration fragments, see the
511 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
512 section.
513 </para>
514
515 <para>
516 During this part of the audit phase, the contents of the final
517 <filename>.config</filename> file are compared against the
518 fragments specified by the system.
519 These fragments can be system fragments, distro fragments,
520 or user-specified configuration elements.
521 Regardless of their origin, the OpenEmbedded build system
522 warns the user if a specific option is not included in the
523 final kernel configuration.
524 </para>
525
526 <para>
527 By default, in order to not overwhelm the user with
528 configuration warnings, the system only reports missing
529 "hardware" options as they could result in a boot
530 failure or indicate that important hardware is not available.
531 </para>
532
533 <para>
534 To determine whether or not a given option is "hardware" or
535 "non-hardware", the kernel Metadata in
536 <filename>yocto-kernel-cache</filename> contains files that
537 classify individual or groups of options as either hardware
538 or non-hardware.
539 To better show this, consider a situation where the
540 <filename>yocto-kernel-cache</filename> contains the following
541 files:
542 <literallayout class='monospaced'>
543 yocto-kernel-cache/features/drm-psb/hardware.cfg
544 yocto-kernel-cache/features/kgdb/hardware.cfg
545 yocto-kernel-cache/ktypes/base/hardware.cfg
546 yocto-kernel-cache/bsp/mti-malta32/hardware.cfg
547 yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg
548 yocto-kernel-cache/bsp/qemuarma9/hardware.cfg
549 yocto-kernel-cache/bsp/mti-malta64/hardware.cfg
550 yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg
551 yocto-kernel-cache/bsp/common-pc/hardware.cfg
552 yocto-kernel-cache/bsp/common-pc-64/hardware.cfg
553 yocto-kernel-cache/features/rfkill/non-hardware.cfg
554 yocto-kernel-cache/ktypes/base/non-hardware.cfg
555 yocto-kernel-cache/features/aufs/non-hardware.kcf
556 yocto-kernel-cache/features/ocf/non-hardware.kcf
557 yocto-kernel-cache/ktypes/base/non-hardware.kcf
558 yocto-kernel-cache/ktypes/base/hardware.kcf
559 yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf
560 </literallayout>
561 The following list provides explanations for the various
562 files:
563 <itemizedlist>
564 <listitem><para>
565 <filename>hardware.kcf</filename>:
566 Specifies a list of kernel Kconfig files that contain
567 hardware options only.
568 </para></listitem>
569 <listitem><para>
570 <filename>non-hardware.kcf</filename>:
571 Specifies a list of kernel Kconfig files that contain
572 non-hardware options only.
573 </para></listitem>
574 <listitem><para>
575 <filename>hardware.cfg</filename>:
576 Specifies a list of kernel <filename>CONFIG_</filename>
577 options that are hardware, regardless of whether or not
578 they are within a Kconfig file specified by a hardware
579 or non-hardware Kconfig file (i.e.
580 <filename>hardware.kcf</filename> or
581 <filename>non-hardware.kcf</filename>).
582 </para></listitem>
583 <listitem><para>
584 <filename>non-hardware.cfg</filename>:
585 Specifies a list of kernel <filename>CONFIG_</filename>
586 options that are not hardware, regardless of whether or
587 not they are within a Kconfig file specified by a
588 hardware or non-hardware Kconfig file (i.e.
589 <filename>hardware.kcf</filename> or
590 <filename>non-hardware.kcf</filename>).
591 </para></listitem>
592 </itemizedlist>
593 Here is a specific example using the
594 <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>:
595 <literallayout class='monospaced'>
596 CONFIG_SERIAL_8250
597 CONFIG_SERIAL_8250_CONSOLE
598 CONFIG_SERIAL_8250_NR_UARTS
599 CONFIG_SERIAL_8250_PCI
600 CONFIG_SERIAL_CORE
601 CONFIG_SERIAL_CORE_CONSOLE
602 CONFIG_VGA_ARB
603 </literallayout>
604 The kernel configuration audit automatically detects these
605 files (hence the names must be exactly the ones discussed here),
606 and uses them as inputs when generating warnings about the
607 final <filename>.config</filename> file.
608 </para>
609
610 <para>
611 A user-specified kernel Metadata repository, or recipe space
612 feature, can use these same files to classify options that are
613 found within its <filename>.cfg</filename> files as hardware
614 or non-hardware, to prevent the OpenEmbedded build system from
615 producing an error or warning when an option is not in the
616 final <filename>.config</filename> file.
617 </para>
618 </section>
619</appendix>
620<!--
621vim: expandtab tw=80 ts=4
622-->
diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl
deleted file mode 100644
index 88bf7c678a..0000000000
--- a/documentation/kernel-dev/kernel-dev-customization.xsl
+++ /dev/null
@@ -1,28 +0,0 @@
1<?xml version='1.0'?>
2<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
3
4<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">
5
6 <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
7
8<!--
9
10 <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
11
12 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
13
14-->
15
16 <xsl:include href="../template/permalinks.xsl"/>
17 <xsl:include href="../template/section.title.xsl"/>
18 <xsl:include href="../template/component.title.xsl"/>
19 <xsl:include href="../template/division.title.xsl"/>
20 <xsl:include href="../template/formal.object.heading.xsl"/>
21
22 <xsl:param name="html.stylesheet" select="'kernel-dev-style.css'" />
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
28</xsl:stylesheet>
diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml
deleted file mode 100644
index d76f0a4e32..0000000000
--- a/documentation/kernel-dev/kernel-dev-faq.xml
+++ /dev/null
@@ -1,143 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<appendix id='kernel-dev-faq'>
7<title>Kernel Development FAQ</title>
8
9<section id='kernel-dev-faq-section'>
10 <title>Common Questions and Solutions</title>
11
12 <para>
13 The following lists some solutions for common questions.
14
15
16 <qandaset>
17 <qandaentry>
18 <question>
19 <para>
20 How do I use my own Linux kernel <filename>.config</filename>
21 file?
22 </para>
23 </question>
24 <answer>
25 <para>
26 Refer to the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
27 section for information.
28 </para>
29 </answer>
30 </qandaentry>
31
32 <qandaentry>
33 <question>
34 <para>
35 How do I create configuration fragments?
36 </para>
37 </question>
38 <answer>
39 <para>
40 Refer to the
41 "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
42 section for information.
43 </para>
44 </answer>
45 </qandaentry>
46
47 <qandaentry>
48 <question>
49 <para>
50 How do I use my own Linux kernel sources?
51 </para>
52 </question>
53 <answer>
54 <para>
55 Refer to the "<link linkend='working-with-your-own-sources'>Working With Your Own Sources</link>"
56 section for information.
57 </para>
58 </answer>
59 </qandaentry>
60
61 <qandaentry>
62 <question>
63 <para>
64 How do I install/not-install the kernel image on the rootfs?
65 </para>
66 </question>
67 <answer>
68 <para>
69 The kernel image (e.g. <filename>vmlinuz</filename>) is provided
70 by the <filename>kernel-image</filename> package.
71 Image recipes depend on <filename>kernel-base</filename>.
72 To specify whether or not the kernel
73 image is installed in the generated root filesystem, override
74 <filename>RDEPENDS_kernel-base</filename> to include or not
75 include "kernel-image".</para>
76 <para>See the
77 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
78 section in the Yocto Project Development Tasks Manual
79 for information on how to use an append file to
80 override metadata.
81 </para>
82 </answer>
83 </qandaentry>
84
85 <qandaentry>
86 <question>
87 <para>
88 How do I install a specific kernel module?
89 </para>
90 </question>
91 <answer>
92 <para>
93 Linux kernel modules are packaged individually.
94 To ensure a specific kernel module is included in an image,
95 include it in the appropriate machine
96 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
97 variable.</para>
98 <para>These other variables are useful for installing specific
99 modules:
100 <literallayout class='monospaced'>
101 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
102 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
103 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
104 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
105 </literallayout>
106 For example, set the following in the <filename>qemux86.conf</filename>
107 file to include the <filename>ab123</filename> kernel modules
108 with images built for the <filename>qemux86</filename> machine:
109 <literallayout class='monospaced'>
110 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
111 </literallayout>
112 For more information, see the
113 "<link linkend='incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</link>"
114 section.
115 </para>
116 </answer>
117 </qandaentry>
118
119 <qandaentry>
120 <question>
121 <para>
122 How do I change the Linux kernel command line?
123 </para>
124 </question>
125 <answer>
126 <para>
127 The Linux kernel command line is typically specified in
128 the machine config using the <filename>APPEND</filename> variable.
129 For example, you can add some helpful debug information doing
130 the following:
131 <literallayout class='monospaced'>
132 APPEND += "printk.time=y initcall_debug debug"
133 </literallayout>
134 </para>
135 </answer>
136 </qandaentry>
137 </qandaset>
138 </para>
139</section>
140</appendix>
141<!--
142vim: expandtab tw=80 ts=4
143-->
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
deleted file mode 100644
index 7c1ea0e510..0000000000
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ /dev/null
@@ -1,260 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='kernel-dev-intro'>
7<title>Introduction</title>
8
9<section id='kernel-dev-overview'>
10 <title>Overview</title>
11
12 <para>
13 Regardless of how you intend to make use of the Yocto Project,
14 chances are you will work with the Linux kernel.
15 This manual describes how to set up your build host to support
16 kernel development, introduces the kernel development process,
17 provides background information on the Yocto Linux kernel
18 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
19 describes common tasks you can perform using the kernel tools,
20 shows you how to use the kernel Metadata needed to work with
21 the kernel inside the Yocto Project, and provides insight into how
22 the Yocto Project team develops and maintains Yocto Linux kernel
23 Git repositories and Metadata.
24 </para>
25
26 <para>
27 Each Yocto Project release has a set of Yocto Linux kernel recipes,
28 whose Git repositories you can view in the Yocto
29 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
30 the "Yocto Linux Kernel" heading.
31 New recipes for the release track the latest Linux kernel
32 upstream developments from
33 <ulink url='http://www.kernel.org'></ulink> and introduce
34 newly-supported platforms.
35 Previous recipes in the release are refreshed and supported for at
36 least one additional Yocto Project release.
37 As they align, these previous releases are updated to include the
38 latest from the Long Term Support Initiative (LTSI) project.
39 You can learn more about Yocto Linux kernels and LTSI in the
40 "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>"
41 section.
42 </para>
43
44 <para>
45 Also included is a Yocto Linux kernel development recipe
46 (<filename>linux-yocto-dev.bb</filename>) should you want to work
47 with the very latest in upstream Yocto Linux kernel development and
48 kernel Metadata development.
49 <note>
50 For more on Yocto Linux kernels, see the
51 "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>
52 section.
53 </note>
54 </para>
55
56 <para>
57 The Yocto Project also provides a powerful set of kernel
58 tools for managing Yocto Linux kernel sources and configuration data.
59 You can use these tools to make a single configuration change,
60 apply multiple patches, or work with your own kernel sources.
61 </para>
62
63 <para>
64 In particular, the kernel tools allow you to generate configuration
65 fragments that specify only what you must, and nothing more.
66 Configuration fragments only need to contain the highest level
67 visible <filename>CONFIG</filename> options as presented by the
68 Yocto Linux kernel <filename>menuconfig</filename> system.
69 Contrast this against a complete Yocto Linux kernel
70 <filename>.config</filename> file, which includes all the automatically
71 selected <filename>CONFIG</filename> options.
72 This efficiency reduces your maintenance effort and allows you
73 to further separate your configuration in ways that make sense for
74 your project.
75 A common split separates policy and hardware.
76 For example, all your kernels might support the
77 <filename>proc</filename> and <filename>sys</filename> filesystems,
78 but only specific boards require sound, USB, or specific drivers.
79 Specifying these configurations individually allows you to aggregate
80 them together as needed, but maintains them in only one place.
81 Similar logic applies to separating source changes.
82 </para>
83
84 <para>
85 If you do not maintain your own kernel sources and need to make
86 only minimal changes to the sources, the released recipes provide a
87 vetted base upon which to layer your changes.
88 Doing so allows you to benefit from the continual kernel
89 integration and testing performed during development of the
90 Yocto Project.
91 </para>
92
93 <para>
94 If, instead, you have a very specific Linux kernel source tree
95 and are unable to align with one of the official Yocto Linux kernel
96 recipes, an alternative exists by which you can use the Yocto
97 Project Linux kernel tools with your own kernel sources.
98 </para>
99
100 <para>
101 The remainder of this manual provides instructions for completing
102 specific Linux kernel development tasks.
103 These instructions assume you are comfortable working with
104 <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
105 recipes and basic open-source development tools.
106 Understanding these concepts will facilitate the process of working
107 with the kernel recipes.
108 If you find you need some additional background, please be sure to
109 review and understand the following documentation:
110 <itemizedlist>
111 <listitem><para>
112 <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
113 document.
114 </para></listitem>
115 <listitem><para>
116 <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
117 </para></listitem>
118 <listitem><para>
119 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
120 as described in the Yocto Project Application Development and
121 the Extensible Software Development Kit (eSDK) manual.
122 </para></listitem>
123 <listitem><para>
124 The
125 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
126 section in the Yocto Project Development Tasks Manual.
127 </para></listitem>
128 <listitem><para>
129 The
130 "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
131 section.
132 </para></listitem>
133 </itemizedlist>
134 </para>
135</section>
136
137<section id='kernel-modification-workflow'>
138 <title>Kernel Modification Workflow</title>
139
140 <para>
141 Kernel modification involves changing the Yocto Project kernel,
142 which could involve changing configuration options as well as adding
143 new kernel recipes.
144 Configuration changes can be added in the form of configuration
145 fragments, while recipe modification comes through the kernel's
146 <filename>recipes-kernel</filename> area in a kernel layer you create.
147 </para>
148
149 <para>
150 This section presents a high-level overview of the Yocto Project
151 kernel modification workflow.
152 The illustration and accompanying list provide general information
153 and references for further information.
154 <imagedata fileref="figures/kernel-dev-flow.png"
155 width="9in" depth="5in" align="center" scalefit="1" />
156 </para>
157
158 <para>
159 <orderedlist>
160 <listitem><para>
161
162
163 <emphasis>Set up Your Host Development System to Support
164 Development Using the Yocto Project</emphasis>:
165 See the
166 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>"
167 section in the Yocto Project Development Tasks Manual for
168 options on how to get a build host ready to use the Yocto
169 Project.
170 </para></listitem>
171 <listitem><para>
172 <emphasis>Set Up Your Host Development System for Kernel Development:</emphasis>
173 It is recommended that you use <filename>devtool</filename>
174 and an extensible SDK for kernel development.
175 Alternatively, you can use traditional kernel development
176 methods with the Yocto Project.
177 Either way, there are steps you need to take to get the
178 development environment ready.</para>
179
180 <para>Using <filename>devtool</filename> and the eSDK requires
181 that you have a clean build of the image and that you are
182 set up with the appropriate eSDK.
183 For more information, see the
184 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
185 section.</para>
186
187 <para>Using traditional kernel development requires that you
188 have the kernel source available in an isolated local Git
189 repository.
190 For more information, see the
191 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
192 section.
193 </para></listitem>
194 <listitem><para>
195 <emphasis>Make Changes to the Kernel Source Code if
196 applicable:</emphasis>
197 Modifying the kernel does not always mean directly
198 changing source files.
199 However, if you have to do this, you make the changes to the
200 files in the eSDK's Build Directory if you are using
201 <filename>devtool</filename>.
202 For more information, see the
203 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
204 section.</para>
205
206 <para>If you are using traditional kernel development, you
207 edit the source files in the kernel's local Git repository.
208 For more information, see the
209 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
210 section.
211 </para></listitem>
212 <listitem><para>
213 <emphasis>Make Kernel Configuration Changes if
214 Applicable:</emphasis>
215 If your situation calls for changing the kernel's
216 configuration, you can use
217 <link linkend='using-menuconfig'><filename>menuconfig</filename></link>,
218 which allows you to interactively develop and test the
219 configuration changes you are making to the kernel.
220 Saving changes you make with <filename>menuconfig</filename>
221 updates the kernel's <filename>.config</filename> file.
222 <note><title>Warning</title>
223 Try to resist the temptation to directly edit an
224 existing <filename>.config</filename> file, which is
225 found in the Build Directory among the source code
226 used for the build.
227 Doing so, can produce unexpected results when the
228 OpenEmbedded build system regenerates the configuration
229 file.
230 </note>
231 Once you are satisfied with the configuration
232 changes made using <filename>menuconfig</filename>
233 and you have saved them, you can directly compare the
234 resulting <filename>.config</filename> file against an
235 existing original and gather those changes into a
236 <link linkend='creating-config-fragments'>configuration fragment file</link>
237 to be referenced from within the kernel's
238 <filename>.bbappend</filename> file.</para>
239
240 <para>Additionally, if you are working in a BSP layer
241 and need to modify the BSP's kernel's configuration,
242 you can use <filename>menuconfig</filename>.
243 </para></listitem>
244 <listitem><para>
245 <emphasis>Rebuild the Kernel Image With Your Changes:</emphasis>
246 Rebuilding the kernel image applies your changes.
247 Depending on your target hardware, you can verify your changes
248 on actual hardware or perhaps QEMU.
249 </para></listitem>
250 </orderedlist>
251 The remainder of this developer's guide covers common tasks typically
252 used during kernel development, advanced Metadata usage, and Yocto Linux
253 kernel maintenance concepts.
254 </para>
255</section>
256
257</chapter>
258<!--
259vim: expandtab tw=80 ts=4
260-->
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml
deleted file mode 100644
index 3d9c7c66fd..0000000000
--- a/documentation/kernel-dev/kernel-dev-maint-appx.xml
+++ /dev/null
@@ -1,357 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<appendix id='kernel-dev-maint-appx'>
7<title>Kernel Maintenance</title>
8
9 <section id='tree-construction'>
10 <title>Tree Construction</title>
11
12 <para>
13 This section describes construction of the Yocto Project kernel
14 source repositories as accomplished by the Yocto Project team to
15 create Yocto Linux kernel repositories.
16 These kernel repositories are found under the heading "Yocto Linux
17 Kernel" at
18 <ulink url='&YOCTO_GIT_URL;'>&YOCTO_GIT_URL;</ulink>
19 and are shipped as part of a Yocto Project release.
20 The team creates these repositories by compiling and executing the
21 set of feature descriptions for every BSP and feature in the
22 product.
23 Those feature descriptions list all necessary patches,
24 configurations, branches, tags, and feature divisions found in a
25 Yocto Linux kernel.
26 Thus, the Yocto Project Linux kernel repository (or tree) and
27 accompanying Metadata in the
28 <filename>yocto-kernel-cache</filename> are built.
29 </para>
30
31 <para>
32 The existence of these repositories allow you to access and clone a
33 particular Yocto Project Linux kernel repository and use it to
34 build images based on their configurations and features.
35 </para>
36
37 <para>
38 You can find the files used to describe all the valid features and
39 BSPs in the Yocto Project Linux kernel in any clone of the Yocto
40 Project Linux kernel source repository and
41 <filename>yocto-kernel-cache</filename> Git trees.
42 For example, the following commands clone the Yocto Project
43 baseline Linux kernel that branches off
44 <filename>linux.org</filename> version 4.12 and the
45 <filename>yocto-kernel-cache</filename>, which contains stores of
46 kernel Metadata:
47 <literallayout class='monospaced'>
48 $ git clone git://git.yoctoproject.org/linux-yocto-4.12
49 $ git clone git://git.yoctoproject.org/linux-kernel-cache
50 </literallayout>
51 For more information on how to set up a local Git repository of
52 the Yocto Project Linux kernel files, see the
53 "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
54 section.
55 </para>
56
57 <para>
58 Once you have cloned the kernel Git repository and the
59 cache of Metadata on your local machine, you can discover the
60 branches that are available in the repository using the following
61 Git command:
62 <literallayout class='monospaced'>
63 $ git branch -a
64 </literallayout>
65 Checking out a branch allows you to work with a particular
66 Yocto Linux kernel.
67 For example, the following commands check out the
68 "standard/beagleboard" branch of the Yocto Linux kernel repository
69 and the "yocto-4.12" branch of the
70 <filename>yocto-kernel-cache</filename> repository:
71 <literallayout class='monospaced'>
72 $ cd ~/linux-yocto-4.12
73 $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
74 $ cd ~/linux-kernel-cache
75 $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12
76 </literallayout>
77 <note>
78 Branches in the <filename>yocto-kernel-cache</filename>
79 repository correspond to Yocto Linux kernel versions
80 (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
81 </note>
82 Once you have checked out and switched to appropriate branches,
83 you can see a snapshot of all the kernel source files used to
84 used to build that particular Yocto Linux kernel for a
85 particular board.
86 </para>
87
88 <para>
89 To see the features and configurations for a particular Yocto
90 Linux kernel, you need to examine the
91 <filename>yocto-kernel-cache</filename> Git repository.
92 As mentioned, branches in the
93 <filename>yocto-kernel-cache</filename> repository correspond to
94 Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>).
95 Branches contain descriptions in the form of
96 <filename>.scc</filename> and <filename>.cfg</filename> files.
97 </para>
98
99 <para>
100 You should realize, however, that browsing your local
101 <filename>yocto-kernel-cache</filename> repository for feature
102 descriptions and patches is not an effective way to determine what
103 is in a particular kernel branch.
104 Instead, you should use Git directly to discover the changes in
105 a branch.
106 Using Git is an efficient and flexible way to inspect changes to
107 the kernel.
108 <note>
109 Ground up reconstruction of the complete kernel tree is an
110 action only taken by the Yocto Project team during an active
111 development cycle.
112 When you create a clone of the kernel Git repository, you are
113 simply making it efficiently available for building and
114 development.
115 </note>
116 </para>
117
118 <para>
119 The following steps describe what happens when the Yocto Project
120 Team constructs the Yocto Project kernel source Git repository
121 (or tree) found at
122 <ulink url='&YOCTO_GIT_URL;'></ulink> given the
123 introduction of a new top-level kernel feature or BSP.
124 The following actions effectively provide the Metadata
125 and create the tree that includes the new feature, patch, or BSP:
126 <orderedlist>
127 <listitem><para>
128 <emphasis>Pass Feature to the OpenEmbedded Build System:</emphasis>
129 A top-level kernel feature is passed to the kernel build
130 subsystem.
131 Normally, this feature is a BSP for a particular kernel
132 type.
133 </para></listitem>
134 <listitem><para>
135 <emphasis>Locate Feature:</emphasis>
136 The file that describes the top-level feature is located
137 by searching these system directories:
138 <itemizedlist>
139 <listitem><para>
140 The in-tree kernel-cache directories, which are
141 located in the
142 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink>
143 repository organized under the "Yocto Linux Kernel"
144 heading in the
145 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
146 </para></listitem>
147 <listitem><para>
148 Areas pointed to by <filename>SRC_URI</filename>
149 statements found in kernel recipes
150 </para></listitem>
151 </itemizedlist>
152 For a typical build, the target of the search is a
153 feature description in an <filename>.scc</filename> file
154 whose name follows this format (e.g.
155 <filename>beaglebone-standard.scc</filename> and
156 <filename>beaglebone-preempt-rt.scc</filename>):
157 <literallayout class='monospaced'>
158 <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
159 </literallayout>
160 </para></listitem>
161 <listitem><para>
162 <emphasis>Expand Feature:</emphasis>
163 Once located, the feature description is either expanded
164 into a simple script of actions, or into an existing
165 equivalent script that is already part of the shipped
166 kernel.
167 </para></listitem>
168 <listitem><para>
169 <emphasis>Append Extra Features:</emphasis>
170 Extra features are appended to the top-level feature
171 description.
172 These features can come from the
173 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
174 variable in recipes.
175 </para></listitem>
176 <listitem><para>
177 <emphasis>Locate, Expand, and Append Each Feature:</emphasis>
178 Each extra feature is located, expanded and appended to
179 the script as described in step three.
180 </para></listitem>
181 <listitem><para>
182 <emphasis>Execute the Script:</emphasis>
183 The script is executed to produce files
184 <filename>.scc</filename> and <filename>.cfg</filename>
185 files in appropriate directories of the
186 <filename>yocto-kernel-cache</filename> repository.
187 These files are descriptions of all the branches, tags,
188 patches and configurations that need to be applied to the
189 base Git repository to completely create the
190 source (build) branch for the new BSP or feature.
191 </para></listitem>
192 <listitem><para>
193 <emphasis>Clone Base Repository:</emphasis>
194 The base repository is cloned, and the actions
195 listed in the <filename>yocto-kernel-cache</filename>
196 directories are applied to the tree.
197 </para></listitem>
198 <listitem><para>
199 <emphasis>Perform Cleanup:</emphasis>
200 The Git repositories are left with the desired branches
201 checked out and any required branching, patching and
202 tagging has been performed.
203 </para></listitem>
204 </orderedlist>
205 </para>
206
207 <para>
208 The kernel tree and cache are ready for developer consumption to
209 be locally cloned, configured, and built into a Yocto Project
210 kernel specific to some target hardware.
211 <note><title>Notes</title>
212 <itemizedlist>
213 <listitem><para>
214 The generated <filename>yocto-kernel-cache</filename>
215 repository adds to the kernel as shipped with the Yocto
216 Project release.
217 Any add-ons and configuration data are applied to the
218 end of an existing branch.
219 The full repository generation that is found in the
220 official Yocto Project kernel repositories at
221 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>
222 is the combination of all supported boards and
223 configurations.
224 </para></listitem>
225 <listitem><para>
226 The technique the Yocto Project team uses is flexible
227 and allows for seamless blending of an immutable
228 history with additional patches specific to a
229 deployment.
230 Any additions to the kernel become an integrated part
231 of the branches.
232 </para></listitem>
233 <listitem><para>
234 The full kernel tree that you see on
235 <ulink url='&YOCTO_GIT_URL;'></ulink> is
236 generated through repeating the above steps for all
237 valid BSPs.
238 The end result is a branched, clean history tree that
239 makes up the kernel for a given release.
240 You can see the script (<filename>kgit-scc</filename>)
241 responsible for this in the
242 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools'><filename>yocto-kernel-tools</filename></ulink>
243 repository.
244 </para></listitem>
245 <listitem><para>
246 The steps used to construct the full kernel tree are
247 the same steps that BitBake uses when it builds a
248 kernel image.
249 </para></listitem>
250 </itemizedlist>
251 </note>
252 </para>
253 </section>
254
255 <section id='build-strategy'>
256 <title>Build Strategy</title>
257
258 <para>
259 Once you have cloned a Yocto Linux kernel repository and the
260 cache repository (<filename>yocto-kernel-cache</filename>) onto
261 your development system, you can consider the compilation phase
262 of kernel development, which is building a kernel image.
263 Some prerequisites exist that are validated by the build process
264 before compilation starts:
265 </para>
266
267 <itemizedlist>
268 <listitem><para>
269 The
270 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
271 points to the kernel Git repository.
272 </para></listitem>
273 <listitem><para>
274 A BSP build branch with Metadata exists in the
275 <filename>yocto-kernel-cache</filename> repository.
276 The branch is based on the Yocto Linux kernel version and
277 has configurations and features grouped under the
278 <filename>yocto-kernel-cache/bsp</filename> directory.
279 For example, features and configurations for the
280 BeagleBone Board assuming a
281 <filename>linux-yocto_4.12</filename> kernel reside in the
282 following area of the <filename>yocto-kernel-cache</filename>
283 repository:
284 <literallayout class='monospaced'>
285 yocto-kernel-cache/bsp/beaglebone
286 </literallayout>
287 <note>
288 In the previous example, the "yocto-4.12" branch is
289 checked out in the <filename>yocto-kernel-cache</filename>
290 repository.
291 </note>
292 </para></listitem>
293 </itemizedlist>
294
295 <para>
296 The OpenEmbedded build system makes sure these conditions exist
297 before attempting compilation.
298 Other means, however, do exist, such as as bootstrapping a BSP.
299 </para>
300
301 <para>
302 Before building a kernel, the build process verifies the tree
303 and configures the kernel by processing all of the
304 configuration "fragments" specified by feature descriptions
305 in the <filename>.scc</filename> files.
306 As the features are compiled, associated kernel configuration
307 fragments are noted and recorded in the series of directories
308 in their compilation order.
309 The fragments are migrated, pre-processed and passed to the
310 Linux Kernel Configuration subsystem (<filename>lkc</filename>) as
311 raw input in the form of a <filename>.config</filename> file.
312 The <filename>lkc</filename> uses its own internal dependency
313 constraints to do the final processing of that information and
314 generates the final <filename>.config</filename> file that is used
315 during compilation.
316 </para>
317
318 <para>
319 Using the board's architecture and other relevant values from
320 the board's template, kernel compilation is started and a kernel
321 image is produced.
322 </para>
323
324 <para>
325 The other thing that you notice once you configure a kernel is that
326 the build process generates a build tree that is separate from
327 your kernel's local Git source repository tree.
328 This build tree has a name that uses the following form, where
329 <filename>${MACHINE}</filename> is the metadata name of the
330 machine (BSP) and "kernel_type" is one of the Yocto Project
331 supported kernel types (e.g. "standard"):
332 <literallayout class='monospaced'>
333 linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build
334 </literallayout>
335 </para>
336
337 <para>
338 The existing support in the <filename>kernel.org</filename> tree
339 achieves this default functionality.
340 </para>
341
342 <para>
343 This behavior means that all the generated files for a particular
344 machine or BSP are now in the build tree directory.
345 The files include the final <filename>.config</filename> file,
346 all the <filename>.o</filename> files, the <filename>.a</filename>
347 files, and so forth.
348 Since each machine or BSP has its own separate
349 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
350 in its own separate branch of the Git repository, you can easily
351 switch between different builds.
352 </para>
353 </section>
354</appendix>
355<!--
356vim: expandtab tw=80 ts=4
357-->
diff --git a/documentation/kernel-dev/kernel-dev-style.css b/documentation/kernel-dev/kernel-dev-style.css
deleted file mode 100644
index fc6fbb8de1..0000000000
--- a/documentation/kernel-dev/kernel-dev-style.css
+++ /dev/null
@@ -1,991 +0,0 @@
1/*
2
3 SPDX-License-Identifier: CC-BY-2.0-UK
4
5 Generic XHTML / DocBook XHTML CSS Stylesheet.
6
7 Browser wrangling and typographic design by
8 Oyvind Kolas / pippin@gimp.org
9
10 Customised for Poky by
11 Matthew Allum / mallum@o-hand.com
12
13 Thanks to:
14 Liam R. E. Quin
15 William Skaggs
16 Jakub Steiner
17
18 Structure
19 ---------
20
21 The stylesheet is divided into the following sections:
22
23 Positioning
24 Margins, paddings, width, font-size, clearing.
25 Decorations
26 Borders, style
27 Colors
28 Colors
29 Graphics
30 Graphical backgrounds
31 Nasty IE tweaks
32 Workarounds needed to make it work in internet explorer,
33 currently makes the stylesheet non validating, but up until
34 this point it is validating.
35 Mozilla extensions
36 Transparency for footer
37 Rounded corners on boxes
38
39*/
40
41
42 /*************** /
43 / Positioning /
44/ ***************/
45
46body {
47 font-family: Verdana, Sans, sans-serif;
48
49 min-width: 640px;
50 width: 80%;
51 margin: 0em auto;
52 padding: 2em 5em 5em 5em;
53 color: #333;
54}
55
56h1,h2,h3,h4,h5,h6,h7 {
57 font-family: Arial, Sans;
58 color: #00557D;
59 clear: both;
60}
61
62h1 {
63 font-size: 2em;
64 text-align: left;
65 padding: 0em 0em 0em 0em;
66 margin: 2em 0em 0em 0em;
67}
68
69h2.subtitle {
70 margin: 0.10em 0em 3.0em 0em;
71 padding: 0em 0em 0em 0em;
72 font-size: 1.8em;
73 padding-left: 20%;
74 font-weight: normal;
75 font-style: italic;
76}
77
78h2 {
79 margin: 2em 0em 0.66em 0em;
80 padding: 0.5em 0em 0em 0em;
81 font-size: 1.5em;
82 font-weight: bold;
83}
84
85h3.subtitle {
86 margin: 0em 0em 1em 0em;
87 padding: 0em 0em 0em 0em;
88 font-size: 142.14%;
89 text-align: right;
90}
91
92h3 {
93 margin: 1em 0em 0.5em 0em;
94 padding: 1em 0em 0em 0em;
95 font-size: 140%;
96 font-weight: bold;
97}
98
99h4 {
100 margin: 1em 0em 0.5em 0em;
101 padding: 1em 0em 0em 0em;
102 font-size: 120%;
103 font-weight: bold;
104}
105
106h5 {
107 margin: 1em 0em 0.5em 0em;
108 padding: 1em 0em 0em 0em;
109 font-size: 110%;
110 font-weight: bold;
111}
112
113h6 {
114 margin: 1em 0em 0em 0em;
115 padding: 1em 0em 0em 0em;
116 font-size: 110%;
117 font-weight: bold;
118}
119
120.authorgroup {
121 background-color: transparent;
122 background-repeat: no-repeat;
123 padding-top: 256px;
124 background-image: url("figures/kernel-dev-title.png");
125 background-position: left top;
126 margin-top: -256px;
127 padding-right: 50px;
128 margin-left: 0px;
129 text-align: right;
130 width: 740px;
131}
132
133h3.author {
134 margin: 0em 0me 0em 0em;
135 padding: 0em 0em 0em 0em;
136 font-weight: normal;
137 font-size: 100%;
138 color: #333;
139 clear: both;
140}
141
142.author tt.email {
143 font-size: 66%;
144}
145
146.titlepage hr {
147 width: 0em;
148 clear: both;
149}
150
151.revhistory {
152 padding-top: 2em;
153 clear: both;
154}
155
156.toc,
157.list-of-tables,
158.list-of-examples,
159.list-of-figures {
160 padding: 1.33em 0em 2.5em 0em;
161 color: #00557D;
162}
163
164.toc p,
165.list-of-tables p,
166.list-of-figures p,
167.list-of-examples p {
168 padding: 0em 0em 0em 0em;
169 padding: 0em 0em 0.3em;
170 margin: 1.5em 0em 0em 0em;
171}
172
173.toc p b,
174.list-of-tables p b,
175.list-of-figures p b,
176.list-of-examples p b{
177 font-size: 100.0%;
178 font-weight: bold;
179}
180
181.toc dl,
182.list-of-tables dl,
183.list-of-figures dl,
184.list-of-examples dl {
185 margin: 0em 0em 0.5em 0em;
186 padding: 0em 0em 0em 0em;
187}
188
189.toc dt {
190 margin: 0em 0em 0em 0em;
191 padding: 0em 0em 0em 0em;
192}
193
194.toc dd {
195 margin: 0em 0em 0em 2.6em;
196 padding: 0em 0em 0em 0em;
197}
198
199div.glossary dl,
200div.variablelist dl {
201}
202
203.glossary dl dt,
204.variablelist dl dt,
205.variablelist dl dt span.term {
206 font-weight: normal;
207 width: 20em;
208 text-align: right;
209}
210
211.variablelist dl dt {
212 margin-top: 0.5em;
213}
214
215.glossary dl dd,
216.variablelist dl dd {
217 margin-top: -1em;
218 margin-left: 25.5em;
219}
220
221.glossary dd p,
222.variablelist dd p {
223 margin-top: 0em;
224 margin-bottom: 1em;
225}
226
227
228div.calloutlist table td {
229 padding: 0em 0em 0em 0em;
230 margin: 0em 0em 0em 0em;
231}
232
233div.calloutlist table td p {
234 margin-top: 0em;
235 margin-bottom: 1em;
236}
237
238div p.copyright {
239 text-align: left;
240}
241
242div.legalnotice p.legalnotice-title {
243 margin-bottom: 0em;
244}
245
246p {
247 line-height: 1.5em;
248 margin-top: 0em;
249
250}
251
252dl {
253 padding-top: 0em;
254}
255
256hr {
257 border: solid 1px;
258}
259
260
261.mediaobject,
262.mediaobjectco {
263 text-align: center;
264}
265
266img {
267 border: none;
268}
269
270ul {
271 padding: 0em 0em 0em 1.5em;
272}
273
274ul li {
275 padding: 0em 0em 0em 0em;
276}
277
278ul li p {
279 text-align: left;
280}
281
282table {
283 width :100%;
284}
285
286th {
287 padding: 0.25em;
288 text-align: left;
289 font-weight: normal;
290 vertical-align: top;
291}
292
293td {
294 padding: 0.25em;
295 vertical-align: top;
296}
297
298p a[id] {
299 margin: 0px;
300 padding: 0px;
301 display: inline;
302 background-image: none;
303}
304
305a {
306 text-decoration: underline;
307 color: #444;
308}
309
310pre {
311 overflow: auto;
312}
313
314a:hover {
315 text-decoration: underline;
316 /*font-weight: bold;*/
317}
318
319/* This style defines how the permalink character
320 appears by itself and when hovered over with
321 the mouse. */
322
323[alt='Permalink'] { color: #eee; }
324[alt='Permalink']:hover { color: black; }
325
326
327div.informalfigure,
328div.informalexample,
329div.informaltable,
330div.figure,
331div.table,
332div.example {
333 margin: 1em 0em;
334 padding: 1em;
335 page-break-inside: avoid;
336}
337
338
339div.informalfigure p.title b,
340div.informalexample p.title b,
341div.informaltable p.title b,
342div.figure p.title b,
343div.example p.title b,
344div.table p.title b{
345 padding-top: 0em;
346 margin-top: 0em;
347 font-size: 100%;
348 font-weight: normal;
349}
350
351.mediaobject .caption,
352.mediaobject .caption p {
353 text-align: center;
354 font-size: 80%;
355 padding-top: 0.5em;
356 padding-bottom: 0.5em;
357}
358
359.epigraph {
360 padding-left: 55%;
361 margin-bottom: 1em;
362}
363
364.epigraph p {
365 text-align: left;
366}
367
368.epigraph .quote {
369 font-style: italic;
370}
371.epigraph .attribution {
372 font-style: normal;
373 text-align: right;
374}
375
376span.application {
377 font-style: italic;
378}
379
380.programlisting {
381 font-family: monospace;
382 font-size: 80%;
383 white-space: pre;
384 margin: 1.33em 0em;
385 padding: 1.33em;
386}
387
388.tip,
389.warning,
390.caution,
391.note {
392 margin-top: 1em;
393 margin-bottom: 1em;
394
395}
396
397/* force full width of table within div */
398.tip table,
399.warning table,
400.caution table,
401.note table {
402 border: none;
403 width: 100%;
404}
405
406
407.tip table th,
408.warning table th,
409.caution table th,
410.note table th {
411 padding: 0.8em 0.0em 0.0em 0.0em;
412 margin : 0em 0em 0em 0em;
413}
414
415.tip p,
416.warning p,
417.caution p,
418.note p {
419 margin-top: 0.5em;
420 margin-bottom: 0.5em;
421 padding-right: 1em;
422 text-align: left;
423}
424
425.acronym {
426 text-transform: uppercase;
427}
428
429b.keycap,
430.keycap {
431 padding: 0.09em 0.3em;
432 margin: 0em;
433}
434
435.itemizedlist li {
436 clear: none;
437}
438
439.filename {
440 font-size: medium;
441 font-family: Courier, monospace;
442}
443
444
445div.navheader, div.heading{
446 position: absolute;
447 left: 0em;
448 top: 0em;
449 width: 100%;
450 background-color: #cdf;
451 width: 100%;
452}
453
454div.navfooter, div.footing{
455 position: fixed;
456 left: 0em;
457 bottom: 0em;
458 background-color: #eee;
459 width: 100%;
460}
461
462
463div.navheader td,
464div.navfooter td {
465 font-size: 66%;
466}
467
468div.navheader table th {
469 /*font-family: Georgia, Times, serif;*/
470 /*font-size: x-large;*/
471 font-size: 80%;
472}
473
474div.navheader table {
475 border-left: 0em;
476 border-right: 0em;
477 border-top: 0em;
478 width: 100%;
479}
480
481div.navfooter table {
482 border-left: 0em;
483 border-right: 0em;
484 border-bottom: 0em;
485 width: 100%;
486}
487
488div.navheader table td a,
489div.navfooter table td a {
490 color: #777;
491 text-decoration: none;
492}
493
494/* normal text in the footer */
495div.navfooter table td {
496 color: black;
497}
498
499div.navheader table td a:visited,
500div.navfooter table td a:visited {
501 color: #444;
502}
503
504
505/* links in header and footer */
506div.navheader table td a:hover,
507div.navfooter table td a:hover {
508 text-decoration: underline;
509 background-color: transparent;
510 color: #33a;
511}
512
513div.navheader hr,
514div.navfooter hr {
515 display: none;
516}
517
518
519.qandaset tr.question td p {
520 margin: 0em 0em 1em 0em;
521 padding: 0em 0em 0em 0em;
522}
523
524.qandaset tr.answer td p {
525 margin: 0em 0em 1em 0em;
526 padding: 0em 0em 0em 0em;
527}
528.answer td {
529 padding-bottom: 1.5em;
530}
531
532.emphasis {
533 font-weight: bold;
534}
535
536
537 /************* /
538 / decorations /
539/ *************/
540
541.titlepage {
542}
543
544.part .title {
545}
546
547.subtitle {
548 border: none;
549}
550
551/*
552h1 {
553 border: none;
554}
555
556h2 {
557 border-top: solid 0.2em;
558 border-bottom: solid 0.06em;
559}
560
561h3 {
562 border-top: 0em;
563 border-bottom: solid 0.06em;
564}
565
566h4 {
567 border: 0em;
568 border-bottom: solid 0.06em;
569}
570
571h5 {
572 border: 0em;
573}
574*/
575
576.programlisting {
577 border: solid 1px;
578}
579
580div.figure,
581div.table,
582div.informalfigure,
583div.informaltable,
584div.informalexample,
585div.example {
586 border: 1px solid;
587}
588
589
590
591.tip,
592.warning,
593.caution,
594.note {
595 border: 1px solid;
596}
597
598.tip table th,
599.warning table th,
600.caution table th,
601.note table th {
602 border-bottom: 1px solid;
603}
604
605.question td {
606 border-top: 1px solid black;
607}
608
609.answer {
610}
611
612
613b.keycap,
614.keycap {
615 border: 1px solid;
616}
617
618
619div.navheader, div.heading{
620 border-bottom: 1px solid;
621}
622
623
624div.navfooter, div.footing{
625 border-top: 1px solid;
626}
627
628 /********* /
629 / colors /
630/ *********/
631
632body {
633 color: #333;
634 background: white;
635}
636
637a {
638 background: transparent;
639}
640
641a:hover {
642 background-color: #dedede;
643}
644
645
646h1,
647h2,
648h3,
649h4,
650h5,
651h6,
652h7,
653h8 {
654 background-color: transparent;
655}
656
657hr {
658 border-color: #aaa;
659}
660
661
662.tip, .warning, .caution, .note {
663 border-color: #fff;
664}
665
666
667.tip table th,
668.warning table th,
669.caution table th,
670.note table th {
671 border-bottom-color: #fff;
672}
673
674
675.warning {
676 background-color: #f0f0f2;
677}
678
679.caution {
680 background-color: #f0f0f2;
681}
682
683.tip {
684 background-color: #f0f0f2;
685}
686
687.note {
688 background-color: #f0f0f2;
689}
690
691.glossary dl dt,
692.variablelist dl dt,
693.variablelist dl dt span.term {
694 color: #044;
695}
696
697div.figure,
698div.table,
699div.example,
700div.informalfigure,
701div.informaltable,
702div.informalexample {
703 border-color: #aaa;
704}
705
706pre.programlisting {
707 color: black;
708 background-color: #fff;
709 border-color: #aaa;
710 border-width: 2px;
711}
712
713.guimenu,
714.guilabel,
715.guimenuitem {
716 background-color: #eee;
717}
718
719
720b.keycap,
721.keycap {
722 background-color: #eee;
723 border-color: #999;
724}
725
726
727div.navheader {
728 border-color: black;
729}
730
731
732div.navfooter {
733 border-color: black;
734}
735
736.writernotes {
737 color: red;
738}
739
740
741 /*********** /
742 / graphics /
743/ ***********/
744
745/*
746body {
747 background-image: url("images/body_bg.jpg");
748 background-attachment: fixed;
749}
750
751.navheader,
752.note,
753.tip {
754 background-image: url("images/note_bg.jpg");
755 background-attachment: fixed;
756}
757
758.warning,
759.caution {
760 background-image: url("images/warning_bg.jpg");
761 background-attachment: fixed;
762}
763
764.figure,
765.informalfigure,
766.example,
767.informalexample,
768.table,
769.informaltable {
770 background-image: url("images/figure_bg.jpg");
771 background-attachment: fixed;
772}
773
774*/
775h1,
776h2,
777h3,
778h4,
779h5,
780h6,
781h7{
782}
783
784/*
785Example of how to stick an image as part of the title.
786
787div.article .titlepage .title
788{
789 background-image: url("figures/white-on-black.png");
790 background-position: center;
791 background-repeat: repeat-x;
792}
793*/
794
795div.preface .titlepage .title,
796div.colophon .title,
797div.chapter .titlepage .title,
798div.article .titlepage .title
799{
800}
801
802div.section div.section .titlepage .title,
803div.sect2 .titlepage .title {
804 background: none;
805}
806
807
808h1.title {
809 background-color: transparent;
810 background-repeat: no-repeat;
811 height: 256px;
812 text-indent: -9000px;
813 overflow:hidden;
814}
815
816h2.subtitle {
817 background-color: transparent;
818 text-indent: -9000px;
819 overflow:hidden;
820 width: 0px;
821 display: none;
822}
823
824 /*************************************** /
825 / pippin.gimp.org specific alterations /
826/ ***************************************/
827
828/*
829div.heading, div.navheader {
830 color: #777;
831 font-size: 80%;
832 padding: 0;
833 margin: 0;
834 text-align: left;
835 position: absolute;
836 top: 0px;
837 left: 0px;
838 width: 100%;
839 height: 50px;
840 background: url('/gfx/heading_bg.png') transparent;
841 background-repeat: repeat-x;
842 background-attachment: fixed;
843 border: none;
844}
845
846div.heading a {
847 color: #444;
848}
849
850div.footing, div.navfooter {
851 border: none;
852 color: #ddd;
853 font-size: 80%;
854 text-align:right;
855
856 width: 100%;
857 padding-top: 10px;
858 position: absolute;
859 bottom: 0px;
860 left: 0px;
861
862 background: url('/gfx/footing_bg.png') transparent;
863}
864*/
865
866
867
868 /****************** /
869 / nasty ie tweaks /
870/ ******************/
871
872/*
873div.heading, div.navheader {
874 width:expression(document.body.clientWidth + "px");
875}
876
877div.footing, div.navfooter {
878 width:expression(document.body.clientWidth + "px");
879 margin-left:expression("-5em");
880}
881body {
882 padding:expression("4em 5em 0em 5em");
883}
884*/
885
886 /**************************************** /
887 / mozilla vendor specific css extensions /
888/ ****************************************/
889/*
890div.navfooter, div.footing{
891 -moz-opacity: 0.8em;
892}
893
894div.figure,
895div.table,
896div.informalfigure,
897div.informaltable,
898div.informalexample,
899div.example,
900.tip,
901.warning,
902.caution,
903.note {
904 -moz-border-radius: 0.5em;
905}
906
907b.keycap,
908.keycap {
909 -moz-border-radius: 0.3em;
910}
911*/
912
913table tr td table tr td {
914 display: none;
915}
916
917
918hr {
919 display: none;
920}
921
922table {
923 border: 0em;
924}
925
926 .photo {
927 float: right;
928 margin-left: 1.5em;
929 margin-bottom: 1.5em;
930 margin-top: 0em;
931 max-width: 17em;
932 border: 1px solid gray;
933 padding: 3px;
934 background: white;
935}
936 .seperator {
937 padding-top: 2em;
938 clear: both;
939 }
940
941 #validators {
942 margin-top: 5em;
943 text-align: right;
944 color: #777;
945 }
946 @media print {
947 body {
948 font-size: 8pt;
949 }
950 .noprint {
951 display: none;
952 }
953 }
954
955
956.tip,
957.note {
958 background: #f0f0f2;
959 color: #333;
960 padding: 20px;
961 margin: 20px;
962}
963
964.tip h3,
965.note h3 {
966 padding: 0em;
967 margin: 0em;
968 font-size: 2em;
969 font-weight: bold;
970 color: #333;
971}
972
973.tip a,
974.note a {
975 color: #333;
976 text-decoration: underline;
977}
978
979.footnote {
980 font-size: small;
981 color: #333;
982}
983
984/* Changes the announcement text */
985.tip h3,
986.warning h3,
987.caution h3,
988.note h3 {
989 font-size:large;
990 color: #00557D;
991}
diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml
deleted file mode 100755
index 887ff836f1..0000000000
--- a/documentation/kernel-dev/kernel-dev.xml
+++ /dev/null
@@ -1,187 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<book id='kernel-dev' lang='en'
7 xmlns:xi="http://www.w3.org/2003/XInclude"
8 xmlns="http://docbook.org/ns/docbook"
9 >
10 <bookinfo>
11
12 <mediaobject>
13 <imageobject>
14 <imagedata fileref='figures/kernel-dev-title.png'
15 format='SVG'
16 align='left' scalefit='1' width='100%'/>
17 </imageobject>
18 </mediaobject>
19
20 <title>
21 Yocto Project Linux Kernel Development Manual
22 </title>
23
24 <authorgroup>
25 <author>
26 <affiliation>
27 <orgname>&ORGNAME;</orgname>
28 </affiliation>
29 <email>&ORGEMAIL;</email>
30 </author>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>1.4</revnumber>
36 <date>April 2013</date>
37 <revremark>The initial document 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.6</revnumber>
46 <date>April 2014</date>
47 <revremark>Released with the Yocto Project 1.6 Release.</revremark>
48 </revision>
49 <revision>
50 <revnumber>1.7</revnumber>
51 <date>October 2014</date>
52 <revremark>Released with the Yocto Project 1.7 Release.</revremark>
53 </revision>
54 <revision>
55 <revnumber>1.8</revnumber>
56 <date>April 2015</date>
57 <revremark>Released with the Yocto Project 1.8 Release.</revremark>
58 </revision>
59 <revision>
60 <revnumber>2.0</revnumber>
61 <date>October 2015</date>
62 <revremark>Released with the Yocto Project 2.0 Release.</revremark>
63 </revision>
64 <revision>
65 <revnumber>2.1</revnumber>
66 <date>April 2016</date>
67 <revremark>Released with the Yocto Project 2.1 Release.</revremark>
68 </revision>
69 <revision>
70 <revnumber>2.2</revnumber>
71 <date>October 2016</date>
72 <revremark>Released with the Yocto Project 2.2 Release.</revremark>
73 </revision>
74 <revision>
75 <revnumber>2.3</revnumber>
76 <date>May 2017</date>
77 <revremark>Released with the Yocto Project 2.3 Release.</revremark>
78 </revision>
79 <revision>
80 <revnumber>2.4</revnumber>
81 <date>October 2017</date>
82 <revremark>Released with the Yocto Project 2.4 Release.</revremark>
83 </revision>
84 <revision>
85 <revnumber>2.5</revnumber>
86 <date>May 2018</date>
87 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
88 </revision>
89 <revision>
90 <revnumber>2.6</revnumber>
91 <date>November 2018</date>
92 <revremark>Released with the Yocto Project 2.6 Release.</revremark>
93 </revision>
94 <revision>
95 <revnumber>2.7</revnumber>
96 <date>May 2019</date>
97 <revremark>Released with the Yocto Project 2.7 Release.</revremark>
98 </revision>
99 <revision>
100 <revnumber>3.0</revnumber>
101 <date>October 2019</date>
102 <revremark>Released with the Yocto Project 3.0 Release.</revremark>
103 </revision>
104 <revision>
105 <revnumber>3.1</revnumber>
106 <date>&REL_MONTH_YEAR;</date>
107 <revremark>Released with the Yocto Project 3.1 Release.</revremark>
108 </revision>
109 </revhistory>
110
111 <copyright>
112 <year>&COPYRIGHT_YEAR;</year>
113 <holder>Linux Foundation</holder>
114 </copyright>
115
116 <legalnotice>
117 <para>
118 Permission is granted to copy, distribute and/or modify this document under
119 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.
120 </para>
121 <note><title>Manual Notes</title>
122 <itemizedlist>
123 <listitem><para>
124 This version of the
125 <emphasis>Yocto Project Linux Kernel Development Manual</emphasis>
126 is for the &YOCTO_DOC_VERSION; release of the
127 Yocto Project.
128 To be sure you have the latest version of the manual
129 for this release, go to the
130 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
131 and select the manual from that site.
132 Manuals from the site are more up-to-date than manuals
133 derived from the Yocto Project released TAR files.
134 </para></listitem>
135 <listitem><para>
136 If you located this manual through a web search, the
137 version of the manual might not be the one you want
138 (e.g. the search might have returned a manual much
139 older than the Yocto Project version with which you
140 are working).
141 You can see all Yocto Project major releases by
142 visiting the
143 <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
144 page.
145 If you need a version of this manual for a different
146 Yocto Project release, visit the
147 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
148 and select the manual set by using the
149 "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
150 pull-down menus.
151 </para></listitem>
152 <listitem>
153 <para>
154 To report any inaccuracies or problems with this
155 (or any other Yocto Project) manual, send an email to
156 the Yocto Project documentation mailing list at
157 <filename>docs@lists.yoctoproject.org</filename> or
158 log into the freenode <filename>#yocto</filename> channel.
159 </para>
160 </listitem>
161 </itemizedlist>
162 </note>
163 </legalnotice>
164
165 </bookinfo>
166
167 <xi:include href="kernel-dev-intro.xml"/>
168
169 <xi:include href="kernel-dev-common.xml"/>
170
171 <xi:include href="kernel-dev-advanced.xml"/>
172
173 <xi:include href="kernel-dev-concepts-appx.xml"/>
174
175 <xi:include href="kernel-dev-maint-appx.xml"/>
176
177 <xi:include href="kernel-dev-faq.xml"/>
178
179<!-- <index id='index'>
180 <title>Index</title>
181 </index>
182-->
183
184</book>
185<!--
186vim: expandtab tw=80 ts=4
187-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-17 00:24:25 +0000