forked from brl/citadel
353 lines
17 KiB
XML
353 lines
17 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; ] >
|
||
|
|
|
||
|
|
<appendix id='kernel-dev-maint-appx'>
|
||
|
|
<title>Kernel Maintenance</title>
|
||
|
|
|
||
|
|
<section id='tree-construction'>
|
||
|
|
<title>Tree Construction</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This section describes construction of the Yocto Project kernel
|
||
|
|
source repositories as accomplished by the Yocto Project team to
|
||
|
|
create Yocto Linux kernel repositories.
|
||
|
|
These kernel repositories are found under the heading "Yocto Linux
|
||
|
|
Kernel" at
|
||
|
|
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
|
||
|
|
and are shipped as part of a Yocto Project release.
|
||
|
|
The team creates these repositories by compiling and executing the
|
||
|
|
set of feature descriptions for every BSP and feature in the
|
||
|
|
product.
|
||
|
|
Those feature descriptions list all necessary patches,
|
||
|
|
configurations, branches, tags, and feature divisions found in a
|
||
|
|
Yocto Linux kernel.
|
||
|
|
Thus, the Yocto Project Linux kernel repository (or tree) and
|
||
|
|
accompanying Metadata in the
|
||
|
|
<filename>yocto-kernel-cache</filename> are built.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The existence of these repositories allow you to access and clone a
|
||
|
|
particular Yocto Project Linux kernel repository and use it to
|
||
|
|
build images based on their configurations and features.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
You can find the files used to describe all the valid features and
|
||
|
|
BSPs in the Yocto Project Linux kernel in any clone of the Yocto
|
||
|
|
Project Linux kernel source repository and
|
||
|
|
<filename>yocto-kernel-cache</filename> Git trees.
|
||
|
|
For example, the following commands clone the Yocto Project
|
||
|
|
baseline Linux kernel that branches off
|
||
|
|
<filename>linux.org</filename> version 4.12 and the
|
||
|
|
<filename>yocto-kernel-cache</filename>, which contains stores of
|
||
|
|
kernel Metadata:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
$ git clone git://git.yoctoproject.org/linux-yocto-4.12
|
||
|
|
$ git clone git://git.yoctoproject.org/linux-kernel-cache
|
||
|
|
</literallayout>
|
||
|
|
For more information on how to set up a local Git repository of
|
||
|
|
the Yocto Project Linux kernel files, see the
|
||
|
|
"<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
|
||
|
|
section.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Once you have cloned the kernel Git repository and the
|
||
|
|
cache of Metadata on your local machine, you can discover the
|
||
|
|
branches that are available in the repository using the following
|
||
|
|
Git command:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
$ git branch -a
|
||
|
|
</literallayout>
|
||
|
|
Checking out a branch allows you to work with a particular
|
||
|
|
Yocto Linux kernel.
|
||
|
|
For example, the following commands check out the
|
||
|
|
"standard/beagleboard" branch of the Yocto Linux kernel repository
|
||
|
|
and the "yocto-4.12" branch of the
|
||
|
|
<filename>yocto-kernel-cache</filename> repository:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
$ cd ~/linux-yocto-4.12
|
||
|
|
$ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
|
||
|
|
$ cd ~/linux-kernel-cache
|
||
|
|
$ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12
|
||
|
|
</literallayout>
|
||
|
|
<note>
|
||
|
|
Branches in the <filename>yocto-kernel-cache</filename>
|
||
|
|
repository correspond to Yocto Linux kernel versions
|
||
|
|
(e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
|
||
|
|
</note>
|
||
|
|
Once you have checked out and switched to appropriate branches,
|
||
|
|
you can see a snapshot of all the kernel source files used to
|
||
|
|
used to build that particular Yocto Linux kernel for a
|
||
|
|
particular board.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
To see the features and configurations for a particular Yocto
|
||
|
|
Linux kernel, you need to examine the
|
||
|
|
<filename>yocto-kernel-cache</filename> Git repository.
|
||
|
|
As mentioned, branches in the
|
||
|
|
<filename>yocto-kernel-cache</filename> repository correspond to
|
||
|
|
Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>).
|
||
|
|
Branches contain descriptions in the form of
|
||
|
|
<filename>.scc</filename> and <filename>.cfg</filename> files.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
You should realize, however, that browsing your local
|
||
|
|
<filename>yocto-kernel-cache</filename> repository for feature
|
||
|
|
descriptions and patches is not an effective way to determine what
|
||
|
|
is in a particular kernel branch.
|
||
|
|
Instead, you should use Git directly to discover the changes in
|
||
|
|
a branch.
|
||
|
|
Using Git is an efficient and flexible way to inspect changes to
|
||
|
|
the kernel.
|
||
|
|
<note>
|
||
|
|
Ground up reconstruction of the complete kernel tree is an
|
||
|
|
action only taken by the Yocto Project team during an active
|
||
|
|
development cycle.
|
||
|
|
When you create a clone of the kernel Git repository, you are
|
||
|
|
simply making it efficiently available for building and
|
||
|
|
development.
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The following steps describe what happens when the Yocto Project
|
||
|
|
Team constructs the Yocto Project kernel source Git repository
|
||
|
|
(or tree) found at
|
||
|
|
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
|
||
|
|
introduction of a new top-level kernel feature or BSP.
|
||
|
|
These are the actions that effectively provide the Metadata
|
||
|
|
and create the tree that includes the new feature, patch or BSP:
|
||
|
|
<orderedlist>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Pass Feature to Build Subsystem:</emphasis>
|
||
|
|
A top-level kernel feature is passed to the kernel build
|
||
|
|
subsystem.
|
||
|
|
Normally, this feature is a BSP for a particular kernel
|
||
|
|
type.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Locate Feature:</emphasis>
|
||
|
|
The file that describes the top-level feature is located
|
||
|
|
by searching these system directories:
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>
|
||
|
|
The in-tree kernel-cache directories, which are
|
||
|
|
located in the
|
||
|
|
<filename>yocto-kernel-cache</filename>
|
||
|
|
repository
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
Areas pointed to by <filename>SRC_URI</filename>
|
||
|
|
statements found in kernel recipes
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
For a typical build, the target of the search is a
|
||
|
|
feature description in an <filename>.scc</filename> file
|
||
|
|
whose name follows this format:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
<replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
|
||
|
|
</literallayout>
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Expand Feature:</emphasis>
|
||
|
|
Once located, the feature description is either expanded
|
||
|
|
into a simple script of actions, or into an existing
|
||
|
|
equivalent script that is already part of the shipped
|
||
|
|
kernel.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Append Extra Features:</emphasis>
|
||
|
|
Extra features are appended to the top-level feature
|
||
|
|
description.
|
||
|
|
These features can come from the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
|
||
|
|
variable in recipes.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Locate, Expand, and Append Each Feature:</emphasis>
|
||
|
|
Each extra feature is located, expanded and appended to
|
||
|
|
the script as described in step three.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Execute the Script:</emphasis>
|
||
|
|
The script is executed to produce files
|
||
|
|
<filename>.scc</filename> and <filename>.cfg</filename>
|
||
|
|
files in appropriate directories of the
|
||
|
|
<filename>yocto-kernel-cache</filename> repository.
|
||
|
|
These files are descriptions of all the branches, tags,
|
||
|
|
patches and configurations that need to be applied to the
|
||
|
|
base Git repository to completely create the
|
||
|
|
source (build) branch for the new BSP or feature.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Clone Base Repository:</emphasis>
|
||
|
|
The base repository is cloned, and the actions
|
||
|
|
listed in the <filename>yocto-kernel-cache</filename>
|
||
|
|
directories are applied to the tree.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Perform Cleanup:</emphasis>
|
||
|
|
The Git repositories are left with the desired branches
|
||
|
|
checked out and any required branching, patching and
|
||
|
|
tagging has been performed.
|
||
|
|
</para></listitem>
|
||
|
|
</orderedlist>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The kernel tree and cache are ready for developer consumption to
|
||
|
|
be locally cloned, configured, and built into a Yocto Project
|
||
|
|
kernel specific to some target hardware.
|
||
|
|
<note><title>Notes</title>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>
|
||
|
|
The generated <filename>yocto-kernel-cache</filename>
|
||
|
|
repository adds to the kernel as shipped with the Yocto
|
||
|
|
Project release.
|
||
|
|
Any add-ons and configuration data are applied to the
|
||
|
|
end of an existing branch.
|
||
|
|
The full repository generation that is found in the
|
||
|
|
official Yocto Project kernel repositories at
|
||
|
|
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
|
||
|
|
is the combination of all supported boards and
|
||
|
|
configurations.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
The technique the Yocto Project team uses is flexible
|
||
|
|
and allows for seamless blending of an immutable
|
||
|
|
history with additional patches specific to a
|
||
|
|
deployment.
|
||
|
|
Any additions to the kernel become an integrated part
|
||
|
|
of the branches.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
The full kernel tree that you see on
|
||
|
|
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> is
|
||
|
|
generated through repeating the above steps for all
|
||
|
|
valid BSPs.
|
||
|
|
The end result is a branched, clean history tree that
|
||
|
|
makes up the kernel for a given release.
|
||
|
|
You can see the script (<filename>kgit-scc</filename>)
|
||
|
|
responsible for this in the
|
||
|
|
<ulink url='&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools'><filename>yocto-kernel-tools</filename></ulink>
|
||
|
|
repository.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
The steps used to construct the full kernel tree are
|
||
|
|
the same steps that BitBake uses when it builds a
|
||
|
|
kernel image.
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='build-strategy'>
|
||
|
|
<title>Build Strategy</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Once you have cloned a Yocto Linux kernel repository and the
|
||
|
|
cache repository (<filename>yocto-kernel-cache</filename>) onto
|
||
|
|
your development system, you can consider the compilation phase
|
||
|
|
of kernel development, which is building a kernel image.
|
||
|
|
Some prerequisites exist that are validated by the build process
|
||
|
|
before compilation starts:
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>
|
||
|
|
The
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
||
|
|
points to the kernel Git repository.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
A BSP build branch with Metadata exists in the
|
||
|
|
<filename>yocto-kernel-cache</filename> repository.
|
||
|
|
The branch is based on the Yocto Linux kernel version and
|
||
|
|
has configurations and features grouped under the
|
||
|
|
<filename>yocto-kernel-cache/bsp</filename> directory.
|
||
|
|
For example, features and configurations for the
|
||
|
|
BeagleBone Board assuming a
|
||
|
|
<filename>linux-yocto_4.12</filename> kernel reside in the
|
||
|
|
following area of the <filename>yocto-kernel-cache</filename>
|
||
|
|
repository:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
yocto-kernel-cache/bsp/beaglebone
|
||
|
|
</literallayout>
|
||
|
|
<note>
|
||
|
|
In the previous example, the "yocto-4.12" branch is
|
||
|
|
checked out in the <filename>yocto-kernel-cache</filename>
|
||
|
|
repository.
|
||
|
|
</note>
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The OpenEmbedded build system makes sure these conditions exist
|
||
|
|
before attempting compilation.
|
||
|
|
Other means, however, do exist, such as as bootstrapping a BSP.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Before building a kernel, the build process verifies the tree
|
||
|
|
and configures the kernel by processing all of the
|
||
|
|
configuration "fragments" specified by feature descriptions
|
||
|
|
in the <filename>.scc</filename> files.
|
||
|
|
As the features are compiled, associated kernel configuration
|
||
|
|
fragments are noted and recorded in the series of directories
|
||
|
|
in their compilation order.
|
||
|
|
The fragments are migrated, pre-processed and passed to the
|
||
|
|
Linux Kernel Configuration subsystem (<filename>lkc</filename>) as
|
||
|
|
raw input in the form of a <filename>.config</filename> file.
|
||
|
|
The <filename>lkc</filename> uses its own internal dependency
|
||
|
|
constraints to do the final processing of that information and
|
||
|
|
generates the final <filename>.config</filename> file that is used
|
||
|
|
during compilation.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Using the board's architecture and other relevant values from
|
||
|
|
the board's template, kernel compilation is started and a kernel
|
||
|
|
image is produced.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The other thing that you notice once you configure a kernel is that
|
||
|
|
the build process generates a build tree that is separate from
|
||
|
|
your kernel's local Git source repository tree.
|
||
|
|
This build tree has a name that uses the following form, where
|
||
|
|
<filename>${MACHINE}</filename> is the metadata name of the
|
||
|
|
machine (BSP) and "kernel_type" is one of the Yocto Project
|
||
|
|
supported kernel types (e.g. "standard"):
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build
|
||
|
|
</literallayout>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The existing support in the <filename>kernel.org</filename> tree
|
||
|
|
achieves this default functionality.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This behavior means that all the generated files for a particular
|
||
|
|
machine or BSP are now in the build tree directory.
|
||
|
|
The files include the final <filename>.config</filename> file,
|
||
|
|
all the <filename>.o</filename> files, the <filename>.a</filename>
|
||
|
|
files, and so forth.
|
||
|
|
Since each machine or BSP has its own separate
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
|
||
|
|
in its own separate branch of the Git repository, you can easily
|
||
|
|
switch between different builds.
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
</appendix>
|
||
|
|
<!--
|
||
|
|
vim: expandtab tw=80 ts=4
|
||
|
|
-->
|