blob: bcaaaeed1426e09ce18b6398cba41c40d7594112 [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 Williamsac13d5f2023-11-24 18:59:46 -060072 KBRANCH:beaglebone-yocto = "standard/beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050073
74The linux-yocto style recipes can optionally define the following
75variables:
76
77 - :term:`KERNEL_FEATURES`
78
79 - :term:`LINUX_KERNEL_TYPE`
80
81:term:`LINUX_KERNEL_TYPE`
82defines the kernel type to be used in assembling the configuration. If
Andrew Geissler09036742021-06-25 14:25:14 -050083you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard".
84Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` defines the search
Andrew Geisslerc9f78652020-09-18 14:11:35 -050085arguments used by the kernel tools to find the appropriate description
86within the kernel Metadata with which to build out the sources and
87configuration. The linux-yocto recipes define "standard", "tiny", and
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050088"preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050089section for more information on kernel types.
90
91During the build, the kern-tools search for the BSP description file
Andrew Geissler09036742021-06-25 14:25:14 -050092that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050093variables passed in from the recipe. The tools use the first BSP
Andrew Geissler4c19ea12020-10-27 13:52:24 -050094description they find that matches both variables. If the tools cannot find
Andrew Geisslerc9f78652020-09-18 14:11:35 -050095a match, they issue a warning.
96
Andrew Geissler09036742021-06-25 14:25:14 -050097The tools first search for the :term:`KMACHINE` and then for the
98:term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they
99will use the sources from the :term:`KBRANCH` and any configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500100specified in the :term:`SRC_URI`.
101
102You can use the
103:term:`KERNEL_FEATURES`
104variable to include features (configuration fragments, patches, or both)
Andrew Geissler09036742021-06-25 14:25:14 -0500105that are not already included by the :term:`KMACHINE` and
106:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500107feature specified as "features/netfilter/netfilter.scc", specify::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108
109 KERNEL_FEATURES += "features/netfilter/netfilter.scc"
110
111To include a
112feature called "cfg/sound.scc" just for the ``qemux86`` machine,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500113specify::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500115 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500116
117The value of
Andrew Geissler09036742021-06-25 14:25:14 -0500118the entries in :term:`KERNEL_FEATURES` are dependent on their location
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500119within the kernel Metadata itself. The examples here are taken from the
120``yocto-kernel-cache`` repository. Each branch of this repository
121contains "features" and "cfg" subdirectories at the top-level. For more
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500122information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`"
123section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500124
125Kernel Metadata Syntax
126======================
127
128The kernel Metadata consists of three primary types of files: ``scc``
129[1]_ description files, configuration fragments, and patches. The
130``scc`` files define variables and include or otherwise reference any of
131the three file types. The description files are used to aggregate all
132types of kernel Metadata into what ultimately describes the sources and
133the configuration required to build a Linux kernel tailored to a
134specific machine.
135
136The ``scc`` description files are used to define two fundamental types
137of kernel Metadata:
138
139- Features
140
141- Board Support Packages (BSPs)
142
143Features aggregate sources in the form of patches and configuration
144fragments into a modular reusable unit. You can use features to
145implement conceptually separate kernel Metadata descriptions such as
146pure configuration fragments, simple patches, complex features, and
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500147kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500148features and policy to be reused in the BSPs.
149
150BSPs define hardware-specific features and aggregate them with kernel
151types to form the final description of what will be assembled and built.
152
153While the kernel Metadata syntax does not enforce any logical separation
154of configuration fragments, patches, features or kernel types, best
155practices dictate a logical separation of these types of Metadata. The
Andrew Geisslerc926e172021-05-07 16:11:35 -0500156following Metadata file hierarchy is recommended::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500157
158 base/
159 bsp/
160 cfg/
161 features/
162 ktypes/
163 patches/
164
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500165The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`.
166The remaining directories all contain "features". Separating ``bsp`` from the
167rest of the structure aids conceptualizing intended usage.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500168
169Use these guidelines to help place your ``scc`` description files within
170the structure:
171
172- If your file contains only configuration fragments, place the file in
173 the ``cfg`` directory.
174
175- If your file contains only source-code fixes, place the file in the
176 ``patches`` directory.
177
178- If your file encapsulates a major feature, often combining sources
179 and configurations, place the file in ``features`` directory.
180
181- If your file aggregates non-hardware configuration and patches in
182 order to define a base kernel policy or major kernel type to be
183 reused across multiple BSPs, place the file in ``ktypes`` directory.
184
Andrew Geissler615f2f12022-07-15 14:00:58 -0500185These distinctions can easily become blurred --- especially as out-of-tree
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500186features slowly merge upstream over time. Also, remember that how the
187description files are placed is a purely logical organization and has no
188impact on the functionality of the kernel Metadata. There is no impact
189because all of ``cfg``, ``features``, ``patches``, and ``ktypes``,
190contain "features" as far as the kernel tools are concerned.
191
192Paths used in kernel Metadata files are relative to base, which is
193either
194:term:`FILESEXTRAPATHS` if
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500195you are creating Metadata in
196:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197or the top level of
Andrew Geissler09209ee2020-12-13 08:44:15 -0600198:yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500199if you are creating
200:ref:`kernel-dev/advanced:metadata outside the recipe-space`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500201
202.. [1]
203 ``scc`` stands for Series Configuration Control, but the naming has
204 less significance in the current implementation of the tooling than
205 it had in the past. Consider ``scc`` files to be description files.
206
207Configuration
208-------------
209
210The simplest unit of kernel Metadata is the configuration-only feature.
211This feature consists of one or more Linux kernel configuration
212parameters in a configuration fragment file (``.cfg``) and a ``.scc``
213file that describes the fragment.
214
215As an example, consider the Symmetric Multi-Processing (SMP) fragment
216used with the ``linux-yocto-4.12`` kernel as defined outside of the
217recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
218two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
219``cfg`` directory of the ``yocto-4.12`` branch in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500220``yocto-kernel-cache`` Git repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221
222 cfg/smp.scc:
223 define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
224 define KFEATURE_COMPATIBILITY all
225
226 kconf hardware smp.cfg
227
228 cfg/smp.cfg:
229 CONFIG_SMP=y
230 CONFIG_SCHED_SMT=y
231 # Increase default NR_CPUS from 8 to 64 so that platform with
232 # more than 8 processors can be all activated at boot time
233 CONFIG_NR_CPUS=64
234 # The following is needed when setting NR_CPUS to something
235 # greater than 8 on x86 architectures, it should be automatically
236 # disregarded by Kconfig when using a different arch
237 CONFIG_X86_BIGSMP=y
238
239You can find general information on configuration
Andrew Geissler09209ee2020-12-13 08:44:15 -0600240fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500241
242Within the ``smp.scc`` file, the
243:term:`KFEATURE_DESCRIPTION`
244statement provides a short description of the fragment. Higher level
245kernel tools use this description.
246
247Also within the ``smp.scc`` file, the ``kconf`` command includes the
248actual configuration fragment in an ``.scc`` file, and the "hardware"
249keyword identifies the fragment as being hardware enabling, as opposed
250to general policy, which would use the "non-hardware" keyword. The
251distinction is made for the benefit of the configuration validation
252tools, which warn you if a hardware fragment overrides a policy set by a
253non-hardware fragment.
254
255.. note::
256
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500257 The description file can include multiple ``kconf`` statements, one per
258 fragment.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500259
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500260As described in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600261":ref:`kernel-dev/common:validating configuration`" section, you can
Andrew Geisslerc926e172021-05-07 16:11:35 -0500262use the following BitBake command to audit your configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500263
264 $ bitbake linux-yocto -c kernel_configcheck -f
265
266Patches
267-------
268
269Patch descriptions are very similar to configuration fragment
270descriptions, which are described in the previous section. However,
271instead of a ``.cfg`` file, these descriptions work with source patches
272(i.e. ``.patch`` files).
273
274A typical patch includes a description file and the patch itself. As an
275example, consider the build patches used with the ``linux-yocto-4.12``
276kernel as defined outside of the recipe space (i.e.
277``yocto-kernel-cache``). This Metadata consists of several files:
278``build.scc`` and a set of ``*.patch`` files. You can find these files
279in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
280``yocto-kernel-cache`` Git repository.
281
282The following listings show the ``build.scc`` file and part of the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500283``modpost-mask-trivial-warnings.patch`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500284
285 patches/build/build.scc:
286 patch arm-serialize-build-targets.patch
287 patch powerpc-serialize-image-targets.patch
288 patch kbuild-exclude-meta-directory-from-distclean-processi.patch
289
290 # applied by kgit
291 # patch kbuild-add-meta-files-to-the-ignore-li.patch
292
293 patch modpost-mask-trivial-warnings.patch
294 patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
295
296 patches/build/modpost-mask-trivial-warnings.patch:
297 From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
298 From: Paul Gortmaker <paul.gortmaker@windriver.com>
299 Date: Sun, 25 Jan 2009 17:58:09 -0500
300 Subject: [PATCH] modpost: mask trivial warnings
301
302 Newer HOSTCC will complain about various stdio fcns because
303 .
304 .
305 .
306 char *dump_write = NULL, *files_source = NULL;
307 int opt;
308 --
309 2.10.1
310
311 generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
312
313The description file can
314include multiple patch statements where each statement handles a single
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700315patch. In the example ``build.scc`` file, there are five patch statements
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500316for the five patches in the directory.
317
318You can create a typical ``.patch`` file using ``diff -Nurp`` or
319``git format-patch`` commands. For information on how to create patches,
Andrew Geissler09209ee2020-12-13 08:44:15 -0600320see the ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
321and ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500322sections.
323
324Features
325--------
326
327Features are complex kernel Metadata types that consist of configuration
328fragments, patches, and possibly other feature description files. As an
Andrew Geisslerc926e172021-05-07 16:11:35 -0500329example, consider the following generic listing::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500330
331 features/myfeature.scc
332 define KFEATURE_DESCRIPTION "Enable myfeature"
333
334 patch 0001-myfeature-core.patch
335 patch 0002-myfeature-interface.patch
336
337 include cfg/myfeature_dependency.scc
338 kconf non-hardware myfeature.cfg
339
340This example shows how the ``patch`` and ``kconf`` commands are used as well
341as how an additional feature description file is included with the
342``include`` command.
343
344Typically, features are less granular than configuration fragments and
345are more likely than configuration fragments and patches to be the types
Andrew Geissler09036742021-06-25 14:25:14 -0500346of things you want to specify in the :term:`KERNEL_FEATURES` variable of the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500347Linux kernel recipe. See the
348":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
349in the manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500350
351Kernel Types
352------------
353
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500354A kernel type defines a high-level kernel policy by aggregating non-hardware
355configuration fragments with patches you want to use when building a Linux
356kernel of a specific type (e.g. a real-time kernel). Syntactically, kernel
357types are no different than features as described in the
358":ref:`kernel-dev/advanced:features`" section. The :term:`LINUX_KERNEL_TYPE`
359variable in the kernel recipe selects the kernel type. For example, in the
360``linux-yocto_4.12.bb`` kernel recipe found in ``poky/meta/recipes-kernel/linux``, a
361:ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
362directive includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500363which has the following statement that defines the default kernel type::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500364
365 LINUX_KERNEL_TYPE ??= "standard"
366
367Another example would be the real-time kernel (i.e.
368``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500369type as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500370
371 LINUX_KERNEL_TYPE = "preempt-rt"
372
373.. note::
374
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500375 You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
Andrew Geissler09209ee2020-12-13 08:44:15 -0600376 of the :ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500377 (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600378 ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500379 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500380
381Three kernel types ("standard", "tiny", and "preempt-rt") are supported
382for Linux Yocto kernels:
383
384- "standard": Includes the generic Linux kernel policy of the Yocto
385 Project linux-yocto kernel recipes. This policy includes, among other
386 things, which file systems, networking options, core kernel features,
387 and debugging and tracing options are supported.
388
389- "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
390 configuration options required to build a real-time Linux kernel.
391 This kernel type inherits from the "standard" kernel type.
392
393- "tiny": Defines a bare minimum configuration meant to serve as a base
394 for very small Linux kernels. The "tiny" kernel type is independent
395 from the "standard" configuration. Although the "tiny" kernel type
396 does not currently include any source changes, it might in the
397 future.
398
399For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
400``standard.scc``). Here is a partial listing for the ``standard.scc``
401file, which is found in the ``ktypes/standard`` directory of the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500402``yocto-kernel-cache`` Git repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500403
404 # Include this kernel type fragment to get the standard features and
405 # configuration values.
406
407 # Note: if only the features are desired, but not the configuration
408 # then this should be included as:
409 # include ktypes/standard/standard.scc nocfg
410 # if no chained configuration is desired, include it as:
411 # include ktypes/standard/standard.scc nocfg inherit
412
413
414
415 include ktypes/base/base.scc
416 branch standard
417
418 kconf non-hardware standard.cfg
419
420 include features/kgdb/kgdb.scc
421 .
422 .
423 .
424
425 include cfg/net/ip6_nf.scc
426 include cfg/net/bridge.scc
427
428 include cfg/systemd.scc
429
430 include features/rfkill/rfkill.scc
431
432As with any ``.scc`` file, a kernel type definition can aggregate other
433``.scc`` files with ``include`` commands. These definitions can also
434directly pull in configuration fragments and patches with the ``kconf``
435and ``patch`` commands, respectively.
436
437.. note::
438
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500439 It is not strictly necessary to create a kernel type ``.scc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500440 file. The Board Support Package (BSP) file can implicitly define the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500441 kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600442 ":ref:`kernel-dev/advanced:bsp descriptions`" section for more
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500443 information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500444
445BSP Descriptions
446----------------
447
448BSP descriptions (i.e. ``*.scc`` files) combine kernel types with
449hardware-specific features. The hardware-specific Metadata is typically
450defined independently in the BSP layer, and then aggregated with each
451supported kernel type.
452
453.. note::
454
455 For BSPs supported by the Yocto Project, the BSP description files
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500456 are located in the ``bsp`` directory of the ``yocto-kernel-cache``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500457 repository organized under the "Yocto Linux Kernel" heading in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600458 :yocto_git:`Yocto Project Source Repositories <>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500459
460This section overviews the BSP description structure, the aggregation
461concepts, and presents a detailed example using a BSP supported by the
462Yocto Project (i.e. BeagleBone Board). For complete information on BSP
Andrew Geissler09209ee2020-12-13 08:44:15 -0600463layer file hierarchy, see the :doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500464
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500465Description Overview
466~~~~~~~~~~~~~~~~~~~~
467
468For simplicity, consider the following root BSP layer description files
469for the BeagleBone board. These files employ both a structure and naming
470convention for consistency. The naming convention for the file is as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500471follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500472
473 bsp_root_name-kernel_type.scc
474
475Here are some example root layer
476BSP filenames for the BeagleBone Board BSP, which is supported by the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500477Yocto Project::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500478
479 beaglebone-standard.scc
480 beaglebone-preempt-rt.scc
481
482Each file uses the root name (i.e "beaglebone") BSP name followed by the
483kernel type.
484
Andrew Geisslerc926e172021-05-07 16:11:35 -0500485Examine the ``beaglebone-standard.scc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500486
487 define KMACHINE beaglebone
488 define KTYPE standard
489 define KARCH arm
490
491 include ktypes/standard/standard.scc
492 branch beaglebone
493
494 include beaglebone.scc
495
496 # default policy for standard kernels
497 include features/latencytop/latencytop.scc
498 include features/profiling/profiling.scc
499
500Every top-level BSP description file
501should define the :term:`KMACHINE`,
502:term:`KTYPE`, and
503:term:`KARCH` variables. These
504variables allow the OpenEmbedded build system to identify the
505description as meeting the criteria set by the recipe being built. This
506example supports the "beaglebone" machine for the "standard" kernel and
507the "arm" architecture.
508
Andrew Geissler09036742021-06-25 14:25:14 -0500509Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700510type description file. Thus, if you do not have the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500511kernel type defined in your kernel Metadata as it is here, you only need
512to ensure that the
513:term:`LINUX_KERNEL_TYPE`
Andrew Geissler09036742021-06-25 14:25:14 -0500514variable in the kernel recipe and the :term:`KTYPE` variable in the BSP
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500515description file match.
516
517To separate your kernel policy from your hardware configuration, you
518include a kernel type (``ktype``), such as "standard". In the previous
Andrew Geisslerc926e172021-05-07 16:11:35 -0500519example, this is done using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500520
521 include ktypes/standard/standard.scc
522
523This file aggregates all the configuration
524fragments, patches, and features that make up your standard kernel
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500525policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500526information.
527
528To aggregate common configurations and features specific to the kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -0500529for `mybsp`, use the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500530
531 include mybsp.scc
532
Andrew Geisslerc926e172021-05-07 16:11:35 -0500533You can see that in the BeagleBone example with the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500534
535 include beaglebone.scc
536
537For information on how to break a complete ``.config`` file into the various
Andrew Geissler09209ee2020-12-13 08:44:15 -0600538configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500539
540Finally, if you have any configurations specific to the hardware that
Andrew Geisslerc926e172021-05-07 16:11:35 -0500541are not in a ``*.scc`` file, you can include them as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500542
543 kconf hardware mybsp-extra.cfg
544
545The BeagleBone example does not include these
546types of configurations. However, the Malta 32-bit board does
Andrew Geisslerc926e172021-05-07 16:11:35 -0500547("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500548
549 define KMACHINE mti-malta32-le
550 define KMACHINE qemumipsel
551 define KTYPE standard
552 define KARCH mips
553
554 include ktypes/standard/standard.scc
555 branch mti-malta32
556
557 include mti-malta32.scc
558 kconf hardware mti-malta32-le.cfg
559
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500560Example
561~~~~~~~
562
563Many real-world examples are more complex. Like any other ``.scc`` file,
564BSP descriptions can aggregate features. Consider the Minnow BSP
565definition given the ``linux-yocto-4.4`` branch of the
Andrew Geissler517393d2023-01-13 08:55:19 -0600566``yocto-kernel-cache`` (i.e. ``yocto-kernel-cache/bsp/minnow/minnow.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500567
568 include cfg/x86.scc
569 include features/eg20t/eg20t.scc
570 include cfg/dmaengine.scc
571 include features/power/intel.scc
572 include cfg/efi.scc
573 include features/usb/ehci-hcd.scc
574 include features/usb/ohci-hcd.scc
575 include features/usb/usb-gadgets.scc
576 include features/usb/touchscreen-composite.scc
577 include cfg/timer/hpet.scc
578 include features/leds/leds.scc
579 include features/spi/spidev.scc
580 include features/i2c/i2cdev.scc
581 include features/mei/mei-txe.scc
582
583 # Earlyprintk and port debug requires 8250
584 kconf hardware cfg/8250.cfg
585
586 kconf hardware minnow.cfg
587 kconf hardware minnow-dev.cfg
588
Andrew Geissler517393d2023-01-13 08:55:19 -0600589.. note::
590
591 Although the Minnow Board BSP is unused, the Metadata remains and is
592 being used here just as an example.
593
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500594The ``minnow.scc`` description file includes a hardware configuration
595fragment (``minnow.cfg``) specific to the Minnow BSP as well as several
596more general configuration fragments and features enabling hardware
597found on the machine. This ``minnow.scc`` description file is then
598included in each of the three "minnow" description files for the
599supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
600Consider the "minnow" description for the "standard" kernel type (i.e.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500601``minnow-standard.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500602
603 define KMACHINE minnow
604 define KTYPE standard
605 define KARCH i386
606
607 include ktypes/standard
608
609 include minnow.scc
610
611 # Extra minnow configs above the minimal defined in minnow.scc
612 include cfg/efi-ext.scc
613 include features/media/media-all.scc
614 include features/sound/snd_hda_intel.scc
615
616 # The following should really be in standard.scc
617 # USB live-image support
618 include cfg/usb-mass-storage.scc
619 include cfg/boot-live.scc
620
621 # Basic profiling
622 include features/latencytop/latencytop.scc
623 include features/profiling/profiling.scc
624
625 # Requested drivers that don't have an existing scc
626 kconf hardware minnow-drivers-extra.cfg
627
628The ``include`` command midway through the file includes the ``minnow.scc`` description
629that defines all enabled hardware for the BSP that is common to all
630kernel types. Using this command significantly reduces duplication.
631
632Now consider the "minnow" description for the "tiny" kernel type (i.e.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500633``minnow-tiny.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500634
635 define KMACHINE minnow
636 define KTYPE tiny
637 define KARCH i386
638
639 include ktypes/tiny
640
641 include minnow.scc
642
643As you might expect,
644the "tiny" description includes quite a bit less. In fact, it includes
645only the minimal policy defined by the "tiny" kernel type and the
646hardware-specific configuration required for booting the machine along
647with the most basic functionality of the system as defined in the base
648"minnow" description file.
649
650Notice again the three critical variables:
651:term:`KMACHINE`,
652:term:`KTYPE`, and
653:term:`KARCH`. Of these variables, only
Andrew Geissler09036742021-06-25 14:25:14 -0500654:term:`KTYPE` has changed to specify the "tiny" kernel type.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500655
656Kernel Metadata Location
657========================
658
659Kernel Metadata always exists outside of the kernel tree either defined
660in a kernel recipe (recipe-space) or outside of the recipe. Where you
661choose to define the Metadata depends on what you want to do and how you
662intend to work. Regardless of where you define the kernel Metadata, the
663syntax used applies equally.
664
665If you are unfamiliar with the Linux kernel and only wish to apply a
666configuration and possibly a couple of patches provided to you by
667others, the recipe-space method is recommended. This method is also a
668good approach if you are working with Linux kernel sources you do not
669control or if you just do not want to maintain a Linux kernel Git
670repository on your own. For partial information on how you can define
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500671kernel Metadata in the recipe-space, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600672":ref:`kernel-dev/common:modifying an existing recipe`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500673
674Conversely, if you are actively developing a kernel and are already
675maintaining a Linux kernel Git repository of your own, you might find it
676more convenient to work with kernel Metadata kept outside the
677recipe-space. Working with Metadata in this area can make iterative
678development of the Linux kernel more efficient outside of the BitBake
679environment.
680
681Recipe-Space Metadata
682---------------------
683
684When stored in recipe-space, the kernel Metadata files reside in a
Andrew Geissler595f6302022-01-24 19:11:47 +0000685directory hierarchy below :term:`FILESEXTRAPATHS`. For
686a linux-yocto recipe or for a Linux kernel recipe derived by copying
687:oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
688</openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`
689into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500690``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600691See the ":ref:`kernel-dev/common:modifying an existing recipe`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500692section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500693
694Here is an example that shows a trivial tree of kernel Metadata stored
Andrew Geisslerc926e172021-05-07 16:11:35 -0500695in recipe-space within a BSP layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500696
697 meta-my_bsp_layer/
698 `-- recipes-kernel
699 `-- linux
700 `-- linux-yocto
701 |-- bsp-standard.scc
702 |-- bsp.cfg
703 `-- standard.cfg
704
705When the Metadata is stored in recipe-space, you must take steps to
706ensure BitBake has the necessary information to decide what files to
707fetch and when they need to be fetched again. It is only necessary to
708specify the ``.scc`` files on the
709:term:`SRC_URI`. BitBake parses them
710and fetches any files referenced in the ``.scc`` files by the
711``include``, ``patch``, or ``kconf`` commands. Because of this, it is
712necessary to bump the recipe :term:`PR`
713value when changing the content of files not explicitly listed in the
Andrew Geissler09036742021-06-25 14:25:14 -0500714:term:`SRC_URI`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500715
716If the BSP description is in recipe space, you cannot simply list the
Andrew Geissler09036742021-06-25 14:25:14 -0500717``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500718form from your kernel append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500719
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500720 SRC_URI:append:myplatform = " \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500721 file://myplatform;type=kmeta;destsuffix=myplatform \
722 "
723
724Metadata Outside the Recipe-Space
725---------------------------------
726
727When stored outside of the recipe-space, the kernel Metadata files
728reside in a separate repository. The OpenEmbedded build system adds the
729Metadata to the build as a "type=kmeta" repository through the
730:term:`SRC_URI` variable. As an
Andrew Geissler09036742021-06-25 14:25:14 -0500731example, consider the following :term:`SRC_URI` statement from the
Patrick Williamsb542dec2023-06-09 01:26:37 -0500732``linux-yocto_5.15.bb`` kernel recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500733
Patrick Williamsb542dec2023-06-09 01:26:37 -0500734 SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \
735 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 -0500736
737``${KMETA}``, in this context, is simply used to name the directory into
738which the Git fetcher places the Metadata. This behavior is no different
Andrew Geissler09036742021-06-25 14:25:14 -0500739than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500740see the previous section).
741
742You can keep kernel Metadata in a "kernel-cache", which is a directory
743containing configuration fragments. As with any Metadata kept outside
Andrew Geissler09036742021-06-25 14:25:14 -0500744the recipe-space, you simply need to use the :term:`SRC_URI` statement with
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500745the "type=kmeta" attribute. Doing so makes the kernel Metadata available
746during the configuration phase.
747
Andrew Geissler09036742021-06-25 14:25:14 -0500748If you modify the Metadata, you must not forget to update the :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500749statements in the kernel's recipe. In particular, you need to update the
750``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
751wish to use. Changing the data in these branches and not updating the
Andrew Geissler09036742021-06-25 14:25:14 -0500752:term:`SRCREV` statements to match will cause the build to fetch an older
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500753commit.
754
755Organizing Your Source
756======================
757
758Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
Andrew Geissler595f6302022-01-24 19:11:47 +0000759kernel sources that have only a single branch. This type of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500760repository structure is fine for linear development supporting a single
761machine and architecture. However, if you work with multiple boards and
762architectures, a kernel source repository with multiple branches is more
763efficient. For example, suppose you need a series of patches for one
764board to boot. Sometimes, these patches are works-in-progress or
765fundamentally wrong, yet they are still necessary for specific boards.
766In these situations, you most likely do not want to include these
767patches in every kernel you build (i.e. have the patches as part of the
Andrew Geissler595f6302022-01-24 19:11:47 +0000768default branch). It is situations like these that give rise to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500769multiple branches used within a Linux kernel sources Git repository.
770
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700771Here are repository organization strategies maximizing source reuse,
772removing redundancy, and logically ordering your changes. This section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500773presents strategies for the following cases:
774
775- Encapsulating patches in a feature description and only including the
776 patches in the BSP descriptions of the applicable boards.
777
778- Creating a machine branch in your kernel source repository and
779 applying the patches on that branch only.
780
781- Creating a feature branch in your kernel source repository and
782 merging that branch into your BSP when needed.
783
784The approach you take is entirely up to you and depends on what works
785best for your development model.
786
787Encapsulating Patches
788---------------------
789
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500790If you are reusing patches from an external tree and are not working on
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500791the patches, you might find the encapsulated feature to be appropriate.
792Given this scenario, you do not need to create any branches in the
793source repository. Rather, you just take the static patches you need and
794encapsulate them within a feature description. Once you have the feature
795description, you simply include that into the BSP description as
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500796described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500797
798You can find information on how to create patches and BSP descriptions
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500799in the ":ref:`kernel-dev/advanced:patches`" and
800":ref:`kernel-dev/advanced:bsp descriptions`" sections.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500801
802Machine Branches
803----------------
804
805When you have multiple machines and architectures to support, or you are
806actively working on board support, it is more efficient to create
807branches in the repository based on individual machines. Having machine
Andrew Geissler595f6302022-01-24 19:11:47 +0000808branches allows common source to remain in the development branch with any
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500809features specific to a machine stored in the appropriate machine branch.
810This organization method frees you from continually reintegrating your
811patches into a feature.
812
813Once you have a new branch, you can set up your kernel Metadata to use
814the branch a couple different ways. In the recipe, you can specify the
Andrew Geissler09036742021-06-25 14:25:14 -0500815new branch as the :term:`KBRANCH` to use for the board as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500816
817 KBRANCH = "mynewbranch"
818
819Another method is to use the ``branch`` command in the BSP
Andrew Geisslerc926e172021-05-07 16:11:35 -0500820description::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500821
822 mybsp.scc:
823 define KMACHINE mybsp
824 define KTYPE standard
825 define KARCH i386
826 include standard.scc
827
828 branch mynewbranch
829
830 include mybsp-hw.scc
831
832If you find yourself with numerous branches, you might consider using a
833hierarchical branching system similar to what the Yocto Linux Kernel Git
Andrew Geisslerc926e172021-05-07 16:11:35 -0500834repositories use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500835
836 common/kernel_type/machine
837
838If you had two kernel types, "standard" and "small" for instance, three
839machines, and common as ``mydir``, the branches in your Git repository
Andrew Geisslerc926e172021-05-07 16:11:35 -0500840might look like this::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500841
842 mydir/base
843 mydir/standard/base
844 mydir/standard/machine_a
845 mydir/standard/machine_b
846 mydir/standard/machine_c
847 mydir/small/base
848 mydir/small/machine_a
849
850This organization can help clarify the branch relationships. In this
851case, ``mydir/standard/machine_a`` includes everything in ``mydir/base``
852and ``mydir/standard/base``. The "standard" and "small" branches add
853sources specific to those kernel types that for whatever reason are not
854appropriate for the other branches.
855
856.. note::
857
858 The "base" branches are an artifact of the way Git manages its data
859 internally on the filesystem: Git will not allow you to use
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500860 ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to
861 create a file and a directory named "standard".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500862
863Feature Branches
864----------------
865
866When you are actively developing new features, it can be more efficient
867to work with that feature as a branch, rather than as a set of patches
868that have to be regularly updated. The Yocto Project Linux kernel tools
869provide for this with the ``git merge`` command.
870
871To merge a feature branch into a BSP, insert the ``git merge`` command
Andrew Geisslerc926e172021-05-07 16:11:35 -0500872after any ``branch`` commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500873
874 mybsp.scc:
875 define KMACHINE mybsp
876 define KTYPE standard
877 define KARCH i386
878 include standard.scc
879
880 branch mynewbranch
881 git merge myfeature
882
883 include mybsp-hw.scc
884
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500885SCC Description File Reference
886==============================
887
888This section provides a brief reference for the commands you can use
889within an SCC description file (``.scc``):
890
891- ``branch [ref]``: Creates a new branch relative to the current branch
892 (typically ``${KTYPE}``) using the currently checked-out branch, or
893 "ref" if specified.
894
895- ``define``: Defines variables, such as
896 :term:`KMACHINE`,
897 :term:`KTYPE`,
898 :term:`KARCH`, and
899 :term:`KFEATURE_DESCRIPTION`.
900
901- ``include SCC_FILE``: Includes an SCC file in the current file. The
902 file is parsed as if you had inserted it inline.
903
904- ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration
905 fragment for merging into the final Linux ``.config`` file.
906
907- ``git merge GIT_BRANCH``: Merges the feature branch into the current
908 branch.
909
910- ``patch PATCH_FILE``: Applies the patch to the current Git branch.
911
912