Squashed 'yocto-poky/' content from commit ea562de
git-subtree-dir: yocto-poky
git-subtree-split: ea562de57590c966cd5a75fda8defecd397e6436
diff --git a/documentation/kernel-dev/figures/kernel-architecture-overview.png b/documentation/kernel-dev/figures/kernel-architecture-overview.png
new file mode 100755
index 0000000..2aad172
--- /dev/null
+++ b/documentation/kernel-dev/figures/kernel-architecture-overview.png
Binary files differ
diff --git a/documentation/kernel-dev/figures/kernel-dev-title.png b/documentation/kernel-dev/figures/kernel-dev-title.png
new file mode 100644
index 0000000..7a8dd54
--- /dev/null
+++ b/documentation/kernel-dev/figures/kernel-dev-title.png
Binary files differ
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
new file mode 100644
index 0000000..4fdb853
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -0,0 +1,1088 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-advanced'>
+<title>Working with Advanced Metadata</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_DEV_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, known as
+ the kern-tools (<filename>kern-tools-native_git.bb</filename>), is
+ to help you manage the complexity of the configuration and sources
+ used to support multiple BSPs and Linux kernel types.
+ </para>
+</section>
+
+<section id='using-kernel-metadata-in-a-recipe'>
+ <title>Using Kernel Metadata in a Recipe</title>
+
+ <para>
+ The kernel sources in the Yocto Project contain kernel Metadata, which
+ is located in the <filename>meta</filename> branches of the kernel
+ source Git repositories.
+ This Metadata defines Board Support Packages (BSPs) that
+ correspond to definitions in linux-yocto recipes for the same BSPs.
+ A BSP consists of an aggregation of kernel policy and hardware-specific
+ feature enablements.
+ The BSP can be influenced from within the linux-yocto recipe.
+ <note>
+ Linux kernel source that contains kernel Metadata is said to be
+ "linux-yocto style" kernel source.
+ A Linux kernel recipe that inherits from the
+ <filename>linux-yocto.inc</filename> include file is said to be a
+ "linux-yocto style" recipe.
+ </note>
+ </para>
+
+ <para>
+ Every linux-yocto style recipe must define the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
+ variable.
+ This variable is typically set to the same value as the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable, which is used by
+ <ulink url='&YOCTO_DOCS_DEV_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.
+ The "ep108-zynqmp" and "qemuzynqmp" BSP combination
+ in the <filename>meta-xilinx</filename>
+ layer is a good example of two BSPs using the same
+ <filename>KMACHINE</filename> value (i.e. "zynqmp").
+ 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-emenlow</filename> layer:
+ <literallayout class='monospaced'>
+ KBRANCH_emenlow-noemgd = "standard/base"
+ </literallayout>
+ </note>
+ </para>
+
+ <para>
+ The linux-yocto style recipes can optionally define the following
+ variables:
+ <literallayout class='monospaced'>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink>
+ </literallayout>
+ </para>
+
+ <para>
+ <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be
+ used in assembling the configuration.
+ If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
+ it defaults to "standard".
+ Together with
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
+ <filename>LINUX_KERNEL_TYPE</filename> defines the search
+ arguments used by the kernel tools to find the
+ appropriate description within the kernel Metadata with which to
+ build out the sources and configuration.
+ The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
+ kernel types.
+ See the "<link linkend='kernel-types'>Kernel Types</link>" section
+ for more information on kernel types.
+ </para>
+
+ <para>
+ During the build, the kern-tools search for the BSP description
+ file that most closely matches the <filename>KMACHINE</filename>
+ and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the
+ recipe.
+ The tools use the first BSP description it finds that match
+ both variables.
+ If the tools cannot find a match, they issue a warning such as
+ the following:
+ <literallayout class='monospaced'>
+ WARNING: Can't find any BSP hardware or required configuration fragments.
+ WARNING: Looked at meta/cfg/broken/emenlow-broken/hdw_frags.txt and
+ meta/cfg/broken/emenlow-broken/required_frags.txt in directory:
+ meta/cfg/broken/emenlow-broken
+ </literallayout>
+ In this example, <filename>KMACHINE</filename> was set to "emenlow-broken"
+ and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken".
+ </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 <filename>KERNEL_FEATURES</filename> 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>meta</filename>
+ branch of the <filename>linux-yocto-3.19</filename> repository.
+ Within that branch, "features" and "cfg" are subdirectories of the
+ <filename>meta/cfg/kernel-cache</filename> directory.
+ For more information, see the
+ "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section.
+ <note>
+ The processing of the these variables has evolved some between the
+ 0.9 and 1.3 releases of the Yocto Project and associated
+ kern-tools sources.
+ The descriptions in this section are accurate for 1.3 and later
+ releases of the Yocto Project.
+ </note>
+ </para>
+</section>
+
+<section id='kernel-metadata-location'>
+ <title>Kernel Metadata Location</title>
+
+ <para>
+ Kernel Metadata can be defined in either the kernel recipe
+ (recipe-space) or in the kernel tree (in-tree).
+ 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 the kernel Metadata in the same
+ repository as the Linux kernel sources.
+ This method 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>
+ </section>
+
+ <section id='in-tree-metadata'>
+ <title>In-Tree Metadata</title>
+
+ <para>
+ When stored in-tree, the kernel Metadata files reside in the
+ <filename>meta</filename> directory of the Linux kernel sources.
+ The <filename>meta</filename> directory can be present in the
+ same repository branch as the sources,
+ such as "master", or <filename>meta</filename> can be its own
+ orphan branch.
+ <note>
+ An orphan branch in Git is a branch with unique history and
+ content to the other branches in the repository.
+ Orphan branches are useful to track Metadata changes
+ independently from the sources of the Linux kernel, while
+ still keeping them together in the same repository.
+ </note>
+ For the purposes of this document, we will discuss all
+ in-tree Metadata as residing below the
+ <filename>meta/cfg/kernel-cache</filename> directory.
+ </para>
+
+ <para>
+ Following is an example that shows how a trivial tree of Metadata
+ is stored in a custom Linux kernel Git repository:
+ <literallayout class='monospaced'>
+ meta/
+ `-- cfg
+ `-- kernel-cache
+ |-- bsp-standard.scc
+ |-- bsp.cfg
+ `-- standard.cfg
+ </literallayout>
+ </para>
+
+ <para>
+ To use a branch different from where the sources reside,
+ specify the branch in the <filename>KMETA</filename> variable
+ in your Linux kernel recipe.
+ Here is an example:
+ <literallayout class='monospaced'>
+ KMETA = "meta"
+ </literallayout>
+ To use the same branch as the sources, set
+ <filename>KMETA</filename> to an empty string:
+ <literallayout class='monospaced'>
+ KMETA = ""
+ </literallayout>
+ If you are working with your own sources and want to create an
+ orphan <filename>meta</filename> branch, use these commands
+ from within your Linux kernel Git repository:
+ <literallayout class='monospaced'>
+ $ git checkout --orphan meta
+ $ git rm -rf .
+ $ git commit --allow-empty -m "Create orphan meta branch"
+ </literallayout>
+ </para>
+
+ <para>
+ If you modify the Metadata in the linux-yocto
+ <filename>meta</filename> branch, you must not forget to update
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+ statements in the kernel's recipe.
+ In particular, you need to update the
+ <filename>SRCREV_meta</filename> variable to match the commit in
+ the <filename>KMETA</filename> branch you wish to use.
+ Changing the data in these branches and not updating the
+ <filename>SRCREV</filename> statements to match will cause the
+ build to fetch an older commit.
+ </para>
+ </section>
+</section>
+
+<section id='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
+ <filename><base></filename>, 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 <filename>meta/cfg/kernel-cache/</filename> if you are creating
+ Metadata <link linkend='in-tree-metadata'>in-tree</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>
+ The Symmetric Multi-Processing (SMP) fragment included in the
+ <filename>linux-yocto-3.19</filename> Git repository
+ consists of the following two files:
+ <literallayout class='monospaced'>
+ cfg/smp.scc:
+ define KFEATURE_DESCRIPTION "Enable SMP"
+ 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
+ </literallayout>
+ You can find information on configuration fragment files in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
+ section of the Yocto Project Development Manual and in
+ the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+ section earlier in this manual.
+ </para>
+
+ <para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>
+ provides a short description of the fragment.
+ Higher level kernel tools use this description.
+ </para>
+
+ <para>
+ The <filename>kconf</filename> command is used to include 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='generating-configuration-files'>Generating Configuration Files</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.
+ </para>
+
+ <para>
+ A typical patch includes a description file and the patch itself:
+ <literallayout class='monospaced'>
+ patches/mypatch.scc:
+ patch mypatch.patch
+
+ patches/mypatch.patch:
+ <replaceable>typical-patch</replaceable>
+ </literallayout>
+ You can create the typical <filename>.patch</filename>
+ file using <filename>diff -Nurp</filename> or
+ <filename>git format-patch</filename>.
+ </para>
+
+ <para>
+ The description file can include multiple patch statements,
+ one per patch.
+ </para>
+ </section>
+
+ <section id='features'>
+ <title>Features</title>
+
+ <para>
+ Features are complex kernel Metadata types that consist
+ of configuration fragments (<filename>kconf</filename>), patches
+ (<filename>patch</filename>), and possibly other feature
+ description files (<filename>include</filename>).
+ </para>
+
+ <para>
+ Here is an example that shows a feature description file:
+ <literallayout class='monospaced'>
+ features/myfeature.scc
+ define KFEATURE_DESCRIPTION "Enable myfeature"
+
+ patch 0001-myfeature-core.patch
+ patch 0002-myfeature-interface.patch
+
+ include cfg/myfeature_dependency.scc
+ kconf non-hardware myfeature.cfg
+ </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.
+ </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 kernels of a
+ specific type.
+ Syntactically, kernel types are no different than features
+ as described in the "<link linkend='features'>Features</link>"
+ section.
+ The <filename>LINUX_KERNEL_TYPE</filename> variable in the kernel
+ recipe selects the kernel type.
+ See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
+ section for more information.
+ </para>
+
+ <para>
+ As an example, the <filename>linux-yocto-3.19</filename>
+ tree defines three kernel types: "standard",
+ "tiny", and "preempt-rt":
+ <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>
+ The "standard" kernel type is defined by
+ <filename>standard.scc</filename>:
+ <literallayout class='monospaced'>
+ # Include this kernel type fragment to get the standard features and
+ # configuration values.
+
+ # Include all standard features
+ include standard-nocfg.scc
+
+ kconf non-hardware standard.cfg
+
+ # individual cfg block section
+ include cfg/fs/devtmpfs.scc
+ include cfg/fs/debugfs.scc
+ include cfg/fs/btrfs.scc
+ include cfg/fs/ext2.scc
+ include cfg/fs/ext3.scc
+ include cfg/fs/ext4.scc
+
+ include cfg/net/ipv6.scc
+ include cfg/net/ip_nf.scc
+ include cfg/net/ip6_nf.scc
+ include cfg/net/bridge.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 combine kernel types with hardware-specific
+ features.
+ The hardware-specific portion is typically defined
+ independently, and then aggregated with each supported kernel
+ type.
+ Consider this simple BSP description that supports the
+ <replaceable>mybsp</replaceable> machine:
+ <literallayout class='monospaced'>
+ <replaceable>mybsp</replaceable>.scc:
+ define KMACHINE <replaceable>mybsp</replaceable>
+ define KTYPE standard
+ define KARCH i386
+
+ kconf <replaceable>mybsp</replaceable>.cfg
+ </literallayout>
+ Every BSP description 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 simple example supports the "mybsp" machine for the "standard"
+ kernel and the "i386" 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 kernel types defined in your kernel
+ Metadata, you only need to ensure that the kernel recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
+ variable and the <filename>KTYPE</filename> variable in the
+ BSP description file match.
+ <note>
+ Future versions of the tooling make the specification of
+ <filename>KTYPE</filename> in the BSP optional.
+ </note>
+ </para>
+
+ <para>
+ If you did want to separate your kernel policy from your
+ hardware configuration, you could do so by specifying a kernel
+ type, such as "standard" and including that description file
+ in the BSP description file.
+ See the "<link linkend='kernel-types'>Kernel Types</link>" section
+ for more information.
+ </para>
+
+ <para>
+ You might also have multiple hardware configurations that you
+ aggregate into a single hardware description file that you
+ could include in the BSP description file, rather than referencing
+ a single <filename>.cfg</filename> file.
+ Consider the following:
+ <literallayout class='monospaced'>
+ <replaceable>mybsp</replaceable>.scc:
+ define KMACHINE mybsp
+ define KTYPE standard
+ define KARCH i386
+
+ include standard.scc
+ include <replaceable>mybsp</replaceable>-hw.scc
+ </literallayout>
+ </para>
+
+ <para>
+ In the above example, <filename>standard.scc</filename>
+ aggregates all the configuration fragments, patches, and
+ features that make up your standard kernel policy whereas
+ <replaceable>mybsp</replaceable><filename>-hw.scc</filename>
+ aggregates all those necessary
+ to support the hardware available on the
+ <replaceable>mybsp</replaceable> machine.
+ For information on how to break a complete
+ <filename>.config</filename> file into the various
+ configuration fragments, see the
+ "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+ section.
+ </para>
+
+ <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 from the
+ <filename>linux-yocto-3.19</filename>
+ Git repository:
+ <literallayout class='monospaced'>
+ minnow.scc:
+ include cfg/x86.scc
+ include features/eg20t/eg20t.scc
+ include cfg/dmaengine.scc
+ include features/power/intel.scc
+ include cfg/efi.scc
+ include features/usb/ehci-hcd.scc
+ include features/usb/ohci-hcd.scc
+ include features/usb/usb-gadgets.scc
+ include features/usb/touchscreen-composite.scc
+ include cfg/timer/hpet.scc
+ include cfg/timer/rtc.scc
+ include features/leds/leds.scc
+ include features/spi/spidev.scc
+ include features/i2c/i2cdev.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 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:
+ <literallayout class='monospaced'>
+ minnow-standard.scc:
+ define KMACHINE minnow
+ define KTYPE standard
+ define KARCH i386
+
+ include ktypes/standard
+
+ include minnow.scc
+
+ # Extra minnow configs above the minimal defined in minnow.scc
+ include cfg/efi-ext.scc
+ include features/media/media-all.scc
+ include features/sound/snd_hda_intel.scc
+
+ # The following should really be in standard.scc
+ # USB live-image support
+ include cfg/usb-mass-storage.scc
+ include cfg/boot-live.scc
+
+ # Basic profiling
+ include features/latencytop/latencytop.scc
+ include features/profiling/profiling.scc
+
+ # Requested drivers that don't have an existing scc
+ kconf hardware minnow-drivers-extra.cfg
+ </literallayout>
+ The <filename>include</filename> command midway through the file
+ includes the <filename>minnow.scc</filename> description that
+ defines all hardware enablements 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:
+ <literallayout class='monospaced'>
+ minnow-tiny.scc:
+ 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:
+ <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
+ and <filename>KARCH</filename>.
+ Of these variables, only the <filename>KTYPE</filename> has changed.
+ It is now set to "tiny".
+ </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 linux-yocto Linux
+ kernel repositories use:
+ <literallayout class='monospaced'>
+ <replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable>
+ </literallayout>
+ </para>
+
+ <para>
+ If you had two kernel types, "standard" and "small" for
+ instance, three machines, and <replaceable>common</replaceable>
+ as <filename>mydir</filename>, the branches in your
+ Git repository might look like this:
+ <literallayout class='monospaced'>
+ mydir/base
+ mydir/standard/base
+ mydir/standard/machine_a
+ mydir/standard/machine_b
+ mydir/standard/machine_c
+ mydir/small/base
+ mydir/small/machine_a
+ </literallayout>
+ </para>
+
+ <para>
+ This organization can help clarify the branch relationships.
+ In this case, <filename>mydir/standard/machine_a</filename>
+ includes everything in <filename>mydir/base</filename> and
+ <filename>mydir/standard/base</filename>.
+ The "standard" and "small" branches add sources specific to those
+ kernel types that for whatever reason are not appropriate for the
+ other branches.
+ <note>The "base" branches are an artifact of the way Git manages
+ its data internally on the filesystem: Git will not allow you
+ to use <filename>mydir/standard</filename> and
+ <filename>mydir/standard/machine_a</filename> because it
+ would have to create a file and a directory named "standard".
+ </note>
+ </para>
+ </section>
+
+ <section id='feature-branches'>
+ <title>Feature Branches</title>
+
+ <para>
+ When you are actively developing new features, it can be more
+ efficient to work with that feature as a branch, rather than
+ as a set of patches that have to be regularly updated.
+ The Yocto Project Linux kernel tools provide for this with
+ the <filename>git merge</filename> command.
+ </para>
+
+ <para>
+ To merge a feature branch into a BSP, insert the
+ <filename>git merge</filename> command after any
+ <filename>branch</filename> commands:
+ <literallayout class='monospaced'>
+ mybsp.scc:
+ define KMACHINE mybsp
+ define KTYPE standard
+ define KARCH i386
+ include standard.scc
+
+ branch mynewbranch
+ git merge myfeature
+
+ include mybsp-hw.scc
+ </literallayout>
+ </para>
+ </section>
+</section>
+
+<section id='scc-reference'>
+ <title>SCC Description File Reference</title>
+
+ <para>
+ This section provides a brief reference for the commands you can use
+ within an SCC description file (<filename>.scc</filename>):
+ <itemizedlist>
+ <listitem><para><filename>branch [ref]</filename>:
+ Creates a new branch relative to the current branch
+ (typically <filename>${KTYPE}</filename>) using
+ the currently checked-out branch, or "ref" if specified.
+ </para></listitem>
+ <listitem><para><filename>define</filename>:
+ Defines variables, such as <filename>KMACHINE</filename>,
+ <filename>KTYPE</filename>, <filename>KARCH</filename>,
+ and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
+ <listitem><para><filename>include SCC_FILE</filename>:
+ Includes an SCC file in the current file.
+ The file is parsed as if you had inserted it inline.
+ </para></listitem>
+ <listitem><para><filename>kconf [hardware|non-hardware] CFG_FILE</filename>:
+ Queues a configuration fragment for merging into the final
+ Linux <filename>.config</filename> file.</para></listitem>
+ <listitem><para><filename>git merge GIT_BRANCH</filename>:
+ Merges the feature branch into the current branch.
+ </para></listitem>
+ <listitem><para><filename>patch PATCH_FILE</filename>:
+ Applies the patch to the current Git branch.</para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
new file mode 100644
index 0000000..27c82ce
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -0,0 +1,1033 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-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 a layer, modifying an existing recipe,
+ 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
+ 1.2.2 Release and forward.
+ </note>
+</para>
+
+ <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_DEV_URL;#bitbake-term'>BitBake</ulink>
+ append files
+ (<filename>.bbappend</filename>) and provides a convenient
+ mechanism to create your own recipe files
+ (<filename>.bb</filename>).
+ For details on how to create and work with layers, see the following
+ sections in the Yocto Project Development Manual:
+ <itemizedlist>
+ <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for
+ general information on layers and how to create layers.</para></listitem>
+ <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for
+ specific instructions on setting up a layer for kernel
+ development.</para></listitem>
+ </itemizedlist>
+ </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_DEV_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 some general resources.
+ You can also see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section
+ of the Yocto Project Development Manual for a detailed
+ example.
+ </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_3.19.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_3.19.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>
+ </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, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
+ section in the Yocto Project Development Manual.
+ </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
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
+ section in the Yocto Project Development Manual.
+ </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,
+ edit the recipe that builds your kernel so that it has the
+ following command form:
+ <literallayout class='monospaced'>
+ KBUILD_DEFCONFIG_<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'>KMACHINE</ulink> ?= <replaceable>defconfig_file</replaceable>
+ </literallayout>
+ You need to append the variable with
+ <filename>KMACHINE</filename> and then supply the path to
+ your "in-tree" <filename>defconfig</filename> file.
+ </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-an-iterative-development-process'>
+ <title>Using an Iterative Development Process</title>
+
+ <para>
+ If you do not have existing patches or configuration files,
+ you can iteratively generate them from within the BitBake build
+ environment as described within this section.
+ During an iterative workflow, running a previously completed BitBake
+ task causes BitBake to invalidate the tasks that follow the
+ completed task in the build sequence.
+ Invalidated tasks rebuild the next time you run the build using
+ BitBake.
+ </para>
+
+ <para>
+ As you read this section, be sure to substitute the name
+ of your Linux kernel recipe for the term
+ "linux-yocto".
+ </para>
+
+ <section id='tip-dirty-string'>
+ <title>"-dirty" String</title>
+
+<!--
+ <para>
+ <emphasis>AR - Darren Hart:</emphasis> This section
+ originated from the old Yocto Project Kernel Architecture
+ and Use Manual.
+ It was decided we need to put it in this section here.
+ Darren needs to figure out where we want it and what part
+ of it we want (all, revision???)
+ </para>
+-->
+
+ <para>
+ If kernel images are being built with "-dirty" on the
+ end of the version string, this simply means that
+ modifications in the source directory have not been committed.
+ <literallayout class='monospaced'>
+ $ git status
+ </literallayout>
+ </para>
+
+ <para>
+ You can use the above Git command to report modified,
+ removed, or added files.
+ You should commit those changes to the tree regardless of
+ whether they will be saved, exported, or used.
+ Once you commit the changes, you need to rebuild the kernel.
+ </para>
+
+ <para>
+ To force a pickup and commit of all such pending changes,
+ enter the following:
+ <literallayout class='monospaced'>
+ $ git add .
+ $ git commit -s -a -m "getting rid of -dirty"
+ </literallayout>
+ </para>
+
+ <para>
+ Next, rebuild the kernel.
+ </para>
+ </section>
+
+ <section id='generating-configuration-files'>
+ <title>Generating Configuration Files</title>
+
+ <para>
+ You can manipulate the <filename>.config</filename> file
+ used to build a linux-yocto recipe with the
+ <filename>menuconfig</filename> command as follows:
+ <literallayout class='monospaced'>
+ $ bitbake linux-yocto -c menuconfig
+ </literallayout>
+ This command starts the Linux kernel configuration tool,
+ which allows you to prepare a new
+ <filename>.config</filename> file for the build.
+ When you exit the tool, be sure to save your changes
+ at the prompt.
+ </para>
+
+ <para>
+ The resulting <filename>.config</filename> file is
+ located in
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the
+ <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>}-build</filename> directory.
+ You can use the entire <filename>.config</filename> file as the
+ <filename>defconfig</filename> file as described in the
+ "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
+ </para>
+
+ <para>
+ A better 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>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 will be creating a
+ <filename>.config</filename> file from a known state.
+ Because situations exist where your build state might
+ become unknown, it is best to run the previous
+ command prior to starting up
+ <filename>menuconfig</filename>.
+ </para></listitem>
+ <listitem><para>Run the <filename>menuconfig</filename>
+ command:
+ <literallayout class='monospaced'>
+ $ bitbake linux-yocto -c menuconfig
+ </literallayout></para></listitem>
+ <listitem><para>Run the <filename>diffconfig</filename>
+ command to prepare a configuration fragment.
+ The resulting file <filename>fragment.cfg</filename>
+ will be 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 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>
+ The kernel tools also provide configuration validation.
+ You can use these tools to produce 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.
+ Here is an example with some sample output of the command
+ that runs these tools:
+ <literallayout class='monospaced'>
+ $ bitbake linux-yocto -c kernel_configcheck -f
+
+ ...
+
+ NOTE: validating kernel configuration
+ This BSP sets 3 invalid/obsolete kernel options.
+ These config options are not offered anywhere within this kernel.
+ The full list can be found in your kernel src dir at:
+ meta/cfg/standard/mybsp/invalid.cfg
+
+ This BSP sets 21 kernel options that are possibly non-hardware related.
+ The full list can be found in your kernel src dir at:
+ meta/cfg/standard/mybsp/specified_non_hdw.cfg
+
+ WARNING: There were 2 hardware options requested that do not
+ have a corresponding value present in the final ".config" file.
+ This probably means you are not getting the config you wanted.
+ The full list can be found in your kernel src dir at:
+ meta/cfg/standard/mybsp/mismatch.cfg
+ </literallayout>
+ </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
+ <filename>kernel_configme</filename> and
+ <filename>kernel_configcheck</filename> commands until
+ they produce no warnings.
+ </para>
+
+ <para>
+ For more information on how to use the
+ <filename>menuconfig</filename> tool, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
+ section in the Yocto Project Development Manual.
+ </para>
+ </section>
+
+ <section id='modifying-source-code'>
+ <title>Modifying Source Code</title>
+
+ <para>
+ You can experiment with source code changes and create a
+ simple patch without leaving the BitBake environment.
+ To get started, be sure to complete a build at
+ least through the kernel configuration task:
+ <literallayout class='monospaced'>
+ $ bitbake linux-yocto -c kernel_configme -f
+ </literallayout>
+ Taking this step ensures you have the sources prepared
+ and the configuration completed.
+ You can find the sources in the
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.
+ </para>
+
+ <para>
+ You can edit the sources as you would any other Linux source
+ tree.
+ However, keep in mind that you will lose changes if you
+ trigger the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
+ task for the recipe.
+ You can avoid triggering this task by not using BitBake to
+ run the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>cleanall</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>cleansstate</filename></ulink>,
+ or forced
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>fetch</filename></ulink>
+ commands.
+ Also, do not modify the recipe itself while working
+ with temporary changes or BitBake might run the
+ <filename>fetch</filename> command depending on the
+ changes to the recipe.
+ </para>
+
+ <para>
+ To test your temporary changes, instruct BitBake to run the
+ <filename>compile</filename> again.
+ The <filename>-f</filename> option forces the command to run
+ even though BitBake might think it has already done so:
+ <literallayout class='monospaced'>
+ $ bitbake linux-yocto -c compile -f
+ </literallayout>
+ If the compile fails, you can update the sources and repeat
+ the <filename>compile</filename>.
+ Once compilation is successful, you can inspect and test
+ the resulting build (i.e. kernel, modules, and so forth) from
+ the following build directory:
+ <literallayout class='monospaced'>
+ ${WORKDIR}/linux-${PACKAGE_ARCH}-${LINUX_KERNEL_TYPE}-build
+ </literallayout>
+ Alternatively, you can run the <filename>deploy</filename>
+ command to place the kernel image in the
+ <filename>tmp/deploy/images</filename> directory:
+ <literallayout class='monospaced'>
+ $ bitbake linux-yocto -c deploy
+ </literallayout>
+ And, of course, you can perform the remaining installation and
+ packaging steps by issuing:
+ <literallayout class='monospaced'>
+ $ bitbake linux-yocto
+ </literallayout>
+ </para>
+
+ <para>
+ For rapid iterative development, the edit-compile-repeat loop
+ described in this section is preferable to rebuilding the
+ entire recipe because the installation and packaging tasks
+ are very time consuming.
+ </para>
+
+ <para>
+ Once you are satisfied with your source code modifications,
+ you can make them permanent by generating patches and
+ applying them to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statement as described in the
+ "<link linkend='applying-patches'>Applying Patches</link>"
+ section.
+ If you are not familiar with generating patches, refer to the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
+ section in the Yocto Project Development Manual.
+ </para>
+ </section>
+ </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_DEV_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>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 Linux kernel you
+ are using (e.g.
+ <filename>linux-yocto-myproject_3.19.bb</filename>,
+ where "3.19" is the base version of the Linux kernel
+ with which you would be working).</para></listitem>
+ <listitem><para>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>Make sure you have either a
+ <filename>defconfig</filename> file or configuration
+ fragment files.
+ 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> to the
+ <filename>files</filename> directory 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.
+ 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>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.
+ "3.19").</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>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='http://git.yoctoproject.org/cgit.cgi'></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>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
new file mode 100644
index 0000000..ac91749
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -0,0 +1,253 @@
+<!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; ] >
+
+<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, like other kernels, are based off the Linux
+ kernel releases from <ulink url='http://www.kernel.org'></ulink>.
+ At the beginning of a major development cycle, the Yocto Project team
+ chooses its 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 kernel chosen is in the
+ final stages of development by the community.
+ In other words, the kernel is in the release
+ candidate or "rc" phase and not yet a 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 team to deliver the most up-to-date kernel
+ possible, while still ensuring that the team has a stable official release for
+ the baseline Linux kernel version.
+ </para>
+ <para>
+ The ultimate source for kernels available through the Yocto Project are released kernels
+ from <filename>kernel.org</filename>.
+ In addition to a foundational kernel from <filename>kernel.org</filename>, the
+ kernels available contain a mix of important new mainline
+ developments, non-mainline developments (when there is no alternative),
+ 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>
+ Once a 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
+ kernel development, BSP support, and release timing to select the best
+ possible <filename>kernel.org</filename> version.
+ The team continually monitors 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 kernel both adds features and introduces new bugs.
+ These consequences are the basic properties of upstream kernel development and are
+ managed by the Yocto Project team's kernel strategy.
+ It is the Yocto Project team's policy to not back-port minor features to the released 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 kernel can easily create mismatches, incompatibilities and very
+ subtle errors.
+ </para>
+ <para>
+ These policies result in both a stable and a cutting
+ edge kernel that mixes forward ports of existing features and significant and critical
+ new functionality.
+ Forward porting functionality in the kernels available through the Yocto Project kernel
+ can be thought of as a "micro uprev."
+ The many “micro uprevs” produce a kernel version with a mix of
+ important new mainline, non-mainline, BSP developments and feature integrations.
+ This 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 kernels is evolving and the kernels are used in leading edge
+ feature and BSP development.
+ </para>
+ </section>
+
+ <section id='kernel-architecture'>
+ <title>Kernel Architecture</title>
+ <para>
+ This section describes the architecture of the kernels available through the
+ Yocto Project and provides information
+ on the mechanisms used to achieve that architecture.
+ </para>
+
+ <section id='architecture-overview'>
+ <title>Overview</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 used achieve that goal in a manner similar to the
+ upstream <filename>kernel.org</filename>.
+ </para>
+ <para>
+ You can think of a Yocto Project 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
+ source code manager (SCM) Git.
+ For information on Git as applied to the Yocto Project, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
+ Yocto Project Development Manual.
+ </para>
+ <para>
+ The result is that 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 kernel.
+ </para>
+ <para>
+ The following illustration shows the conceptual Yocto Project kernel.
+ </para>
+ <para>
+ <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 release) from
+ which the Yocto Project kernel is created.
+ From this point "up" 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 up the tree.
+ Placing these common features in the
+ tree this way means features do not have to be duplicated along individual branches of the
+ structure.
+ </para>
+ <para>
+ From the Yocto Project Baseline Kernel, branch points represent specific functionality
+ for individual 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 a real-time kernel.
+ </para>
+ <para>
+ In this example structure, the real-time kernel branch has common features for all
+ real-time 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 kernel needed for any given set
+ of requirements.
+ </para>
+ </section>
+
+ <section id='branching-and-workflow'>
+ <title>Branching Strategy and Workflow</title>
+ <para>
+ 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 branching strategy results in a tree that has features organized to be specific
+ for particular functionality, single kernel types, or a subset of kernel types.
+ This strategy also 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 they 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 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.
+ The developer does not need to be aware of the existence of any other branches at all.
+ Of course, there is value in the existence of 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>
+ 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 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='source-code-manager-git'>
+ <title>Source Code Manager - Git</title>
+ <para>
+ The Source Code Manager (SCM) is Git.
+ This SCM is the obvious mechanism for meeting the previously mentioned goals.
+ Not only is it the SCM for <filename>kernel.org</filename> but,
+ Git continues to grow in popularity and supports many different work flows,
+ front-ends and management techniques.
+ </para>
+ <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_DEV_URL;#git'>Git</ulink>"
+ section in the Yocto Project Development Manual.
+ These referenced sections overview Git and describe a minimal set of
+ commands that allows you to be functional using Git.
+ <note>
+ 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 Master" in order to use it with the Yocto Project.
+ </note>
+ </para>
+ </section>
+ </section>
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl
new file mode 100644
index 0000000..325b738
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-customization.xsl
@@ -0,0 +1,26 @@
+<?xml version='1.0'?>
+<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/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl
new file mode 100644
index 0000000..3c56a5a
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl
@@ -0,0 +1,35 @@
+<?xml version='1.0'?>
+<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/eclipse/eclipse3.xsl" />
+
+<!--
+
+ <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" />
+
+ <xsl:import
+ href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" />
+
+-->
+
+ <xsl:param name="chunker.output.indent" select="'yes'"/>
+ <xsl:param name="chunk.quietly" select="1"/>
+ <xsl:param name="chunk.first.sections" select="1"/>
+ <xsl:param name="chunk.section.depth" select="10"/>
+ <xsl:param name="use.id.as.filename" select="1"/>
+ <xsl:param name="ulink.target" select="'_self'" />
+ <xsl:param name="base.dir" select="'html/kernel-dev/'"/>
+ <xsl:param name="html.stylesheet" select="'../book.css'"/>
+ <xsl:param name="eclipse.manifest" select="0"/>
+ <xsl:param name="create.plugin.xml" select="0"/>
+ <xsl:param name="suppress.navigation" select="1"/>
+ <xsl:param name="generate.index" select="0"/>
+ <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/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml
new file mode 100644
index 0000000..9d9aef6
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-examples.xml
@@ -0,0 +1,918 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-how-to'>
+
+<title>Working with the Yocto Project Kernel</title>
+
+
+<section id='actions-org'>
+ <title>Introduction</title>
+ <para>
+ This chapter describes how to accomplish tasks involving a kernel's tree structure.
+ The information is designed to help the developer that wants to modify the Yocto
+ Project kernel and contribute changes upstream to the Yocto Project.
+ The information covers the following:
+ <itemizedlist>
+ <listitem><para>Tree construction</para></listitem>
+ <listitem><para>Build strategies</para></listitem>
+ <listitem><para>Workflow examples</para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+ <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 kernel repositories.
+ These kernel repositories are found under the heading "Yocto Linux Kernel" at
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
+ and can be 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/feature
+ in the product.
+ Those feature descriptions list all necessary patches,
+ configuration, branching, tagging and feature divisions found in a kernel.
+ Thus, the Yocto Project kernel repository (or tree) is built.
+ </para>
+ <para>
+ The existence of this tree allows you to access and clone a particular
+ Yocto Project 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 kernel in any clone of the Yocto Project kernel source repository
+ Git tree.
+ For example, the following command clones the Yocto Project baseline kernel that
+ branched off of <filename>linux.org</filename> version 3.4:
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/linux-yocto-3.4
+ </literallayout>
+ For another example of how to set up a local Git repository of the Yocto Project
+ kernel files, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
+ item in the Yocto Project Development Manual.
+ </para>
+ <para>
+ Once you have cloned the kernel Git repository on your local machine, you can
+ switch to the <filename>meta</filename> branch within the repository.
+ Here is an example that assumes the local Git repository for the kernel is in
+ a top-level directory named <filename>linux-yocto-3.4</filename>:
+ <literallayout class='monospaced'>
+ $ cd ~/linux-yocto-3.4
+ $ git checkout -b meta origin/meta
+ </literallayout>
+ Once you have checked out and switched to the <filename>meta</filename> branch,
+ you can see a snapshot of all the kernel configuration and feature descriptions that are
+ used to build that particular kernel repository.
+ These descriptions are in the form of <filename>.scc</filename> files.
+ </para>
+ <para>
+ You should realize, however, that browsing your local kernel 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.
+ For examples showing how to use Git to inspect kernel commits, see the following sections
+ in this chapter.
+ <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;/cgit.cgi'></ulink> given the
+ introduction of a new top-level kernel feature or BSP.
+ These are the actions that effectively create the tree
+ that includes the new feature, patch or BSP:
+ <orderedlist>
+ <listitem><para>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>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 <filename>meta/cfg/kernel-cache</filename></para></listitem>
+ <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
+ found in 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:
+ <literallayout class='monospaced'>
+ <bsp_name>-<kernel_type>.scc
+ </literallayout>
+ </para></listitem>
+ <listitem><para>Once located, the feature description is either compiled into a simple script
+ of actions, or into an existing equivalent script that is already part of the
+ shipped kernel.</para></listitem>
+ <listitem><para>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>Each extra feature is located, compiled and appended to the script
+ as described in step three.</para></listitem>
+ <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
+ directories.
+ These directories 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>The base repository is cloned, and the actions
+ listed in the <filename>meta-*</filename> directories are applied to the
+ tree.</para></listitem>
+ <listitem><para>The Git repository is left with the desired branch checked out and any
+ required branching, patching and tagging has been performed.</para></listitem>
+ </orderedlist>
+ </para>
+ <para>
+ The kernel tree is now ready for developer consumption to be locally cloned,
+ configured, and built into a Yocto Project kernel specific to some target hardware.
+ <note><para>The generated <filename>meta-*</filename> directories add 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;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
+ is the combination of all supported boards and configurations.</para>
+ <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>
+ </note>
+ </para>
+ </section>
+
+ <section id='build-strategy'>
+ <title>Build Strategy</title>
+ <para>
+ Once a local Git repository of the Yocto Project kernel exists on a development system,
+ you can consider the compilation phase of kernel development - 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 exists.
+ This branch has the following form:
+ <literallayout class='monospaced'>
+ <kernel_type>/<bsp_name>
+ </literallayout></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, see
+ the "<link linkend='workflow-examples'>Workflow Examples</link>".
+ </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 <filename>meta-*</filename> 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}-<kernel_type>-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 build directory in its own separate branch
+ of the Git repository, you can easily switch between different builds.
+ </para>
+ </section>
+
+ <section id='workflow-examples'>
+ <title>Workflow Examples</title>
+
+ <para>
+ As previously noted, the Yocto Project kernel has built-in Git integration.
+ However, these utilities are not the only way to work with the kernel repository.
+ The Yocto Project has not made changes to Git or to other tools that
+ would invalidate alternate workflows.
+ Additionally, the way the kernel repository is constructed results in using
+ only core Git functionality, thus allowing any number of tools or front ends to use the
+ resulting tree.
+ </para>
+
+ <para>
+ This section contains several workflow examples.
+ Many of the examples use Git commands.
+ You can find Git documentation at
+ <ulink url='http://git-scm.com/documentation'></ulink>.
+ You can find a simple overview of using Git with the Yocto Project in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
+ section of the Yocto Project Development Manual.
+ </para>
+
+ <section id='change-inspection-kernel-changes-commits'>
+ <title>Change Inspection: Changes/Commits</title>
+
+ <para>
+ A common question when working with a kernel is:
+ "What changes have been applied to this tree?"
+ </para>
+
+ <para>
+ In projects that have a collection of directories that
+ contain patches to the kernel, it is possible to inspect or "grep" the contents
+ of the directories to get a general feel for the changes.
+ This sort of patch inspection is not an efficient way to determine what has been
+ done to the kernel.
+ The reason it is inefficient is because there are many optional patches that are
+ selected based on the kernel type and the feature description.
+ Additionally, patches could exist in directories that are not included in the search.
+ </para>
+
+ <para>
+ A more efficient way to determine what has changed in the branch is to use
+ Git and inspect or search the kernel tree.
+ This method gives you a full view of not only the source code modifications,
+ but also provides the reasons for the changes.
+ </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.
+ Because Git repositories in the Yocto Project do not break existing Git
+ functionality, and because there exists many permutations of these types of
+ Git commands, many methods exist by which you can discover 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='http://git.yoctoproject.org/cgit.cgi'></ulink>.
+ For example, the branch names for the <filename>linux-yocto-3.4</filename>
+ kernel repository can be seen at
+ <ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></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 (<filename><commit>..<commit></filename>).
+ </para>
+
+ <para>
+ Here is an example that looks at what has changed in the
+ <filename>emenlow</filename> branch of the
+ <filename>linux-yocto-3.4</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 a summary of changes use the <filename>git log</filename> command.
+ Here is an example using the same branches:
+ <literallayout class='monospaced'>
+ $ git log --oneline origin/standard/base..origin/standard/emenlow
+ </literallayout>
+ The <filename>git log</filename> output might be more useful than
+ the <filename>git whatchanged</filename> as you get
+ a short, one-line summary of each change and not the entire commit.
+ </para>
+
+ <para>
+ If you want to see code differences associated with all the changes, use
+ the <filename>git diff</filename> command.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ git diff origin/standard/base..origin/standard/emenlow
+ </literallayout>
+ </para>
+
+ <para>
+ You can see the commit log messages and the text differences using the
+ <filename>git show</filename> command:
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ git show origin/standard/base..origin/standard/emenlow
+ </literallayout>
+ </para>
+
+ <para>
+ You can create individual patches for each change by using the
+ <filename>git format-patch</filename> command.
+ 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='show-a-particular-feature-or-branch-change'>
+ <title>Show a Particular Feature or Branch Change</title>
+
+ <para>
+ Developers use tags in the Yocto Project kernel tree to divide changes for significant
+ features or branches.
+ Once you know a particular tag, you can use Git commands
+ to show changes associated with the tag and find the branches that contain
+ the feature.
+ <note>
+ Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
+ present, there could be many tags.
+ </note>
+ The <filename>git show <tag></filename> command shows changes that are tagged by
+ a feature.
+ Here is an example that shows changes tagged by the <filename>systemtap</filename>
+ feature:
+ <literallayout class='monospaced'>
+ $ git show systemtap
+ </literallayout>
+ You can use the <filename>git branch --contains <tag></filename> 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>
+
+ <para>
+ You can use many other comparisons to isolate BSP and kernel changes.
+ For example, you can compare against <filename>kernel.org</filename> tags
+ such as the <filename>v3.4</filename> tag.
+ </para>
+ </section>
+ </section>
+
+ <section id='development-saving-kernel-modifications'>
+ <title>Development: Saving Kernel Modifications</title>
+
+ <para>
+ Another common operation is to build a BSP supplied by the Yocto Project, make some
+ changes, rebuild, and then test.
+ Those local changes often need to be exported, shared or otherwise maintained.
+ </para>
+
+ <para>
+ Since the Yocto Project kernel source tree is backed by Git, this activity is
+ much easier as compared to with previous releases.
+ Because Git tracks file modifications, additions and deletions, it is easy
+ to modify the code and later realize that you need to save the changes.
+ It is also easy to determine what has changed.
+ This method also provides many tools to commit, undo and export those modifications.
+ </para>
+
+ <para>
+ This section and its sub-sections, describe general application of Git's
+ <filename>push</filename> and <filename>pull</filename> commands, which are used to
+ get your changes upstream or source your code from an upstream repository.
+ The Yocto Project provides scripts that help you work in a collaborative development
+ environment.
+ For information on these scripts, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
+ Upstream and Request a Pull</ulink>" and
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
+ sections in the Yocto Project Development Manual.
+ </para>
+
+ <para>
+ There are many ways to save kernel modifications.
+ The technique employed
+ depends on the destination for the patches:
+
+ <itemizedlist>
+ <listitem><para>Bulk storage</para></listitem>
+ <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
+ <listitem><para>External submissions</para></listitem>
+ <listitem><para>Exporting for integration into another Source Code
+ Manager (SCM)</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Because of the following list of issues, the destination of the patches also influences
+ the method for gathering them:
+
+ <itemizedlist>
+ <listitem><para>Bisectability</para></listitem>
+ <listitem><para>Commit headers</para></listitem>
+ <listitem><para>Division of subsystems for separate submission or review</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <section id='bulk-export'>
+ <title>Bulk Export</title>
+
+ <para>
+ This section describes how you can "bulk" export changes that have not
+ been separated or divided.
+ This situation works well when you are simply storing patches outside of the kernel
+ source repository, either permanently or temporarily, and you are not committing
+ incremental changes during development.
+ <note>
+ This technique is not appropriate for full integration of upstream submission
+ because changes are not properly divided and do not provide an avenue for per-change
+ commit messages.
+ Therefore, this example assumes that changes have not been committed incrementally
+ during development and that you simply must gather and export them.
+ </note>
+ <literallayout class='monospaced'>
+ # bulk export of ALL modifications without separation or division
+ # of the changes
+
+ $ git add .
+ $ git commit -s -a -m <msg>
+ or
+ $ git commit -s -a # and interact with $EDITOR
+ </literallayout>
+ </para>
+
+ <para>
+ The previous operations capture all the local changes in the project source
+ tree in a single Git commit.
+ And, that commit is also stored in the project's source tree.
+ </para>
+
+ <para>
+ Once the changes are exported, you can restore them manually using a template
+ or through integration with the <filename>default_kernel</filename>.
+ </para>
+
+ </section>
+
+ <section id='incremental-planned-sharing'>
+ <title>Incremental/Planned Sharing</title>
+
+ <para>
+ This section describes how to save modifications when you are making incremental
+ commits or practicing planned sharing.
+ The examples in this section assume that you have incrementally committed
+ changes to the tree during development and now need to export them.
+ The sections that follow
+ describe how you can export your changes internally through either patches or by
+ using Git commands.
+ </para>
+
+ <para>
+ During development, the following commands are of interest.
+ For full Git documentation, refer to the Git documentation at
+ <ulink url='http://github.com'></ulink>.
+
+ <literallayout class='monospaced'>
+ # edit a file
+ $ vi <path>/file
+ # stage the change
+ $ git add <path>/file
+ # commit the change
+ $ git commit -s
+ # remove a file
+ $ git rm <path>/file
+ # commit the change
+ $ git commit -s
+
+ ... etc.
+ </literallayout>
+ </para>
+
+ <para>
+ Distributed development with Git is possible when you use a universally
+ agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
+ specific change set with a specific parent.
+ This identifier is created for you when
+ you create a commit, and is re-created when you amend, alter or re-apply
+ a commit.
+ As an individual in isolation, this is of no interest.
+ However, if you
+ intend to share your tree with normal Git <filename>push</filename> and
+ <filename>pull</filename> operations for
+ distributed development, you should consider the ramifications of changing a
+ commit that you have already shared with others.
+ </para>
+
+ <para>
+ Assuming that the changes have not been pushed upstream, or pulled into
+ another repository, you can update both the commit content and commit messages
+ associated with development by using the following commands:
+
+ <literallayout class='monospaced'>
+ $ Git add <path>/file
+ $ Git commit --amend
+ $ Git rebase or Git rebase -i
+ </literallayout>
+ </para>
+
+ <para>
+ Again, assuming that the changes have not been pushed upstream, and that
+ no pending works-in-progress exist (use <filename>git status</filename> to check), then
+ you can revert (undo) commits by using the following commands:
+
+ <literallayout class='monospaced'>
+ # remove the commit, update working tree and remove all
+ # traces of the change
+ $ git reset --hard HEAD^
+ # remove the commit, but leave the files changed and staged for re-commit
+ $ git reset --soft HEAD^
+ # remove the commit, leave file change, but not staged for commit
+ $ git reset --mixed HEAD^
+ </literallayout>
+ </para>
+
+ <para>
+ You can create branches, "cherry-pick" changes, or perform any number of Git
+ operations until the commits are in good order for pushing upstream
+ or for pull requests.
+ After a <filename>push</filename> or <filename>pull</filename> command,
+ commits are normally considered
+ "permanent" and you should not modify them.
+ If the commits need to be changed, you can incrementally do so with new commits.
+ These practices follow standard Git workflow and the <filename>kernel.org</filename> best
+ practices, which is recommended.
+ <note>
+ It is recommended to tag or branch before adding changes to a Yocto Project
+ BSP or before creating a new one.
+ The reason for this recommendation is because the branch or tag provides a
+ reference point to facilitate locating and exporting local changes.
+ </note>
+ </para>
+
+ <section id='export-internally-via-patches'>
+ <title>Exporting Changes Internally by Using Patches</title>
+
+ <para>
+ This section describes how you can extract committed changes from a working directory
+ by exporting them as patches.
+ Once the changes have been extracted, you can use the patches for upstream submission,
+ place them in a Yocto Project template for automatic kernel patching,
+ or apply them in many other common uses.
+ </para>
+
+ <para>
+ This example shows how to create a directory with sequentially numbered patches.
+ Once the directory is created, you can apply it to a repository using the
+ <filename>git am</filename> command to reproduce the original commit and all
+ the related information such as author, date, commit log, and so forth.
+ <note>
+ The new commit identifiers (ID) will be generated upon re-application.
+ This action reflects that the commit is now applied to an underlying commit
+ with a different ID.
+ </note>
+ <literallayout class='monospaced'>
+ # <first-commit> can be a tag if one was created before development
+ # began. It can also be the parent branch if a branch was created
+ # before development began.
+
+ $ git format-patch -o <dir> <first commit>..<last commit>
+ </literallayout>
+ </para>
+
+ <para>
+ In other words:
+ <literallayout class='monospaced'>
+ # Identify commits of interest.
+
+ # If the tree was tagged before development
+ $ git format-patch -o <save dir> <tag>
+
+ # If no tags are available
+ $ git format-patch -o <save dir> HEAD^ # last commit
+ $ git format-patch -o <save dir> HEAD^^ # last 2 commits
+ $ git whatchanged # identify last commit
+ $ git format-patch -o <save dir> <commit id>
+ $ git format-patch -o <save dir> <rev-list>
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='export-internally-via-git'>
+ <title>Exporting Changes Internally by Using Git</title>
+
+ <para>
+ This section describes how you can export changes from a working directory
+ by pushing the changes into a master repository or by making a pull request.
+ Once you have pushed the changes to the master repository, you can then
+ pull those same changes into a new kernel build at a later time.
+ </para>
+
+ <para>
+ Use this command form to push the changes:
+ <literallayout class='monospaced'>
+ $ git push ssh://<master_server>/<path_to_repo>
+ <local_branch>:<remote_branch>
+ </literallayout>
+ </para>
+
+ <para>
+ For example, the following command pushes the changes from your local branch
+ <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
+ in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
+ <literallayout class='monospaced'>
+ $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
+ yocto/standard/common-pc/base:yocto/standard/common-pc/base
+ </literallayout>
+ </para>
+
+ <para>
+ A pull request entails using the <filename>git request-pull</filename> command to compose
+ an email to the
+ maintainer requesting that a branch be pulled into the master repository, see
+ <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
+ <note>
+ Other commands such as <filename>git stash</filename> or branching can also be used to save
+ changes, but are not covered in this document.
+ </note>
+ </para>
+ </section>
+ </section>
+
+ <section id='export-for-external-upstream-submission'>
+ <title>Exporting Changes for External (Upstream) Submission</title>
+
+ <para>
+ This section describes how to export changes for external upstream submission.
+ If the patch series is large or the maintainer prefers to pull
+ changes, you can submit these changes by using a pull request.
+ However, it is common to send patches as an email series.
+ This method allows easy review and integration of the changes.
+ <note>
+ Before sending patches for review be sure you understand the
+ community standards for submitting and documenting changes and follow their best practices.
+ For example, kernel patches should follow standards such as:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
+ <listitem><para>Documentation/SubmittingPatches (in any linux
+ kernel source tree)</para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The messages used to commit changes are a large part of these standards.
+ Consequently, be sure that the headers for each commit have the required information.
+ For information on how to follow the Yocto Project commit message standards, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
+ Change</ulink>" section in the Yocto Project Development Manual.
+ </para>
+
+ <para>
+ If the initial commits were not properly documented or do not meet those standards,
+ you can re-base by using the <filename>git rebase -i</filename> command to
+ manipulate the commits and
+ get them into the required format.
+ Other techniques such as branching and cherry-picking commits are also viable options.
+ </para>
+
+ <para>
+ Once you complete the commits, you can generate the email that sends the patches
+ to the maintainer(s) or lists that review and integrate changes.
+ The command <filename>git send-email</filename> is commonly used to ensure
+ that patches are properly
+ formatted for easy application and avoid mailer-induced patch damage.
+ </para>
+
+ <para>
+ The following is an example of dumping patches for external submission:
+ <literallayout class='monospaced'>
+ # dump the last 4 commits
+ $ git format-patch --thread -n -o ~/rr/ HEAD^^^^
+ $ git send-email --compose --subject '[RFC 0/N] <patch series summary>' \
+ --to foo@yoctoproject.org --to bar@yoctoproject.org \
+ --cc list@yoctoproject.org ~/rr
+ # the editor is invoked for the 0/N patch, and when complete the entire
+ # series is sent via email for review
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='export-for-import-into-other-scm'>
+ <title>Exporting Changes for Import into Another SCM</title>
+
+ <para>
+ When you want to export changes for import into another
+ Source Code Manager (SCM), you can use any of the previously discussed
+ techniques.
+ However, if the patches are manually applied to a secondary tree and then
+ that tree is checked into the SCM, you can lose change information such as
+ commit logs.
+ This process is not recommended.
+ </para>
+
+ <para>
+ Many SCMs can directly import Git commits, or can translate Git patches so that
+ information is not lost.
+ Those facilities are SCM-dependent and you should use them whenever possible.
+ </para>
+ </section>
+ </section>
+
+ <section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
+ <title>Working with the Yocto Project Kernel in Another SCM</title>
+
+ <para>
+ This section describes kernel development in an SCM other than Git,
+ which is not the same as exporting changes to another SCM described earlier.
+ For this scenario, you use the OpenEmbedded build system to
+ develop the kernel in a different SCM.
+ The following must be true for you to accomplish this:
+ <itemizedlist>
+ <listitem><para>The delivered Yocto Project kernel must be exported into the second
+ SCM.</para></listitem>
+ <listitem><para>Development must be exported from that secondary SCM into a
+ format that can be used by the OpenEmbedded build system.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <section id='exporting-delivered-kernel-to-scm'>
+ <title>Exporting the Delivered Kernel to the SCM</title>
+
+ <para>
+ Depending on the SCM, it might be possible to export the entire Yocto Project
+ kernel Git repository, branches and all, into a new environment.
+ This method is preferred because it has the most flexibility and potential to maintain
+ the meta data associated with each commit.
+ </para>
+
+ <para>
+ When a direct import mechanism is not available, it is still possible to
+ export a branch (or series of branches) and check them into a new repository.
+ </para>
+
+ <para>
+ The following commands illustrate some of the steps you could use to
+ import the <filename>yocto/standard/common-pc/base</filename>
+ kernel into a secondary SCM:
+ <literallayout class='monospaced'>
+ $ git checkout yocto/standard/common-pc/base
+ $ cd .. ; echo linux/.git > .cvsignore
+ $ cvs import -m "initial import" linux MY_COMPANY start
+ </literallayout>
+ </para>
+
+ <para>
+ You could now relocate the CVS repository and use it in a centralized manner.
+ </para>
+
+ <para>
+ The following commands illustrate how you can condense and merge two BSPs into a
+ second SCM:
+ <literallayout class='monospaced'>
+ $ git checkout yocto/standard/common-pc/base
+ $ git merge yocto/standard/common-pc-64/base
+ # resolve any conflicts and commit them
+ $ cd .. ; echo linux/.git > .cvsignore
+ $ cvs import -m "initial import" linux MY_COMPANY start
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='importing-changes-for-build'>
+ <title>Importing Changes for the Build</title>
+
+ <para>
+ Once development has reached a suitable point in the second development
+ environment, you need to export the changes as patches.
+ To export them, place the changes in a recipe and
+ automatically apply them to the kernel during patching.
+ </para>
+ </section>
+ </section>
+
+ <section id='bsp-creating'>
+ <title>Creating a BSP Based on an Existing Similar BSP</title>
+
+ <para>
+ This section overviews the process of creating a BSP based on an
+ existing similar BSP.
+ The information is introductory in nature and does not provide step-by-step examples.
+ For detailed information on how to create a new BSP, see
+ the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
+ Yocto Project Board Support Package (BSP) Developer's Guide, or see the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
+ wiki page.
+ </para>
+
+ <para>
+ The basic steps you need to follow are:
+ <orderedlist>
+ <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
+ You must create a local
+ <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+ by either creating a Git repository (recommended) or
+ extracting a Yocto Project release tarball.</para></listitem>
+ <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
+ Try to map your board features as closely to the features of a BSP that is
+ already supported and exists in the Yocto Project.
+ Starting with something as close as possible to your board makes developing
+ your BSP easier.
+ You can find all the BSPs that are supported and ship with the Yocto Project
+ on the Yocto Project's Download page at
+ <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
+ <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
+ You need to either have a local Git repository of the base BSP set up or
+ have downloaded and extracted the files from a release BSP tarball.
+ Either method gives you access to the BSP source files.</para></listitem>
+ <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
+ BSP work:</emphasis>
+ Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
+ <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
+ Configuration changes involve the files in the BSP's <filename>conf</filename>
+ directory.
+ Changes include creating a machine-specific configuration file and editing the
+ <filename>layer.conf</filename> file.
+ The configuration changes identify the kernel you will be using.
+ Recipe changes include removing, modifying, or adding new recipe files that
+ instruct the build process on what features to include in the image.</para></listitem>
+ <listitem><para><emphasis>Prepare for the build:</emphasis>
+ Before you actually initiate the build, you need to set up the build environment
+ by sourcing the environment initialization script.
+ After setting up the environment, you need to make some build configuration
+ changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
+ files.</para></listitem>
+ <listitem><para><emphasis>Build the image:</emphasis>
+ The OpenEmbedded build system uses BitBake to create the image.
+ You need to decide on the type of image you are going to build (e.g. minimal, base,
+ core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
+ command.</para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='tip-dirty-string'>
+ <title>"-dirty" String</title>
+
+ <para>
+ If kernel images are being built with "-dirty" on the end of the version
+ string, this simply means that modifications in the source
+ directory have not been committed.
+ <literallayout class='monospaced'>
+ $ git status
+ </literallayout>
+ </para>
+
+ <para>
+ You can use the above Git command to report modified, removed, or added files.
+ You should commit those changes to the tree regardless of whether they will be saved,
+ exported, or used.
+ Once you commit the changes you need to rebuild the kernel.
+ </para>
+
+ <para>
+ To brute force pickup and commit all such pending changes, enter the following:
+ <literallayout class='monospaced'>
+ $ git add .
+ $ git commit -s -a -m "getting rid of -dirty"
+ </literallayout>
+ </para>
+
+ <para>
+ Next, rebuild the kernel.
+ </para>
+ </section>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml
new file mode 100644
index 0000000..2b99ad2
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-faq.xml
@@ -0,0 +1,140 @@
+<!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; ] >
+
+<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='generating-configuration-files'>Generating Configuration Files</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</ulink>"
+ section in the Yocto Project Development 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/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
new file mode 100644
index 0000000..263e500
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -0,0 +1,149 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-intro'>
+<title>Introduction</title>
+
+<!--
+<para>
+ <emphasis>AR - Darren Hart:</emphasis> See if the concepts in these
+ three bullets are adequately covered in somewhere in this manual:
+ <itemizedlist>
+ <listitem><para>Do we convey that our kernel Git repositories
+ have a clear and continuous history, similar to the way the
+ kernel Git repositories for <filename>kernel.org</filename>
+ do.
+ </para></listitem>
+ <listitem><para>Does the manual note that Yocto Project delivers
+ a key set of supported kernel types, where
+ each type is tailored to meet a specific use (e.g. networking,
+ consumer, devices, and so forth).</para></listitem>
+ <listitem><para>Do we convey that the Yocto Project uses a
+ Git branching strategy that, from a
+ developer's point of view, results in a linear path from the
+ baseline kernel.org, through a select group of features and
+ ends with their BSP-specific commits.</para></listitem>
+ </itemizedlist>
+</para>
+-->
+
+ <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 provides background information on the Yocto Linux kernel
+ <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
+ describes common tasks you can perform using the kernel tools,
+ and shows you how to use the kernel Metadata needed to work with
+ the kernel inside the Yocto Project.
+ </para>
+
+ <para>
+ Each Yocto Project release has a set of linux-yocto 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 upstream developments
+ and introduce newly-supported platforms.
+ Previous recipes in the release are refreshed and supported for at
+ least one additional release.
+ As they align, these previous releases are updated to include the
+ latest from the
+ <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink>
+ (LTSI) project.
+ Also included is a linux-yocto development recipe
+ (<filename>linux-yocto-dev.bb</filename>) should you want to work
+ with the very latest in upstream Linux kernel development and
+ kernel Metadata development.
+ </para>
+
+ <para>
+ The Yocto Project also provides a powerful set of kernel
+ tools for managing 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 Linux
+ kernel <filename>menuconfig</filename> system.
+ Contrast this against a complete Linux kernel
+ <filename>.config</filename>, 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 linux-yocto
+ recipes, an alternative exists by which you can use the Yocto
+ Project Linux kernel tools with your own kernel sources.
+ </para>
+ </section>
+
+ <section id='kernel-dev-other-resources'>
+ <title>Other Resources</title>
+
+ <para>
+ The sections that follow provide 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_QS_URL;'>Yocto Project Quick Start</ulink>
+ </para></listitem>
+ <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-modifying-source-code'>Modifying Source Code</ulink>"
+ section in the Yocto Project Development 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 Manual</para></listitem>
+ <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section
+ in the Yocto Project Development Manual.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Finally, while this document focuses on the manual creation of
+ recipes, patches, and configuration files, the Yocto Project
+ Board Support Package (BSP) tools are available to automate
+ this process with existing content and work well to create the
+ initial framework and boilerplate code.
+ For details on these tools, see the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
+ section in the Yocto Project Board Support Package (BSP) Developer's
+ Guide.
+ </para>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml
new file mode 100644
index 0000000..6bb0cf6
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml
@@ -0,0 +1,220 @@
+<!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; ] >
+
+<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 kernel repositories.
+ These kernel repositories are found under the heading "Yocto Linux Kernel" at
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
+ and can be 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,
+ configuration, branching, tagging and feature divisions found in a kernel.
+ Thus, the Yocto Project kernel repository (or tree) is built.
+ </para>
+ <para>
+ The existence of this tree allows you to access and clone a particular
+ Yocto Project 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 kernel in any clone of the Yocto Project kernel source repository
+ Git tree.
+ For example, the following command clones the Yocto Project baseline kernel that
+ branched off of <filename>linux.org</filename> version 3.19:
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/linux-yocto-3.19
+ </literallayout>
+ For another example of how to set up a local Git repository of the Yocto Project
+ kernel files, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
+ item in the Yocto Project Development Manual.
+ </para>
+ <para>
+ Once you have cloned the kernel Git repository on your local machine, you can
+ switch to the <filename>meta</filename> branch within the repository.
+ Here is an example that assumes the local Git repository for the kernel is in
+ a top-level directory named <filename>linux-yocto-3.19</filename>:
+ <literallayout class='monospaced'>
+ $ cd linux-yocto-3.19
+ $ git checkout -b meta origin/meta
+ </literallayout>
+ Once you have checked out and switched to the <filename>meta</filename> branch,
+ you can see a snapshot of all the kernel configuration and feature descriptions that are
+ used to build that particular kernel repository.
+ These descriptions are in the form of <filename>.scc</filename> files.
+ </para>
+ <para>
+ You should realize, however, that browsing your local kernel 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;/cgit.cgi'></ulink> given the
+ introduction of a new top-level kernel feature or BSP.
+ These are the actions that effectively create the tree
+ that includes the new feature, patch or BSP:
+ <orderedlist>
+ <listitem><para>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>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 <filename>meta/cfg/kernel-cache</filename></para></listitem>
+ <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
+ found in 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:
+ <literallayout class='monospaced'>
+ <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
+ </literallayout>
+ </para></listitem>
+ <listitem><para>Once located, the feature description is either compiled into a simple script
+ of actions, or into an existing equivalent script that is already part of the
+ shipped kernel.</para></listitem>
+ <listitem><para>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>Each extra feature is located, compiled and appended to the script
+ as described in step three.</para></listitem>
+ <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
+ directories.
+ These directories 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>The base repository is cloned, and the actions
+ listed in the <filename>meta-*</filename> directories are applied to the
+ tree.</para></listitem>
+ <listitem><para>The Git repository is left with the desired branch checked out and any
+ required branching, patching and tagging has been performed.</para></listitem>
+ </orderedlist>
+ </para>
+ <para>
+ The kernel tree is now ready for developer consumption to be locally cloned,
+ configured, and built into a Yocto Project kernel specific to some target hardware.
+ <note><para>The generated <filename>meta-*</filename> directories add 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;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
+ is the combination of all supported boards and configurations.</para>
+ <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>
+ </note>
+ </para>
+ </section>
+
+ <section id='build-strategy'>
+ <title>Build Strategy</title>
+
+<!--
+ <para>
+ <emphasis>AR - Darren Hart:</emphasis> Some parts of this section
+ need to be in the
+ "<link linkend='using-an-iterative-development-process'>Using an Iterative Development Process</link>"
+ section.
+ Darren needs to figure out which parts and identify them.
+ </para>
+-->
+
+ <para>
+ Once a local Git repository of the Yocto Project kernel exists on a development system,
+ you can consider the compilation phase of kernel development - 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 exists.
+ This branch has the following form:
+ <literallayout class='monospaced'>
+ <replaceable>kernel_type</replaceable>/<replaceable>bsp_name</replaceable>
+ </literallayout></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 <filename>meta-*</filename> 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_DEV_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/documentation/kernel-dev/kernel-dev-style.css b/documentation/kernel-dev/kernel-dev-style.css
new file mode 100644
index 0000000..6e0c1c7
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-style.css
@@ -0,0 +1,984 @@
+/*
+ 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;
+}
+
+
+ /*********** /
+ / 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/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml
new file mode 100644
index 0000000..e3df2cc
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev.xml
@@ -0,0 +1,115 @@
+<!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; ] >
+
+<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>
+ <firstname>Darren</firstname> <surname>Hart</surname>
+ <affiliation>
+ <orgname>Intel Corporation</orgname>
+ </affiliation>
+ <email>darren.hart@intel.com</email>
+ </author>
+ </authorgroup>
+
+ <revhistory>
+ <revision>
+ <revnumber>1.4</revnumber>
+ <date>April 2013</date>
+ <revremark>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.5.1</revnumber>
+ <date>January 2014</date>
+ <revremark>Released with the Yocto Project 1.5.1 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>1.9</revnumber>
+ <date>October 2015</date>
+ <revremark>Released with the Yocto Project 1.9 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>
+ For the latest version of this manual associated with this
+ Yocto Project release, see the
+ <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>
+ from the Yocto Project website.
+ </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-examples.xml"/>
+-->
+
+ <xi:include href="kernel-dev-faq.xml"/>
+
+<!-- <index id='index'>
+ <title>Index</title>
+ </index>
+-->
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
