2011-07-27 20:07:32 +00:00
|
|
|
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
2011-07-27 20:03:18 +00:00
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
|
2011-07-27 20:07:32 +00:00
|
|
|
<appendix id='dev-manual-kernel-appendix'>
|
2011-07-27 20:03:18 +00:00
|
|
|
|
2011-07-27 20:15:54 +00:00
|
|
|
<title>Kernel Modification Case</title>
|
2011-07-27 20:03:18 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Kernel modification involves changing or adding configurations to an existing kernel, or
|
|
|
|
adding recipes to the kernel that are needed to support specific hardware features.
|
|
|
|
The process is similar to creating a Board Support Package (BSP) except that it does not
|
|
|
|
involve a BSP layer.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This section presents a brief overview of the kernel structure and then provides a simple
|
|
|
|
example that shows how to modify the kernel.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='yocto-project-kernel'>
|
|
|
|
<title>Yocto Project Kernel Overview</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
When one thinks of the source files for a kernel they usually think of a fixed structure
|
|
|
|
of files that contain kernel patches.
|
|
|
|
The Yocto Project, however, employs mechanisims that in a sense result in a kernel source
|
|
|
|
generator.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto
|
|
|
|
Project files.
|
|
|
|
Git employs branching strategies that effectively produce a tree-like structure whose
|
|
|
|
branches represent diversions from more general code.
|
|
|
|
For example, suppose two kernels are basically identical with the exception of a couple
|
|
|
|
different features in each.
|
|
|
|
In the Yocto Project source repositories managed by Git a main branch can contain the
|
|
|
|
common or shared
|
|
|
|
parts of the kernel source and two branches that diverge from that common branch can
|
|
|
|
each contain the features specific to the respective kernel.
|
|
|
|
The result is a managed tree whose "leaves" represent the end of a specific path that yields
|
|
|
|
a set of kernel source files necessary for a specific piece of hardware and its features.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A big advantage to this scheme is the sharing of common features by keeping them in
|
|
|
|
"larger" branches that are further up the tree.
|
|
|
|
This practice eliminates redundant storage of similar features shared among kernels.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
When you build the kernel on your development system all files needed for the build
|
|
|
|
are taken from the Yocto Project source repositories pointed to by the
|
|
|
|
<filename>SRC_URI</filename> variable and gathered in a temporary work area
|
|
|
|
where they are subsequently used to create the unique kernel.
|
|
|
|
Thus, in a sense, the process constructs a local source tree specific to your
|
|
|
|
kernel to generate the new kernel image - a source generator if you will.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
|
|
|
|
see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
|
|
|
|
The Yocto Project Kernel Architecture and Use Manual</ulink>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You can find a web interface to the Yocto Project source repository at
|
|
|
|
<ulink url='http://git.yoctoproject.org/'></ulink>.
|
|
|
|
Within the interface you will see groups of related source code, each of which can
|
|
|
|
be cloned using Git to result in a working Git repository on your local system
|
|
|
|
(referred to as the "local Yocto Project files" in this manual).
|
|
|
|
The Yocto Project supports four types of kernels in its source repositories at
|
|
|
|
<ulink url='http://git.yoctoproject.org/'></ulink>:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
|
|
|
|
stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The current
|
|
|
|
Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
|
|
|
|
<listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
|
|
|
|
kernel based on the Linux 2.6.39-rc1 release.</para></listitem>
|
|
|
|
<listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on
|
|
|
|
minimal Linux mainline tracking.
|
|
|
|
[WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this
|
|
|
|
repository on their development system.]</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='modifying-a-kernel-example'>
|
|
|
|
<title>Modifying a Kernel Example</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This section presents a simple example that illustrates kernel modification
|
|
|
|
based on the <filename>linux-yocto-2.6.37</filename> kernel.
|
|
|
|
The example uses the audio and mixer capabilities supported by the
|
|
|
|
<ulink url='http://www.alsa-project.org/main/index.php/Main_Page'>Advanced Linux
|
|
|
|
Sound Architecture (ALSA) Project</ulink>.
|
|
|
|
As the example progresses you will see how to do the following:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Iteratively modify a base kernel locally.</para></listitem>
|
|
|
|
<listitem><para>Provide a recipe-based solution for your modified kernel.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para>Proved an "in-tree" solution for your modified kernel
|
|
|
|
(i.e. make the modifcations part of the Yocto Project).</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The example flows as follows:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Be sure your host development system is set up to support
|
|
|
|
development using the Yocto Project.
|
|
|
|
See
|
|
|
|
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
|
|
|
|
The Linux Distributions</ulink> section and
|
|
|
|
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
|
|
|
|
The Packages</ulink> section both
|
|
|
|
in the Yocto Project Quick Start for requirements.
|
|
|
|
You will also need a release of Yocto Project installed on the host.</para></listitem>
|
|
|
|
<listitem><para>Set up your environment for optimal local kernel development.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para>Create a layer to isolate your kernel work.</para></listitem>
|
|
|
|
<listitem><para>Next item.</para></listitem>
|
|
|
|
<listitem><para>Next item.</para></listitem>
|
|
|
|
<listitem><para>Next item.</para></listitem>
|
|
|
|
<listitem><para>Next item.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='setting-up-yocto-project-kernel-example'>
|
|
|
|
<title>Setting Up Yocto Project</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You need to have the Yocto Project files available on your host system.
|
|
|
|
The process is identical to that described in the
|
|
|
|
<xref linkend='getting-setup'>"Getting Setup"</xref> section earlier in this
|
|
|
|
manual.
|
|
|
|
Be sure to either set up a local Git repository for <filename>poky</filename>
|
|
|
|
or download and unpack the Yocto Project release tarball.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='create-a-git-repository-of-poky-extras'>
|
|
|
|
<title>Create a Git Repository of <filename>poky-extras</filename></title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Everytime you change a configuration or add a recipe to the kernel you need to
|
|
|
|
do a fetch from the Linux Yocto kernel source repositories.
|
|
|
|
This can get tedious and time consuming if you need to fetch the entire
|
|
|
|
Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change
|
|
|
|
to the kernel.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You can get around this by setting up a <filename>meta-kernel-dev</filename>
|
|
|
|
area on your local system.
|
|
|
|
This area contains "append" files for every kernel recipe, which also include
|
|
|
|
a <filename>KSRC</filename> statement that points to the kernel source files.
|
|
|
|
You can set up the environment so that the <filename>KSRC</filename> points to the
|
|
|
|
<filename>meta-kernel-dev</filename>, thus pulling source from a local area.
|
|
|
|
This setup can speed up development time.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To get set up you need to do two things: create a local Git repository
|
|
|
|
of the <filename>poky-extras</filename> repository, and create a bare clone of the
|
|
|
|
Linux Yocto 2.6.37 kernel Git repository.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The following transcript shows how to clone the <filename>poky-extras</filename>
|
|
|
|
Git repository into the current working directory, which is <filename>poky</filename>
|
|
|
|
in this example.
|
|
|
|
The command creates the repository in a directory named <filename>poky-extras</filename>:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ git clone git://git.yoctoproject.org/poky-extras
|
|
|
|
Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
|
|
|
|
remote: Counting objects: 532, done.
|
|
|
|
remote: Compressing objects: 100% (472/472), done.
|
|
|
|
remote: Total 532 (delta 138), reused 307 (delta 39)
|
|
|
|
Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done.
|
|
|
|
Resolving deltas: 100% (138/138), done.
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This transcript shows how to clone a bare Git repository of the Linux Yocto
|
|
|
|
2.6.37 kernel:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37
|
|
|
|
Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/
|
|
|
|
remote: Counting objects: 1886034, done.
|
|
|
|
remote: Compressing objects: 100% (314326/314326), done.
|
|
|
|
remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798)
|
|
|
|
Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done.
|
|
|
|
Resolving deltas: 100% (1570202/1570202), done.
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors
|
|
|
|
the upstream repository of the kernel.
|
|
|
|
You can effectively point to this local clone now during development to avoid
|
|
|
|
having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a
|
|
|
|
kernel change.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='create-a-layer-for-your-kernel-work'>
|
|
|
|
<title>Create a Layer for Your Kernel Work</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It is always good to isolate your work using your own layer.
|
|
|
|
Doing so allows you to experiment and easily start over should things go wrong.
|
|
|
|
This example uses a layer named <filename>meta-amixer</filename>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
When you set up a layer for kernel work you should follow the general layout
|
|
|
|
guidelines as described for BSP layers.
|
|
|
|
This layout is described in the
|
|
|
|
<ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
|
|
|
|
Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
|
|
|
|
Guide.
|
|
|
|
In the standard layout you will notice a suggested structure for recipes and
|
|
|
|
configuration information.
|
|
|
|
[WRITER'S NOTE: The <filename>meta-elc</filename> example uses an
|
|
|
|
<filename>images</filename> directory.
|
|
|
|
Currently, <filename>images</filename> is not part of the standard BSP layout.
|
|
|
|
I need to find out from Darren if this directory is required for kernel work.]
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
[WRITER'S NOTE: I need a paragraph here describing how to set up the layer.
|
|
|
|
I am not sure if you should copy an existing BSP layer and modify from there.
|
|
|
|
Or, if you should just look at a BSP layer and then create your own files.
|
|
|
|
Email to Darren on this but no answer yet.]
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='making-changes-to-your-kernel-layer'>
|
|
|
|
<title>Making Changes to Your Kernel Layer</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In the standard layer structure you have several areas that you need to examine or
|
|
|
|
modify.
|
|
|
|
For this example the layer contains four areas:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para><emphasis><filename>conf</filename></emphasis> - Contains the
|
|
|
|
<filename>layer.conf</filename> that identifies the location of the recipe files.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para><emphasis><filename>images</filename></emphasis> - Contains the
|
|
|
|
image recipe file.
|
|
|
|
This recipe includes the base image you will be using and specifies other
|
|
|
|
packages the image might need.</para></listitem>
|
|
|
|
<listitem><para><emphasis><filename>recipes-bsp</filename></emphasis> - Contains
|
|
|
|
recipes specific to the hardware for which you are developing the kernel.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para><emphasis><filename>recipes-kernel</filename></emphasis> - Contains the
|
|
|
|
"append" files that add information to the main recipe kernel.
|
|
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Let's take a look at the <filename>layer.conf</filename> in the
|
|
|
|
<filename>conf</filename> directory first.
|
|
|
|
This configuration file enables the Yocto Project build system to locate and
|
|
|
|
use the information in your new layer.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The variable <filename>BBPATH</filename> needs to include the path to your layer
|
|
|
|
as follows:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
BBPATH := "${BBPATH}:${LAYERDIR}"
|
|
|
|
</literallayout>
|
|
|
|
And, the variable <filename>BBFILES</filename> needs to be modified to include your
|
|
|
|
recipe and append files:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
BBFILES := "${BBFILES} ${LAYERDIR}/images/*.bb \
|
|
|
|
${LAYERDIR}/images/*.bbappend \
|
|
|
|
${LAYERDIR}/recipes-*/*/*.bb \
|
|
|
|
${LAYERDIR}/recipes-*/*/*.bbappend"
|
|
|
|
</literallayout>
|
|
|
|
Finally, you need to be sure to use your layer name in these variables at the
|
|
|
|
end of the file:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
BBFILE_COLLECTIONS += "elc"
|
|
|
|
BBFILE_PATTERN_elc := "^${LAYERDIR}/"
|
|
|
|
BBFILE_PRIORITY_elc = "9"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The <filename>images</filename> directory contains an append file that helps
|
|
|
|
further define the image.
|
|
|
|
In our example, the base image is <filename>core-image-minimal</filename>.
|
|
|
|
The image does, however, need some additional modules that we are using
|
|
|
|
for this example.
|
|
|
|
These modules support the amixer functionality.
|
|
|
|
Here is the append file:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
require recipes-core/images/poky-image-minimal.bb
|
|
|
|
|
|
|
|
IMAGE_INSTALL += "dropbear alsa-utils-aplay alsa-utils-alsamixer"
|
|
|
|
IMAGE_INSTALL_append_qemux86 += " kernel-module-snd-ens1370 \
|
|
|
|
kernel-module-snd-rawmidi kernel-module-loop kernel-module-nls-cp437 \
|
|
|
|
kernel-module-nls-iso8859-1 qemux86-audio alsa-utils-amixer"
|
|
|
|
|
|
|
|
LICENSE = "MIT"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
While the focus of this example is not on the BSP, it is worth mentioning that the
|
|
|
|
<filename>recipes-bsp</filename> directory has the recipes and append files for
|
|
|
|
features that the hardware requires.
|
|
|
|
In this example, there is a script and a recipe to support the
|
|
|
|
<filename>amixer</filename> functionality in QEMU.
|
|
|
|
It is beyond the scope of this manual to go too deeply into the script.
|
|
|
|
Suffice it to say that the script tests for the presence of the mixer, sets up
|
|
|
|
default mixer values, enables the mixer, unmutes master and then
|
|
|
|
sets the volume to 100.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The recipe <filename>qemu86-audio.bb</filename> installs and runs the
|
|
|
|
<filename>amixer</filename> when the system boots.
|
|
|
|
Here is the recipe:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SUMMARY = "Provide a basic init script to enable audio"
|
|
|
|
DESCRIPTION = "Set the volume and unmute the Front mixer setting during boot."
|
|
|
|
SECTION = "base"
|
|
|
|
LICENSE = "MIT"
|
|
|
|
LIC_FILES_CHKSUM = "file://${POKYBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58"
|
|
|
|
|
|
|
|
PR = "r4"
|
|
|
|
|
|
|
|
inherit update-rc.d
|
|
|
|
|
|
|
|
RDEPENDS = "alsa-utils-amixer"
|
|
|
|
|
|
|
|
SRC_URI = "file://qemux86-audio"
|
|
|
|
|
|
|
|
INITSCRIPT_NAME = "qemux86-audio"
|
|
|
|
INITSCRIPT_PARAMS = "defaults 90"
|
|
|
|
|
|
|
|
do_install() {
|
|
|
|
install -d ${D}${sysconfdir} \
|
|
|
|
${D}${sysconfdir}/init.d
|
|
|
|
install -m 0755 ${WORKDIR}/qemux86-audio ${D}${sysconfdir}/init.d
|
|
|
|
cat ${WORKDIR}/${INITSCRIPT_NAME} | \
|
|
|
|
sed -e 's,/etc,${sysconfdir},g' \
|
|
|
|
-e 's,/usr/sbin,${sbindir},g' \
|
|
|
|
-e 's,/var,${localstatedir},g' \
|
|
|
|
-e 's,/usr/bin,${bindir},g' \
|
|
|
|
-e 's,/usr,${prefix},g' > ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
|
|
|
|
chmod 755 ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
|
|
|
|
}
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The last area to look at is <filename>recipes-kernel</filename>.
|
|
|
|
This area holds configuration fragments and kernel append files.
|
|
|
|
The append file must have the same name as the kernel recipe, which is
|
|
|
|
<filename>linux-yocto-2.6.37</filename> in this example.
|
|
|
|
The file can <filename>SRC_URI</filename> statements to point to configuration
|
|
|
|
fragments you might have in the layer.
|
|
|
|
The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify
|
|
|
|
included kernel configurations that ship with the Yocto Project.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
2011-07-27 20:07:32 +00:00
|
|
|
</appendix>
|
2011-07-27 20:03:18 +00:00
|
|
|
<!--
|
|
|
|
vim: expandtab tw=80 ts=4
|
|
|
|
-->
|