summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-advanced.xml
diff options
context:
space:
mode:
authorTudor Florea <tudor.florea@enea.com>2015-10-09 20:59:03 (GMT)
committerTudor Florea <tudor.florea@enea.com>2015-10-09 20:59:03 (GMT)
commit972dcfcdbfe75dcfeb777150c136576cf1a71e99 (patch)
tree97a61cd7e293d7ae9d56ef7ed0f81253365bb026 /documentation/kernel-dev/kernel-dev-advanced.xml
downloadpoky-972dcfcdbfe75dcfeb777150c136576cf1a71e99.tar.gz
initial commit for Enea Linux 5.0 arm
Signed-off-by: Tudor Florea <tudor.florea@enea.com>
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml1074
1 files changed, 1074 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
new file mode 100644
index 0000000..283f483
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -0,0 +1,1074 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='kernel-dev-advanced'>
6<title>Working with Advanced Metadata</title>
7
8<section id='kernel-dev-advanced-overview'>
9 <title>Overview</title>
10
11 <para>
12 In addition to supporting configuration fragments and patches, the
13 Yocto Project kernel tools also support rich
14 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> that you can
15 use to define complex policies and Board Support Package (BSP) support.
16 The purpose of the Metadata and the tools that manage it, known as
17 the kern-tools (<filename>kern-tools-native_git.bb</filename>), is
18 to help you manage the complexity of the configuration and sources
19 used to support multiple BSPs and Linux kernel types.
20 </para>
21</section>
22
23<section id='using-kernel-metadata-in-a-recipe'>
24 <title>Using Kernel Metadata in a Recipe</title>
25
26 <para>
27 The kernel sources in the Yocto Project contain kernel Metadata, which is
28 located in the <filename>meta</filename> branches of the kernel source
29 Git repositories.
30 This Metadata defines Board Support Packages (BSPs) that
31 correspond to definitions in linux-yocto recipes for the same BSPs.
32 A BSP consists of an aggregation of kernel policy and hardware-specific
33 feature enablements.
34 The BSP can be influenced from within the linux-yocto recipe.
35 <note>
36 Linux kernel source that contains kernel Metadata is said to be
37 "linux-yocto style" kernel source.
38 A Linux kernel recipe that inherits from the
39 <filename>linux-yocto.inc</filename> include file is said to be a
40 "linux-yocto style" recipe.
41 </note>
42 </para>
43
44 <para>
45 Every linux-yocto style recipe must define the
46 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
47 variable.
48 This variable is typically set to the same value as the
49 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
50 variable, which is used by
51 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
52 (e.g. "edgerouter" or "fri2").
53 Multiple BSPs can reuse the same <filename>KMACHINE</filename>
54 name if they are built using the same BSP description.
55 The "fri2" and "fri2-noemgd" BSP combination
56 in the <filename>meta-intel</filename>
57 layer is a good example of two BSPs using the same
58 <filename>KMACHINE</filename> value (i.e. "fri2").
59 See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section
60 for more information.
61 </para>
62
63 <para>
64 The linux-yocto style recipes can optionally define the following
65 variables:
66 <literallayout class='monospaced'>
67 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'>KBRANCH</ulink>
68 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink>
69 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH_DEFAULT'>KBRANCH_DEFAULT</ulink>
70 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink>
71 </literallayout>
72 <filename>KBRANCH_DEFAULT</filename> defines the Linux kernel source
73 repository's default branch to use to build the Linux kernel.
74 The value is used as the default for <filename>KBRANCH</filename>, which
75 can define an alternate branch typically with a machine override as
76 follows:
77 <literallayout class='monospaced'>
78 KBRANCH_fri2 = "standard/fri2"
79 </literallayout>
80 Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename>
81 initializes to "master".
82 </para>
83
84 <para>
85 <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be
86 used in assembling the configuration.
87 If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
88 it defaults to "standard".
89 Together with
90 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
91 <filename>LINUX_KERNEL_TYPE</filename> defines the search
92 arguments used by the kernel tools to find the
93 appropriate description within the kernel Metadata with which to
94 build out the sources and configuration.
95 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
96 kernel types.
97 See the <link linkend='kernel-types'>Kernel Types</link> section
98 for more information on kernel types.
99 </para>
100
101 <para>
102 During the build, the kern-tools search for the BSP description
103 file that most closely matches the <filename>KMACHINE</filename>
104 and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the
105 recipe.
106 The tools use the first BSP description it finds that match
107 both variables.
108 If the tools cannot find a match, they issue a warning such as
109 the following:
110 <literallayout class='monospaced'>
111 WARNING: Can't find any BSP hardware or required configuration fragments.
112 WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and
113 meta/cfg/broken/fri2-broken/required_frags.txt in directory:
114 meta/cfg/broken/fri2-broken
115 </literallayout>
116 In this example, <filename>KMACHINE</filename> was set to "fri2-broken"
117 and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken".
118 </para>
119
120 <para>
121 The tools first search for the <filename>KMACHINE</filename> and
122 then for the <filename>LINUX_KERNEL_TYPE</filename>.
123 If the tools cannot find a partial match, they will use the
124 sources from the <filename>KBRANCH</filename> and any configuration
125 specified in the
126 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
127 </para>
128
129 <para>
130 You can use the <filename>KERNEL_FEATURES</filename> variable
131 to include features (configuration fragments, patches, or both) that
132 are not already included by the <filename>KMACHINE</filename> and
133 <filename>LINUX_KERNEL_TYPE</filename> variable combination.
134 For example, to include a feature specified as "features/netfilter.scc",
135 specify:
136 <literallayout class='monospaced'>
137 KERNEL_FEATURES += "features/netfilter.scc"
138 </literallayout>
139 To include a feature called "cfg/sound.scc" just for the
140 <filename>qemux86</filename> machine, specify:
141 <literallayout class='monospaced'>
142 KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"
143 </literallayout>
144 The value of the entries in <filename>KERNEL_FEATURES</filename>
145 are dependent on their location within the kernel Metadata itself.
146 The examples here are taken from the
147 <filename>linux-yocto-3.4</filename> repository where "features"
148 and "cfg" are subdirectories within the
149 <filename>meta/cfg/kernel-cache</filename> directory.
150 For more information, see the
151 "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section.
152 <note>
153 The processing of the these variables has evolved some between the
154 0.9 and 1.3 releases of the Yocto Project and associated
155 kern-tools sources.
156 The descriptions in this section are accurate for 1.3 and later
157 releases of the Yocto Project.
158 </note>
159 </para>
160</section>
161
162<section id='kernel-metadata-location'>
163 <title>Kernel Metadata Location</title>
164
165 <para>
166 Kernel Metadata can be defined in either the kernel recipe
167 (recipe-space) or in the kernel tree (in-tree).
168 Where you choose to define the Metadata depends on what you want
169 to do and how you intend to work.
170 Regardless of where you define the kernel Metadata, the syntax used
171 applies equally.
172 </para>
173
174 <para>
175 If you are unfamiliar with the Linux kernel and only wish
176 to apply a configuration and possibly a couple of patches provided to
177 you by others, the recipe-space method is recommended.
178 This method is also a good approach if you are working with Linux kernel
179 sources you do not control or if you just do not want to maintain a
180 Linux kernel Git repository on your own.
181 For partial information on how you can define kernel Metadata in
182 the recipe-space, see the
183 "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
184 section.
185 </para>
186
187 <para>
188 Conversely, if you are actively developing a kernel and are already
189 maintaining a Linux kernel Git repository of your own, you might find
190 it more convenient to work with the kernel Metadata in the same
191 repository as the Linux kernel sources.
192 This method can make iterative development of the Linux kernel
193 more efficient outside of the BitBake environment.
194 </para>
195
196 <section id='recipe-space-metadata'>
197 <title>Recipe-Space Metadata</title>
198
199 <para>
200 When stored in recipe-space, the kernel Metadata files reside in a
201 directory hierarchy below
202 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
203 For a linux-yocto recipe or for a Linux kernel recipe derived
204 by copying and modifying
205 <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
206 to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
207 is typically set to
208 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>.
209 See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
210 section for more information.
211 </para>
212
213 <para>
214 Here is an example that shows a trivial tree of kernel Metadata
215 stored in recipe-space within a BSP layer:
216 <literallayout class='monospaced'>
217 meta-<replaceable>my_bsp_layer</replaceable>/
218 `-- recipes-kernel
219 `-- linux
220 `-- linux-yocto
221 |-- bsp-standard.scc
222 |-- bsp.cfg
223 `-- standard.cfg
224 </literallayout>
225 </para>
226
227 <para>
228 When the Metadata is stored in recipe-space, you must take
229 steps to ensure BitBake has the necessary information to decide
230 what files to fetch and when they need to be fetched again.
231 It is only necessary to specify the <filename>.scc</filename>
232 files on the
233 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
234 BitBake parses them and fetches any files referenced in the
235 <filename>.scc</filename> files by the <filename>include</filename>,
236 <filename>patch</filename>, or <filename>kconf</filename> commands.
237 Because of this, it is necessary to bump the recipe
238 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
239 value when changing the content of files not explicitly listed
240 in the <filename>SRC_URI</filename>.
241 </para>
242 </section>
243
244 <section id='in-tree-metadata'>
245 <title>In-Tree Metadata</title>
246
247 <para>
248 When stored in-tree, the kernel Metadata files reside in the
249 <filename>meta</filename> directory of the Linux kernel sources.
250 The <filename>meta</filename> directory can be present in the
251 same repository branch as the sources,
252 such as "master", or <filename>meta</filename> can be its own
253 orphan branch.
254 <note>
255 An orphan branch in Git is a branch with unique history and
256 content to the other branches in the repository.
257 Orphan branches are useful to track Metadata changes
258 independently from the sources of the Linux kernel, while
259 still keeping them together in the same repository.
260 </note>
261 For the purposes of this document, we will discuss all
262 in-tree Metadata as residing below the
263 <filename>meta/cfg/kernel-cache</filename> directory.
264 </para>
265
266 <para>
267 Following is an example that shows how a trivial tree of Metadata
268 is stored in a custom Linux kernel Git repository:
269 <literallayout class='monospaced'>
270 meta/
271 `-- cfg
272 `-- kernel-cache
273 |-- bsp-standard.scc
274 |-- bsp.cfg
275 `-- standard.cfg
276 </literallayout>
277 </para>
278
279 <para>
280 To use a branch different from where the sources reside,
281 specify the branch in the <filename>KMETA</filename> variable
282 in your Linux kernel recipe.
283 Here is an example:
284 <literallayout class='monospaced'>
285 KMETA = "meta"
286 </literallayout>
287 To use the same branch as the sources, set
288 <filename>KMETA</filename> to an empty string:
289 <literallayout class='monospaced'>
290 KMETA = ""
291 </literallayout>
292 If you are working with your own sources and want to create an
293 orphan <filename>meta</filename> branch, use these commands
294 from within your Linux kernel Git repository:
295 <literallayout class='monospaced'>
296 $ git checkout --orphan meta
297 $ git rm -rf .
298 $ git commit --allow-empty -m "Create orphan meta branch"
299 </literallayout>
300 </para>
301
302 <para>
303 If you modify the Metadata in the linux-yocto
304 <filename>meta</filename> branch, you must not forget to update
305 the
306 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
307 statements in the kernel's recipe.
308 In particular, you need to update the
309 <filename>SRCREV_meta</filename> variable to match the commit in
310 the <filename>KMETA</filename> branch you wish to use.
311 Changing the data in these branches and not updating the
312 <filename>SRCREV</filename> statements to match will cause the
313 build to fetch an older commit.
314 </para>
315 </section>
316</section>
317
318<section id='kernel-metadata-syntax'>
319 <title>Kernel Metadata Syntax</title>
320
321 <para>
322 The kernel Metadata consists of three primary types of files:
323 <filename>scc</filename>
324 <footnote>
325 <para>
326 <filename>scc</filename> stands for Series Configuration
327 Control, but the naming has less significance in the
328 current implementation of the tooling than it had in the
329 past.
330 Consider <filename>scc</filename> files to be description files.
331 </para>
332 </footnote>
333 description files, configuration fragments, and patches.
334 The <filename>scc</filename> files define variables and include or
335 otherwise reference any of the three file types.
336 The description files are used to aggregate all types of kernel
337 Metadata into
338 what ultimately describes the sources and the configuration required
339 to build a Linux kernel tailored to a specific machine.
340 </para>
341
342 <para>
343 The <filename>scc</filename> description files are used to define two
344 fundamental types of kernel Metadata:
345 <itemizedlist>
346 <listitem><para>Features</para></listitem>
347 <listitem><para>Board Support Packages (BSPs)</para></listitem>
348 </itemizedlist>
349 </para>
350
351 <para>
352 Features aggregate sources in the form of patches and configuration
353 fragments into a modular reusable unit.
354 You can use features to implement conceptually separate kernel
355 Metadata descriptions such as pure configuration fragments,
356 simple patches, complex features, and kernel types.
357 <link linkend='kernel-types'>Kernel types</link> define general
358 kernel features and policy to be reused in the BSPs.
359 </para>
360
361 <para>
362 BSPs define hardware-specific features and aggregate them with kernel
363 types to form the final description of what will be assembled and built.
364 </para>
365
366 <para>
367 While the kernel Metadata syntax does not enforce any logical
368 separation of configuration fragments, patches, features or kernel
369 types, best practices dictate a logical separation of these types
370 of Metadata.
371 The following Metadata file hierarchy is recommended:
372 <literallayout class='monospaced'>
373 <replaceable>base</replaceable>/
374 bsp/
375 cfg/
376 features/
377 ktypes/
378 patches/
379 </literallayout>
380 </para>
381
382 <para>
383 The <filename>bsp</filename> directory contains the
384 <link linkend='bsp-descriptions'>BSP descriptions</link>.
385 The remaining directories all contain "features".
386 Separating <filename>bsp</filename> from the rest of the structure
387 aids conceptualizing intended usage.
388 </para>
389
390 <para>
391 Use these guidelines to help place your <filename>scc</filename>
392 description files within the structure:
393 <itemizedlist>
394 <listitem><para>If your file contains
395 only configuration fragments, place the file in the
396 <filename>cfg</filename> directory.</para></listitem>
397 <listitem><para>If your file contains
398 only source-code fixes, place the file in the
399 <filename>patches</filename> directory.</para></listitem>
400 <listitem><para>If your file encapsulates
401 a major feature, often combining sources and configurations,
402 place the file in <filename>features</filename> directory.
403 </para></listitem>
404 <listitem><para>If your file aggregates
405 non-hardware configuration and patches in order to define a
406 base kernel policy or major kernel type to be reused across
407 multiple BSPs, place the file in <filename>ktypes</filename>
408 directory.
409 </para></listitem>
410 </itemizedlist>
411 </para>
412
413 <para>
414 These distinctions can easily become blurred - especially as
415 out-of-tree features slowly merge upstream over time.
416 Also, remember that how the description files are placed is
417 a purely logical organization and has no impact on the functionality
418 of the kernel Metadata.
419 There is no impact because all of <filename>cfg</filename>,
420 <filename>features</filename>, <filename>patches</filename>, and
421 <filename>ktypes</filename>, contain "features" as far as the kernel
422 tools are concerned.
423 </para>
424
425 <para>
426 Paths used in kernel Metadata files are relative to
427 <filename>&lt;base&gt;</filename>, which is either
428 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
429 if you are creating Metadata in
430 <link linkend='recipe-space-metadata'>recipe-space</link>,
431 or <filename>meta/cfg/kernel-cache/</filename> if you are creating
432 Metadata <link linkend='in-tree-metadata'>in-tree</link>.
433 </para>
434
435 <section id='configuration'>
436 <title>Configuration</title>
437
438 <para>
439 The simplest unit of kernel Metadata is the configuration-only
440 feature.
441 This feature consists of one or more Linux kernel configuration
442 parameters in a configuration fragment file
443 (<filename>.cfg</filename>) and an <filename>.scc</filename> file
444 that describes the fragment.
445 </para>
446
447 <para>
448 The Symmetric Multi-Processing (SMP) fragment included in the
449 <filename>linux-yocto-3.4</filename> Git repository
450 consists of the following two files:
451 <literallayout class='monospaced'>
452 cfg/smp.scc:
453 define KFEATURE_DESCRIPTION "Enable SMP"
454 kconf hardware smp.cfg
455
456 cfg/smp.cfg:
457 CONFIG_SMP=y
458 CONFIG_SCHED_SMT=y
459 </literallayout>
460 You can find information on configuration fragment files in the
461 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
462 section of the Yocto Project Development Manual and in
463 the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
464 section earlier in this manual.
465 </para>
466
467 <para>
468 <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>
469 provides a short description of the fragment.
470 Higher level kernel tools use this description.
471 </para>
472
473 <para>
474 The <filename>kconf</filename> command is used to include the
475 actual configuration fragment in an <filename>.scc</filename>
476 file, and the "hardware" keyword identifies the fragment as
477 being hardware enabling, as opposed to general policy,
478 which would use the "non-hardware" keyword.
479 The distinction is made for the benefit of the configuration
480 validation tools, which warn you if a hardware fragment
481 overrides a policy set by a non-hardware fragment.
482 <note>
483 The description file can include multiple
484 <filename>kconf</filename> statements, one per fragment.
485 </note>
486 </para>
487
488 <para>
489 As described in the
490 "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
491 section, you can use the following BitBake command to audit your
492 configuration:
493 <literallayout class='monospaced'>
494 $ bitbake linux-yocto -c kernel_configcheck -f
495 </literallayout>
496 </para>
497 </section>
498
499 <section id='patches'>
500 <title>Patches</title>
501
502 <para>
503 Patch descriptions are very similar to configuration fragment
504 descriptions, which are described in the previous section.
505 However, instead of a <filename>.cfg</filename> file, these
506 descriptions work with source patches.
507 </para>
508
509 <para>
510 A typical patch includes a description file and the patch itself:
511 <literallayout class='monospaced'>
512 patches/mypatch.scc:
513 patch mypatch.patch
514
515 patches/mypatch.patch:
516 <replaceable>typical-patch</replaceable>
517 </literallayout>
518 You can create the typical <filename>.patch</filename>
519 file using <filename>diff -Nurp</filename> or
520 <filename>git format-patch</filename>.
521 </para>
522
523 <para>
524 The description file can include multiple patch statements,
525 one per patch.
526 </para>
527 </section>
528
529 <section id='features'>
530 <title>Features</title>
531
532 <para>
533 Features are complex kernel Metadata types that consist
534 of configuration fragments (<filename>kconf</filename>), patches
535 (<filename>patch</filename>), and possibly other feature
536 description files (<filename>include</filename>).
537 </para>
538
539 <para>
540 Here is an example that shows a feature description file:
541 <literallayout class='monospaced'>
542 features/myfeature.scc
543 define KFEATURE_DESCRIPTION "Enable myfeature"
544
545 patch 0001-myfeature-core.patch
546 patch 0002-myfeature-interface.patch
547
548 include cfg/myfeature_dependency.scc
549 kconf non-hardware myfeature.cfg
550 </literallayout>
551 This example shows how the <filename>patch</filename> and
552 <filename>kconf</filename> commands are used as well as
553 how an additional feature description file is included.
554 </para>
555
556 <para>
557 Typically, features are less granular than configuration
558 fragments and are more likely than configuration fragments
559 and patches to be the types of things you want to specify
560 in the <filename>KERNEL_FEATURES</filename> variable of the
561 Linux kernel recipe.
562 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
563 section earlier in the manual.
564 </para>
565 </section>
566
567 <section id='kernel-types'>
568 <title>Kernel Types</title>
569
570 <para>
571 A kernel type defines a high-level kernel policy by
572 aggregating non-hardware configuration fragments with
573 patches you want to use when building a Linux kernels of a
574 specific type.
575 Syntactically, kernel types are no different than features
576 as described in the "<link linkend='features'>Features</link>"
577 section.
578 The <filename>LINUX_KERNEL_TYPE</filename> variable in the kernel
579 recipe selects the kernel type.
580 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
581 section for more information.
582 </para>
583
584 <para>
585 As an example, the <filename>linux-yocto-3.4</filename>
586 tree defines three kernel types: "standard",
587 "tiny", and "preempt-rt":
588 <itemizedlist>
589 <listitem><para>"standard":
590 Includes the generic Linux kernel policy of the Yocto
591 Project linux-yocto kernel recipes.
592 This policy includes, among other things, which file
593 systems, networking options, core kernel features, and
594 debugging and tracing options are supported.
595 </para></listitem>
596 <listitem><para>"preempt-rt":
597 Applies the <filename>PREEMPT_RT</filename>
598 patches and the configuration options required to
599 build a real-time Linux kernel.
600 This kernel type inherits from the "standard" kernel type.
601 </para></listitem>
602 <listitem><para>"tiny":
603 Defines a bare minimum configuration meant to serve as a
604 base for very small Linux kernels.
605 The "tiny" kernel type is independent from the "standard"
606 configuration.
607 Although the "tiny" kernel type does not currently include
608 any source changes, it might in the future.
609 </para></listitem>
610 </itemizedlist>
611 </para>
612
613 <para>
614 The "standard" kernel type is defined by
615 <filename>standard.scc</filename>:
616 <literallayout class='monospaced'>
617 # Include this kernel type fragment to get the standard features and
618 # configuration values.
619
620 # Include all standard features
621 include standard-nocfg.scc
622
623 kconf non-hardware standard.cfg
624
625 # individual cfg block section
626 include cfg/fs/devtmpfs.scc
627 include cfg/fs/debugfs.scc
628 include cfg/fs/btrfs.scc
629 include cfg/fs/ext2.scc
630 include cfg/fs/ext3.scc
631 include cfg/fs/ext4.scc
632
633 include cfg/net/ipv6.scc
634 include cfg/net/ip_nf.scc
635 include cfg/net/ip6_nf.scc
636 include cfg/net/bridge.scc
637 </literallayout>
638 </para>
639
640 <para>
641 As with any <filename>.scc</filename> file, a
642 kernel type definition can aggregate other
643 <filename>.scc</filename> files with
644 <filename>include</filename> commands.
645 These definitions can also directly pull in
646 configuration fragments and patches with the
647 <filename>kconf</filename> and <filename>patch</filename>
648 commands, respectively.
649 </para>
650
651 <note>
652 It is not strictly necessary to create a kernel type
653 <filename>.scc</filename> file.
654 The Board Support Package (BSP) file can implicitly define
655 the kernel type using a <filename>define
656 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename>
657 line.
658 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
659 section for more information.
660 </note>
661 </section>
662
663 <section id='bsp-descriptions'>
664 <title>BSP Descriptions</title>
665
666 <para>
667 BSP descriptions combine kernel types with hardware-specific
668 features.
669 The hardware-specific portion is typically defined
670 independently, and then aggregated with each supported kernel
671 type.
672 Consider this simple BSP description that supports the "mybsp"
673 machine:
674 <literallayout class='monospaced'>
675 mybsp.scc:
676 define KMACHINE mybsp
677 define KTYPE standard
678 define KARCH i386
679
680 kconf mybsp.cfg
681 </literallayout>
682 Every BSP description should define the
683 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
684 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
685 and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
686 variables.
687 These variables allow the OpenEmbedded build system to identify
688 the description as meeting the criteria set by the recipe being
689 built.
690 This simple example supports the "mybsp" machine for the "standard"
691 kernel and the "i386" architecture.
692 </para>
693
694 <para>
695 Be aware that a hard link between the
696 <filename>KTYPE</filename> variable and a kernel type
697 description file does not exist.
698 Thus, if you do not have kernel types defined in your kernel
699 Metadata, you only need to ensure that the kernel recipe's
700 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
701 variable and the <filename>KTYPE</filename> variable in the
702 BSP description file match.
703 <note>
704 Future versions of the tooling make the specification of
705 <filename>KTYPE</filename> in the BSP optional.
706 </note>
707 </para>
708
709 <para>
710 If you did want to separate your kernel policy from your
711 hardware configuration, you could do so by specifying a kernel
712 type, such as "standard" and including that description file
713 in the BSP description file.
714 See the "<link linkend='kernel-types'>Kernel Types</link>" section
715 for more information.
716 </para>
717
718 <para>
719 You might also have multiple hardware configurations that you
720 aggregate into a single hardware description file that you
721 could include in the BSP description file, rather than referencing
722 a single <filename>.cfg</filename> file.
723 Consider the following:
724 <literallayout class='monospaced'>
725 mybsp.scc:
726 define KMACHINE mybsp
727 define KTYPE standard
728 define KARCH i386
729
730 include standard.scc
731 include mybsp-hw.scc
732 </literallayout>
733 </para>
734
735 <para>
736 In the above example, <filename>standard.scc</filename>
737 aggregates all the configuration fragments, patches, and
738 features that make up your standard kernel policy whereas
739 <filename>mybsp-hw.scc</filename> aggregates all those necessary
740 to support the hardware available on the "mybsp" machine.
741 For information on how to break a complete
742 <filename>.config</filename> file into the various
743 configuration fragments, see the
744 "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
745 section.
746 </para>
747
748 <para>
749 Many real-world examples are more complex.
750 Like any other <filename>.scc</filename> file, BSP
751 descriptions can aggregate features.
752 Consider the Fish River Island 2 (fri2)
753 BSP definition from the <filename>linux-yocto-3.4</filename>
754 Git repository:
755 <literallayout class='monospaced'>
756 fri2.scc:
757 kconf hardware fri2.cfg
758
759 include cfg/x86.scc
760 include features/eg20t/eg20t.scc
761 include cfg/dmaengine.scc
762 include features/ericsson-3g/f5521gw.scc
763 include features/power/intel.scc
764 include cfg/efi.scc
765 include features/usb/ehci-hcd.scc
766 include features/usb/ohci-hcd.scc
767 include features/iwlwifi/iwlwifi.scc
768 </literallayout>
769 </para>
770
771 <para>
772 The <filename>fri2.scc</filename> description file includes
773 a hardware configuration fragment
774 (<filename>fri2.cfg</filename>) specific to the Fish River
775 Island 2 BSP as well as several more general configuration
776 fragments and features enabling hardware found on the
777 machine.
778 This description file is then included in each of the three
779 "fri2" description files for the supported kernel types
780 (i.e. "standard", "preempt-rt", and "tiny").
781 Consider the "fri2" description for the "standard" kernel
782 type:
783 <literallayout class='monospaced'>
784 fri2-standard.scc:
785 define KMACHINE fri2
786 define KTYPE standard
787 define KARCH i386
788
789 include ktypes/standard/standard.scc
790 branch fri2
791
792 git merge emgd-1.14
793
794 include fri2.scc
795
796 # Extra fri2 configs above the minimal defined in fri2.scc
797 include cfg/efi-ext.scc
798 include features/drm-emgd/drm-emgd.scc
799 include cfg/vesafb.scc
800
801 # default policy for standard kernels
802 include cfg/usb-mass-storage.scc
803 </literallayout>
804 The <filename>include</filename> command midway through the file
805 includes the <filename>fri2.scc</filename> description that
806 defines all hardware enablements for the BSP that is common to all
807 kernel types.
808 Using this command significantly reduces duplication.
809 </para>
810
811 <para>
812 This "fri2" standard description introduces a few more variables
813 and commands that are worth further discussion.
814 Notice the <filename>branch fri2</filename> command, which creates
815 a machine-specific branch into which source changes are applied.
816 With this branch set up, the <filename>git merge</filename> command
817 uses Git to merge in a feature branch named "emgd-1.14".
818 You could also handle this with the <filename>patch</filename>
819 command.
820 However, for commonly used features such as this, feature branches
821 are a convenient mechanism.
822 See the "<link linkend='feature-branches'>Feature Branches</link>"
823 section for more information.
824 </para>
825
826 <para>
827 Now consider the "fri2" description for the "tiny" kernel type:
828 <literallayout class='monospaced'>
829 fri2-tiny.scc:
830 define KMACHINE fri2
831 define KTYPE tiny
832 define KARCH i386
833
834 include ktypes/tiny/tiny.scc
835 branch fri2
836
837 include fri2.scc
838 </literallayout>
839 As you might expect, the "tiny" description includes quite a
840 bit less.
841 In fact, it includes only the minimal policy defined by the
842 "tiny" kernel type and the hardware-specific configuration required
843 for booting the machine along with the most basic functionality of
844 the system as defined in the base "fri2" description file.
845 </para>
846
847 <para>
848 Notice again the three critical variables:
849 <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
850 and <filename>KARCH</filename>.
851 Of these variables, only the <filename>KTYPE</filename> has changed.
852 It is now set to "tiny".
853 </para>
854 </section>
855</section>
856
857<section id='organizing-your-source'>
858 <title>Organizing Your Source</title>
859
860 <para>
861 Many recipes based on the <filename>linux-yocto-custom.bb</filename>
862 recipe use Linux kernel sources that have only a single
863 branch - "master".
864 This type of repository structure is fine for linear development
865 supporting a single machine and architecture.
866 However, if you work with multiple boards and architectures,
867 a kernel source repository with multiple branches is more
868 efficient.
869 For example, suppose you need a series of patches for one board to boot.
870 Sometimes, these patches are works-in-progress or fundamentally wrong,
871 yet they are still necessary for specific boards.
872 In these situations, you most likely do not want to include these
873 patches in every kernel you build (i.e. have the patches as part of
874 the lone "master" branch).
875 It is situations like these that give rise to multiple branches used
876 within a Linux kernel sources Git repository.
877 </para>
878
879 <para>
880 Repository organization strategies exist that maximize source reuse,
881 remove redundancy, and logically order your changes.
882 This section presents strategies for the following cases:
883 <itemizedlist>
884 <listitem><para>Encapsulating patches in a feature description
885 and only including the patches in the BSP descriptions of
886 the applicable boards.</para></listitem>
887 <listitem><para>Creating a machine branch in your
888 kernel source repository and applying the patches on that
889 branch only.</para></listitem>
890 <listitem><para>Creating a feature branch in your
891 kernel source repository and merging that branch into your
892 BSP when needed.</para></listitem>
893 </itemizedlist>
894 </para>
895
896 <para>
897 The approach you take is entirely up to you
898 and depends on what works best for your development model.
899 </para>
900
901 <section id='encapsulating-patches'>
902 <title>Encapsulating Patches</title>
903
904 <para>
905 if you are reusing patches from an external tree and are not
906 working on the patches, you might find the encapsulated feature
907 to be appropriate.
908 Given this scenario, you do not need to create any branches in the
909 source repository.
910 Rather, you just take the static patches you need and encapsulate
911 them within a feature description.
912 Once you have the feature description, you simply include that into
913 the BSP description as described in the
914 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
915 section.
916 </para>
917
918 <para>
919 You can find information on how to create patches and BSP
920 descriptions in the "<link linkend='patches'>Patches</link>" and
921 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
922 sections.
923 </para>
924 </section>
925
926 <section id='machine-branches'>
927 <title>Machine Branches</title>
928
929 <para>
930 When you have multiple machines and architectures to support,
931 or you are actively working on board support, it is more
932 efficient to create branches in the repository based on
933 individual machines.
934 Having machine branches allows common source to remain in the
935 "master" branch with any features specific to a machine stored
936 in the appropriate machine branch.
937 This organization method frees you from continually reintegrating
938 your patches into a feature.
939 </para>
940
941 <para>
942 Once you have a new branch, you can set up your kernel Metadata
943 to use the branch a couple different ways.
944 In the recipe, you can specify the new branch as the
945 <filename>KBRANCH</filename> to use for the board as
946 follows:
947 <literallayout class='monospaced'>
948 KBRANCH = "mynewbranch"
949 </literallayout>
950 Another method is to use the <filename>branch</filename> command
951 in the BSP description:
952 <literallayout class='monospaced'>
953 mybsp.scc:
954 define KMACHINE mybsp
955 define KTYPE standard
956 define KARCH i386
957 include standard.scc
958
959 branch mynewbranch
960
961 include mybsp-hw.scc
962 </literallayout>
963 </para>
964
965 <para>
966 If you find
967 yourself with numerous branches, you might consider using a
968 hierarchical branching system similar to what the linux-yocto Linux
969 kernel repositories use:
970 <literallayout class='monospaced'>
971 <replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable>
972 </literallayout>
973 </para>
974
975 <para>
976 If you had two kernel types, "standard" and "small" for
977 instance, three machines, and <replaceable>common</replaceable>
978 as <filename>mydir</filename>, the branches in your
979 Git repository might look like this:
980 <literallayout class='monospaced'>
981 mydir/base
982 mydir/standard/base
983 mydir/standard/machine_a
984 mydir/standard/machine_b
985 mydir/standard/machine_c
986 mydir/small/base
987 mydir/small/machine_a
988 </literallayout>
989 </para>
990
991 <para>
992 This organization can help clarify the branch relationships.
993 In this case, <filename>mydir/standard/machine_a</filename>
994 includes everything in <filename>mydir/base</filename> and
995 <filename>mydir/standard/base</filename>.
996 The "standard" and "small" branches add sources specific to those
997 kernel types that for whatever reason are not appropriate for the
998 other branches.
999 <note>The "base" branches are an artifact of the way Git manages
1000 its data internally on the filesystem: Git will not allow you
1001 to use <filename>mydir/standard</filename> and
1002 <filename>mydir/standard/machine_a</filename> because it
1003 would have to create a file and a directory named "standard".
1004 </note>
1005 </para>
1006 </section>
1007
1008 <section id='feature-branches'>
1009 <title>Feature Branches</title>
1010
1011 <para>
1012 When you are actively developing new features, it can be more
1013 efficient to work with that feature as a branch, rather than
1014 as a set of patches that have to be regularly updated.
1015 The Yocto Project Linux kernel tools provide for this with
1016 the <filename>git merge</filename> command.
1017 </para>
1018
1019 <para>
1020 To merge a feature branch into a BSP, insert the
1021 <filename>git merge</filename> command after any
1022 <filename>branch</filename> commands:
1023 <literallayout class='monospaced'>
1024 mybsp.scc:
1025 define KMACHINE mybsp
1026 define KTYPE standard
1027 define KARCH i386
1028 include standard.scc
1029
1030 branch mynewbranch
1031 git merge myfeature
1032
1033 include mybsp-hw.scc
1034 </literallayout>
1035 </para>
1036 </section>
1037</section>
1038
1039<section id='scc-reference'>
1040 <title>SCC Description File Reference</title>
1041
1042 <para>
1043 This section provides a brief reference for the commands you can use
1044 within an SCC description file (<filename>.scc</filename>):
1045 <itemizedlist>
1046 <listitem><para><filename>branch [ref]</filename>:
1047 Creates a new branch relative to the current branch
1048 (typically <filename>${KTYPE}</filename>) using
1049 the currently checked-out branch, or "ref" if specified.
1050 </para></listitem>
1051 <listitem><para><filename>define</filename>:
1052 Defines variables, such as <filename>KMACHINE</filename>,
1053 <filename>KTYPE</filename>, <filename>KARCH</filename>,
1054 and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
1055 <listitem><para><filename>include SCC_FILE</filename>:
1056 Includes an SCC file in the current file.
1057 The file is parsed as if you had inserted it inline.
1058 </para></listitem>
1059 <listitem><para><filename>kconf [hardware|non-hardware] CFG_FILE</filename>:
1060 Queues a configuration fragment for merging into the final
1061 Linux <filename>.config</filename> file.</para></listitem>
1062 <listitem><para><filename>git merge GIT_BRANCH</filename>:
1063 Merges the feature branch into the current branch.
1064 </para></listitem>
1065 <listitem><para><filename>patch PATCH_FILE</filename>:
1066 Applies the patch to the current Git branch.</para></listitem>
1067 </itemizedlist>
1068 </para>
1069</section>
1070
1071</chapter>
1072<!--
1073vim: expandtab tw=80 ts=4
1074-->