Revert "Revert "poky: subtree update:b23aa6b753..ad30a6d470""
This reverts commit 4873add6e11c1bd421c83cd08df589f1184aa673.
A fix has been put up for openbmc/openbmc#3720 so we can bring
this back now
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
Change-Id: If59020a5b502f70aa7149fbef4ad2f50824d1ce6
diff --git a/poky/documentation/kernel-dev/history.rst b/poky/documentation/kernel-dev/history.rst
index 3ffb7ea..761b506 100644
--- a/poky/documentation/kernel-dev/history.rst
+++ b/poky/documentation/kernel-dev/history.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-2.0-UK
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
***********************
Manual Revision History
diff --git a/poky/documentation/kernel-dev/kernel-dev-advanced.rst b/poky/documentation/kernel-dev/kernel-dev-advanced.rst
index 36133ca..eeb8f87 100644
--- a/poky/documentation/kernel-dev/kernel-dev-advanced.rst
+++ b/poky/documentation/kernel-dev/kernel-dev-advanced.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-2.0-UK
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
*******************************************************
Working with Advanced Metadata (``yocto-kernel-cache``)
diff --git a/poky/documentation/kernel-dev/kernel-dev-advanced.xml b/poky/documentation/kernel-dev/kernel-dev-advanced.xml
deleted file mode 100644
index 3717796..0000000
--- a/poky/documentation/kernel-dev/kernel-dev-advanced.xml
+++ /dev/null
@@ -1,1257 +0,0 @@
-<!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; ] >
-<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
-
-<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_OM_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
- <filename>MACHINE</filename> 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 <filename>MACHINE</filename>
- 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 <filename>KMACHINE</filename>,
- <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
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink>
- 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).
- For complete information on BSP layer file hierarchy, see the
- <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
- </para>
-
- <section id='bsp-description-file-overview'>
- <title>Overview</title>
-
- <para>
- 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:
- <literallayout class='monospaced'>
- <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
- </literallayout>
- Here are some example root layer 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 root name (i.e "beaglebone") 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
- <filename>SRCREV</filename> 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
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>,
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>.
- </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
--->
diff --git a/poky/documentation/kernel-dev/kernel-dev-common.rst b/poky/documentation/kernel-dev/kernel-dev-common.rst
index d4b60a9..64235f3 100644
--- a/poky/documentation/kernel-dev/kernel-dev-common.rst
+++ b/poky/documentation/kernel-dev/kernel-dev-common.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-2.0-UK
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
************
Common Tasks
diff --git a/poky/documentation/kernel-dev/kernel-dev-common.xml b/poky/documentation/kernel-dev/kernel-dev-common.xml
deleted file mode 100644
index 8e8a6db..0000000
--- a/poky/documentation/kernel-dev/kernel-dev-common.xml
+++ /dev/null
@@ -1,2730 +0,0 @@
-<!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; ] >
-<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
-
-<chapter id='kernel-dev-common'>
-<title>Common Tasks</title>
-
- <para>
- This chapter presents several common tasks you perform when you
- work with the Yocto Project Linux kernel.
- These tasks include preparing your host development system for
- kernel development, preparing a layer, modifying an existing recipe,
- patching the kernel, configuring the kernel, iterative development,
- working with your own sources, and incorporating out-of-tree modules.
- <note>
- The examples presented in this chapter work with the Yocto Project
- 2.4 Release and forward.
- </note>
- </para>
-
- <section id='preparing-the-build-host-to-work-on-the-kernel'>
- <title>Preparing the Build Host to Work on the Kernel</title>
-
- <para>
- Before you can do any kernel development, you need to be
- sure your build host is set up to use the Yocto Project.
- For information on how to get set up, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
- section in the Yocto Project Development Tasks Manual.
- Part of preparing the system is creating a local Git
- repository of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- (<filename>poky</filename>) on your system.
- Follow the steps in the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
- section in the Yocto Project Development Tasks Manual to set up your
- Source Directory.
- <note>
- Be sure you check out the appropriate development branch or
- you create your local branch by checking out a specific tag
- to get the desired version of Yocto Project.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
- and
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
- sections in the Yocto Project Development Tasks Manual for more
- information.
- </note>
- </para>
-
- <para>
- Kernel development is best accomplished using
- <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
- and not through traditional kernel workflow methods.
- The remainder of this section provides information for both
- scenarios.
- </para>
-
- <section id='getting-ready-to-develop-using-devtool'>
- <title>Getting Ready to Develop Using <filename>devtool</filename></title>
-
- <para>
- Follow these steps to prepare to update the kernel image using
- <filename>devtool</filename>.
- Completing this procedure leaves you with a clean kernel image
- and ready to make modifications as described in the
- "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
- section:
- <orderedlist>
- <listitem><para>
- <emphasis>Initialize the BitBake Environment:</emphasis>
- Before building an extensible SDK, you need to
- initialize the BitBake build environment by sourcing the
- build environment script
- (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>):
- <literallayout class='monospaced'>
- $ cd ~/poky
- $ source oe-init-build-env
- </literallayout>
- <note>
- The previous commands assume the
- <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
- (i.e. <filename>poky</filename>) have been cloned
- using Git and the local repository is named
- "poky".
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis>
- By default, the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- variable is set to "qemux86-64", which is fine if you are
- building for the QEMU emulator in 64-bit mode.
- However, if you are not, you need to set the
- <filename>MACHINE</filename> variable appropriately in
- your <filename>conf/local.conf</filename> file found in
- the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- (i.e. <filename>~/poky/build</filename> in this
- example).</para>
-
- <para>Also, since you are preparing to work on the
- kernel image, you need to set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
- variable to include kernel modules.</para>
-
- <para>In this example we wish to build for qemux86 so
- we must set the <filename>MACHINE</filename> variable
- to "qemux86" and also add the "kernel-modules". As described
- we do this by appending to <filename>conf/local.conf</filename>:
- <literallayout class='monospaced'>
- MACHINE = "qemux86"
- MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Create a Layer for Patches:</emphasis>
- You need to create a layer to hold patches created
- for the kernel image.
- You can use the
- <filename>bitbake-layers create-layer</filename>
- command as follows:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ bitbake-layers create-layer ../../meta-mylayer
- NOTE: Starting bitbake server...
- Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
- $
- </literallayout>
- <note>
- For background information on working with
- common and BSP layers, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section in the Yocto Project Development Tasks
- Manual and the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
- section in the Yocto Project Board Support (BSP)
- Developer's Guide, respectively.
- For information on how to use the
- <filename>bitbake-layers create-layer</filename>
- command to quickly set up a layer, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
- section in the Yocto Project Development Tasks
- Manual.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Inform the BitBake Build Environment About
- Your Layer:</emphasis>
- As directed when you created your layer, you need to
- add the layer to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
- variable in the <filename>bblayers.conf</filename> file
- as follows:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ bitbake-layers add-layer ../../meta-mylayer
- NOTE: Starting bitbake server...
- $
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Extensible SDK:</emphasis>
- Use BitBake to build the extensible SDK specifically
- for use with images to be run using QEMU:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ bitbake core-image-minimal -c populate_sdk_ext
- </literallayout>
- Once the build finishes, you can find the SDK installer
- file (i.e. <filename>*.sh</filename> file) in the
- following directory:
- <literallayout class='monospaced'>
- ~/poky/build/tmp/deploy/sdk
- </literallayout>
- For this example, the installer file is named
- <filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename>
- </para></listitem>
- <listitem><para>
- <emphasis>Install the Extensible SDK:</emphasis>
- Use the following command to install the SDK.
- For this example, install the SDK in the default
- <filename>~/poky_sdk</filename> directory:
- <literallayout class='monospaced'>
- $ cd ~/poky/build/tmp/deploy/sdk
- $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
- Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
- ============================================================================
- Enter target directory for SDK (default: ~/poky_sdk):
- You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
- Extracting SDK......................................done
- Setting it up...
- Extracting buildtools...
- Preparing build system...
- Parsing recipes: 100% |#################################################################| Time: 0:00:52
- Initializing tasks: 100% |############## ###############################################| Time: 0:00:04
- Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00
- Parsing recipes: 100% |#################################################################| Time: 0:00:33
- Initializing tasks: 100% |##############################################################| Time: 0:00:00
- done
- SDK has been successfully set up and is ready to be used.
- Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
- $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
- </literallayout>
- </para></listitem>
- <listitem><para id='setting-up-the-esdk-terminal'>
- <emphasis>Set Up a New Terminal to Work With the
- Extensible SDK:</emphasis>
- You must set up a new terminal to work with the SDK.
- You cannot use the same BitBake shell used to build the
- installer.</para>
-
- <para>After opening a new shell, run the SDK environment
- setup script as directed by the output from installing
- the SDK:
- <literallayout class='monospaced'>
- $ source ~/poky_sdk/environment-setup-i586-poky-linux
- "SDK environment now set up; additionally you may now run devtool to perform development tasks.
- Run devtool --help for further details.
- </literallayout>
- <note>
- If you get a warning about attempting to use the
- extensible SDK in an environment set up to run
- BitBake, you did not use a new shell.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Clean Image:</emphasis>
- The final step in preparing to work on the kernel is to
- build an initial image using
- <filename>devtool</filename> in the new terminal you
- just set up and initialized for SDK work:
- <literallayout class='monospaced'>
- $ devtool build-image
- Parsing recipes: 100% |##########################################| Time: 0:00:05
- Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
- WARNING: No packages to add, building image core-image-minimal unmodified
- Loading cache: 100% |############################################| Time: 0:00:00
- Loaded 1299 entries from dependency cache.
- NOTE: Resolving any missing task queue dependencies
- Initializing tasks: 100% |#######################################| Time: 0:00:07
- Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
- NOTE: Executing SetScene Tasks
- NOTE: Executing RunQueue Tasks
- NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
- NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
- </literallayout>
- If you were building for actual hardware and not for
- emulation, you could flash the image to a USB stick
- on <filename>/dev/sdd</filename> and boot your device.
- For an example that uses a Minnowboard, see the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
- Wiki page.
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- At this point you have set up to start making modifications to
- the kernel by using the extensible SDK.
- For a continued example, see the
- "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
- section.
- </para>
- </section>
-
- <section id='getting-ready-for-traditional-kernel-development'>
- <title>Getting Ready for Traditional Kernel Development</title>
-
- <para>
- Getting ready for traditional kernel development using the Yocto
- Project involves many of the same steps as described in the
- previous section.
- However, you need to establish a local copy of the kernel source
- since you will be editing these files.
- </para>
-
- <para>
- Follow these steps to prepare to update the kernel image using
- traditional kernel development flow with the Yocto Project.
- Completing this procedure leaves you ready to make modifications
- to the kernel source as described in the
- "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
- section:
- <orderedlist>
- <listitem><para>
- <emphasis>Initialize the BitBake Environment:</emphasis>
- Before you can do anything using BitBake, you need to
- initialize the BitBake build environment by sourcing the
- build environment script
- (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>).
- Also, for this example, be sure that the local branch
- you have checked out for <filename>poky</filename> is
- the Yocto Project &DISTRO_NAME; branch.
- If you need to checkout out the &DISTRO_NAME; branch,
- see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking out by Branch in Poky</ulink>"
- section in the Yocto Project Development Tasks Manual.
- <literallayout class='monospaced'>
- $ cd ~/poky
- $ git branch
- master
- * &DISTRO_NAME;
- $ source oe-init-build-env
- </literallayout>
- <note>
- The previous commands assume the
- <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
- (i.e. <filename>poky</filename>) have been cloned
- using Git and the local repository is named
- "poky".
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Prepare Your <filename>local.conf</filename>
- File:</emphasis>
- By default, the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- variable is set to "qemux86-64", which is fine if you are
- building for the QEMU emulator in 64-bit mode.
- However, if you are not, you need to set the
- <filename>MACHINE</filename> variable appropriately in
- your <filename>conf/local.conf</filename> file found
- in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- (i.e. <filename>~/poky/build</filename> in this
- example).</para>
-
- <para>Also, since you are preparing to work on the
- kernel image, you need to set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
- variable to include kernel modules.</para>
-
- <para>In this example we wish to build for qemux86 so
- we must set the <filename>MACHINE</filename> variable
- to "qemux86" and also add the "kernel-modules". As described
- we do this by appending to <filename>conf/local.conf</filename>:
- <literallayout class='monospaced'>
- MACHINE = "qemux86"
- MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Create a Layer for Patches:</emphasis>
- You need to create a layer to hold patches created
- for the kernel image.
- You can use the
- <filename>bitbake-layers create-layer</filename>
- command as follows:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ bitbake-layers create-layer ../../meta-mylayer
- NOTE: Starting bitbake server...
- Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
- </literallayout>
- <note>
- For background information on working with
- common and BSP layers, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section in the Yocto Project Development Tasks
- Manual and the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
- section in the Yocto Project Board Support (BSP)
- Developer's Guide, respectively.
- For information on how to use the
- <filename>bitbake-layers create-layer</filename>
- command to quickly set up a layer, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
- section in the Yocto Project Development Tasks
- Manual.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Inform the BitBake Build Environment About
- Your Layer:</emphasis>
- As directed when you created your layer, you need to add
- the layer to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
- variable in the <filename>bblayers.conf</filename> file
- as follows:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ bitbake-layers add-layer ../../meta-mylayer
- NOTE: Starting bitbake server ...
- $
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Create a Local Copy of the Kernel Git
- Repository:</emphasis>
- You can find Git repositories of supported Yocto Project
- kernels organized under "Yocto Linux Kernel" in the
- Yocto Project Source Repositories at
- <ulink url='&YOCTO_GIT_URL;'></ulink>.
- </para>
-
- <para>
- For simplicity, it is recommended that you create your
- copy of the kernel Git repository outside of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
- which is usually named <filename>poky</filename>.
- Also, be sure you are in the
- <filename>standard/base</filename> branch.
- </para>
-
- <para>
- The following commands show how to create a local copy
- of the <filename>linux-yocto-4.12</filename> kernel and
- be in the <filename>standard/base</filename> branch.
- <note>
- The <filename>linux-yocto-4.12</filename> kernel
- can be used with the Yocto Project 2.4 release
- and forward.
- You cannot use the
- <filename>linux-yocto-4.12</filename> kernel with
- releases prior to Yocto Project 2.4:
- </note>
- <literallayout class='monospaced'>
- $ cd ~
- $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base
- Cloning into 'linux-yocto-4.12'...
- remote: Counting objects: 6097195, done.
- remote: Compressing objects: 100% (901026/901026), done.
- remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256)
- Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done.
- Resolving deltas: 100% (5152604/5152604), done.
- Checking connectivity... done.
- Checking out files: 100% (59846/59846), done.
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Create a Local Copy of the Kernel Cache Git
- Repository:</emphasis>
- For simplicity, it is recommended that you create your
- copy of the kernel cache Git repository outside of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
- which is usually named <filename>poky</filename>.
- Also, for this example, be sure you are in the
- <filename>yocto-4.12</filename> branch.
- </para>
-
- <para>
- The following commands show how to create a local copy
- of the <filename>yocto-kernel-cache</filename> and
- be in the <filename>yocto-4.12</filename> branch:
- <literallayout class='monospaced'>
- $ cd ~
- $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
- Cloning into 'yocto-kernel-cache'...
- remote: Counting objects: 22639, done.
- remote: Compressing objects: 100% (9761/9761), done.
- remote: Total 22639 (delta 12400), reused 22586 (delta 12347)
- Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done.
- Resolving deltas: 100% (12400/12400), done.
- Checking connectivity... done.
- </literallayout>
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- At this point, you are ready to start making modifications to
- the kernel using traditional kernel development steps.
- For a continued example, see the
- "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
- section.
- </para>
- </section>
- </section>
-
- <section id='creating-and-preparing-a-layer'>
- <title>Creating and Preparing a Layer</title>
-
- <para>
- If you are going to be modifying kernel recipes, it is recommended
- that you create and prepare your own layer in which to do your
- work.
- Your layer contains its own
- <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
- append files (<filename>.bbappend</filename>) and provides a
- convenient mechanism to create your own recipe files
- (<filename>.bb</filename>) as well as store and use kernel
- patch files.
- For background information on working with layers, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section in the Yocto Project Development Tasks Manual.
- <note><title>Tip</title>
- The Yocto Project comes with many tools that simplify
- tasks you need to perform.
- One such tool is the
- <filename>bitbake-layers create-layer</filename>
- command, which simplifies creating a new layer.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
- section in the Yocto Project Development Tasks Manual for
- information on how to use this script to quick set up a
- new layer.
- </note>
- </para>
-
- <para>
- To better understand the layer you create for kernel development,
- the following section describes how to create a layer
- without the aid of tools.
- These steps assume creation of a layer named
- <filename>mylayer</filename> in your home directory:
- <orderedlist>
- <listitem><para>
- <emphasis>Create Structure</emphasis>:
- Create the layer's structure:
- <literallayout class='monospaced'>
- $ cd $HOME
- $ mkdir meta-mylayer
- $ mkdir meta-mylayer/conf
- $ mkdir meta-mylayer/recipes-kernel
- $ mkdir meta-mylayer/recipes-kernel/linux
- $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto
- </literallayout>
- The <filename>conf</filename> directory holds your
- configuration files, while the
- <filename>recipes-kernel</filename> directory holds your
- append file and eventual patch files.
- </para></listitem>
- <listitem><para>
- <emphasis>Create the Layer Configuration File</emphasis>:
- Move to the <filename>meta-mylayer/conf</filename>
- directory and create the <filename>layer.conf</filename>
- file as follows:
- <literallayout class='monospaced'>
- # We have a conf and classes directory, add to BBPATH
- BBPATH .= ":${LAYERDIR}"
-
- # We have recipes-* directories, add to BBFILES
- BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
- ${LAYERDIR}/recipes-*/*/*.bbappend"
-
- BBFILE_COLLECTIONS += "mylayer"
- BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
- BBFILE_PRIORITY_mylayer = "5"
- </literallayout>
- Notice <filename>mylayer</filename> as part of the last
- three statements.
- </para></listitem>
- <listitem><para>
- <emphasis>Create the Kernel Recipe Append File</emphasis>:
- Move to the
- <filename>meta-mylayer/recipes-kernel/linux</filename>
- directory and create the kernel's append file.
- This example uses the
- <filename>linux-yocto-4.12</filename> kernel.
- Thus, the name of the append file is
- <filename>linux-yocto_4.12.bbappend</filename>:
- <literallayout class='monospaced'>
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
-
- SRC_URI_append = " file://<replaceable>patch-file-one</replaceable>"
- SRC_URI_append = " file://<replaceable>patch-file-two</replaceable>"
- SRC_URI_append = " file://<replaceable>patch-file-three</replaceable>"
- </literallayout>
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- statements enable the OpenEmbedded build system to find
- patch files.
- For more information on using append files, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='modifying-an-existing-recipe'>
- <title>Modifying an Existing Recipe</title>
-
- <para>
- In many cases, you can customize an existing linux-yocto recipe to
- meet the needs of your project.
- Each release of the Yocto Project provides a few Linux
- kernel recipes from which you can choose.
- These are located in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- in <filename>meta/recipes-kernel/linux</filename>.
- </para>
-
- <para>
- Modifying an existing recipe can consist of the following:
- <itemizedlist>
- <listitem><para>Creating the append file</para></listitem>
- <listitem><para>Applying patches</para></listitem>
- <listitem><para>Changing the configuration</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Before modifying an existing recipe, be sure that you have created
- a minimal, custom layer from which you can work.
- See the
- "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
- section for information.
- </para>
-
- <section id='creating-the-append-file'>
- <title>Creating the Append File</title>
-
- <para>
- You create this file in your custom layer.
- You also name it accordingly based on the linux-yocto recipe
- you are using.
- For example, if you are modifying the
- <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
- recipe, the append file will typically be located as follows
- within your custom layer:
- <literallayout class='monospaced'>
- <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.12.bbappend
- </literallayout>
- The append file should initially extend the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
- search path by prepending the directory that contains your
- files to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- variable as follows:
- <literallayout class='monospaced'>
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
- </literallayout>
- The path <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>
- expands to "linux-yocto" in the current directory for this
- example.
- If you add any new files that modify the kernel recipe and you
- have extended <filename>FILESPATH</filename> as
- described above, you must place the files in your layer in the
- following area:
- <literallayout class='monospaced'>
- <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/
- </literallayout>
- <note>If you are working on a new machine Board Support Package
- (BSP), be sure to refer to the
- <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
- </note>
- </para>
-
- <para>
- As an example, consider the following append file
- used by the BSPs in <filename>meta-yocto-bsp</filename>:
- <literallayout class='monospaced'>
- meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
- </literallayout>
- The following listing shows the file.
- Be aware that the actual commit ID strings in this
- example listing might be different than the actual strings
- in the file from the <filename>meta-yocto-bsp</filename>
- layer upstream.
- <literallayout class='monospaced'>
- KBRANCH_genericx86 = "standard/base"
- KBRANCH_genericx86-64 = "standard/base"
-
- KMACHINE_genericx86 ?= "common-pc"
- KMACHINE_genericx86-64 ?= "common-pc-64"
- KBRANCH_edgerouter = "standard/edgerouter"
- KBRANCH_beaglebone = "standard/beaglebone"
-
- SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
- SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
- SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
- SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
-
-
- COMPATIBLE_MACHINE_genericx86 = "genericx86"
- COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
- COMPATIBLE_MACHINE_edgerouter = "edgerouter"
- COMPATIBLE_MACHINE_beaglebone = "beaglebone"
-
- LINUX_VERSION_genericx86 = "4.12.7"
- LINUX_VERSION_genericx86-64 = "4.12.7"
- LINUX_VERSION_edgerouter = "4.12.10"
- LINUX_VERSION_beaglebone = "4.12.10"
- </literallayout>
- This append file contains statements used to support
- several BSPs that ship with the Yocto Project.
- The file defines machines using the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
- variable and uses the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
- variable to ensure the machine name used by the OpenEmbedded
- build system maps to the machine name used by the Linux Yocto
- kernel.
- The file also uses the optional
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
- variable to ensure the build process uses the
- appropriate kernel branch.
- </para>
-
- <para>
- Although this particular example does not use it, the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
- variable could be used to enable features specific to
- the kernel.
- The append file points to specific commits in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- Git repository and the <filename>meta</filename> Git repository
- branches to identify the exact kernel needed to build the
- BSP.
- </para>
-
- <para>
- One thing missing in this particular BSP, which you will
- typically need when developing a BSP, is the kernel
- configuration file (<filename>.config</filename>) for your BSP.
- When developing a BSP, you probably have a kernel configuration
- file or a set of kernel configuration files that, when taken
- together, define the kernel configuration for your BSP.
- You can accomplish this definition by putting the configurations
- in a file or a set of files inside a directory located at the
- same level as your kernel's append file and having the same
- name as the kernel's main recipe file.
- With all these conditions met, simply reference those files in
- the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- statement in the append file.
- </para>
-
- <para>
- For example, suppose you had some configuration options
- in a file called <filename>network_configs.cfg</filename>.
- You can place that file inside a directory named
- <filename>linux-yocto</filename> and then add
- a <filename>SRC_URI</filename> statement such as the
- following to the append file.
- When the OpenEmbedded build system builds the kernel, the
- configuration options are picked up and applied.
- <literallayout class='monospaced'>
- SRC_URI += "file://network_configs.cfg"
- </literallayout>
- </para>
-
- <para>
- To group related configurations into multiple files, you
- perform a similar procedure.
- Here is an example that groups separate configurations
- specifically for Ethernet and graphics into their own
- files and adds the configurations by using a
- <filename>SRC_URI</filename> statement like the following
- in your append file:
- <literallayout class='monospaced'>
- SRC_URI += "file://myconfig.cfg \
- file://eth.cfg \
- file://gfx.cfg"
- </literallayout>
- </para>
-
- <para>
- Another variable you can use in your kernel recipe append
- file is the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- variable.
- When you use this statement, you are extending the locations
- used by the OpenEmbedded system to look for files and
- patches as the recipe is processed.
- </para>
-
- <note>
- <para>
- Other methods exist to accomplish grouping and defining
- configuration options.
- For example, if you are working with a local clone of the
- kernel repository, you could checkout the kernel's
- <filename>meta</filename> branch, make your changes, and
- then push the changes to the local bare clone of the
- kernel.
- The result is that you directly add configuration options
- to the <filename>meta</filename> branch for your BSP.
- The configuration options will likely end up in that
- location anyway if the BSP gets added to the Yocto Project.
- </para>
-
- <para>
- In general, however, the Yocto Project maintainers take
- care of moving the <filename>SRC_URI</filename>-specified
- configuration options to the kernel's
- <filename>meta</filename> branch.
- Not only is it easier for BSP developers to not have to
- worry about putting those configurations in the branch,
- but having the maintainers do it allows them to apply
- 'global' knowledge about the kinds of common configuration
- options multiple BSPs in the tree are typically using.
- This allows for promotion of common configurations into
- common features.
- </para>
- </note>
- </section>
-
- <section id='applying-patches'>
- <title>Applying Patches</title>
-
- <para>
- If you have a single patch or a small series of patches
- that you want to apply to the Linux kernel source, you
- can do so just as you would with any other recipe.
- You first copy the patches to the path added to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- in your <filename>.bbappend</filename> file as described in
- the previous section, and then reference them in
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- statements.
- </para>
-
- <para>
- For example, you can apply a three-patch series by adding the
- following lines to your linux-yocto
- <filename>.bbappend</filename> file in your layer:
- <literallayout class='monospaced'>
- SRC_URI += "file://0001-first-change.patch"
- SRC_URI += "file://0002-second-change.patch"
- SRC_URI += "file://0003-third-change.patch"
- </literallayout>
- The next time you run BitBake to build the Linux kernel,
- BitBake detects the change in the recipe and fetches and
- applies the patches before building the kernel.
- </para>
-
- <para>
- For a detailed example showing how to patch the kernel using
- <filename>devtool</filename>, 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='changing-the-configuration'>
- <title>Changing the Configuration</title>
-
- <para>
- You can make wholesale or incremental changes to the final
- <filename>.config</filename> file used for the eventual
- Linux kernel configuration by including a
- <filename>defconfig</filename> file and by specifying
- configuration fragments in the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- to be applied to that file.
- </para>
-
- <para>
- If you have a complete, working Linux kernel
- <filename>.config</filename>
- file you want to use for the configuration, as before, copy
- that file to the appropriate <filename>${PN}</filename>
- directory in your layer's
- <filename>recipes-kernel/linux</filename> directory,
- and rename the copied file to "defconfig".
- Then, add the following lines to the linux-yocto
- <filename>.bbappend</filename> file in your layer:
- <literallayout class='monospaced'>
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
- SRC_URI += "file://defconfig"
- </literallayout>
- The <filename>SRC_URI</filename> tells the build system how to
- search for the file, while the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- extends the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
- variable (search directories) to include the
- <filename>${PN}</filename> directory you created to hold the
- configuration changes.
- </para>
-
- <note>
- The build system applies the configurations from the
- <filename>defconfig</filename> file before applying any
- subsequent configuration fragments.
- The final kernel configuration is a combination of the
- configurations in the <filename>defconfig</filename> file and
- any configuration fragments you provide.
- You need to realize that if you have any configuration
- fragments, the build system applies these on top of and
- after applying the existing <filename>defconfig</filename>
- file configurations.
- </note>
-
- <para>
- Generally speaking, the preferred approach is to determine the
- incremental change you want to make and add that as a
- configuration fragment.
- For example, if you want to add support for a basic serial
- console, create a file named <filename>8250.cfg</filename> in
- the <filename>${PN}</filename> directory with the following
- content (without indentation):
- <literallayout class='monospaced'>
- CONFIG_SERIAL_8250=y
- CONFIG_SERIAL_8250_CONSOLE=y
- CONFIG_SERIAL_8250_PCI=y
- CONFIG_SERIAL_8250_NR_UARTS=4
- CONFIG_SERIAL_8250_RUNTIME_UARTS=4
- CONFIG_SERIAL_CORE=y
- CONFIG_SERIAL_CORE_CONSOLE=y
- </literallayout>
- Next, include this configuration fragment and extend the
- <filename>FILESPATH</filename> variable in your
- <filename>.bbappend</filename> file:
- <literallayout class='monospaced'>
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
- SRC_URI += "file://8250.cfg"
- </literallayout>
- The next time you run BitBake to build the Linux kernel, BitBake
- detects the change in the recipe and fetches and applies the
- new configuration before building the kernel.
- </para>
-
- <para>
- For a detailed example showing how to configure the kernel,
- see the
- "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
- section.
- </para>
- </section>
-
- <section id='using-an-in-tree-defconfig-file'>
- <title>Using an "In-Tree" <filename>defconfig</filename> File</title>
-
- <para>
- It might be desirable to have kernel configuration fragment
- support through a <filename>defconfig</filename> file that
- is pulled from the kernel source tree for the configured
- machine.
- By default, the OpenEmbedded build system looks for
- <filename>defconfig</filename> files in the layer used for
- Metadata, which is "out-of-tree", and then configures them
- using the following:
- <literallayout class='monospaced'>
- SRC_URI += "file://defconfig"
- </literallayout>
- If you do not want to maintain copies of
- <filename>defconfig</filename> files in your layer but would
- rather allow users to use the default configuration from the
- kernel tree and still be able to add configuration fragments
- to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- through, for example, append files, you can direct the
- OpenEmbedded build system to use a
- <filename>defconfig</filename> file that is "in-tree".
- </para>
-
- <para>
- To specify an "in-tree" <filename>defconfig</filename> file,
- use the following statement form:
- <literallayout class='monospaced'>
- KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
- </literallayout>
- Here is an example that assigns the
- <filename>KBUILD_DEFCONFIG</filename> variable based on
- "raspberrypi2" and provides the path to the "in-tree"
- <filename>defconfig</filename> file
- to be used for a Raspberry Pi 2,
- which is based on the Broadcom 2708/2709 chipset:
- <literallayout class='monospaced'>
- KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig"
- </literallayout>
- </para>
-
- <para>
- Aside from modifying your kernel recipe and providing your own
- <filename>defconfig</filename> file, you need to be sure no
- files or statements set <filename>SRC_URI</filename> to use a
- <filename>defconfig</filename> other than your "in-tree"
- file (e.g. a kernel's
- <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename>
- file).
- In other words, if the build system detects a statement
- that identifies an "out-of-tree"
- <filename>defconfig</filename> file, that statement
- will override your
- <filename>KBUILD_DEFCONFIG</filename> variable.
- </para>
-
- <para>
- See the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink>
- variable description for more information.
- </para>
- </section>
- </section>
-
- <section id="using-devtool-to-patch-the-kernel">
- <title>Using <filename>devtool</filename> to Patch the Kernel</title>
-
- <para>
- The steps in this procedure show you how you can patch the
- kernel using the extensible SDK and <filename>devtool</filename>.
- <note>
- Before attempting this procedure, be sure you have performed
- the steps to get ready for updating the kernel as described
- in the
- "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
- section.
- </note>
- </para>
-
- <para>
- Patching the kernel involves changing or adding configurations
- to an existing kernel, changing or adding recipes to the kernel
- that are needed to support specific hardware features, or even
- altering the source code itself.
- </para>
-
- <para>
- This example creates a simple patch by adding some QEMU emulator
- console output at boot time through <filename>printk</filename>
- statements in the kernel's <filename>calibrate.c</filename> source
- code file.
- Applying the patch and booting the modified image causes the added
- messages to appear on the emulator's console.
- The example is a continuation of the setup procedure found in
- the
- "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
- Section.
- <orderedlist>
- <listitem><para>
- <emphasis>Check Out the Kernel Source Files:</emphasis>
- First you must use <filename>devtool</filename> to checkout
- the kernel source code in its workspace.
- Be sure you are in the terminal set up to do work
- with the extensible SDK.
- <note>
- See this
- <link linkend='setting-up-the-esdk-terminal'>step</link>
- in the
- "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
- section for more information.
- </note>
- Use the following <filename>devtool</filename> command
- to check out the code:
- <literallayout class='monospaced'>
- $ devtool modify linux-yocto
- </literallayout>
- <note>
- During the checkout operation, a bug exists that could
- cause errors such as the following to appear:
- <literallayout class='monospaced'>
- ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
- be3a89ce7c47178880ba7bf6293d7404 for
- /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
- </literallayout>
- You can safely ignore these messages.
- The source code is correctly checked out.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Edit the Source Files</emphasis>
- Follow these steps to make some simple changes to the source
- files:
- <orderedlist>
- <listitem><para>
- <emphasis>Change the working directory</emphasis>:
- In the previous step, the output noted where you can find
- the source files (e.g.
- <filename>~/poky_sdk/workspace/sources/linux-yocto</filename>).
- Change to where the kernel source code is before making
- your edits to the <filename>calibrate.c</filename> file:
- <literallayout class='monospaced'>
- $ cd ~/poky_sdk/workspace/sources/linux-yocto
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Edit the source file</emphasis>:
- Edit the <filename>init/calibrate.c</filename> file to have
- the following changes:
- <literallayout class='monospaced'>
- void calibrate_delay(void)
- {
- unsigned long lpj;
- static bool printed;
- int this_cpu = smp_processor_id();
-
- printk("*************************************\n");
- printk("* *\n");
- printk("* HELLO YOCTO KERNEL *\n");
- printk("* *\n");
- printk("*************************************\n");
-
- if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
- .
- .
- .
- </literallayout>
- </para></listitem>
- </orderedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Updated Kernel Source:</emphasis>
- To build the updated kernel source, use
- <filename>devtool</filename>:
- <literallayout class='monospaced'>
- $ devtool build linux-yocto
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Create the Image With the New Kernel:</emphasis>
- Use the <filename>devtool build-image</filename> command
- to create a new image that has the new kernel.
- <note>
- If the image you originally created resulted in a Wic
- file, you can use an alternate method to create the new
- image with the updated kernel.
- For an example, see the steps in the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink>
- Wiki Page.
- </note>
- <literallayout class='monospaced'>
- $ cd ~
- $ devtool build-image core-image-minimal
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Test the New Image:</emphasis>
- For this example, you can run the new image using QEMU
- to verify your changes:
- <orderedlist>
- <listitem><para>
- <emphasis>Boot the image</emphasis>:
- Boot the modified image in the QEMU emulator
- using this command:
- <literallayout class='monospaced'>
- $ runqemu qemux86
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Verify the changes</emphasis>:
- Log into the machine using <filename>root</filename>
- with no password and then use the following shell
- command to scroll through the console's boot output.
- <literallayout class='monospaced'>
- # dmesg | less
- </literallayout>
- You should see the results of your
- <filename>printk</filename> statements
- as part of the output when you scroll down the
- console window.
- </para></listitem>
- </orderedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Stage and commit your changes</emphasis>:
- Within your eSDK terminal, change your working directory to
- where you modified the <filename>calibrate.c</filename>
- file and use these Git commands to stage and commit your
- changes:
- <literallayout class='monospaced'>
- $ cd ~/poky_sdk/workspace/sources/linux-yocto
- $ git status
- $ git add init/calibrate.c
- $ git commit -m "calibrate: Add printk example"
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Export the Patches and Create an Append File:</emphasis>
- To export your commits as patches and create a
- <filename>.bbappend</filename> file, use the following
- command in the terminal used to work with the extensible
- SDK.
- This example uses the previously established layer named
- <filename>meta-mylayer</filename>.
- <note>
- See Step 3 of the
- "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using devtool</link>"
- section for information on setting up this layer.
- </note>
- <literallayout class='monospaced'>
- $ devtool finish linux-yocto ~/meta-mylayer
- </literallayout>
- Once the command finishes, the patches and the
- <filename>.bbappend</filename> file are located in the
- <filename>~/meta-mylayer/recipes-kernel/linux</filename>
- directory.
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Image With Your Modified Kernel:</emphasis>
- You can now build an image that includes your kernel
- patches.
- Execute the following command from your
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- in the terminal set up to run BitBake:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ bitbake core-image-minimal
- </literallayout>
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id="using-traditional-kernel-development-to-patch-the-kernel">
- <title>Using Traditional Kernel Development to Patch the Kernel</title>
-
- <para>
- The steps in this procedure show you how you can patch the
- kernel using traditional kernel development (i.e. not using
- <filename>devtool</filename> and the extensible SDK as
- described in the
- "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
- section).
- <note>
- Before attempting this procedure, be sure you have performed
- the steps to get ready for updating the kernel as described
- in the
- "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
- section.
- </note>
- </para>
-
- <para>
- Patching the kernel involves changing or adding configurations
- to an existing kernel, changing or adding recipes to the kernel
- that are needed to support specific hardware features, or even
- altering the source code itself.
- </para>
-
- <para>
- The example in this section creates a simple patch by adding some
- QEMU emulator console output at boot time through
- <filename>printk</filename> statements in the kernel's
- <filename>calibrate.c</filename> source code file.
- Applying the patch and booting the modified image causes the added
- messages to appear on the emulator's console.
- The example is a continuation of the setup procedure found in
- the
- "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
- Section.
- <orderedlist>
- <listitem><para>
- <emphasis>Edit the Source Files</emphasis>
- Prior to this step, you should have used Git to create a
- local copy of the repository for your kernel.
- Assuming you created the repository as directed in the
- "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
- section, use the following commands to edit the
- <filename>calibrate.c</filename> file:
- <orderedlist>
- <listitem><para>
- <emphasis>Change the working directory</emphasis>:
- You need to locate the source files in the
- local copy of the kernel Git repository:
- Change to where the kernel source code is before making
- your edits to the <filename>calibrate.c</filename> file:
- <literallayout class='monospaced'>
- $ cd ~/linux-yocto-4.12/init
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Edit the source file</emphasis>:
- Edit the <filename>calibrate.c</filename> file to have
- the following changes:
- <literallayout class='monospaced'>
- void calibrate_delay(void)
- {
- unsigned long lpj;
- static bool printed;
- int this_cpu = smp_processor_id();
-
- printk("*************************************\n");
- printk("* *\n");
- printk("* HELLO YOCTO KERNEL *\n");
- printk("* *\n");
- printk("*************************************\n");
-
- if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
- .
- .
- .
- </literallayout>
- </para></listitem>
- </orderedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Stage and Commit Your Changes:</emphasis>
- Use standard Git commands to stage and commit the changes
- you just made:
- <literallayout class='monospaced'>
- $ git add calibrate.c
- $ git commit -m "calibrate.c - Added some printk statements"
- </literallayout>
- If you do not stage and commit your changes, the OpenEmbedded
- Build System will not pick up the changes.
- </para></listitem>
- <listitem><para>
- <emphasis>Update Your <filename>local.conf</filename> File
- to Point to Your Source Files:</emphasis>
- In addition to your <filename>local.conf</filename> file
- specifying to use "kernel-modules" and the "qemux86"
- machine, it must also point to the updated kernel source
- files.
- Add
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
- statements similar to the following to your
- <filename>local.conf</filename>:
- <literallayout class='monospaced'>
- $ cd ~/poky/build/conf
- </literallayout>
- Add the following to the <filename>local.conf</filename>:
- <literallayout class='monospaced'>
- SRC_URI_pn-linux-yocto = "git:///<replaceable>path-to</replaceable>/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
- git:///<replaceable>path-to</replaceable>/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
- SRCREV_meta_qemux86 = "${AUTOREV}"
- SRCREV_machine_qemux86 = "${AUTOREV}"
- </literallayout>
- <note>
- Be sure to replace
- <replaceable>path-to</replaceable> with the pathname
- to your local Git repositories.
- Also, you must be sure to specify the correct branch
- and machine types.
- For this example, the branch is
- <filename>standard/base</filename> and the machine is
- "qemux86".
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Image:</emphasis>
- With the source modified, your changes staged and
- committed, and the <filename>local.conf</filename> file
- pointing to the kernel files, you can now use BitBake to
- build the image:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ bitbake core-image-minimal
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Boot the image</emphasis>:
- Boot the modified image in the QEMU emulator
- using this command.
- When prompted to login to the QEMU console, use "root"
- with no password:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ runqemu qemux86
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Look for Your Changes:</emphasis>
- As QEMU booted, you might have seen your changes rapidly
- scroll by.
- If not, use these commands to see your changes:
- <literallayout class='monospaced'>
- # dmesg | less
- </literallayout>
- You should see the results of your
- <filename>printk</filename> statements
- as part of the output when you scroll down the
- console window.
- </para></listitem>
- <listitem><para>
- <emphasis>Generate the Patch File:</emphasis>
- Once you are sure that your patch works correctly, you
- can generate a <filename>*.patch</filename> file in the
- kernel source repository:
- <literallayout class='monospaced'>
- $ cd ~/linux-yocto-4.12/init
- $ git format-patch -1
- 0001-calibrate.c-Added-some-printk-statements.patch
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Move the Patch File to Your Layer:</emphasis>
- In order for subsequent builds to pick up patches, you
- need to move the patch file you created in the previous
- step to your layer <filename>meta-mylayer</filename>.
- For this example, the layer created earlier is located
- in your home directory as <filename>meta-mylayer</filename>.
- When the layer was created using the
- <filename>yocto-create</filename> script, no additional
- hierarchy was created to support patches.
- Before moving the patch file, you need to add additional
- structure to your layer using the following commands:
- <literallayout class='monospaced'>
- $ cd ~/meta-mylayer
- $ mkdir recipes-kernel
- $ mkdir recipes-kernel/linux
- $ mkdir recipes-kernel/linux/linux-yocto
- </literallayout>
- Once you have created this hierarchy in your layer, you can
- move the patch file using the following command:
- <literallayout class='monospaced'>
- $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Create the Append File:</emphasis>
- Finally, you need to create the
- <filename>linux-yocto_4.12.bbappend</filename> file and
- insert statements that allow the OpenEmbedded build
- system to find the patch.
- The append file needs to be in your layer's
- <filename>recipes-kernel/linux</filename>
- directory and it must be named
- <filename>linux-yocto_4.12.bbappend</filename> and have
- the following contents:
- <literallayout class='monospaced'>
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
-
- SRC_URI_append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
- </literallayout>
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- statements enable the OpenEmbedded build system to find
- the patch file.</para>
-
- <para>For more information on append files and patches,
- see the
- "<link linkend='creating-the-append-file'>Creating the Append File</link>"
- and
- "<link linkend='applying-patches'>Applying Patches</link>"
- sections.
- You can also see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer"</ulink>"
- section in the Yocto Project Development Tasks Manual.
- <note>
- To build <filename>core-image-minimal</filename>
- again and see the effects of your patch, you can
- essentially eliminate the temporary source files
- saved in <filename>poky/build/tmp/work/...</filename>
- and residual effects of the build by entering the
- following sequence of commands:
- <literallayout class='monospaced'>
- $ cd ~/poky/build
- $ bitbake -c cleanall yocto-linux
- $ bitbake core-image-minimal -c cleanall
- $ bitbake core-image-minimal
- $ runqemu qemux86
- </literallayout>
- </note>
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='configuring-the-kernel'>
- <title>Configuring the Kernel</title>
-
- <para>
- Configuring the Yocto Project kernel consists of making sure the
- <filename>.config</filename> file has all the right information
- in it for the image you are building.
- You can use the <filename>menuconfig</filename> tool and
- configuration fragments to make sure your
- <filename>.config</filename> file is just how you need it.
- You can also save known configurations in a
- <filename>defconfig</filename> file that the build system can use
- for kernel configuration.
- </para>
-
- <para>
- This section describes how to use <filename>menuconfig</filename>,
- create and use configuration fragments, and how to interactively
- modify your <filename>.config</filename> file to create the
- leanest kernel configuration file possible.
- </para>
-
- <para>
- For more information on kernel configuration, see the
- "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
- section.
- </para>
-
- <section id='using-menuconfig'>
- <title>Using <filename>menuconfig</filename></title>
-
- <para>
- The easiest way to define kernel configurations is to set
- them through the <filename>menuconfig</filename> tool.
- This tool provides an interactive method with which
- to set kernel configurations.
- For general information on <filename>menuconfig</filename>, see
- <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
- </para>
-
- <para>
- To use the <filename>menuconfig</filename> tool in the Yocto
- Project development environment, you must do the following:
- <itemizedlist>
- <listitem><para>
- Because you launch <filename>menuconfig</filename>
- using BitBake, you must be sure to set up your
- environment by running the
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
- script found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
- </para></listitem>
- <listitem><para>
- You must be sure of the state of your build's
- configuration in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- </para></listitem>
- <listitem><para>
- Your build host must have the following two packages
- installed:
- <literallayout class='monospaced'>
- libncurses5-dev
- libtinfo-dev
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The following commands initialize the BitBake environment,
- run the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink>
- task, and launch <filename>menuconfig</filename>.
- These commands assume the Source Directory's top-level folder
- is <filename>~/poky</filename>:
- <literallayout class='monospaced'>
- $ cd poky
- $ source oe-init-build-env
- $ bitbake linux-yocto -c kernel_configme -f
- $ bitbake linux-yocto -c menuconfig
- </literallayout>
- Once <filename>menuconfig</filename> comes up, its standard
- interface allows you to interactively examine and configure
- all the kernel configuration parameters.
- After making your changes, simply exit the tool and save your
- changes to create an updated version of the
- <filename>.config</filename> configuration file.
- <note>
- You can use the entire <filename>.config</filename> file
- as the <filename>defconfig</filename> file.
- For information on <filename>defconfig</filename> files,
- see the
- "<link linkend='changing-the-configuration'>Changing the Configuration</link>",
- "<link linkend='using-an-in-tree-defconfig-file'>Using an In-Tree <filename>defconfig</filename> File</link>,
- and
- "<link linkend='creating-a-defconfig-file'>Creating a <filename>defconfig</filename> File</link>"
- sections.
- </note>
- </para>
-
- <para>
- Consider an example that configures the "CONFIG_SMP" setting
- for the <filename>linux-yocto-4.12</filename> kernel.
- <note>
- The OpenEmbedded build system recognizes this kernel as
- <filename>linux-yocto</filename> through Metadata (e.g.
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink><filename>_linux-yocto ?= "12.4%"</filename>).
- </note>
- Once <filename>menuconfig</filename> launches, use the
- interface to navigate through the selections to find the
- configuration settings in which you are interested.
- For this example, you deselect "CONFIG_SMP" by clearing the
- "Symmetric Multi-Processing Support" option.
- Using the interface, you can find the option under
- "Processor Type and Features".
- To deselect "CONFIG_SMP", use the arrow keys to
- highlight "Symmetric Multi-Processing Support" and enter "N"
- to clear the asterisk.
- When you are finished, exit out and save the change.
- </para>
-
- <para>
- Saving the selections updates the <filename>.config</filename>
- configuration file.
- This is the file that the OpenEmbedded build system uses to
- configure the kernel during the build.
- You can find and examine this file in the Build Directory in
- <filename>tmp/work/</filename>.
- The actual <filename>.config</filename> is located in the
- area where the specific kernel is built.
- For example, if you were building a Linux Yocto kernel based
- on the <filename>linux-yocto-4.12</filename> kernel and you
- were building a QEMU image targeted for
- <filename>x86</filename> architecture, the
- <filename>.config</filename> file would be:
- <literallayout class='monospaced'>
- poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
- ...967-r0/linux-qemux86-standard-build/.config
- </literallayout>
- <note>
- The previous example directory is artificially split and
- many of the characters in the actual filename are omitted
- in order to make it more readable.
- Also, depending on the kernel you are using, the exact
- pathname might differ.
- </note>
- </para>
-
- <para>
- Within the <filename>.config</filename> file, you can see the
- kernel settings.
- For example, the following entry shows that symmetric
- multi-processor support is not set:
- <literallayout class='monospaced'>
- # CONFIG_SMP is not set
- </literallayout>
- </para>
-
- <para>
- A good method to isolate changed configurations is to use a
- combination of the <filename>menuconfig</filename> tool and
- simple shell commands.
- Before changing configurations with
- <filename>menuconfig</filename>, copy the existing
- <filename>.config</filename> and rename it to something else,
- use <filename>menuconfig</filename> to make as many changes as
- you want and save them, then compare the renamed configuration
- file against the newly created file.
- You can use the resulting differences as your base to create
- configuration fragments to permanently save in your kernel
- layer.
- <note>
- Be sure to make a copy of the <filename>.config</filename>
- file and do not just rename it.
- The build system needs an existing
- <filename>.config</filename> file from which to work.
- </note>
- </para>
- </section>
-
- <section id='creating-a-defconfig-file'>
- <title>Creating a <filename>defconfig</filename> File</title>
-
- <para>
- A <filename>defconfig</filename> file in the context of
- the Yocto Project is often a <filename>.config</filename>
- file that is copied from a build or a
- <filename>defconfig</filename> taken from the kernel tree
- and moved into recipe space.
- You can use a <filename>defconfig</filename> file
- to retain a known set of kernel configurations from which the
- OpenEmbedded build system can draw to create the final
- <filename>.config</filename> file.
- <note>
- Out-of-the-box, the Yocto Project never ships a
- <filename>defconfig</filename> or
- <filename>.config</filename> file.
- The OpenEmbedded build system creates the final
- <filename>.config</filename> file used to configure the
- kernel.
- </note>
- </para>
-
- <para>
- To create a <filename>defconfig</filename>, start with a
- complete, working Linux kernel <filename>.config</filename>
- file.
- Copy that file to the appropriate
- <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
- directory in your layer's
- <filename>recipes-kernel/linux</filename> directory, and rename
- the copied file to "defconfig" (e.g.
- <filename>~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig</filename>).
- Then, add the following lines to the linux-yocto
- <filename>.bbappend</filename> file in your layer:
- <literallayout class='monospaced'>
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
- SRC_URI += "file://defconfig"
- </literallayout>
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- tells the build system how to search for the file, while the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- extends the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
- variable (search directories) to include the
- <filename>${PN}</filename> directory you created to hold the
- configuration changes.
- <note>
- The build system applies the configurations from the
- <filename>defconfig</filename> file before applying any
- subsequent configuration fragments.
- The final kernel configuration is a combination of the
- configurations in the <filename>defconfig</filename>
- file and any configuration fragments you provide.
- You need to realize that if you have any configuration
- fragments, the build system applies these on top of and
- after applying the existing defconfig file configurations.
- </note>
- For more information on configuring the kernel, see the
- "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
- section.
- </para>
- </section>
-
- <section id='creating-config-fragments'>
- <title>Creating Configuration Fragments</title>
-
- <para>
- Configuration fragments are simply kernel options that
- appear in a file placed where the OpenEmbedded build system
- can find and apply them.
- The build system applies configuration fragments after
- applying configurations from a <filename>defconfig</filename>
- file.
- Thus, the final kernel configuration is a combination of the
- configurations in the <filename>defconfig</filename>
- file and then any configuration fragments you provide.
- The build system applies fragments on top of and
- after applying the existing defconfig file configurations.
- </para>
-
- <para>
- Syntactically, the configuration statement is identical to
- what would appear in the <filename>.config</filename> file,
- which is in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
- <note>
- For more information about where the
- <filename>.config</filename> file is located, see the
- example in the
- "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
- section.
- </note>
- </para>
-
- <para>
- It is simple to create a configuration fragment.
- One method is to use shell commands.
- For example, issuing the following from the shell creates a
- configuration fragment file named
- <filename>my_smp.cfg</filename> that enables multi-processor
- support within the kernel:
- <literallayout class='monospaced'>
- $ echo "CONFIG_SMP=y" >> my_smp.cfg
- </literallayout>
- <note>
- All configuration fragment files must use the
- <filename>.cfg</filename> extension in order for the
- OpenEmbedded build system to recognize them as a
- configuration fragment.
- </note>
- </para>
-
- <para>
- Another method is to create a configuration fragment using the
- differences between two configuration files: one previously
- created and saved, and one freshly created using the
- <filename>menuconfig</filename> tool.
- </para>
-
- <para>
- To create a configuration fragment using this method, follow
- these steps:
- <orderedlist>
- <listitem><para>
- <emphasis>Complete a Build Through Kernel Configuration:</emphasis>
- Complete a build at least through the kernel
- configuration task as follows:
- <literallayout class='monospaced'>
- $ bitbake linux-yocto -c kernel_configme -f
- </literallayout>
- This step ensures that you create a
- <filename>.config</filename> file from a known state.
- Because situations exist where your build state might
- become unknown, it is best to run this task prior
- to starting <filename>menuconfig</filename>.
- </para></listitem>
- <listitem><para>
- <emphasis>Launch <filename>menuconfig</filename>:</emphasis>
- Run the <filename>menuconfig</filename> command:
- <literallayout class='monospaced'>
- $ bitbake linux-yocto -c menuconfig
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Create the Configuration Fragment:</emphasis>
- Run the <filename>diffconfig</filename>
- command to prepare a configuration fragment.
- The resulting file <filename>fragment.cfg</filename>
- is placed in the
- <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory:
- <literallayout class='monospaced'>
- $ bitbake linux-yocto -c diffconfig
- </literallayout>
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- The <filename>diffconfig</filename> command creates a file
- that is a list of Linux kernel <filename>CONFIG_</filename>
- assignments.
- See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
- section for additional information on how to use the output
- as a configuration fragment.
- <note>
- You can also use this method to create configuration
- fragments for a BSP.
- See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
- section for more information.
- </note>
- </para>
-
- <para>
- Where do you put your configuration fragment files?
- You can place these files in an area pointed to by
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- as directed by your <filename>bblayers.conf</filename> file,
- which is located in your layer.
- The OpenEmbedded build system picks up the configuration and
- adds it to the kernel's configuration.
- For example, suppose you had a set of configuration options
- in a file called <filename>myconfig.cfg</filename>.
- If you put that file inside a directory named
- <filename>linux-yocto</filename> that resides in the same
- directory as the kernel's append file within your layer
- and then add the following statements to the kernel's append
- file, those configuration options will be picked up and applied
- when the kernel is built:
- <literallayout class='monospaced'>
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
- SRC_URI += "file://myconfig.cfg"
- </literallayout>
- </para>
-
- <para>
- As mentioned earlier, you can group related configurations
- into multiple files and name them all in the
- <filename>SRC_URI</filename> statement as well.
- For example, you could group separate configurations
- specifically for Ethernet and graphics into their own files
- and add those by using a <filename>SRC_URI</filename> statement
- like the following in your append file:
- <literallayout class='monospaced'>
- SRC_URI += "file://myconfig.cfg \
- file://eth.cfg \
- file://gfx.cfg"
- </literallayout>
- </para>
- </section>
-
- <section id='validating-configuration'>
- <title>Validating Configuration</title>
-
- <para>
- You can use the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink>
- task to provide configuration validation:
- <literallayout class='monospaced'>
- $ bitbake linux-yocto -c kernel_configcheck -f
- </literallayout>
- Running this task produces warnings for when a
- requested configuration does not appear in the final
- <filename>.config</filename> file or when you override a
- policy configuration in a hardware configuration fragment.
- </para>
-
- <para>
- In order to run this task, you must have an existing
- <filename>.config</filename> file.
- See the
- "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
- section for information on how to create a configuration file.
- </para>
-
- <para>
- Following is sample output from the
- <filename>do_kernel_configcheck</filename> task:
- <literallayout class='monospaced'>
- Loading cache: 100% |########################################################| Time: 0:00:00
- Loaded 1275 entries from dependency cache.
- NOTE: Resolving any missing task queue dependencies
-
- Build Configuration:
- .
- .
- .
-
- NOTE: Executing SetScene Tasks
- NOTE: Executing RunQueue Tasks
- WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
- [kernel config]: specified values did not make it into the kernel's final configuration:
-
- ---------- CONFIG_X86_TSC -----------------
- Config: CONFIG_X86_TSC
- From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
- Requested value: CONFIG_X86_TSC=y
- Actual value:
-
-
- ---------- CONFIG_X86_BIGSMP -----------------
- Config: CONFIG_X86_BIGSMP
- From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
- Requested value: # CONFIG_X86_BIGSMP is not set
- Actual value:
-
-
- ---------- CONFIG_NR_CPUS -----------------
- Config: CONFIG_NR_CPUS
- From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
- /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
- Requested value: CONFIG_NR_CPUS=8
- Actual value: CONFIG_NR_CPUS=1
-
-
- ---------- CONFIG_SCHED_SMT -----------------
- Config: CONFIG_SCHED_SMT
- From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
- Requested value: CONFIG_SCHED_SMT=y
- Actual value:
-
-
-
- NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded.
-
- Summary: There were 3 WARNING messages shown.
- </literallayout>
- <note>
- The previous output example has artificial line breaks
- to make it more readable.
- </note>
- </para>
-
- <para>
- The output describes the various problems that you can
- encounter along with where to find the offending configuration
- items.
- You can use the information in the logs to adjust your
- configuration files and then repeat the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink>
- tasks until they produce no warnings.
- </para>
-
- <para>
- For more information on how to use the
- <filename>menuconfig</filename> tool, see the
- "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
- section.
- </para>
- </section>
-
- <section id='fine-tuning-the-kernel-configuration-file'>
- <title>Fine-Tuning the Kernel Configuration File</title>
-
- <para>
- You can make sure the <filename>.config</filename> file is as
- lean or efficient as possible by reading the output of the
- kernel configuration fragment audit, noting any issues, making
- changes to correct the issues, and then repeating.
- </para>
-
- <para>
- As part of the kernel build process, the
- <filename>do_kernel_configcheck</filename> task runs.
- This task validates the kernel configuration by checking the
- final <filename>.config</filename> file against the input
- files.
- During the check, the task produces warning messages for the
- following issues:
- <itemizedlist>
- <listitem><para>
- Requested options that did not make the final
- <filename>.config</filename> file.
- </para></listitem>
- <listitem><para>
- Configuration items that appear twice in the same
- configuration fragment.
- </para></listitem>
- <listitem><para>
- Configuration items tagged as "required" that were
- overridden.
- </para></listitem>
- <listitem><para>
- A board overrides a non-board specific option.
- </para></listitem>
- <listitem><para>
- Listed options not valid for the kernel being
- processed.
- In other words, the option does not appear anywhere.
- </para></listitem>
- </itemizedlist>
- <note>
- The <filename>do_kernel_configcheck</filename> task can
- also optionally report if an option is overridden during
- processing.
- </note>
- </para>
-
- <para>
- For each output warning, a message points to the file
- that contains a list of the options and a pointer to the
- configuration fragment that defines them.
- Collectively, the files are the key to streamlining the
- configuration.
- </para>
-
- <para>
- To streamline the configuration, do the following:
- <orderedlist>
- <listitem><para>
- <emphasis>Use a Working Configuration:</emphasis>
- Start with a full configuration that you
- know works.
- Be sure the configuration builds and boots
- successfully.
- Use this configuration file as your baseline.
- </para></listitem>
- <listitem><para>
- <emphasis>Run Configure and Check Tasks:</emphasis>
- Separately run the
- <filename>do_kernel_configme</filename> and
- <filename>do_kernel_configcheck</filename> tasks:
- <literallayout class='monospaced'>
- $ bitbake linux-yocto -c kernel_configme -f
- $ bitbake linux-yocto -c kernel_configcheck -f
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Process the Results:</emphasis>
- Take the resulting list of files from the
- <filename>do_kernel_configcheck</filename> task
- warnings and do the following:
- <itemizedlist>
- <listitem><para>
- Drop values that are redefined in the fragment
- but do not change the final
- <filename>.config</filename> file.
- </para></listitem>
- <listitem><para>
- Analyze and potentially drop values from the
- <filename>.config</filename> file that override
- required configurations.
- </para></listitem>
- <listitem><para>
- Analyze and potentially remove non-board
- specific options.
- </para></listitem>
- <listitem><para>
- Remove repeated and invalid options.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Re-Run Configure and Check Tasks:</emphasis>
- After you have worked through the output of the kernel
- configuration audit, you can re-run the
- <filename>do_kernel_configme</filename> and
- <filename>do_kernel_configcheck</filename> tasks to
- see the results of your changes.
- If you have more issues, you can deal with them as
- described in the previous step.
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- Iteratively working through steps two through four eventually
- yields a minimal, streamlined configuration file.
- Once you have the best <filename>.config</filename>, you can
- build the Linux Yocto kernel.
- </para>
- </section>
- </section>
-
- <section id='expanding-variables'>
- <title>Expanding Variables</title>
-
- <para>
- Sometimes it is helpful to determine what a variable expands
- to during a build.
- You can do examine the values of variables by examining the
- output of the <filename>bitbake -e</filename> command.
- The output is long and is more easily managed in a text file,
- which allows for easy searches:
- <literallayout class='monospaced'>
- $ bitbake -e virtual/kernel > <replaceable>some_text_file</replaceable>
- </literallayout>
- Within the text file, you can see exactly how each variable is
- expanded and used by the OpenEmbedded build system.
- </para>
- </section>
-
- <section id='working-with-a-dirty-kernel-version-string'>
- <title>Working with a "Dirty" Kernel Version String</title>
-
- <para>
- If you build a kernel image and the version string has a
- "+" or a "-dirty" at the end, uncommitted modifications exist
- in the kernel's source directory.
- Follow these steps to clean up the version string:
- <orderedlist>
- <listitem><para>
- <emphasis>Discover the Uncommitted Changes:</emphasis>
- Go to the kernel's locally cloned Git repository
- (source directory) and use the following Git command
- to list the files that have been changed, added, or
- removed:
- <literallayout class='monospaced'>
- $ git status
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Commit the Changes:</emphasis>
- You should commit those changes to the kernel source
- tree regardless of whether or not you will save,
- export, or use the changes:
- <literallayout class='monospaced'>
- $ git add
- $ git commit -s -a -m "getting rid of -dirty"
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Rebuild the Kernel Image:</emphasis>
- Once you commit the changes, rebuild the kernel.</para>
-
- <para>Depending on your particular kernel development
- workflow, the commands you use to rebuild the
- kernel might differ.
- For information on building the kernel image when
- using <filename>devtool</filename>, see the
- "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
- section.
- For information on building the kernel image when
- using Bitbake, see the
- "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
- section.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='working-with-your-own-sources'>
- <title>Working With Your Own Sources</title>
-
- <para>
- If you cannot work with one of the Linux kernel
- versions supported by existing linux-yocto recipes, you can
- still make use of the Yocto Project Linux kernel tooling by
- working with your own sources.
- When you use your own sources, you will not be able to
- leverage the existing kernel
- <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> and
- stabilization work of the linux-yocto sources.
- However, you will be able to manage your own Metadata in the same
- format as the linux-yocto sources.
- Maintaining format compatibility facilitates converging with
- linux-yocto on a future, mutually-supported kernel version.
- </para>
-
- <para>
- To help you use your own sources, the Yocto Project provides a
- linux-yocto custom recipe
- (<filename>linux-yocto-custom.bb</filename>) that uses
- <filename>kernel.org</filename> sources
- and the Yocto Project Linux kernel tools for managing
- kernel Metadata.
- You can find this recipe in the
- <filename>poky</filename> Git repository of the
- Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
- at:
- <literallayout class="monospaced">
- poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
- </literallayout>
- </para>
-
- <para>
- Here are some basic steps you can use to work with your own
- sources:
- <orderedlist>
- <listitem><para>
- <emphasis>Create a Copy of the Kernel Recipe:</emphasis>
- Copy the <filename>linux-yocto-custom.bb</filename>
- recipe to your layer and give it a meaningful name.
- The name should include the version of the Yocto Linux
- kernel you are using (e.g.
- <filename>linux-yocto-myproject_4.12.bb</filename>,
- where "4.12" is the base version of the Linux kernel
- with which you would be working).
- </para></listitem>
- <listitem><para>
- <emphasis>Create a Directory for Your Patches:</emphasis>
- In the same directory inside your layer, create a matching
- directory to store your patches and configuration files
- (e.g. <filename>linux-yocto-myproject</filename>).
- </para></listitem>
- <listitem><para>
- <emphasis>Ensure You Have Configurations:</emphasis>
- Make sure you have either a <filename>defconfig</filename>
- file or configuration fragment files in your layer.
- When you use the <filename>linux-yocto-custom.bb</filename>
- recipe, you must specify a configuration.
- If you do not have a <filename>defconfig</filename> file,
- you can run the following:
- <literallayout class='monospaced'>
- $ make defconfig
- </literallayout>
- After running the command, copy the resulting
- <filename>.config</filename> file to the
- <filename>files</filename> directory in your layer
- as "defconfig" and then add it to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- variable in the recipe.</para>
-
- <para>Running the <filename>make defconfig</filename>
- command results in the default configuration for your
- architecture as defined by your kernel.
- However, no guarantee exists that this configuration is
- valid for your use case, or that your board will even boot.
- This is particularly true for non-x86 architectures.</para>
-
- <para>To use non-x86 <filename>defconfig</filename> files,
- you need to be more specific and find one that matches your
- board (i.e. for arm, you look in
- <filename>arch/arm/configs</filename> and use the one that
- is the best starting point for your board).
- </para></listitem>
- <listitem><para>
- <emphasis>Edit the Recipe:</emphasis>
- Edit the following variables in your recipe as appropriate
- for your project:
- <itemizedlist>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
- The <filename>SRC_URI</filename> should specify
- a Git repository that uses one of the supported Git
- fetcher protocols (i.e. <filename>file</filename>,
- <filename>git</filename>, <filename>http</filename>,
- and so forth).
- The <filename>SRC_URI</filename> variable should
- also specify either a <filename>defconfig</filename>
- file or some configuration fragment files.
- The skeleton recipe provides an example
- <filename>SRC_URI</filename> as a syntax reference.
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
- The Linux kernel version you are using (e.g.
- "4.12").
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
- The Linux kernel
- <filename>CONFIG_LOCALVERSION</filename> that is
- compiled into the resulting kernel and visible
- through the <filename>uname</filename> command.
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
- The commit ID from which you want to build.
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
- Treat this variable the same as you would in any
- other recipe.
- Increment the variable to indicate to the
- OpenEmbedded build system that the recipe has
- changed.
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
- The default <filename>PV</filename> assignment is
- typically adequate.
- It combines the <filename>LINUX_VERSION</filename>
- with the Source Control Manager (SCM) revision
- as derived from the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
- variable.
- The combined results are a string with the
- following form:
- <literallayout class='monospaced'>
- 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
- </literallayout>
- While lengthy, the extra verbosity in
- <filename>PV</filename> helps ensure you are using
- the exact sources from which you intend to build.
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
- A list of the machines supported by your new recipe.
- This variable in the example recipe is set
- by default to a regular expression that matches
- only the empty string, "(^$)".
- This default setting triggers an explicit build
- failure.
- You must change it to match a list of the machines
- that your new recipe supports.
- For example, to support the
- <filename>qemux86</filename> and
- <filename>qemux86-64</filename> machines, use
- the following form:
- <literallayout class='monospaced'>
- COMPATIBLE_MACHINE = "qemux86|qemux86-64"
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Customize Your Recipe as Needed:</emphasis>
- Provide further customizations to your recipe
- as needed just as you would customize an existing
- linux-yocto recipe.
- See the
- "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
- section for information.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='working-with-out-of-tree-modules'>
- <title>Working with Out-of-Tree Modules</title>
-
- <para>
- This section describes steps to build out-of-tree modules on
- your target and describes how to incorporate out-of-tree modules
- in the build.
- </para>
-
- <section id='building-out-of-tree-modules-on-the-target'>
- <title>Building Out-of-Tree Modules on the Target</title>
-
- <para>
- While the traditional Yocto Project development model would be
- to include kernel modules as part of the normal build
- process, you might find it useful to build modules on the
- target.
- This could be the case if your target system is capable
- and powerful enough to handle the necessary compilation.
- Before deciding to build on your target, however, you should
- consider the benefits of using a proper cross-development
- environment from your build host.
- </para>
-
- <para>
- If you want to be able to build out-of-tree modules on
- the target, there are some steps you need to take
- on the target that is running your SDK image.
- Briefly, the <filename>kernel-dev</filename> package
- is installed by default on all
- <filename>*.sdk</filename> images and the
- <filename>kernel-devsrc</filename> package is installed
- on many of the <filename>*.sdk</filename> images.
- However, you need to create some scripts prior to
- attempting to build the out-of-tree modules on the target
- that is running that image.
- </para>
-
- <para>
- Prior to attempting to build the out-of-tree modules,
- you need to be on the target as root and you need to
- change to the <filename>/usr/src/kernel</filename> directory.
- Next, <filename>make</filename> the scripts:
- <literallayout class='monospaced'>
- # cd /usr/src/kernel
- # make scripts
- </literallayout>
- Because all SDK image recipes include
- <filename>dev-pkgs</filename>, the
- <filename>kernel-dev</filename> packages will be installed
- as part of the SDK image and the
- <filename>kernel-devsrc</filename> packages will be installed
- as part of applicable SDK images.
- The SDK uses the scripts when building out-of-tree
- modules.
- Once you have switched to that directory and created the
- scripts, you should be able to build your out-of-tree modules
- on the target.
- </para>
- </section>
-
- <section id='incorporating-out-of-tree-modules'>
- <title>Incorporating Out-of-Tree Modules</title>
-
- <para>
- While it is always preferable to work with sources integrated
- into the Linux kernel sources, if you need an external kernel
- module, the <filename>hello-mod.bb</filename> recipe is
- available as a template from which you can create your
- own out-of-tree Linux kernel module recipe.
- </para>
-
- <para>
- This template recipe is located in the
- <filename>poky</filename> Git repository of the
- Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
- at:
- <literallayout class="monospaced">
- poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
- </literallayout>
- </para>
-
- <para>
- To get started, copy this recipe to your layer and give it a
- meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
- In the same directory, create a new directory named
- <filename>files</filename> where you can store any source files,
- patches, or other files necessary for building
- the module that do not come with the sources.
- Finally, update the recipe as needed for the module.
- Typically, you will need to set the following variables:
- <itemizedlist>
- <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
- </para></listitem>
- <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
- </para></listitem>
- <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- </para></listitem>
- <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Depending on the build system used by the module sources,
- you might need to make some adjustments.
- For example, a typical module <filename>Makefile</filename>
- looks much like the one provided with the
- <filename>hello-mod</filename> template:
- <literallayout class='monospaced'>
- obj-m := hello.o
-
- SRC := $(shell pwd)
-
- all:
- $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
-
- modules_install:
- $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
- ...
- </literallayout>
- </para>
-
- <para>
- The important point to note here is the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
- variable.
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink>
- class sets this variable and the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
- variable to
- <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
- with the necessary Linux kernel build information to build
- modules.
- If your module <filename>Makefile</filename> uses a different
- variable, you might want to override the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
- step, or create a patch to
- the <filename>Makefile</filename> to work with the more typical
- <filename>KERNEL_SRC</filename> or
- <filename>KERNEL_PATH</filename> variables.
- </para>
-
- <para>
- After you have prepared your recipe, you will likely want to
- include the module in your images.
- To do this, see the documentation for the following variables in
- the Yocto Project Reference Manual and set one of them
- appropriately for your machine configuration file:
- <itemizedlist>
- <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
- </para></listitem>
- <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
- </para></listitem>
- <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
- </para></listitem>
- <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Modules are often not required for boot and can be excluded from
- certain build configurations.
- The following allows for the most flexibility:
- <literallayout class='monospaced'>
- MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
- </literallayout>
- The value is derived by appending the module filename without
- the <filename>.ko</filename> extension to the string
- "kernel-module-".
- </para>
-
- <para>
- Because the variable is
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
- and not a
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
- variable, the build will not fail if this module is not
- available to include in the image.
- </para>
- </section>
- </section>
-
-
- <section id='inspecting-changes-and-commits'>
- <title>Inspecting Changes and Commits</title>
-
- <para>
- A common question when working with a kernel is:
- "What changes have been applied to this tree?"
- Rather than using "grep" across directories to see what has
- changed, you can use Git to inspect or search the kernel tree.
- Using Git is an efficient way to see what has changed in the tree.
- </para>
-
- <section id='what-changed-in-a-kernel'>
- <title>What Changed in a Kernel?</title>
-
- <para>
- Following are a few examples that show how to use Git
- commands to examine changes.
- These examples are by no means the only way to see changes.
- <note>
- In the following examples, unless you provide a commit
- range, <filename>kernel.org</filename> history is blended
- with Yocto Project kernel changes.
- You can form ranges by using branch names from the
- kernel tree as the upper and lower commit markers with
- the Git commands.
- You can see the branch names through the web interface
- to the Yocto Project source repositories at
- <ulink url='&YOCTO_GIT_URL;'></ulink>.
- </note>
- To see a full range of the changes, use the
- <filename>git whatchanged</filename> command and specify a
- commit range for the branch
- (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>).
- </para>
-
- <para>
- Here is an example that looks at what has changed in the
- <filename>emenlow</filename> branch of the
- <filename>linux-yocto-3.19</filename> kernel.
- The lower commit range is the commit associated with the
- <filename>standard/base</filename> branch, while
- the upper commit range is the commit associated with the
- <filename>standard/emenlow</filename> branch.
- <literallayout class='monospaced'>
- $ git whatchanged origin/standard/base..origin/standard/emenlow
- </literallayout>
- </para>
-
- <para>
- To see short, one line summaries of changes use the
- <filename>git log</filename> command:
- <literallayout class='monospaced'>
- $ git log --oneline origin/standard/base..origin/standard/emenlow
- </literallayout>
- </para>
-
- <para>
- Use this command to see code differences for the changes:
- <literallayout class='monospaced'>
- $ git diff origin/standard/base..origin/standard/emenlow
- </literallayout>
- </para>
-
- <para>
- Use this command to see the commit log messages and the
- text differences:
- <literallayout class='monospaced'>
- $ git show origin/standard/base..origin/standard/emenlow
- </literallayout>
- </para>
-
- <para>
- Use this command to create individual patches for
- each change.
- Here is an example that that creates patch files for each
- commit and places them in your <filename>Documents</filename>
- directory:
- <literallayout class='monospaced'>
- $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
- </literallayout>
- </para>
- </section>
-
- <section id='showing-a-particular-feature-or-branch-change'>
- <title>Showing a Particular Feature or Branch Change</title>
-
- <para>
- Tags in the Yocto Project kernel tree divide changes for
- significant features or branches.
- The <filename>git show</filename> <replaceable>tag</replaceable>
- command shows changes based on a tag.
- Here is an example that shows <filename>systemtap</filename>
- changes:
- <literallayout class='monospaced'>
- $ git show systemtap
- </literallayout>
- You can use the
- <filename>git branch --contains</filename> <replaceable>tag</replaceable>
- command to show the branches that contain a particular feature.
- This command shows the branches that contain the
- <filename>systemtap</filename> feature:
- <literallayout class='monospaced'>
- $ git branch --contains systemtap
- </literallayout>
- </para>
- </section>
- </section>
-
- <section id='adding-recipe-space-kernel-features'>
- <title>Adding Recipe-Space Kernel Features</title>
-
- <para>
- You can add kernel features in the
- <link linkend='recipe-space-metadata'>recipe-space</link> by
- using the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
- variable and by specifying the feature's <filename>.scc</filename>
- file path in the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- statement.
- When you add features using this method, the OpenEmbedded build
- system checks to be sure the features are present.
- If the features are not present, the build stops.
- Kernel features are the last elements processed for configuring
- and patching the kernel.
- Therefore, adding features in this manner is a way
- to enforce specific features are present and enabled
- without needing to do a full audit of any other layer's additions
- to the <filename>SRC_URI</filename> statement.
- </para>
-
- <para>
- You add a kernel feature by providing the feature as part of the
- <filename>KERNEL_FEATURES</filename> variable and by providing the
- path to the feature's <filename>.scc</filename> file, which is
- relative to the root of the kernel Metadata.
- The OpenEmbedded build system searches all forms of kernel
- Metadata on the <filename>SRC_URI</filename> statement regardless
- of whether the Metadata is in the "kernel-cache", system kernel
- Metadata, or a recipe-space Metadata (i.e. part of the kernel
- recipe).
- See the
- "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>"
- section for additional information.
- </para>
-
- <para>
- When you specify the feature's <filename>.scc</filename> file
- on the <filename>SRC_URI</filename> statement, the OpenEmbedded
- build system adds the directory of that
- <filename>.scc</filename> file along with all its subdirectories
- to the kernel feature search path.
- Because subdirectories are searched, you can reference a single
- <filename>.scc</filename> file in the
- <filename>SRC_URI</filename> statement to reference multiple kernel
- features.
- </para>
-
- <para>
- Consider the following example that adds the "test.scc" feature
- to the build.
- <orderedlist>
- <listitem><para>
- <emphasis>Create the Feature File:</emphasis>
- Create a <filename>.scc</filename> file and locate it
- just as you would any other patch file,
- <filename>.cfg</filename> file, or fetcher item
- you specify in the <filename>SRC_URI</filename>
- statement.
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- You must add the directory of the
- <filename>.scc</filename> file to the fetcher's
- search path in the same manner as you would
- add a <filename>.patch</filename> file.
- </para></listitem>
- <listitem><para>
- You can create additional
- <filename>.scc</filename> files beneath the
- directory that contains the file you are
- adding.
- All subdirectories are searched during the
- build as potential feature directories.
- </para></listitem>
- </itemizedlist>
- </note>
- Continuing with the example, suppose the "test.scc"
- feature you are adding has a
- <filename>test.scc</filename> file in the following
- directory:
- <literallayout class='monospaced'>
- <replaceable>my_recipe</replaceable>
- |
- +-linux-yocto
- |
- +-test.cfg
- +-test.scc
- </literallayout>
- In this example, the <filename>linux-yocto</filename>
- directory has both the feature
- <filename>test.scc</filename> file and a similarly
- named configuration fragment file
- <filename>test.cfg</filename>.
- </para></listitem>
- <listitem><para>
- <emphasis>Add the Feature File to <filename>SRC_URI</filename>:</emphasis>
- Add the <filename>.scc</filename> file to the
- recipe's <filename>SRC_URI</filename> statement:
- <literallayout class='monospaced'>
- SRC_URI_append = " file://test.scc"
- </literallayout>
- The leading space before the path is important as the
- path is appended to the existing path.
- </para></listitem>
- <listitem><para>
- <emphasis>Specify the Feature as a Kernel Feature:</emphasis>
- Use the <filename>KERNEL_FEATURES</filename> statement
- to specify the feature as a kernel feature:
- <literallayout class='monospaced'>
- KERNEL_FEATURES_append = " test.scc"
- </literallayout>
- The OpenEmbedded build system processes the kernel feature
- when it builds the kernel.
- <note>
- If other features are contained below "test.scc",
- then their directories are relative to the directory
- containing the <filename>test.scc</filename> file.
- </note>
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.rst b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.rst
index 04cb117..5b6ebef 100644
--- a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.rst
+++ b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-2.0-UK
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
************************
Advanced Kernel Concepts
diff --git a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
deleted file mode 100644
index bf0c525..0000000
--- a/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ /dev/null
@@ -1,622 +0,0 @@
-<!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; ] >
-<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
-
-<appendix id='kernel-dev-concepts-appx'>
-<title>Advanced Kernel Concepts</title>
-
- <section id='kernel-big-picture'>
- <title>Yocto Project Kernel Development and Maintenance</title>
-
- <para>
- Kernels available through the Yocto Project (Yocto Linux kernels),
- like other kernels, are based off the Linux kernel releases from
- <ulink url='http://www.kernel.org'></ulink>.
- At the beginning of a major Linux kernel development cycle, the
- Yocto Project team chooses a Linux kernel based on factors such as
- release timing, the anticipated release timing of final upstream
- <filename>kernel.org</filename> versions, and Yocto Project
- feature requirements.
- Typically, the Linux kernel chosen is in the final stages of
- development by the Linux community.
- In other words, the Linux kernel is in the release candidate
- or "rc" phase and has yet to reach final release.
- But, by being in the final stages of external development, the
- team knows that the <filename>kernel.org</filename> final release
- will clearly be within the early stages of the Yocto Project
- development window.
- </para>
-
- <para>
- This balance allows the Yocto Project team to deliver the most
- up-to-date Yocto Linux kernel possible, while still ensuring that
- the team has a stable official release for the baseline Linux
- kernel version.
- </para>
-
- <para>
- As implied earlier, the ultimate source for Yocto Linux kernels
- are released kernels from <filename>kernel.org</filename>.
- In addition to a foundational kernel from
- <filename>kernel.org</filename>, the available Yocto Linux kernels
- contain a mix of important new mainline developments, non-mainline
- developments (when no alternative exists), Board Support Package
- (BSP) developments, and custom features.
- These additions result in a commercially released Yocto
- Project Linux kernel that caters to specific embedded designer
- needs for targeted hardware.
- </para>
-
- <para>
- You can find a web interface to the Yocto Linux kernels in the
- <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
- at
- <ulink url='&YOCTO_GIT_URL;'></ulink>.
- If you look at the interface, you will see to the left a
- grouping of Git repositories titled "Yocto Linux Kernel".
- Within this group, you will find several Linux Yocto kernels
- developed and included with Yocto Project releases:
- <itemizedlist>
- <listitem><para>
- <emphasis><filename>linux-yocto-4.1</filename>:</emphasis>
- The stable Yocto Project kernel to use with the Yocto
- Project Release 2.0.
- This kernel is based on the Linux 4.1 released kernel.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>linux-yocto-4.4</filename>:</emphasis>
- The stable Yocto Project kernel to use with the Yocto
- Project Release 2.1.
- This kernel is based on the Linux 4.4 released kernel.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>linux-yocto-4.6</filename>:</emphasis>
- A temporary kernel that is not tied to any Yocto Project
- release.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>linux-yocto-4.8</filename>:</emphasis>
- The stable yocto Project kernel to use with the Yocto
- Project Release 2.2.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>linux-yocto-4.9</filename>:</emphasis>
- The stable Yocto Project kernel to use with the Yocto
- Project Release 2.3.
- This kernel is based on the Linux 4.9 released kernel.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>linux-yocto-4.10</filename>:</emphasis>
- The default stable Yocto Project kernel to use with the
- Yocto Project Release 2.3.
- This kernel is based on the Linux 4.10 released kernel.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>linux-yocto-4.12</filename>:</emphasis>
- The default stable Yocto Project kernel to use with the
- Yocto Project Release 2.4.
- This kernel is based on the Linux 4.12 released kernel.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>yocto-kernel-cache</filename>:</emphasis>
- The <filename>linux-yocto-cache</filename> contains
- patches and configurations for the linux-yocto kernel
- tree.
- This repository is useful when working on the linux-yocto
- kernel.
- For more information on this "Advanced Kernel Metadata",
- see the
- "<link linkend='kernel-dev-advanced'>Working With Advanced Metadata (<filename>yocto-kernel-cache</filename>)</link>"
- Chapter.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>linux-yocto-dev</filename>:</emphasis>
- A development kernel based on the latest upstream release
- candidate available.
- </para></listitem>
- </itemizedlist>
- <note><title>Notes</title>
- Long Term Support Initiative (LTSI) for Yocto Linux
- kernels is as follows:
- <itemizedlist>
- <listitem><para>
- For Yocto Project releases 1.7, 1.8, and 2.0,
- the LTSI kernel is
- <filename>linux-yocto-3.14</filename>.
- </para></listitem>
- <listitem><para>
- For Yocto Project releases 2.1, 2.2, and 2.3,
- the LTSI kernel is <filename>linux-yocto-4.1</filename>.
- </para></listitem>
- <listitem><para>
- For Yocto Project release 2.4, the LTSI kernel is
- <filename>linux-yocto-4.9</filename>
- </para></listitem>
- <listitem><para>
- <filename>linux-yocto-4.4</filename> is an LTS
- kernel.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <para>
- Once a Yocto Linux kernel is officially released, the Yocto
- Project team goes into their next development cycle, or upward
- revision (uprev) cycle, while still continuing maintenance on the
- released kernel.
- It is important to note that the most sustainable and stable way
- to include feature development upstream is through a kernel uprev
- process.
- Back-porting hundreds of individual fixes and minor features from
- various kernel versions is not sustainable and can easily
- compromise quality.
- </para>
-
- <para>
- During the uprev cycle, the Yocto Project team uses an ongoing
- analysis of Linux kernel development, BSP support, and release
- timing to select the best possible <filename>kernel.org</filename>
- Linux kernel version on which to base subsequent Yocto Linux
- kernel development.
- The team continually monitors Linux community kernel development
- to look for significant features of interest.
- The team does consider back-porting large features if they have a
- significant advantage.
- User or community demand can also trigger a back-port or creation
- of new functionality in the Yocto Project baseline kernel during
- the uprev cycle.
- </para>
-
- <para>
- Generally speaking, every new Linux kernel both adds features and
- introduces new bugs.
- These consequences are the basic properties of upstream
- Linux kernel development and are managed by the Yocto Project
- team's Yocto Linux kernel development strategy.
- It is the Yocto Project team's policy to not back-port minor
- features to the released Yocto Linux kernel.
- They only consider back-porting significant technological
- jumps ‐ and, that is done after a complete gap analysis.
- The reason for this policy is that back-porting any small to
- medium sized change from an evolving Linux kernel can easily
- create mismatches, incompatibilities and very subtle errors.
- </para>
-
- <para>
- The policies described in this section result in both a stable
- and a cutting edge Yocto Linux kernel that mixes forward ports of
- existing Linux kernel features and significant and critical new
- functionality.
- Forward porting Linux kernel functionality into the Yocto Linux
- kernels available through the Yocto Project can be thought of as
- a "micro uprev."
- The many "micro uprevs" produce a Yocto Linux kernel version with
- a mix of important new mainline, non-mainline, BSP developments
- and feature integrations.
- This Yocto Linux kernel gives insight into new features and
- allows focused amounts of testing to be done on the kernel,
- which prevents surprises when selecting the next major uprev.
- The quality of these cutting edge Yocto Linux kernels is evolving
- and the kernels are used in leading edge feature and BSP
- development.
- </para>
- </section>
-
- <section id='yocto-linux-kernel-architecture-and-branching-strategies'>
- <title>Yocto Linux Kernel Architecture and Branching Strategies</title>
-
- <para>
- As mentioned earlier, a key goal of the Yocto Project is
- to present the developer with a kernel that has a clear and
- continuous history that is visible to the user.
- The architecture and mechanisms, in particular the branching
- strategies, used achieve that goal in a manner similar to
- upstream Linux kernel development in
- <filename>kernel.org</filename>.
- </para>
-
- <para>
- You can think of a Yocto Linux kernel as consisting of a
- baseline Linux kernel with added features logically structured
- on top of the baseline.
- The features are tagged and organized by way of a branching
- strategy implemented by the Yocto Project team using the
- Source Code Manager (SCM) Git.
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- Git is the obvious SCM for meeting the Yocto Linux
- kernel organizational and structural goals described
- in this section.
- Not only is Git the SCM for Linux kernel development in
- <filename>kernel.org</filename> but, Git continues to
- grow in popularity and supports many different work
- flows, front-ends and management techniques.
- </para></listitem>
- <listitem><para>
- You can find documentation on Git at
- <ulink url='http://git-scm.com/documentation'></ulink>.
- You can also get an introduction to Git as it
- applies to the Yocto Project in the
- "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
- section in the Yocto Project Overview and Concepts
- Manual.
- The latter reference provides an overview of
- Git and presents a minimal set of Git commands
- that allows you to be functional using Git.
- You can use as much, or as little, of what Git
- has to offer to accomplish what you need for your
- project.
- You do not have to be a "Git Expert" in order to
- use it with the Yocto Project.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <para>
- Using Git's tagging and branching features, the Yocto Project
- team creates kernel branches at points where functionality is
- no longer shared and thus, needs to be isolated.
- For example, board-specific incompatibilities would require
- different functionality and would require a branch to
- separate the features.
- Likewise, for specific kernel features, the same branching
- strategy is used.
- </para>
-
- <para>
- This "tree-like" architecture results in a structure that has
- features organized to be specific for particular functionality,
- single kernel types, or a subset of kernel types.
- Thus, the user has the ability to see the added features and the
- commits that make up those features.
- In addition to being able to see added features, the user
- can also view the history of what made up the baseline
- Linux kernel.
- </para>
-
- <para>
- Another consequence of this strategy results in not having to
- store the same feature twice internally in the tree.
- Rather, the kernel team stores the unique differences required
- to apply the feature onto the kernel type in question.
- <note>
- The Yocto Project team strives to place features in the tree
- such that features can be shared by all boards and kernel
- types where possible.
- However, during development cycles or when large features
- are merged, the team cannot always follow this practice.
- In those cases, the team uses isolated branches to merge
- features.
- </note>
- </para>
-
- <para>
- BSP-specific code additions are handled in a similar manner to
- kernel-specific additions.
- Some BSPs only make sense given certain kernel types.
- So, for these types, the team creates branches off the end
- of that kernel type for all of the BSPs that are supported on
- that kernel type.
- From the perspective of the tools that create the BSP branch,
- the BSP is really no different than a feature.
- Consequently, the same branching strategy applies to BSPs as
- it does to kernel features.
- So again, rather than store the BSP twice, the team only
- stores the unique differences for the BSP across the supported
- multiple kernels.
- </para>
-
- <para>
- While this strategy can result in a tree with a significant number
- of branches, it is important to realize that from the developer's
- point of view, there is a linear path that travels from the
- baseline <filename>kernel.org</filename>, through a select
- group of features and ends with their BSP-specific commits.
- In other words, the divisions of the kernel are transparent and
- are not relevant to the developer on a day-to-day basis.
- From the developer's perspective, this path is the "master" branch
- in Git terms.
- The developer does not need to be aware of the existence of any
- other branches at all.
- Of course, value exists in the having these branches in the tree,
- should a person decide to explore them.
- For example, a comparison between two BSPs at either the commit
- level or at the line-by-line code <filename>diff</filename> level
- is now a trivial operation.
- </para>
-
- <para>
- The following illustration shows the conceptual Yocto
- Linux kernel.
- <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
- </para>
-
- <para>
- In the illustration, the "Kernel.org Branch Point" marks the
- specific spot (or Linux kernel release) from which the
- Yocto Linux kernel is created.
- From this point forward in the tree, features and differences
- are organized and tagged.
- </para>
-
- <para>
- The "Yocto Project Baseline Kernel" contains functionality that
- is common to every kernel type and BSP that is organized
- further along in the tree.
- Placing these common features in the tree this way means
- features do not have to be duplicated along individual
- branches of the tree structure.
- </para>
-
- <para>
- From the "Yocto Project Baseline Kernel", branch points represent
- specific functionality for individual Board Support Packages
- (BSPs) as well as real-time kernels.
- The illustration represents this through three BSP-specific
- branches and a real-time kernel branch.
- Each branch represents some unique functionality for the BSP
- or for a real-time Yocto Linux kernel.
- </para>
-
- <para>
- In this example structure, the "Real-time (rt) Kernel" branch has
- common features for all real-time Yocto Linux kernels and
- contains more branches for individual BSP-specific real-time
- kernels.
- The illustration shows three branches as an example.
- Each branch points the way to specific, unique features for a
- respective real-time kernel as they apply to a given BSP.
- </para>
-
- <para>
- The resulting tree structure presents a clear path of markers
- (or branches) to the developer that, for all practical
- purposes, is the Yocto Linux kernel needed for any given set of
- requirements.
- <note>
- Keep in mind the figure does not take into account all the
- supported Yocto Linux kernels, but rather shows a single
- generic kernel just for conceptual purposes.
- Also keep in mind that this structure represents the Yocto
- Project
- <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
- that are either pulled from during the build or established
- on the host development system prior to the build by either
- cloning a particular kernel's Git repository or by
- downloading and unpacking a tarball.
- </note>
- </para>
-
- <para>
- Working with the kernel as a structured tree follows recognized
- community best practices.
- In particular, the kernel as shipped with the product, should be
- considered an "upstream source" and viewed as a series of
- historical and documented modifications (commits).
- These modifications represent the development and stabilization
- done by the Yocto Project kernel development team.
- </para>
-
- <para>
- Because commits only change at significant release points in the
- product life cycle, developers can work on a branch created
- from the last relevant commit in the shipped Yocto Project Linux
- kernel.
- As mentioned previously, the structure is transparent to the
- developer because the kernel tree is left in this state after
- cloning and building the kernel.
- </para>
- </section>
-
- <section id='kernel-build-file-hierarchy'>
- <title>Kernel Build File Hierarchy</title>
-
- <para>
- Upstream storage of all the available kernel source code is
- one thing, while representing and using the code on your host
- development system is another.
- Conceptually, you can think of the kernel source repositories
- as all the source files necessary for all the supported
- Yocto Linux kernels.
- As a developer, you are just interested in the source files
- for the kernel on which you are working.
- And, furthermore, you need them available on your host system.
- </para>
-
- <para>
- Kernel source code is available on your host system several
- different ways:
- <itemizedlist>
- <listitem><para>
- <emphasis>Files Accessed While using <filename>devtool</filename>:</emphasis>
- <filename>devtool</filename>, which is available with the
- Yocto Project, is the preferred method by which to
- modify the kernel.
- See the
- "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
- section.
- </para></listitem>
- <listitem><para>
- <emphasis>Cloned Repository:</emphasis>
- If you are working in the kernel all the time, you probably
- would want to set up your own local Git repository of the
- Yocto Linux kernel tree.
- For information on how to clone a Yocto Linux kernel
- Git repository, see the
- "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
- section.
- </para></listitem>
- <listitem><para>
- <emphasis>Temporary Source Files from a Build:</emphasis>
- If you just need to make some patches to the kernel using
- a traditional BitBake workflow (i.e. not using the
- <filename>devtool</filename>), you can access temporary
- kernel source files that were extracted and used during
- a kernel build.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The temporary kernel source files resulting from a build using
- BitBake have a particular hierarchy.
- When you build the kernel on your development system, all files
- needed for the build are taken from the source repositories
- pointed to by the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- variable and gathered in a temporary work area where they are
- subsequently used to create the unique kernel.
- Thus, in a sense, the process constructs a local source tree
- specific to your kernel from which to generate the new kernel
- image.
- </para>
-
- <para>
- The following figure shows the temporary file structure
- created on your host system when you build the kernel using
- Bitbake.
- This
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- contains all the source files used during the build.
- <imagedata fileref="figures/kernel-overview-2-generic.png"
- width="6in" depth="5in" align="center" scale="100" />
- </para>
-
- <para>
- Again, for additional information on the Yocto Project kernel's
- architecture and its branching strategy, see the
- "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>"
- section.
- You can also reference 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 for detailed example that modifies the kernel.
- </para>
- </section>
-
- <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'>
- <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title>
-
- <para>
- This section describes part of the kernel configuration audit
- phase that most developers can ignore.
- For general information on kernel configuration including
- <filename>menuconfig</filename>, <filename>defconfig</filename>
- files, and configuration fragments, see the
- "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
- section.
- </para>
-
- <para>
- During this part of the audit phase, the contents of the final
- <filename>.config</filename> file are compared against the
- fragments specified by the system.
- These fragments can be system fragments, distro fragments,
- or user-specified configuration elements.
- Regardless of their origin, the OpenEmbedded build system
- warns the user if a specific option is not included in the
- final kernel configuration.
- </para>
-
- <para>
- By default, in order to not overwhelm the user with
- configuration warnings, the system only reports missing
- "hardware" options as they could result in a boot
- failure or indicate that important hardware is not available.
- </para>
-
- <para>
- To determine whether or not a given option is "hardware" or
- "non-hardware", the kernel Metadata in
- <filename>yocto-kernel-cache</filename> contains files that
- classify individual or groups of options as either hardware
- or non-hardware.
- To better show this, consider a situation where the
- <filename>yocto-kernel-cache</filename> contains the following
- files:
- <literallayout class='monospaced'>
- yocto-kernel-cache/features/drm-psb/hardware.cfg
- yocto-kernel-cache/features/kgdb/hardware.cfg
- yocto-kernel-cache/ktypes/base/hardware.cfg
- yocto-kernel-cache/bsp/mti-malta32/hardware.cfg
- yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg
- yocto-kernel-cache/bsp/qemuarma9/hardware.cfg
- yocto-kernel-cache/bsp/mti-malta64/hardware.cfg
- yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg
- yocto-kernel-cache/bsp/common-pc/hardware.cfg
- yocto-kernel-cache/bsp/common-pc-64/hardware.cfg
- yocto-kernel-cache/features/rfkill/non-hardware.cfg
- yocto-kernel-cache/ktypes/base/non-hardware.cfg
- yocto-kernel-cache/features/aufs/non-hardware.kcf
- yocto-kernel-cache/features/ocf/non-hardware.kcf
- yocto-kernel-cache/ktypes/base/non-hardware.kcf
- yocto-kernel-cache/ktypes/base/hardware.kcf
- yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf
- </literallayout>
- The following list provides explanations for the various
- files:
- <itemizedlist>
- <listitem><para>
- <filename>hardware.kcf</filename>:
- Specifies a list of kernel Kconfig files that contain
- hardware options only.
- </para></listitem>
- <listitem><para>
- <filename>non-hardware.kcf</filename>:
- Specifies a list of kernel Kconfig files that contain
- non-hardware options only.
- </para></listitem>
- <listitem><para>
- <filename>hardware.cfg</filename>:
- Specifies a list of kernel <filename>CONFIG_</filename>
- options that are hardware, regardless of whether or not
- they are within a Kconfig file specified by a hardware
- or non-hardware Kconfig file (i.e.
- <filename>hardware.kcf</filename> or
- <filename>non-hardware.kcf</filename>).
- </para></listitem>
- <listitem><para>
- <filename>non-hardware.cfg</filename>:
- Specifies a list of kernel <filename>CONFIG_</filename>
- options that are not hardware, regardless of whether or
- not they are within a Kconfig file specified by a
- hardware or non-hardware Kconfig file (i.e.
- <filename>hardware.kcf</filename> or
- <filename>non-hardware.kcf</filename>).
- </para></listitem>
- </itemizedlist>
- Here is a specific example using the
- <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>:
- <literallayout class='monospaced'>
- CONFIG_SERIAL_8250
- CONFIG_SERIAL_8250_CONSOLE
- CONFIG_SERIAL_8250_NR_UARTS
- CONFIG_SERIAL_8250_PCI
- CONFIG_SERIAL_CORE
- CONFIG_SERIAL_CORE_CONSOLE
- CONFIG_VGA_ARB
- </literallayout>
- The kernel configuration audit automatically detects these
- files (hence the names must be exactly the ones discussed here),
- and uses them as inputs when generating warnings about the
- final <filename>.config</filename> file.
- </para>
-
- <para>
- A user-specified kernel Metadata repository, or recipe space
- feature, can use these same files to classify options that are
- found within its <filename>.cfg</filename> files as hardware
- or non-hardware, to prevent the OpenEmbedded build system from
- producing an error or warning when an option is not in the
- final <filename>.config</filename> file.
- </para>
- </section>
-</appendix>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/poky/documentation/kernel-dev/kernel-dev-customization.xsl b/poky/documentation/kernel-dev/kernel-dev-customization.xsl
deleted file mode 100644
index 88bf7c6..0000000
--- a/poky/documentation/kernel-dev/kernel-dev-customization.xsl
+++ /dev/null
@@ -1,28 +0,0 @@
-<?xml version='1.0'?>
-<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
-
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-
- <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-<!--
-
- <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
- <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-
--->
-
- <xsl:include href="../template/permalinks.xsl"/>
- <xsl:include href="../template/section.title.xsl"/>
- <xsl:include href="../template/component.title.xsl"/>
- <xsl:include href="../template/division.title.xsl"/>
- <xsl:include href="../template/formal.object.heading.xsl"/>
-
- <xsl:param name="html.stylesheet" select="'kernel-dev-style.css'" />
- <xsl:param name="chapter.autolabel" select="1" />
- <xsl:param name="appendix.autolabel">A</xsl:param>
- <xsl:param name="section.autolabel" select="1" />
- <xsl:param name="section.label.includes.component.label" select="1" />
-
-</xsl:stylesheet>
diff --git a/poky/documentation/kernel-dev/kernel-dev-faq.rst b/poky/documentation/kernel-dev/kernel-dev-faq.rst
index b5e6a84..70bf4a2 100644
--- a/poky/documentation/kernel-dev/kernel-dev-faq.rst
+++ b/poky/documentation/kernel-dev/kernel-dev-faq.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-2.0-UK
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
**********************
Kernel Development FAQ
diff --git a/poky/documentation/kernel-dev/kernel-dev-faq.xml b/poky/documentation/kernel-dev/kernel-dev-faq.xml
deleted file mode 100644
index d76f0a4..0000000
--- a/poky/documentation/kernel-dev/kernel-dev-faq.xml
+++ /dev/null
@@ -1,143 +0,0 @@
-<!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; ] >
-<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
-
-<appendix id='kernel-dev-faq'>
-<title>Kernel Development FAQ</title>
-
-<section id='kernel-dev-faq-section'>
- <title>Common Questions and Solutions</title>
-
- <para>
- The following lists some solutions for common questions.
-
-
- <qandaset>
- <qandaentry>
- <question>
- <para>
- How do I use my own Linux kernel <filename>.config</filename>
- file?
- </para>
- </question>
- <answer>
- <para>
- Refer to the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
- section for information.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>
- How do I create configuration fragments?
- </para>
- </question>
- <answer>
- <para>
- Refer to the
- "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
- section for information.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>
- How do I use my own Linux kernel sources?
- </para>
- </question>
- <answer>
- <para>
- Refer to the "<link linkend='working-with-your-own-sources'>Working With Your Own Sources</link>"
- section for information.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>
- How do I install/not-install the kernel image on the rootfs?
- </para>
- </question>
- <answer>
- <para>
- The kernel image (e.g. <filename>vmlinuz</filename>) is provided
- by the <filename>kernel-image</filename> package.
- Image recipes depend on <filename>kernel-base</filename>.
- To specify whether or not the kernel
- image is installed in the generated root filesystem, override
- <filename>RDEPENDS_kernel-base</filename> to include or not
- include "kernel-image".</para>
- <para>See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
- section in the Yocto Project Development Tasks Manual
- for information on how to use an append file to
- override metadata.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>
- How do I install a specific kernel module?
- </para>
- </question>
- <answer>
- <para>
- Linux kernel modules are packaged individually.
- To ensure a specific kernel module is included in an image,
- include it in the appropriate machine
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
- variable.</para>
- <para>These other variables are useful for installing specific
- modules:
- <literallayout class='monospaced'>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
- </literallayout>
- For example, set the following in the <filename>qemux86.conf</filename>
- file to include the <filename>ab123</filename> kernel modules
- with images built for the <filename>qemux86</filename> machine:
- <literallayout class='monospaced'>
- MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
- </literallayout>
- For more information, see the
- "<link linkend='incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</link>"
- section.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>
- How do I change the Linux kernel command line?
- </para>
- </question>
- <answer>
- <para>
- The Linux kernel command line is typically specified in
- the machine config using the <filename>APPEND</filename> variable.
- For example, you can add some helpful debug information doing
- the following:
- <literallayout class='monospaced'>
- APPEND += "printk.time=y initcall_debug debug"
- </literallayout>
- </para>
- </answer>
- </qandaentry>
- </qandaset>
- </para>
-</section>
-</appendix>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/poky/documentation/kernel-dev/kernel-dev-intro.rst b/poky/documentation/kernel-dev/kernel-dev-intro.rst
index 21d43d5..447cddb 100644
--- a/poky/documentation/kernel-dev/kernel-dev-intro.rst
+++ b/poky/documentation/kernel-dev/kernel-dev-intro.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-2.0-UK
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
************
Introduction
diff --git a/poky/documentation/kernel-dev/kernel-dev-intro.xml b/poky/documentation/kernel-dev/kernel-dev-intro.xml
deleted file mode 100644
index 7c1ea0e..0000000
--- a/poky/documentation/kernel-dev/kernel-dev-intro.xml
+++ /dev/null
@@ -1,260 +0,0 @@
-<!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; ] >
-<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
-
-<chapter id='kernel-dev-intro'>
-<title>Introduction</title>
-
-<section id='kernel-dev-overview'>
- <title>Overview</title>
-
- <para>
- Regardless of how you intend to make use of the Yocto Project,
- chances are you will work with the Linux kernel.
- This manual describes how to set up your build host to support
- kernel development, introduces the kernel development process,
- provides background information on the Yocto Linux kernel
- <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
- describes common tasks you can perform using the kernel tools,
- shows you how to use the kernel Metadata needed to work with
- the kernel inside the Yocto Project, and provides insight into how
- the Yocto Project team develops and maintains Yocto Linux kernel
- Git repositories and Metadata.
- </para>
-
- <para>
- Each Yocto Project release has a set of Yocto Linux kernel recipes,
- whose Git repositories you can view in the Yocto
- <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
- the "Yocto Linux Kernel" heading.
- New recipes for the release track the latest Linux kernel
- upstream developments from
- <ulink url='http://www.kernel.org'></ulink> and introduce
- newly-supported platforms.
- Previous recipes in the release are refreshed and supported for at
- least one additional Yocto Project release.
- As they align, these previous releases are updated to include the
- latest from the Long Term Support Initiative (LTSI) project.
- You can learn more about Yocto Linux kernels and LTSI in the
- "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>"
- section.
- </para>
-
- <para>
- Also included is a Yocto Linux kernel development recipe
- (<filename>linux-yocto-dev.bb</filename>) should you want to work
- with the very latest in upstream Yocto Linux kernel development and
- kernel Metadata development.
- <note>
- For more on Yocto Linux kernels, see the
- "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>
- section.
- </note>
- </para>
-
- <para>
- The Yocto Project also provides a powerful set of kernel
- tools for managing Yocto Linux kernel sources and configuration data.
- You can use these tools to make a single configuration change,
- apply multiple patches, or work with your own kernel sources.
- </para>
-
- <para>
- In particular, the kernel tools allow you to generate configuration
- fragments that specify only what you must, and nothing more.
- Configuration fragments only need to contain the highest level
- visible <filename>CONFIG</filename> options as presented by the
- Yocto Linux kernel <filename>menuconfig</filename> system.
- Contrast this against a complete Yocto Linux kernel
- <filename>.config</filename> file, which includes all the automatically
- selected <filename>CONFIG</filename> options.
- This efficiency reduces your maintenance effort and allows you
- to further separate your configuration in ways that make sense for
- your project.
- A common split separates policy and hardware.
- For example, all your kernels might support the
- <filename>proc</filename> and <filename>sys</filename> filesystems,
- but only specific boards require sound, USB, or specific drivers.
- Specifying these configurations individually allows you to aggregate
- them together as needed, but maintains them in only one place.
- Similar logic applies to separating source changes.
- </para>
-
- <para>
- If you do not maintain your own kernel sources and need to make
- only minimal changes to the sources, the released recipes provide a
- vetted base upon which to layer your changes.
- Doing so allows you to benefit from the continual kernel
- integration and testing performed during development of the
- Yocto Project.
- </para>
-
- <para>
- If, instead, you have a very specific Linux kernel source tree
- and are unable to align with one of the official Yocto Linux kernel
- recipes, an alternative exists by which you can use the Yocto
- Project Linux kernel tools with your own kernel sources.
- </para>
-
- <para>
- The remainder of this manual provides instructions for completing
- specific Linux kernel development tasks.
- These instructions assume you are comfortable working with
- <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
- recipes and basic open-source development tools.
- Understanding these concepts will facilitate the process of working
- with the kernel recipes.
- If you find you need some additional background, please be sure to
- review and understand the following documentation:
- <itemizedlist>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
- document.
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
- as described in the Yocto Project Application Development and
- the Extensible Software Development Kit (eSDK) manual.
- </para></listitem>
- <listitem><para>
- The
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>
- The
- "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
- section.
- </para></listitem>
- </itemizedlist>
- </para>
-</section>
-
-<section id='kernel-modification-workflow'>
- <title>Kernel Modification Workflow</title>
-
- <para>
- Kernel modification involves changing the Yocto Project kernel,
- which could involve changing configuration options as well as adding
- new kernel recipes.
- Configuration changes can be added in the form of configuration
- fragments, while recipe modification comes through the kernel's
- <filename>recipes-kernel</filename> area in a kernel layer you create.
- </para>
-
- <para>
- This section presents a high-level overview of the Yocto Project
- kernel modification workflow.
- The illustration and accompanying list provide general information
- and references for further information.
- <imagedata fileref="figures/kernel-dev-flow.png"
- width="9in" depth="5in" align="center" scalefit="1" />
- </para>
-
- <para>
- <orderedlist>
- <listitem><para>
-
-
- <emphasis>Set up Your Host Development System to Support
- Development Using the Yocto Project</emphasis>:
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>"
- section in the Yocto Project Development Tasks Manual for
- options on how to get a build host ready to use the Yocto
- Project.
- </para></listitem>
- <listitem><para>
- <emphasis>Set Up Your Host Development System for Kernel Development:</emphasis>
- It is recommended that you use <filename>devtool</filename>
- and an extensible SDK for kernel development.
- Alternatively, you can use traditional kernel development
- methods with the Yocto Project.
- Either way, there are steps you need to take to get the
- development environment ready.</para>
-
- <para>Using <filename>devtool</filename> and the eSDK requires
- that you have a clean build of the image and that you are
- set up with the appropriate eSDK.
- For more information, see the
- "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
- section.</para>
-
- <para>Using traditional kernel development requires that you
- have the kernel source available in an isolated local Git
- repository.
- For more information, see the
- "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
- section.
- </para></listitem>
- <listitem><para>
- <emphasis>Make Changes to the Kernel Source Code if
- applicable:</emphasis>
- Modifying the kernel does not always mean directly
- changing source files.
- However, if you have to do this, you make the changes to the
- files in the eSDK's Build Directory if you are using
- <filename>devtool</filename>.
- For more information, see the
- "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
- section.</para>
-
- <para>If you are using traditional kernel development, you
- edit the source files in the kernel's local Git repository.
- For more information, see the
- "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
- section.
- </para></listitem>
- <listitem><para>
- <emphasis>Make Kernel Configuration Changes if
- Applicable:</emphasis>
- If your situation calls for changing the kernel's
- configuration, you can use
- <link linkend='using-menuconfig'><filename>menuconfig</filename></link>,
- which allows you to interactively develop and test the
- configuration changes you are making to the kernel.
- Saving changes you make with <filename>menuconfig</filename>
- updates the kernel's <filename>.config</filename> file.
- <note><title>Warning</title>
- Try to resist the temptation to directly edit an
- existing <filename>.config</filename> file, which is
- found in the Build Directory among the source code
- used for the build.
- Doing so, can produce unexpected results when the
- OpenEmbedded build system regenerates the configuration
- file.
- </note>
- Once you are satisfied with the configuration
- changes made using <filename>menuconfig</filename>
- and you have saved them, you can directly compare the
- resulting <filename>.config</filename> file against an
- existing original and gather those changes into a
- <link linkend='creating-config-fragments'>configuration fragment file</link>
- to be referenced from within the kernel's
- <filename>.bbappend</filename> file.</para>
-
- <para>Additionally, if you are working in a BSP layer
- and need to modify the BSP's kernel's configuration,
- you can use <filename>menuconfig</filename>.
- </para></listitem>
- <listitem><para>
- <emphasis>Rebuild the Kernel Image With Your Changes:</emphasis>
- Rebuilding the kernel image applies your changes.
- Depending on your target hardware, you can verify your changes
- on actual hardware or perhaps QEMU.
- </para></listitem>
- </orderedlist>
- The remainder of this developer's guide covers common tasks typically
- used during kernel development, advanced Metadata usage, and Yocto Linux
- kernel maintenance concepts.
- </para>
-</section>
-
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/poky/documentation/kernel-dev/kernel-dev-maint-appx.rst b/poky/documentation/kernel-dev/kernel-dev-maint-appx.rst
index 5514dac..1788332 100644
--- a/poky/documentation/kernel-dev/kernel-dev-maint-appx.rst
+++ b/poky/documentation/kernel-dev/kernel-dev-maint-appx.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-2.0-UK
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
******************
Kernel Maintenance
diff --git a/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml b/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml
deleted file mode 100644
index 3d9c7c6..0000000
--- a/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml
+++ /dev/null
@@ -1,357 +0,0 @@
-<!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; ] >
-<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
-
-<appendix id='kernel-dev-maint-appx'>
-<title>Kernel Maintenance</title>
-
- <section id='tree-construction'>
- <title>Tree Construction</title>
-
- <para>
- This section describes construction of the Yocto Project kernel
- source repositories as accomplished by the Yocto Project team to
- create Yocto Linux kernel repositories.
- These kernel repositories are found under the heading "Yocto Linux
- Kernel" at
- <ulink url='&YOCTO_GIT_URL;'>&YOCTO_GIT_URL;</ulink>
- and are shipped as part of a Yocto Project release.
- The team creates these repositories by compiling and executing the
- set of feature descriptions for every BSP and feature in the
- product.
- Those feature descriptions list all necessary patches,
- configurations, branches, tags, and feature divisions found in a
- Yocto Linux kernel.
- Thus, the Yocto Project Linux kernel repository (or tree) and
- accompanying Metadata in the
- <filename>yocto-kernel-cache</filename> are built.
- </para>
-
- <para>
- The existence of these repositories allow you to access and clone a
- particular Yocto Project Linux kernel repository and use it to
- build images based on their configurations and features.
- </para>
-
- <para>
- You can find the files used to describe all the valid features and
- BSPs in the Yocto Project Linux kernel in any clone of the Yocto
- Project Linux kernel source repository and
- <filename>yocto-kernel-cache</filename> Git trees.
- For example, the following commands clone the Yocto Project
- baseline Linux kernel that branches off
- <filename>linux.org</filename> version 4.12 and the
- <filename>yocto-kernel-cache</filename>, which contains stores of
- kernel Metadata:
- <literallayout class='monospaced'>
- $ git clone git://git.yoctoproject.org/linux-yocto-4.12
- $ git clone git://git.yoctoproject.org/linux-kernel-cache
- </literallayout>
- For more information on how to set up a local Git repository of
- the Yocto Project Linux kernel files, see the
- "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
- section.
- </para>
-
- <para>
- Once you have cloned the kernel Git repository and the
- cache of Metadata on your local machine, you can discover the
- branches that are available in the repository using the following
- Git command:
- <literallayout class='monospaced'>
- $ git branch -a
- </literallayout>
- Checking out a branch allows you to work with a particular
- Yocto Linux kernel.
- For example, the following commands check out the
- "standard/beagleboard" branch of the Yocto Linux kernel repository
- and the "yocto-4.12" branch of the
- <filename>yocto-kernel-cache</filename> repository:
- <literallayout class='monospaced'>
- $ cd ~/linux-yocto-4.12
- $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
- $ cd ~/linux-kernel-cache
- $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12
- </literallayout>
- <note>
- Branches in the <filename>yocto-kernel-cache</filename>
- repository correspond to Yocto Linux kernel versions
- (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
- </note>
- Once you have checked out and switched to appropriate branches,
- you can see a snapshot of all the kernel source files used to
- used to build that particular Yocto Linux kernel for a
- particular board.
- </para>
-
- <para>
- To see the features and configurations for a particular Yocto
- Linux kernel, you need to examine the
- <filename>yocto-kernel-cache</filename> Git repository.
- As mentioned, branches in the
- <filename>yocto-kernel-cache</filename> repository correspond to
- Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>).
- Branches contain descriptions in the form of
- <filename>.scc</filename> and <filename>.cfg</filename> files.
- </para>
-
- <para>
- You should realize, however, that browsing your local
- <filename>yocto-kernel-cache</filename> repository for feature
- descriptions and patches is not an effective way to determine what
- is in a particular kernel branch.
- Instead, you should use Git directly to discover the changes in
- a branch.
- Using Git is an efficient and flexible way to inspect changes to
- the kernel.
- <note>
- Ground up reconstruction of the complete kernel tree is an
- action only taken by the Yocto Project team during an active
- development cycle.
- When you create a clone of the kernel Git repository, you are
- simply making it efficiently available for building and
- development.
- </note>
- </para>
-
- <para>
- The following steps describe what happens when the Yocto Project
- Team constructs the Yocto Project kernel source Git repository
- (or tree) found at
- <ulink url='&YOCTO_GIT_URL;'></ulink> given the
- introduction of a new top-level kernel feature or BSP.
- The following actions effectively provide the Metadata
- and create the tree that includes the new feature, patch, or BSP:
- <orderedlist>
- <listitem><para>
- <emphasis>Pass Feature to the OpenEmbedded Build System:</emphasis>
- A top-level kernel feature is passed to the kernel build
- subsystem.
- Normally, this feature is a BSP for a particular kernel
- type.
- </para></listitem>
- <listitem><para>
- <emphasis>Locate Feature:</emphasis>
- The file that describes the top-level feature is located
- by searching these system directories:
- <itemizedlist>
- <listitem><para>
- The in-tree kernel-cache directories, which are
- located in the
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink>
- repository organized under the "Yocto Linux Kernel"
- heading in the
- <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
- </para></listitem>
- <listitem><para>
- Areas pointed to by <filename>SRC_URI</filename>
- statements found in kernel recipes
- </para></listitem>
- </itemizedlist>
- For a typical build, the target of the search is a
- feature description in an <filename>.scc</filename> file
- whose name follows this format (e.g.
- <filename>beaglebone-standard.scc</filename> and
- <filename>beaglebone-preempt-rt.scc</filename>):
- <literallayout class='monospaced'>
- <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Expand Feature:</emphasis>
- Once located, the feature description is either expanded
- into a simple script of actions, or into an existing
- equivalent script that is already part of the shipped
- kernel.
- </para></listitem>
- <listitem><para>
- <emphasis>Append Extra Features:</emphasis>
- Extra features are appended to the top-level feature
- description.
- These features can come from the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
- variable in recipes.
- </para></listitem>
- <listitem><para>
- <emphasis>Locate, Expand, and Append Each Feature:</emphasis>
- Each extra feature is located, expanded and appended to
- the script as described in step three.
- </para></listitem>
- <listitem><para>
- <emphasis>Execute the Script:</emphasis>
- The script is executed to produce files
- <filename>.scc</filename> and <filename>.cfg</filename>
- files in appropriate directories of the
- <filename>yocto-kernel-cache</filename> repository.
- These files are descriptions of all the branches, tags,
- patches and configurations that need to be applied to the
- base Git repository to completely create the
- source (build) branch for the new BSP or feature.
- </para></listitem>
- <listitem><para>
- <emphasis>Clone Base Repository:</emphasis>
- The base repository is cloned, and the actions
- listed in the <filename>yocto-kernel-cache</filename>
- directories are applied to the tree.
- </para></listitem>
- <listitem><para>
- <emphasis>Perform Cleanup:</emphasis>
- The Git repositories are left with the desired branches
- checked out and any required branching, patching and
- tagging has been performed.
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- The kernel tree and cache are ready for developer consumption to
- be locally cloned, configured, and built into a Yocto Project
- kernel specific to some target hardware.
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- The generated <filename>yocto-kernel-cache</filename>
- repository adds to the kernel as shipped with the Yocto
- Project release.
- Any add-ons and configuration data are applied to the
- end of an existing branch.
- The full repository generation that is found in the
- official Yocto Project kernel repositories at
- <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>
- is the combination of all supported boards and
- configurations.
- </para></listitem>
- <listitem><para>
- The technique the Yocto Project team uses is flexible
- and allows for seamless blending of an immutable
- history with additional patches specific to a
- deployment.
- Any additions to the kernel become an integrated part
- of the branches.
- </para></listitem>
- <listitem><para>
- The full kernel tree that you see on
- <ulink url='&YOCTO_GIT_URL;'></ulink> is
- generated through repeating the above steps for all
- valid BSPs.
- The end result is a branched, clean history tree that
- makes up the kernel for a given release.
- You can see the script (<filename>kgit-scc</filename>)
- responsible for this in the
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools'><filename>yocto-kernel-tools</filename></ulink>
- repository.
- </para></listitem>
- <listitem><para>
- The steps used to construct the full kernel tree are
- the same steps that BitBake uses when it builds a
- kernel image.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
- </section>
-
- <section id='build-strategy'>
- <title>Build Strategy</title>
-
- <para>
- Once you have cloned a Yocto Linux kernel repository and the
- cache repository (<filename>yocto-kernel-cache</filename>) onto
- your development system, you can consider the compilation phase
- of kernel development, which is building a kernel image.
- Some prerequisites exist that are validated by the build process
- before compilation starts:
- </para>
-
- <itemizedlist>
- <listitem><para>
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- points to the kernel Git repository.
- </para></listitem>
- <listitem><para>
- A BSP build branch with Metadata exists in the
- <filename>yocto-kernel-cache</filename> repository.
- The branch is based on the Yocto Linux kernel version and
- has configurations and features grouped under the
- <filename>yocto-kernel-cache/bsp</filename> directory.
- For example, features and configurations for the
- BeagleBone Board assuming a
- <filename>linux-yocto_4.12</filename> kernel reside in the
- following area of the <filename>yocto-kernel-cache</filename>
- repository:
- <literallayout class='monospaced'>
- yocto-kernel-cache/bsp/beaglebone
- </literallayout>
- <note>
- In the previous example, the "yocto-4.12" branch is
- checked out in the <filename>yocto-kernel-cache</filename>
- repository.
- </note>
- </para></listitem>
- </itemizedlist>
-
- <para>
- The OpenEmbedded build system makes sure these conditions exist
- before attempting compilation.
- Other means, however, do exist, such as as bootstrapping a BSP.
- </para>
-
- <para>
- Before building a kernel, the build process verifies the tree
- and configures the kernel by processing all of the
- configuration "fragments" specified by feature descriptions
- in the <filename>.scc</filename> files.
- As the features are compiled, associated kernel configuration
- fragments are noted and recorded in the series of directories
- in their compilation order.
- The fragments are migrated, pre-processed and passed to the
- Linux Kernel Configuration subsystem (<filename>lkc</filename>) as
- raw input in the form of a <filename>.config</filename> file.
- The <filename>lkc</filename> uses its own internal dependency
- constraints to do the final processing of that information and
- generates the final <filename>.config</filename> file that is used
- during compilation.
- </para>
-
- <para>
- Using the board's architecture and other relevant values from
- the board's template, kernel compilation is started and a kernel
- image is produced.
- </para>
-
- <para>
- The other thing that you notice once you configure a kernel is that
- the build process generates a build tree that is separate from
- your kernel's local Git source repository tree.
- This build tree has a name that uses the following form, where
- <filename>${MACHINE}</filename> is the metadata name of the
- machine (BSP) and "kernel_type" is one of the Yocto Project
- supported kernel types (e.g. "standard"):
- <literallayout class='monospaced'>
- linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build
- </literallayout>
- </para>
-
- <para>
- The existing support in the <filename>kernel.org</filename> tree
- achieves this default functionality.
- </para>
-
- <para>
- This behavior means that all the generated files for a particular
- machine or BSP are now in the build tree directory.
- The files include the final <filename>.config</filename> file,
- all the <filename>.o</filename> files, the <filename>.a</filename>
- files, and so forth.
- Since each machine or BSP has its own separate
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- in its own separate branch of the Git repository, you can easily
- switch between different builds.
- </para>
- </section>
-</appendix>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/poky/documentation/kernel-dev/kernel-dev-style.css b/poky/documentation/kernel-dev/kernel-dev-style.css
deleted file mode 100644
index fc6fbb8..0000000
--- a/poky/documentation/kernel-dev/kernel-dev-style.css
+++ /dev/null
@@ -1,991 +0,0 @@
-/*
-
- SPDX-License-Identifier: CC-BY-2.0-UK
-
- Generic XHTML / DocBook XHTML CSS Stylesheet.
-
- Browser wrangling and typographic design by
- Oyvind Kolas / pippin@gimp.org
-
- Customised for Poky by
- Matthew Allum / mallum@o-hand.com
-
- Thanks to:
- Liam R. E. Quin
- William Skaggs
- Jakub Steiner
-
- Structure
- ---------
-
- The stylesheet is divided into the following sections:
-
- Positioning
- Margins, paddings, width, font-size, clearing.
- Decorations
- Borders, style
- Colors
- Colors
- Graphics
- Graphical backgrounds
- Nasty IE tweaks
- Workarounds needed to make it work in internet explorer,
- currently makes the stylesheet non validating, but up until
- this point it is validating.
- Mozilla extensions
- Transparency for footer
- Rounded corners on boxes
-
-*/
-
-
- /*************** /
- / Positioning /
-/ ***************/
-
-body {
- font-family: Verdana, Sans, sans-serif;
-
- min-width: 640px;
- width: 80%;
- margin: 0em auto;
- padding: 2em 5em 5em 5em;
- color: #333;
-}
-
-h1,h2,h3,h4,h5,h6,h7 {
- font-family: Arial, Sans;
- color: #00557D;
- clear: both;
-}
-
-h1 {
- font-size: 2em;
- text-align: left;
- padding: 0em 0em 0em 0em;
- margin: 2em 0em 0em 0em;
-}
-
-h2.subtitle {
- margin: 0.10em 0em 3.0em 0em;
- padding: 0em 0em 0em 0em;
- font-size: 1.8em;
- padding-left: 20%;
- font-weight: normal;
- font-style: italic;
-}
-
-h2 {
- margin: 2em 0em 0.66em 0em;
- padding: 0.5em 0em 0em 0em;
- font-size: 1.5em;
- font-weight: bold;
-}
-
-h3.subtitle {
- margin: 0em 0em 1em 0em;
- padding: 0em 0em 0em 0em;
- font-size: 142.14%;
- text-align: right;
-}
-
-h3 {
- margin: 1em 0em 0.5em 0em;
- padding: 1em 0em 0em 0em;
- font-size: 140%;
- font-weight: bold;
-}
-
-h4 {
- margin: 1em 0em 0.5em 0em;
- padding: 1em 0em 0em 0em;
- font-size: 120%;
- font-weight: bold;
-}
-
-h5 {
- margin: 1em 0em 0.5em 0em;
- padding: 1em 0em 0em 0em;
- font-size: 110%;
- font-weight: bold;
-}
-
-h6 {
- margin: 1em 0em 0em 0em;
- padding: 1em 0em 0em 0em;
- font-size: 110%;
- font-weight: bold;
-}
-
-.authorgroup {
- background-color: transparent;
- background-repeat: no-repeat;
- padding-top: 256px;
- background-image: url("figures/kernel-dev-title.png");
- background-position: left top;
- margin-top: -256px;
- padding-right: 50px;
- margin-left: 0px;
- text-align: right;
- width: 740px;
-}
-
-h3.author {
- margin: 0em 0me 0em 0em;
- padding: 0em 0em 0em 0em;
- font-weight: normal;
- font-size: 100%;
- color: #333;
- clear: both;
-}
-
-.author tt.email {
- font-size: 66%;
-}
-
-.titlepage hr {
- width: 0em;
- clear: both;
-}
-
-.revhistory {
- padding-top: 2em;
- clear: both;
-}
-
-.toc,
-.list-of-tables,
-.list-of-examples,
-.list-of-figures {
- padding: 1.33em 0em 2.5em 0em;
- color: #00557D;
-}
-
-.toc p,
-.list-of-tables p,
-.list-of-figures p,
-.list-of-examples p {
- padding: 0em 0em 0em 0em;
- padding: 0em 0em 0.3em;
- margin: 1.5em 0em 0em 0em;
-}
-
-.toc p b,
-.list-of-tables p b,
-.list-of-figures p b,
-.list-of-examples p b{
- font-size: 100.0%;
- font-weight: bold;
-}
-
-.toc dl,
-.list-of-tables dl,
-.list-of-figures dl,
-.list-of-examples dl {
- margin: 0em 0em 0.5em 0em;
- padding: 0em 0em 0em 0em;
-}
-
-.toc dt {
- margin: 0em 0em 0em 0em;
- padding: 0em 0em 0em 0em;
-}
-
-.toc dd {
- margin: 0em 0em 0em 2.6em;
- padding: 0em 0em 0em 0em;
-}
-
-div.glossary dl,
-div.variablelist dl {
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
- font-weight: normal;
- width: 20em;
- text-align: right;
-}
-
-.variablelist dl dt {
- margin-top: 0.5em;
-}
-
-.glossary dl dd,
-.variablelist dl dd {
- margin-top: -1em;
- margin-left: 25.5em;
-}
-
-.glossary dd p,
-.variablelist dd p {
- margin-top: 0em;
- margin-bottom: 1em;
-}
-
-
-div.calloutlist table td {
- padding: 0em 0em 0em 0em;
- margin: 0em 0em 0em 0em;
-}
-
-div.calloutlist table td p {
- margin-top: 0em;
- margin-bottom: 1em;
-}
-
-div p.copyright {
- text-align: left;
-}
-
-div.legalnotice p.legalnotice-title {
- margin-bottom: 0em;
-}
-
-p {
- line-height: 1.5em;
- margin-top: 0em;
-
-}
-
-dl {
- padding-top: 0em;
-}
-
-hr {
- border: solid 1px;
-}
-
-
-.mediaobject,
-.mediaobjectco {
- text-align: center;
-}
-
-img {
- border: none;
-}
-
-ul {
- padding: 0em 0em 0em 1.5em;
-}
-
-ul li {
- padding: 0em 0em 0em 0em;
-}
-
-ul li p {
- text-align: left;
-}
-
-table {
- width :100%;
-}
-
-th {
- padding: 0.25em;
- text-align: left;
- font-weight: normal;
- vertical-align: top;
-}
-
-td {
- padding: 0.25em;
- vertical-align: top;
-}
-
-p a[id] {
- margin: 0px;
- padding: 0px;
- display: inline;
- background-image: none;
-}
-
-a {
- text-decoration: underline;
- color: #444;
-}
-
-pre {
- overflow: auto;
-}
-
-a:hover {
- text-decoration: underline;
- /*font-weight: bold;*/
-}
-
-/* This style defines how the permalink character
- appears by itself and when hovered over with
- the mouse. */
-
-[alt='Permalink'] { color: #eee; }
-[alt='Permalink']:hover { color: black; }
-
-
-div.informalfigure,
-div.informalexample,
-div.informaltable,
-div.figure,
-div.table,
-div.example {
- margin: 1em 0em;
- padding: 1em;
- page-break-inside: avoid;
-}
-
-
-div.informalfigure p.title b,
-div.informalexample p.title b,
-div.informaltable p.title b,
-div.figure p.title b,
-div.example p.title b,
-div.table p.title b{
- padding-top: 0em;
- margin-top: 0em;
- font-size: 100%;
- font-weight: normal;
-}
-
-.mediaobject .caption,
-.mediaobject .caption p {
- text-align: center;
- font-size: 80%;
- padding-top: 0.5em;
- padding-bottom: 0.5em;
-}
-
-.epigraph {
- padding-left: 55%;
- margin-bottom: 1em;
-}
-
-.epigraph p {
- text-align: left;
-}
-
-.epigraph .quote {
- font-style: italic;
-}
-.epigraph .attribution {
- font-style: normal;
- text-align: right;
-}
-
-span.application {
- font-style: italic;
-}
-
-.programlisting {
- font-family: monospace;
- font-size: 80%;
- white-space: pre;
- margin: 1.33em 0em;
- padding: 1.33em;
-}
-
-.tip,
-.warning,
-.caution,
-.note {
- margin-top: 1em;
- margin-bottom: 1em;
-
-}
-
-/* force full width of table within div */
-.tip table,
-.warning table,
-.caution table,
-.note table {
- border: none;
- width: 100%;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
- padding: 0.8em 0.0em 0.0em 0.0em;
- margin : 0em 0em 0em 0em;
-}
-
-.tip p,
-.warning p,
-.caution p,
-.note p {
- margin-top: 0.5em;
- margin-bottom: 0.5em;
- padding-right: 1em;
- text-align: left;
-}
-
-.acronym {
- text-transform: uppercase;
-}
-
-b.keycap,
-.keycap {
- padding: 0.09em 0.3em;
- margin: 0em;
-}
-
-.itemizedlist li {
- clear: none;
-}
-
-.filename {
- font-size: medium;
- font-family: Courier, monospace;
-}
-
-
-div.navheader, div.heading{
- position: absolute;
- left: 0em;
- top: 0em;
- width: 100%;
- background-color: #cdf;
- width: 100%;
-}
-
-div.navfooter, div.footing{
- position: fixed;
- left: 0em;
- bottom: 0em;
- background-color: #eee;
- width: 100%;
-}
-
-
-div.navheader td,
-div.navfooter td {
- font-size: 66%;
-}
-
-div.navheader table th {
- /*font-family: Georgia, Times, serif;*/
- /*font-size: x-large;*/
- font-size: 80%;
-}
-
-div.navheader table {
- border-left: 0em;
- border-right: 0em;
- border-top: 0em;
- width: 100%;
-}
-
-div.navfooter table {
- border-left: 0em;
- border-right: 0em;
- border-bottom: 0em;
- width: 100%;
-}
-
-div.navheader table td a,
-div.navfooter table td a {
- color: #777;
- text-decoration: none;
-}
-
-/* normal text in the footer */
-div.navfooter table td {
- color: black;
-}
-
-div.navheader table td a:visited,
-div.navfooter table td a:visited {
- color: #444;
-}
-
-
-/* links in header and footer */
-div.navheader table td a:hover,
-div.navfooter table td a:hover {
- text-decoration: underline;
- background-color: transparent;
- color: #33a;
-}
-
-div.navheader hr,
-div.navfooter hr {
- display: none;
-}
-
-
-.qandaset tr.question td p {
- margin: 0em 0em 1em 0em;
- padding: 0em 0em 0em 0em;
-}
-
-.qandaset tr.answer td p {
- margin: 0em 0em 1em 0em;
- padding: 0em 0em 0em 0em;
-}
-.answer td {
- padding-bottom: 1.5em;
-}
-
-.emphasis {
- font-weight: bold;
-}
-
-
- /************* /
- / decorations /
-/ *************/
-
-.titlepage {
-}
-
-.part .title {
-}
-
-.subtitle {
- border: none;
-}
-
-/*
-h1 {
- border: none;
-}
-
-h2 {
- border-top: solid 0.2em;
- border-bottom: solid 0.06em;
-}
-
-h3 {
- border-top: 0em;
- border-bottom: solid 0.06em;
-}
-
-h4 {
- border: 0em;
- border-bottom: solid 0.06em;
-}
-
-h5 {
- border: 0em;
-}
-*/
-
-.programlisting {
- border: solid 1px;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example {
- border: 1px solid;
-}
-
-
-
-.tip,
-.warning,
-.caution,
-.note {
- border: 1px solid;
-}
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
- border-bottom: 1px solid;
-}
-
-.question td {
- border-top: 1px solid black;
-}
-
-.answer {
-}
-
-
-b.keycap,
-.keycap {
- border: 1px solid;
-}
-
-
-div.navheader, div.heading{
- border-bottom: 1px solid;
-}
-
-
-div.navfooter, div.footing{
- border-top: 1px solid;
-}
-
- /********* /
- / colors /
-/ *********/
-
-body {
- color: #333;
- background: white;
-}
-
-a {
- background: transparent;
-}
-
-a:hover {
- background-color: #dedede;
-}
-
-
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7,
-h8 {
- background-color: transparent;
-}
-
-hr {
- border-color: #aaa;
-}
-
-
-.tip, .warning, .caution, .note {
- border-color: #fff;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
- border-bottom-color: #fff;
-}
-
-
-.warning {
- background-color: #f0f0f2;
-}
-
-.caution {
- background-color: #f0f0f2;
-}
-
-.tip {
- background-color: #f0f0f2;
-}
-
-.note {
- background-color: #f0f0f2;
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
- color: #044;
-}
-
-div.figure,
-div.table,
-div.example,
-div.informalfigure,
-div.informaltable,
-div.informalexample {
- border-color: #aaa;
-}
-
-pre.programlisting {
- color: black;
- background-color: #fff;
- border-color: #aaa;
- border-width: 2px;
-}
-
-.guimenu,
-.guilabel,
-.guimenuitem {
- background-color: #eee;
-}
-
-
-b.keycap,
-.keycap {
- background-color: #eee;
- border-color: #999;
-}
-
-
-div.navheader {
- border-color: black;
-}
-
-
-div.navfooter {
- border-color: black;
-}
-
-.writernotes {
- color: red;
-}
-
-
- /*********** /
- / graphics /
-/ ***********/
-
-/*
-body {
- background-image: url("images/body_bg.jpg");
- background-attachment: fixed;
-}
-
-.navheader,
-.note,
-.tip {
- background-image: url("images/note_bg.jpg");
- background-attachment: fixed;
-}
-
-.warning,
-.caution {
- background-image: url("images/warning_bg.jpg");
- background-attachment: fixed;
-}
-
-.figure,
-.informalfigure,
-.example,
-.informalexample,
-.table,
-.informaltable {
- background-image: url("images/figure_bg.jpg");
- background-attachment: fixed;
-}
-
-*/
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7{
-}
-
-/*
-Example of how to stick an image as part of the title.
-
-div.article .titlepage .title
-{
- background-image: url("figures/white-on-black.png");
- background-position: center;
- background-repeat: repeat-x;
-}
-*/
-
-div.preface .titlepage .title,
-div.colophon .title,
-div.chapter .titlepage .title,
-div.article .titlepage .title
-{
-}
-
-div.section div.section .titlepage .title,
-div.sect2 .titlepage .title {
- background: none;
-}
-
-
-h1.title {
- background-color: transparent;
- background-repeat: no-repeat;
- height: 256px;
- text-indent: -9000px;
- overflow:hidden;
-}
-
-h2.subtitle {
- background-color: transparent;
- text-indent: -9000px;
- overflow:hidden;
- width: 0px;
- display: none;
-}
-
- /*************************************** /
- / pippin.gimp.org specific alterations /
-/ ***************************************/
-
-/*
-div.heading, div.navheader {
- color: #777;
- font-size: 80%;
- padding: 0;
- margin: 0;
- text-align: left;
- position: absolute;
- top: 0px;
- left: 0px;
- width: 100%;
- height: 50px;
- background: url('/gfx/heading_bg.png') transparent;
- background-repeat: repeat-x;
- background-attachment: fixed;
- border: none;
-}
-
-div.heading a {
- color: #444;
-}
-
-div.footing, div.navfooter {
- border: none;
- color: #ddd;
- font-size: 80%;
- text-align:right;
-
- width: 100%;
- padding-top: 10px;
- position: absolute;
- bottom: 0px;
- left: 0px;
-
- background: url('/gfx/footing_bg.png') transparent;
-}
-*/
-
-
-
- /****************** /
- / nasty ie tweaks /
-/ ******************/
-
-/*
-div.heading, div.navheader {
- width:expression(document.body.clientWidth + "px");
-}
-
-div.footing, div.navfooter {
- width:expression(document.body.clientWidth + "px");
- margin-left:expression("-5em");
-}
-body {
- padding:expression("4em 5em 0em 5em");
-}
-*/
-
- /**************************************** /
- / mozilla vendor specific css extensions /
-/ ****************************************/
-/*
-div.navfooter, div.footing{
- -moz-opacity: 0.8em;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example,
-.tip,
-.warning,
-.caution,
-.note {
- -moz-border-radius: 0.5em;
-}
-
-b.keycap,
-.keycap {
- -moz-border-radius: 0.3em;
-}
-*/
-
-table tr td table tr td {
- display: none;
-}
-
-
-hr {
- display: none;
-}
-
-table {
- border: 0em;
-}
-
- .photo {
- float: right;
- margin-left: 1.5em;
- margin-bottom: 1.5em;
- margin-top: 0em;
- max-width: 17em;
- border: 1px solid gray;
- padding: 3px;
- background: white;
-}
- .seperator {
- padding-top: 2em;
- clear: both;
- }
-
- #validators {
- margin-top: 5em;
- text-align: right;
- color: #777;
- }
- @media print {
- body {
- font-size: 8pt;
- }
- .noprint {
- display: none;
- }
- }
-
-
-.tip,
-.note {
- background: #f0f0f2;
- color: #333;
- padding: 20px;
- margin: 20px;
-}
-
-.tip h3,
-.note h3 {
- padding: 0em;
- margin: 0em;
- font-size: 2em;
- font-weight: bold;
- color: #333;
-}
-
-.tip a,
-.note a {
- color: #333;
- text-decoration: underline;
-}
-
-.footnote {
- font-size: small;
- color: #333;
-}
-
-/* Changes the announcement text */
-.tip h3,
-.warning h3,
-.caution h3,
-.note h3 {
- font-size:large;
- color: #00557D;
-}
diff --git a/poky/documentation/kernel-dev/kernel-dev.rst b/poky/documentation/kernel-dev/kernel-dev.rst
index 332e089..55b42ed 100644
--- a/poky/documentation/kernel-dev/kernel-dev.rst
+++ b/poky/documentation/kernel-dev/kernel-dev.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-2.0-UK
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
=============================================
Yocto Project Linux Kernel Development Manual
diff --git a/poky/documentation/kernel-dev/kernel-dev.xml b/poky/documentation/kernel-dev/kernel-dev.xml
deleted file mode 100755
index 887ff83..0000000
--- a/poky/documentation/kernel-dev/kernel-dev.xml
+++ /dev/null
@@ -1,187 +0,0 @@
-<!DOCTYPE book 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; ] >
-<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
-
-<book id='kernel-dev' lang='en'
- xmlns:xi="http://www.w3.org/2003/XInclude"
- xmlns="http://docbook.org/ns/docbook"
- >
- <bookinfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref='figures/kernel-dev-title.png'
- format='SVG'
- align='left' scalefit='1' width='100%'/>
- </imageobject>
- </mediaobject>
-
- <title>
- Yocto Project Linux Kernel Development Manual
- </title>
-
- <authorgroup>
- <author>
- <affiliation>
- <orgname>&ORGNAME;</orgname>
- </affiliation>
- <email>&ORGEMAIL;</email>
- </author>
- </authorgroup>
-
- <revhistory>
- <revision>
- <revnumber>1.4</revnumber>
- <date>April 2013</date>
- <revremark>The initial document released with the Yocto Project 1.4 Release.</revremark>
- </revision>
- <revision>
- <revnumber>1.5</revnumber>
- <date>October 2013</date>
- <revremark>Released with the Yocto Project 1.5 Release.</revremark>
- </revision>
- <revision>
- <revnumber>1.6</revnumber>
- <date>April 2014</date>
- <revremark>Released with the Yocto Project 1.6 Release.</revremark>
- </revision>
- <revision>
- <revnumber>1.7</revnumber>
- <date>October 2014</date>
- <revremark>Released with the Yocto Project 1.7 Release.</revremark>
- </revision>
- <revision>
- <revnumber>1.8</revnumber>
- <date>April 2015</date>
- <revremark>Released with the Yocto Project 1.8 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.0</revnumber>
- <date>October 2015</date>
- <revremark>Released with the Yocto Project 2.0 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.1</revnumber>
- <date>April 2016</date>
- <revremark>Released with the Yocto Project 2.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.2</revnumber>
- <date>October 2016</date>
- <revremark>Released with the Yocto Project 2.2 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.3</revnumber>
- <date>May 2017</date>
- <revremark>Released with the Yocto Project 2.3 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4</revnumber>
- <date>October 2017</date>
- <revremark>Released with the Yocto Project 2.4 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.5</revnumber>
- <date>May 2018</date>
- <revremark>Released with the Yocto Project 2.5 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.6</revnumber>
- <date>November 2018</date>
- <revremark>Released with the Yocto Project 2.6 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.7</revnumber>
- <date>May 2019</date>
- <revremark>Released with the Yocto Project 2.7 Release.</revremark>
- </revision>
- <revision>
- <revnumber>3.0</revnumber>
- <date>October 2019</date>
- <revremark>Released with the Yocto Project 3.0 Release.</revremark>
- </revision>
- <revision>
- <revnumber>3.1</revnumber>
- <date>&REL_MONTH_YEAR;</date>
- <revremark>Released with the Yocto Project 3.1 Release.</revremark>
- </revision>
- </revhistory>
-
- <copyright>
- <year>©RIGHT_YEAR;</year>
- <holder>Linux Foundation</holder>
- </copyright>
-
- <legalnotice>
- <para>
- Permission is granted to copy, distribute and/or modify this document under
- the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons.
- </para>
- <note><title>Manual Notes</title>
- <itemizedlist>
- <listitem><para>
- This version of the
- <emphasis>Yocto Project Linux Kernel Development Manual</emphasis>
- is for the &YOCTO_DOC_VERSION; release of the
- Yocto Project.
- To be sure you have the latest version of the manual
- for this release, go to the
- <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
- and select the manual from that site.
- Manuals from the site are more up-to-date than manuals
- derived from the Yocto Project released TAR files.
- </para></listitem>
- <listitem><para>
- If you located this manual through a web search, the
- version of the manual might not be the one you want
- (e.g. the search might have returned a manual much
- older than the Yocto Project version with which you
- are working).
- You can see all Yocto Project major releases by
- visiting the
- <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
- page.
- If you need a version of this manual for a different
- Yocto Project release, visit the
- <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
- and select the manual set by using the
- "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
- pull-down menus.
- </para></listitem>
- <listitem>
- <para>
- To report any inaccuracies or problems with this
- (or any other Yocto Project) manual, send an email to
- the Yocto Project documentation mailing list at
- <filename>docs@lists.yoctoproject.org</filename> or
- log into the freenode <filename>#yocto</filename> channel.
- </para>
- </listitem>
- </itemizedlist>
- </note>
- </legalnotice>
-
- </bookinfo>
-
- <xi:include href="kernel-dev-intro.xml"/>
-
- <xi:include href="kernel-dev-common.xml"/>
-
- <xi:include href="kernel-dev-advanced.xml"/>
-
- <xi:include href="kernel-dev-concepts-appx.xml"/>
-
- <xi:include href="kernel-dev-maint-appx.xml"/>
-
- <xi:include href="kernel-dev-faq.xml"/>
-
-<!-- <index id='index'>
- <title>Index</title>
- </index>
--->
-
-</book>
-<!--
-vim: expandtab tw=80 ts=4
--->