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