diff options
Diffstat (limited to 'poky/documentation/kernel-dev/kernel-dev-common.xml')
| -rw-r--r-- | poky/documentation/kernel-dev/kernel-dev-common.xml | 2730 |
1 files changed, 2730 insertions, 0 deletions
diff --git a/poky/documentation/kernel-dev/kernel-dev-common.xml b/poky/documentation/kernel-dev/kernel-dev-common.xml new file mode 100644 index 000000000..8e8a6dbed --- /dev/null +++ b/poky/documentation/kernel-dev/kernel-dev-common.xml @@ -0,0 +1,2730 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> + +<chapter id='kernel-dev-common'> +<title>Common Tasks</title> + + <para> + This chapter presents several common tasks you perform when you + work with the Yocto Project Linux kernel. + These tasks include preparing your host development system for + kernel development, preparing a layer, modifying an existing recipe, + patching the kernel, configuring the kernel, iterative development, + working with your own sources, and incorporating out-of-tree modules. + <note> + The examples presented in this chapter work with the Yocto Project + 2.4 Release and forward. + </note> + </para> + + <section id='preparing-the-build-host-to-work-on-the-kernel'> + <title>Preparing the Build Host to Work on the Kernel</title> + + <para> + Before you can do any kernel development, you need to be + sure your build host is set up to use the Yocto Project. + For information on how to get set up, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" + section in the Yocto Project Development Tasks Manual. + Part of preparing the system is creating a local Git + repository of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (<filename>poky</filename>) on your system. + Follow the steps in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" + section in the Yocto Project Development Tasks Manual to set up your + Source Directory. + <note> + Be sure you check out the appropriate development branch or + you create your local branch by checking out a specific tag + to get the desired version of Yocto Project. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>" + and + "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>" + sections in the Yocto Project Development Tasks Manual for more + information. + </note> + </para> + + <para> + Kernel development is best accomplished using + <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink> + and not through traditional kernel workflow methods. + The remainder of this section provides information for both + scenarios. + </para> + + <section id='getting-ready-to-develop-using-devtool'> + <title>Getting Ready to Develop Using <filename>devtool</filename></title> + + <para> + Follow these steps to prepare to update the kernel image using + <filename>devtool</filename>. + Completing this procedure leaves you with a clean kernel image + and ready to make modifications as described in the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section: + <orderedlist> + <listitem><para> + <emphasis>Initialize the BitBake Environment:</emphasis> + Before building an extensible SDK, you need to + initialize the BitBake build environment by sourcing the + build environment script + (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>): + <literallayout class='monospaced'> + $ cd ~/poky + $ source oe-init-build-env + </literallayout> + <note> + The previous commands assume the + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> + (i.e. <filename>poky</filename>) have been cloned + using Git and the local repository is named + "poky". + </note> + </para></listitem> + <listitem><para> + <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis> + By default, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable is set to "qemux86-64", which is fine if you are + building for the QEMU emulator in 64-bit mode. + However, if you are not, you need to set the + <filename>MACHINE</filename> variable appropriately in + your <filename>conf/local.conf</filename> file found in + the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + (i.e. <filename>~/poky/build</filename> in this + example).</para> + + <para>Also, since you are preparing to work on the + kernel image, you need to set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> + variable to include kernel modules.</para> + + <para>In this example we wish to build for qemux86 so + we must set the <filename>MACHINE</filename> variable + to "qemux86" and also add the "kernel-modules". As described + we do this by appending to <filename>conf/local.conf</filename>: + <literallayout class='monospaced'> + MACHINE = "qemux86" + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create a Layer for Patches:</emphasis> + You need to create a layer to hold patches created + for the kernel image. + You can use the + <filename>bitbake-layers create-layer</filename> + command as follows: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake-layers create-layer ../../meta-mylayer + NOTE: Starting bitbake server... + Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' + $ + </literallayout> + <note> + For background information on working with + common and BSP layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks + Manual and the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support (BSP) + Developer's Guide, respectively. + For information on how to use the + <filename>bitbake-layers create-layer</filename> + command to quickly set up a layer, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" + section in the Yocto Project Development Tasks + Manual. + </note> + </para></listitem> + <listitem><para> + <emphasis>Inform the BitBake Build Environment About + Your Layer:</emphasis> + As directed when you created your layer, you need to + add the layer to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> + variable in the <filename>bblayers.conf</filename> file + as follows: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake-layers add-layer ../../meta-mylayer + NOTE: Starting bitbake server... + $ + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Build the Extensible SDK:</emphasis> + Use BitBake to build the extensible SDK specifically + for use with images to be run using QEMU: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake core-image-minimal -c populate_sdk_ext + </literallayout> + Once the build finishes, you can find the SDK installer + file (i.e. <filename>*.sh</filename> file) in the + following directory: + <literallayout class='monospaced'> + ~/poky/build/tmp/deploy/sdk + </literallayout> + For this example, the installer file is named + <filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename> + </para></listitem> + <listitem><para> + <emphasis>Install the Extensible SDK:</emphasis> + Use the following command to install the SDK. + For this example, install the SDK in the default + <filename>~/poky_sdk</filename> directory: + <literallayout class='monospaced'> + $ cd ~/poky/build/tmp/deploy/sdk + $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh + Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; + ============================================================================ + Enter target directory for SDK (default: ~/poky_sdk): + You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y + Extracting SDK......................................done + Setting it up... + Extracting buildtools... + Preparing build system... + Parsing recipes: 100% |#################################################################| Time: 0:00:52 + Initializing tasks: 100% |############## ###############################################| Time: 0:00:04 + Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00 + Parsing recipes: 100% |#################################################################| Time: 0:00:33 + Initializing tasks: 100% |##############################################################| Time: 0:00:00 + done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux + </literallayout> + </para></listitem> + <listitem><para id='setting-up-the-esdk-terminal'> + <emphasis>Set Up a New Terminal to Work With the + Extensible SDK:</emphasis> + You must set up a new terminal to work with the SDK. + You cannot use the same BitBake shell used to build the + installer.</para> + + <para>After opening a new shell, run the SDK environment + setup script as directed by the output from installing + the SDK: + <literallayout class='monospaced'> + $ source ~/poky_sdk/environment-setup-i586-poky-linux + "SDK environment now set up; additionally you may now run devtool to perform development tasks. + Run devtool --help for further details. + </literallayout> + <note> + If you get a warning about attempting to use the + extensible SDK in an environment set up to run + BitBake, you did not use a new shell. + </note> + </para></listitem> + <listitem><para> + <emphasis>Build the Clean Image:</emphasis> + The final step in preparing to work on the kernel is to + build an initial image using + <filename>devtool</filename> in the new terminal you + just set up and initialized for SDK work: + <literallayout class='monospaced'> + $ devtool build-image + Parsing recipes: 100% |##########################################| Time: 0:00:05 + Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors. + WARNING: No packages to add, building image core-image-minimal unmodified + Loading cache: 100% |############################################| Time: 0:00:00 + Loaded 1299 entries from dependency cache. + NOTE: Resolving any missing task queue dependencies + Initializing tasks: 100% |#######################################| Time: 0:00:07 + Checking sstate mirror object availability: 100% |###############| Time: 0:00:00 + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. + NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86 + </literallayout> + If you were building for actual hardware and not for + emulation, you could flash the image to a USB stick + on <filename>/dev/sdd</filename> and boot your device. + For an example that uses a Minnowboard, see the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink> + Wiki page. + </para></listitem> + </orderedlist> + </para> + + <para> + At this point you have set up to start making modifications to + the kernel by using the extensible SDK. + For a continued example, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section. + </para> + </section> + + <section id='getting-ready-for-traditional-kernel-development'> + <title>Getting Ready for Traditional Kernel Development</title> + + <para> + Getting ready for traditional kernel development using the Yocto + Project involves many of the same steps as described in the + previous section. + However, you need to establish a local copy of the kernel source + since you will be editing these files. + </para> + + <para> + Follow these steps to prepare to update the kernel image using + traditional kernel development flow with the Yocto Project. + Completing this procedure leaves you ready to make modifications + to the kernel source as described in the + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + section: + <orderedlist> + <listitem><para> + <emphasis>Initialize the BitBake Environment:</emphasis> + Before you can do anything using BitBake, you need to + initialize the BitBake build environment by sourcing the + build environment script + (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>). + Also, for this example, be sure that the local branch + you have checked out for <filename>poky</filename> is + the Yocto Project &DISTRO_NAME; branch. + If you need to checkout out the &DISTRO_NAME; branch, + see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking out by Branch in Poky</ulink>" + section in the Yocto Project Development Tasks Manual. + <literallayout class='monospaced'> + $ cd ~/poky + $ git branch + master + * &DISTRO_NAME; + $ source oe-init-build-env + </literallayout> + <note> + The previous commands assume the + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> + (i.e. <filename>poky</filename>) have been cloned + using Git and the local repository is named + "poky". + </note> + </para></listitem> + <listitem><para> + <emphasis>Prepare Your <filename>local.conf</filename> + File:</emphasis> + By default, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable is set to "qemux86-64", which is fine if you are + building for the QEMU emulator in 64-bit mode. + However, if you are not, you need to set the + <filename>MACHINE</filename> variable appropriately in + your <filename>conf/local.conf</filename> file found + in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + (i.e. <filename>~/poky/build</filename> in this + example).</para> + + <para>Also, since you are preparing to work on the + kernel image, you need to set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> + variable to include kernel modules.</para> + + <para>In this example we wish to build for qemux86 so + we must set the <filename>MACHINE</filename> variable + to "qemux86" and also add the "kernel-modules". As described + we do this by appending to <filename>conf/local.conf</filename>: + <literallayout class='monospaced'> + MACHINE = "qemux86" + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create a Layer for Patches:</emphasis> + You need to create a layer to hold patches created + for the kernel image. + You can use the + <filename>bitbake-layers create-layer</filename> + command as follows: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake-layers create-layer ../../meta-mylayer + NOTE: Starting bitbake server... + Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' + </literallayout> + <note> + For background information on working with + common and BSP layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks + Manual and the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support (BSP) + Developer's Guide, respectively. + For information on how to use the + <filename>bitbake-layers create-layer</filename> + command to quickly set up a layer, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" + section in the Yocto Project Development Tasks + Manual. + </note> + </para></listitem> + <listitem><para> + <emphasis>Inform the BitBake Build Environment About + Your Layer:</emphasis> + As directed when you created your layer, you need to add + the layer to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> + variable in the <filename>bblayers.conf</filename> file + as follows: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake-layers add-layer ../../meta-mylayer + NOTE: Starting bitbake server ... + $ + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create a Local Copy of the Kernel Git + Repository:</emphasis> + You can find Git repositories of supported Yocto Project + kernels organized under "Yocto Linux Kernel" in the + Yocto Project Source Repositories at + <ulink url='&YOCTO_GIT_URL;'></ulink>. + </para> + + <para> + For simplicity, it is recommended that you create your + copy of the kernel Git repository outside of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, + which is usually named <filename>poky</filename>. + Also, be sure you are in the + <filename>standard/base</filename> branch. + </para> + + <para> + The following commands show how to create a local copy + of the <filename>linux-yocto-4.12</filename> kernel and + be in the <filename>standard/base</filename> branch. + <note> + The <filename>linux-yocto-4.12</filename> kernel + can be used with the Yocto Project 2.4 release + and forward. + You cannot use the + <filename>linux-yocto-4.12</filename> kernel with + releases prior to Yocto Project 2.4: + </note> + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base + Cloning into 'linux-yocto-4.12'... + remote: Counting objects: 6097195, done. + remote: Compressing objects: 100% (901026/901026), done. + remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256) + Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done. + Resolving deltas: 100% (5152604/5152604), done. + Checking connectivity... done. + Checking out files: 100% (59846/59846), done. + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create a Local Copy of the Kernel Cache Git + Repository:</emphasis> + For simplicity, it is recommended that you create your + copy of the kernel cache Git repository outside of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, + which is usually named <filename>poky</filename>. + Also, for this example, be sure you are in the + <filename>yocto-4.12</filename> branch. + </para> + + <para> + The following commands show how to create a local copy + of the <filename>yocto-kernel-cache</filename> and + be in the <filename>yocto-4.12</filename> branch: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 + Cloning into 'yocto-kernel-cache'... + remote: Counting objects: 22639, done. + remote: Compressing objects: 100% (9761/9761), done. + remote: Total 22639 (delta 12400), reused 22586 (delta 12347) + Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done. + Resolving deltas: 100% (12400/12400), done. + Checking connectivity... done. + </literallayout> + </para></listitem> + </orderedlist> + </para> + + <para> + At this point, you are ready to start making modifications to + the kernel using traditional kernel development steps. + For a continued example, see the + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + section. + </para> + </section> + </section> + + <section id='creating-and-preparing-a-layer'> + <title>Creating and Preparing a Layer</title> + + <para> + If you are going to be modifying kernel recipes, it is recommended + that you create and prepare your own layer in which to do your + work. + Your layer contains its own + <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> + append files (<filename>.bbappend</filename>) and provides a + convenient mechanism to create your own recipe files + (<filename>.bb</filename>) as well as store and use kernel + patch files. + For background information on working with layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks Manual. + <note><title>Tip</title> + The Yocto Project comes with many tools that simplify + tasks you need to perform. + One such tool is the + <filename>bitbake-layers create-layer</filename> + command, which simplifies creating a new layer. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" + section in the Yocto Project Development Tasks Manual for + information on how to use this script to quick set up a + new layer. + </note> + </para> + + <para> + To better understand the layer you create for kernel development, + the following section describes how to create a layer + without the aid of tools. + These steps assume creation of a layer named + <filename>mylayer</filename> in your home directory: + <orderedlist> + <listitem><para> + <emphasis>Create Structure</emphasis>: + Create the layer's structure: + <literallayout class='monospaced'> + $ cd $HOME + $ mkdir meta-mylayer + $ mkdir meta-mylayer/conf + $ mkdir meta-mylayer/recipes-kernel + $ mkdir meta-mylayer/recipes-kernel/linux + $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto + </literallayout> + The <filename>conf</filename> directory holds your + configuration files, while the + <filename>recipes-kernel</filename> directory holds your + append file and eventual patch files. + </para></listitem> + <listitem><para> + <emphasis>Create the Layer Configuration File</emphasis>: + Move to the <filename>meta-mylayer/conf</filename> + directory and create the <filename>layer.conf</filename> + file as follows: + <literallayout class='monospaced'> + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "mylayer" + BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" + BBFILE_PRIORITY_mylayer = "5" + </literallayout> + Notice <filename>mylayer</filename> as part of the last + three statements. + </para></listitem> + <listitem><para> + <emphasis>Create the Kernel Recipe Append File</emphasis>: + Move to the + <filename>meta-mylayer/recipes-kernel/linux</filename> + directory and create the kernel's append file. + This example uses the + <filename>linux-yocto-4.12</filename> kernel. + Thus, the name of the append file is + <filename>linux-yocto_4.12.bbappend</filename>: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + SRC_URI_append = " file://<replaceable>patch-file-one</replaceable>" + SRC_URI_append = " file://<replaceable>patch-file-two</replaceable>" + SRC_URI_append = " file://<replaceable>patch-file-three</replaceable>" + </literallayout> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statements enable the OpenEmbedded build system to find + patch files. + For more information on using append files, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" + section in the Yocto Project Development Tasks Manual. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='modifying-an-existing-recipe'> + <title>Modifying an Existing Recipe</title> + + <para> + In many cases, you can customize an existing linux-yocto recipe to + meet the needs of your project. + Each release of the Yocto Project provides a few Linux + kernel recipes from which you can choose. + These are located in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + in <filename>meta/recipes-kernel/linux</filename>. + </para> + + <para> + Modifying an existing recipe can consist of the following: + <itemizedlist> + <listitem><para>Creating the append file</para></listitem> + <listitem><para>Applying patches</para></listitem> + <listitem><para>Changing the configuration</para></listitem> + </itemizedlist> + </para> + + <para> + Before modifying an existing recipe, be sure that you have created + a minimal, custom layer from which you can work. + See the + "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>" + section for information. + </para> + + <section id='creating-the-append-file'> + <title>Creating the Append File</title> + + <para> + You create this file in your custom layer. + You also name it accordingly based on the linux-yocto recipe + you are using. + For example, if you are modifying the + <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename> + recipe, the append file will typically be located as follows + within your custom layer: + <literallayout class='monospaced'> + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.12.bbappend + </literallayout> + The append file should initially extend the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> + search path by prepending the directory that contains your + files to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + variable as follows: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + </literallayout> + The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> + expands to "linux-yocto" in the current directory for this + example. + If you add any new files that modify the kernel recipe and you + have extended <filename>FILESPATH</filename> as + described above, you must place the files in your layer in the + following area: + <literallayout class='monospaced'> + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/ + </literallayout> + <note>If you are working on a new machine Board Support Package + (BSP), be sure to refer to the + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + </note> + </para> + + <para> + As an example, consider the following append file + used by the BSPs in <filename>meta-yocto-bsp</filename>: + <literallayout class='monospaced'> + meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend + </literallayout> + The following listing shows the file. + Be aware that the actual commit ID strings in this + example listing might be different than the actual strings + in the file from the <filename>meta-yocto-bsp</filename> + layer upstream. + <literallayout class='monospaced'> + KBRANCH_genericx86 = "standard/base" + KBRANCH_genericx86-64 = "standard/base" + + KMACHINE_genericx86 ?= "common-pc" + KMACHINE_genericx86-64 ?= "common-pc-64" + KBRANCH_edgerouter = "standard/edgerouter" + KBRANCH_beaglebone = "standard/beaglebone" + + SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" + SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" + SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" + SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" + + + COMPATIBLE_MACHINE_genericx86 = "genericx86" + COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE_edgerouter = "edgerouter" + COMPATIBLE_MACHINE_beaglebone = "beaglebone" + + LINUX_VERSION_genericx86 = "4.12.7" + LINUX_VERSION_genericx86-64 = "4.12.7" + LINUX_VERSION_edgerouter = "4.12.10" + LINUX_VERSION_beaglebone = "4.12.10" + </literallayout> + This append file contains statements used to support + several BSPs that ship with the Yocto Project. + The file defines machines using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> + variable and uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> + variable to ensure the machine name used by the OpenEmbedded + build system maps to the machine name used by the Linux Yocto + kernel. + The file also uses the optional + <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> + variable to ensure the build process uses the + appropriate kernel branch. + </para> + + <para> + Although this particular example does not use it, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable could be used to enable features specific to + the kernel. + The append file points to specific commits in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + Git repository and the <filename>meta</filename> Git repository + branches to identify the exact kernel needed to build the + BSP. + </para> + + <para> + One thing missing in this particular BSP, which you will + typically need when developing a BSP, is the kernel + configuration file (<filename>.config</filename>) for your BSP. + When developing a BSP, you probably have a kernel configuration + file or a set of kernel configuration files that, when taken + together, define the kernel configuration for your BSP. + You can accomplish this definition by putting the configurations + in a file or a set of files inside a directory located at the + same level as your kernel's append file and having the same + name as the kernel's main recipe file. + With all these conditions met, simply reference those files in + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement in the append file. + </para> + + <para> + For example, suppose you had some configuration options + in a file called <filename>network_configs.cfg</filename>. + You can place that file inside a directory named + <filename>linux-yocto</filename> and then add + a <filename>SRC_URI</filename> statement such as the + following to the append file. + When the OpenEmbedded build system builds the kernel, the + configuration options are picked up and applied. + <literallayout class='monospaced'> + SRC_URI += "file://network_configs.cfg" + </literallayout> + </para> + + <para> + To group related configurations into multiple files, you + perform a similar procedure. + Here is an example that groups separate configurations + specifically for Ethernet and graphics into their own + files and adds the configurations by using a + <filename>SRC_URI</filename> statement like the following + in your append file: + <literallayout class='monospaced'> + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + </literallayout> + </para> + + <para> + Another variable you can use in your kernel recipe append + file is the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + variable. + When you use this statement, you are extending the locations + used by the OpenEmbedded system to look for files and + patches as the recipe is processed. + </para> + + <note> + <para> + Other methods exist to accomplish grouping and defining + configuration options. + For example, if you are working with a local clone of the + kernel repository, you could checkout the kernel's + <filename>meta</filename> branch, make your changes, and + then push the changes to the local bare clone of the + kernel. + The result is that you directly add configuration options + to the <filename>meta</filename> branch for your BSP. + The configuration options will likely end up in that + location anyway if the BSP gets added to the Yocto Project. + </para> + + <para> + In general, however, the Yocto Project maintainers take + care of moving the <filename>SRC_URI</filename>-specified + configuration options to the kernel's + <filename>meta</filename> branch. + Not only is it easier for BSP developers to not have to + worry about putting those configurations in the branch, + but having the maintainers do it allows them to apply + 'global' knowledge about the kinds of common configuration + options multiple BSPs in the tree are typically using. + This allows for promotion of common configurations into + common features. + </para> + </note> + </section> + + <section id='applying-patches'> + <title>Applying Patches</title> + + <para> + If you have a single patch or a small series of patches + that you want to apply to the Linux kernel source, you + can do so just as you would with any other recipe. + You first copy the patches to the path added to + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + in your <filename>.bbappend</filename> file as described in + the previous section, and then reference them in + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statements. + </para> + + <para> + For example, you can apply a three-patch series by adding the + following lines to your linux-yocto + <filename>.bbappend</filename> file in your layer: + <literallayout class='monospaced'> + SRC_URI += "file://0001-first-change.patch" + SRC_URI += "file://0002-second-change.patch" + SRC_URI += "file://0003-third-change.patch" + </literallayout> + The next time you run BitBake to build the Linux kernel, + BitBake detects the change in the recipe and fetches and + applies the patches before building the kernel. + </para> + + <para> + For a detailed example showing how to patch the kernel using + <filename>devtool</filename>, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + and + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + sections. + </para> + </section> + + <section id='changing-the-configuration'> + <title>Changing the Configuration</title> + + <para> + You can make wholesale or incremental changes to the final + <filename>.config</filename> file used for the eventual + Linux kernel configuration by including a + <filename>defconfig</filename> file and by specifying + configuration fragments in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + to be applied to that file. + </para> + + <para> + If you have a complete, working Linux kernel + <filename>.config</filename> + file you want to use for the configuration, as before, copy + that file to the appropriate <filename>${PN}</filename> + directory in your layer's + <filename>recipes-kernel/linux</filename> directory, + and rename the copied file to "defconfig". + Then, add the following lines to the linux-yocto + <filename>.bbappend</filename> file in your layer: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + SRC_URI += "file://defconfig" + </literallayout> + The <filename>SRC_URI</filename> tells the build system how to + search for the file, while the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + extends the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> + variable (search directories) to include the + <filename>${PN}</filename> directory you created to hold the + configuration changes. + </para> + + <note> + The build system applies the configurations from the + <filename>defconfig</filename> file before applying any + subsequent configuration fragments. + The final kernel configuration is a combination of the + configurations in the <filename>defconfig</filename> file and + any configuration fragments you provide. + You need to realize that if you have any configuration + fragments, the build system applies these on top of and + after applying the existing <filename>defconfig</filename> + file configurations. + </note> + + <para> + Generally speaking, the preferred approach is to determine the + incremental change you want to make and add that as a + configuration fragment. + For example, if you want to add support for a basic serial + console, create a file named <filename>8250.cfg</filename> in + the <filename>${PN}</filename> directory with the following + content (without indentation): + <literallayout class='monospaced'> + CONFIG_SERIAL_8250=y + CONFIG_SERIAL_8250_CONSOLE=y + CONFIG_SERIAL_8250_PCI=y + CONFIG_SERIAL_8250_NR_UARTS=4 + CONFIG_SERIAL_8250_RUNTIME_UARTS=4 + CONFIG_SERIAL_CORE=y + CONFIG_SERIAL_CORE_CONSOLE=y + </literallayout> + Next, include this configuration fragment and extend the + <filename>FILESPATH</filename> variable in your + <filename>.bbappend</filename> file: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + SRC_URI += "file://8250.cfg" + </literallayout> + The next time you run BitBake to build the Linux kernel, BitBake + detects the change in the recipe and fetches and applies the + new configuration before building the kernel. + </para> + + <para> + For a detailed example showing how to configure the kernel, + see the + "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" + section. + </para> + </section> + + <section id='using-an-in-tree-defconfig-file'> + <title>Using an "In-Tree" <filename>defconfig</filename> File</title> + + <para> + It might be desirable to have kernel configuration fragment + support through a <filename>defconfig</filename> file that + is pulled from the kernel source tree for the configured + machine. + By default, the OpenEmbedded build system looks for + <filename>defconfig</filename> files in the layer used for + Metadata, which is "out-of-tree", and then configures them + using the following: + <literallayout class='monospaced'> + SRC_URI += "file://defconfig" + </literallayout> + If you do not want to maintain copies of + <filename>defconfig</filename> files in your layer but would + rather allow users to use the default configuration from the + kernel tree and still be able to add configuration fragments + to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + through, for example, append files, you can direct the + OpenEmbedded build system to use a + <filename>defconfig</filename> file that is "in-tree". + </para> + + <para> + To specify an "in-tree" <filename>defconfig</filename> file, + use the following statement form: + <literallayout class='monospaced'> + KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable> + </literallayout> + Here is an example that assigns the + <filename>KBUILD_DEFCONFIG</filename> variable based on + "raspberrypi2" and provides the path to the "in-tree" + <filename>defconfig</filename> file + to be used for a Raspberry Pi 2, + which is based on the Broadcom 2708/2709 chipset: + <literallayout class='monospaced'> + KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig" + </literallayout> + </para> + + <para> + Aside from modifying your kernel recipe and providing your own + <filename>defconfig</filename> file, you need to be sure no + files or statements set <filename>SRC_URI</filename> to use a + <filename>defconfig</filename> other than your "in-tree" + file (e.g. a kernel's + <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename> + file). + In other words, if the build system detects a statement + that identifies an "out-of-tree" + <filename>defconfig</filename> file, that statement + will override your + <filename>KBUILD_DEFCONFIG</filename> variable. + </para> + + <para> + See the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink> + variable description for more information. + </para> + </section> + </section> + + <section id="using-devtool-to-patch-the-kernel"> + <title>Using <filename>devtool</filename> to Patch the Kernel</title> + + <para> + The steps in this procedure show you how you can patch the + kernel using the extensible SDK and <filename>devtool</filename>. + <note> + Before attempting this procedure, be sure you have performed + the steps to get ready for updating the kernel as described + in the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" + section. + </note> + </para> + + <para> + Patching the kernel involves changing or adding configurations + to an existing kernel, changing or adding recipes to the kernel + that are needed to support specific hardware features, or even + altering the source code itself. + </para> + + <para> + This example creates a simple patch by adding some QEMU emulator + console output at boot time through <filename>printk</filename> + statements in the kernel's <filename>calibrate.c</filename> source + code file. + Applying the patch and booting the modified image causes the added + messages to appear on the emulator's console. + The example is a continuation of the setup procedure found in + the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" + Section. + <orderedlist> + <listitem><para> + <emphasis>Check Out the Kernel Source Files:</emphasis> + First you must use <filename>devtool</filename> to checkout + the kernel source code in its workspace. + Be sure you are in the terminal set up to do work + with the extensible SDK. + <note> + See this + <link linkend='setting-up-the-esdk-terminal'>step</link> + in the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>" + section for more information. + </note> + Use the following <filename>devtool</filename> command + to check out the code: + <literallayout class='monospaced'> + $ devtool modify linux-yocto + </literallayout> + <note> + During the checkout operation, a bug exists that could + cause errors such as the following to appear: + <literallayout class='monospaced'> + ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus + be3a89ce7c47178880ba7bf6293d7404 for + /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack + </literallayout> + You can safely ignore these messages. + The source code is correctly checked out. + </note> + </para></listitem> + <listitem><para> + <emphasis>Edit the Source Files</emphasis> + Follow these steps to make some simple changes to the source + files: + <orderedlist> + <listitem><para> + <emphasis>Change the working directory</emphasis>: + In the previous step, the output noted where you can find + the source files (e.g. + <filename>~/poky_sdk/workspace/sources/linux-yocto</filename>). + Change to where the kernel source code is before making + your edits to the <filename>calibrate.c</filename> file: + <literallayout class='monospaced'> + $ cd ~/poky_sdk/workspace/sources/linux-yocto + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Edit the source file</emphasis>: + Edit the <filename>init/calibrate.c</filename> file to have + the following changes: + <literallayout class='monospaced'> + void calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + printk("*************************************\n"); + printk("* *\n"); + printk("* HELLO YOCTO KERNEL *\n"); + printk("* *\n"); + printk("*************************************\n"); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + </literallayout> + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para> + <emphasis>Build the Updated Kernel Source:</emphasis> + To build the updated kernel source, use + <filename>devtool</filename>: + <literallayout class='monospaced'> + $ devtool build linux-yocto + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create the Image With the New Kernel:</emphasis> + Use the <filename>devtool build-image</filename> command + to create a new image that has the new kernel. + <note> + If the image you originally created resulted in a Wic + file, you can use an alternate method to create the new + image with the updated kernel. + For an example, see the steps in the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk'>TipsAndTricks/KernelDevelopmentWithEsdk</ulink> + Wiki Page. + </note> + <literallayout class='monospaced'> + $ cd ~ + $ devtool build-image core-image-minimal + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Test the New Image:</emphasis> + For this example, you can run the new image using QEMU + to verify your changes: + <orderedlist> + <listitem><para> + <emphasis>Boot the image</emphasis>: + Boot the modified image in the QEMU emulator + using this command: + <literallayout class='monospaced'> + $ runqemu qemux86 + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Verify the changes</emphasis>: + Log into the machine using <filename>root</filename> + with no password and then use the following shell + command to scroll through the console's boot output. + <literallayout class='monospaced'> + # dmesg | less + </literallayout> + You should see the results of your + <filename>printk</filename> statements + as part of the output when you scroll down the + console window. + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para> + <emphasis>Stage and commit your changes</emphasis>: + Within your eSDK terminal, change your working directory to + where you modified the <filename>calibrate.c</filename> + file and use these Git commands to stage and commit your + changes: + <literallayout class='monospaced'> + $ cd ~/poky_sdk/workspace/sources/linux-yocto + $ git status + $ git add init/calibrate.c + $ git commit -m "calibrate: Add printk example" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Export the Patches and Create an Append File:</emphasis> + To export your commits as patches and create a + <filename>.bbappend</filename> file, use the following + command in the terminal used to work with the extensible + SDK. + This example uses the previously established layer named + <filename>meta-mylayer</filename>. + <note> + See Step 3 of the + "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using devtool</link>" + section for information on setting up this layer. + </note> + <literallayout class='monospaced'> + $ devtool finish linux-yocto ~/meta-mylayer + </literallayout> + Once the command finishes, the patches and the + <filename>.bbappend</filename> file are located in the + <filename>~/meta-mylayer/recipes-kernel/linux</filename> + directory. + </para></listitem> + <listitem><para> + <emphasis>Build the Image With Your Modified Kernel:</emphasis> + You can now build an image that includes your kernel + patches. + Execute the following command from your + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + in the terminal set up to run BitBake: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake core-image-minimal + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id="using-traditional-kernel-development-to-patch-the-kernel"> + <title>Using Traditional Kernel Development to Patch the Kernel</title> + + <para> + The steps in this procedure show you how you can patch the + kernel using traditional kernel development (i.e. not using + <filename>devtool</filename> and the extensible SDK as + described in the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section). + <note> + Before attempting this procedure, be sure you have performed + the steps to get ready for updating the kernel as described + in the + "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" + section. + </note> + </para> + + <para> + Patching the kernel involves changing or adding configurations + to an existing kernel, changing or adding recipes to the kernel + that are needed to support specific hardware features, or even + altering the source code itself. + </para> + + <para> + The example in this section creates a simple patch by adding some + QEMU emulator console output at boot time through + <filename>printk</filename> statements in the kernel's + <filename>calibrate.c</filename> source code file. + Applying the patch and booting the modified image causes the added + messages to appear on the emulator's console. + The example is a continuation of the setup procedure found in + the + "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" + Section. + <orderedlist> + <listitem><para> + <emphasis>Edit the Source Files</emphasis> + Prior to this step, you should have used Git to create a + local copy of the repository for your kernel. + Assuming you created the repository as directed in the + "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" + section, use the following commands to edit the + <filename>calibrate.c</filename> file: + <orderedlist> + <listitem><para> + <emphasis>Change the working directory</emphasis>: + You need to locate the source files in the + local copy of the kernel Git repository: + Change to where the kernel source code is before making + your edits to the <filename>calibrate.c</filename> file: + <literallayout class='monospaced'> + $ cd ~/linux-yocto-4.12/init + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Edit the source file</emphasis>: + Edit the <filename>calibrate.c</filename> file to have + the following changes: + <literallayout class='monospaced'> + void calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + printk("*************************************\n"); + printk("* *\n"); + printk("* HELLO YOCTO KERNEL *\n"); + printk("* *\n"); + printk("*************************************\n"); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + </literallayout> + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para> + <emphasis>Stage and Commit Your Changes:</emphasis> + Use standard Git commands to stage and commit the changes + you just made: + <literallayout class='monospaced'> + $ git add calibrate.c + $ git commit -m "calibrate.c - Added some printk statements" + </literallayout> + If you do not stage and commit your changes, the OpenEmbedded + Build System will not pick up the changes. + </para></listitem> + <listitem><para> + <emphasis>Update Your <filename>local.conf</filename> File + to Point to Your Source Files:</emphasis> + In addition to your <filename>local.conf</filename> file + specifying to use "kernel-modules" and the "qemux86" + machine, it must also point to the updated kernel source + files. + Add + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> + statements similar to the following to your + <filename>local.conf</filename>: + <literallayout class='monospaced'> + $ cd ~/poky/build/conf + </literallayout> + Add the following to the <filename>local.conf</filename>: + <literallayout class='monospaced'> + SRC_URI_pn-linux-yocto = "git:///<replaceable>path-to</replaceable>/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ + git:///<replaceable>path-to</replaceable>/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" + SRCREV_meta_qemux86 = "${AUTOREV}" + SRCREV_machine_qemux86 = "${AUTOREV}" + </literallayout> + <note> + Be sure to replace + <replaceable>path-to</replaceable> with the pathname + to your local Git repositories. + Also, you must be sure to specify the correct branch + and machine types. + For this example, the branch is + <filename>standard/base</filename> and the machine is + "qemux86". + </note> + </para></listitem> + <listitem><para> + <emphasis>Build the Image:</emphasis> + With the source modified, your changes staged and + committed, and the <filename>local.conf</filename> file + pointing to the kernel files, you can now use BitBake to + build the image: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake core-image-minimal + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Boot the image</emphasis>: + Boot the modified image in the QEMU emulator + using this command. + When prompted to login to the QEMU console, use "root" + with no password: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ runqemu qemux86 + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Look for Your Changes:</emphasis> + As QEMU booted, you might have seen your changes rapidly + scroll by. + If not, use these commands to see your changes: + <literallayout class='monospaced'> + # dmesg | less + </literallayout> + You should see the results of your + <filename>printk</filename> statements + as part of the output when you scroll down the + console window. + </para></listitem> + <listitem><para> + <emphasis>Generate the Patch File:</emphasis> + Once you are sure that your patch works correctly, you + can generate a <filename>*.patch</filename> file in the + kernel source repository: + <literallayout class='monospaced'> + $ cd ~/linux-yocto-4.12/init + $ git format-patch -1 + 0001-calibrate.c-Added-some-printk-statements.patch + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Move the Patch File to Your Layer:</emphasis> + In order for subsequent builds to pick up patches, you + need to move the patch file you created in the previous + step to your layer <filename>meta-mylayer</filename>. + For this example, the layer created earlier is located + in your home directory as <filename>meta-mylayer</filename>. + When the layer was created using the + <filename>yocto-create</filename> script, no additional + hierarchy was created to support patches. + Before moving the patch file, you need to add additional + structure to your layer using the following commands: + <literallayout class='monospaced'> + $ cd ~/meta-mylayer + $ mkdir recipes-kernel + $ mkdir recipes-kernel/linux + $ mkdir recipes-kernel/linux/linux-yocto + </literallayout> + Once you have created this hierarchy in your layer, you can + move the patch file using the following command: + <literallayout class='monospaced'> + $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create the Append File:</emphasis> + Finally, you need to create the + <filename>linux-yocto_4.12.bbappend</filename> file and + insert statements that allow the OpenEmbedded build + system to find the patch. + The append file needs to be in your layer's + <filename>recipes-kernel/linux</filename> + directory and it must be named + <filename>linux-yocto_4.12.bbappend</filename> and have + the following contents: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + SRC_URI_append = " file://0001-calibrate.c-Added-some-printk-statements.patch" + </literallayout> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statements enable the OpenEmbedded build system to find + the patch file.</para> + + <para>For more information on append files and patches, + see the + "<link linkend='creating-the-append-file'>Creating the Append File</link>" + and + "<link linkend='applying-patches'>Applying Patches</link>" + sections. + You can also see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer"</ulink>" + section in the Yocto Project Development Tasks Manual. + <note> + To build <filename>core-image-minimal</filename> + again and see the effects of your patch, you can + essentially eliminate the temporary source files + saved in <filename>poky/build/tmp/work/...</filename> + and residual effects of the build by entering the + following sequence of commands: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ bitbake -c cleanall yocto-linux + $ bitbake core-image-minimal -c cleanall + $ bitbake core-image-minimal + $ runqemu qemux86 + </literallayout> + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='configuring-the-kernel'> + <title>Configuring the Kernel</title> + + <para> + Configuring the Yocto Project kernel consists of making sure the + <filename>.config</filename> file has all the right information + in it for the image you are building. + You can use the <filename>menuconfig</filename> tool and + configuration fragments to make sure your + <filename>.config</filename> file is just how you need it. + You can also save known configurations in a + <filename>defconfig</filename> file that the build system can use + for kernel configuration. + </para> + + <para> + This section describes how to use <filename>menuconfig</filename>, + create and use configuration fragments, and how to interactively + modify your <filename>.config</filename> file to create the + leanest kernel configuration file possible. + </para> + + <para> + For more information on kernel configuration, see the + "<link linkend='changing-the-configuration'>Changing the Configuration</link>" + section. + </para> + + <section id='using-menuconfig'> + <title>Using <filename>menuconfig</filename></title> + + <para> + The easiest way to define kernel configurations is to set + them through the <filename>menuconfig</filename> tool. + This tool provides an interactive method with which + to set kernel configurations. + For general information on <filename>menuconfig</filename>, see + <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>. + </para> + + <para> + To use the <filename>menuconfig</filename> tool in the Yocto + Project development environment, you must do the following: + <itemizedlist> + <listitem><para> + Because you launch <filename>menuconfig</filename> + using BitBake, you must be sure to set up your + environment by running the + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + script found in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. + </para></listitem> + <listitem><para> + You must be sure of the state of your build's + configuration in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + </para></listitem> + <listitem><para> + Your build host must have the following two packages + installed: + <literallayout class='monospaced'> + libncurses5-dev + libtinfo-dev + </literallayout> + </para></listitem> + </itemizedlist> + </para> + + <para> + The following commands initialize the BitBake environment, + run the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink> + task, and launch <filename>menuconfig</filename>. + These commands assume the Source Directory's top-level folder + is <filename>~/poky</filename>: + <literallayout class='monospaced'> + $ cd poky + $ source oe-init-build-env + $ bitbake linux-yocto -c kernel_configme -f + $ bitbake linux-yocto -c menuconfig + </literallayout> + Once <filename>menuconfig</filename> comes up, its standard + interface allows you to interactively examine and configure + all the kernel configuration parameters. + After making your changes, simply exit the tool and save your + changes to create an updated version of the + <filename>.config</filename> configuration file. + <note> + You can use the entire <filename>.config</filename> file + as the <filename>defconfig</filename> file. + For information on <filename>defconfig</filename> files, + see the + "<link linkend='changing-the-configuration'>Changing the Configuration</link>", + "<link linkend='using-an-in-tree-defconfig-file'>Using an In-Tree <filename>defconfig</filename> File</link>, + and + "<link linkend='creating-a-defconfig-file'>Creating a <filename>defconfig</filename> File</link>" + sections. + </note> + </para> + + <para> + Consider an example that configures the "CONFIG_SMP" setting + for the <filename>linux-yocto-4.12</filename> kernel. + <note> + The OpenEmbedded build system recognizes this kernel as + <filename>linux-yocto</filename> through Metadata (e.g. + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink><filename>_linux-yocto ?= "12.4%"</filename>). + </note> + Once <filename>menuconfig</filename> launches, use the + interface to navigate through the selections to find the + configuration settings in which you are interested. + For this example, you deselect "CONFIG_SMP" by clearing the + "Symmetric Multi-Processing Support" option. + Using the interface, you can find the option under + "Processor Type and Features". + To deselect "CONFIG_SMP", use the arrow keys to + highlight "Symmetric Multi-Processing Support" and enter "N" + to clear the asterisk. + When you are finished, exit out and save the change. + </para> + + <para> + Saving the selections updates the <filename>.config</filename> + configuration file. + This is the file that the OpenEmbedded build system uses to + configure the kernel during the build. + You can find and examine this file in the Build Directory in + <filename>tmp/work/</filename>. + The actual <filename>.config</filename> is located in the + area where the specific kernel is built. + For example, if you were building a Linux Yocto kernel based + on the <filename>linux-yocto-4.12</filename> kernel and you + were building a QEMU image targeted for + <filename>x86</filename> architecture, the + <filename>.config</filename> file would be: + <literallayout class='monospaced'> + poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18... + ...967-r0/linux-qemux86-standard-build/.config + </literallayout> + <note> + The previous example directory is artificially split and + many of the characters in the actual filename are omitted + in order to make it more readable. + Also, depending on the kernel you are using, the exact + pathname might differ. + </note> + </para> + + <para> + Within the <filename>.config</filename> file, you can see the + kernel settings. + For example, the following entry shows that symmetric + multi-processor support is not set: + <literallayout class='monospaced'> + # CONFIG_SMP is not set + </literallayout> + </para> + + <para> + A good method to isolate changed configurations is to use a + combination of the <filename>menuconfig</filename> tool and + simple shell commands. + Before changing configurations with + <filename>menuconfig</filename>, copy the existing + <filename>.config</filename> and rename it to something else, + use <filename>menuconfig</filename> to make as many changes as + you want and save them, then compare the renamed configuration + file against the newly created file. + You can use the resulting differences as your base to create + configuration fragments to permanently save in your kernel + layer. + <note> + Be sure to make a copy of the <filename>.config</filename> + file and do not just rename it. + The build system needs an existing + <filename>.config</filename> file from which to work. + </note> + </para> + </section> + + <section id='creating-a-defconfig-file'> + <title>Creating a <filename>defconfig</filename> File</title> + + <para> + A <filename>defconfig</filename> file in the context of + the Yocto Project is often a <filename>.config</filename> + file that is copied from a build or a + <filename>defconfig</filename> taken from the kernel tree + and moved into recipe space. + You can use a <filename>defconfig</filename> file + to retain a known set of kernel configurations from which the + OpenEmbedded build system can draw to create the final + <filename>.config</filename> file. + <note> + Out-of-the-box, the Yocto Project never ships a + <filename>defconfig</filename> or + <filename>.config</filename> file. + The OpenEmbedded build system creates the final + <filename>.config</filename> file used to configure the + kernel. + </note> + </para> + + <para> + To create a <filename>defconfig</filename>, start with a + complete, working Linux kernel <filename>.config</filename> + file. + Copy that file to the appropriate + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> + directory in your layer's + <filename>recipes-kernel/linux</filename> directory, and rename + the copied file to "defconfig" (e.g. + <filename>~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig</filename>). + Then, add the following lines to the linux-yocto + <filename>.bbappend</filename> file in your layer: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + SRC_URI += "file://defconfig" + </literallayout> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + tells the build system how to search for the file, while the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + extends the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> + variable (search directories) to include the + <filename>${PN}</filename> directory you created to hold the + configuration changes. + <note> + The build system applies the configurations from the + <filename>defconfig</filename> file before applying any + subsequent configuration fragments. + The final kernel configuration is a combination of the + configurations in the <filename>defconfig</filename> + file and any configuration fragments you provide. + You need to realize that if you have any configuration + fragments, the build system applies these on top of and + after applying the existing defconfig file configurations. + </note> + For more information on configuring the kernel, see the + "<link linkend='changing-the-configuration'>Changing the Configuration</link>" + section. + </para> + </section> + + <section id='creating-config-fragments'> + <title>Creating Configuration Fragments</title> + + <para> + Configuration fragments are simply kernel options that + appear in a file placed where the OpenEmbedded build system + can find and apply them. + The build system applies configuration fragments after + applying configurations from a <filename>defconfig</filename> + file. + Thus, the final kernel configuration is a combination of the + configurations in the <filename>defconfig</filename> + file and then any configuration fragments you provide. + The build system applies fragments on top of and + after applying the existing defconfig file configurations. + </para> + + <para> + Syntactically, the configuration statement is identical to + what would appear in the <filename>.config</filename> file, + which is in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. + <note> + For more information about where the + <filename>.config</filename> file is located, see the + example in the + "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" + section. + </note> + </para> + + <para> + It is simple to create a configuration fragment. + One method is to use shell commands. + For example, issuing the following from the shell creates a + configuration fragment file named + <filename>my_smp.cfg</filename> that enables multi-processor + support within the kernel: + <literallayout class='monospaced'> + $ echo "CONFIG_SMP=y" >> my_smp.cfg + </literallayout> + <note> + All configuration fragment files must use the + <filename>.cfg</filename> extension in order for the + OpenEmbedded build system to recognize them as a + configuration fragment. + </note> + </para> + + <para> + Another method is to create a configuration fragment using the + differences between two configuration files: one previously + created and saved, and one freshly created using the + <filename>menuconfig</filename> tool. + </para> + + <para> + To create a configuration fragment using this method, follow + these steps: + <orderedlist> + <listitem><para> + <emphasis>Complete a Build Through Kernel Configuration:</emphasis> + Complete a build at least through the kernel + configuration task as follows: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configme -f + </literallayout> + This step ensures that you create a + <filename>.config</filename> file from a known state. + Because situations exist where your build state might + become unknown, it is best to run this task prior + to starting <filename>menuconfig</filename>. + </para></listitem> + <listitem><para> + <emphasis>Launch <filename>menuconfig</filename>:</emphasis> + Run the <filename>menuconfig</filename> command: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c menuconfig + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create the Configuration Fragment:</emphasis> + Run the <filename>diffconfig</filename> + command to prepare a configuration fragment. + The resulting file <filename>fragment.cfg</filename> + is placed in the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c diffconfig + </literallayout> + </para></listitem> + </orderedlist> + </para> + + <para> + The <filename>diffconfig</filename> command creates a file + that is a list of Linux kernel <filename>CONFIG_</filename> + assignments. + See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>" + section for additional information on how to use the output + as a configuration fragment. + <note> + You can also use this method to create configuration + fragments for a BSP. + See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>" + section for more information. + </note> + </para> + + <para> + Where do you put your configuration fragment files? + You can place these files in an area pointed to by + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + as directed by your <filename>bblayers.conf</filename> file, + which is located in your layer. + The OpenEmbedded build system picks up the configuration and + adds it to the kernel's configuration. + For example, suppose you had a set of configuration options + in a file called <filename>myconfig.cfg</filename>. + If you put that file inside a directory named + <filename>linux-yocto</filename> that resides in the same + directory as the kernel's append file within your layer + and then add the following statements to the kernel's append + file, those configuration options will be picked up and applied + when the kernel is built: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + SRC_URI += "file://myconfig.cfg" + </literallayout> + </para> + + <para> + As mentioned earlier, you can group related configurations + into multiple files and name them all in the + <filename>SRC_URI</filename> statement as well. + For example, you could group separate configurations + specifically for Ethernet and graphics into their own files + and add those by using a <filename>SRC_URI</filename> statement + like the following in your append file: + <literallayout class='monospaced'> + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + </literallayout> + </para> + </section> + + <section id='validating-configuration'> + <title>Validating Configuration</title> + + <para> + You can use the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink> + task to provide configuration validation: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configcheck -f + </literallayout> + Running this task produces warnings for when a + requested configuration does not appear in the final + <filename>.config</filename> file or when you override a + policy configuration in a hardware configuration fragment. + </para> + + <para> + In order to run this task, you must have an existing + <filename>.config</filename> file. + See the + "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" + section for information on how to create a configuration file. + </para> + + <para> + Following is sample output from the + <filename>do_kernel_configcheck</filename> task: + <literallayout class='monospaced'> + Loading cache: 100% |########################################################| Time: 0:00:00 + Loaded 1275 entries from dependency cache. + NOTE: Resolving any missing task queue dependencies + + Build Configuration: + . + . + . + + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck: + [kernel config]: specified values did not make it into the kernel's final configuration: + + ---------- CONFIG_X86_TSC ----------------- + Config: CONFIG_X86_TSC + From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg + Requested value: CONFIG_X86_TSC=y + Actual value: + + + ---------- CONFIG_X86_BIGSMP ----------------- + Config: CONFIG_X86_BIGSMP + From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg + /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig + Requested value: # CONFIG_X86_BIGSMP is not set + Actual value: + + + ---------- CONFIG_NR_CPUS ----------------- + Config: CONFIG_NR_CPUS + From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg + /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg + /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig + Requested value: CONFIG_NR_CPUS=8 + Actual value: CONFIG_NR_CPUS=1 + + + ---------- CONFIG_SCHED_SMT ----------------- + Config: CONFIG_SCHED_SMT + From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg + /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig + Requested value: CONFIG_SCHED_SMT=y + Actual value: + + + + NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded. + + Summary: There were 3 WARNING messages shown. + </literallayout> + <note> + The previous output example has artificial line breaks + to make it more readable. + </note> + </para> + + <para> + The output describes the various problems that you can + encounter along with where to find the offending configuration + items. + You can use the information in the logs to adjust your + configuration files and then repeat the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck'><filename>do_kernel_configcheck</filename></ulink> + tasks until they produce no warnings. + </para> + + <para> + For more information on how to use the + <filename>menuconfig</filename> tool, see the + "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>" + section. + </para> + </section> + + <section id='fine-tuning-the-kernel-configuration-file'> + <title>Fine-Tuning the Kernel Configuration File</title> + + <para> + You can make sure the <filename>.config</filename> file is as + lean or efficient as possible by reading the output of the + kernel configuration fragment audit, noting any issues, making + changes to correct the issues, and then repeating. + </para> + + <para> + As part of the kernel build process, the + <filename>do_kernel_configcheck</filename> task runs. + This task validates the kernel configuration by checking the + final <filename>.config</filename> file against the input + files. + During the check, the task produces warning messages for the + following issues: + <itemizedlist> + <listitem><para> + Requested options that did not make the final + <filename>.config</filename> file. + </para></listitem> + <listitem><para> + Configuration items that appear twice in the same + configuration fragment. + </para></listitem> + <listitem><para> + Configuration items tagged as "required" that were + overridden. + </para></listitem> + <listitem><para> + A board overrides a non-board specific option. + </para></listitem> + <listitem><para> + Listed options not valid for the kernel being + processed. + In other words, the option does not appear anywhere. + </para></listitem> + </itemizedlist> + <note> + The <filename>do_kernel_configcheck</filename> task can + also optionally report if an option is overridden during + processing. + </note> + </para> + + <para> + For each output warning, a message points to the file + that contains a list of the options and a pointer to the + configuration fragment that defines them. + Collectively, the files are the key to streamlining the + configuration. + </para> + + <para> + To streamline the configuration, do the following: + <orderedlist> + <listitem><para> + <emphasis>Use a Working Configuration:</emphasis> + Start with a full configuration that you + know works. + Be sure the configuration builds and boots + successfully. + Use this configuration file as your baseline. + </para></listitem> + <listitem><para> + <emphasis>Run Configure and Check Tasks:</emphasis> + Separately run the + <filename>do_kernel_configme</filename> and + <filename>do_kernel_configcheck</filename> tasks: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configme -f + $ bitbake linux-yocto -c kernel_configcheck -f + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Process the Results:</emphasis> + Take the resulting list of files from the + <filename>do_kernel_configcheck</filename> task + warnings and do the following: + <itemizedlist> + <listitem><para> + Drop values that are redefined in the fragment + but do not change the final + <filename>.config</filename> file. + </para></listitem> + <listitem><para> + Analyze and potentially drop values from the + <filename>.config</filename> file that override + required configurations. + </para></listitem> + <listitem><para> + Analyze and potentially remove non-board + specific options. + </para></listitem> + <listitem><para> + Remove repeated and invalid options. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Re-Run Configure and Check Tasks:</emphasis> + After you have worked through the output of the kernel + configuration audit, you can re-run the + <filename>do_kernel_configme</filename> and + <filename>do_kernel_configcheck</filename> tasks to + see the results of your changes. + If you have more issues, you can deal with them as + described in the previous step. + </para></listitem> + </orderedlist> + </para> + + <para> + Iteratively working through steps two through four eventually + yields a minimal, streamlined configuration file. + Once you have the best <filename>.config</filename>, you can + build the Linux Yocto kernel. + </para> + </section> + </section> + + <section id='expanding-variables'> + <title>Expanding Variables</title> + + <para> + Sometimes it is helpful to determine what a variable expands + to during a build. + You can do examine the values of variables by examining the + output of the <filename>bitbake -e</filename> command. + The output is long and is more easily managed in a text file, + which allows for easy searches: + <literallayout class='monospaced'> + $ bitbake -e virtual/kernel > <replaceable>some_text_file</replaceable> + </literallayout> + Within the text file, you can see exactly how each variable is + expanded and used by the OpenEmbedded build system. + </para> + </section> + + <section id='working-with-a-dirty-kernel-version-string'> + <title>Working with a "Dirty" Kernel Version String</title> + + <para> + If you build a kernel image and the version string has a + "+" or a "-dirty" at the end, uncommitted modifications exist + in the kernel's source directory. + Follow these steps to clean up the version string: + <orderedlist> + <listitem><para> + <emphasis>Discover the Uncommitted Changes:</emphasis> + Go to the kernel's locally cloned Git repository + (source directory) and use the following Git command + to list the files that have been changed, added, or + removed: + <literallayout class='monospaced'> + $ git status + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Commit the Changes:</emphasis> + You should commit those changes to the kernel source + tree regardless of whether or not you will save, + export, or use the changes: + <literallayout class='monospaced'> + $ git add + $ git commit -s -a -m "getting rid of -dirty" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Rebuild the Kernel Image:</emphasis> + Once you commit the changes, rebuild the kernel.</para> + + <para>Depending on your particular kernel development + workflow, the commands you use to rebuild the + kernel might differ. + For information on building the kernel image when + using <filename>devtool</filename>, see the + "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" + section. + For information on building the kernel image when + using Bitbake, see the + "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" + section. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='working-with-your-own-sources'> + <title>Working With Your Own Sources</title> + + <para> + If you cannot work with one of the Linux kernel + versions supported by existing linux-yocto recipes, you can + still make use of the Yocto Project Linux kernel tooling by + working with your own sources. + When you use your own sources, you will not be able to + leverage the existing kernel + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> and + stabilization work of the linux-yocto sources. + However, you will be able to manage your own Metadata in the same + format as the linux-yocto sources. + Maintaining format compatibility facilitates converging with + linux-yocto on a future, mutually-supported kernel version. + </para> + + <para> + To help you use your own sources, the Yocto Project provides a + linux-yocto custom recipe + (<filename>linux-yocto-custom.bb</filename>) that uses + <filename>kernel.org</filename> sources + and the Yocto Project Linux kernel tools for managing + kernel Metadata. + You can find this recipe in the + <filename>poky</filename> Git repository of the + Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> + at: + <literallayout class="monospaced"> + poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb + </literallayout> + </para> + + <para> + Here are some basic steps you can use to work with your own + sources: + <orderedlist> + <listitem><para> + <emphasis>Create a Copy of the Kernel Recipe:</emphasis> + Copy the <filename>linux-yocto-custom.bb</filename> + recipe to your layer and give it a meaningful name. + The name should include the version of the Yocto Linux + kernel you are using (e.g. + <filename>linux-yocto-myproject_4.12.bb</filename>, + where "4.12" is the base version of the Linux kernel + with which you would be working). + </para></listitem> + <listitem><para> + <emphasis>Create a Directory for Your Patches:</emphasis> + In the same directory inside your layer, create a matching + directory to store your patches and configuration files + (e.g. <filename>linux-yocto-myproject</filename>). + </para></listitem> + <listitem><para> + <emphasis>Ensure You Have Configurations:</emphasis> + Make sure you have either a <filename>defconfig</filename> + file or configuration fragment files in your layer. + When you use the <filename>linux-yocto-custom.bb</filename> + recipe, you must specify a configuration. + If you do not have a <filename>defconfig</filename> file, + you can run the following: + <literallayout class='monospaced'> + $ make defconfig + </literallayout> + After running the command, copy the resulting + <filename>.config</filename> file to the + <filename>files</filename> directory in your layer + as "defconfig" and then add it to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable in the recipe.</para> + + <para>Running the <filename>make defconfig</filename> + command results in the default configuration for your + architecture as defined by your kernel. + However, no guarantee exists that this configuration is + valid for your use case, or that your board will even boot. + This is particularly true for non-x86 architectures.</para> + + <para>To use non-x86 <filename>defconfig</filename> files, + you need to be more specific and find one that matches your + board (i.e. for arm, you look in + <filename>arch/arm/configs</filename> and use the one that + is the best starting point for your board). + </para></listitem> + <listitem><para> + <emphasis>Edit the Recipe:</emphasis> + Edit the following variables in your recipe as appropriate + for your project: + <itemizedlist> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>: + The <filename>SRC_URI</filename> should specify + a Git repository that uses one of the supported Git + fetcher protocols (i.e. <filename>file</filename>, + <filename>git</filename>, <filename>http</filename>, + and so forth). + The <filename>SRC_URI</filename> variable should + also specify either a <filename>defconfig</filename> + file or some configuration fragment files. + The skeleton recipe provides an example + <filename>SRC_URI</filename> as a syntax reference. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>: + The Linux kernel version you are using (e.g. + "4.12"). + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>: + The Linux kernel + <filename>CONFIG_LOCALVERSION</filename> that is + compiled into the resulting kernel and visible + through the <filename>uname</filename> command. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>: + The commit ID from which you want to build. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: + Treat this variable the same as you would in any + other recipe. + Increment the variable to indicate to the + OpenEmbedded build system that the recipe has + changed. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: + The default <filename>PV</filename> assignment is + typically adequate. + It combines the <filename>LINUX_VERSION</filename> + with the Source Control Manager (SCM) revision + as derived from the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink> + variable. + The combined results are a string with the + following form: + <literallayout class='monospaced'> + 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 + </literallayout> + While lengthy, the extra verbosity in + <filename>PV</filename> helps ensure you are using + the exact sources from which you intend to build. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>: + A list of the machines supported by your new recipe. + This variable in the example recipe is set + by default to a regular expression that matches + only the empty string, "(^$)". + This default setting triggers an explicit build + failure. + You must change it to match a list of the machines + that your new recipe supports. + For example, to support the + <filename>qemux86</filename> and + <filename>qemux86-64</filename> machines, use + the following form: + <literallayout class='monospaced'> + COMPATIBLE_MACHINE = "qemux86|qemux86-64" + </literallayout> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Customize Your Recipe as Needed:</emphasis> + Provide further customizations to your recipe + as needed just as you would customize an existing + linux-yocto recipe. + See the + "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" + section for information. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='working-with-out-of-tree-modules'> + <title>Working with Out-of-Tree Modules</title> + + <para> + This section describes steps to build out-of-tree modules on + your target and describes how to incorporate out-of-tree modules + in the build. + </para> + + <section id='building-out-of-tree-modules-on-the-target'> + <title>Building Out-of-Tree Modules on the Target</title> + + <para> + While the traditional Yocto Project development model would be + to include kernel modules as part of the normal build + process, you might find it useful to build modules on the + target. + This could be the case if your target system is capable + and powerful enough to handle the necessary compilation. + Before deciding to build on your target, however, you should + consider the benefits of using a proper cross-development + environment from your build host. + </para> + + <para> + If you want to be able to build out-of-tree modules on + the target, there are some steps you need to take + on the target that is running your SDK image. + Briefly, the <filename>kernel-dev</filename> package + is installed by default on all + <filename>*.sdk</filename> images and the + <filename>kernel-devsrc</filename> package is installed + on many of the <filename>*.sdk</filename> images. + However, you need to create some scripts prior to + attempting to build the out-of-tree modules on the target + that is running that image. + </para> + + <para> + Prior to attempting to build the out-of-tree modules, + you need to be on the target as root and you need to + change to the <filename>/usr/src/kernel</filename> directory. + Next, <filename>make</filename> the scripts: + <literallayout class='monospaced'> + # cd /usr/src/kernel + # make scripts + </literallayout> + Because all SDK image recipes include + <filename>dev-pkgs</filename>, the + <filename>kernel-dev</filename> packages will be installed + as part of the SDK image and the + <filename>kernel-devsrc</filename> packages will be installed + as part of applicable SDK images. + The SDK uses the scripts when building out-of-tree + modules. + Once you have switched to that directory and created the + scripts, you should be able to build your out-of-tree modules + on the target. + </para> + </section> + + <section id='incorporating-out-of-tree-modules'> + <title>Incorporating Out-of-Tree Modules</title> + + <para> + While it is always preferable to work with sources integrated + into the Linux kernel sources, if you need an external kernel + module, the <filename>hello-mod.bb</filename> recipe is + available as a template from which you can create your + own out-of-tree Linux kernel module recipe. + </para> + + <para> + This template recipe is located in the + <filename>poky</filename> Git repository of the + Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> + at: + <literallayout class="monospaced"> + poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb + </literallayout> + </para> + + <para> + To get started, copy this recipe to your layer and give it a + meaningful name (e.g. <filename>mymodule_1.0.bb</filename>). + In the same directory, create a new directory named + <filename>files</filename> where you can store any source files, + patches, or other files necessary for building + the module that do not come with the sources. + Finally, update the recipe as needed for the module. + Typically, you will need to set the following variables: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> + </para></listitem> + </itemizedlist> + </para> + + <para> + Depending on the build system used by the module sources, + you might need to make some adjustments. + For example, a typical module <filename>Makefile</filename> + looks much like the one provided with the + <filename>hello-mod</filename> template: + <literallayout class='monospaced'> + obj-m := hello.o + + SRC := $(shell pwd) + + all: + $(MAKE) -C $(KERNEL_SRC) M=$(SRC) + + modules_install: + $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install + ... + </literallayout> + </para> + + <para> + The important point to note here is the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink> + variable. + The + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink> + class sets this variable and the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink> + variable to + <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename> + with the necessary Linux kernel build information to build + modules. + If your module <filename>Makefile</filename> uses a different + variable, you might want to override the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink> + step, or create a patch to + the <filename>Makefile</filename> to work with the more typical + <filename>KERNEL_SRC</filename> or + <filename>KERNEL_PATH</filename> variables. + </para> + + <para> + After you have prepared your recipe, you will likely want to + include the module in your images. + To do this, see the documentation for the following variables in + the Yocto Project Reference Manual and set one of them + appropriately for your machine configuration file: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink> + </para></listitem> + </itemizedlist> + </para> + + <para> + Modules are often not required for boot and can be excluded from + certain build configurations. + The following allows for the most flexibility: + <literallayout class='monospaced'> + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" + </literallayout> + The value is derived by appending the module filename without + the <filename>.ko</filename> extension to the string + "kernel-module-". + </para> + + <para> + Because the variable is + <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> + and not a + <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> + variable, the build will not fail if this module is not + available to include in the image. + </para> + </section> + </section> + + + <section id='inspecting-changes-and-commits'> + <title>Inspecting Changes and Commits</title> + + <para> + A common question when working with a kernel is: + "What changes have been applied to this tree?" + Rather than using "grep" across directories to see what has + changed, you can use Git to inspect or search the kernel tree. + Using Git is an efficient way to see what has changed in the tree. + </para> + + <section id='what-changed-in-a-kernel'> + <title>What Changed in a Kernel?</title> + + <para> + Following are a few examples that show how to use Git + commands to examine changes. + These examples are by no means the only way to see changes. + <note> + In the following examples, unless you provide a commit + range, <filename>kernel.org</filename> history is blended + with Yocto Project kernel changes. + You can form ranges by using branch names from the + kernel tree as the upper and lower commit markers with + the Git commands. + You can see the branch names through the web interface + to the Yocto Project source repositories at + <ulink url='&YOCTO_GIT_URL;'></ulink>. + </note> + To see a full range of the changes, use the + <filename>git whatchanged</filename> command and specify a + commit range for the branch + (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>). + </para> + + <para> + Here is an example that looks at what has changed in the + <filename>emenlow</filename> branch of the + <filename>linux-yocto-3.19</filename> kernel. + The lower commit range is the commit associated with the + <filename>standard/base</filename> branch, while + the upper commit range is the commit associated with the + <filename>standard/emenlow</filename> branch. + <literallayout class='monospaced'> + $ git whatchanged origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + To see short, one line summaries of changes use the + <filename>git log</filename> command: + <literallayout class='monospaced'> + $ git log --oneline origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + Use this command to see code differences for the changes: + <literallayout class='monospaced'> + $ git diff origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + Use this command to see the commit log messages and the + text differences: + <literallayout class='monospaced'> + $ git show origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + + <para> + Use this command to create individual patches for + each change. + Here is an example that that creates patch files for each + commit and places them in your <filename>Documents</filename> + directory: + <literallayout class='monospaced'> + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + </literallayout> + </para> + </section> + + <section id='showing-a-particular-feature-or-branch-change'> + <title>Showing a Particular Feature or Branch Change</title> + + <para> + Tags in the Yocto Project kernel tree divide changes for + significant features or branches. + The <filename>git show</filename> <replaceable>tag</replaceable> + command shows changes based on a tag. + Here is an example that shows <filename>systemtap</filename> + changes: + <literallayout class='monospaced'> + $ git show systemtap + </literallayout> + You can use the + <filename>git branch --contains</filename> <replaceable>tag</replaceable> + command to show the branches that contain a particular feature. + This command shows the branches that contain the + <filename>systemtap</filename> feature: + <literallayout class='monospaced'> + $ git branch --contains systemtap + </literallayout> + </para> + </section> + </section> + + <section id='adding-recipe-space-kernel-features'> + <title>Adding Recipe-Space Kernel Features</title> + + <para> + You can add kernel features in the + <link linkend='recipe-space-metadata'>recipe-space</link> by + using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable and by specifying the feature's <filename>.scc</filename> + file path in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement. + When you add features using this method, the OpenEmbedded build + system checks to be sure the features are present. + If the features are not present, the build stops. + Kernel features are the last elements processed for configuring + and patching the kernel. + Therefore, adding features in this manner is a way + to enforce specific features are present and enabled + without needing to do a full audit of any other layer's additions + to the <filename>SRC_URI</filename> statement. + </para> + + <para> + You add a kernel feature by providing the feature as part of the + <filename>KERNEL_FEATURES</filename> variable and by providing the + path to the feature's <filename>.scc</filename> file, which is + relative to the root of the kernel Metadata. + The OpenEmbedded build system searches all forms of kernel + Metadata on the <filename>SRC_URI</filename> statement regardless + of whether the Metadata is in the "kernel-cache", system kernel + Metadata, or a recipe-space Metadata (i.e. part of the kernel + recipe). + See the + "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>" + section for additional information. + </para> + + <para> + When you specify the feature's <filename>.scc</filename> file + on the <filename>SRC_URI</filename> statement, the OpenEmbedded + build system adds the directory of that + <filename>.scc</filename> file along with all its subdirectories + to the kernel feature search path. + Because subdirectories are searched, you can reference a single + <filename>.scc</filename> file in the + <filename>SRC_URI</filename> statement to reference multiple kernel + features. + </para> + + <para> + Consider the following example that adds the "test.scc" feature + to the build. + <orderedlist> + <listitem><para> + <emphasis>Create the Feature File:</emphasis> + Create a <filename>.scc</filename> file and locate it + just as you would any other patch file, + <filename>.cfg</filename> file, or fetcher item + you specify in the <filename>SRC_URI</filename> + statement. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + You must add the directory of the + <filename>.scc</filename> file to the fetcher's + search path in the same manner as you would + add a <filename>.patch</filename> file. + </para></listitem> + <listitem><para> + You can create additional + <filename>.scc</filename> files beneath the + directory that contains the file you are + adding. + All subdirectories are searched during the + build as potential feature directories. + </para></listitem> + </itemizedlist> + </note> + Continuing with the example, suppose the "test.scc" + feature you are adding has a + <filename>test.scc</filename> file in the following + directory: + <literallayout class='monospaced'> + <replaceable>my_recipe</replaceable> + | + +-linux-yocto + | + +-test.cfg + +-test.scc + </literallayout> + In this example, the <filename>linux-yocto</filename> + directory has both the feature + <filename>test.scc</filename> file and a similarly + named configuration fragment file + <filename>test.cfg</filename>. + </para></listitem> + <listitem><para> + <emphasis>Add the Feature File to <filename>SRC_URI</filename>:</emphasis> + Add the <filename>.scc</filename> file to the + recipe's <filename>SRC_URI</filename> statement: + <literallayout class='monospaced'> + SRC_URI_append = " file://test.scc" + </literallayout> + The leading space before the path is important as the + path is appended to the existing path. + </para></listitem> + <listitem><para> + <emphasis>Specify the Feature as a Kernel Feature:</emphasis> + Use the <filename>KERNEL_FEATURES</filename> statement + to specify the feature as a kernel feature: + <literallayout class='monospaced'> + KERNEL_FEATURES_append = " test.scc" + </literallayout> + The OpenEmbedded build system processes the kernel feature + when it builds the kernel. + <note> + If other features are contained below "test.scc", + then their directories are relative to the directory + containing the <filename>test.scc</filename> file. + </note> + </para></listitem> + </orderedlist> + </para> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |