sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

kernel-dev: Rough text in for new chapter. Makefile edited. 

The raw text for the second chapter is in by section.  This has
no formatting whatsoever.  I also edited the Makefile so that
the new "Common Tasks" chapter would make as part of the manual.

(From yocto-docs rev: 68bcc1e977fbdd7b1a4b448171d1149edc72db51)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2012-12-18 10:32:14 -06:00 committed by Richard Purdie
parent 494e9ef06b
commit 974ef52d56
2 changed files with 348 additions and 356 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

702
documentation/kernel-dev/kernel-dev-common.xml
View File

@ -2,388 +2,380 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<chapter id='kernel-concepts'>
<chapter id='kernel-dev-common'>
<title>Yocto Project Kernel Concepts</title>
<title>Common Tasks</title>
<section id='concepts-org'>
<title>Introduction</title>
<para>
This chapter provides conceptual information about the kernel:
<itemizedlist>
<listitem><para>Kernel Goals</para></listitem>
<listitem><para>Kernel Development and Maintenance Overview</para></listitem>
<listitem><para>Kernel Architecture</para></listitem>
<listitem><para>Kernel Tools</para></listitem>
</itemizedlist>
</para>
</section>
<para>
This chapter describes common tasks you need to do when working
on the Yocto Project Linux kernel.
</para>
<section id='preparing-a-layer'>
<title>Preparing a Layer</title>
<section id='kernel-goals'>
<title>Kernel Goals</title>
<para>
The complexity of embedded kernel design has increased dramatically.
Whether it is managing multiple implementations of a particular feature or tuning and
optimizing board specific features, both flexibility and maintainability are key concerns.
The Linux kernels available through the Yocto Project are presented with the embedded
developer's needs in mind and have evolved to assist in these key concerns.
For example, prior methods such as applying hundreds of patches to an extracted
tarball have been replaced with proven techniques that allow easy inspection,
bisection and analysis of changes.
Application of these techniques also creates a platform for performing integration and
collaboration with the thousands of upstream development projects.
</para>
<para>
With all these considerations in mind, the Yocto Project's kernel and development team
strives to attain these goals:
<itemizedlist>
<listitem><para>Allow the end user to leverage community best practices to seamlessly
manage the development, build and debug cycles.</para></listitem>
<listitem><para>Create a platform for performing integration and collaboration with the
thousands of upstream development projects that exist.</para></listitem>
<listitem><para>Provide mechanisms that support many different work flows, front-ends and
management techniques.</para></listitem>
<listitem><para>Deliver the most up-to-date kernel possible while still ensuring that
the baseline kernel is the most stable official release.</para></listitem>
<listitem><para>Include major technological features as part of the Yocto Project's
upward revision strategy.</para></listitem>
<listitem><para>Present a kernel Git repository that, similar to the upstream
<filename>kernel.org</filename> tree,
has a clear and continuous history.</para></listitem>
<listitem><para>Deliver a key set of supported kernel types, where each type is tailored
to meet a specific use (e.g. networking, consumer, devices, and so forth).</para></listitem>
<listitem><para>Employ a Git branching strategy that, from a developer's point of view,
results in a linear path from the baseline <filename>kernel.org</filename>,
through a select group of features and
ends with their BSP-specific commits.</para></listitem>
</itemizedlist>
Customizing recipes is best done in a layer with bbappend files. Layers also
provide a convenient mechanism to create your own recipes. This guide assumes
you will be working from within a layer independent from those released with the
Yocto Project. For details on how to create and work with layers, refer to
section 5.1 Understanding and Creating Layers in the Yocto Project Development
Manual.
(Kernel specific directions in 5.7.4)
</para>
</section>
<section id='kernel-big-picture'>
<title>Yocto Project Kernel Development and Maintenance Overview</title>
<para>
Kernels available through the Yocto Project, like other kernels, are based off the Linux
kernel releases from <ulink url='http://www.kernel.org'></ulink>.
At the beginning of a major development cycle, the Yocto Project team
chooses its kernel based on factors such as release timing, the anticipated release
timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
feature requirements.
Typically, the kernel chosen is in the
final stages of development by the community.
In other words, the kernel is in the release
candidate or "rc" phase and not yet a final release.
But, by being in the final stages of external development, the team knows that the
<filename>kernel.org</filename> final release will clearly be within the early stages of
the Yocto Project development window.
</para>
<para>
This balance allows the team to deliver the most up-to-date kernel
possible, while still ensuring that the team has a stable official release for
the baseline Linux kernel version.
</para>
<para>
The ultimate source for kernels available through the Yocto Project are released kernels
from <filename>kernel.org</filename>.
In addition to a foundational kernel from <filename>kernel.org</filename>, the
kernels available contain a mix of important new mainline
developments, non-mainline developments (when there is no alternative),
Board Support Package (BSP) developments,
and custom features.
These additions result in a commercially released Yocto Project Linux kernel that caters
to specific embedded designer needs for targeted hardware.
</para>
<para>
Once a kernel is officially released, the Yocto Project team goes into
their next development cycle, or upward revision (uprev) cycle, while still
continuing maintenance on the released kernel.
It is important to note that the most sustainable and stable way
to include feature development upstream is through a kernel uprev process.
Back-porting hundreds of individual fixes and minor features from various
kernel versions is not sustainable and can easily compromise quality.
</para>
<para>
During the uprev cycle, the Yocto Project team uses an ongoing analysis of
kernel development, BSP support, and release timing to select the best
possible <filename>kernel.org</filename> version.
The team continually monitors community kernel
development to look for significant features of interest.
The team does consider back-porting large features if they have a significant advantage.
User or community demand can also trigger a back-port or creation of new
functionality in the Yocto Project baseline kernel during the uprev cycle.
</para>
<para>
Generally speaking, every new kernel both adds features and introduces new bugs.
These consequences are the basic properties of upstream kernel development and are
managed by the Yocto Project team's kernel strategy.
It is the Yocto Project team's policy to not back-port minor features to the released kernel.
They only consider back-porting significant technological jumps - and, that is done
after a complete gap analysis.
The reason for this policy is that back-porting any small to medium sized change
from an evolving kernel can easily create mismatches, incompatibilities and very
subtle errors.
</para>
<para>
These policies result in both a stable and a cutting
edge kernel that mixes forward ports of existing features and significant and critical
new functionality.
Forward porting functionality in the kernels available through the Yocto Project kernel
can be thought of as a "micro uprev."
The many “micro uprevs” produce a kernel version with a mix of
important new mainline, non-mainline, BSP developments and feature integrations.
This kernel gives insight into new features and allows focused
amounts of testing to be done on the kernel, which prevents
surprises when selecting the next major uprev.
The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
feature and BSP development.
</para>
</section>
<section id='modifying-an-existing-recipe'>
<title>Modifying an Existing Recipe</title>
<section id='kernel-architecture'>
<title>Kernel Architecture</title>
<para>
This section describes the architecture of the kernels available through the
Yocto Project and provides information
on the mechanisms used to achieve that architecture.
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 to choose from. To get started, prepare a layer and a bbappend
file corresponding to the recipe you wish to modify.
See [New example in Dev Manual] for instructions to create a minimal layer.
The bbappend will typical be located at the following location relative to the
layer (if modifying the linux-yocto_3.4.bb recipe):
recipes-kernel/linux/linux-yocto_3.4.bbappend
And should contain the following text initially:
FILESEXTRAPATHS := "${THISDIR}/${PN}"
The ${PN} will expand to "linux-yocto" in this example. Any new files added to
modify the recipe should then be added to the following path within the layer:
recipes-kernel/linux/linux-yocto/
NOTE: If you are working on a new machine BSP, be sure to refer to the Yocto
Project Board Support Package Developer's Guide.
</para>
<section id='architecture-overview'>
<title>Overview</title>
<section id='applying-patches'>
<title>Applying Patches</title>
<para>
As mentioned earlier, a key goal of the Yocto Project is to present the
developer with
a kernel that has a clear and continuous history that is visible to the user.
The architecture and mechanisms used achieve that goal in a manner similar to the
upstream <filename>kernel.org</filename>.
</para>
<para>
You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
added features logically structured on top of the baseline.
The features are tagged and organized by way of a branching strategy implemented by the
source code manager (SCM) Git.
For information on Git as applied to the Yocto Project, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
Yocto Project Development Manual.
</para>
<para>
The result is that the user has the ability to see the added features and
the commits that make up those features.
In addition to being able to see added features, the user can also view the history of what
made up the baseline kernel.
</para>
<para>
The following illustration shows the conceptual Yocto Project kernel.
</para>
<para>
<imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
</para>
<para>
In the illustration, the "Kernel.org Branch Point"
marks the specific spot (or release) from
which the Yocto Project kernel is created.
From this point "up" in the tree, features and differences are organized and tagged.
</para>
<para>
The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
type and BSP that is organized further up the tree.
Placing these common features in the
tree this way means features don't have to be duplicated along individual branches of the
structure.
</para>
<para>
From the Yocto Project Baseline Kernel, branch points represent specific functionality
for individual BSPs as well as real-time kernels.
The illustration represents this through three BSP-specific branches and a real-time
kernel branch.
Each branch represents some unique functionality for the BSP or a real-time kernel.
</para>
<para>
In this example structure, the real-time kernel branch has common features for all
real-time kernels and contains
more branches for individual BSP-specific real-time kernels.
The illustration shows three branches as an example.
Each branch points the way to specific, unique features for a respective real-time
kernel as they apply to a given BSP.
</para>
<para>
The resulting tree structure presents a clear path of markers (or branches) to the
developer that, for all practical purposes, is the kernel needed for any given set
of requirements.
If you have a patch, or a small series of patches, 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 FILESEXTRAPATHS in the bbappend file as
described in 2.2 and then reference them in the SRC_URI.
For example, you can apply a three patch series by adding the following lines to
your linux-yocto bbappend file in your layer:
SRC_URI += "file://0001-first-change.patch"
SRC_URI += "file://0002-first-change.patch"
SRC_URI += "file://0003-first-change.patch"
At the next build, bitbake will detect the change in the recipe and fetch and
apply the patches before rebuilding the Linux kernel.
</para>
</section>
<section id='branching-and-workflow'>
<title>Branching Strategy and Workflow</title>
<para>
The Yocto Project team creates kernel branches at points where functionality is
no longer shared and thus, needs to be isolated.
For example, board-specific incompatibilities would require different functionality
and would require a branch to separate the features.
Likewise, for specific kernel features, the same branching strategy is used.
</para>
<para>
This branching strategy results in a tree that has features organized to be specific
for particular functionality, single kernel types, or a subset of kernel types.
This strategy also results in not having to store the same feature twice
internally in the tree.
Rather, the kernel team stores the unique differences required to apply the
feature onto the kernel type in question.
<note>
The Yocto Project team strives to place features in the tree such that they can be
shared by all boards and kernel types where possible.
However, during development cycles or when large features are merged,
the team cannot always follow this practice.
In those cases, the team uses isolated branches to merge features.
</note>
</para>
<para>
BSP-specific code additions are handled in a similar manner to kernel-specific additions.
Some BSPs only make sense given certain kernel types.
So, for these types, the team creates branches off the end of that kernel type for all
of the BSPs that are supported on that kernel type.
From the perspective of the tools that create the BSP branch, the BSP is really no
different than a feature.
Consequently, the same branching strategy applies to BSPs as it does to features.
So again, rather than store the BSP twice, the team only stores the unique
differences for the BSP across the supported multiple kernels.
</para>
<para>
While this strategy can result in a tree with a significant number of branches, it is
important to realize that from the developer's point of view, there is a linear
path that travels from the baseline <filename>kernel.org</filename>, through a select
group of features and ends with their BSP-specific commits.
In other words, the divisions of the kernel are transparent and are not relevant
to the developer on a day-to-day basis.
From the developer's perspective, this path is the "master" branch.
The developer does not need to be aware of the existence of any other branches at all.
Of course, there is value in the existence of these branches
in the tree, should a person decide to explore them.
For example, a comparison between two BSPs at either the commit level or at the line-by-line
code <filename>diff</filename> level is now a trivial operation.
</para>
<para>
Working with the kernel as a structured tree follows recognized community best practices.
In particular, the kernel as shipped with the product, should be
considered an "upstream source" and viewed as a series of
historical and documented modifications (commits).
These modifications represent the development and stabilization done
by the Yocto Project kernel development team.
</para>
<para>
Because commits only change at significant release points in the product life cycle,
developers can work on a branch created
from the last relevant commit in the shipped Yocto Project kernel.
As mentioned previously, the structure is transparent to the developer
because the kernel tree is left in this state after cloning and building the kernel.
</para>
</section>
<section id='changing-the-configuration'>
<title>Changing the Configuration</title>
<section id='source-code-manager-git'>
<title>Source Code Manager - Git</title>
<para>
The Source Code Manager (SCM) is Git.
This SCM is the obvious mechanism for meeting the previously mentioned goals.
Not only is it the SCM for <filename>kernel.org</filename> but,
Git continues to grow in popularity and supports many different work flows,
front-ends and management techniques.
</para>
<para>
You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
You can also get an introduction to Git as it applies to the Yocto Project in the
"<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
section in the Yocto Project Development Manual.
These referenced sections overview Git and describe a minimal set of
commands that allows you to be functional using Git.
<note>
You can use as much, or as little, of what Git has to offer to accomplish what
you need for your project.
You do not have to be a "Git Master" in order to use it with the Yocto Project.
</note>
Making wholesale or incremental changes to the Linux kernel config can be made
by including a defconfig or configuration fragments in the SRC_URI.
If you have a complete Linux kernel .config file you want to use, copy it as
"defconfig" to the ${FILES} directory and add the following line to your
linux-yocto bbappend file in your layer:
SRC_URI += "file://defconfig"
Generally speaking, the preferred approach is to determine the incremental
change you want to make and add that as a fragment. For example, if you wanted
to add support for a basic serial console, create a file named "8250.cfg" in the
${FILES} directory with the following content (without indentation):
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
Then include this configuration fragment in the SRC_URI:
SRC_URI += "file://8250.cfg"
At the next build, bitbake will detect the change in the recipe and fetch and
apply the new configuration before rebuilding the Linux kernel.
</para>
</section>
</section>
<section id='kernel-configuration'>
<title>Kernel Configuration</title>
<para>
Kernel configuration, along with kernel features, defines how a kernel
image is built for the Yocto Project.
Through configuration settings, you can customize a Yocto Project kernel to be
specific to particular hardware.
For example, you can specify sound support or networking support.
This section describes basic concepts behind Kernel configuration within the
Yocto Project and references you to other areas for specific configuration
applications.
</para>
<section id='iterative-development'>
<title>Iterative Development</title>
<para>
Conceptually, configuration of a Yocto Project kernel occurs similarly to that needed for any
Linux kernel.
The build process for a Yocto Project kernel uses a <filename>.config</filename> file, which
is created through the Linux Kernel Configuration (LKC) tool.
You can directly set various configurations in the
<filename>.config</filename> file by using the <filename>menuconfig</filename>
tool as built by BitBake.
You can also define configurations in the file by using configuration fragments.
<note>
It is not recommended that you edit the <filename>.config</filename> file directly.
</note>
Here are some brief descriptions of the ways you can affect the
<filename>.config</filename> file:
<itemizedlist>
<listitem><para><emphasis>The <filename>menuconfig</filename> Tool:</emphasis>
One of many front-ends that allows you to define kernel configurations.
Some others are <filename>make config</filename>,
<filename>make nconfig</filename>, and <filename>make gconfig</filename>.
In the Yocto Project environment, you must use BitBake to build the
<filename>menuconfig</filename> tool before you can use it to define
configurations:
<literallayout class='monospaced'>
$ bitbake linux-yocto -c menuconfig
</literallayout>
After the tool is built, you can interact with it normally.
You can see how <filename>menuconfig</filename> is used to change a simple
kernel configuration in the
"<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
section of the Yocto Project Development Manual.
For general information on <filename>menuconfig</filename>, see
<ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
</para></listitem>
<listitem><para><emphasis>Configuration Fragments:</emphasis> A file with a
list of kernel options just as they would appear syntactically in the
<filename>.config</filename> file.
Configuration fragments are typically logical groupings and are assembled
by the OpenEmbedded build system to produce input used by the LKC
that ultimately generates the <filename>.config</filename> file.</para>
<para>The
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink></filename>
variable can be used to list configuration fragments.
For further discussion on applying configuration fragments, see the
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-kernel'>Linux Kernel Configuration</ulink>"
section in the Yocto Project Board Support Package (BSP) Guide.
</para></listitem>
</itemizedlist>
If you do not have existing patches or configuration files, you can easily
generate them from within the bitbake build environment, as will be described
below. As you do, running previously completed bitbake tasks will cause bitbake
to invalidate the tasks that follow them in the build sequence, causing them to
rebuild at the next invocation of the build. Throughout this section, be sure to
substitute "linux-yocto" with the name of the Linux kernel recipe you are
working with.
</para>
<section id='generating-configuration-files'>
<title>Generating Configuration Files</title>
<para>
You can manipulate the config used to build a linux-yocto recipe with the
"menuconfig" command.
$ bitbake linux-yocto -c menuconfig
This will start the Linux kernel configuration tool, allowing you to prepare a
new .config for the build. When you exit, be sure to save the changes when
prompted. The resulting .config file will be located in the ${WORKDIR} under
the linux-${MACHINE}-${KTYPE}-build directory. You can use this in its entirety
as the defconfig file described in 2.2.2.
Better still, would be to use the "menuconfig" command and take the difference
of the new .config file with the previous one to generate a configuration
fragment. To do this, be sure to complete a build at least through the kernel
configuration task:
$ bitbake linux-yocto -c kernel_configme -f
Then make a copy of the .config file, calling it "config.orig", for example. Run
the "menuconfig" command as described above. Finally, prepare a configuration
fragment from the difference between the files. Ultimately you want a list of
Linux kernel CONFIG_ assignments, and not something in diff format. Something
like the following will do that automatically (but plan on reviewing the output
as you can usually remove some of the defaults):
$ diff -Nurp config.orig .config | sed -n "s/^\+//p" > frag.cfg
You can use the output as a configuration fragment described in 2.2.2. This
method can also be used to define a BSP configuration fragment (See 3.3.5).
The Yocto Project kernel tools provide some configuration validation tools which
will warn when a configuration you requested does not appear in the final
config, or when you override a policy configuration in a hardware configuration
fragment. You can run these tools with the following command:
$ 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 aren't getting the config you wanted.
The full list can be found in your kernel src dir at:
meta/cfg/standard/mybsp/mismatch.cfg
The various problems that you can encounter are described in the output along
with where to find the offending configuration items. You can use these logs to
adjust your configuration files and repeat the "kernel_configme" and
"kernel_configcheck" commands until no warnings are produced.
</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:
$ bitbake linux-yocto -c kernel_configme -f
This step will ensure you have the sources prepared and the configuration
completed. You will find the sources in the ${WORKDIR}/linux directory.
You can edit the sources as you would any other Linux source tree, but keep in
mind that your changes will be lost if you trigger the fetch task for the
recipe. Avoid this by not issuing the "cleanall" or "cleansstate", or forcing
the "fetch" command. Also be sure not to modify the recipe itself while working
with temporary changes or bitbake may run the fetch command (depending on the
changes to the recipe).
To test your temporary changes, instruct bitbake to run the compile again. The
-f option forces the command to run again even though bitbake may think it has
already done so:
$ bitbake linux-yocto -c compile -f
If the compile fails, you can update the sources and repeat the compile
command. Once it compiles successfully, you can inspect and test the resulting
build (kernel, modules, etc.) from the build directory at
${WORKDIR}/linux-${MACHINE}-${KTYPE}-build. Alternatively, you can run the
deploy command to place the kernel image in the tmp/deploy/images directory:
$ bitbake linux-yocto -c deploy
And of course, you can run through all the remaining installation and packaging
steps by issuing:
$ bitbake linux-yocto
For rapid iterative development, the edit-compile-repeat loop is preferable to
rebuilding the entire recipe as the installation and packaging tasks are very
time consuming.
Once you are happy with your modifications, you can make these permanent by
generating patches and applying them to the SRC_URI as described in section
2.2.1 Applying Patches. If you are not familiar with generating patches, refer
to the Yocto Project Development Manual, section 5.7.3 Creating the Patch.
</para>
</section>
</section>
<section id='working-with-your-own-sources'>
<title>Working With Your Own Sources</title>
<para>
If you find yourself unable to 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 while working with your own sources. You will not
be able to leverage the existing meta-data and stabilization work of the
linux-yocto sources, but you will be able to manage your own meta-data in the
same format as the linux-yocto sources which will facilitate converging with
linux-yocto on a future mutually-supported kernel version.
The linux-yocto-custom recipe, located in the poky repository at:
meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
is provided as an example recipe which uses kernel.org sources and the Yocto
Project Linux kernel tools for managing meta-data. To get started, copy this
recipe to your layer and provide it with a meaningful name, such as
linux-yocto-myproject_3.5.bb, where 3.5 is the base version of the Linux kernel
you will be working with. In the same directory, create a matching directory,
e.g. linux-yocto-myproject to store your patches and configuration files.
Edit the following variables in the recipe as appropriate for your project:
o SRC_URI
o LINUX_VERSION
o LINUX_VERSION_EXTENSION
o SRCREV
o PR
o PV
o COMPATIBLE_MACHINE
The SRC_URI should be a git repository, using one of the supported git fetcher
protocols (file, git, http, etc.). The skeleton recipe provides an example
SRC_URI as a syntax reference.
Set LINUX_VERSION to the Linux kernel version you are using, such as "3.6.3".
LINUX_VERSION_EXTENSION is used to define the Linux kernel CONFIG_LOCALVERSION
which will be compiled in to the resulting kernel and visible via the uname
command.
Set SRCREV to the commit ID you wish to build from.
Treat the PR as you would the PR of any other recipe. Increment it to indicate
to the build system that the recipe has changed.
The default PV assignment is typically adequate. It combines the LINUX_VERSION
with the SCM revision (from the SRCPV variable) and results in a string
something like:
"3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2"
While lengthy, this extra verbosity helps ensure you are building from the exact
sources you intend.
Finally, the default COMPATIBLE_MACHINE assignment for linux-yocto-custom is set
to a regular expression matching only the empty string, "(^$)". This will
trigger an explicit build failure. You must change it to match a list of the
machines supported by your new recipe, such as "(qemux86|qemux86-64)"
With that in place, you can continue to customize this recipe as you would the
existing linux-yocto recipes. See Section 2.2 Modifying an Existing Recipe for
details.
</para>
</section>
<section id='kernel-tools'>
<title>Kernel Tools</title>
<section id='incorporating-out-of-tree-modules'>
<title>Incorporating Out-of-Tree Modules</title>
<para>
Since most standard workflows involve moving forward with an existing tree by
continuing to add and alter the underlying baseline, the tools that manage
the Yocto Project's kernel construction are largely hidden from the developer to
present a simplified view of the kernel for ease of use.
</para>
<para>
Fundamentally, the kernel tools that manage and construct the
Yocto Project kernel accomplish the following:
<itemizedlist>
<listitem><para>Group patches into named, reusable features.</para></listitem>
<listitem><para>Allow top-down control of included features.</para></listitem>
<listitem><para>Bind kernel configurations to kernel patches and features.</para></listitem>
<listitem><para>Present a seamless Git repository that blends Yocto Project value
with the <filename>kernel.org</filename> history and development.</para></listitem>
</itemizedlist>
While it is always preferable to work with sources integrated into the Linux
kernel sources, if you have need of an external kernel module, the hello-mod
recipe is available as a template to create your own out-of-tree Linux kernel
module recipe. It is available in the poky repository at:
meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
To get started, copy this recipe to your layer and provide it with a meaningful name, such as
mymodule_1.0.bb. In the same directory, create a directory named "files" where
you can store any source files, patches, or other files necessary for building
the module which do not come with the sources. Finally, update the recipe as
appropriate for the module. Typically you will need to set the following
variables:
o DESCRIPTION
o LICENSE*
o SRC_URI
o PV
Depending on the build system used by the module sources, you may need to make
adjustments. For example, a typical module Makefile will look much like that
provided with hello-mod:
obj-m := hello.o
SRC := $(shell pwd)
all:
$(MAKE) -C $(KERNEL_SRC) M=$(SRC)
modules_install:
$(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
...
The important point to note here is the KERNEL_SRC variable. The module bbclass
class sets this, as well as KERNEL_PATH, to ${STAGING_KERNEL_DIR} with the
necessary Linux kernel build information to build modules. If your module
Makefile uses a different variable, you may want to override the do_compile()
step, or create a patch to the Makefile to work with the more typical KERNEL_SRC
or KERNEL_PATH variables.
After you have prepared the 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 as appropriate in your
machine config file:
MACHINE_ESSENTIAL_EXTRA_RDEPENDS
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS
MACHINE_EXTRA_RDEPENDS
MACHINE_EXTRA_RRECOMMENDS
As modules are often not required for boot and may be excluded from certain
build configurations, the following allows for the most flexibility:
MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
Where the value is derived by appending the module filename without the .ko
extension to the string "kernel-module-".
As it is an RRECOMMENDS (and not an RDEPENDS) variable, the build will not fail
if this module is not available to include in the image.
</para>
</section>
</chapter>

2
documentation/kernel-dev/kernel-dev.xml
View File

@ -59,9 +59,9 @@
<xi:include href="kernel-dev-intro.xml"/>
<!--
<xi:include href="kernel-dev-common.xml"/>
<!--
<xi:include href="kernel-dev-advanced.xml"/>
<xi:include href="kernel-dev-examples.xml"/>