1252 lines
54 KiB
XML
1252 lines
54 KiB
XML
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||
|
|
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
||
|
|
|
||
|
|
<chapter id='kernel-dev-advanced'>
|
||
|
|
<title>Working with Advanced Metadata (<filename>yocto-kernel-cache</filename>)</title>
|
||
|
|
|
||
|
|
<section id='kernel-dev-advanced-overview'>
|
||
|
|
<title>Overview</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
In addition to supporting configuration fragments and patches, the
|
||
|
|
Yocto Project kernel tools also support rich
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> 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.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Kernel Metadata exists in many places.
|
||
|
|
One area in the Yocto Project
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
|
||
|
|
is the <filename>yocto-kernel-cache</filename> Git repository.
|
||
|
|
You can find this repository grouped under the "Yocto Linux Kernel"
|
||
|
|
heading in the
|
||
|
|
<ulink url='&YOCTO_GIT_URL;'>Yocto Project Source Repositories</ulink>.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Kernel development tools ("kern-tools") exist also in the Yocto
|
||
|
|
Project Source Repositories under the "Yocto Linux Kernel" heading
|
||
|
|
in the <filename>yocto-kernel-tools</filename> Git repository.
|
||
|
|
The recipe that builds these tools is
|
||
|
|
<filename>meta/recipes-kernel/kern-tools/kern-tools-native_git.bb</filename>
|
||
|
|
in the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
|
||
|
|
(e.g. <filename>poky</filename>).
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='using-kernel-metadata-in-a-recipe'>
|
||
|
|
<title>Using Kernel Metadata in a Recipe</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
As mentioned in the introduction, the Yocto Project contains kernel
|
||
|
|
Metadata, which is located in the
|
||
|
|
<filename>yocto-kernel-cache</filename> 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 <filename>linux-yocto.inc</filename> file)
|
||
|
|
is said to be a "linux-yocto style" recipe.
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Every linux-yocto style recipe must define the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
|
||
|
|
variable.
|
||
|
|
This variable is typically set to the same value as the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
|
||
|
|
variable, which is used by
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
|
||
|
|
However, in some cases, the variable might instead refer to the
|
||
|
|
underlying platform of the <filename>MACHINE</filename>.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Multiple BSPs can reuse the same <filename>KMACHINE</filename>
|
||
|
|
name if they are built using the same BSP description.
|
||
|
|
Multiple Corei7-based BSPs could share the same "intel-corei7-64"
|
||
|
|
value for <filename>KMACHINE</filename>.
|
||
|
|
It is important to realize that <filename>KMACHINE</filename> is
|
||
|
|
just for kernel mapping, while
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
|
||
|
|
is the machine type within a BSP Layer.
|
||
|
|
Even with this distinction, however, these two variables can hold
|
||
|
|
the same value.
|
||
|
|
See the <link linkend='bsp-descriptions'>BSP Descriptions</link>
|
||
|
|
section for more information.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Every linux-yocto style recipe must also indicate the Linux kernel
|
||
|
|
source repository branch used to build the Linux kernel.
|
||
|
|
The <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
|
||
|
|
variable must be set to indicate the branch.
|
||
|
|
<note>
|
||
|
|
You can use the <filename>KBRANCH</filename> value to define an
|
||
|
|
alternate branch typically with a machine override as shown here
|
||
|
|
from the <filename>meta-yocto-bsp</filename> layer:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
KBRANCH_edgerouter = "standard/edgerouter"
|
||
|
|
</literallayout>
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The linux-yocto style recipes can optionally define the following
|
||
|
|
variables:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
KERNEL_FEATURES
|
||
|
|
LINUX_KERNEL_TYPE
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
|
||
|
|
defines the kernel type to be
|
||
|
|
used in assembling the configuration.
|
||
|
|
If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
|
||
|
|
it defaults to "standard".
|
||
|
|
Together with
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
|
||
|
|
<filename>LINUX_KERNEL_TYPE</filename> 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 "<link linkend='kernel-types'>Kernel Types</link>" section
|
||
|
|
for more information on kernel types.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
During the build, the kern-tools search for the BSP description
|
||
|
|
file that most closely matches the <filename>KMACHINE</filename>
|
||
|
|
and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the
|
||
|
|
recipe.
|
||
|
|
The tools use the first BSP description it finds that match
|
||
|
|
both variables.
|
||
|
|
If the tools cannot find a match, they issue a warning.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The tools first search for the <filename>KMACHINE</filename> and
|
||
|
|
then for the <filename>LINUX_KERNEL_TYPE</filename>.
|
||
|
|
If the tools cannot find a partial match, they will use the
|
||
|
|
sources from the <filename>KBRANCH</filename> and any configuration
|
||
|
|
specified in the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
You can use the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
|
||
|
|
variable
|
||
|
|
to include features (configuration fragments, patches, or both) that
|
||
|
|
are not already included by the <filename>KMACHINE</filename> and
|
||
|
|
<filename>LINUX_KERNEL_TYPE</filename> variable combination.
|
||
|
|
For example, to include a feature specified as
|
||
|
|
"features/netfilter/netfilter.scc",
|
||
|
|
specify:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
KERNEL_FEATURES += "features/netfilter/netfilter.scc"
|
||
|
|
</literallayout>
|
||
|
|
To include a feature called "cfg/sound.scc" just for the
|
||
|
|
<filename>qemux86</filename> machine, specify:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc"
|
||
|
|
</literallayout>
|
||
|
|
The value of the entries in <filename>KERNEL_FEATURES</filename>
|
||
|
|
are dependent on their location within the kernel Metadata itself.
|
||
|
|
The examples here are taken from the
|
||
|
|
<filename>yocto-kernel-cache</filename> repository.
|
||
|
|
Each branch of this repository contains "features" and "cfg"
|
||
|
|
subdirectories at the top-level.
|
||
|
|
For more information, see the
|
||
|
|
"<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>"
|
||
|
|
section.
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='kernel-metadata-syntax'>
|
||
|
|
<title>Kernel Metadata Syntax</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The kernel Metadata consists of three primary types of files:
|
||
|
|
<filename>scc</filename>
|
||
|
|
<footnote>
|
||
|
|
<para>
|
||
|
|
<filename>scc</filename> 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 <filename>scc</filename> files to be description files.
|
||
|
|
</para>
|
||
|
|
</footnote>
|
||
|
|
description files, configuration fragments, and patches.
|
||
|
|
The <filename>scc</filename> 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.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The <filename>scc</filename> description files are used to define two
|
||
|
|
fundamental types of kernel Metadata:
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>Features</para></listitem>
|
||
|
|
<listitem><para>Board Support Packages (BSPs)</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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.
|
||
|
|
<link linkend='kernel-types'>Kernel types</link> define general
|
||
|
|
kernel features and policy to be reused in the BSPs.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
BSPs define hardware-specific features and aggregate them with kernel
|
||
|
|
types to form the final description of what will be assembled and built.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
<replaceable>base</replaceable>/
|
||
|
|
bsp/
|
||
|
|
cfg/
|
||
|
|
features/
|
||
|
|
ktypes/
|
||
|
|
patches/
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The <filename>bsp</filename> directory contains the
|
||
|
|
<link linkend='bsp-descriptions'>BSP descriptions</link>.
|
||
|
|
The remaining directories all contain "features".
|
||
|
|
Separating <filename>bsp</filename> from the rest of the structure
|
||
|
|
aids conceptualizing intended usage.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Use these guidelines to help place your <filename>scc</filename>
|
||
|
|
description files within the structure:
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>If your file contains
|
||
|
|
only configuration fragments, place the file in the
|
||
|
|
<filename>cfg</filename> directory.</para></listitem>
|
||
|
|
<listitem><para>If your file contains
|
||
|
|
only source-code fixes, place the file in the
|
||
|
|
<filename>patches</filename> directory.</para></listitem>
|
||
|
|
<listitem><para>If your file encapsulates
|
||
|
|
a major feature, often combining sources and configurations,
|
||
|
|
place the file in <filename>features</filename> directory.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>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 <filename>ktypes</filename>
|
||
|
|
directory.
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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 <filename>cfg</filename>,
|
||
|
|
<filename>features</filename>, <filename>patches</filename>, and
|
||
|
|
<filename>ktypes</filename>, contain "features" as far as the kernel
|
||
|
|
tools are concerned.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Paths used in kernel Metadata files are relative to
|
||
|
|
<replaceable>base</replaceable>, which is either
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
|
||
|
|
if you are creating Metadata in
|
||
|
|
<link linkend='recipe-space-metadata'>recipe-space</link>,
|
||
|
|
or the top level of
|
||
|
|
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/'><filename>yocto-kernel-cache</filename></ulink>
|
||
|
|
if you are creating
|
||
|
|
<link linkend='metadata-outside-the-recipe-space'>Metadata outside of the recipe-space</link>.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<section id='configuration'>
|
||
|
|
<title>Configuration</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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
|
||
|
|
(<filename>.cfg</filename>) and a <filename>.scc</filename> file
|
||
|
|
that describes the fragment.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
As an example, consider the Symmetric Multi-Processing (SMP)
|
||
|
|
fragment used with the <filename>linux-yocto-4.12</filename>
|
||
|
|
kernel as defined outside of the recipe space (i.e.
|
||
|
|
<filename>yocto-kernel-cache</filename>).
|
||
|
|
This Metadata consists of two files: <filename>smp.scc</filename>
|
||
|
|
and <filename>smp.cfg</filename>.
|
||
|
|
You can find these files in the <filename>cfg</filename> directory
|
||
|
|
of the <filename>yocto-4.12</filename> branch in the
|
||
|
|
<filename>yocto-kernel-cache</filename> Git repository:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
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
|
||
|
|
</literallayout>
|
||
|
|
You can find general information on configuration fragment files in
|
||
|
|
the
|
||
|
|
"<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
|
||
|
|
section.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Within the <filename>smp.scc</filename> file, the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>
|
||
|
|
statement provides a short description of the fragment.
|
||
|
|
Higher level kernel tools use this description.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Also within the <filename>smp.scc</filename> file, the
|
||
|
|
<filename>kconf</filename> command includes the
|
||
|
|
actual configuration fragment in an <filename>.scc</filename>
|
||
|
|
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
|
||
|
|
<filename>kconf</filename> statements, one per fragment.
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
As described in the
|
||
|
|
"<link linkend='validating-configuration'>Validating Configuration</link>"
|
||
|
|
section, you can use the following BitBake command to audit your
|
||
|
|
configuration:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
$ bitbake linux-yocto -c kernel_configcheck -f
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='patches'>
|
||
|
|
<title>Patches</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Patch descriptions are very similar to configuration fragment
|
||
|
|
descriptions, which are described in the previous section.
|
||
|
|
However, instead of a <filename>.cfg</filename> file, these
|
||
|
|
descriptions work with source patches (i.e.
|
||
|
|
<filename>.patch</filename> files).
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
A typical patch includes a description file and the patch itself.
|
||
|
|
As an example, consider the build patches used with the
|
||
|
|
<filename>linux-yocto-4.12</filename> kernel as defined outside of
|
||
|
|
the recipe space (i.e. <filename>yocto-kernel-cache</filename>).
|
||
|
|
This Metadata consists of several files:
|
||
|
|
<filename>build.scc</filename> and a set of
|
||
|
|
<filename>*.patch</filename> files.
|
||
|
|
You can find these files in the <filename>patches/build</filename>
|
||
|
|
directory of the <filename>yocto-4.12</filename> branch in the
|
||
|
|
<filename>yocto-kernel-cache</filename> Git repository.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The following listings show the <filename>build.scc</filename>
|
||
|
|
file and part of the
|
||
|
|
<filename>modpost-mask-trivial-warnings.patch</filename> file:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
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)
|
||
|
|
</literallayout>
|
||
|
|
The description file can include multiple patch statements where
|
||
|
|
each statement handles a single patch.
|
||
|
|
In the example <filename>build.scc</filename> file, five patch
|
||
|
|
statements exist for the five patches in the directory.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
You can create a typical <filename>.patch</filename> file using
|
||
|
|
<filename>diff -Nurp</filename> or
|
||
|
|
<filename>git format-patch</filename> commands.
|
||
|
|
For information on how to create patches, see the
|
||
|
|
"<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
|
||
|
|
and
|
||
|
|
"<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
|
||
|
|
sections.
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='features'>
|
||
|
|
<title>Features</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
features/<replaceable>myfeature</replaceable>.scc
|
||
|
|
define KFEATURE_DESCRIPTION "Enable <replaceable>myfeature</replaceable>"
|
||
|
|
|
||
|
|
patch 0001-<replaceable>myfeature</replaceable>-core.patch
|
||
|
|
patch 0002-<replaceable>myfeature</replaceable>-interface.patch
|
||
|
|
|
||
|
|
include cfg/<replaceable>myfeature</replaceable>_dependency.scc
|
||
|
|
kconf non-hardware <replaceable>myfeature</replaceable>.cfg
|
||
|
|
</literallayout>
|
||
|
|
This example shows how the <filename>patch</filename> and
|
||
|
|
<filename>kconf</filename> commands are used as well as
|
||
|
|
how an additional feature description file is included with
|
||
|
|
the <filename>include</filename> command.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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 <filename>KERNEL_FEATURES</filename> variable of the
|
||
|
|
Linux kernel recipe.
|
||
|
|
See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
|
||
|
|
section earlier in the manual.
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='kernel-types'>
|
||
|
|
<title>Kernel Types</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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 "<link linkend='features'>Features</link>"
|
||
|
|
section.
|
||
|
|
The
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
|
||
|
|
variable in the kernel recipe selects the kernel type.
|
||
|
|
For example, in the <filename>linux-yocto_4.12.bb</filename>
|
||
|
|
kernel recipe found in
|
||
|
|
<filename>poky/meta/recipes-kernel/linux</filename>, a
|
||
|
|
<ulink url='&YOCTO_DOCS_BB_URL;#require-inclusion'><filename>require</filename></ulink>
|
||
|
|
directive includes the
|
||
|
|
<filename>poky/meta/recipes-kernel/linux/linux-yocto.inc</filename>
|
||
|
|
file, which has the following statement that defines the default
|
||
|
|
kernel type:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
LINUX_KERNEL_TYPE ??= "standard"
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Another example would be the real-time kernel (i.e.
|
||
|
|
<filename>linux-yocto-rt_4.12.bb</filename>).
|
||
|
|
This kernel recipe directly sets the kernel type as follows:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
LINUX_KERNEL_TYPE = "preempt-rt"
|
||
|
|
</literallayout>
|
||
|
|
<note>
|
||
|
|
You can find kernel recipes in the
|
||
|
|
<filename>meta/recipes-kernel/linux</filename> directory of the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
|
||
|
|
(e.g. <filename>poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>).
|
||
|
|
See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
|
||
|
|
section for more information.
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Three kernel types ("standard", "tiny", and "preempt-rt") are
|
||
|
|
supported for Linux Yocto kernels:
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>"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.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>"preempt-rt":
|
||
|
|
Applies the <filename>PREEMPT_RT</filename>
|
||
|
|
patches and the configuration options required to
|
||
|
|
build a real-time Linux kernel.
|
||
|
|
This kernel type inherits from the "standard" kernel type.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>"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.
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
For any given kernel type, the Metadata is defined by the
|
||
|
|
<filename>.scc</filename> (e.g. <filename>standard.scc</filename>).
|
||
|
|
Here is a partial listing for the <filename>standard.scc</filename>
|
||
|
|
file, which is found in the <filename>ktypes/standard</filename>
|
||
|
|
directory of the <filename>yocto-kernel-cache</filename> Git
|
||
|
|
repository:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
# 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
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
As with any <filename>.scc</filename> file, a
|
||
|
|
kernel type definition can aggregate other
|
||
|
|
<filename>.scc</filename> files with
|
||
|
|
<filename>include</filename> commands.
|
||
|
|
These definitions can also directly pull in
|
||
|
|
configuration fragments and patches with the
|
||
|
|
<filename>kconf</filename> and <filename>patch</filename>
|
||
|
|
commands, respectively.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<note>
|
||
|
|
It is not strictly necessary to create a kernel type
|
||
|
|
<filename>.scc</filename> file.
|
||
|
|
The Board Support Package (BSP) file can implicitly define
|
||
|
|
the kernel type using a <filename>define
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename>
|
||
|
|
line.
|
||
|
|
See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
|
||
|
|
section for more information.
|
||
|
|
</note>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='bsp-descriptions'>
|
||
|
|
<title>BSP Descriptions</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
BSP descriptions (i.e. <filename>*.scc</filename> 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 <filename>bsp</filename> directory
|
||
|
|
of the <filename>yocto-kernel-cache</filename> repository
|
||
|
|
organized under the "Yocto Linux Kernel" heading in the
|
||
|
|
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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).
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<section id='bsp-description-file-overview'>
|
||
|
|
<title>Overview</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
For simplicity, consider the following top-level BSP
|
||
|
|
description files for the BeagleBone board.
|
||
|
|
Top-level BSP descriptions files employ both a structure
|
||
|
|
and naming convention for consistency.
|
||
|
|
The naming convention for the file is as follows:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
<replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
|
||
|
|
</literallayout>
|
||
|
|
Here are some example top-level BSP filenames for the
|
||
|
|
BeagleBone Board BSP, which is supported by the Yocto Project:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
beaglebone-standard.scc
|
||
|
|
beaglebone-preempt-rt.scc
|
||
|
|
</literallayout>
|
||
|
|
Each file uses the BSP name followed by the kernel type.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Examine the <filename>beaglebone-standard.scc</filename>
|
||
|
|
file:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
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
|
||
|
|
</literallayout>
|
||
|
|
Every top-level BSP description file should define the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
|
||
|
|
and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
|
||
|
|
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.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Be aware that a hard link between the
|
||
|
|
<filename>KTYPE</filename> variable and a kernel type
|
||
|
|
description file does not exist.
|
||
|
|
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
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
|
||
|
|
variable in the kernel recipe and the
|
||
|
|
<filename>KTYPE</filename> variable in the BSP description
|
||
|
|
file match.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
To separate your kernel policy from your hardware configuration,
|
||
|
|
you include a kernel type (<filename>ktype</filename>), such as
|
||
|
|
"standard".
|
||
|
|
In the previous example, this is done using the following:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
include ktypes/standard/standard.scc
|
||
|
|
</literallayout>
|
||
|
|
This file aggregates all the configuration fragments, patches,
|
||
|
|
and features that make up your standard kernel policy.
|
||
|
|
See the "<link linkend='kernel-types'>Kernel Types</link>"
|
||
|
|
section for more information.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
To aggregate common configurations and features specific to the
|
||
|
|
kernel for <replaceable>mybsp</replaceable>, use the following:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
include <replaceable>mybsp</replaceable>.scc
|
||
|
|
</literallayout>
|
||
|
|
You can see that in the BeagleBone example with the following:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
include beaglebone.scc
|
||
|
|
</literallayout>
|
||
|
|
For information on how to break a complete
|
||
|
|
<filename>.config</filename> file into the various
|
||
|
|
configuration fragments, see the
|
||
|
|
"<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
|
||
|
|
section.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Finally, if you have any configurations specific to the
|
||
|
|
hardware that are not in a <filename>*.scc</filename> file,
|
||
|
|
you can include them as follows:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
|
||
|
|
</literallayout>
|
||
|
|
The BeagleBone example does not include these types of
|
||
|
|
configurations.
|
||
|
|
However, the Malta 32-bit board does ("mti-malta32").
|
||
|
|
Here is the <filename>mti-malta32-le-standard.scc</filename>
|
||
|
|
file:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
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
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='bsp-description-file-example-minnow'>
|
||
|
|
<title>Example</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Many real-world examples are more complex.
|
||
|
|
Like any other <filename>.scc</filename> file, BSP
|
||
|
|
descriptions can aggregate features.
|
||
|
|
Consider the Minnow BSP definition given the
|
||
|
|
<filename>linux-yocto-4.4</filename> branch of the
|
||
|
|
<filename>yocto-kernel-cache</filename> (i.e.
|
||
|
|
<filename>yocto-kernel-cache/bsp/minnow/minnow.scc</filename>):
|
||
|
|
<note>
|
||
|
|
Although the Minnow Board BSP is unused, the Metadata
|
||
|
|
remains and is being used here just as an example.
|
||
|
|
</note>
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
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
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The <filename>minnow.scc</filename> description file includes
|
||
|
|
a hardware configuration fragment
|
||
|
|
(<filename>minnow.cfg</filename>) specific to the Minnow
|
||
|
|
BSP as well as several more general configuration
|
||
|
|
fragments and features enabling hardware found on the
|
||
|
|
machine.
|
||
|
|
This <filename>minnow.scc</filename> 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. <filename>minnow-standard.scc</filename>:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
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
|
||
|
|
</literallayout>
|
||
|
|
The <filename>include</filename> command midway through the file
|
||
|
|
includes the <filename>minnow.scc</filename> description that
|
||
|
|
defines all enabled hardware for the BSP that is common to
|
||
|
|
all kernel types.
|
||
|
|
Using this command significantly reduces duplication.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Now consider the "minnow" description for the "tiny" kernel
|
||
|
|
type (i.e. <filename>minnow-tiny.scc</filename>:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
define KMACHINE minnow
|
||
|
|
define KTYPE tiny
|
||
|
|
define KARCH i386
|
||
|
|
|
||
|
|
include ktypes/tiny
|
||
|
|
|
||
|
|
include minnow.scc
|
||
|
|
</literallayout>
|
||
|
|
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.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Notice again the three critical variables:
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
|
||
|
|
and
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>.
|
||
|
|
Of these variables, only <filename>KTYPE</filename>
|
||
|
|
has changed to specify the "tiny" kernel type.
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='kernel-metadata-location'>
|
||
|
|
<title>Kernel Metadata Location</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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
|
||
|
|
"<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
|
||
|
|
section.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<section id='recipe-space-metadata'>
|
||
|
|
<title>Recipe-Space Metadata</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
When stored in recipe-space, the kernel Metadata files reside in a
|
||
|
|
directory hierarchy below
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
|
||
|
|
For a linux-yocto recipe or for a Linux kernel recipe derived
|
||
|
|
by copying and modifying
|
||
|
|
<filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
|
||
|
|
to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
|
||
|
|
is typically set to
|
||
|
|
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>.
|
||
|
|
See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
|
||
|
|
section for more information.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Here is an example that shows a trivial tree of kernel Metadata
|
||
|
|
stored in recipe-space within a BSP layer:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
meta-<replaceable>my_bsp_layer</replaceable>/
|
||
|
|
`-- recipes-kernel
|
||
|
|
`-- linux
|
||
|
|
`-- linux-yocto
|
||
|
|
|-- bsp-standard.scc
|
||
|
|
|-- bsp.cfg
|
||
|
|
`-- standard.cfg
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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 <filename>.scc</filename>
|
||
|
|
files on the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
|
||
|
|
BitBake parses them and fetches any files referenced in the
|
||
|
|
<filename>.scc</filename> files by the <filename>include</filename>,
|
||
|
|
<filename>patch</filename>, or <filename>kconf</filename> commands.
|
||
|
|
Because of this, it is necessary to bump the recipe
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
|
||
|
|
value when changing the content of files not explicitly listed
|
||
|
|
in the <filename>SRC_URI</filename>.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
If the BSP description is in recipe space, you cannot simply list
|
||
|
|
the <filename>*.scc</filename> in the <filename>SRC_URI</filename>
|
||
|
|
statement.
|
||
|
|
You need to use the following form from your kernel append file:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
SRC_URI_append_<replaceable>myplatform</replaceable> = " \
|
||
|
|
file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \
|
||
|
|
"
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='metadata-outside-the-recipe-space'>
|
||
|
|
<title>Metadata Outside the Recipe-Space</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
||
|
|
variable.
|
||
|
|
As an example, consider the following <filename>SRC_URI</filename>
|
||
|
|
statement from the <filename>linux-yocto_4.12.bb</filename>
|
||
|
|
kernel recipe:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
|
||
|
|
git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
|
||
|
|
</literallayout>
|
||
|
|
<filename>${KMETA}</filename>, 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
|
||
|
|
<filename>SRC_URI</filename> statement used in a recipe (e.g.
|
||
|
|
see the previous section).
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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 <filename>SRC_URI</filename> statement with the
|
||
|
|
"type=kmeta" attribute.
|
||
|
|
Doing so makes the kernel Metadata available during the
|
||
|
|
configuration phase.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
If you modify the Metadata, you must not forget to update the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
|
||
|
|
statements in the kernel's recipe.
|
||
|
|
In particular, you need to update the
|
||
|
|
<filename>SRCREV_meta</filename> variable to match the commit in
|
||
|
|
the <filename>KMETA</filename> branch you wish to use.
|
||
|
|
Changing the data in these branches and not updating the
|
||
|
|
<filename>SRCREV</filename> statements to match will cause the
|
||
|
|
build to fetch an older commit.
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='organizing-your-source'>
|
||
|
|
<title>Organizing Your Source</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Many recipes based on the <filename>linux-yocto-custom.bb</filename>
|
||
|
|
recipe use Linux kernel sources that have only a single
|
||
|
|
branch - "master".
|
||
|
|
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 lone "master" branch).
|
||
|
|
It is situations like these that give rise to multiple branches used
|
||
|
|
within a Linux kernel sources Git repository.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Repository organization strategies exist that maximize source reuse,
|
||
|
|
remove redundancy, and logically order your changes.
|
||
|
|
This section presents strategies for the following cases:
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>Encapsulating patches in a feature description
|
||
|
|
and only including the patches in the BSP descriptions of
|
||
|
|
the applicable boards.</para></listitem>
|
||
|
|
<listitem><para>Creating a machine branch in your
|
||
|
|
kernel source repository and applying the patches on that
|
||
|
|
branch only.</para></listitem>
|
||
|
|
<listitem><para>Creating a feature branch in your
|
||
|
|
kernel source repository and merging that branch into your
|
||
|
|
BSP when needed.</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The approach you take is entirely up to you
|
||
|
|
and depends on what works best for your development model.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<section id='encapsulating-patches'>
|
||
|
|
<title>Encapsulating Patches</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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
|
||
|
|
"<link linkend='bsp-descriptions'>BSP Descriptions</link>"
|
||
|
|
section.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
You can find information on how to create patches and BSP
|
||
|
|
descriptions in the "<link linkend='patches'>Patches</link>" and
|
||
|
|
"<link linkend='bsp-descriptions'>BSP Descriptions</link>"
|
||
|
|
sections.
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='machine-branches'>
|
||
|
|
<title>Machine Branches</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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
|
||
|
|
"master" 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.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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
|
||
|
|
<filename>KBRANCH</filename> to use for the board as
|
||
|
|
follows:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
KBRANCH = "mynewbranch"
|
||
|
|
</literallayout>
|
||
|
|
Another method is to use the <filename>branch</filename> command
|
||
|
|
in the BSP description:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
mybsp.scc:
|
||
|
|
define KMACHINE mybsp
|
||
|
|
define KTYPE standard
|
||
|
|
define KARCH i386
|
||
|
|
include standard.scc
|
||
|
|
|
||
|
|
branch mynewbranch
|
||
|
|
|
||
|
|
include mybsp-hw.scc
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
<replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable>
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
If you had two kernel types, "standard" and "small" for
|
||
|
|
instance, three machines, and <replaceable>common</replaceable>
|
||
|
|
as <filename>mydir</filename>, the branches in your
|
||
|
|
Git repository might look like this:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
mydir/base
|
||
|
|
mydir/standard/base
|
||
|
|
mydir/standard/machine_a
|
||
|
|
mydir/standard/machine_b
|
||
|
|
mydir/standard/machine_c
|
||
|
|
mydir/small/base
|
||
|
|
mydir/small/machine_a
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This organization can help clarify the branch relationships.
|
||
|
|
In this case, <filename>mydir/standard/machine_a</filename>
|
||
|
|
includes everything in <filename>mydir/base</filename> and
|
||
|
|
<filename>mydir/standard/base</filename>.
|
||
|
|
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 <filename>mydir/standard</filename> and
|
||
|
|
<filename>mydir/standard/machine_a</filename> because it
|
||
|
|
would have to create a file and a directory named "standard".
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='feature-branches'>
|
||
|
|
<title>Feature Branches</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
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 <filename>git merge</filename> command.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
To merge a feature branch into a BSP, insert the
|
||
|
|
<filename>git merge</filename> command after any
|
||
|
|
<filename>branch</filename> commands:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
mybsp.scc:
|
||
|
|
define KMACHINE mybsp
|
||
|
|
define KTYPE standard
|
||
|
|
define KARCH i386
|
||
|
|
include standard.scc
|
||
|
|
|
||
|
|
branch mynewbranch
|
||
|
|
git merge myfeature
|
||
|
|
|
||
|
|
include mybsp-hw.scc
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='scc-reference'>
|
||
|
|
<title>SCC Description File Reference</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This section provides a brief reference for the commands you can use
|
||
|
|
within an SCC description file (<filename>.scc</filename>):
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>
|
||
|
|
<filename>branch [ref]</filename>:
|
||
|
|
Creates a new branch relative to the current branch
|
||
|
|
(typically <filename>${KTYPE}</filename>) using
|
||
|
|
the currently checked-out branch, or "ref" if specified.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<filename>define</filename>:
|
||
|
|
Defines variables, such as <filename>KMACHINE</filename>,
|
||
|
|
<filename>KTYPE</filename>, <filename>KARCH</filename>,
|
||
|
|
and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<filename>include SCC_FILE</filename>:
|
||
|
|
Includes an SCC file in the current file.
|
||
|
|
The file is parsed as if you had inserted it inline.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<filename>kconf [hardware|non-hardware] CFG_FILE</filename>:
|
||
|
|
Queues a configuration fragment for merging into the final
|
||
|
|
Linux <filename>.config</filename> file.</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<filename>git merge GIT_BRANCH</filename>:
|
||
|
|
Merges the feature branch into the current branch.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<filename>patch PATCH_FILE</filename>:
|
||
|
|
Applies the patch to the current Git branch.
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
</chapter>
|
||
|
|
<!--
|
||
|
|
vim: expandtab tw=80 ts=4
|
||
|
|
-->
|