221 lines
12 KiB
XML
221 lines
12 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 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 can be 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,
|
|
configuration, branching, tagging and feature divisions found in a kernel.
|
|
Thus, the Yocto Project kernel repository (or tree) is built.
|
|
</para>
|
|
<para>
|
|
The existence of this tree allows you to access and clone a particular
|
|
Yocto Project 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 kernel in any clone of the Yocto Project kernel source repository
|
|
Git tree.
|
|
For example, the following command clones the Yocto Project baseline kernel that
|
|
branched off of <filename>linux.org</filename> version 3.19:
|
|
<literallayout class='monospaced'>
|
|
$ git clone git://git.yoctoproject.org/linux-yocto-3.19
|
|
</literallayout>
|
|
For another example of how to set up a local Git repository of the Yocto Project
|
|
kernel files, see the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
|
|
item in the Yocto Project Development Manual.
|
|
</para>
|
|
<para>
|
|
Once you have cloned the kernel Git repository on your local machine, you can
|
|
switch to the <filename>meta</filename> branch within the repository.
|
|
Here is an example that assumes the local Git repository for the kernel is in
|
|
a top-level directory named <filename>linux-yocto-3.19</filename>:
|
|
<literallayout class='monospaced'>
|
|
$ cd linux-yocto-3.19
|
|
$ git checkout -b meta origin/meta
|
|
</literallayout>
|
|
Once you have checked out and switched to the <filename>meta</filename> branch,
|
|
you can see a snapshot of all the kernel configuration and feature descriptions that are
|
|
used to build that particular kernel repository.
|
|
These descriptions are in the form of <filename>.scc</filename> files.
|
|
</para>
|
|
<para>
|
|
You should realize, however, that browsing your local kernel 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 create the tree
|
|
that includes the new feature, patch or BSP:
|
|
<orderedlist>
|
|
<listitem><para>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>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 <filename>meta/cfg/kernel-cache</filename></para></listitem>
|
|
<listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
|
|
found in 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>Once located, the feature description is either compiled into a simple script
|
|
of actions, or into an existing equivalent script that is already part of the
|
|
shipped kernel.</para></listitem>
|
|
<listitem><para>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>Each extra feature is located, compiled and appended to the script
|
|
as described in step three.</para></listitem>
|
|
<listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
|
|
directories.
|
|
These directories 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>The base repository is cloned, and the actions
|
|
listed in the <filename>meta-*</filename> directories are applied to the
|
|
tree.</para></listitem>
|
|
<listitem><para>The Git repository is left with the desired branch checked out and any
|
|
required branching, patching and tagging has been performed.</para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
<para>
|
|
The kernel tree is now ready for developer consumption to be locally cloned,
|
|
configured, and built into a Yocto Project kernel specific to some target hardware.
|
|
<note><para>The generated <filename>meta-*</filename> directories add 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>
|
|
<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>
|
|
</note>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='build-strategy'>
|
|
<title>Build Strategy</title>
|
|
|
|
<!--
|
|
<para>
|
|
<emphasis>AR - Darren Hart:</emphasis> Some parts of this section
|
|
need to be in the
|
|
"<link linkend='using-an-iterative-development-process'>Using an Iterative Development Process</link>"
|
|
section.
|
|
Darren needs to figure out which parts and identify them.
|
|
</para>
|
|
-->
|
|
|
|
<para>
|
|
Once a local Git repository of the Yocto Project kernel exists on a development system,
|
|
you can consider the compilation phase of kernel development - 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 exists.
|
|
This branch has the following form:
|
|
<literallayout class='monospaced'>
|
|
<replaceable>kernel_type</replaceable>/<replaceable>bsp_name</replaceable>
|
|
</literallayout></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 <filename>meta-*</filename> 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_DEV_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
|
|
-->
|