1326 lines
67 KiB
XML
1326 lines
67 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
|
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
|
|
|
<chapter id='kernel-dev-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 a layer, modifying an existing recipe,
|
|
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
|
|
1.2.2 Release and forward.
|
|
</note>
|
|
</para>
|
|
|
|
<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_DEV_URL;#bitbake-term'>BitBake</ulink>
|
|
append files
|
|
(<filename>.bbappend</filename>) and provides a convenient
|
|
mechanism to create your own recipe files
|
|
(<filename>.bb</filename>).
|
|
For details on how to create and work 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 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>yocto-layer create</filename>
|
|
script, which simplifies creating a new layer.
|
|
See the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
|
|
section in the Yocto Project Development Manual for more
|
|
information.
|
|
</note>
|
|
</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_DEV_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 some general resources.
|
|
You can also see the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section
|
|
of the Yocto Project Development Manual for a detailed
|
|
example.
|
|
</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.4.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.4.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.4.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"
|
|
KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
|
|
|
|
SRCREV_machine_genericx86 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
|
|
SRCREV_machine_genericx86-64 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
|
|
SRCREV_machine_edgerouter ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
|
|
SRCREV_machine_beaglebone ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
|
|
SRCREV_machine_mpc8315e-rdb ?= "06c0dbdcba374ca7f92a53d69292d6bb7bc9b0f3"
|
|
|
|
COMPATIBLE_MACHINE_genericx86 = "genericx86"
|
|
COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
|
|
COMPATIBLE_MACHINE_edgerouter = "edgerouter"
|
|
COMPATIBLE_MACHINE_beaglebone = "beaglebone"
|
|
COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
|
|
|
|
LINUX_VERSION_genericx86 = "4.4.41"
|
|
LINUX_VERSION_genericx86-64 = "4.4.41"
|
|
LINUX_VERSION_edgerouter = "4.4.53"
|
|
LINUX_VERSION_beaglebone = "4.4.53"
|
|
LINUX_VERSION_mpc8315e-rdb = "4.4.53"
|
|
</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_DEV_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, see the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
|
|
section in the Yocto Project Development Manual.
|
|
</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
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
|
|
section in the Yocto Project Development Manual.
|
|
</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,
|
|
edit the recipe that builds your kernel so that it has the
|
|
following command form:
|
|
<literallayout class='monospaced'>
|
|
KBUILD_DEFCONFIG_KMACHINE ?= <replaceable>defconfig_file</replaceable>
|
|
</literallayout>
|
|
You need to append the variable with
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
|
|
and then supply the path to your "in-tree"
|
|
<filename>defconfig</filename> file.
|
|
</para>
|
|
|
|
<para>
|
|
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-an-iterative-development-process'>
|
|
<title>Using an Iterative Development Process</title>
|
|
|
|
<para>
|
|
If you do not have existing patches or configuration files,
|
|
you can iteratively generate them from within the BitBake build
|
|
environment as described within this section.
|
|
During an iterative workflow, running a previously completed BitBake
|
|
task causes BitBake to invalidate the tasks that follow the
|
|
completed task in the build sequence.
|
|
Invalidated tasks rebuild the next time you run the build using
|
|
BitBake.
|
|
</para>
|
|
|
|
<para>
|
|
As you read this section, be sure to substitute the name
|
|
of your Linux kernel recipe for the term
|
|
"linux-yocto".
|
|
</para>
|
|
|
|
<section id='tip-dirty-string'>
|
|
<title>"-dirty" String</title>
|
|
|
|
<!--
|
|
<para>
|
|
<emphasis>AR - Darren Hart:</emphasis> This section
|
|
originated from the old Yocto Project Kernel Architecture
|
|
and Use Manual.
|
|
It was decided we need to put it in this section here.
|
|
Darren needs to figure out where we want it and what part
|
|
of it we want (all, revision???)
|
|
</para>
|
|
-->
|
|
|
|
<para>
|
|
If kernel images are being built with "-dirty" on the
|
|
end of the version string, this simply means that
|
|
modifications in the source directory have not been committed.
|
|
<literallayout class='monospaced'>
|
|
$ git status
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
You can use the above Git command to report modified,
|
|
removed, or added files.
|
|
You should commit those changes to the tree regardless of
|
|
whether they will be saved, exported, or used.
|
|
Once you commit the changes, you need to rebuild the kernel.
|
|
</para>
|
|
|
|
<para>
|
|
To force a pickup and commit of all such pending changes,
|
|
enter the following:
|
|
<literallayout class='monospaced'>
|
|
$ git add .
|
|
$ git commit -s -a -m "getting rid of -dirty"
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
Next, rebuild the kernel.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='generating-configuration-files'>
|
|
<title>Generating Configuration Files</title>
|
|
|
|
<para>
|
|
You can manipulate the <filename>.config</filename> file
|
|
used to build a linux-yocto recipe with the
|
|
<filename>menuconfig</filename> command as follows:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake linux-yocto -c menuconfig
|
|
</literallayout>
|
|
This command starts the Linux kernel configuration tool,
|
|
which allows you to prepare a new
|
|
<filename>.config</filename> file for the build.
|
|
When you exit the tool, be sure to save your changes
|
|
at the prompt.
|
|
</para>
|
|
|
|
<para>
|
|
The resulting <filename>.config</filename> file is
|
|
located in the build directory,
|
|
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
|
|
which expands to
|
|
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build</filename>.
|
|
You can use the entire <filename>.config</filename> file as the
|
|
<filename>defconfig</filename> file as described in the
|
|
"<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
|
|
For more information on the <filename>.config</filename> file,
|
|
see the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
|
|
section in the Yocto Project Development Manual.
|
|
<note>
|
|
You can determine what a variable expands to by looking
|
|
at the output of the <filename>bitbake -e</filename>
|
|
command:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake -e virtual/kernel
|
|
</literallayout>
|
|
Search the output for the variable in which you are
|
|
interested to see exactly how it is expanded and used.
|
|
</note>
|
|
</para>
|
|
|
|
<para>
|
|
A better 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>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 will be creating a
|
|
<filename>.config</filename> file from a known state.
|
|
Because situations exist where your build state might
|
|
become unknown, it is best to run the previous
|
|
command prior to starting up
|
|
<filename>menuconfig</filename>.
|
|
</para></listitem>
|
|
<listitem><para>Run the <filename>menuconfig</filename>
|
|
command:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake linux-yocto -c menuconfig
|
|
</literallayout></para></listitem>
|
|
<listitem><para>Run the <filename>diffconfig</filename>
|
|
command to prepare a configuration fragment.
|
|
The resulting file <filename>fragment.cfg</filename>
|
|
will be 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 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>
|
|
The kernel tools also provide configuration validation.
|
|
You can use these tools to produce 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.
|
|
Here is an example with some sample output of the command
|
|
that runs these tools:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake linux-yocto -c kernel_configcheck -f
|
|
|
|
...
|
|
|
|
NOTE: validating kernel configuration
|
|
This BSP sets 3 invalid/obsolete kernel options.
|
|
These config options are not offered anywhere within this kernel.
|
|
The full list can be found in your kernel src dir at:
|
|
meta/cfg/standard/mybsp/invalid.cfg
|
|
|
|
This BSP sets 21 kernel options that are possibly non-hardware related.
|
|
The full list can be found in your kernel src dir at:
|
|
meta/cfg/standard/mybsp/specified_non_hdw.cfg
|
|
|
|
WARNING: There were 2 hardware options requested that do not
|
|
have a corresponding value present in the final ".config" file.
|
|
This probably means you are not getting the config you wanted.
|
|
The full list can be found in your kernel src dir at:
|
|
meta/cfg/standard/mybsp/mismatch.cfg
|
|
</literallayout>
|
|
</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
|
|
<filename>kernel_configme</filename> and
|
|
<filename>kernel_configcheck</filename> commands until
|
|
they produce no warnings.
|
|
</para>
|
|
|
|
<para>
|
|
For more information on how to use the
|
|
<filename>menuconfig</filename> tool, see the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
|
|
section in the Yocto Project Development Manual.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='modifying-source-code'>
|
|
<title>Modifying Source Code</title>
|
|
|
|
<para>
|
|
You can experiment with source code changes and create a
|
|
simple patch without leaving the BitBake environment.
|
|
To get started, be sure to complete a build at
|
|
least through the kernel configuration task:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake linux-yocto -c kernel_configme -f
|
|
</literallayout>
|
|
Taking this step ensures you have the sources prepared
|
|
and the configuration completed.
|
|
You can find the sources in the build directory within the
|
|
<filename>source/</filename> directory, which is a symlink
|
|
(i.e. <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}/source</filename>).
|
|
The <filename>source/</filename> directory expands to
|
|
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build/source</filename>.
|
|
The directory pointed to by the
|
|
<filename>source/</filename> symlink is also known as
|
|
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink><filename>}</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
You can edit the sources as you would any other Linux source
|
|
tree.
|
|
However, keep in mind that you will lose changes if you
|
|
trigger the
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
|
|
task for the recipe.
|
|
You can avoid triggering this task by not using BitBake to
|
|
run the
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>cleanall</filename></ulink>,
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>cleansstate</filename></ulink>,
|
|
or forced
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>fetch</filename></ulink>
|
|
commands.
|
|
Also, do not modify the recipe itself while working
|
|
with temporary changes or BitBake might run the
|
|
<filename>fetch</filename> command depending on the
|
|
changes to the recipe.
|
|
</para>
|
|
|
|
<para>
|
|
To test your temporary changes, instruct BitBake to run the
|
|
<filename>compile</filename> again.
|
|
The <filename>-f</filename> option forces the command to run
|
|
even though BitBake might think it has already done so:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake linux-yocto -c compile -f
|
|
</literallayout>
|
|
If the compile fails, you can update the sources and repeat
|
|
the <filename>compile</filename>.
|
|
Once compilation is successful, you can inspect and test
|
|
the resulting build (i.e. kernel, modules, and so forth) from
|
|
the following build directory:
|
|
<literallayout class='monospaced'>
|
|
${WORKDIR}/linux-${PACKAGE_ARCH}-${LINUX_KERNEL_TYPE}-build
|
|
</literallayout>
|
|
Alternatively, you can run the <filename>deploy</filename>
|
|
command to place the kernel image in the
|
|
<filename>tmp/deploy/images</filename> directory:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake linux-yocto -c deploy
|
|
</literallayout>
|
|
And, of course, you can perform the remaining installation and
|
|
packaging steps by issuing:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake linux-yocto
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
For rapid iterative development, the edit-compile-repeat loop
|
|
described in this section is preferable to rebuilding the
|
|
entire recipe because the installation and packaging tasks
|
|
are very time consuming.
|
|
</para>
|
|
|
|
<para>
|
|
Once you are satisfied with your source code modifications,
|
|
you can make them permanent by generating patches and
|
|
applying them to the
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
|
statement as described in the
|
|
"<link linkend='applying-patches'>Applying Patches</link>"
|
|
section.
|
|
If you are not familiar with generating patches, refer to the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
|
|
section in the Yocto Project Development Manual.
|
|
</para>
|
|
</section>
|
|
</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_DEV_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>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 Linux kernel you
|
|
are using (e.g.
|
|
<filename>linux-yocto-myproject_3.19.bb</filename>,
|
|
where "3.19" is the base version of the Linux kernel
|
|
with which you would be working).</para></listitem>
|
|
<listitem><para>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>Make sure you have either a
|
|
<filename>defconfig</filename> file or configuration
|
|
fragment files.
|
|
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> to the
|
|
<filename>files</filename> directory 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.
|
|
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>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.
|
|
"3.19").</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>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='http://git.yoctoproject.org/cgit.cgi'></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.
|
|
See the
|
|
"<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>"
|
|
section for additional information.
|
|
</para>
|
|
|
|
<para>
|
|
When you specify the feature's <filename>.scc</filename> file
|
|
on the <filename>SRC_URI</filename> statement, the OpenEmbedded
|
|
build system adds the directory of that
|
|
<filename>.scc</filename> file along with all its subdirectories
|
|
to the kernel feature search path.
|
|
Because subdirectories are searched, you can reference a single
|
|
<filename>.scc</filename> file in the
|
|
<filename>SRC_URI</filename> statement to reference multiple kernel
|
|
features.
|
|
</para>
|
|
|
|
<para>
|
|
Consider the following example that adds the "test.scc" feature
|
|
to the build.
|
|
<orderedlist>
|
|
<listitem><para>
|
|
Create a <filename>.scc</filename> file and locate it
|
|
just as you would any other patch file,
|
|
<filename>.cfg</filename> file, or fetcher item
|
|
you specify in the <filename>SRC_URI</filename>
|
|
statement.
|
|
<note><title>Notes</title>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
You must add the directory of the
|
|
<filename>.scc</filename> file to the fetcher's
|
|
search path in the same manner as you would
|
|
add a <filename>.patch</filename> file.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
You can create additional
|
|
<filename>.scc</filename> files beneath the
|
|
directory that contains the file you are
|
|
adding.
|
|
All subdirectories are searched during the
|
|
build as potential feature directories.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</note>
|
|
Continuing with the example, suppose the "test.scc"
|
|
feature you are adding has a
|
|
<filename>test.scc</filename> file in the following
|
|
directory:
|
|
<literallayout class='monospaced'>
|
|
<replaceable>my_recipe</replaceable>
|
|
|
|
|
+-linux-yocto
|
|
|
|
|
+-test.cfg
|
|
+-test.scc
|
|
</literallayout>
|
|
In this example, the <filename>linux-yocto</filename>
|
|
directory has both the feature
|
|
<filename>test.scc</filename> file and a similarly
|
|
named configuration fragment file
|
|
<filename>test.cfg</filename>.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Add the <filename>.scc</filename> file to the
|
|
recipe's <filename>SRC_URI</filename> statement:
|
|
<literallayout class='monospaced'>
|
|
SRC_URI_append = " file://test.scc"
|
|
</literallayout>
|
|
The leading space before the path is important as the
|
|
path is appended to the existing path.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Specify the feature as a kernel feature:
|
|
<literallayout class='monospaced'>
|
|
KERNEL_FEATURES_append = " test.scc"
|
|
</literallayout>
|
|
The OpenEmbedded build system processes the kernel feature
|
|
when it builds the kernel.
|
|
<note>
|
|
If other features are contained below "test.scc",
|
|
then their directories are relative to the directory
|
|
containing the <filename>test.scc</filename> file.
|
|
</note>
|
|
</para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
<!--
|
|
vim: expandtab tw=80 ts=4
|
|
-->
|