aboutsummaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-03-31 14:42:10 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-04-06 23:11:57 +0100
commit23dbf81eddb3c539875b29885ff52e2f116887ef (patch)
tree4427ca666526f9f2be38dfe1009daa6403543f1b /documentation/kernel-dev
parentf30bfe990a95479ca3f31c44838e9a1cc98ddd1d (diff)
downloadopenembedded-core-contrib-23dbf81eddb3c539875b29885ff52e2f116887ef.tar.gz
kernel-dev: Added new "Adding Recipe-Space Kernel Features" section.
Fixes [YOCTO #4047] I added a new section describing how to add kernel features from within a kernel recipe through the KERNEL_FEATURES variable and the SRC_URI statement. (From yocto-docs rev: d30925c65e3f49b2ba481f1e7f9cac98fe86f6af) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml122
1 files changed, 122 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index d3119a88b2..89c2a6840b 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -1032,6 +1032,128 @@
</para>
</section>
</section>
+
+ <section id='adding-recipe-space-kernel-features'>
+ <title>Adding Recipe-Space Kernel Features</title>
+
+ <para>
+ You can add kernel features in the
+ <link linkend='recipe-space-metadata'>recipe-space</link> by
+ using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
+ variable along with specifying the <filename>.scc</filename> file
+ path on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statement.
+ When you add features using this method, the OpenEmbedded build
+ system checks to be sure the features are present.
+ If the features are not present, the build stops.
+ Kernel features are the last elements processed for configuring
+ and patching the kernel.
+ Therefore, adding features in this manner is a way
+ to enforce that specific features are present, and enabled,
+ without needing to do a full audit of any other layer's additions
+ to the <filename>SRC_URI</filename> statement.
+ </para>
+
+ <para>
+ You add a kernel feature by providing the feature as part of the
+ <filename>KERNEL_FEATURES</filename> variable and by providing the
+ path to the feature's <filename>.scc</filename> file, which is
+ relative to the root of the kernel Metadata.
+ The OpenEmbedded build system searches all forms of kernel
+ Metadata on the <filename>SRC_URI</filename> statement regardless
+ of whether the Metadata is in the "kernel-cache", system kernel
+ Metadata, or a recipe-space Metadata.
+ See the
+ "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>"
+ section for additional information.
+ </para>
+
+ <para>
+ When you specify the feature's <filename>.scc</filename> file
+ on the <filename>SRC_URI</filename> statement, the OpenEmbedded
+ build system adds the directory of that
+ <filename>.scc</filename> file, and all its subdirectories,
+ to the kernel feature search path.
+ Because subdirectories are searched, you can reference a single
+ <filename>.scc</filename> file in the
+ <filename>SRC_URI</filename> statement to reference multiple kernel
+ features.
+ </para>
+
+ <para>
+ Consider the following example that adds the "test.scc" feature
+ to the build.
+ <orderedlist>
+ <listitem><para>
+ Create a <filename>.scc</filename> file and locate it
+ just as you would any other patch file,
+ <filename>.cfg</filename> file, or fetcher item
+ you specify in the <filename>SRC_URI</filename>
+ statement.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ The directory you use for the
+ <filename>.scc</filename> must be added to the
+ fetcher search directory just as you would,
+ for example, if you were adding a
+ <filename>.patch</filename> file.
+ </para></listitem>
+ <listitem><para>
+ You can create additional
+ <filename>.scc</filename> files beneath the
+ directory that contains the file you are
+ adding.
+ All subdirectories are searched during the
+ build as potential feature directories.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ Continuing with the example, suppose the "test.scc"
+ feature you are adding has a
+ <filename>test.scc</filename> file in the following
+ directory:
+ <literallayout class='monospaced'>
+ <replaceable>my_recipe</replaceable>
+ |
+ +-linux-yocto
+ |
+ +-test.cfg
+ +-test.scc
+ </literallayout>
+ In this example, the <filename>linux-yocto</filename>
+ directory has both the feature
+ <filename>test.scc</filename> file and a similarly
+ named configuration fragment file
+ <filename>test.cfg</filename>.
+ </para></listitem>
+ <listitem><para>
+ Add the <filename>.scc</filename> file to the
+ recipe's <filename>SRC_URI</filename> statement:
+ <literallayout class='monospaced'>
+ SRC_URI_append = " file://test.scc"
+ </literallayout>
+ The leading space before the path is important as the
+ path is appended to the existing path.
+ </para></listitem>
+ <listitem><para>
+ Specify the feature as a kernel feature:
+ <literallayout class='monospaced'>
+ KERNEL_FEATURES_append = " test.scc"
+ </literallayout>
+ The OpenEmbedded build system processes the kernel feature
+ when it builds the kernel.
+ <note>
+ If other features are contained below "test.scc",
+ then their directories are relative to the directory
+ containing the <filename>test.scc</filename> file.
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
</chapter>
<!--
vim: expandtab tw=80 ts=4