1 files changed, 1071 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
new file mode 100644
index 0000000000..4589e4b9fc
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -0,0 +1,1071 @@
+<!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 BitBake (e.g. "routerstationpro" or "fri2").
+        Multiple BSPs can reuse the same <filename>KMACHINE</filename>
+        name if they are built using the same BSP description.
+        The "fri2" and "fri2-noemgd" BSP combination
+        in the <filename>meta-intel</filename>
+        layer is a good example of two BSPs using the same
+        <filename>KMACHINE</filename> value (i.e. "fri2").
+        See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section
+        for more information.
+    </para>
+    <para>
+        The linux-yocto style recipes can optionally define the following
+        variables:
+        <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'>KBRANCH</ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH_DEFAULT'>KBRANCH_DEFAULT</ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink>
+        </literallayout>
+        <filename>KBRANCH_DEFAULT</filename> defines the Linux kernel source
+        repository's default branch to use to build the Linux kernel.
+        The value is used as the default for <filename>KBRANCH</filename>, which
+        can define an alternate branch typically with a machine override as
+        follows:
+        <literallayout class='monospaced'>
+     KBRANCH_fri2 = "standard/fri2"
+        </literallayout>
+        Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename>
+        initializes to "master".
+    </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/fri2-broken/hdw_frags.txt and
+              meta/cfg/broken/fri2-broken/required_frags.txt in directory:
+              meta/cfg/broken/fri2-broken
+        </literallayout>
+        In this example, <filename>KMACHINE</filename> was set to "fri2-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.scc",
+        specify:
+        <literallayout class='monospaced'>
+     KERNEL_FEATURES += "features/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>linux-yocto-3.4</filename> repository where "features"
+        and "cfg" are subdirectories within 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-my_bsp_layer/
+     `-- 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'>
+     &lt;base&gt;/
+        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>&lt;base&gt;</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 an <filename>.scc</filename> file
+            that describes the fragment.
+        </para>
+        <para>
+            The Symmetric Multi-Processing (SMP) fragment included in the
+            <filename>linux-yocto-3.4</filename> Git repository
+            consists of the following two files:
+            <literallayout class='monospaced'>
+     cfg/smp.scc:
+        define KFEATURE_DESCRIPTION "Enable SMP"
+        kconf hardware smp.cfg
+     cfg/smp.cfg:
+        CONFIG_SMP=y
+        CONFIG_SCHED_SMT=y
+            </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:
+        &lt;typical-patch&gt;
+            </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.4</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 "mybsp"
+            machine:
+            <literallayout class='monospaced'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
+        kconf mybsp.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'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
+        include standard.scc
+        include mybsp-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
+            <filename>mybsp-hw.scc</filename> aggregates all those necessary
+            to support the hardware available on the "mybsp" 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 Fish River Island 2 (fri2)
+            BSP definition from the <filename>linux-yocto-3.4</filename>
+            Git repository:
+            <literallayout class='monospaced'>
+     fri2.scc:
+        kconf hardware fri2.cfg
+        include cfg/x86.scc
+        include features/eg20t/eg20t.scc
+        include cfg/dmaengine.scc
+        include features/ericsson-3g/f5521gw.scc
+        include features/power/intel.scc
+        include cfg/efi.scc
+        include features/usb/ehci-hcd.scc
+        include features/usb/ohci-hcd.scc
+        include features/iwlwifi/iwlwifi.scc
+            </literallayout>
+        </para>
+        <para>
+            The <filename>fri2.scc</filename> description file includes
+            a hardware configuration fragment
+            (<filename>fri2.cfg</filename>) specific to the Fish River
+            Island 2 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
+            "fri2" description files for the supported kernel types
+            (i.e. "standard", "preempt-rt", and "tiny").
+            Consider the "fri2" description for the "standard" kernel
+            type:
+            <literallayout class='monospaced'>
+     fri2-standard.scc:
+        define KMACHINE fri2
+        define KTYPE standard
+        define KARCH i386
+        include ktypes/standard/standard.scc
+        branch fri2
+        git merge emgd-1.14
+        include fri2.scc
+        # Extra fri2 configs above the minimal defined in fri2.scc
+        include cfg/efi-ext.scc
+        include features/drm-emgd/drm-emgd.scc
+        include cfg/vesafb.scc
+        # default policy for standard kernels
+        include cfg/usb-mass-storage.scc
+            </literallayout>
+            The <filename>include</filename> command midway through the file
+            includes the <filename>fri2.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>
+            This "fri2" standard description introduces a few more variables
+            and commands that are worth further discussion.
+            Notice the <filename>branch fri2</filename> command, which creates
+            a machine-specific branch into which source changes are applied.
+            With this branch set up, the <filename>git merge</filename> command
+            uses Git to merge in a feature branch named "emgd-1.14".
+            You could also handle this with the <filename>patch</filename>
+            command.
+            However, for commonly used features such as this, feature branches
+            are a convenient mechanism.
+            See the "<link linkend='feature-branches'>Feature Branches</link>"
+            section for more information.
+        </para>
+        <para>
+            Now consider the "fri2" description for the "tiny" kernel type:
+            <literallayout class='monospaced'>
+     fri2-tiny.scc:
+        define KMACHINE fri2
+        define KTYPE tiny
+        define KARCH i386
+        include ktypes/tiny/tiny.scc
+        branch fri2
+        include fri2.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 "fri2" 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'>
+     &lt;common&gt;/&lt;kernel_type&gt;/&lt;machine&gt;
+            </literallayout>
+        </para>
+        <para>
+            If you had two kernel types, "standard" and "small" for
+            instance, and three machines, the branches in your
+            Git repository might look like this:
+            <literallayout class='monospaced'>
+     common/base
+     common/standard/base
+     common/standard/machine_a
+     common/standard/machine_b
+     common/standard/machine_c
+     common/small/base
+     common/small/machine_a
+            </literallayout>
+        </para>
+        <para>
+            This organization can help clarify the branch relationships.
+            In this case, <filename>common/standard/machine_a</filename>
+            includes everything in <filename>common/base</filename> and
+            <filename>common/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>common/standard</filename> and
+                <filename>common/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
+-->