diff options
Diffstat (limited to 'yocto-poky/documentation/kernel-dev')
3 files changed, 180 insertions, 40 deletions
diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml index 4fdb853f9..9e15f178a 100644 --- a/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml @@ -29,8 +29,8 @@ 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. + A BSP consists of an aggregation of kernel policy and enabled + hardware-specific features. The BSP can be influenced from within the linux-yocto recipe. <note> Linux kernel source that contains kernel Metadata is said to be @@ -171,8 +171,8 @@ <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). + Kernel Metadata always exists outside of the kernel tree either + defined in a kernel recipe (recipe-space) or outside of the recipe. Where you choose to define the Metadata depends on what you want to do and how you intend to work. Regardless of where you define the kernel Metadata, the syntax used @@ -195,10 +195,10 @@ <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. + it more convenient to work with kernel Metadata kept outside the + recipe-space. + Working with Metadata in this area can make iterative development of + the Linux kernel more efficient outside of the BitBake environment. </para> <section id='recipe-space-metadata'> @@ -249,38 +249,52 @@ </para> </section> - <section id='in-tree-metadata'> - <title>In-Tree Metadata</title> + <section id='metadata-outside-the-recipe-space'> + <title>Metadata Outside the Recipe-Space</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. + When stored outside of the recipe-space, the kernel Metadata + files reside in a separate repository. + The OpenEmbedded build system adds the Metadata to the build as + a "ktype=meta" repository through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable. + As an example, consider the following <filename>SRC_URI</filename> + statement from the <filename>linux-yocto_4.4.bb</filename> + kernel recipe: + <literallayout class='monospaced'> + SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \ + git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}" + </literallayout> + <filename>${KMETA}</filename>, in this context, is simply used to + name the directory into which the Git fetcher places the Metadata. + This behavior is no different than any multi-repository + <filename>SRC_URI</filename> statement used in a recipe. </para> <para> + You can keep kernel Metadata in a "kernel-cache", which is a + directory containing configuration fragments. + As with any Metadata kept outside the recipe-space, you simply + need to use the <filename>SRC_URI</filename> statement with the + "type=kmeta" attribute. + Doing so makes the kernel Metadata available during the + configuration phase. + </para> + +<!-- + + + <para> 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 + `‐‐ cfg + `‐‐ kernel-cache + |‐‐ bsp-standard.scc + |‐‐ bsp.cfg + `‐‐ standard.cfg </literallayout> </para> @@ -301,16 +315,15 @@ orphan <filename>meta</filename> branch, use these commands from within your Linux kernel Git repository: <literallayout class='monospaced'> - $ git checkout --orphan meta + $ git checkout ‐‐orphan meta $ git rm -rf . - $ git commit --allow-empty -m "Create orphan meta branch" + $ 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 + If you modify the Metadata, 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 @@ -437,7 +450,7 @@ 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>. + <link linkend='metadata-outside-the-recipe-space'>Metadata outside of the recipe-space</link>. </para> <section id='configuration'> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml index ab7f80fbe..261471c46 100644 --- a/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml @@ -270,11 +270,12 @@ 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> + KBUILD_DEFCONFIG_KMACHINE ?= <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. + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> + and then supply the path to your "in-tree" + <filename>defconfig</filename> file. </para> <para> @@ -1031,6 +1032,127 @@ </para> </section> </section> + + <section id='adding-recipe-space-kernel-features'> + <title>Adding Recipe-Space Kernel Features</title> + + <para> + You can add kernel features in the + <link linkend='recipe-space-metadata'>recipe-space</link> by + using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable and by specifying the feature's <filename>.scc</filename> + file path in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement. + When you add features using this method, the OpenEmbedded build + system checks to be sure the features are present. + If the features are not present, the build stops. + Kernel features are the last elements processed for configuring + and patching the kernel. + Therefore, adding features in this manner is a way + to enforce specific features are present and enabled + without needing to do a full audit of any other layer's additions + to the <filename>SRC_URI</filename> statement. + </para> + + <para> + You add a kernel feature by providing the feature as part of the + <filename>KERNEL_FEATURES</filename> variable and by providing the + path to the feature's <filename>.scc</filename> file, which is + relative to the root of the kernel Metadata. + The OpenEmbedded build system searches all forms of kernel + Metadata on the <filename>SRC_URI</filename> statement regardless + of whether the Metadata is in the "kernel-cache", system kernel + Metadata, or a recipe-space Metadata. + See the + "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>" + section for additional information. + </para> + + <para> + When you specify the feature's <filename>.scc</filename> file + on the <filename>SRC_URI</filename> statement, the OpenEmbedded + build system adds the directory of that + <filename>.scc</filename> file along with all its subdirectories + to the kernel feature search path. + Because subdirectories are searched, you can reference a single + <filename>.scc</filename> file in the + <filename>SRC_URI</filename> statement to reference multiple kernel + features. + </para> + + <para> + Consider the following example that adds the "test.scc" feature + to the build. + <orderedlist> + <listitem><para> + Create a <filename>.scc</filename> file and locate it + just as you would any other patch file, + <filename>.cfg</filename> file, or fetcher item + you specify in the <filename>SRC_URI</filename> + statement. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + You must add the directory of the + <filename>.scc</filename> file to the fetcher's + search path in the same manner as you would + add a <filename>.patch</filename> file. + </para></listitem> + <listitem><para> + You can create additional + <filename>.scc</filename> files beneath the + directory that contains the file you are + adding. + All subdirectories are searched during the + build as potential feature directories. + </para></listitem> + </itemizedlist> + </note> + Continuing with the example, suppose the "test.scc" + feature you are adding has a + <filename>test.scc</filename> file in the following + directory: + <literallayout class='monospaced'> + <replaceable>my_recipe</replaceable> + | + +-linux-yocto + | + +-test.cfg + +-test.scc + </literallayout> + In this example, the <filename>linux-yocto</filename> + directory has both the feature + <filename>test.scc</filename> file and a similarly + named configuration fragment file + <filename>test.cfg</filename>. + </para></listitem> + <listitem><para> + 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 diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev.xml b/yocto-poky/documentation/kernel-dev/kernel-dev.xml index 38850fa3c..fb11dd15c 100644 --- a/yocto-poky/documentation/kernel-dev/kernel-dev.xml +++ b/yocto-poky/documentation/kernel-dev/kernel-dev.xml @@ -66,6 +66,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> |