diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-common.xml')
| -rw-r--r-- | documentation/kernel-dev/kernel-dev-common.xml | 2730 |
1 files changed, 0 insertions, 2730 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml deleted file mode 100644 index 8e8a6dbed4..0000000000 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ /dev/null @@ -1,2730 +0,0 @@ -<!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 ---> |