Complete Yocto mirror with license table for TQMa6UL (2038-compliance)
- 264 license table entries with exact download URLs (224/264 resolved) - Complete sources/ directory with all BitBake recipes - Build configuration: tqma6ul-multi-mba6ulx, spaetzle (musl) - Full traceability for Softwarefreigabeantrag - GCC 13.4.0, Linux 6.6.102, U-Boot 2023.04, musl 1.2.4 - License distribution: GPL-2.0 (24), MIT (23), GPL-2.0+ (18), BSD-3 (16)
This commit is contained in:
Siggi (OpenClaw Agent)
912
sources/poky/documentation/kernel-dev/advanced.rst
Normal file
912
sources/poky/documentation/kernel-dev/advanced.rst
Normal file
@@ -0,0 +1,912 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
|
||||
|
||||
*******************************************************
|
||||
Working with Advanced Metadata (``yocto-kernel-cache``)
|
||||
*******************************************************
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
In addition to supporting configuration fragments and patches, the Yocto
|
||||
Project kernel tools also support rich
|
||||
:term:`Metadata` that you can use to define
|
||||
complex policies and Board Support Package (BSP) support. The purpose of
|
||||
the Metadata and the tools that manage it is to help you manage the
|
||||
complexity of the configuration and sources used to support multiple
|
||||
BSPs and Linux kernel types.
|
||||
|
||||
Kernel Metadata exists in many places. One area in the
|
||||
:ref:`overview-manual/development-environment:yocto project source repositories`
|
||||
is the ``yocto-kernel-cache`` Git repository. You can find this repository
|
||||
grouped under the "Yocto Linux Kernel" heading in the
|
||||
:yocto_git:`Yocto Project Source Repositories <>`.
|
||||
|
||||
Kernel development tools ("kern-tools") are also available in the Yocto Project
|
||||
Source Repositories under the "Yocto Linux Kernel" heading in the
|
||||
``yocto-kernel-tools`` Git repository. The recipe that builds these
|
||||
tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in
|
||||
the :term:`Source Directory` (e.g.
|
||||
``poky``).
|
||||
|
||||
Using Kernel Metadata in a Recipe
|
||||
=================================
|
||||
|
||||
As mentioned in the introduction, the Yocto Project contains kernel
|
||||
Metadata, which is located in the ``yocto-kernel-cache`` Git repository.
|
||||
This Metadata defines Board Support Packages (BSPs) that correspond to
|
||||
definitions in linux-yocto recipes for corresponding BSPs. A BSP
|
||||
consists of an aggregation of kernel policy and enabled
|
||||
hardware-specific features. The BSP can be influenced from within the
|
||||
linux-yocto recipe.
|
||||
|
||||
.. note::
|
||||
|
||||
A Linux kernel recipe that contains kernel Metadata (e.g. inherits
|
||||
from the ``linux-yocto.inc`` file) is said to be a "linux-yocto style" recipe.
|
||||
|
||||
Every linux-yocto style recipe must define the
|
||||
:term:`KMACHINE` variable. This
|
||||
variable is typically set to the same value as the :term:`MACHINE` variable,
|
||||
which is used by :term:`BitBake`.
|
||||
However, in some cases, the variable might instead refer to the
|
||||
underlying platform of the :term:`MACHINE`.
|
||||
|
||||
Multiple BSPs can reuse the same :term:`KMACHINE` name if they are built
|
||||
using the same BSP description. Multiple Corei7-based BSPs could share
|
||||
the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to
|
||||
realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE`
|
||||
is the machine type within a BSP Layer. Even with this distinction,
|
||||
however, these two variables can hold the same value. See the
|
||||
":ref:`kernel-dev/advanced:bsp descriptions`" section for more information.
|
||||
|
||||
Every linux-yocto style recipe must also indicate the Linux kernel
|
||||
source repository branch used to build the Linux kernel. The
|
||||
:term:`KBRANCH` variable must be set
|
||||
to indicate the branch.
|
||||
|
||||
.. note::
|
||||
|
||||
You can use the :term:`KBRANCH` value to define an alternate branch typically
|
||||
with a machine override as shown here from the ``meta-yocto-bsp`` layer::
|
||||
|
||||
KBRANCH:beaglebone-yocto = "standard/beaglebone"
|
||||
|
||||
The linux-yocto style recipes can optionally define the following
|
||||
variables:
|
||||
|
||||
- :term:`KERNEL_FEATURES`
|
||||
|
||||
- :term:`LINUX_KERNEL_TYPE`
|
||||
|
||||
:term:`LINUX_KERNEL_TYPE`
|
||||
defines the kernel type to be used in assembling the configuration. If
|
||||
you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard".
|
||||
Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` defines the search
|
||||
arguments used by the kernel tools to find the appropriate description
|
||||
within the kernel Metadata with which to build out the sources and
|
||||
configuration. The linux-yocto recipes define "standard", "tiny", and
|
||||
"preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
|
||||
section for more information on kernel types.
|
||||
|
||||
During the build, the kern-tools search for the BSP description file
|
||||
that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE`
|
||||
variables passed in from the recipe. The tools use the first BSP
|
||||
description they find that matches both variables. If the tools cannot find
|
||||
a match, they issue a warning.
|
||||
|
||||
The tools first search for the :term:`KMACHINE` and then for the
|
||||
:term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they
|
||||
will use the sources from the :term:`KBRANCH` and any configuration
|
||||
specified in the :term:`SRC_URI`.
|
||||
|
||||
You can use the
|
||||
:term:`KERNEL_FEATURES`
|
||||
variable to include features (configuration fragments, patches, or both)
|
||||
that are not already included by the :term:`KMACHINE` and
|
||||
:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a
|
||||
feature specified as "features/netfilter/netfilter.scc", specify::
|
||||
|
||||
KERNEL_FEATURES += "features/netfilter/netfilter.scc"
|
||||
|
||||
To include a
|
||||
feature called "cfg/sound.scc" just for the ``qemux86`` machine,
|
||||
specify::
|
||||
|
||||
KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc"
|
||||
|
||||
The value of
|
||||
the entries in :term:`KERNEL_FEATURES` are dependent on their location
|
||||
within the kernel Metadata itself. The examples here are taken from the
|
||||
``yocto-kernel-cache`` repository. Each branch of this repository
|
||||
contains "features" and "cfg" subdirectories at the top-level. For more
|
||||
information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`"
|
||||
section.
|
||||
|
||||
Kernel Metadata Syntax
|
||||
======================
|
||||
|
||||
The kernel Metadata consists of three primary types of files: ``scc``
|
||||
[1]_ description files, configuration fragments, and patches. The
|
||||
``scc`` files define variables and include or otherwise reference any of
|
||||
the three file types. The description files are used to aggregate all
|
||||
types of kernel Metadata into what ultimately describes the sources and
|
||||
the configuration required to build a Linux kernel tailored to a
|
||||
specific machine.
|
||||
|
||||
The ``scc`` description files are used to define two fundamental types
|
||||
of kernel Metadata:
|
||||
|
||||
- Features
|
||||
|
||||
- Board Support Packages (BSPs)
|
||||
|
||||
Features aggregate sources in the form of patches and configuration
|
||||
fragments into a modular reusable unit. You can use features to
|
||||
implement conceptually separate kernel Metadata descriptions such as
|
||||
pure configuration fragments, simple patches, complex features, and
|
||||
kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel
|
||||
features and policy to be reused in the BSPs.
|
||||
|
||||
BSPs define hardware-specific features and aggregate them with kernel
|
||||
types to form the final description of what will be assembled and built.
|
||||
|
||||
While the kernel Metadata syntax does not enforce any logical separation
|
||||
of configuration fragments, patches, features or kernel types, best
|
||||
practices dictate a logical separation of these types of Metadata. The
|
||||
following Metadata file hierarchy is recommended::
|
||||
|
||||
base/
|
||||
bsp/
|
||||
cfg/
|
||||
features/
|
||||
ktypes/
|
||||
patches/
|
||||
|
||||
The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`.
|
||||
The remaining directories all contain "features". Separating ``bsp`` from the
|
||||
rest of the structure aids conceptualizing intended usage.
|
||||
|
||||
Use these guidelines to help place your ``scc`` description files within
|
||||
the structure:
|
||||
|
||||
- If your file contains only configuration fragments, place the file in
|
||||
the ``cfg`` directory.
|
||||
|
||||
- If your file contains only source-code fixes, place the file in the
|
||||
``patches`` directory.
|
||||
|
||||
- If your file encapsulates a major feature, often combining sources
|
||||
and configurations, place the file in ``features`` directory.
|
||||
|
||||
- If your file aggregates non-hardware configuration and patches in
|
||||
order to define a base kernel policy or major kernel type to be
|
||||
reused across multiple BSPs, place the file in ``ktypes`` directory.
|
||||
|
||||
These distinctions can easily become blurred --- especially as out-of-tree
|
||||
features slowly merge upstream over time. Also, remember that how the
|
||||
description files are placed is a purely logical organization and has no
|
||||
impact on the functionality of the kernel Metadata. There is no impact
|
||||
because all of ``cfg``, ``features``, ``patches``, and ``ktypes``,
|
||||
contain "features" as far as the kernel tools are concerned.
|
||||
|
||||
Paths used in kernel Metadata files are relative to base, which is
|
||||
either
|
||||
:term:`FILESEXTRAPATHS` if
|
||||
you are creating Metadata in
|
||||
:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`,
|
||||
or the top level of
|
||||
:yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>`
|
||||
if you are creating
|
||||
:ref:`kernel-dev/advanced:metadata outside the recipe-space`.
|
||||
|
||||
.. [1]
|
||||
``scc`` stands for Series Configuration Control, but the naming has
|
||||
less significance in the current implementation of the tooling than
|
||||
it had in the past. Consider ``scc`` files to be description files.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
The simplest unit of kernel Metadata is the configuration-only feature.
|
||||
This feature consists of one or more Linux kernel configuration
|
||||
parameters in a configuration fragment file (``.cfg``) and a ``.scc``
|
||||
file that describes the fragment.
|
||||
|
||||
As an example, consider the Symmetric Multi-Processing (SMP) fragment
|
||||
used with the ``linux-yocto-4.12`` kernel as defined outside of the
|
||||
recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
|
||||
two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
|
||||
``cfg`` directory of the ``yocto-4.12`` branch in the
|
||||
``yocto-kernel-cache`` Git repository::
|
||||
|
||||
cfg/smp.scc:
|
||||
define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
|
||||
define KFEATURE_COMPATIBILITY all
|
||||
|
||||
kconf hardware smp.cfg
|
||||
|
||||
cfg/smp.cfg:
|
||||
CONFIG_SMP=y
|
||||
CONFIG_SCHED_SMT=y
|
||||
# Increase default NR_CPUS from 8 to 64 so that platform with
|
||||
# more than 8 processors can be all activated at boot time
|
||||
CONFIG_NR_CPUS=64
|
||||
# The following is needed when setting NR_CPUS to something
|
||||
# greater than 8 on x86 architectures, it should be automatically
|
||||
# disregarded by Kconfig when using a different arch
|
||||
CONFIG_X86_BIGSMP=y
|
||||
|
||||
You can find general information on configuration
|
||||
fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
|
||||
|
||||
Within the ``smp.scc`` file, the
|
||||
:term:`KFEATURE_DESCRIPTION`
|
||||
statement provides a short description of the fragment. Higher level
|
||||
kernel tools use this description.
|
||||
|
||||
Also within the ``smp.scc`` file, the ``kconf`` command includes the
|
||||
actual configuration fragment in an ``.scc`` file, and the "hardware"
|
||||
keyword identifies the fragment as being hardware enabling, as opposed
|
||||
to general policy, which would use the "non-hardware" keyword. The
|
||||
distinction is made for the benefit of the configuration validation
|
||||
tools, which warn you if a hardware fragment overrides a policy set by a
|
||||
non-hardware fragment.
|
||||
|
||||
.. note::
|
||||
|
||||
The description file can include multiple ``kconf`` statements, one per
|
||||
fragment.
|
||||
|
||||
As described in the
|
||||
":ref:`kernel-dev/common:validating configuration`" section, you can
|
||||
use the following BitBake command to audit your configuration::
|
||||
|
||||
$ bitbake linux-yocto -c kernel_configcheck -f
|
||||
|
||||
Patches
|
||||
-------
|
||||
|
||||
Patch descriptions are very similar to configuration fragment
|
||||
descriptions, which are described in the previous section. However,
|
||||
instead of a ``.cfg`` file, these descriptions work with source patches
|
||||
(i.e. ``.patch`` files).
|
||||
|
||||
A typical patch includes a description file and the patch itself. As an
|
||||
example, consider the build patches used with the ``linux-yocto-4.12``
|
||||
kernel as defined outside of the recipe space (i.e.
|
||||
``yocto-kernel-cache``). This Metadata consists of several files:
|
||||
``build.scc`` and a set of ``*.patch`` files. You can find these files
|
||||
in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
|
||||
``yocto-kernel-cache`` Git repository.
|
||||
|
||||
The following listings show the ``build.scc`` file and part of the
|
||||
``modpost-mask-trivial-warnings.patch`` file::
|
||||
|
||||
patches/build/build.scc:
|
||||
patch arm-serialize-build-targets.patch
|
||||
patch powerpc-serialize-image-targets.patch
|
||||
patch kbuild-exclude-meta-directory-from-distclean-processi.patch
|
||||
|
||||
# applied by kgit
|
||||
# patch kbuild-add-meta-files-to-the-ignore-li.patch
|
||||
|
||||
patch modpost-mask-trivial-warnings.patch
|
||||
patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
|
||||
|
||||
patches/build/modpost-mask-trivial-warnings.patch:
|
||||
From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
|
||||
From: Paul Gortmaker <paul.gortmaker@windriver.com>
|
||||
Date: Sun, 25 Jan 2009 17:58:09 -0500
|
||||
Subject: [PATCH] modpost: mask trivial warnings
|
||||
|
||||
Newer HOSTCC will complain about various stdio fcns because
|
||||
.
|
||||
.
|
||||
.
|
||||
char *dump_write = NULL, *files_source = NULL;
|
||||
int opt;
|
||||
--
|
||||
2.10.1
|
||||
|
||||
generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
|
||||
|
||||
The description file can
|
||||
include multiple patch statements where each statement handles a single
|
||||
patch. In the example ``build.scc`` file, there are five patch statements
|
||||
for the five patches in the directory.
|
||||
|
||||
You can create a typical ``.patch`` file using ``diff -Nurp`` or
|
||||
``git format-patch`` commands. For information on how to create patches,
|
||||
see the ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
|
||||
and ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
|
||||
sections.
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
Features are complex kernel Metadata types that consist of configuration
|
||||
fragments, patches, and possibly other feature description files. As an
|
||||
example, consider the following generic listing::
|
||||
|
||||
features/myfeature.scc
|
||||
define KFEATURE_DESCRIPTION "Enable myfeature"
|
||||
|
||||
patch 0001-myfeature-core.patch
|
||||
patch 0002-myfeature-interface.patch
|
||||
|
||||
include cfg/myfeature_dependency.scc
|
||||
kconf non-hardware myfeature.cfg
|
||||
|
||||
This example shows how the ``patch`` and ``kconf`` commands are used as well
|
||||
as how an additional feature description file is included with the
|
||||
``include`` command.
|
||||
|
||||
Typically, features are less granular than configuration fragments and
|
||||
are more likely than configuration fragments and patches to be the types
|
||||
of things you want to specify in the :term:`KERNEL_FEATURES` variable of the
|
||||
Linux kernel recipe. See the
|
||||
":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
|
||||
in the manual.
|
||||
|
||||
Kernel Types
|
||||
------------
|
||||
|
||||
A kernel type defines a high-level kernel policy by aggregating non-hardware
|
||||
configuration fragments with patches you want to use when building a Linux
|
||||
kernel of a specific type (e.g. a real-time kernel). Syntactically, kernel
|
||||
types are no different than features as described in the
|
||||
":ref:`kernel-dev/advanced:features`" section. The :term:`LINUX_KERNEL_TYPE`
|
||||
variable in the kernel recipe selects the kernel type. For example, in the
|
||||
``linux-yocto_4.12.bb`` kernel recipe found in ``poky/meta/recipes-kernel/linux``, a
|
||||
:ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
|
||||
directive includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
|
||||
which has the following statement that defines the default kernel type::
|
||||
|
||||
LINUX_KERNEL_TYPE ??= "standard"
|
||||
|
||||
Another example would be the real-time kernel (i.e.
|
||||
``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
|
||||
type as follows::
|
||||
|
||||
LINUX_KERNEL_TYPE = "preempt-rt"
|
||||
|
||||
.. note::
|
||||
|
||||
You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
|
||||
of the :ref:`overview-manual/development-environment:yocto project source repositories`
|
||||
(e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the
|
||||
":ref:`kernel-dev/advanced:using kernel metadata in a recipe`"
|
||||
section for more information.
|
||||
|
||||
Three kernel types ("standard", "tiny", and "preempt-rt") are supported
|
||||
for Linux Yocto kernels:
|
||||
|
||||
- "standard": Includes the generic Linux kernel policy of the Yocto
|
||||
Project linux-yocto kernel recipes. This policy includes, among other
|
||||
things, which file systems, networking options, core kernel features,
|
||||
and debugging and tracing options are supported.
|
||||
|
||||
- "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
|
||||
configuration options required to build a real-time Linux kernel.
|
||||
This kernel type inherits from the "standard" kernel type.
|
||||
|
||||
- "tiny": Defines a bare minimum configuration meant to serve as a base
|
||||
for very small Linux kernels. The "tiny" kernel type is independent
|
||||
from the "standard" configuration. Although the "tiny" kernel type
|
||||
does not currently include any source changes, it might in the
|
||||
future.
|
||||
|
||||
For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
|
||||
``standard.scc``). Here is a partial listing for the ``standard.scc``
|
||||
file, which is found in the ``ktypes/standard`` directory of the
|
||||
``yocto-kernel-cache`` Git repository::
|
||||
|
||||
# Include this kernel type fragment to get the standard features and
|
||||
# configuration values.
|
||||
|
||||
# Note: if only the features are desired, but not the configuration
|
||||
# then this should be included as:
|
||||
# include ktypes/standard/standard.scc nocfg
|
||||
# if no chained configuration is desired, include it as:
|
||||
# include ktypes/standard/standard.scc nocfg inherit
|
||||
|
||||
|
||||
|
||||
include ktypes/base/base.scc
|
||||
branch standard
|
||||
|
||||
kconf non-hardware standard.cfg
|
||||
|
||||
include features/kgdb/kgdb.scc
|
||||
.
|
||||
.
|
||||
.
|
||||
|
||||
include cfg/net/ip6_nf.scc
|
||||
include cfg/net/bridge.scc
|
||||
|
||||
include cfg/systemd.scc
|
||||
|
||||
include features/rfkill/rfkill.scc
|
||||
|
||||
As with any ``.scc`` file, a kernel type definition can aggregate other
|
||||
``.scc`` files with ``include`` commands. These definitions can also
|
||||
directly pull in configuration fragments and patches with the ``kconf``
|
||||
and ``patch`` commands, respectively.
|
||||
|
||||
.. note::
|
||||
|
||||
It is not strictly necessary to create a kernel type ``.scc``
|
||||
file. The Board Support Package (BSP) file can implicitly define the
|
||||
kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the
|
||||
":ref:`kernel-dev/advanced:bsp descriptions`" section for more
|
||||
information.
|
||||
|
||||
BSP Descriptions
|
||||
----------------
|
||||
|
||||
BSP descriptions (i.e. ``*.scc`` files) combine kernel types with
|
||||
hardware-specific features. The hardware-specific Metadata is typically
|
||||
defined independently in the BSP layer, and then aggregated with each
|
||||
supported kernel type.
|
||||
|
||||
.. note::
|
||||
|
||||
For BSPs supported by the Yocto Project, the BSP description files
|
||||
are located in the ``bsp`` directory of the ``yocto-kernel-cache``
|
||||
repository organized under the "Yocto Linux Kernel" heading in the
|
||||
:yocto_git:`Yocto Project Source Repositories <>`.
|
||||
|
||||
This section overviews the BSP description structure, the aggregation
|
||||
concepts, and presents a detailed example using a BSP supported by the
|
||||
Yocto Project (i.e. BeagleBone Board). For complete information on BSP
|
||||
layer file hierarchy, see the :doc:`/bsp-guide/index`.
|
||||
|
||||
Description Overview
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For simplicity, consider the following root BSP layer description files
|
||||
for the BeagleBone board. These files employ both a structure and naming
|
||||
convention for consistency. The naming convention for the file is as
|
||||
follows::
|
||||
|
||||
bsp_root_name-kernel_type.scc
|
||||
|
||||
Here are some example root layer
|
||||
BSP filenames for the BeagleBone Board BSP, which is supported by the
|
||||
Yocto Project::
|
||||
|
||||
beaglebone-standard.scc
|
||||
beaglebone-preempt-rt.scc
|
||||
|
||||
Each file uses the root name (i.e "beaglebone") BSP name followed by the
|
||||
kernel type.
|
||||
|
||||
Examine the ``beaglebone-standard.scc`` file::
|
||||
|
||||
define KMACHINE beaglebone
|
||||
define KTYPE standard
|
||||
define KARCH arm
|
||||
|
||||
include ktypes/standard/standard.scc
|
||||
branch beaglebone
|
||||
|
||||
include beaglebone.scc
|
||||
|
||||
# default policy for standard kernels
|
||||
include features/latencytop/latencytop.scc
|
||||
include features/profiling/profiling.scc
|
||||
|
||||
Every top-level BSP description file
|
||||
should define the :term:`KMACHINE`,
|
||||
:term:`KTYPE`, and
|
||||
:term:`KARCH` variables. These
|
||||
variables allow the OpenEmbedded build system to identify the
|
||||
description as meeting the criteria set by the recipe being built. This
|
||||
example supports the "beaglebone" machine for the "standard" kernel and
|
||||
the "arm" architecture.
|
||||
|
||||
Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel
|
||||
type description file. Thus, if you do not have the
|
||||
kernel type defined in your kernel Metadata as it is here, you only need
|
||||
to ensure that the
|
||||
:term:`LINUX_KERNEL_TYPE`
|
||||
variable in the kernel recipe and the :term:`KTYPE` variable in the BSP
|
||||
description file match.
|
||||
|
||||
To separate your kernel policy from your hardware configuration, you
|
||||
include a kernel type (``ktype``), such as "standard". In the previous
|
||||
example, this is done using the following::
|
||||
|
||||
include ktypes/standard/standard.scc
|
||||
|
||||
This file aggregates all the configuration
|
||||
fragments, patches, and features that make up your standard kernel
|
||||
policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
|
||||
information.
|
||||
|
||||
To aggregate common configurations and features specific to the kernel
|
||||
for `mybsp`, use the following::
|
||||
|
||||
include mybsp.scc
|
||||
|
||||
You can see that in the BeagleBone example with the following::
|
||||
|
||||
include beaglebone.scc
|
||||
|
||||
For information on how to break a complete ``.config`` file into the various
|
||||
configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section.
|
||||
|
||||
Finally, if you have any configurations specific to the hardware that
|
||||
are not in a ``*.scc`` file, you can include them as follows::
|
||||
|
||||
kconf hardware mybsp-extra.cfg
|
||||
|
||||
The BeagleBone example does not include these
|
||||
types of configurations. However, the Malta 32-bit board does
|
||||
("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
|
||||
|
||||
define KMACHINE mti-malta32-le
|
||||
define KMACHINE qemumipsel
|
||||
define KTYPE standard
|
||||
define KARCH mips
|
||||
|
||||
include ktypes/standard/standard.scc
|
||||
branch mti-malta32
|
||||
|
||||
include mti-malta32.scc
|
||||
kconf hardware mti-malta32-le.cfg
|
||||
|
||||
Example
|
||||
~~~~~~~
|
||||
|
||||
Many real-world examples are more complex. Like any other ``.scc`` file,
|
||||
BSP descriptions can aggregate features. Consider the Minnow BSP
|
||||
definition given the ``linux-yocto-4.4`` branch of the
|
||||
``yocto-kernel-cache`` (i.e. ``yocto-kernel-cache/bsp/minnow/minnow.scc``)::
|
||||
|
||||
include cfg/x86.scc
|
||||
include features/eg20t/eg20t.scc
|
||||
include cfg/dmaengine.scc
|
||||
include features/power/intel.scc
|
||||
include cfg/efi.scc
|
||||
include features/usb/ehci-hcd.scc
|
||||
include features/usb/ohci-hcd.scc
|
||||
include features/usb/usb-gadgets.scc
|
||||
include features/usb/touchscreen-composite.scc
|
||||
include cfg/timer/hpet.scc
|
||||
include features/leds/leds.scc
|
||||
include features/spi/spidev.scc
|
||||
include features/i2c/i2cdev.scc
|
||||
include features/mei/mei-txe.scc
|
||||
|
||||
# Earlyprintk and port debug requires 8250
|
||||
kconf hardware cfg/8250.cfg
|
||||
|
||||
kconf hardware minnow.cfg
|
||||
kconf hardware minnow-dev.cfg
|
||||
|
||||
.. note::
|
||||
|
||||
Although the Minnow Board BSP is unused, the Metadata remains and is
|
||||
being used here just as an example.
|
||||
|
||||
The ``minnow.scc`` description file includes a hardware configuration
|
||||
fragment (``minnow.cfg``) specific to the Minnow BSP as well as several
|
||||
more general configuration fragments and features enabling hardware
|
||||
found on the machine. This ``minnow.scc`` description file is then
|
||||
included in each of the three "minnow" description files for the
|
||||
supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
|
||||
Consider the "minnow" description for the "standard" kernel type (i.e.
|
||||
``minnow-standard.scc``)::
|
||||
|
||||
define KMACHINE minnow
|
||||
define KTYPE standard
|
||||
define KARCH i386
|
||||
|
||||
include ktypes/standard
|
||||
|
||||
include minnow.scc
|
||||
|
||||
# Extra minnow configs above the minimal defined in minnow.scc
|
||||
include cfg/efi-ext.scc
|
||||
include features/media/media-all.scc
|
||||
include features/sound/snd_hda_intel.scc
|
||||
|
||||
# The following should really be in standard.scc
|
||||
# USB live-image support
|
||||
include cfg/usb-mass-storage.scc
|
||||
include cfg/boot-live.scc
|
||||
|
||||
# Basic profiling
|
||||
include features/latencytop/latencytop.scc
|
||||
include features/profiling/profiling.scc
|
||||
|
||||
# Requested drivers that don't have an existing scc
|
||||
kconf hardware minnow-drivers-extra.cfg
|
||||
|
||||
The ``include`` command midway through the file includes the ``minnow.scc`` description
|
||||
that defines all enabled hardware for the BSP that is common to all
|
||||
kernel types. Using this command significantly reduces duplication.
|
||||
|
||||
Now consider the "minnow" description for the "tiny" kernel type (i.e.
|
||||
``minnow-tiny.scc``)::
|
||||
|
||||
define KMACHINE minnow
|
||||
define KTYPE tiny
|
||||
define KARCH i386
|
||||
|
||||
include ktypes/tiny
|
||||
|
||||
include minnow.scc
|
||||
|
||||
As you might expect,
|
||||
the "tiny" description includes quite a bit less. In fact, it includes
|
||||
only the minimal policy defined by the "tiny" kernel type and the
|
||||
hardware-specific configuration required for booting the machine along
|
||||
with the most basic functionality of the system as defined in the base
|
||||
"minnow" description file.
|
||||
|
||||
Notice again the three critical variables:
|
||||
:term:`KMACHINE`,
|
||||
:term:`KTYPE`, and
|
||||
:term:`KARCH`. Of these variables, only
|
||||
:term:`KTYPE` has changed to specify the "tiny" kernel type.
|
||||
|
||||
Kernel Metadata Location
|
||||
========================
|
||||
|
||||
Kernel Metadata always exists outside of the kernel tree either defined
|
||||
in a kernel recipe (recipe-space) or outside of the recipe. Where you
|
||||
choose to define the Metadata depends on what you want to do and how you
|
||||
intend to work. Regardless of where you define the kernel Metadata, the
|
||||
syntax used applies equally.
|
||||
|
||||
If you are unfamiliar with the Linux kernel and only wish to apply a
|
||||
configuration and possibly a couple of patches provided to you by
|
||||
others, the recipe-space method is recommended. This method is also a
|
||||
good approach if you are working with Linux kernel sources you do not
|
||||
control or if you just do not want to maintain a Linux kernel Git
|
||||
repository on your own. For partial information on how you can define
|
||||
kernel Metadata in the recipe-space, see the
|
||||
":ref:`kernel-dev/common:modifying an existing recipe`" section.
|
||||
|
||||
Conversely, if you are actively developing a kernel and are already
|
||||
maintaining a Linux kernel Git repository of your own, you might find it
|
||||
more convenient to work with kernel Metadata kept outside the
|
||||
recipe-space. Working with Metadata in this area can make iterative
|
||||
development of the Linux kernel more efficient outside of the BitBake
|
||||
environment.
|
||||
|
||||
Recipe-Space Metadata
|
||||
---------------------
|
||||
|
||||
When stored in recipe-space, the kernel Metadata files reside in a
|
||||
directory hierarchy below :term:`FILESEXTRAPATHS`. For
|
||||
a linux-yocto recipe or for a Linux kernel recipe derived by copying
|
||||
:oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
|
||||
</openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`
|
||||
into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to
|
||||
``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
|
||||
See the ":ref:`kernel-dev/common:modifying an existing recipe`"
|
||||
section for more information.
|
||||
|
||||
Here is an example that shows a trivial tree of kernel Metadata stored
|
||||
in recipe-space within a BSP layer::
|
||||
|
||||
meta-my_bsp_layer/
|
||||
`-- recipes-kernel
|
||||
`-- linux
|
||||
`-- linux-yocto
|
||||
|-- bsp-standard.scc
|
||||
|-- bsp.cfg
|
||||
`-- standard.cfg
|
||||
|
||||
When the Metadata is stored in recipe-space, you must take steps to
|
||||
ensure BitBake has the necessary information to decide what files to
|
||||
fetch and when they need to be fetched again. It is only necessary to
|
||||
specify the ``.scc`` files on the
|
||||
:term:`SRC_URI`. BitBake parses them
|
||||
and fetches any files referenced in the ``.scc`` files by the
|
||||
``include``, ``patch``, or ``kconf`` commands. Because of this, it is
|
||||
necessary to bump the recipe :term:`PR`
|
||||
value when changing the content of files not explicitly listed in the
|
||||
:term:`SRC_URI`.
|
||||
|
||||
If the BSP description is in recipe space, you cannot simply list the
|
||||
``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
|
||||
form from your kernel append file::
|
||||
|
||||
SRC_URI:append:myplatform = " \
|
||||
file://myplatform;type=kmeta;destsuffix=myplatform \
|
||||
"
|
||||
|
||||
Metadata Outside the Recipe-Space
|
||||
---------------------------------
|
||||
|
||||
When stored outside of the recipe-space, the kernel Metadata files
|
||||
reside in a separate repository. The OpenEmbedded build system adds the
|
||||
Metadata to the build as a "type=kmeta" repository through the
|
||||
:term:`SRC_URI` variable. As an
|
||||
example, consider the following :term:`SRC_URI` statement from the
|
||||
``linux-yocto_5.15.bb`` kernel recipe::
|
||||
|
||||
SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \
|
||||
git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-5.15;destsuffix=${KMETA};protocol=https"
|
||||
|
||||
``${KMETA}``, in this context, is simply used to name the directory into
|
||||
which the Git fetcher places the Metadata. This behavior is no different
|
||||
than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g.
|
||||
see the previous section).
|
||||
|
||||
You can keep kernel Metadata in a "kernel-cache", which is a directory
|
||||
containing configuration fragments. As with any Metadata kept outside
|
||||
the recipe-space, you simply need to use the :term:`SRC_URI` statement with
|
||||
the "type=kmeta" attribute. Doing so makes the kernel Metadata available
|
||||
during the configuration phase.
|
||||
|
||||
If you modify the Metadata, you must not forget to update the :term:`SRCREV`
|
||||
statements in the kernel's recipe. In particular, you need to update the
|
||||
``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
|
||||
wish to use. Changing the data in these branches and not updating the
|
||||
:term:`SRCREV` statements to match will cause the build to fetch an older
|
||||
commit.
|
||||
|
||||
Organizing Your Source
|
||||
======================
|
||||
|
||||
Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
|
||||
kernel sources that have only a single branch. This type of
|
||||
repository structure is fine for linear development supporting a single
|
||||
machine and architecture. However, if you work with multiple boards and
|
||||
architectures, a kernel source repository with multiple branches is more
|
||||
efficient. For example, suppose you need a series of patches for one
|
||||
board to boot. Sometimes, these patches are works-in-progress or
|
||||
fundamentally wrong, yet they are still necessary for specific boards.
|
||||
In these situations, you most likely do not want to include these
|
||||
patches in every kernel you build (i.e. have the patches as part of the
|
||||
default branch). It is situations like these that give rise to
|
||||
multiple branches used within a Linux kernel sources Git repository.
|
||||
|
||||
Here are repository organization strategies maximizing source reuse,
|
||||
removing redundancy, and logically ordering your changes. This section
|
||||
presents strategies for the following cases:
|
||||
|
||||
- Encapsulating patches in a feature description and only including the
|
||||
patches in the BSP descriptions of the applicable boards.
|
||||
|
||||
- Creating a machine branch in your kernel source repository and
|
||||
applying the patches on that branch only.
|
||||
|
||||
- Creating a feature branch in your kernel source repository and
|
||||
merging that branch into your BSP when needed.
|
||||
|
||||
The approach you take is entirely up to you and depends on what works
|
||||
best for your development model.
|
||||
|
||||
Encapsulating Patches
|
||||
---------------------
|
||||
|
||||
If you are reusing patches from an external tree and are not working on
|
||||
the patches, you might find the encapsulated feature to be appropriate.
|
||||
Given this scenario, you do not need to create any branches in the
|
||||
source repository. Rather, you just take the static patches you need and
|
||||
encapsulate them within a feature description. Once you have the feature
|
||||
description, you simply include that into the BSP description as
|
||||
described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section.
|
||||
|
||||
You can find information on how to create patches and BSP descriptions
|
||||
in the ":ref:`kernel-dev/advanced:patches`" and
|
||||
":ref:`kernel-dev/advanced:bsp descriptions`" sections.
|
||||
|
||||
Machine Branches
|
||||
----------------
|
||||
|
||||
When you have multiple machines and architectures to support, or you are
|
||||
actively working on board support, it is more efficient to create
|
||||
branches in the repository based on individual machines. Having machine
|
||||
branches allows common source to remain in the development branch with any
|
||||
features specific to a machine stored in the appropriate machine branch.
|
||||
This organization method frees you from continually reintegrating your
|
||||
patches into a feature.
|
||||
|
||||
Once you have a new branch, you can set up your kernel Metadata to use
|
||||
the branch a couple different ways. In the recipe, you can specify the
|
||||
new branch as the :term:`KBRANCH` to use for the board as follows::
|
||||
|
||||
KBRANCH = "mynewbranch"
|
||||
|
||||
Another method is to use the ``branch`` command in the BSP
|
||||
description::
|
||||
|
||||
mybsp.scc:
|
||||
define KMACHINE mybsp
|
||||
define KTYPE standard
|
||||
define KARCH i386
|
||||
include standard.scc
|
||||
|
||||
branch mynewbranch
|
||||
|
||||
include mybsp-hw.scc
|
||||
|
||||
If you find yourself with numerous branches, you might consider using a
|
||||
hierarchical branching system similar to what the Yocto Linux Kernel Git
|
||||
repositories use::
|
||||
|
||||
common/kernel_type/machine
|
||||
|
||||
If you had two kernel types, "standard" and "small" for instance, three
|
||||
machines, and common as ``mydir``, the branches in your Git repository
|
||||
might look like this::
|
||||
|
||||
mydir/base
|
||||
mydir/standard/base
|
||||
mydir/standard/machine_a
|
||||
mydir/standard/machine_b
|
||||
mydir/standard/machine_c
|
||||
mydir/small/base
|
||||
mydir/small/machine_a
|
||||
|
||||
This organization can help clarify the branch relationships. In this
|
||||
case, ``mydir/standard/machine_a`` includes everything in ``mydir/base``
|
||||
and ``mydir/standard/base``. The "standard" and "small" branches add
|
||||
sources specific to those kernel types that for whatever reason are not
|
||||
appropriate for the other branches.
|
||||
|
||||
.. note::
|
||||
|
||||
The "base" branches are an artifact of the way Git manages its data
|
||||
internally on the filesystem: Git will not allow you to use
|
||||
``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to
|
||||
create a file and a directory named "standard".
|
||||
|
||||
Feature Branches
|
||||
----------------
|
||||
|
||||
When you are actively developing new features, it can be more efficient
|
||||
to work with that feature as a branch, rather than as a set of patches
|
||||
that have to be regularly updated. The Yocto Project Linux kernel tools
|
||||
provide for this with the ``git merge`` command.
|
||||
|
||||
To merge a feature branch into a BSP, insert the ``git merge`` command
|
||||
after any ``branch`` commands::
|
||||
|
||||
mybsp.scc:
|
||||
define KMACHINE mybsp
|
||||
define KTYPE standard
|
||||
define KARCH i386
|
||||
include standard.scc
|
||||
|
||||
branch mynewbranch
|
||||
git merge myfeature
|
||||
|
||||
include mybsp-hw.scc
|
||||
|
||||
SCC Description File Reference
|
||||
==============================
|
||||
|
||||
This section provides a brief reference for the commands you can use
|
||||
within an SCC description file (``.scc``):
|
||||
|
||||
- ``branch [ref]``: Creates a new branch relative to the current branch
|
||||
(typically ``${KTYPE}``) using the currently checked-out branch, or
|
||||
"ref" if specified.
|
||||
|
||||
- ``define``: Defines variables, such as
|
||||
:term:`KMACHINE`,
|
||||
:term:`KTYPE`,
|
||||
:term:`KARCH`, and
|
||||
:term:`KFEATURE_DESCRIPTION`.
|
||||
|
||||
- ``include SCC_FILE``: Includes an SCC file in the current file. The
|
||||
file is parsed as if you had inserted it inline.
|
||||
|
||||
- ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration
|
||||
fragment for merging into the final Linux ``.config`` file.
|
||||
|
||||
- ``git merge GIT_BRANCH``: Merges the feature branch into the current
|
||||
branch.
|
||||
|
||||
- ``patch PATCH_FILE``: Applies the patch to the current Git branch.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user