Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/kernel-dev/history.rst b/poky/documentation/kernel-dev/history.rst
index 761b506..3ffb7ea 100644
--- a/poky/documentation/kernel-dev/history.rst
+++ b/poky/documentation/kernel-dev/history.rst
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-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 eeb8f87..36133ca 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-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-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
new file mode 100644
index 0000000..3717796
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -0,0 +1,1257 @@
+<!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 64235f3..d4b60a9 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-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-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
new file mode 100644
index 0000000..8e8a6db
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-common.xml
@@ -0,0 +1,2730 @@
+<!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 5b6ebef..04cb117 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-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-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
new file mode 100644
index 0000000..bf0c525
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -0,0 +1,622 @@
+<!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
new file mode 100644
index 0000000..88bf7c6
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-customization.xsl
@@ -0,0 +1,28 @@
+<?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 70bf4a2..b5e6a84 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-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-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
new file mode 100644
index 0000000..d76f0a4
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-faq.xml
@@ -0,0 +1,143 @@
+<!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 447cddb..21d43d5 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-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-2.0-UK
************
Introduction
diff --git a/poky/documentation/kernel-dev/kernel-dev-intro.xml b/poky/documentation/kernel-dev/kernel-dev-intro.xml
new file mode 100644
index 0000000..7c1ea0e
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-intro.xml
@@ -0,0 +1,260 @@
+<!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 1788332..5514dac 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-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-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
new file mode 100644
index 0000000..3d9c7c6
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-maint-appx.xml
@@ -0,0 +1,357 @@
+<!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
new file mode 100644
index 0000000..fc6fbb8
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev-style.css
@@ -0,0 +1,991 @@
+/*
+
+ 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 55b42ed..332e089 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-SA-2.0-UK
+.. SPDX-License-Identifier: CC-BY-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
new file mode 100755
index 0000000..887ff83
--- /dev/null
+++ b/poky/documentation/kernel-dev/kernel-dev.xml
@@ -0,0 +1,187 @@
+<!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
+-->