blob: eeb8f879247f6ff9d7e90d45323bc350013ab1e9 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3*******************************************************
4Working with Advanced Metadata (``yocto-kernel-cache``)
5*******************************************************
6
7.. _kernel-dev-advanced-overview:
8
9Overview
10========
11
12In addition to supporting configuration fragments and patches, the Yocto
13Project kernel tools also support rich
14:term:`Metadata` that you can use to define
15complex policies and Board Support Package (BSP) support. The purpose of
16the Metadata and the tools that manage it is to help you manage the
17complexity of the configuration and sources used to support multiple
18BSPs and Linux kernel types.
19
20Kernel Metadata exists in many places. One area in the
21:ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
22is the ``yocto-kernel-cache`` Git repository. You can find this repository
23grouped under the "Yocto Linux Kernel" heading in the
24:yocto_git:`Yocto Project Source Repositories <>`.
25
26Kernel development tools ("kern-tools") exist also in the Yocto Project
27Source Repositories under the "Yocto Linux Kernel" heading in the
28``yocto-kernel-tools`` Git repository. The recipe that builds these
29tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in
30the :term:`Source Directory` (e.g.
31``poky``).
32
33Using Kernel Metadata in a Recipe
34=================================
35
36As mentioned in the introduction, the Yocto Project contains kernel
37Metadata, which is located in the ``yocto-kernel-cache`` Git repository.
38This Metadata defines Board Support Packages (BSPs) that correspond to
39definitions in linux-yocto recipes for corresponding BSPs. A BSP
40consists of an aggregation of kernel policy and enabled
41hardware-specific features. The BSP can be influenced from within the
42linux-yocto recipe.
43
44.. note::
45
46 A Linux kernel recipe that contains kernel Metadata (e.g. inherits
47 from the
48 linux-yocto.inc
49 file) is said to be a "linux-yocto style" recipe.
50
51Every linux-yocto style recipe must define the
52:term:`KMACHINE` variable. This
53variable is typically set to the same value as the ``MACHINE`` variable,
54which is used by :term:`BitBake`.
55However, in some cases, the variable might instead refer to the
56underlying platform of the ``MACHINE``.
57
58Multiple BSPs can reuse the same ``KMACHINE`` name if they are built
59using the same BSP description. Multiple Corei7-based BSPs could share
60the same "intel-corei7-64" value for ``KMACHINE``. It is important to
61realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE``
62is the machine type within a BSP Layer. Even with this distinction,
63however, these two variables can hold the same value. See the `BSP
64Descriptions <#bsp-descriptions>`__ section for more information.
65
66Every linux-yocto style recipe must also indicate the Linux kernel
67source repository branch used to build the Linux kernel. The
68:term:`KBRANCH` variable must be set
69to indicate the branch.
70
71.. note::
72
73 You can use the
74 KBRANCH
75 value to define an alternate branch typically with a machine override
76 as shown here from the
77 meta-yocto-bsp
78 layer:
79 ::
80
81 KBRANCH_edgerouter = "standard/edgerouter"
82
83
84The linux-yocto style recipes can optionally define the following
85variables:
86
87 - :term:`KERNEL_FEATURES`
88
89 - :term:`LINUX_KERNEL_TYPE`
90
91:term:`LINUX_KERNEL_TYPE`
92defines the kernel type to be used in assembling the configuration. If
93you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard".
94Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search
95arguments used by the kernel tools to find the appropriate description
96within the kernel Metadata with which to build out the sources and
97configuration. The linux-yocto recipes define "standard", "tiny", and
98"preempt-rt" kernel types. See the "`Kernel Types <#kernel-types>`__"
99section for more information on kernel types.
100
101During the build, the kern-tools search for the BSP description file
102that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE``
103variables passed in from the recipe. The tools use the first BSP
104description it finds that match both variables. If the tools cannot find
105a match, they issue a warning.
106
107The tools first search for the ``KMACHINE`` and then for the
108``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they
109will use the sources from the ``KBRANCH`` and any configuration
110specified in the :term:`SRC_URI`.
111
112You can use the
113:term:`KERNEL_FEATURES`
114variable to include features (configuration fragments, patches, or both)
115that are not already included by the ``KMACHINE`` and
116``LINUX_KERNEL_TYPE`` variable combination. For example, to include a
117feature specified as "features/netfilter/netfilter.scc", specify:
118::
119
120 KERNEL_FEATURES += "features/netfilter/netfilter.scc"
121
122To include a
123feature called "cfg/sound.scc" just for the ``qemux86`` machine,
124specify:
125::
126
127 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc"
128
129The value of
130the entries in ``KERNEL_FEATURES`` are dependent on their location
131within the kernel Metadata itself. The examples here are taken from the
132``yocto-kernel-cache`` repository. Each branch of this repository
133contains "features" and "cfg" subdirectories at the top-level. For more
134information, see the "`Kernel Metadata
135Syntax <#kernel-metadata-syntax>`__" section.
136
137Kernel Metadata Syntax
138======================
139
140The kernel Metadata consists of three primary types of files: ``scc``
141[1]_ description files, configuration fragments, and patches. The
142``scc`` files define variables and include or otherwise reference any of
143the three file types. The description files are used to aggregate all
144types of kernel Metadata into what ultimately describes the sources and
145the configuration required to build a Linux kernel tailored to a
146specific machine.
147
148The ``scc`` description files are used to define two fundamental types
149of kernel Metadata:
150
151- Features
152
153- Board Support Packages (BSPs)
154
155Features aggregate sources in the form of patches and configuration
156fragments into a modular reusable unit. You can use features to
157implement conceptually separate kernel Metadata descriptions such as
158pure configuration fragments, simple patches, complex features, and
159kernel types. `Kernel types <#kernel-types>`__ define general kernel
160features and policy to be reused in the BSPs.
161
162BSPs define hardware-specific features and aggregate them with kernel
163types to form the final description of what will be assembled and built.
164
165While the kernel Metadata syntax does not enforce any logical separation
166of configuration fragments, patches, features or kernel types, best
167practices dictate a logical separation of these types of Metadata. The
168following Metadata file hierarchy is recommended:
169::
170
171 base/
172 bsp/
173 cfg/
174 features/
175 ktypes/
176 patches/
177
178The ``bsp`` directory contains the `BSP
179descriptions <#bsp-descriptions>`__. The remaining directories all
180contain "features". Separating ``bsp`` from the rest of the structure
181aids conceptualizing intended usage.
182
183Use these guidelines to help place your ``scc`` description files within
184the structure:
185
186- If your file contains only configuration fragments, place the file in
187 the ``cfg`` directory.
188
189- If your file contains only source-code fixes, place the file in the
190 ``patches`` directory.
191
192- If your file encapsulates a major feature, often combining sources
193 and configurations, place the file in ``features`` directory.
194
195- If your file aggregates non-hardware configuration and patches in
196 order to define a base kernel policy or major kernel type to be
197 reused across multiple BSPs, place the file in ``ktypes`` directory.
198
199These distinctions can easily become blurred - especially as out-of-tree
200features slowly merge upstream over time. Also, remember that how the
201description files are placed is a purely logical organization and has no
202impact on the functionality of the kernel Metadata. There is no impact
203because all of ``cfg``, ``features``, ``patches``, and ``ktypes``,
204contain "features" as far as the kernel tools are concerned.
205
206Paths used in kernel Metadata files are relative to base, which is
207either
208:term:`FILESEXTRAPATHS` if
209you are creating Metadata in `recipe-space <#recipe-space-metadata>`__,
210or the top level of
211:yocto_git:`yocto-kernel-cache </cgit/cgit.cgi/yocto-kernel-cache/tree/>`
212if you are creating `Metadata outside of the
213recipe-space <#metadata-outside-the-recipe-space>`__.
214
215.. [1]
216 ``scc`` stands for Series Configuration Control, but the naming has
217 less significance in the current implementation of the tooling than
218 it had in the past. Consider ``scc`` files to be description files.
219
220Configuration
221-------------
222
223The simplest unit of kernel Metadata is the configuration-only feature.
224This feature consists of one or more Linux kernel configuration
225parameters in a configuration fragment file (``.cfg``) and a ``.scc``
226file that describes the fragment.
227
228As an example, consider the Symmetric Multi-Processing (SMP) fragment
229used with the ``linux-yocto-4.12`` kernel as defined outside of the
230recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
231two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
232``cfg`` directory of the ``yocto-4.12`` branch in the
233``yocto-kernel-cache`` Git repository:
234::
235
236 cfg/smp.scc:
237 define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
238 define KFEATURE_COMPATIBILITY all
239
240 kconf hardware smp.cfg
241
242 cfg/smp.cfg:
243 CONFIG_SMP=y
244 CONFIG_SCHED_SMT=y
245 # Increase default NR_CPUS from 8 to 64 so that platform with
246 # more than 8 processors can be all activated at boot time
247 CONFIG_NR_CPUS=64
248 # The following is needed when setting NR_CPUS to something
249 # greater than 8 on x86 architectures, it should be automatically
250 # disregarded by Kconfig when using a different arch
251 CONFIG_X86_BIGSMP=y
252
253You can find general information on configuration
254fragment files in the "`Creating Configuration
255Fragments <#creating-config-fragments>`__" section.
256
257Within the ``smp.scc`` file, the
258:term:`KFEATURE_DESCRIPTION`
259statement provides a short description of the fragment. Higher level
260kernel tools use this description.
261
262Also within the ``smp.scc`` file, the ``kconf`` command includes the
263actual configuration fragment in an ``.scc`` file, and the "hardware"
264keyword identifies the fragment as being hardware enabling, as opposed
265to general policy, which would use the "non-hardware" keyword. The
266distinction is made for the benefit of the configuration validation
267tools, which warn you if a hardware fragment overrides a policy set by a
268non-hardware fragment.
269
270.. note::
271
272 The description file can include multiple
273 kconf
274 statements, one per fragment.
275
276As described in the "`Validating
277Configuration <#validating-configuration>`__" section, you can use the
278following BitBake command to audit your configuration:
279::
280
281 $ bitbake linux-yocto -c kernel_configcheck -f
282
283Patches
284-------
285
286Patch descriptions are very similar to configuration fragment
287descriptions, which are described in the previous section. However,
288instead of a ``.cfg`` file, these descriptions work with source patches
289(i.e. ``.patch`` files).
290
291A typical patch includes a description file and the patch itself. As an
292example, consider the build patches used with the ``linux-yocto-4.12``
293kernel as defined outside of the recipe space (i.e.
294``yocto-kernel-cache``). This Metadata consists of several files:
295``build.scc`` and a set of ``*.patch`` files. You can find these files
296in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
297``yocto-kernel-cache`` Git repository.
298
299The following listings show the ``build.scc`` file and part of the
300``modpost-mask-trivial-warnings.patch`` file:
301::
302
303 patches/build/build.scc:
304 patch arm-serialize-build-targets.patch
305 patch powerpc-serialize-image-targets.patch
306 patch kbuild-exclude-meta-directory-from-distclean-processi.patch
307
308 # applied by kgit
309 # patch kbuild-add-meta-files-to-the-ignore-li.patch
310
311 patch modpost-mask-trivial-warnings.patch
312 patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
313
314 patches/build/modpost-mask-trivial-warnings.patch:
315 From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
316 From: Paul Gortmaker <paul.gortmaker@windriver.com>
317 Date: Sun, 25 Jan 2009 17:58:09 -0500
318 Subject: [PATCH] modpost: mask trivial warnings
319
320 Newer HOSTCC will complain about various stdio fcns because
321 .
322 .
323 .
324 char *dump_write = NULL, *files_source = NULL;
325 int opt;
326 --
327 2.10.1
328
329 generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
330
331The description file can
332include multiple patch statements where each statement handles a single
333patch. In the example ``build.scc`` file, five patch statements exist
334for the five patches in the directory.
335
336You can create a typical ``.patch`` file using ``diff -Nurp`` or
337``git format-patch`` commands. For information on how to create patches,
338see the "`Using ``devtool`` to Patch the
339Kernel <#using-devtool-to-patch-the-kernel>`__" and "`Using Traditional
340Kernel Development to Patch the
341Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
342sections.
343
344Features
345--------
346
347Features are complex kernel Metadata types that consist of configuration
348fragments, patches, and possibly other feature description files. As an
349example, consider the following generic listing:
350::
351
352 features/myfeature.scc
353 define KFEATURE_DESCRIPTION "Enable myfeature"
354
355 patch 0001-myfeature-core.patch
356 patch 0002-myfeature-interface.patch
357
358 include cfg/myfeature_dependency.scc
359 kconf non-hardware myfeature.cfg
360
361This example shows how the ``patch`` and ``kconf`` commands are used as well
362as how an additional feature description file is included with the
363``include`` command.
364
365Typically, features are less granular than configuration fragments and
366are more likely than configuration fragments and patches to be the types
367of things you want to specify in the ``KERNEL_FEATURES`` variable of the
368Linux kernel recipe. See the "`Using Kernel Metadata in a
369Recipe <#using-kernel-metadata-in-a-recipe>`__" section earlier in the
370manual.
371
372Kernel Types
373------------
374
375A kernel type defines a high-level kernel policy by aggregating
376non-hardware configuration fragments with patches you want to use when
377building a Linux kernel of a specific type (e.g. a real-time kernel).
378Syntactically, kernel types are no different than features as described
379in the "`Features <#features>`__" section. The
380:term:`LINUX_KERNEL_TYPE`
381variable in the kernel recipe selects the kernel type. For example, in
382the ``linux-yocto_4.12.bb`` kernel recipe found in
383``poky/meta/recipes-kernel/linux``, a
384:ref:`require <bitbake:require-inclusion>` directive
385includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
386which has the following statement that defines the default kernel type:
387::
388
389 LINUX_KERNEL_TYPE ??= "standard"
390
391Another example would be the real-time kernel (i.e.
392``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
393type as follows:
394::
395
396 LINUX_KERNEL_TYPE = "preempt-rt"
397
398.. note::
399
400 You can find kernel recipes in the
401 meta/recipes-kernel/linux
402 directory of the
403 Source Directory
404 (e.g.
405 poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb
406 ). See the "
407 Using Kernel Metadata in a Recipe
408 " section for more information.
409
410Three kernel types ("standard", "tiny", and "preempt-rt") are supported
411for Linux Yocto kernels:
412
413- "standard": Includes the generic Linux kernel policy of the Yocto
414 Project linux-yocto kernel recipes. This policy includes, among other
415 things, which file systems, networking options, core kernel features,
416 and debugging and tracing options are supported.
417
418- "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
419 configuration options required to build a real-time Linux kernel.
420 This kernel type inherits from the "standard" kernel type.
421
422- "tiny": Defines a bare minimum configuration meant to serve as a base
423 for very small Linux kernels. The "tiny" kernel type is independent
424 from the "standard" configuration. Although the "tiny" kernel type
425 does not currently include any source changes, it might in the
426 future.
427
428For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
429``standard.scc``). Here is a partial listing for the ``standard.scc``
430file, which is found in the ``ktypes/standard`` directory of the
431``yocto-kernel-cache`` Git repository:
432::
433
434 # Include this kernel type fragment to get the standard features and
435 # configuration values.
436
437 # Note: if only the features are desired, but not the configuration
438 # then this should be included as:
439 # include ktypes/standard/standard.scc nocfg
440 # if no chained configuration is desired, include it as:
441 # include ktypes/standard/standard.scc nocfg inherit
442
443
444
445 include ktypes/base/base.scc
446 branch standard
447
448 kconf non-hardware standard.cfg
449
450 include features/kgdb/kgdb.scc
451 .
452 .
453 .
454
455 include cfg/net/ip6_nf.scc
456 include cfg/net/bridge.scc
457
458 include cfg/systemd.scc
459
460 include features/rfkill/rfkill.scc
461
462As with any ``.scc`` file, a kernel type definition can aggregate other
463``.scc`` files with ``include`` commands. These definitions can also
464directly pull in configuration fragments and patches with the ``kconf``
465and ``patch`` commands, respectively.
466
467.. note::
468
469 It is not strictly necessary to create a kernel type
470 .scc
471 file. The Board Support Package (BSP) file can implicitly define the
472 kernel type using a
473 define
474 KTYPE
475 myktype
476 line. See the "
477 BSP Descriptions
478 " section for more information.
479
480BSP Descriptions
481----------------
482
483BSP descriptions (i.e. ``*.scc`` files) combine kernel types with
484hardware-specific features. The hardware-specific Metadata is typically
485defined independently in the BSP layer, and then aggregated with each
486supported kernel type.
487
488.. note::
489
490 For BSPs supported by the Yocto Project, the BSP description files
491 are located in the
492 bsp
493 directory of the
494 yocto-kernel-cache
495 repository organized under the "Yocto Linux Kernel" heading in the
496 Yocto Project Source Repositories
497 .
498
499This section overviews the BSP description structure, the aggregation
500concepts, and presents a detailed example using a BSP supported by the
501Yocto Project (i.e. BeagleBone Board). For complete information on BSP
502layer file hierarchy, see the :doc:`../bsp-guide/bsp-guide`.
503
504.. _bsp-description-file-overview:
505
506Description Overview
507~~~~~~~~~~~~~~~~~~~~
508
509For simplicity, consider the following root BSP layer description files
510for the BeagleBone board. These files employ both a structure and naming
511convention for consistency. The naming convention for the file is as
512follows:
513::
514
515 bsp_root_name-kernel_type.scc
516
517Here are some example root layer
518BSP filenames for the BeagleBone Board BSP, which is supported by the
519Yocto Project:
520::
521
522 beaglebone-standard.scc
523 beaglebone-preempt-rt.scc
524
525Each file uses the root name (i.e "beaglebone") BSP name followed by the
526kernel type.
527
528Examine the ``beaglebone-standard.scc`` file:
529::
530
531 define KMACHINE beaglebone
532 define KTYPE standard
533 define KARCH arm
534
535 include ktypes/standard/standard.scc
536 branch beaglebone
537
538 include beaglebone.scc
539
540 # default policy for standard kernels
541 include features/latencytop/latencytop.scc
542 include features/profiling/profiling.scc
543
544Every top-level BSP description file
545should define the :term:`KMACHINE`,
546:term:`KTYPE`, and
547:term:`KARCH` variables. These
548variables allow the OpenEmbedded build system to identify the
549description as meeting the criteria set by the recipe being built. This
550example supports the "beaglebone" machine for the "standard" kernel and
551the "arm" architecture.
552
553Be aware that a hard link between the ``KTYPE`` variable and a kernel
554type description file does not exist. Thus, if you do not have the
555kernel type defined in your kernel Metadata as it is here, you only need
556to ensure that the
557:term:`LINUX_KERNEL_TYPE`
558variable in the kernel recipe and the ``KTYPE`` variable in the BSP
559description file match.
560
561To separate your kernel policy from your hardware configuration, you
562include a kernel type (``ktype``), such as "standard". In the previous
563example, this is done using the following:
564::
565
566 include ktypes/standard/standard.scc
567
568This file aggregates all the configuration
569fragments, patches, and features that make up your standard kernel
570policy. See the "`Kernel Types <#kernel-types>`__" section for more
571information.
572
573To aggregate common configurations and features specific to the kernel
574for mybsp, use the following:
575::
576
577 include mybsp.scc
578
579You can see that in the BeagleBone example with the following:
580::
581
582 include beaglebone.scc
583
584For information on how to break a complete ``.config`` file into the various
585configuration fragments, see the "`Creating Configuration
586Fragments <#creating-config-fragments>`__" section.
587
588Finally, if you have any configurations specific to the hardware that
589are not in a ``*.scc`` file, you can include them as follows:
590::
591
592 kconf hardware mybsp-extra.cfg
593
594The BeagleBone example does not include these
595types of configurations. However, the Malta 32-bit board does
596("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:
597::
598
599 define KMACHINE mti-malta32-le
600 define KMACHINE qemumipsel
601 define KTYPE standard
602 define KARCH mips
603
604 include ktypes/standard/standard.scc
605 branch mti-malta32
606
607 include mti-malta32.scc
608 kconf hardware mti-malta32-le.cfg
609
610.. _bsp-description-file-example-minnow:
611
612Example
613~~~~~~~
614
615Many real-world examples are more complex. Like any other ``.scc`` file,
616BSP descriptions can aggregate features. Consider the Minnow BSP
617definition given the ``linux-yocto-4.4`` branch of the
618``yocto-kernel-cache`` (i.e.
619``yocto-kernel-cache/bsp/minnow/minnow.scc``):
620
621.. note::
622
623 Although the Minnow Board BSP is unused, the Metadata remains and is
624 being used here just as an example.
625
626::
627
628 include cfg/x86.scc
629 include features/eg20t/eg20t.scc
630 include cfg/dmaengine.scc
631 include features/power/intel.scc
632 include cfg/efi.scc
633 include features/usb/ehci-hcd.scc
634 include features/usb/ohci-hcd.scc
635 include features/usb/usb-gadgets.scc
636 include features/usb/touchscreen-composite.scc
637 include cfg/timer/hpet.scc
638 include features/leds/leds.scc
639 include features/spi/spidev.scc
640 include features/i2c/i2cdev.scc
641 include features/mei/mei-txe.scc
642
643 # Earlyprintk and port debug requires 8250
644 kconf hardware cfg/8250.cfg
645
646 kconf hardware minnow.cfg
647 kconf hardware minnow-dev.cfg
648
649The ``minnow.scc`` description file includes a hardware configuration
650fragment (``minnow.cfg``) specific to the Minnow BSP as well as several
651more general configuration fragments and features enabling hardware
652found on the machine. This ``minnow.scc`` description file is then
653included in each of the three "minnow" description files for the
654supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
655Consider the "minnow" description for the "standard" kernel type (i.e.
656``minnow-standard.scc``:
657::
658
659 define KMACHINE minnow
660 define KTYPE standard
661 define KARCH i386
662
663 include ktypes/standard
664
665 include minnow.scc
666
667 # Extra minnow configs above the minimal defined in minnow.scc
668 include cfg/efi-ext.scc
669 include features/media/media-all.scc
670 include features/sound/snd_hda_intel.scc
671
672 # The following should really be in standard.scc
673 # USB live-image support
674 include cfg/usb-mass-storage.scc
675 include cfg/boot-live.scc
676
677 # Basic profiling
678 include features/latencytop/latencytop.scc
679 include features/profiling/profiling.scc
680
681 # Requested drivers that don't have an existing scc
682 kconf hardware minnow-drivers-extra.cfg
683
684The ``include`` command midway through the file includes the ``minnow.scc`` description
685that defines all enabled hardware for the BSP that is common to all
686kernel types. Using this command significantly reduces duplication.
687
688Now consider the "minnow" description for the "tiny" kernel type (i.e.
689``minnow-tiny.scc``):
690::
691
692 define KMACHINE minnow
693 define KTYPE tiny
694 define KARCH i386
695
696 include ktypes/tiny
697
698 include minnow.scc
699
700As you might expect,
701the "tiny" description includes quite a bit less. In fact, it includes
702only the minimal policy defined by the "tiny" kernel type and the
703hardware-specific configuration required for booting the machine along
704with the most basic functionality of the system as defined in the base
705"minnow" description file.
706
707Notice again the three critical variables:
708:term:`KMACHINE`,
709:term:`KTYPE`, and
710:term:`KARCH`. Of these variables, only
711``KTYPE`` has changed to specify the "tiny" kernel type.
712
713Kernel Metadata Location
714========================
715
716Kernel Metadata always exists outside of the kernel tree either defined
717in a kernel recipe (recipe-space) or outside of the recipe. Where you
718choose to define the Metadata depends on what you want to do and how you
719intend to work. Regardless of where you define the kernel Metadata, the
720syntax used applies equally.
721
722If you are unfamiliar with the Linux kernel and only wish to apply a
723configuration and possibly a couple of patches provided to you by
724others, the recipe-space method is recommended. This method is also a
725good approach if you are working with Linux kernel sources you do not
726control or if you just do not want to maintain a Linux kernel Git
727repository on your own. For partial information on how you can define
728kernel Metadata in the recipe-space, see the "`Modifying an Existing
729Recipe <#modifying-an-existing-recipe>`__" section.
730
731Conversely, if you are actively developing a kernel and are already
732maintaining a Linux kernel Git repository of your own, you might find it
733more convenient to work with kernel Metadata kept outside the
734recipe-space. Working with Metadata in this area can make iterative
735development of the Linux kernel more efficient outside of the BitBake
736environment.
737
738Recipe-Space Metadata
739---------------------
740
741When stored in recipe-space, the kernel Metadata files reside in a
742directory hierarchy below
743:term:`FILESEXTRAPATHS`. For
744a linux-yocto recipe or for a Linux kernel recipe derived by copying and
745modifying
746``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to
747a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to
748``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
749See the "`Modifying an Existing
750Recipe <#modifying-an-existing-recipe>`__" section for more information.
751
752Here is an example that shows a trivial tree of kernel Metadata stored
753in recipe-space within a BSP layer:
754::
755
756 meta-my_bsp_layer/
757 `-- recipes-kernel
758 `-- linux
759 `-- linux-yocto
760 |-- bsp-standard.scc
761 |-- bsp.cfg
762 `-- standard.cfg
763
764When the Metadata is stored in recipe-space, you must take steps to
765ensure BitBake has the necessary information to decide what files to
766fetch and when they need to be fetched again. It is only necessary to
767specify the ``.scc`` files on the
768:term:`SRC_URI`. BitBake parses them
769and fetches any files referenced in the ``.scc`` files by the
770``include``, ``patch``, or ``kconf`` commands. Because of this, it is
771necessary to bump the recipe :term:`PR`
772value when changing the content of files not explicitly listed in the
773``SRC_URI``.
774
775If the BSP description is in recipe space, you cannot simply list the
776``*.scc`` in the ``SRC_URI`` statement. You need to use the following
777form from your kernel append file:
778::
779
780 SRC_URI_append_myplatform = " \
781 file://myplatform;type=kmeta;destsuffix=myplatform \
782 "
783
784Metadata Outside the Recipe-Space
785---------------------------------
786
787When stored outside of the recipe-space, the kernel Metadata files
788reside in a separate repository. The OpenEmbedded build system adds the
789Metadata to the build as a "type=kmeta" repository through the
790:term:`SRC_URI` variable. As an
791example, consider the following ``SRC_URI`` statement from the
792``linux-yocto_4.12.bb`` kernel recipe:
793::
794
795 SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
796 git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
797
798
799``${KMETA}``, in this context, is simply used to name the directory into
800which the Git fetcher places the Metadata. This behavior is no different
801than any multi-repository ``SRC_URI`` statement used in a recipe (e.g.
802see the previous section).
803
804You can keep kernel Metadata in a "kernel-cache", which is a directory
805containing configuration fragments. As with any Metadata kept outside
806the recipe-space, you simply need to use the ``SRC_URI`` statement with
807the "type=kmeta" attribute. Doing so makes the kernel Metadata available
808during the configuration phase.
809
810If you modify the Metadata, you must not forget to update the ``SRCREV``
811statements in the kernel's recipe. In particular, you need to update the
812``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
813wish to use. Changing the data in these branches and not updating the
814``SRCREV`` statements to match will cause the build to fetch an older
815commit.
816
817Organizing Your Source
818======================
819
820Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
821kernel sources that have only a single branch - "master". This type of
822repository structure is fine for linear development supporting a single
823machine and architecture. However, if you work with multiple boards and
824architectures, a kernel source repository with multiple branches is more
825efficient. For example, suppose you need a series of patches for one
826board to boot. Sometimes, these patches are works-in-progress or
827fundamentally wrong, yet they are still necessary for specific boards.
828In these situations, you most likely do not want to include these
829patches in every kernel you build (i.e. have the patches as part of the
830lone "master" branch). It is situations like these that give rise to
831multiple branches used within a Linux kernel sources Git repository.
832
833Repository organization strategies exist that maximize source reuse,
834remove redundancy, and logically order your changes. This section
835presents strategies for the following cases:
836
837- Encapsulating patches in a feature description and only including the
838 patches in the BSP descriptions of the applicable boards.
839
840- Creating a machine branch in your kernel source repository and
841 applying the patches on that branch only.
842
843- Creating a feature branch in your kernel source repository and
844 merging that branch into your BSP when needed.
845
846The approach you take is entirely up to you and depends on what works
847best for your development model.
848
849Encapsulating Patches
850---------------------
851
852if you are reusing patches from an external tree and are not working on
853the patches, you might find the encapsulated feature to be appropriate.
854Given this scenario, you do not need to create any branches in the
855source repository. Rather, you just take the static patches you need and
856encapsulate them within a feature description. Once you have the feature
857description, you simply include that into the BSP description as
858described in the "`BSP Descriptions <#bsp-descriptions>`__" section.
859
860You can find information on how to create patches and BSP descriptions
861in the "`Patches <#patches>`__" and "`BSP
862Descriptions <#bsp-descriptions>`__" sections.
863
864Machine Branches
865----------------
866
867When you have multiple machines and architectures to support, or you are
868actively working on board support, it is more efficient to create
869branches in the repository based on individual machines. Having machine
870branches allows common source to remain in the "master" branch with any
871features specific to a machine stored in the appropriate machine branch.
872This organization method frees you from continually reintegrating your
873patches into a feature.
874
875Once you have a new branch, you can set up your kernel Metadata to use
876the branch a couple different ways. In the recipe, you can specify the
877new branch as the ``KBRANCH`` to use for the board as follows:
878::
879
880 KBRANCH = "mynewbranch"
881
882Another method is to use the ``branch`` command in the BSP
883description:
884
885 mybsp.scc:
886 define KMACHINE mybsp
887 define KTYPE standard
888 define KARCH i386
889 include standard.scc
890
891 branch mynewbranch
892
893 include mybsp-hw.scc
894
895If you find yourself with numerous branches, you might consider using a
896hierarchical branching system similar to what the Yocto Linux Kernel Git
897repositories use:
898::
899
900 common/kernel_type/machine
901
902If you had two kernel types, "standard" and "small" for instance, three
903machines, and common as ``mydir``, the branches in your Git repository
904might look like this:
905:
906
907 mydir/base
908 mydir/standard/base
909 mydir/standard/machine_a
910 mydir/standard/machine_b
911 mydir/standard/machine_c
912 mydir/small/base
913 mydir/small/machine_a
914
915This organization can help clarify the branch relationships. In this
916case, ``mydir/standard/machine_a`` includes everything in ``mydir/base``
917and ``mydir/standard/base``. The "standard" and "small" branches add
918sources specific to those kernel types that for whatever reason are not
919appropriate for the other branches.
920
921.. note::
922
923 The "base" branches are an artifact of the way Git manages its data
924 internally on the filesystem: Git will not allow you to use
925 mydir/standard
926 and
927 mydir/standard/machine_a
928 because it would have to create a file and a directory named
929 "standard".
930
931Feature Branches
932----------------
933
934When you are actively developing new features, it can be more efficient
935to work with that feature as a branch, rather than as a set of patches
936that have to be regularly updated. The Yocto Project Linux kernel tools
937provide for this with the ``git merge`` command.
938
939To merge a feature branch into a BSP, insert the ``git merge`` command
940after any ``branch`` commands:
941::
942
943 mybsp.scc:
944 define KMACHINE mybsp
945 define KTYPE standard
946 define KARCH i386
947 include standard.scc
948
949 branch mynewbranch
950 git merge myfeature
951
952 include mybsp-hw.scc
953
954.. _scc-reference:
955
956SCC Description File Reference
957==============================
958
959This section provides a brief reference for the commands you can use
960within an SCC description file (``.scc``):
961
962- ``branch [ref]``: Creates a new branch relative to the current branch
963 (typically ``${KTYPE}``) using the currently checked-out branch, or
964 "ref" if specified.
965
966- ``define``: Defines variables, such as
967 :term:`KMACHINE`,
968 :term:`KTYPE`,
969 :term:`KARCH`, and
970 :term:`KFEATURE_DESCRIPTION`.
971
972- ``include SCC_FILE``: Includes an SCC file in the current file. The
973 file is parsed as if you had inserted it inline.
974
975- ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration
976 fragment for merging into the final Linux ``.config`` file.
977
978- ``git merge GIT_BRANCH``: Merges the feature branch into the current
979 branch.
980
981- ``patch PATCH_FILE``: Applies the patch to the current Git branch.
982
983