blob: 355326de6e3f3cc39bdaf5ba1fb2e068d2fef63a [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
Andrew Geissler615f2f12022-07-15 14:00:58 -0500186These distinctions can easily become blurred --- especially as out-of-tree
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187features 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
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500355A kernel type defines a high-level kernel policy by aggregating non-hardware
356configuration fragments with patches you want to use when building a Linux
357kernel of a specific type (e.g. a real-time kernel). Syntactically, kernel
358types are no different than features as described in the
359":ref:`kernel-dev/advanced:features`" section. The :term:`LINUX_KERNEL_TYPE`
360variable in the kernel recipe selects the kernel type. For example, in the
361``linux-yocto_4.12.bb`` kernel recipe found in ``poky/meta/recipes-kernel/linux``, a
362:ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
363directive includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500364which has the following statement that defines the default kernel type::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500365
366 LINUX_KERNEL_TYPE ??= "standard"
367
368Another example would be the real-time kernel (i.e.
369``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500370type as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500371
372 LINUX_KERNEL_TYPE = "preempt-rt"
373
374.. note::
375
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500376 You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
Andrew Geissler09209ee2020-12-13 08:44:15 -0600377 of the :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500378 (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600379 ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500380 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500381
382Three kernel types ("standard", "tiny", and "preempt-rt") are supported
383for Linux Yocto kernels:
384
385- "standard": Includes the generic Linux kernel policy of the Yocto
386 Project linux-yocto kernel recipes. This policy includes, among other
387 things, which file systems, networking options, core kernel features,
388 and debugging and tracing options are supported.
389
390- "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
391 configuration options required to build a real-time Linux kernel.
392 This kernel type inherits from the "standard" kernel type.
393
394- "tiny": Defines a bare minimum configuration meant to serve as a base
395 for very small Linux kernels. The "tiny" kernel type is independent
396 from the "standard" configuration. Although the "tiny" kernel type
397 does not currently include any source changes, it might in the
398 future.
399
400For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
401``standard.scc``). Here is a partial listing for the ``standard.scc``
402file, which is found in the ``ktypes/standard`` directory of the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500403``yocto-kernel-cache`` Git repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500404
405 # Include this kernel type fragment to get the standard features and
406 # configuration values.
407
408 # Note: if only the features are desired, but not the configuration
409 # then this should be included as:
410 # include ktypes/standard/standard.scc nocfg
411 # if no chained configuration is desired, include it as:
412 # include ktypes/standard/standard.scc nocfg inherit
413
414
415
416 include ktypes/base/base.scc
417 branch standard
418
419 kconf non-hardware standard.cfg
420
421 include features/kgdb/kgdb.scc
422 .
423 .
424 .
425
426 include cfg/net/ip6_nf.scc
427 include cfg/net/bridge.scc
428
429 include cfg/systemd.scc
430
431 include features/rfkill/rfkill.scc
432
433As with any ``.scc`` file, a kernel type definition can aggregate other
434``.scc`` files with ``include`` commands. These definitions can also
435directly pull in configuration fragments and patches with the ``kconf``
436and ``patch`` commands, respectively.
437
438.. note::
439
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500440 It is not strictly necessary to create a kernel type ``.scc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500441 file. The Board Support Package (BSP) file can implicitly define the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500442 kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600443 ":ref:`kernel-dev/advanced:bsp descriptions`" section for more
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500444 information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445
446BSP Descriptions
447----------------
448
449BSP descriptions (i.e. ``*.scc`` files) combine kernel types with
450hardware-specific features. The hardware-specific Metadata is typically
451defined independently in the BSP layer, and then aggregated with each
452supported kernel type.
453
454.. note::
455
456 For BSPs supported by the Yocto Project, the BSP description files
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500457 are located in the ``bsp`` directory of the ``yocto-kernel-cache``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500458 repository organized under the "Yocto Linux Kernel" heading in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600459 :yocto_git:`Yocto Project Source Repositories <>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500460
461This section overviews the BSP description structure, the aggregation
462concepts, and presents a detailed example using a BSP supported by the
463Yocto Project (i.e. BeagleBone Board). For complete information on BSP
Andrew Geissler09209ee2020-12-13 08:44:15 -0600464layer file hierarchy, see the :doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500465
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500466Description Overview
467~~~~~~~~~~~~~~~~~~~~
468
469For simplicity, consider the following root BSP layer description files
470for the BeagleBone board. These files employ both a structure and naming
471convention for consistency. The naming convention for the file is as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500472follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473
474 bsp_root_name-kernel_type.scc
475
476Here are some example root layer
477BSP filenames for the BeagleBone Board BSP, which is supported by the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500478Yocto Project::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500479
480 beaglebone-standard.scc
481 beaglebone-preempt-rt.scc
482
483Each file uses the root name (i.e "beaglebone") BSP name followed by the
484kernel type.
485
Andrew Geisslerc926e172021-05-07 16:11:35 -0500486Examine the ``beaglebone-standard.scc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500487
488 define KMACHINE beaglebone
489 define KTYPE standard
490 define KARCH arm
491
492 include ktypes/standard/standard.scc
493 branch beaglebone
494
495 include beaglebone.scc
496
497 # default policy for standard kernels
498 include features/latencytop/latencytop.scc
499 include features/profiling/profiling.scc
500
501Every top-level BSP description file
502should define the :term:`KMACHINE`,
503:term:`KTYPE`, and
504:term:`KARCH` variables. These
505variables allow the OpenEmbedded build system to identify the
506description as meeting the criteria set by the recipe being built. This
507example supports the "beaglebone" machine for the "standard" kernel and
508the "arm" architecture.
509
Andrew Geissler09036742021-06-25 14:25:14 -0500510Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700511type description file. Thus, if you do not have the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500512kernel type defined in your kernel Metadata as it is here, you only need
513to ensure that the
514:term:`LINUX_KERNEL_TYPE`
Andrew Geissler09036742021-06-25 14:25:14 -0500515variable in the kernel recipe and the :term:`KTYPE` variable in the BSP
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500516description file match.
517
518To separate your kernel policy from your hardware configuration, you
519include a kernel type (``ktype``), such as "standard". In the previous
Andrew Geisslerc926e172021-05-07 16:11:35 -0500520example, this is done using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500521
522 include ktypes/standard/standard.scc
523
524This file aggregates all the configuration
525fragments, patches, and features that make up your standard kernel
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500526policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500527information.
528
529To aggregate common configurations and features specific to the kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500530for `mybsp`, use the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500531
532 include mybsp.scc
533
Andrew Geisslerc926e172021-05-07 16:11:35 -0500534You can see that in the BeagleBone example with the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500535
536 include beaglebone.scc
537
538For information on how to break a complete ``.config`` file into the various
Andrew Geissler09209ee2020-12-13 08:44:15 -0600539configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500540
541Finally, if you have any configurations specific to the hardware that
Andrew Geisslerc926e172021-05-07 16:11:35 -0500542are not in a ``*.scc`` file, you can include them as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500543
544 kconf hardware mybsp-extra.cfg
545
546The BeagleBone example does not include these
547types of configurations. However, the Malta 32-bit board does
Andrew Geisslerc926e172021-05-07 16:11:35 -0500548("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500549
550 define KMACHINE mti-malta32-le
551 define KMACHINE qemumipsel
552 define KTYPE standard
553 define KARCH mips
554
555 include ktypes/standard/standard.scc
556 branch mti-malta32
557
558 include mti-malta32.scc
559 kconf hardware mti-malta32-le.cfg
560
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500561Example
562~~~~~~~
563
564Many real-world examples are more complex. Like any other ``.scc`` file,
565BSP descriptions can aggregate features. Consider the Minnow BSP
566definition given the ``linux-yocto-4.4`` branch of the
Andrew Geissler517393d2023-01-13 08:55:19 -0600567``yocto-kernel-cache`` (i.e. ``yocto-kernel-cache/bsp/minnow/minnow.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500568
569 include cfg/x86.scc
570 include features/eg20t/eg20t.scc
571 include cfg/dmaengine.scc
572 include features/power/intel.scc
573 include cfg/efi.scc
574 include features/usb/ehci-hcd.scc
575 include features/usb/ohci-hcd.scc
576 include features/usb/usb-gadgets.scc
577 include features/usb/touchscreen-composite.scc
578 include cfg/timer/hpet.scc
579 include features/leds/leds.scc
580 include features/spi/spidev.scc
581 include features/i2c/i2cdev.scc
582 include features/mei/mei-txe.scc
583
584 # Earlyprintk and port debug requires 8250
585 kconf hardware cfg/8250.cfg
586
587 kconf hardware minnow.cfg
588 kconf hardware minnow-dev.cfg
589
Andrew Geissler517393d2023-01-13 08:55:19 -0600590.. note::
591
592 Although the Minnow Board BSP is unused, the Metadata remains and is
593 being used here just as an example.
594
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500595The ``minnow.scc`` description file includes a hardware configuration
596fragment (``minnow.cfg``) specific to the Minnow BSP as well as several
597more general configuration fragments and features enabling hardware
598found on the machine. This ``minnow.scc`` description file is then
599included in each of the three "minnow" description files for the
600supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
601Consider the "minnow" description for the "standard" kernel type (i.e.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500602``minnow-standard.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500603
604 define KMACHINE minnow
605 define KTYPE standard
606 define KARCH i386
607
608 include ktypes/standard
609
610 include minnow.scc
611
612 # Extra minnow configs above the minimal defined in minnow.scc
613 include cfg/efi-ext.scc
614 include features/media/media-all.scc
615 include features/sound/snd_hda_intel.scc
616
617 # The following should really be in standard.scc
618 # USB live-image support
619 include cfg/usb-mass-storage.scc
620 include cfg/boot-live.scc
621
622 # Basic profiling
623 include features/latencytop/latencytop.scc
624 include features/profiling/profiling.scc
625
626 # Requested drivers that don't have an existing scc
627 kconf hardware minnow-drivers-extra.cfg
628
629The ``include`` command midway through the file includes the ``minnow.scc`` description
630that defines all enabled hardware for the BSP that is common to all
631kernel types. Using this command significantly reduces duplication.
632
633Now consider the "minnow" description for the "tiny" kernel type (i.e.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500634``minnow-tiny.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500635
636 define KMACHINE minnow
637 define KTYPE tiny
638 define KARCH i386
639
640 include ktypes/tiny
641
642 include minnow.scc
643
644As you might expect,
645the "tiny" description includes quite a bit less. In fact, it includes
646only the minimal policy defined by the "tiny" kernel type and the
647hardware-specific configuration required for booting the machine along
648with the most basic functionality of the system as defined in the base
649"minnow" description file.
650
651Notice again the three critical variables:
652:term:`KMACHINE`,
653:term:`KTYPE`, and
654:term:`KARCH`. Of these variables, only
Andrew Geissler09036742021-06-25 14:25:14 -0500655:term:`KTYPE` has changed to specify the "tiny" kernel type.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500656
657Kernel Metadata Location
658========================
659
660Kernel Metadata always exists outside of the kernel tree either defined
661in a kernel recipe (recipe-space) or outside of the recipe. Where you
662choose to define the Metadata depends on what you want to do and how you
663intend to work. Regardless of where you define the kernel Metadata, the
664syntax used applies equally.
665
666If you are unfamiliar with the Linux kernel and only wish to apply a
667configuration and possibly a couple of patches provided to you by
668others, the recipe-space method is recommended. This method is also a
669good approach if you are working with Linux kernel sources you do not
670control or if you just do not want to maintain a Linux kernel Git
671repository on your own. For partial information on how you can define
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500672kernel Metadata in the recipe-space, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600673":ref:`kernel-dev/common:modifying an existing recipe`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500674
675Conversely, if you are actively developing a kernel and are already
676maintaining a Linux kernel Git repository of your own, you might find it
677more convenient to work with kernel Metadata kept outside the
678recipe-space. Working with Metadata in this area can make iterative
679development of the Linux kernel more efficient outside of the BitBake
680environment.
681
682Recipe-Space Metadata
683---------------------
684
685When stored in recipe-space, the kernel Metadata files reside in a
Andrew Geissler595f6302022-01-24 19:11:47 +0000686directory hierarchy below :term:`FILESEXTRAPATHS`. For
687a linux-yocto recipe or for a Linux kernel recipe derived by copying
688:oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
689</openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`
690into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500691``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600692See the ":ref:`kernel-dev/common:modifying an existing recipe`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500693section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500694
695Here is an example that shows a trivial tree of kernel Metadata stored
Andrew Geisslerc926e172021-05-07 16:11:35 -0500696in recipe-space within a BSP layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500697
698 meta-my_bsp_layer/
699 `-- recipes-kernel
700 `-- linux
701 `-- linux-yocto
702 |-- bsp-standard.scc
703 |-- bsp.cfg
704 `-- standard.cfg
705
706When the Metadata is stored in recipe-space, you must take steps to
707ensure BitBake has the necessary information to decide what files to
708fetch and when they need to be fetched again. It is only necessary to
709specify the ``.scc`` files on the
710:term:`SRC_URI`. BitBake parses them
711and fetches any files referenced in the ``.scc`` files by the
712``include``, ``patch``, or ``kconf`` commands. Because of this, it is
713necessary to bump the recipe :term:`PR`
714value when changing the content of files not explicitly listed in the
Andrew Geissler09036742021-06-25 14:25:14 -0500715:term:`SRC_URI`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500716
717If the BSP description is in recipe space, you cannot simply list the
Andrew Geissler09036742021-06-25 14:25:14 -0500718``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500719form from your kernel append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500720
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500721 SRC_URI:append:myplatform = " \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500722 file://myplatform;type=kmeta;destsuffix=myplatform \
723 "
724
725Metadata Outside the Recipe-Space
726---------------------------------
727
728When stored outside of the recipe-space, the kernel Metadata files
729reside in a separate repository. The OpenEmbedded build system adds the
730Metadata to the build as a "type=kmeta" repository through the
731:term:`SRC_URI` variable. As an
Andrew Geissler09036742021-06-25 14:25:14 -0500732example, consider the following :term:`SRC_URI` statement from the
Patrick Williamsb542dec2023-06-09 01:26:37 -0500733``linux-yocto_5.15.bb`` kernel recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500734
Patrick Williamsb542dec2023-06-09 01:26:37 -0500735 SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \
736 git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-5.15;destsuffix=${KMETA};protocol=https"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500737
738``${KMETA}``, in this context, is simply used to name the directory into
739which the Git fetcher places the Metadata. This behavior is no different
Andrew Geissler09036742021-06-25 14:25:14 -0500740than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500741see the previous section).
742
743You can keep kernel Metadata in a "kernel-cache", which is a directory
744containing configuration fragments. As with any Metadata kept outside
Andrew Geissler09036742021-06-25 14:25:14 -0500745the recipe-space, you simply need to use the :term:`SRC_URI` statement with
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500746the "type=kmeta" attribute. Doing so makes the kernel Metadata available
747during the configuration phase.
748
Andrew Geissler09036742021-06-25 14:25:14 -0500749If you modify the Metadata, you must not forget to update the :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500750statements in the kernel's recipe. In particular, you need to update the
751``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
752wish to use. Changing the data in these branches and not updating the
Andrew Geissler09036742021-06-25 14:25:14 -0500753:term:`SRCREV` statements to match will cause the build to fetch an older
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500754commit.
755
756Organizing Your Source
757======================
758
759Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
Andrew Geissler595f6302022-01-24 19:11:47 +0000760kernel sources that have only a single branch. This type of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500761repository structure is fine for linear development supporting a single
762machine and architecture. However, if you work with multiple boards and
763architectures, a kernel source repository with multiple branches is more
764efficient. For example, suppose you need a series of patches for one
765board to boot. Sometimes, these patches are works-in-progress or
766fundamentally wrong, yet they are still necessary for specific boards.
767In these situations, you most likely do not want to include these
768patches in every kernel you build (i.e. have the patches as part of the
Andrew Geissler595f6302022-01-24 19:11:47 +0000769default branch). It is situations like these that give rise to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500770multiple branches used within a Linux kernel sources Git repository.
771
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700772Here are repository organization strategies maximizing source reuse,
773removing redundancy, and logically ordering your changes. This section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500774presents strategies for the following cases:
775
776- Encapsulating patches in a feature description and only including the
777 patches in the BSP descriptions of the applicable boards.
778
779- Creating a machine branch in your kernel source repository and
780 applying the patches on that branch only.
781
782- Creating a feature branch in your kernel source repository and
783 merging that branch into your BSP when needed.
784
785The approach you take is entirely up to you and depends on what works
786best for your development model.
787
788Encapsulating Patches
789---------------------
790
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500791If you are reusing patches from an external tree and are not working on
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500792the patches, you might find the encapsulated feature to be appropriate.
793Given this scenario, you do not need to create any branches in the
794source repository. Rather, you just take the static patches you need and
795encapsulate them within a feature description. Once you have the feature
796description, you simply include that into the BSP description as
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500797described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500798
799You can find information on how to create patches and BSP descriptions
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500800in the ":ref:`kernel-dev/advanced:patches`" and
801":ref:`kernel-dev/advanced:bsp descriptions`" sections.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500802
803Machine Branches
804----------------
805
806When you have multiple machines and architectures to support, or you are
807actively working on board support, it is more efficient to create
808branches in the repository based on individual machines. Having machine
Andrew Geissler595f6302022-01-24 19:11:47 +0000809branches allows common source to remain in the development branch with any
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500810features specific to a machine stored in the appropriate machine branch.
811This organization method frees you from continually reintegrating your
812patches into a feature.
813
814Once you have a new branch, you can set up your kernel Metadata to use
815the branch a couple different ways. In the recipe, you can specify the
Andrew Geissler09036742021-06-25 14:25:14 -0500816new branch as the :term:`KBRANCH` to use for the board as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500817
818 KBRANCH = "mynewbranch"
819
820Another method is to use the ``branch`` command in the BSP
Andrew Geisslerc926e172021-05-07 16:11:35 -0500821description::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500822
823 mybsp.scc:
824 define KMACHINE mybsp
825 define KTYPE standard
826 define KARCH i386
827 include standard.scc
828
829 branch mynewbranch
830
831 include mybsp-hw.scc
832
833If you find yourself with numerous branches, you might consider using a
834hierarchical branching system similar to what the Yocto Linux Kernel Git
Andrew Geisslerc926e172021-05-07 16:11:35 -0500835repositories use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500836
837 common/kernel_type/machine
838
839If you had two kernel types, "standard" and "small" for instance, three
840machines, and common as ``mydir``, the branches in your Git repository
Andrew Geisslerc926e172021-05-07 16:11:35 -0500841might look like this::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500842
843 mydir/base
844 mydir/standard/base
845 mydir/standard/machine_a
846 mydir/standard/machine_b
847 mydir/standard/machine_c
848 mydir/small/base
849 mydir/small/machine_a
850
851This organization can help clarify the branch relationships. In this
852case, ``mydir/standard/machine_a`` includes everything in ``mydir/base``
853and ``mydir/standard/base``. The "standard" and "small" branches add
854sources specific to those kernel types that for whatever reason are not
855appropriate for the other branches.
856
857.. note::
858
859 The "base" branches are an artifact of the way Git manages its data
860 internally on the filesystem: Git will not allow you to use
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500861 ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to
862 create a file and a directory named "standard".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500863
864Feature Branches
865----------------
866
867When you are actively developing new features, it can be more efficient
868to work with that feature as a branch, rather than as a set of patches
869that have to be regularly updated. The Yocto Project Linux kernel tools
870provide for this with the ``git merge`` command.
871
872To merge a feature branch into a BSP, insert the ``git merge`` command
Andrew Geisslerc926e172021-05-07 16:11:35 -0500873after any ``branch`` commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500874
875 mybsp.scc:
876 define KMACHINE mybsp
877 define KTYPE standard
878 define KARCH i386
879 include standard.scc
880
881 branch mynewbranch
882 git merge myfeature
883
884 include mybsp-hw.scc
885
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500886SCC Description File Reference
887==============================
888
889This section provides a brief reference for the commands you can use
890within an SCC description file (``.scc``):
891
892- ``branch [ref]``: Creates a new branch relative to the current branch
893 (typically ``${KTYPE}``) using the currently checked-out branch, or
894 "ref" if specified.
895
896- ``define``: Defines variables, such as
897 :term:`KMACHINE`,
898 :term:`KTYPE`,
899 :term:`KARCH`, and
900 :term:`KFEATURE_DESCRIPTION`.
901
902- ``include SCC_FILE``: Includes an SCC file in the current file. The
903 file is parsed as if you had inserted it inline.
904
905- ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration
906 fragment for merging into the final Linux ``.config`` file.
907
908- ``git merge GIT_BRANCH``: Merges the feature branch into the current
909 branch.
910
911- ``patch PATCH_FILE``: Applies the patch to the current Git branch.
912
913