blob: b5290b61b3880b222a373f252fdc9a92fe78c2f0 [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
William A. Kennington IIIac69b482021-06-02 12:28:27 -070024Kernel development tools ("kern-tools") are also available in the Yocto Project
Andrew Geisslerc9f78652020-09-18 14:11:35 -050025Source 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
Andrew Geissler09036742021-06-25 14:25:14 -050049variable is typically set to the same value as the :term:`MACHINE` variable,
Andrew Geisslerc9f78652020-09-18 14:11:35 -050050which is used by :term:`BitBake`.
51However, in some cases, the variable might instead refer to the
Andrew Geissler09036742021-06-25 14:25:14 -050052underlying platform of the :term:`MACHINE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050053
Andrew Geissler09036742021-06-25 14:25:14 -050054Multiple BSPs can reuse the same :term:`KMACHINE` name if they are built
Andrew Geisslerc9f78652020-09-18 14:11:35 -050055using the same BSP description. Multiple Corei7-based BSPs could share
Andrew Geissler09036742021-06-25 14:25:14 -050056the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to
57realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050058is the machine type within a BSP Layer. Even with this distinction,
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050059however, these two variables can hold the same value. See the
60":ref:`kernel-dev/advanced:bsp descriptions`" section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061
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 Geissler09036742021-06-25 14:25:14 -050069 You can use the :term:`KBRANCH` value to define an alternate branch typically
Andrew Geisslerc926e172021-05-07 16:11:35 -050070 with a machine override as shown here from the ``meta-yocto-bsp`` layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050071
Patrick Williams0ca19cc2021-08-16 14:03:13 -050072 KBRANCH:edgerouter = "standard/edgerouter"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050073
74
75The linux-yocto style recipes can optionally define the following
76variables:
77
78 - :term:`KERNEL_FEATURES`
79
80 - :term:`LINUX_KERNEL_TYPE`
81
82:term:`LINUX_KERNEL_TYPE`
83defines the kernel type to be used in assembling the configuration. If
Andrew Geissler09036742021-06-25 14:25:14 -050084you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard".
85Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` defines the search
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086arguments used by the kernel tools to find the appropriate description
87within the kernel Metadata with which to build out the sources and
88configuration. The linux-yocto recipes define "standard", "tiny", and
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050089"preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090section for more information on kernel types.
91
92During the build, the kern-tools search for the BSP description file
Andrew Geissler09036742021-06-25 14:25:14 -050093that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050094variables passed in from the recipe. The tools use the first BSP
Andrew Geissler4c19ea12020-10-27 13:52:24 -050095description they find that matches both variables. If the tools cannot find
Andrew Geisslerc9f78652020-09-18 14:11:35 -050096a match, they issue a warning.
97
Andrew Geissler09036742021-06-25 14:25:14 -050098The tools first search for the :term:`KMACHINE` and then for the
99:term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they
100will use the sources from the :term:`KBRANCH` and any configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500101specified in the :term:`SRC_URI`.
102
103You can use the
104:term:`KERNEL_FEATURES`
105variable to include features (configuration fragments, patches, or both)
Andrew Geissler09036742021-06-25 14:25:14 -0500106that are not already included by the :term:`KMACHINE` and
107:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500108feature specified as "features/netfilter/netfilter.scc", specify::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500109
110 KERNEL_FEATURES += "features/netfilter/netfilter.scc"
111
112To include a
113feature called "cfg/sound.scc" just for the ``qemux86`` machine,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500114specify::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500116 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117
118The value of
Andrew Geissler09036742021-06-25 14:25:14 -0500119the entries in :term:`KERNEL_FEATURES` are dependent on their location
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500120within the kernel Metadata itself. The examples here are taken from the
121``yocto-kernel-cache`` repository. Each branch of this repository
122contains "features" and "cfg" subdirectories at the top-level. For more
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500123information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`"
124section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500125
126Kernel Metadata Syntax
127======================
128
129The kernel Metadata consists of three primary types of files: ``scc``
130[1]_ description files, configuration fragments, and patches. The
131``scc`` files define variables and include or otherwise reference any of
132the three file types. The description files are used to aggregate all
133types of kernel Metadata into what ultimately describes the sources and
134the configuration required to build a Linux kernel tailored to a
135specific machine.
136
137The ``scc`` description files are used to define two fundamental types
138of kernel Metadata:
139
140- Features
141
142- Board Support Packages (BSPs)
143
144Features aggregate sources in the form of patches and configuration
145fragments into a modular reusable unit. You can use features to
146implement conceptually separate kernel Metadata descriptions such as
147pure configuration fragments, simple patches, complex features, and
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500148kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500149features and policy to be reused in the BSPs.
150
151BSPs define hardware-specific features and aggregate them with kernel
152types to form the final description of what will be assembled and built.
153
154While the kernel Metadata syntax does not enforce any logical separation
155of configuration fragments, patches, features or kernel types, best
156practices dictate a logical separation of these types of Metadata. The
Andrew Geisslerc926e172021-05-07 16:11:35 -0500157following Metadata file hierarchy is recommended::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500158
159 base/
160 bsp/
161 cfg/
162 features/
163 ktypes/
164 patches/
165
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500166The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`.
167The remaining directories all contain "features". Separating ``bsp`` from the
168rest of the structure aids conceptualizing intended usage.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500169
170Use these guidelines to help place your ``scc`` description files within
171the structure:
172
173- If your file contains only configuration fragments, place the file in
174 the ``cfg`` directory.
175
176- If your file contains only source-code fixes, place the file in the
177 ``patches`` directory.
178
179- If your file encapsulates a major feature, often combining sources
180 and configurations, place the file in ``features`` directory.
181
182- If your file aggregates non-hardware configuration and patches in
183 order to define a base kernel policy or major kernel type to be
184 reused across multiple BSPs, place the file in ``ktypes`` directory.
185
186These distinctions can easily become blurred - especially as out-of-tree
187features slowly merge upstream over time. Also, remember that how the
188description files are placed is a purely logical organization and has no
189impact on the functionality of the kernel Metadata. There is no impact
190because all of ``cfg``, ``features``, ``patches``, and ``ktypes``,
191contain "features" as far as the kernel tools are concerned.
192
193Paths used in kernel Metadata files are relative to base, which is
194either
195:term:`FILESEXTRAPATHS` if
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500196you are creating Metadata in
197:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500198or the top level of
Andrew Geissler09209ee2020-12-13 08:44:15 -0600199:yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500200if you are creating
201:ref:`kernel-dev/advanced:metadata outside the recipe-space`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500202
203.. [1]
204 ``scc`` stands for Series Configuration Control, but the naming has
205 less significance in the current implementation of the tooling than
206 it had in the past. Consider ``scc`` files to be description files.
207
208Configuration
209-------------
210
211The simplest unit of kernel Metadata is the configuration-only feature.
212This feature consists of one or more Linux kernel configuration
213parameters in a configuration fragment file (``.cfg``) and a ``.scc``
214file that describes the fragment.
215
216As an example, consider the Symmetric Multi-Processing (SMP) fragment
217used with the ``linux-yocto-4.12`` kernel as defined outside of the
218recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
219two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
220``cfg`` directory of the ``yocto-4.12`` branch in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500221``yocto-kernel-cache`` Git repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500222
223 cfg/smp.scc:
224 define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
225 define KFEATURE_COMPATIBILITY all
226
227 kconf hardware smp.cfg
228
229 cfg/smp.cfg:
230 CONFIG_SMP=y
231 CONFIG_SCHED_SMT=y
232 # Increase default NR_CPUS from 8 to 64 so that platform with
233 # more than 8 processors can be all activated at boot time
234 CONFIG_NR_CPUS=64
235 # The following is needed when setting NR_CPUS to something
236 # greater than 8 on x86 architectures, it should be automatically
237 # disregarded by Kconfig when using a different arch
238 CONFIG_X86_BIGSMP=y
239
240You can find general information on configuration
Andrew Geissler09209ee2020-12-13 08:44:15 -0600241fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500242
243Within the ``smp.scc`` file, the
244:term:`KFEATURE_DESCRIPTION`
245statement provides a short description of the fragment. Higher level
246kernel tools use this description.
247
248Also within the ``smp.scc`` file, the ``kconf`` command includes the
249actual configuration fragment in an ``.scc`` file, and the "hardware"
250keyword identifies the fragment as being hardware enabling, as opposed
251to general policy, which would use the "non-hardware" keyword. The
252distinction is made for the benefit of the configuration validation
253tools, which warn you if a hardware fragment overrides a policy set by a
254non-hardware fragment.
255
256.. note::
257
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500258 The description file can include multiple ``kconf`` statements, one per
259 fragment.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500261As described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600262":ref:`kernel-dev/common:validating configuration`" section, you can
Andrew Geisslerc926e172021-05-07 16:11:35 -0500263use the following BitBake command to audit your configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500264
265 $ bitbake linux-yocto -c kernel_configcheck -f
266
267Patches
268-------
269
270Patch descriptions are very similar to configuration fragment
271descriptions, which are described in the previous section. However,
272instead of a ``.cfg`` file, these descriptions work with source patches
273(i.e. ``.patch`` files).
274
275A typical patch includes a description file and the patch itself. As an
276example, consider the build patches used with the ``linux-yocto-4.12``
277kernel as defined outside of the recipe space (i.e.
278``yocto-kernel-cache``). This Metadata consists of several files:
279``build.scc`` and a set of ``*.patch`` files. You can find these files
280in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
281``yocto-kernel-cache`` Git repository.
282
283The following listings show the ``build.scc`` file and part of the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500284``modpost-mask-trivial-warnings.patch`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500285
286 patches/build/build.scc:
287 patch arm-serialize-build-targets.patch
288 patch powerpc-serialize-image-targets.patch
289 patch kbuild-exclude-meta-directory-from-distclean-processi.patch
290
291 # applied by kgit
292 # patch kbuild-add-meta-files-to-the-ignore-li.patch
293
294 patch modpost-mask-trivial-warnings.patch
295 patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
296
297 patches/build/modpost-mask-trivial-warnings.patch:
298 From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
299 From: Paul Gortmaker <paul.gortmaker@windriver.com>
300 Date: Sun, 25 Jan 2009 17:58:09 -0500
301 Subject: [PATCH] modpost: mask trivial warnings
302
303 Newer HOSTCC will complain about various stdio fcns because
304 .
305 .
306 .
307 char *dump_write = NULL, *files_source = NULL;
308 int opt;
309 --
310 2.10.1
311
312 generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
313
314The description file can
315include multiple patch statements where each statement handles a single
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700316patch. In the example ``build.scc`` file, there are five patch statements
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500317for the five patches in the directory.
318
319You can create a typical ``.patch`` file using ``diff -Nurp`` or
320``git format-patch`` commands. For information on how to create patches,
Andrew Geissler09209ee2020-12-13 08:44:15 -0600321see the ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
322and ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500323sections.
324
325Features
326--------
327
328Features are complex kernel Metadata types that consist of configuration
329fragments, patches, and possibly other feature description files. As an
Andrew Geisslerc926e172021-05-07 16:11:35 -0500330example, consider the following generic listing::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500331
332 features/myfeature.scc
333 define KFEATURE_DESCRIPTION "Enable myfeature"
334
335 patch 0001-myfeature-core.patch
336 patch 0002-myfeature-interface.patch
337
338 include cfg/myfeature_dependency.scc
339 kconf non-hardware myfeature.cfg
340
341This example shows how the ``patch`` and ``kconf`` commands are used as well
342as how an additional feature description file is included with the
343``include`` command.
344
345Typically, features are less granular than configuration fragments and
346are more likely than configuration fragments and patches to be the types
Andrew Geissler09036742021-06-25 14:25:14 -0500347of things you want to specify in the :term:`KERNEL_FEATURES` variable of the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500348Linux kernel recipe. See the
349":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
350in the manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500351
352Kernel Types
353------------
354
355A kernel type defines a high-level kernel policy by aggregating
356non-hardware configuration fragments with patches you want to use when
357building a Linux kernel of a specific type (e.g. a real-time kernel).
358Syntactically, kernel types are no different than features as described
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500359in the ":ref:`kernel-dev/advanced:features`" section. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500360:term:`LINUX_KERNEL_TYPE`
361variable in the kernel recipe selects the kernel type. For example, in
362the ``linux-yocto_4.12.bb`` kernel recipe found in
363``poky/meta/recipes-kernel/linux``, a
Andrew Geissler09209ee2020-12-13 08:44:15 -0600364:ref:`require <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directive
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500365includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500366which has the following statement that defines the default kernel type::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500367
368 LINUX_KERNEL_TYPE ??= "standard"
369
370Another example would be the real-time kernel (i.e.
371``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500372type as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500373
374 LINUX_KERNEL_TYPE = "preempt-rt"
375
376.. note::
377
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500378 You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
Andrew Geissler09209ee2020-12-13 08:44:15 -0600379 of the :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500380 (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600381 ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500382 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500383
384Three kernel types ("standard", "tiny", and "preempt-rt") are supported
385for Linux Yocto kernels:
386
387- "standard": Includes the generic Linux kernel policy of the Yocto
388 Project linux-yocto kernel recipes. This policy includes, among other
389 things, which file systems, networking options, core kernel features,
390 and debugging and tracing options are supported.
391
392- "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
393 configuration options required to build a real-time Linux kernel.
394 This kernel type inherits from the "standard" kernel type.
395
396- "tiny": Defines a bare minimum configuration meant to serve as a base
397 for very small Linux kernels. The "tiny" kernel type is independent
398 from the "standard" configuration. Although the "tiny" kernel type
399 does not currently include any source changes, it might in the
400 future.
401
402For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
403``standard.scc``). Here is a partial listing for the ``standard.scc``
404file, which is found in the ``ktypes/standard`` directory of the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500405``yocto-kernel-cache`` Git repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500406
407 # Include this kernel type fragment to get the standard features and
408 # configuration values.
409
410 # Note: if only the features are desired, but not the configuration
411 # then this should be included as:
412 # include ktypes/standard/standard.scc nocfg
413 # if no chained configuration is desired, include it as:
414 # include ktypes/standard/standard.scc nocfg inherit
415
416
417
418 include ktypes/base/base.scc
419 branch standard
420
421 kconf non-hardware standard.cfg
422
423 include features/kgdb/kgdb.scc
424 .
425 .
426 .
427
428 include cfg/net/ip6_nf.scc
429 include cfg/net/bridge.scc
430
431 include cfg/systemd.scc
432
433 include features/rfkill/rfkill.scc
434
435As with any ``.scc`` file, a kernel type definition can aggregate other
436``.scc`` files with ``include`` commands. These definitions can also
437directly pull in configuration fragments and patches with the ``kconf``
438and ``patch`` commands, respectively.
439
440.. note::
441
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500442 It is not strictly necessary to create a kernel type ``.scc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500443 file. The Board Support Package (BSP) file can implicitly define the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500444 kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600445 ":ref:`kernel-dev/advanced:bsp descriptions`" section for more
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500446 information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500447
448BSP Descriptions
449----------------
450
451BSP descriptions (i.e. ``*.scc`` files) combine kernel types with
452hardware-specific features. The hardware-specific Metadata is typically
453defined independently in the BSP layer, and then aggregated with each
454supported kernel type.
455
456.. note::
457
458 For BSPs supported by the Yocto Project, the BSP description files
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500459 are located in the ``bsp`` directory of the ``yocto-kernel-cache``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500460 repository organized under the "Yocto Linux Kernel" heading in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600461 :yocto_git:`Yocto Project Source Repositories <>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500462
463This section overviews the BSP description structure, the aggregation
464concepts, and presents a detailed example using a BSP supported by the
465Yocto Project (i.e. BeagleBone Board). For complete information on BSP
Andrew Geissler09209ee2020-12-13 08:44:15 -0600466layer file hierarchy, see the :doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500467
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500468Description Overview
469~~~~~~~~~~~~~~~~~~~~
470
471For simplicity, consider the following root BSP layer description files
472for the BeagleBone board. These files employ both a structure and naming
473convention for consistency. The naming convention for the file is as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500474follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500475
476 bsp_root_name-kernel_type.scc
477
478Here are some example root layer
479BSP filenames for the BeagleBone Board BSP, which is supported by the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500480Yocto Project::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500481
482 beaglebone-standard.scc
483 beaglebone-preempt-rt.scc
484
485Each file uses the root name (i.e "beaglebone") BSP name followed by the
486kernel type.
487
Andrew Geisslerc926e172021-05-07 16:11:35 -0500488Examine the ``beaglebone-standard.scc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500489
490 define KMACHINE beaglebone
491 define KTYPE standard
492 define KARCH arm
493
494 include ktypes/standard/standard.scc
495 branch beaglebone
496
497 include beaglebone.scc
498
499 # default policy for standard kernels
500 include features/latencytop/latencytop.scc
501 include features/profiling/profiling.scc
502
503Every top-level BSP description file
504should define the :term:`KMACHINE`,
505:term:`KTYPE`, and
506:term:`KARCH` variables. These
507variables allow the OpenEmbedded build system to identify the
508description as meeting the criteria set by the recipe being built. This
509example supports the "beaglebone" machine for the "standard" kernel and
510the "arm" architecture.
511
Andrew Geissler09036742021-06-25 14:25:14 -0500512Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700513type description file. Thus, if you do not have the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500514kernel type defined in your kernel Metadata as it is here, you only need
515to ensure that the
516:term:`LINUX_KERNEL_TYPE`
Andrew Geissler09036742021-06-25 14:25:14 -0500517variable in the kernel recipe and the :term:`KTYPE` variable in the BSP
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500518description file match.
519
520To separate your kernel policy from your hardware configuration, you
521include a kernel type (``ktype``), such as "standard". In the previous
Andrew Geisslerc926e172021-05-07 16:11:35 -0500522example, this is done using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500523
524 include ktypes/standard/standard.scc
525
526This file aggregates all the configuration
527fragments, patches, and features that make up your standard kernel
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500528policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500529information.
530
531To aggregate common configurations and features specific to the kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500532for `mybsp`, use the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500533
534 include mybsp.scc
535
Andrew Geisslerc926e172021-05-07 16:11:35 -0500536You can see that in the BeagleBone example with the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500537
538 include beaglebone.scc
539
540For information on how to break a complete ``.config`` file into the various
Andrew Geissler09209ee2020-12-13 08:44:15 -0600541configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500542
543Finally, if you have any configurations specific to the hardware that
Andrew Geisslerc926e172021-05-07 16:11:35 -0500544are not in a ``*.scc`` file, you can include them as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500545
546 kconf hardware mybsp-extra.cfg
547
548The BeagleBone example does not include these
549types of configurations. However, the Malta 32-bit board does
Andrew Geisslerc926e172021-05-07 16:11:35 -0500550("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500551
552 define KMACHINE mti-malta32-le
553 define KMACHINE qemumipsel
554 define KTYPE standard
555 define KARCH mips
556
557 include ktypes/standard/standard.scc
558 branch mti-malta32
559
560 include mti-malta32.scc
561 kconf hardware mti-malta32-le.cfg
562
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500563Example
564~~~~~~~
565
566Many real-world examples are more complex. Like any other ``.scc`` file,
567BSP descriptions can aggregate features. Consider the Minnow BSP
568definition given the ``linux-yocto-4.4`` branch of the
569``yocto-kernel-cache`` (i.e.
570``yocto-kernel-cache/bsp/minnow/minnow.scc``):
571
572.. note::
573
574 Although the Minnow Board BSP is unused, the Metadata remains and is
575 being used here just as an example.
576
577::
578
579 include cfg/x86.scc
580 include features/eg20t/eg20t.scc
581 include cfg/dmaengine.scc
582 include features/power/intel.scc
583 include cfg/efi.scc
584 include features/usb/ehci-hcd.scc
585 include features/usb/ohci-hcd.scc
586 include features/usb/usb-gadgets.scc
587 include features/usb/touchscreen-composite.scc
588 include cfg/timer/hpet.scc
589 include features/leds/leds.scc
590 include features/spi/spidev.scc
591 include features/i2c/i2cdev.scc
592 include features/mei/mei-txe.scc
593
594 # Earlyprintk and port debug requires 8250
595 kconf hardware cfg/8250.cfg
596
597 kconf hardware minnow.cfg
598 kconf hardware minnow-dev.cfg
599
600The ``minnow.scc`` description file includes a hardware configuration
601fragment (``minnow.cfg``) specific to the Minnow BSP as well as several
602more general configuration fragments and features enabling hardware
603found on the machine. This ``minnow.scc`` description file is then
604included in each of the three "minnow" description files for the
605supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
606Consider the "minnow" description for the "standard" kernel type (i.e.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500607``minnow-standard.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500608
609 define KMACHINE minnow
610 define KTYPE standard
611 define KARCH i386
612
613 include ktypes/standard
614
615 include minnow.scc
616
617 # Extra minnow configs above the minimal defined in minnow.scc
618 include cfg/efi-ext.scc
619 include features/media/media-all.scc
620 include features/sound/snd_hda_intel.scc
621
622 # The following should really be in standard.scc
623 # USB live-image support
624 include cfg/usb-mass-storage.scc
625 include cfg/boot-live.scc
626
627 # Basic profiling
628 include features/latencytop/latencytop.scc
629 include features/profiling/profiling.scc
630
631 # Requested drivers that don't have an existing scc
632 kconf hardware minnow-drivers-extra.cfg
633
634The ``include`` command midway through the file includes the ``minnow.scc`` description
635that defines all enabled hardware for the BSP that is common to all
636kernel types. Using this command significantly reduces duplication.
637
638Now consider the "minnow" description for the "tiny" kernel type (i.e.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500639``minnow-tiny.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500640
641 define KMACHINE minnow
642 define KTYPE tiny
643 define KARCH i386
644
645 include ktypes/tiny
646
647 include minnow.scc
648
649As you might expect,
650the "tiny" description includes quite a bit less. In fact, it includes
651only the minimal policy defined by the "tiny" kernel type and the
652hardware-specific configuration required for booting the machine along
653with the most basic functionality of the system as defined in the base
654"minnow" description file.
655
656Notice again the three critical variables:
657:term:`KMACHINE`,
658:term:`KTYPE`, and
659:term:`KARCH`. Of these variables, only
Andrew Geissler09036742021-06-25 14:25:14 -0500660:term:`KTYPE` has changed to specify the "tiny" kernel type.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500661
662Kernel Metadata Location
663========================
664
665Kernel Metadata always exists outside of the kernel tree either defined
666in a kernel recipe (recipe-space) or outside of the recipe. Where you
667choose to define the Metadata depends on what you want to do and how you
668intend to work. Regardless of where you define the kernel Metadata, the
669syntax used applies equally.
670
671If you are unfamiliar with the Linux kernel and only wish to apply a
672configuration and possibly a couple of patches provided to you by
673others, the recipe-space method is recommended. This method is also a
674good approach if you are working with Linux kernel sources you do not
675control or if you just do not want to maintain a Linux kernel Git
676repository on your own. For partial information on how you can define
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500677kernel Metadata in the recipe-space, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600678":ref:`kernel-dev/common:modifying an existing recipe`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500679
680Conversely, if you are actively developing a kernel and are already
681maintaining a Linux kernel Git repository of your own, you might find it
682more convenient to work with kernel Metadata kept outside the
683recipe-space. Working with Metadata in this area can make iterative
684development of the Linux kernel more efficient outside of the BitBake
685environment.
686
687Recipe-Space Metadata
688---------------------
689
690When stored in recipe-space, the kernel Metadata files reside in a
Andrew Geissler595f6302022-01-24 19:11:47 +0000691directory hierarchy below :term:`FILESEXTRAPATHS`. For
692a linux-yocto recipe or for a Linux kernel recipe derived by copying
693:oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
694</openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`
695into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500696``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600697See the ":ref:`kernel-dev/common:modifying an existing recipe`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500698section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500699
700Here is an example that shows a trivial tree of kernel Metadata stored
Andrew Geisslerc926e172021-05-07 16:11:35 -0500701in recipe-space within a BSP layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500702
703 meta-my_bsp_layer/
704 `-- recipes-kernel
705 `-- linux
706 `-- linux-yocto
707 |-- bsp-standard.scc
708 |-- bsp.cfg
709 `-- standard.cfg
710
711When the Metadata is stored in recipe-space, you must take steps to
712ensure BitBake has the necessary information to decide what files to
713fetch and when they need to be fetched again. It is only necessary to
714specify the ``.scc`` files on the
715:term:`SRC_URI`. BitBake parses them
716and fetches any files referenced in the ``.scc`` files by the
717``include``, ``patch``, or ``kconf`` commands. Because of this, it is
718necessary to bump the recipe :term:`PR`
719value when changing the content of files not explicitly listed in the
Andrew Geissler09036742021-06-25 14:25:14 -0500720:term:`SRC_URI`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500721
722If the BSP description is in recipe space, you cannot simply list the
Andrew Geissler09036742021-06-25 14:25:14 -0500723``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500724form from your kernel append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500725
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500726 SRC_URI:append:myplatform = " \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500727 file://myplatform;type=kmeta;destsuffix=myplatform \
728 "
729
730Metadata Outside the Recipe-Space
731---------------------------------
732
733When stored outside of the recipe-space, the kernel Metadata files
734reside in a separate repository. The OpenEmbedded build system adds the
735Metadata to the build as a "type=kmeta" repository through the
736:term:`SRC_URI` variable. As an
Andrew Geissler09036742021-06-25 14:25:14 -0500737example, consider the following :term:`SRC_URI` statement from the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500738``linux-yocto_4.12.bb`` kernel recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500739
740 SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
741 git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
742
743
744``${KMETA}``, in this context, is simply used to name the directory into
745which the Git fetcher places the Metadata. This behavior is no different
Andrew Geissler09036742021-06-25 14:25:14 -0500746than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500747see the previous section).
748
749You can keep kernel Metadata in a "kernel-cache", which is a directory
750containing configuration fragments. As with any Metadata kept outside
Andrew Geissler09036742021-06-25 14:25:14 -0500751the recipe-space, you simply need to use the :term:`SRC_URI` statement with
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500752the "type=kmeta" attribute. Doing so makes the kernel Metadata available
753during the configuration phase.
754
Andrew Geissler09036742021-06-25 14:25:14 -0500755If you modify the Metadata, you must not forget to update the :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500756statements in the kernel's recipe. In particular, you need to update the
757``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
758wish to use. Changing the data in these branches and not updating the
Andrew Geissler09036742021-06-25 14:25:14 -0500759:term:`SRCREV` statements to match will cause the build to fetch an older
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500760commit.
761
762Organizing Your Source
763======================
764
765Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
Andrew Geissler595f6302022-01-24 19:11:47 +0000766kernel sources that have only a single branch. This type of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500767repository structure is fine for linear development supporting a single
768machine and architecture. However, if you work with multiple boards and
769architectures, a kernel source repository with multiple branches is more
770efficient. For example, suppose you need a series of patches for one
771board to boot. Sometimes, these patches are works-in-progress or
772fundamentally wrong, yet they are still necessary for specific boards.
773In these situations, you most likely do not want to include these
774patches in every kernel you build (i.e. have the patches as part of the
Andrew Geissler595f6302022-01-24 19:11:47 +0000775default branch). It is situations like these that give rise to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500776multiple branches used within a Linux kernel sources Git repository.
777
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700778Here are repository organization strategies maximizing source reuse,
779removing redundancy, and logically ordering your changes. This section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500780presents strategies for the following cases:
781
782- Encapsulating patches in a feature description and only including the
783 patches in the BSP descriptions of the applicable boards.
784
785- Creating a machine branch in your kernel source repository and
786 applying the patches on that branch only.
787
788- Creating a feature branch in your kernel source repository and
789 merging that branch into your BSP when needed.
790
791The approach you take is entirely up to you and depends on what works
792best for your development model.
793
794Encapsulating Patches
795---------------------
796
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500797If you are reusing patches from an external tree and are not working on
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500798the patches, you might find the encapsulated feature to be appropriate.
799Given this scenario, you do not need to create any branches in the
800source repository. Rather, you just take the static patches you need and
801encapsulate them within a feature description. Once you have the feature
802description, you simply include that into the BSP description as
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500803described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500804
805You can find information on how to create patches and BSP descriptions
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500806in the ":ref:`kernel-dev/advanced:patches`" and
807":ref:`kernel-dev/advanced:bsp descriptions`" sections.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500808
809Machine Branches
810----------------
811
812When you have multiple machines and architectures to support, or you are
813actively working on board support, it is more efficient to create
814branches in the repository based on individual machines. Having machine
Andrew Geissler595f6302022-01-24 19:11:47 +0000815branches allows common source to remain in the development branch with any
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500816features specific to a machine stored in the appropriate machine branch.
817This organization method frees you from continually reintegrating your
818patches into a feature.
819
820Once you have a new branch, you can set up your kernel Metadata to use
821the branch a couple different ways. In the recipe, you can specify the
Andrew Geissler09036742021-06-25 14:25:14 -0500822new branch as the :term:`KBRANCH` to use for the board as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500823
824 KBRANCH = "mynewbranch"
825
826Another method is to use the ``branch`` command in the BSP
Andrew Geisslerc926e172021-05-07 16:11:35 -0500827description::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500828
829 mybsp.scc:
830 define KMACHINE mybsp
831 define KTYPE standard
832 define KARCH i386
833 include standard.scc
834
835 branch mynewbranch
836
837 include mybsp-hw.scc
838
839If you find yourself with numerous branches, you might consider using a
840hierarchical branching system similar to what the Yocto Linux Kernel Git
Andrew Geisslerc926e172021-05-07 16:11:35 -0500841repositories use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500842
843 common/kernel_type/machine
844
845If you had two kernel types, "standard" and "small" for instance, three
846machines, and common as ``mydir``, the branches in your Git repository
Andrew Geisslerc926e172021-05-07 16:11:35 -0500847might look like this::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500848
849 mydir/base
850 mydir/standard/base
851 mydir/standard/machine_a
852 mydir/standard/machine_b
853 mydir/standard/machine_c
854 mydir/small/base
855 mydir/small/machine_a
856
857This organization can help clarify the branch relationships. In this
858case, ``mydir/standard/machine_a`` includes everything in ``mydir/base``
859and ``mydir/standard/base``. The "standard" and "small" branches add
860sources specific to those kernel types that for whatever reason are not
861appropriate for the other branches.
862
863.. note::
864
865 The "base" branches are an artifact of the way Git manages its data
866 internally on the filesystem: Git will not allow you to use
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500867 ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to
868 create a file and a directory named "standard".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500869
870Feature Branches
871----------------
872
873When you are actively developing new features, it can be more efficient
874to work with that feature as a branch, rather than as a set of patches
875that have to be regularly updated. The Yocto Project Linux kernel tools
876provide for this with the ``git merge`` command.
877
878To merge a feature branch into a BSP, insert the ``git merge`` command
Andrew Geisslerc926e172021-05-07 16:11:35 -0500879after any ``branch`` commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500880
881 mybsp.scc:
882 define KMACHINE mybsp
883 define KTYPE standard
884 define KARCH i386
885 include standard.scc
886
887 branch mynewbranch
888 git merge myfeature
889
890 include mybsp-hw.scc
891
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500892SCC Description File Reference
893==============================
894
895This section provides a brief reference for the commands you can use
896within an SCC description file (``.scc``):
897
898- ``branch [ref]``: Creates a new branch relative to the current branch
899 (typically ``${KTYPE}``) using the currently checked-out branch, or
900 "ref" if specified.
901
902- ``define``: Defines variables, such as
903 :term:`KMACHINE`,
904 :term:`KTYPE`,
905 :term:`KARCH`, and
906 :term:`KFEATURE_DESCRIPTION`.
907
908- ``include SCC_FILE``: Includes an SCC file in the current file. The
909 file is parsed as if you had inserted it inline.
910
911- ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration
912 fragment for merging into the final Linux ``.config`` file.
913
914- ``git merge GIT_BRANCH``: Merges the feature branch into the current
915 branch.
916
917- ``patch PATCH_FILE``: Applies the patch to the current Git branch.
918
919