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

kernel-dev: Created file structure for new kernel-dev manual. 

(From yocto-docs rev: 25be3ebb7713b875c4ec6e3723961b7dd860295d)

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-17 17:17:14 -06:00 committed by Richard Purdie
parent ea50862d40
commit 5cbeb84006
9 changed files with 4315 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
documentation/kernel-dev/figures/kernel-dev-title.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

918
documentation/kernel-dev/kernel-dev-advanced.xml Normal file
View File

@ -0,0 +1,918 @@
<!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-how-to'>
<title>Working with the Yocto Project Kernel</title>
<section id='actions-org'>
<title>Introduction</title>
<para>
This chapter describes how to accomplish tasks involving a kernel's tree structure.
The information is designed to help the developer that wants to modify the Yocto
Project kernel and contribute changes upstream to the Yocto Project.
The information covers the following:
<itemizedlist>
<listitem><para>Tree construction</para></listitem>
<listitem><para>Build strategies</para></listitem>
<listitem><para>Workflow examples</para></listitem>
</itemizedlist>
</para>
</section>
<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/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.4:
<literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/linux-yocto-3.4
</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.4</filename>:
<literallayout class='monospaced'>
$ cd ~/linux-yocto-3.4
$ 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.
For examples showing how to use Git to inspect kernel commits, see the following sections
in this chapter.
<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'>
&lt;bsp_name&gt;-&lt;kernel_type&gt;.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>
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'>
&lt;kernel_type&gt;/&lt;bsp_name&gt;
</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, see
the "<link linkend='workflow-examples'>Workflow Examples</link>".
</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}-&lt;kernel_type&gt;-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 build directory in its own separate branch
of the Git repository, you can easily switch between different builds.
</para>
</section>
<section id='workflow-examples'>
<title>Workflow Examples</title>
<para>
As previously noted, the Yocto Project kernel has built-in Git integration.
However, these utilities are not the only way to work with the kernel repository.
The Yocto Project has not made changes to Git or to other tools that
would invalidate alternate workflows.
Additionally, the way the kernel repository is constructed results in using
only core Git functionality, thus allowing any number of tools or front ends to use the
resulting tree.
</para>
<para>
This section contains several workflow examples.
Many of the examples use Git commands.
You can find Git documentation at
<ulink url='http://git-scm.com/documentation'></ulink>.
You can find a simple overview of using Git with the Yocto Project in the
"<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
section of the Yocto Project Development Manual.
</para>
<section id='change-inspection-kernel-changes-commits'>
<title>Change Inspection: Changes/Commits</title>
<para>
A common question when working with a kernel is:
"What changes have been applied to this tree?"
</para>
<para>
In projects that have a collection of directories that
contain patches to the kernel, it is possible to inspect or "grep" the contents
of the directories to get a general feel for the changes.
This sort of patch inspection is not an efficient way to determine what has been
done to the kernel.
The reason it is inefficient is because there are many optional patches that are
selected based on the kernel type and the feature description.
Additionally, patches could exist in directories that are not included in the search.
</para>
<para>
A more efficient way to determine what has changed in the branch is to use
Git and inspect or search the kernel tree.
This method gives you a full view of not only the source code modifications,
but also provides the reasons for the changes.
</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.
Because Git repositories in the Yocto Project do not break existing Git
functionality, and because there exists many permutations of these types of
Git commands, many methods exist by which you can discover 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>.
For example, the branch names for the <filename>linux-yocto-3.4</filename>
kernel repository can be seen at
<ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></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 (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
</para>
<para>
Here is an example that looks at what has changed in the
<filename>emenlow</filename> branch of the
<filename>linux-yocto-3.4</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 a summary of changes use the <filename>git log</filename> command.
Here is an example using the same branches:
<literallayout class='monospaced'>
$ git log --oneline origin/standard/base..origin/standard/emenlow
</literallayout>
The <filename>git log</filename> output might be more useful than
the <filename>git whatchanged</filename> as you get
a short, one-line summary of each change and not the entire commit.
</para>
<para>
If you want to see code differences associated with all the changes, use
the <filename>git diff</filename> command.
Here is an example:
<literallayout class='monospaced'>
$ git diff origin/standard/base..origin/standard/emenlow
</literallayout>
</para>
<para>
You can see the commit log messages and the text differences using the
<filename>git show</filename> command:
Here is an example:
<literallayout class='monospaced'>
$ git show origin/standard/base..origin/standard/emenlow
</literallayout>
</para>
<para>
You can create individual patches for each change by using the
<filename>git format-patch</filename> command.
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='show-a-particular-feature-or-branch-change'>
<title>Show a Particular Feature or Branch Change</title>
<para>
Developers use tags in the Yocto Project kernel tree to divide changes for significant
features or branches.
Once you know a particular tag, you can use Git commands
to show changes associated with the tag and find the branches that contain
the feature.
<note>
Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
present, there could be many tags.
</note>
The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
a feature.
Here is an example that shows changes tagged by the <filename>systemtap</filename>
feature:
<literallayout class='monospaced'>
$ git show systemtap
</literallayout>
You can use the <filename>git branch --contains &lt;tag&gt;</filename> 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>
<para>
You can use many other comparisons to isolate BSP and kernel changes.
For example, you can compare against <filename>kernel.org</filename> tags
such as the <filename>v3.4</filename> tag.
</para>
</section>
</section>
<section id='development-saving-kernel-modifications'>
<title>Development: Saving Kernel Modifications</title>
<para>
Another common operation is to build a BSP supplied by the Yocto Project, make some
changes, rebuild, and then test.
Those local changes often need to be exported, shared or otherwise maintained.
</para>
<para>
Since the Yocto Project kernel source tree is backed by Git, this activity is
much easier as compared to with previous releases.
Because Git tracks file modifications, additions and deletions, it is easy
to modify the code and later realize that you need to save the changes.
It is also easy to determine what has changed.
This method also provides many tools to commit, undo and export those modifications.
</para>
<para>
This section and its sub-sections, describe general application of Git's
<filename>push</filename> and <filename>pull</filename> commands, which are used to
get your changes upstream or source your code from an upstream repository.
The Yocto Project provides scripts that help you work in a collaborative development
environment.
For information on these scripts, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
Upstream and Request a Pull</ulink>" and
"<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
sections in the Yocto Project Development Manual.
</para>
<para>
There are many ways to save kernel modifications.
The technique employed
depends on the destination for the patches:
<itemizedlist>
<listitem><para>Bulk storage</para></listitem>
<listitem><para>Internal sharing either through patches or by using Git</para></listitem>
<listitem><para>External submissions</para></listitem>
<listitem><para>Exporting for integration into another Source Code
Manager (SCM)</para></listitem>
</itemizedlist>
</para>
<para>
Because of the following list of issues, the destination of the patches also influences
the method for gathering them:
<itemizedlist>
<listitem><para>Bisectability</para></listitem>
<listitem><para>Commit headers</para></listitem>
<listitem><para>Division of subsystems for separate submission or review</para></listitem>
</itemizedlist>
</para>
<section id='bulk-export'>
<title>Bulk Export</title>
<para>
This section describes how you can "bulk" export changes that have not
been separated or divided.
This situation works well when you are simply storing patches outside of the kernel
source repository, either permanently or temporarily, and you are not committing
incremental changes during development.
<note>
This technique is not appropriate for full integration of upstream submission
because changes are not properly divided and do not provide an avenue for per-change
commit messages.
Therefore, this example assumes that changes have not been committed incrementally
during development and that you simply must gather and export them.
</note>
<literallayout class='monospaced'>
# bulk export of ALL modifications without separation or division
# of the changes
$ git add .
$ git commit -s -a -m &lt;msg&gt;
or
$ git commit -s -a # and interact with $EDITOR
</literallayout>
</para>
<para>
The previous operations capture all the local changes in the project source
tree in a single Git commit.
And, that commit is also stored in the project's source tree.
</para>
<para>
Once the changes are exported, you can restore them manually using a template
or through integration with the <filename>default_kernel</filename>.
</para>
</section>
<section id='incremental-planned-sharing'>
<title>Incremental/Planned Sharing</title>
<para>
This section describes how to save modifications when you are making incremental
commits or practicing planned sharing.
The examples in this section assume that you have incrementally committed
changes to the tree during development and now need to export them.
The sections that follow
describe how you can export your changes internally through either patches or by
using Git commands.
</para>
<para>
During development, the following commands are of interest.
For full Git documentation, refer to the Git documentation at
<ulink url='http://github.com'></ulink>.
<literallayout class='monospaced'>
# edit a file
$ vi &lt;path&gt;/file
# stage the change
$ git add &lt;path&gt;/file
# commit the change
$ git commit -s
# remove a file
$ git rm &lt;path&gt;/file
# commit the change
$ git commit -s
... etc.
</literallayout>
</para>
<para>
Distributed development with Git is possible when you use a universally
agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
specific change set with a specific parent.
This identifier is created for you when
you create a commit, and is re-created when you amend, alter or re-apply
a commit.
As an individual in isolation, this is of no interest.
However, if you
intend to share your tree with normal Git <filename>push</filename> and
<filename>pull</filename> operations for
distributed development, you should consider the ramifications of changing a
commit that you have already shared with others.
</para>
<para>
Assuming that the changes have not been pushed upstream, or pulled into
another repository, you can update both the commit content and commit messages
associated with development by using the following commands:
<literallayout class='monospaced'>
$ Git add &lt;path&gt;/file
$ Git commit --amend
$ Git rebase or Git rebase -i
</literallayout>
</para>
<para>
Again, assuming that the changes have not been pushed upstream, and that
no pending works-in-progress exist (use <filename>git status</filename> to check), then
you can revert (undo) commits by using the following commands:
<literallayout class='monospaced'>
# remove the commit, update working tree and remove all
# traces of the change
$ git reset --hard HEAD^
# remove the commit, but leave the files changed and staged for re-commit
$ git reset --soft HEAD^
# remove the commit, leave file change, but not staged for commit
$ git reset --mixed HEAD^
</literallayout>
</para>
<para>
You can create branches, "cherry-pick" changes, or perform any number of Git
operations until the commits are in good order for pushing upstream
or for pull requests.
After a <filename>push</filename> or <filename>pull</filename> command,
commits are normally considered
"permanent" and you should not modify them.
If the commits need to be changed, you can incrementally do so with new commits.
These practices follow standard Git workflow and the <filename>kernel.org</filename> best
practices, which is recommended.
<note>
It is recommended to tag or branch before adding changes to a Yocto Project
BSP or before creating a new one.
The reason for this recommendation is because the branch or tag provides a
reference point to facilitate locating and exporting local changes.
</note>
</para>
<section id='export-internally-via-patches'>
<title>Exporting Changes Internally by Using Patches</title>
<para>
This section describes how you can extract committed changes from a working directory
by exporting them as patches.
Once the changes have been extracted, you can use the patches for upstream submission,
place them in a Yocto Project template for automatic kernel patching,
or apply them in many other common uses.
</para>
<para>
This example shows how to create a directory with sequentially numbered patches.
Once the directory is created, you can apply it to a repository using the
<filename>git am</filename> command to reproduce the original commit and all
the related information such as author, date, commit log, and so forth.
<note>
The new commit identifiers (ID) will be generated upon re-application.
This action reflects that the commit is now applied to an underlying commit
with a different ID.
</note>
<literallayout class='monospaced'>
# &lt;first-commit&gt; can be a tag if one was created before development
# began. It can also be the parent branch if a branch was created
# before development began.
$ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
</literallayout>
</para>
<para>
In other words:
<literallayout class='monospaced'>
# Identify commits of interest.
# If the tree was tagged before development
$ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
# If no tags are available
$ git format-patch -o &lt;save dir&gt; HEAD^ # last commit
$ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
$ git whatchanged # identify last commit
$ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
$ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
</literallayout>
</para>
</section>
<section id='export-internally-via-git'>
<title>Exporting Changes Internally by Using Git</title>
<para>
This section describes how you can export changes from a working directory
by pushing the changes into a master repository or by making a pull request.
Once you have pushed the changes to the master repository, you can then
pull those same changes into a new kernel build at a later time.
</para>
<para>
Use this command form to push the changes:
<literallayout class='monospaced'>
$ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
&lt;local_branch&gt;:&lt;remote_branch&gt;
</literallayout>
</para>
<para>
For example, the following command pushes the changes from your local branch
<filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
<literallayout class='monospaced'>
$ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
yocto/standard/common-pc/base:yocto/standard/common-pc/base
</literallayout>
</para>
<para>
A pull request entails using the <filename>git request-pull</filename> command to compose
an email to the
maintainer requesting that a branch be pulled into the master repository, see
<ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
<note>
Other commands such as <filename>git stash</filename> or branching can also be used to save
changes, but are not covered in this document.
</note>
</para>
</section>
</section>
<section id='export-for-external-upstream-submission'>
<title>Exporting Changes for External (Upstream) Submission</title>
<para>
This section describes how to export changes for external upstream submission.
If the patch series is large or the maintainer prefers to pull
changes, you can submit these changes by using a pull request.
However, it is common to send patches as an email series.
This method allows easy review and integration of the changes.
<note>
Before sending patches for review be sure you understand the
community standards for submitting and documenting changes and follow their best practices.
For example, kernel patches should follow standards such as:
<itemizedlist>
<listitem><para>
<ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
<listitem><para>Documentation/SubmittingPatches (in any linux
kernel source tree)</para></listitem>
</itemizedlist>
</note>
</para>
<para>
The messages used to commit changes are a large part of these standards.
Consequently, be sure that the headers for each commit have the required information.
For information on how to follow the Yocto Project commit message standards, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
Change</ulink>" section in the Yocto Project Development Manual.
</para>
<para>
If the initial commits were not properly documented or do not meet those standards,
you can re-base by using the <filename>git rebase -i</filename> command to
manipulate the commits and
get them into the required format.
Other techniques such as branching and cherry-picking commits are also viable options.
</para>
<para>
Once you complete the commits, you can generate the email that sends the patches
to the maintainer(s) or lists that review and integrate changes.
The command <filename>git send-email</filename> is commonly used to ensure
that patches are properly
formatted for easy application and avoid mailer-induced patch damage.
</para>
<para>
The following is an example of dumping patches for external submission:
<literallayout class='monospaced'>
# dump the last 4 commits
$ git format-patch --thread -n -o ~/rr/ HEAD^^^^
$ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
--to foo@yoctoproject.org --to bar@yoctoproject.org \
--cc list@yoctoproject.org ~/rr
# the editor is invoked for the 0/N patch, and when complete the entire
# series is sent via email for review
</literallayout>
</para>
</section>
<section id='export-for-import-into-other-scm'>
<title>Exporting Changes for Import into Another SCM</title>
<para>
When you want to export changes for import into another
Source Code Manager (SCM), you can use any of the previously discussed
techniques.
However, if the patches are manually applied to a secondary tree and then
that tree is checked into the SCM, you can lose change information such as
commit logs.
This process is not recommended.
</para>
<para>
Many SCMs can directly import Git commits, or can translate Git patches so that
information is not lost.
Those facilities are SCM-dependent and you should use them whenever possible.
</para>
</section>
</section>
<section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
<title>Working with the Yocto Project Kernel in Another SCM</title>
<para>
This section describes kernel development in an SCM other than Git,
which is not the same as exporting changes to another SCM described earlier.
For this scenario, you use the OpenEmbedded build system to
develop the kernel in a different SCM.
The following must be true for you to accomplish this:
<itemizedlist>
<listitem><para>The delivered Yocto Project kernel must be exported into the second
SCM.</para></listitem>
<listitem><para>Development must be exported from that secondary SCM into a
format that can be used by the OpenEmbedded build system.</para></listitem>
</itemizedlist>
</para>
<section id='exporting-delivered-kernel-to-scm'>
<title>Exporting the Delivered Kernel to the SCM</title>
<para>
Depending on the SCM, it might be possible to export the entire Yocto Project
kernel Git repository, branches and all, into a new environment.
This method is preferred because it has the most flexibility and potential to maintain
the meta data associated with each commit.
</para>
<para>
When a direct import mechanism is not available, it is still possible to
export a branch (or series of branches) and check them into a new repository.
</para>
<para>
The following commands illustrate some of the steps you could use to
import the <filename>yocto/standard/common-pc/base</filename>
kernel into a secondary SCM:
<literallayout class='monospaced'>
$ git checkout yocto/standard/common-pc/base
$ cd .. ; echo linux/.git &gt; .cvsignore
$ cvs import -m "initial import" linux MY_COMPANY start
</literallayout>
</para>
<para>
You could now relocate the CVS repository and use it in a centralized manner.
</para>
<para>
The following commands illustrate how you can condense and merge two BSPs into a
second SCM:
<literallayout class='monospaced'>
$ git checkout yocto/standard/common-pc/base
$ git merge yocto/standard/common-pc-64/base
# resolve any conflicts and commit them
$ cd .. ; echo linux/.git &gt; .cvsignore
$ cvs import -m "initial import" linux MY_COMPANY start
</literallayout>
</para>
</section>
<section id='importing-changes-for-build'>
<title>Importing Changes for the Build</title>
<para>
Once development has reached a suitable point in the second development
environment, you need to export the changes as patches.
To export them, place the changes in a recipe and
automatically apply them to the kernel during patching.
</para>
</section>
</section>
<section id='bsp-creating'>
<title>Creating a BSP Based on an Existing Similar BSP</title>
<para>
This section overviews the process of creating a BSP based on an
existing similar BSP.
The information is introductory in nature and does not provide step-by-step examples.
For detailed information on how to create a new BSP, see
the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
Yocto Project Board Support Package (BSP) Developer's Guide, or see the
<ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
wiki page.
</para>
<para>
The basic steps you need to follow are:
<orderedlist>
<listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
You must create a local
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
by either creating a Git repository (recommended) or
extracting a Yocto Project release tarball.</para></listitem>
<listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
Try to map your board features as closely to the features of a BSP that is
already supported and exists in the Yocto Project.
Starting with something as close as possible to your board makes developing
your BSP easier.
You can find all the BSPs that are supported and ship with the Yocto Project
on the Yocto Project's Download page at
<ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
<listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
You need to either have a local Git repository of the base BSP set up or
have downloaded and extracted the files from a release BSP tarball.
Either method gives you access to the BSP source files.</para></listitem>
<listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
BSP work:</emphasis>
Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
<listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
Configuration changes involve the files in the BSP's <filename>conf</filename>
directory.
Changes include creating a machine-specific configuration file and editing the
<filename>layer.conf</filename> file.
The configuration changes identify the kernel you will be using.
Recipe changes include removing, modifying, or adding new recipe files that
instruct the build process on what features to include in the image.</para></listitem>
<listitem><para><emphasis>Prepare for the build:</emphasis>
Before you actually initiate the build, you need to set up the build environment
by sourcing the environment initialization script.
After setting up the environment, you need to make some build configuration
changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
files.</para></listitem>
<listitem><para><emphasis>Build the image:</emphasis>
The OpenEmbedded build system uses BitBake to create the image.
You need to decide on the type of image you are going to build (e.g. minimal, base,
core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
command.</para></listitem>
</orderedlist>
</para>
</section>
<section id='tip-dirty-string'>
<title>"-dirty" String</title>
<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 brute force pickup and commit 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>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->

392
documentation/kernel-dev/kernel-dev-common.xml Normal file
View File

@ -0,0 +1,392 @@
<!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-concepts'>
<title>Yocto Project Kernel Concepts</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>
<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>
</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='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.
</para>
<section id='architecture-overview'>
<title>Overview</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.
</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='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>
</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>
<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>
</para>
</section>
<section id='kernel-tools'>
<title>Kernel Tools</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>
</para>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->

8
documentation/kernel-dev/kernel-dev-customization.xsl Normal file
View File

@ -0,0 +1,8 @@
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
<!-- <xsl:param name="generate.toc" select="'article nop'"></xsl:param> -->
</xsl:stylesheet>

918
documentation/kernel-dev/kernel-dev-examples.xml Normal file
View File

@ -0,0 +1,918 @@
<!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-how-to'>
<title>Working with the Yocto Project Kernel</title>
<section id='actions-org'>
<title>Introduction</title>
<para>
This chapter describes how to accomplish tasks involving a kernel's tree structure.
The information is designed to help the developer that wants to modify the Yocto
Project kernel and contribute changes upstream to the Yocto Project.
The information covers the following:
<itemizedlist>
<listitem><para>Tree construction</para></listitem>
<listitem><para>Build strategies</para></listitem>
<listitem><para>Workflow examples</para></listitem>
</itemizedlist>
</para>
</section>
<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/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.4:
<literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/linux-yocto-3.4
</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.4</filename>:
<literallayout class='monospaced'>
$ cd ~/linux-yocto-3.4
$ 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.
For examples showing how to use Git to inspect kernel commits, see the following sections
in this chapter.
<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'>
&lt;bsp_name&gt;-&lt;kernel_type&gt;.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>
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'>
&lt;kernel_type&gt;/&lt;bsp_name&gt;
</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, see
the "<link linkend='workflow-examples'>Workflow Examples</link>".
</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}-&lt;kernel_type&gt;-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 build directory in its own separate branch
of the Git repository, you can easily switch between different builds.
</para>
</section>
<section id='workflow-examples'>
<title>Workflow Examples</title>
<para>
As previously noted, the Yocto Project kernel has built-in Git integration.
However, these utilities are not the only way to work with the kernel repository.
The Yocto Project has not made changes to Git or to other tools that
would invalidate alternate workflows.
Additionally, the way the kernel repository is constructed results in using
only core Git functionality, thus allowing any number of tools or front ends to use the
resulting tree.
</para>
<para>
This section contains several workflow examples.
Many of the examples use Git commands.
You can find Git documentation at
<ulink url='http://git-scm.com/documentation'></ulink>.
You can find a simple overview of using Git with the Yocto Project in the
"<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
section of the Yocto Project Development Manual.
</para>
<section id='change-inspection-kernel-changes-commits'>
<title>Change Inspection: Changes/Commits</title>
<para>
A common question when working with a kernel is:
"What changes have been applied to this tree?"
</para>
<para>
In projects that have a collection of directories that
contain patches to the kernel, it is possible to inspect or "grep" the contents
of the directories to get a general feel for the changes.
This sort of patch inspection is not an efficient way to determine what has been
done to the kernel.
The reason it is inefficient is because there are many optional patches that are
selected based on the kernel type and the feature description.
Additionally, patches could exist in directories that are not included in the search.
</para>
<para>
A more efficient way to determine what has changed in the branch is to use
Git and inspect or search the kernel tree.
This method gives you a full view of not only the source code modifications,
but also provides the reasons for the changes.
</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.
Because Git repositories in the Yocto Project do not break existing Git
functionality, and because there exists many permutations of these types of
Git commands, many methods exist by which you can discover 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>.
For example, the branch names for the <filename>linux-yocto-3.4</filename>
kernel repository can be seen at
<ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></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 (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
</para>
<para>
Here is an example that looks at what has changed in the
<filename>emenlow</filename> branch of the
<filename>linux-yocto-3.4</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 a summary of changes use the <filename>git log</filename> command.
Here is an example using the same branches:
<literallayout class='monospaced'>
$ git log --oneline origin/standard/base..origin/standard/emenlow
</literallayout>
The <filename>git log</filename> output might be more useful than
the <filename>git whatchanged</filename> as you get
a short, one-line summary of each change and not the entire commit.
</para>
<para>
If you want to see code differences associated with all the changes, use
the <filename>git diff</filename> command.
Here is an example:
<literallayout class='monospaced'>
$ git diff origin/standard/base..origin/standard/emenlow
</literallayout>
</para>
<para>
You can see the commit log messages and the text differences using the
<filename>git show</filename> command:
Here is an example:
<literallayout class='monospaced'>
$ git show origin/standard/base..origin/standard/emenlow
</literallayout>
</para>
<para>
You can create individual patches for each change by using the
<filename>git format-patch</filename> command.
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='show-a-particular-feature-or-branch-change'>
<title>Show a Particular Feature or Branch Change</title>
<para>
Developers use tags in the Yocto Project kernel tree to divide changes for significant
features or branches.
Once you know a particular tag, you can use Git commands
to show changes associated with the tag and find the branches that contain
the feature.
<note>
Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
present, there could be many tags.
</note>
The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
a feature.
Here is an example that shows changes tagged by the <filename>systemtap</filename>
feature:
<literallayout class='monospaced'>
$ git show systemtap
</literallayout>
You can use the <filename>git branch --contains &lt;tag&gt;</filename> 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>
<para>
You can use many other comparisons to isolate BSP and kernel changes.
For example, you can compare against <filename>kernel.org</filename> tags
such as the <filename>v3.4</filename> tag.
</para>
</section>
</section>
<section id='development-saving-kernel-modifications'>
<title>Development: Saving Kernel Modifications</title>
<para>
Another common operation is to build a BSP supplied by the Yocto Project, make some
changes, rebuild, and then test.
Those local changes often need to be exported, shared or otherwise maintained.
</para>
<para>
Since the Yocto Project kernel source tree is backed by Git, this activity is
much easier as compared to with previous releases.
Because Git tracks file modifications, additions and deletions, it is easy
to modify the code and later realize that you need to save the changes.
It is also easy to determine what has changed.
This method also provides many tools to commit, undo and export those modifications.
</para>
<para>
This section and its sub-sections, describe general application of Git's
<filename>push</filename> and <filename>pull</filename> commands, which are used to
get your changes upstream or source your code from an upstream repository.
The Yocto Project provides scripts that help you work in a collaborative development
environment.
For information on these scripts, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
Upstream and Request a Pull</ulink>" and
"<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
sections in the Yocto Project Development Manual.
</para>
<para>
There are many ways to save kernel modifications.
The technique employed
depends on the destination for the patches:
<itemizedlist>
<listitem><para>Bulk storage</para></listitem>
<listitem><para>Internal sharing either through patches or by using Git</para></listitem>
<listitem><para>External submissions</para></listitem>
<listitem><para>Exporting for integration into another Source Code
Manager (SCM)</para></listitem>
</itemizedlist>
</para>
<para>
Because of the following list of issues, the destination of the patches also influences
the method for gathering them:
<itemizedlist>
<listitem><para>Bisectability</para></listitem>
<listitem><para>Commit headers</para></listitem>
<listitem><para>Division of subsystems for separate submission or review</para></listitem>
</itemizedlist>
</para>
<section id='bulk-export'>
<title>Bulk Export</title>
<para>
This section describes how you can "bulk" export changes that have not
been separated or divided.
This situation works well when you are simply storing patches outside of the kernel
source repository, either permanently or temporarily, and you are not committing
incremental changes during development.
<note>
This technique is not appropriate for full integration of upstream submission
because changes are not properly divided and do not provide an avenue for per-change
commit messages.
Therefore, this example assumes that changes have not been committed incrementally
during development and that you simply must gather and export them.
</note>
<literallayout class='monospaced'>
# bulk export of ALL modifications without separation or division
# of the changes
$ git add .
$ git commit -s -a -m &lt;msg&gt;
or
$ git commit -s -a # and interact with $EDITOR
</literallayout>
</para>
<para>
The previous operations capture all the local changes in the project source
tree in a single Git commit.
And, that commit is also stored in the project's source tree.
</para>
<para>
Once the changes are exported, you can restore them manually using a template
or through integration with the <filename>default_kernel</filename>.
</para>
</section>
<section id='incremental-planned-sharing'>
<title>Incremental/Planned Sharing</title>
<para>
This section describes how to save modifications when you are making incremental
commits or practicing planned sharing.
The examples in this section assume that you have incrementally committed
changes to the tree during development and now need to export them.
The sections that follow
describe how you can export your changes internally through either patches or by
using Git commands.
</para>
<para>
During development, the following commands are of interest.
For full Git documentation, refer to the Git documentation at
<ulink url='http://github.com'></ulink>.
<literallayout class='monospaced'>
# edit a file
$ vi &lt;path&gt;/file
# stage the change
$ git add &lt;path&gt;/file
# commit the change
$ git commit -s
# remove a file
$ git rm &lt;path&gt;/file
# commit the change
$ git commit -s
... etc.
</literallayout>
</para>
<para>
Distributed development with Git is possible when you use a universally
agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
specific change set with a specific parent.
This identifier is created for you when
you create a commit, and is re-created when you amend, alter or re-apply
a commit.
As an individual in isolation, this is of no interest.
However, if you
intend to share your tree with normal Git <filename>push</filename> and
<filename>pull</filename> operations for
distributed development, you should consider the ramifications of changing a
commit that you have already shared with others.
</para>
<para>
Assuming that the changes have not been pushed upstream, or pulled into
another repository, you can update both the commit content and commit messages
associated with development by using the following commands:
<literallayout class='monospaced'>
$ Git add &lt;path&gt;/file
$ Git commit --amend
$ Git rebase or Git rebase -i
</literallayout>
</para>
<para>
Again, assuming that the changes have not been pushed upstream, and that
no pending works-in-progress exist (use <filename>git status</filename> to check), then
you can revert (undo) commits by using the following commands:
<literallayout class='monospaced'>
# remove the commit, update working tree and remove all
# traces of the change
$ git reset --hard HEAD^
# remove the commit, but leave the files changed and staged for re-commit
$ git reset --soft HEAD^
# remove the commit, leave file change, but not staged for commit
$ git reset --mixed HEAD^
</literallayout>
</para>
<para>
You can create branches, "cherry-pick" changes, or perform any number of Git
operations until the commits are in good order for pushing upstream
or for pull requests.
After a <filename>push</filename> or <filename>pull</filename> command,
commits are normally considered
"permanent" and you should not modify them.
If the commits need to be changed, you can incrementally do so with new commits.
These practices follow standard Git workflow and the <filename>kernel.org</filename> best
practices, which is recommended.
<note>
It is recommended to tag or branch before adding changes to a Yocto Project
BSP or before creating a new one.
The reason for this recommendation is because the branch or tag provides a
reference point to facilitate locating and exporting local changes.
</note>
</para>
<section id='export-internally-via-patches'>
<title>Exporting Changes Internally by Using Patches</title>
<para>
This section describes how you can extract committed changes from a working directory
by exporting them as patches.
Once the changes have been extracted, you can use the patches for upstream submission,
place them in a Yocto Project template for automatic kernel patching,
or apply them in many other common uses.
</para>
<para>
This example shows how to create a directory with sequentially numbered patches.
Once the directory is created, you can apply it to a repository using the
<filename>git am</filename> command to reproduce the original commit and all
the related information such as author, date, commit log, and so forth.
<note>
The new commit identifiers (ID) will be generated upon re-application.
This action reflects that the commit is now applied to an underlying commit
with a different ID.
</note>
<literallayout class='monospaced'>
# &lt;first-commit&gt; can be a tag if one was created before development
# began. It can also be the parent branch if a branch was created
# before development began.
$ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
</literallayout>
</para>
<para>
In other words:
<literallayout class='monospaced'>
# Identify commits of interest.
# If the tree was tagged before development
$ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
# If no tags are available
$ git format-patch -o &lt;save dir&gt; HEAD^ # last commit
$ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
$ git whatchanged # identify last commit
$ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
$ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
</literallayout>
</para>
</section>
<section id='export-internally-via-git'>
<title>Exporting Changes Internally by Using Git</title>
<para>
This section describes how you can export changes from a working directory
by pushing the changes into a master repository or by making a pull request.
Once you have pushed the changes to the master repository, you can then
pull those same changes into a new kernel build at a later time.
</para>
<para>
Use this command form to push the changes:
<literallayout class='monospaced'>
$ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
&lt;local_branch&gt;:&lt;remote_branch&gt;
</literallayout>
</para>
<para>
For example, the following command pushes the changes from your local branch
<filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
<literallayout class='monospaced'>
$ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
yocto/standard/common-pc/base:yocto/standard/common-pc/base
</literallayout>
</para>
<para>
A pull request entails using the <filename>git request-pull</filename> command to compose
an email to the
maintainer requesting that a branch be pulled into the master repository, see
<ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
<note>
Other commands such as <filename>git stash</filename> or branching can also be used to save
changes, but are not covered in this document.
</note>
</para>
</section>
</section>
<section id='export-for-external-upstream-submission'>
<title>Exporting Changes for External (Upstream) Submission</title>
<para>
This section describes how to export changes for external upstream submission.
If the patch series is large or the maintainer prefers to pull
changes, you can submit these changes by using a pull request.
However, it is common to send patches as an email series.
This method allows easy review and integration of the changes.
<note>
Before sending patches for review be sure you understand the
community standards for submitting and documenting changes and follow their best practices.
For example, kernel patches should follow standards such as:
<itemizedlist>
<listitem><para>
<ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
<listitem><para>Documentation/SubmittingPatches (in any linux
kernel source tree)</para></listitem>
</itemizedlist>
</note>
</para>
<para>
The messages used to commit changes are a large part of these standards.
Consequently, be sure that the headers for each commit have the required information.
For information on how to follow the Yocto Project commit message standards, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
Change</ulink>" section in the Yocto Project Development Manual.
</para>
<para>
If the initial commits were not properly documented or do not meet those standards,
you can re-base by using the <filename>git rebase -i</filename> command to
manipulate the commits and
get them into the required format.
Other techniques such as branching and cherry-picking commits are also viable options.
</para>
<para>
Once you complete the commits, you can generate the email that sends the patches
to the maintainer(s) or lists that review and integrate changes.
The command <filename>git send-email</filename> is commonly used to ensure
that patches are properly
formatted for easy application and avoid mailer-induced patch damage.
</para>
<para>
The following is an example of dumping patches for external submission:
<literallayout class='monospaced'>
# dump the last 4 commits
$ git format-patch --thread -n -o ~/rr/ HEAD^^^^
$ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
--to foo@yoctoproject.org --to bar@yoctoproject.org \
--cc list@yoctoproject.org ~/rr
# the editor is invoked for the 0/N patch, and when complete the entire
# series is sent via email for review
</literallayout>
</para>
</section>
<section id='export-for-import-into-other-scm'>
<title>Exporting Changes for Import into Another SCM</title>
<para>
When you want to export changes for import into another
Source Code Manager (SCM), you can use any of the previously discussed
techniques.
However, if the patches are manually applied to a secondary tree and then
that tree is checked into the SCM, you can lose change information such as
commit logs.
This process is not recommended.
</para>
<para>
Many SCMs can directly import Git commits, or can translate Git patches so that
information is not lost.
Those facilities are SCM-dependent and you should use them whenever possible.
</para>
</section>
</section>
<section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
<title>Working with the Yocto Project Kernel in Another SCM</title>
<para>
This section describes kernel development in an SCM other than Git,
which is not the same as exporting changes to another SCM described earlier.
For this scenario, you use the OpenEmbedded build system to
develop the kernel in a different SCM.
The following must be true for you to accomplish this:
<itemizedlist>
<listitem><para>The delivered Yocto Project kernel must be exported into the second
SCM.</para></listitem>
<listitem><para>Development must be exported from that secondary SCM into a
format that can be used by the OpenEmbedded build system.</para></listitem>
</itemizedlist>
</para>
<section id='exporting-delivered-kernel-to-scm'>
<title>Exporting the Delivered Kernel to the SCM</title>
<para>
Depending on the SCM, it might be possible to export the entire Yocto Project
kernel Git repository, branches and all, into a new environment.
This method is preferred because it has the most flexibility and potential to maintain
the meta data associated with each commit.
</para>
<para>
When a direct import mechanism is not available, it is still possible to
export a branch (or series of branches) and check them into a new repository.
</para>
<para>
The following commands illustrate some of the steps you could use to
import the <filename>yocto/standard/common-pc/base</filename>
kernel into a secondary SCM:
<literallayout class='monospaced'>
$ git checkout yocto/standard/common-pc/base
$ cd .. ; echo linux/.git &gt; .cvsignore
$ cvs import -m "initial import" linux MY_COMPANY start
</literallayout>
</para>
<para>
You could now relocate the CVS repository and use it in a centralized manner.
</para>
<para>
The following commands illustrate how you can condense and merge two BSPs into a
second SCM:
<literallayout class='monospaced'>
$ git checkout yocto/standard/common-pc/base
$ git merge yocto/standard/common-pc-64/base
# resolve any conflicts and commit them
$ cd .. ; echo linux/.git &gt; .cvsignore
$ cvs import -m "initial import" linux MY_COMPANY start
</literallayout>
</para>
</section>
<section id='importing-changes-for-build'>
<title>Importing Changes for the Build</title>
<para>
Once development has reached a suitable point in the second development
environment, you need to export the changes as patches.
To export them, place the changes in a recipe and
automatically apply them to the kernel during patching.
</para>
</section>
</section>
<section id='bsp-creating'>
<title>Creating a BSP Based on an Existing Similar BSP</title>
<para>
This section overviews the process of creating a BSP based on an
existing similar BSP.
The information is introductory in nature and does not provide step-by-step examples.
For detailed information on how to create a new BSP, see
the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
Yocto Project Board Support Package (BSP) Developer's Guide, or see the
<ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
wiki page.
</para>
<para>
The basic steps you need to follow are:
<orderedlist>
<listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
You must create a local
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
by either creating a Git repository (recommended) or
extracting a Yocto Project release tarball.</para></listitem>
<listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
Try to map your board features as closely to the features of a BSP that is
already supported and exists in the Yocto Project.
Starting with something as close as possible to your board makes developing
your BSP easier.
You can find all the BSPs that are supported and ship with the Yocto Project
on the Yocto Project's Download page at
<ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
<listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
You need to either have a local Git repository of the base BSP set up or
have downloaded and extracted the files from a release BSP tarball.
Either method gives you access to the BSP source files.</para></listitem>
<listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
BSP work:</emphasis>
Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
<listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
Configuration changes involve the files in the BSP's <filename>conf</filename>
directory.
Changes include creating a machine-specific configuration file and editing the
<filename>layer.conf</filename> file.
The configuration changes identify the kernel you will be using.
Recipe changes include removing, modifying, or adding new recipe files that
instruct the build process on what features to include in the image.</para></listitem>
<listitem><para><emphasis>Prepare for the build:</emphasis>
Before you actually initiate the build, you need to set up the build environment
by sourcing the environment initialization script.
After setting up the environment, you need to make some build configuration
changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
files.</para></listitem>
<listitem><para><emphasis>Build the image:</emphasis>
The OpenEmbedded build system uses BitBake to create the image.
You need to decide on the type of image you are going to build (e.g. minimal, base,
core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
command.</para></listitem>
</orderedlist>
</para>
</section>
<section id='tip-dirty-string'>
<title>"-dirty" String</title>
<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 brute force pickup and commit 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>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->

918
documentation/kernel-dev/kernel-dev-faq.xml Normal file
View File

@ -0,0 +1,918 @@
<!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-how-to'>
<title>Working with the Yocto Project Kernel</title>
<section id='actions-org'>
<title>Introduction</title>
<para>
This chapter describes how to accomplish tasks involving a kernel's tree structure.
The information is designed to help the developer that wants to modify the Yocto
Project kernel and contribute changes upstream to the Yocto Project.
The information covers the following:
<itemizedlist>
<listitem><para>Tree construction</para></listitem>
<listitem><para>Build strategies</para></listitem>
<listitem><para>Workflow examples</para></listitem>
</itemizedlist>
</para>
</section>
<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/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.4:
<literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/linux-yocto-3.4
</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.4</filename>:
<literallayout class='monospaced'>
$ cd ~/linux-yocto-3.4
$ 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.
For examples showing how to use Git to inspect kernel commits, see the following sections
in this chapter.
<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'>
&lt;bsp_name&gt;-&lt;kernel_type&gt;.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>
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'>
&lt;kernel_type&gt;/&lt;bsp_name&gt;
</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, see
the "<link linkend='workflow-examples'>Workflow Examples</link>".
</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}-&lt;kernel_type&gt;-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 build directory in its own separate branch
of the Git repository, you can easily switch between different builds.
</para>
</section>
<section id='workflow-examples'>
<title>Workflow Examples</title>
<para>
As previously noted, the Yocto Project kernel has built-in Git integration.
However, these utilities are not the only way to work with the kernel repository.
The Yocto Project has not made changes to Git or to other tools that
would invalidate alternate workflows.
Additionally, the way the kernel repository is constructed results in using
only core Git functionality, thus allowing any number of tools or front ends to use the
resulting tree.
</para>
<para>
This section contains several workflow examples.
Many of the examples use Git commands.
You can find Git documentation at
<ulink url='http://git-scm.com/documentation'></ulink>.
You can find a simple overview of using Git with the Yocto Project in the
"<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
section of the Yocto Project Development Manual.
</para>
<section id='change-inspection-kernel-changes-commits'>
<title>Change Inspection: Changes/Commits</title>
<para>
A common question when working with a kernel is:
"What changes have been applied to this tree?"
</para>
<para>
In projects that have a collection of directories that
contain patches to the kernel, it is possible to inspect or "grep" the contents
of the directories to get a general feel for the changes.
This sort of patch inspection is not an efficient way to determine what has been
done to the kernel.
The reason it is inefficient is because there are many optional patches that are
selected based on the kernel type and the feature description.
Additionally, patches could exist in directories that are not included in the search.
</para>
<para>
A more efficient way to determine what has changed in the branch is to use
Git and inspect or search the kernel tree.
This method gives you a full view of not only the source code modifications,
but also provides the reasons for the changes.
</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.
Because Git repositories in the Yocto Project do not break existing Git
functionality, and because there exists many permutations of these types of
Git commands, many methods exist by which you can discover 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>.
For example, the branch names for the <filename>linux-yocto-3.4</filename>
kernel repository can be seen at
<ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></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 (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
</para>
<para>
Here is an example that looks at what has changed in the
<filename>emenlow</filename> branch of the
<filename>linux-yocto-3.4</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 a summary of changes use the <filename>git log</filename> command.
Here is an example using the same branches:
<literallayout class='monospaced'>
$ git log --oneline origin/standard/base..origin/standard/emenlow
</literallayout>
The <filename>git log</filename> output might be more useful than
the <filename>git whatchanged</filename> as you get
a short, one-line summary of each change and not the entire commit.
</para>
<para>
If you want to see code differences associated with all the changes, use
the <filename>git diff</filename> command.
Here is an example:
<literallayout class='monospaced'>
$ git diff origin/standard/base..origin/standard/emenlow
</literallayout>
</para>
<para>
You can see the commit log messages and the text differences using the
<filename>git show</filename> command:
Here is an example:
<literallayout class='monospaced'>
$ git show origin/standard/base..origin/standard/emenlow
</literallayout>
</para>
<para>
You can create individual patches for each change by using the
<filename>git format-patch</filename> command.
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='show-a-particular-feature-or-branch-change'>
<title>Show a Particular Feature or Branch Change</title>
<para>
Developers use tags in the Yocto Project kernel tree to divide changes for significant
features or branches.
Once you know a particular tag, you can use Git commands
to show changes associated with the tag and find the branches that contain
the feature.
<note>
Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
present, there could be many tags.
</note>
The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
a feature.
Here is an example that shows changes tagged by the <filename>systemtap</filename>
feature:
<literallayout class='monospaced'>
$ git show systemtap
</literallayout>
You can use the <filename>git branch --contains &lt;tag&gt;</filename> 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>
<para>
You can use many other comparisons to isolate BSP and kernel changes.
For example, you can compare against <filename>kernel.org</filename> tags
such as the <filename>v3.4</filename> tag.
</para>
</section>
</section>
<section id='development-saving-kernel-modifications'>
<title>Development: Saving Kernel Modifications</title>
<para>
Another common operation is to build a BSP supplied by the Yocto Project, make some
changes, rebuild, and then test.
Those local changes often need to be exported, shared or otherwise maintained.
</para>
<para>
Since the Yocto Project kernel source tree is backed by Git, this activity is
much easier as compared to with previous releases.
Because Git tracks file modifications, additions and deletions, it is easy
to modify the code and later realize that you need to save the changes.
It is also easy to determine what has changed.
This method also provides many tools to commit, undo and export those modifications.
</para>
<para>
This section and its sub-sections, describe general application of Git's
<filename>push</filename> and <filename>pull</filename> commands, which are used to
get your changes upstream or source your code from an upstream repository.
The Yocto Project provides scripts that help you work in a collaborative development
environment.
For information on these scripts, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
Upstream and Request a Pull</ulink>" and
"<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
sections in the Yocto Project Development Manual.
</para>
<para>
There are many ways to save kernel modifications.
The technique employed
depends on the destination for the patches:
<itemizedlist>
<listitem><para>Bulk storage</para></listitem>
<listitem><para>Internal sharing either through patches or by using Git</para></listitem>
<listitem><para>External submissions</para></listitem>
<listitem><para>Exporting for integration into another Source Code
Manager (SCM)</para></listitem>
</itemizedlist>
</para>
<para>
Because of the following list of issues, the destination of the patches also influences
the method for gathering them:
<itemizedlist>
<listitem><para>Bisectability</para></listitem>
<listitem><para>Commit headers</para></listitem>
<listitem><para>Division of subsystems for separate submission or review</para></listitem>
</itemizedlist>
</para>
<section id='bulk-export'>
<title>Bulk Export</title>
<para>
This section describes how you can "bulk" export changes that have not
been separated or divided.
This situation works well when you are simply storing patches outside of the kernel
source repository, either permanently or temporarily, and you are not committing
incremental changes during development.
<note>
This technique is not appropriate for full integration of upstream submission
because changes are not properly divided and do not provide an avenue for per-change
commit messages.
Therefore, this example assumes that changes have not been committed incrementally
during development and that you simply must gather and export them.
</note>
<literallayout class='monospaced'>
# bulk export of ALL modifications without separation or division
# of the changes
$ git add .
$ git commit -s -a -m &lt;msg&gt;
or
$ git commit -s -a # and interact with $EDITOR
</literallayout>
</para>
<para>
The previous operations capture all the local changes in the project source
tree in a single Git commit.
And, that commit is also stored in the project's source tree.
</para>
<para>
Once the changes are exported, you can restore them manually using a template
or through integration with the <filename>default_kernel</filename>.
</para>
</section>
<section id='incremental-planned-sharing'>
<title>Incremental/Planned Sharing</title>
<para>
This section describes how to save modifications when you are making incremental
commits or practicing planned sharing.
The examples in this section assume that you have incrementally committed
changes to the tree during development and now need to export them.
The sections that follow
describe how you can export your changes internally through either patches or by
using Git commands.
</para>
<para>
During development, the following commands are of interest.
For full Git documentation, refer to the Git documentation at
<ulink url='http://github.com'></ulink>.
<literallayout class='monospaced'>
# edit a file
$ vi &lt;path&gt;/file
# stage the change
$ git add &lt;path&gt;/file
# commit the change
$ git commit -s
# remove a file
$ git rm &lt;path&gt;/file
# commit the change
$ git commit -s
... etc.
</literallayout>
</para>
<para>
Distributed development with Git is possible when you use a universally
agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
specific change set with a specific parent.
This identifier is created for you when
you create a commit, and is re-created when you amend, alter or re-apply
a commit.
As an individual in isolation, this is of no interest.
However, if you
intend to share your tree with normal Git <filename>push</filename> and
<filename>pull</filename> operations for
distributed development, you should consider the ramifications of changing a
commit that you have already shared with others.
</para>
<para>
Assuming that the changes have not been pushed upstream, or pulled into
another repository, you can update both the commit content and commit messages
associated with development by using the following commands:
<literallayout class='monospaced'>
$ Git add &lt;path&gt;/file
$ Git commit --amend
$ Git rebase or Git rebase -i
</literallayout>
</para>
<para>
Again, assuming that the changes have not been pushed upstream, and that
no pending works-in-progress exist (use <filename>git status</filename> to check), then
you can revert (undo) commits by using the following commands:
<literallayout class='monospaced'>
# remove the commit, update working tree and remove all
# traces of the change
$ git reset --hard HEAD^
# remove the commit, but leave the files changed and staged for re-commit
$ git reset --soft HEAD^
# remove the commit, leave file change, but not staged for commit
$ git reset --mixed HEAD^
</literallayout>
</para>
<para>
You can create branches, "cherry-pick" changes, or perform any number of Git
operations until the commits are in good order for pushing upstream
or for pull requests.
After a <filename>push</filename> or <filename>pull</filename> command,
commits are normally considered
"permanent" and you should not modify them.
If the commits need to be changed, you can incrementally do so with new commits.
These practices follow standard Git workflow and the <filename>kernel.org</filename> best
practices, which is recommended.
<note>
It is recommended to tag or branch before adding changes to a Yocto Project
BSP or before creating a new one.
The reason for this recommendation is because the branch or tag provides a
reference point to facilitate locating and exporting local changes.
</note>
</para>
<section id='export-internally-via-patches'>
<title>Exporting Changes Internally by Using Patches</title>
<para>
This section describes how you can extract committed changes from a working directory
by exporting them as patches.
Once the changes have been extracted, you can use the patches for upstream submission,
place them in a Yocto Project template for automatic kernel patching,
or apply them in many other common uses.
</para>
<para>
This example shows how to create a directory with sequentially numbered patches.
Once the directory is created, you can apply it to a repository using the
<filename>git am</filename> command to reproduce the original commit and all
the related information such as author, date, commit log, and so forth.
<note>
The new commit identifiers (ID) will be generated upon re-application.
This action reflects that the commit is now applied to an underlying commit
with a different ID.
</note>
<literallayout class='monospaced'>
# &lt;first-commit&gt; can be a tag if one was created before development
# began. It can also be the parent branch if a branch was created
# before development began.
$ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
</literallayout>
</para>
<para>
In other words:
<literallayout class='monospaced'>
# Identify commits of interest.
# If the tree was tagged before development
$ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
# If no tags are available
$ git format-patch -o &lt;save dir&gt; HEAD^ # last commit
$ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
$ git whatchanged # identify last commit
$ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
$ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
</literallayout>
</para>
</section>
<section id='export-internally-via-git'>
<title>Exporting Changes Internally by Using Git</title>
<para>
This section describes how you can export changes from a working directory
by pushing the changes into a master repository or by making a pull request.
Once you have pushed the changes to the master repository, you can then
pull those same changes into a new kernel build at a later time.
</para>
<para>
Use this command form to push the changes:
<literallayout class='monospaced'>
$ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
&lt;local_branch&gt;:&lt;remote_branch&gt;
</literallayout>
</para>
<para>
For example, the following command pushes the changes from your local branch
<filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
<literallayout class='monospaced'>
$ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
yocto/standard/common-pc/base:yocto/standard/common-pc/base
</literallayout>
</para>
<para>
A pull request entails using the <filename>git request-pull</filename> command to compose
an email to the
maintainer requesting that a branch be pulled into the master repository, see
<ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
<note>
Other commands such as <filename>git stash</filename> or branching can also be used to save
changes, but are not covered in this document.
</note>
</para>
</section>
</section>
<section id='export-for-external-upstream-submission'>
<title>Exporting Changes for External (Upstream) Submission</title>
<para>
This section describes how to export changes for external upstream submission.
If the patch series is large or the maintainer prefers to pull
changes, you can submit these changes by using a pull request.
However, it is common to send patches as an email series.
This method allows easy review and integration of the changes.
<note>
Before sending patches for review be sure you understand the
community standards for submitting and documenting changes and follow their best practices.
For example, kernel patches should follow standards such as:
<itemizedlist>
<listitem><para>
<ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
<listitem><para>Documentation/SubmittingPatches (in any linux
kernel source tree)</para></listitem>
</itemizedlist>
</note>
</para>
<para>
The messages used to commit changes are a large part of these standards.
Consequently, be sure that the headers for each commit have the required information.
For information on how to follow the Yocto Project commit message standards, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
Change</ulink>" section in the Yocto Project Development Manual.
</para>
<para>
If the initial commits were not properly documented or do not meet those standards,
you can re-base by using the <filename>git rebase -i</filename> command to
manipulate the commits and
get them into the required format.
Other techniques such as branching and cherry-picking commits are also viable options.
</para>
<para>
Once you complete the commits, you can generate the email that sends the patches
to the maintainer(s) or lists that review and integrate changes.
The command <filename>git send-email</filename> is commonly used to ensure
that patches are properly
formatted for easy application and avoid mailer-induced patch damage.
</para>
<para>
The following is an example of dumping patches for external submission:
<literallayout class='monospaced'>
# dump the last 4 commits
$ git format-patch --thread -n -o ~/rr/ HEAD^^^^
$ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
--to foo@yoctoproject.org --to bar@yoctoproject.org \
--cc list@yoctoproject.org ~/rr
# the editor is invoked for the 0/N patch, and when complete the entire
# series is sent via email for review
</literallayout>
</para>
</section>
<section id='export-for-import-into-other-scm'>
<title>Exporting Changes for Import into Another SCM</title>
<para>
When you want to export changes for import into another
Source Code Manager (SCM), you can use any of the previously discussed
techniques.
However, if the patches are manually applied to a secondary tree and then
that tree is checked into the SCM, you can lose change information such as
commit logs.
This process is not recommended.
</para>
<para>
Many SCMs can directly import Git commits, or can translate Git patches so that
information is not lost.
Those facilities are SCM-dependent and you should use them whenever possible.
</para>
</section>
</section>
<section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
<title>Working with the Yocto Project Kernel in Another SCM</title>
<para>
This section describes kernel development in an SCM other than Git,
which is not the same as exporting changes to another SCM described earlier.
For this scenario, you use the OpenEmbedded build system to
develop the kernel in a different SCM.
The following must be true for you to accomplish this:
<itemizedlist>
<listitem><para>The delivered Yocto Project kernel must be exported into the second
SCM.</para></listitem>
<listitem><para>Development must be exported from that secondary SCM into a
format that can be used by the OpenEmbedded build system.</para></listitem>
</itemizedlist>
</para>
<section id='exporting-delivered-kernel-to-scm'>
<title>Exporting the Delivered Kernel to the SCM</title>
<para>
Depending on the SCM, it might be possible to export the entire Yocto Project
kernel Git repository, branches and all, into a new environment.
This method is preferred because it has the most flexibility and potential to maintain
the meta data associated with each commit.
</para>
<para>
When a direct import mechanism is not available, it is still possible to
export a branch (or series of branches) and check them into a new repository.
</para>
<para>
The following commands illustrate some of the steps you could use to
import the <filename>yocto/standard/common-pc/base</filename>
kernel into a secondary SCM:
<literallayout class='monospaced'>
$ git checkout yocto/standard/common-pc/base
$ cd .. ; echo linux/.git &gt; .cvsignore
$ cvs import -m "initial import" linux MY_COMPANY start
</literallayout>
</para>
<para>
You could now relocate the CVS repository and use it in a centralized manner.
</para>
<para>
The following commands illustrate how you can condense and merge two BSPs into a
second SCM:
<literallayout class='monospaced'>
$ git checkout yocto/standard/common-pc/base
$ git merge yocto/standard/common-pc-64/base
# resolve any conflicts and commit them
$ cd .. ; echo linux/.git &gt; .cvsignore
$ cvs import -m "initial import" linux MY_COMPANY start
</literallayout>
</para>
</section>
<section id='importing-changes-for-build'>
<title>Importing Changes for the Build</title>
<para>
Once development has reached a suitable point in the second development
environment, you need to export the changes as patches.
To export them, place the changes in a recipe and
automatically apply them to the kernel during patching.
</para>
</section>
</section>
<section id='bsp-creating'>
<title>Creating a BSP Based on an Existing Similar BSP</title>
<para>
This section overviews the process of creating a BSP based on an
existing similar BSP.
The information is introductory in nature and does not provide step-by-step examples.
For detailed information on how to create a new BSP, see
the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
Yocto Project Board Support Package (BSP) Developer's Guide, or see the
<ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
wiki page.
</para>
<para>
The basic steps you need to follow are:
<orderedlist>
<listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
You must create a local
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
by either creating a Git repository (recommended) or
extracting a Yocto Project release tarball.</para></listitem>
<listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
Try to map your board features as closely to the features of a BSP that is
already supported and exists in the Yocto Project.
Starting with something as close as possible to your board makes developing
your BSP easier.
You can find all the BSPs that are supported and ship with the Yocto Project
on the Yocto Project's Download page at
<ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
<listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
You need to either have a local Git repository of the base BSP set up or
have downloaded and extracted the files from a release BSP tarball.
Either method gives you access to the BSP source files.</para></listitem>
<listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
BSP work:</emphasis>
Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
<listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
Configuration changes involve the files in the BSP's <filename>conf</filename>
directory.
Changes include creating a machine-specific configuration file and editing the
<filename>layer.conf</filename> file.
The configuration changes identify the kernel you will be using.
Recipe changes include removing, modifying, or adding new recipe files that
instruct the build process on what features to include in the image.</para></listitem>
<listitem><para><emphasis>Prepare for the build:</emphasis>
Before you actually initiate the build, you need to set up the build environment
by sourcing the environment initialization script.
After setting up the environment, you need to make some build configuration
changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
files.</para></listitem>
<listitem><para><emphasis>Build the image:</emphasis>
The OpenEmbedded build system uses BitBake to create the image.
You need to decide on the type of image you are going to build (e.g. minimal, base,
core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
command.</para></listitem>
</orderedlist>
</para>
</section>
<section id='tip-dirty-string'>
<title>"-dirty" String</title>
<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 brute force pickup and commit 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>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->

78
documentation/kernel-dev/kernel-dev-intro.xml Normal file
View File

@ -0,0 +1,78 @@
<!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-doc-intro'>
<title>Yocto Project Kernel Architecture and Use Manual</title>
<section id='kernel-intro-section'>
<title>Introduction</title>
<para>
The Yocto Project presents kernels as a fully patched, history-clean Git
repositories.
Each repository represents selected features, board support,
and configurations extensively tested by the Yocto Project.
Yocto Project kernels allow the end user to leverage community
best practices to seamlessly manage the development, build and debug cycles.
</para>
<para>
This manual describes Yocto Project kernels by providing information
on history, organization, benefits, and use.
The manual consists of two sections:
<itemizedlist>
<listitem><para><emphasis>Concepts:</emphasis> Describes concepts behind a kernel.
You will understand how a kernel is organized and why it is organized in
the way it is. You will understand the benefits of a kernel's organization
and the mechanisms used to work with the kernel and how to apply it in your
design process.</para></listitem>
<listitem><para><emphasis>Using a Kernel:</emphasis> Describes best practices
and "how-to" information
that lets you put a kernel to practical use.
Some examples are how to examine changes in a branch and how to
save kernel modifications.</para></listitem>
</itemizedlist>
</para>
<para>
For more information on the Linux kernel, see the following links:
<itemizedlist>
<listitem><para>The Linux Foundation's guide for kernel development
process - <ulink url='http://www.linuxfoundation.org/content/1-guide-kernel-development-process'></ulink></para></listitem>
<listitem><para>A fairly encompassing guide on Linux kernel development -
<ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem>
</itemizedlist>
</para>
<para>
For more discussion on the Yocto Project kernel, you can see these sections
in the Yocto Project Development Manual:
<itemizedlist>
<listitem><para>
"<ulink url='&YOCTO_DOCS_DEV_URL;#kernel-overview'>Kernel Overview</ulink>"</para></listitem>
<listitem><para>
"<ulink url='&YOCTO_DOCS_DEV_URL;#kernel-modification-workflow'>Kernel Modification Workflow</ulink>"
</para></listitem>
<listitem><para>
"<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"</para></listitem>
<listitem><para>
"<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"</para></listitem>
</itemizedlist>
</para>
<para>
For general information on the Yocto Project, visit the website at
<ulink url='&YOCTO_HOME_URL;'></ulink>.
</para>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->

979
documentation/kernel-dev/kernel-dev-style.css Normal file
View File

@ -0,0 +1,979 @@
/*
Generic XHTML / DocBook XHTML CSS Stylesheet.
Browser wrangling and typographic design by
Oyvind Kolas / pippin@gimp.org
Customised for Poky by
Matthew Allum / mallum@o-hand.com
Thanks to:
Liam R. E. Quin
William Skaggs
Jakub Steiner
Structure
---------
The stylesheet is divided into the following sections:
Positioning
Margins, paddings, width, font-size, clearing.
Decorations
Borders, style
Colors
Colors
Graphics
Graphical backgrounds
Nasty IE tweaks
Workarounds needed to make it work in internet explorer,
currently makes the stylesheet non validating, but up until
this point it is validating.
Mozilla extensions
Transparency for footer
Rounded corners on boxes
*/
/*************** /
/ Positioning /
/ ***************/
body {
font-family: Verdana, Sans, sans-serif;
min-width: 640px;
width: 80%;
margin: 0em auto;
padding: 2em 5em 5em 5em;
color: #333;
}
h1,h2,h3,h4,h5,h6,h7 {
font-family: Arial, Sans;
color: #00557D;
clear: both;
}
h1 {
font-size: 2em;
text-align: left;
padding: 0em 0em 0em 0em;
margin: 2em 0em 0em 0em;
}
h2.subtitle {
margin: 0.10em 0em 3.0em 0em;
padding: 0em 0em 0em 0em;
font-size: 1.8em;
padding-left: 20%;
font-weight: normal;
font-style: italic;
}
h2 {
margin: 2em 0em 0.66em 0em;
padding: 0.5em 0em 0em 0em;
font-size: 1.5em;
font-weight: bold;
}
h3.subtitle {
margin: 0em 0em 1em 0em;
padding: 0em 0em 0em 0em;
font-size: 142.14%;
text-align: right;
}
h3 {
margin: 1em 0em 0.5em 0em;
padding: 1em 0em 0em 0em;
font-size: 140%;
font-weight: bold;
}
h4 {
margin: 1em 0em 0.5em 0em;
padding: 1em 0em 0em 0em;
font-size: 120%;
font-weight: bold;
}
h5 {
margin: 1em 0em 0.5em 0em;
padding: 1em 0em 0em 0em;
font-size: 110%;
font-weight: bold;
}
h6 {
margin: 1em 0em 0em 0em;
padding: 1em 0em 0em 0em;
font-size: 110%;
font-weight: bold;
}
.authorgroup {
background-color: transparent;
background-repeat: no-repeat;
padding-top: 256px;
background-image: url("figures/kernel-title.png");
background-position: left top;
margin-top: -256px;
padding-right: 50px;
margin-left: 0px;
text-align: right;
width: 740px;
}
h3.author {
margin: 0em 0me 0em 0em;
padding: 0em 0em 0em 0em;
font-weight: normal;
font-size: 100%;
color: #333;
clear: both;
}
.author tt.email {
font-size: 66%;
}
.titlepage hr {
width: 0em;
clear: both;
}
.revhistory {
padding-top: 2em;
clear: both;
}
.toc,
.list-of-tables,
.list-of-examples,
.list-of-figures {
padding: 1.33em 0em 2.5em 0em;
color: #00557D;
}
.toc p,
.list-of-tables p,
.list-of-figures p,
.list-of-examples p {
padding: 0em 0em 0em 0em;
padding: 0em 0em 0.3em;
margin: 1.5em 0em 0em 0em;
}
.toc p b,
.list-of-tables p b,
.list-of-figures p b,
.list-of-examples p b{
font-size: 100.0%;
font-weight: bold;
}
.toc dl,
.list-of-tables dl,
.list-of-figures dl,
.list-of-examples dl {
margin: 0em 0em 0.5em 0em;
padding: 0em 0em 0em 0em;
}
.toc dt {
margin: 0em 0em 0em 0em;
padding: 0em 0em 0em 0em;
}
.toc dd {
margin: 0em 0em 0em 2.6em;
padding: 0em 0em 0em 0em;
}
div.glossary dl,
div.variablelist dl {
}
.glossary dl dt,
.variablelist dl dt,
.variablelist dl dt span.term {
font-weight: normal;
width: 20em;
text-align: right;
}
.variablelist dl dt {
margin-top: 0.5em;
}
.glossary dl dd,
.variablelist dl dd {
margin-top: -1em;
margin-left: 25.5em;
}
.glossary dd p,
.variablelist dd p {
margin-top: 0em;
margin-bottom: 1em;
}
div.calloutlist table td {
padding: 0em 0em 0em 0em;
margin: 0em 0em 0em 0em;
}
div.calloutlist table td p {
margin-top: 0em;
margin-bottom: 1em;
}
div p.copyright {
text-align: left;
}
div.legalnotice p.legalnotice-title {
margin-bottom: 0em;
}
p {
line-height: 1.5em;
margin-top: 0em;
}
dl {
padding-top: 0em;
}
hr {
border: solid 1px;
}
.mediaobject,
.mediaobjectco {
text-align: center;
}
img {
border: none;
}
ul {
padding: 0em 0em 0em 1.5em;
}
ul li {
padding: 0em 0em 0em 0em;
}
ul li p {
text-align: left;
}
table {
width :100%;
}
th {
padding: 0.25em;
text-align: left;
font-weight: normal;
vertical-align: top;
}
td {
padding: 0.25em;
vertical-align: top;
}
p a[id] {
margin: 0px;
padding: 0px;
display: inline;
background-image: none;
}
a {
text-decoration: underline;
color: #444;
}
pre {
overflow: auto;
}
a:hover {
text-decoration: underline;
/*font-weight: bold;*/
}
div.informalfigure,
div.informalexample,
div.informaltable,
div.figure,
div.table,
div.example {
margin: 1em 0em;
padding: 1em;
page-break-inside: avoid;
}
div.informalfigure p.title b,
div.informalexample p.title b,
div.informaltable p.title b,
div.figure p.title b,
div.example p.title b,
div.table p.title b{
padding-top: 0em;
margin-top: 0em;
font-size: 100%;
font-weight: normal;
}
.mediaobject .caption,
.mediaobject .caption p {
text-align: center;
font-size: 80%;
padding-top: 0.5em;
padding-bottom: 0.5em;
}
.epigraph {
padding-left: 55%;
margin-bottom: 1em;
}
.epigraph p {
text-align: left;
}
.epigraph .quote {
font-style: italic;
}
.epigraph .attribution {
font-style: normal;
text-align: right;
}
span.application {
font-style: italic;
}
.programlisting {
font-family: monospace;
font-size: 80%;
white-space: pre;
margin: 1.33em 0em;
padding: 1.33em;
}
.tip,
.warning,
.caution,
.note {
margin-top: 1em;
margin-bottom: 1em;
}
/* force full width of table within div */
.tip table,
.warning table,
.caution table,
.note table {
border: none;
width: 100%;
}
.tip table th,
.warning table th,
.caution table th,
.note table th {
padding: 0.8em 0.0em 0.0em 0.0em;
margin : 0em 0em 0em 0em;
}
.tip p,
.warning p,
.caution p,
.note p {
margin-top: 0.5em;
margin-bottom: 0.5em;
padding-right: 1em;
text-align: left;
}
.acronym {
text-transform: uppercase;
}
b.keycap,
.keycap {
padding: 0.09em 0.3em;
margin: 0em;
}
.itemizedlist li {
clear: none;
}
.filename {
font-size: medium;
font-family: Courier, monospace;
}
div.navheader, div.heading{
position: absolute;
left: 0em;
top: 0em;
width: 100%;
background-color: #cdf;
width: 100%;
}
div.navfooter, div.footing{
position: fixed;
left: 0em;
bottom: 0em;
background-color: #eee;
width: 100%;
}
div.navheader td,
div.navfooter td {
font-size: 66%;
}
div.navheader table th {
/*font-family: Georgia, Times, serif;*/
/*font-size: x-large;*/
font-size: 80%;
}
div.navheader table {
border-left: 0em;
border-right: 0em;
border-top: 0em;
width: 100%;
}
div.navfooter table {
border-left: 0em;
border-right: 0em;
border-bottom: 0em;
width: 100%;
}
div.navheader table td a,
div.navfooter table td a {
color: #777;
text-decoration: none;
}
/* normal text in the footer */
div.navfooter table td {
color: black;
}
div.navheader table td a:visited,
div.navfooter table td a:visited {
color: #444;
}
/* links in header and footer */
div.navheader table td a:hover,
div.navfooter table td a:hover {
text-decoration: underline;
background-color: transparent;
color: #33a;
}
div.navheader hr,
div.navfooter hr {
display: none;
}
.qandaset tr.question td p {
margin: 0em 0em 1em 0em;
padding: 0em 0em 0em 0em;
}
.qandaset tr.answer td p {
margin: 0em 0em 1em 0em;
padding: 0em 0em 0em 0em;
}
.answer td {
padding-bottom: 1.5em;
}
.emphasis {
font-weight: bold;
}
/************* /
/ decorations /
/ *************/
.titlepage {
}
.part .title {
}
.subtitle {
border: none;
}
/*
h1 {
border: none;
}
h2 {
border-top: solid 0.2em;
border-bottom: solid 0.06em;
}
h3 {
border-top: 0em;
border-bottom: solid 0.06em;
}
h4 {
border: 0em;
border-bottom: solid 0.06em;
}
h5 {
border: 0em;
}
*/
.programlisting {
border: solid 1px;
}
div.figure,
div.table,
div.informalfigure,
div.informaltable,
div.informalexample,
div.example {
border: 1px solid;
}
.tip,
.warning,
.caution,
.note {
border: 1px solid;
}
.tip table th,
.warning table th,
.caution table th,
.note table th {
border-bottom: 1px solid;
}
.question td {
border-top: 1px solid black;
}
.answer {
}
b.keycap,
.keycap {
border: 1px solid;
}
div.navheader, div.heading{
border-bottom: 1px solid;
}
div.navfooter, div.footing{
border-top: 1px solid;
}
/********* /
/ colors /
/ *********/
body {
color: #333;
background: white;
}
a {
background: transparent;
}
a:hover {
background-color: #dedede;
}
h1,
h2,
h3,
h4,
h5,
h6,
h7,
h8 {
background-color: transparent;
}
hr {
border-color: #aaa;
}
.tip, .warning, .caution, .note {
border-color: #fff;
}
.tip table th,
.warning table th,
.caution table th,
.note table th {
border-bottom-color: #fff;
}
.warning {
background-color: #f0f0f2;
}
.caution {
background-color: #f0f0f2;
}
.tip {
background-color: #f0f0f2;
}
.note {
background-color: #f0f0f2;
}
.glossary dl dt,
.variablelist dl dt,
.variablelist dl dt span.term {
color: #044;
}
div.figure,
div.table,
div.example,
div.informalfigure,
div.informaltable,
div.informalexample {
border-color: #aaa;
}
pre.programlisting {
color: black;
background-color: #fff;
border-color: #aaa;
border-width: 2px;
}
.guimenu,
.guilabel,
.guimenuitem {
background-color: #eee;
}
b.keycap,
.keycap {
background-color: #eee;
border-color: #999;
}
div.navheader {
border-color: black;
}
div.navfooter {
border-color: black;
}
/*********** /
/ graphics /
/ ***********/
/*
body {
background-image: url("images/body_bg.jpg");
background-attachment: fixed;
}
.navheader,
.note,
.tip {
background-image: url("images/note_bg.jpg");
background-attachment: fixed;
}
.warning,
.caution {
background-image: url("images/warning_bg.jpg");
background-attachment: fixed;
}
.figure,
.informalfigure,
.example,
.informalexample,
.table,
.informaltable {
background-image: url("images/figure_bg.jpg");
background-attachment: fixed;
}
*/
h1,
h2,
h3,
h4,
h5,
h6,
h7{
}
/*
Example of how to stick an image as part of the title.
div.article .titlepage .title
{
background-image: url("figures/white-on-black.png");
background-position: center;
background-repeat: repeat-x;
}
*/
div.preface .titlepage .title,
div.colophon .title,
div.chapter .titlepage .title,
div.article .titlepage .title
{
}
div.section div.section .titlepage .title,
div.sect2 .titlepage .title {
background: none;
}
h1.title {
background-color: transparent;
background-image: url("figures/yocto-project-bw.png");
background-repeat: no-repeat;
height: 256px;
text-indent: -9000px;
overflow:hidden;
}
h2.subtitle {
background-color: transparent;
text-indent: -9000px;
overflow:hidden;
width: 0px;
display: none;
}
/*************************************** /
/ pippin.gimp.org specific alterations /
/ ***************************************/
/*
div.heading, div.navheader {
color: #777;
font-size: 80%;
padding: 0;
margin: 0;
text-align: left;
position: absolute;
top: 0px;
left: 0px;
width: 100%;
height: 50px;
background: url('/gfx/heading_bg.png') transparent;
background-repeat: repeat-x;
background-attachment: fixed;
border: none;
}
div.heading a {
color: #444;
}
div.footing, div.navfooter {
border: none;
color: #ddd;
font-size: 80%;
text-align:right;
width: 100%;
padding-top: 10px;
position: absolute;
bottom: 0px;
left: 0px;
background: url('/gfx/footing_bg.png') transparent;
}
*/
/****************** /
/ nasty ie tweaks /
/ ******************/
/*
div.heading, div.navheader {
width:expression(document.body.clientWidth + "px");
}
div.footing, div.navfooter {
width:expression(document.body.clientWidth + "px");
margin-left:expression("-5em");
}
body {
padding:expression("4em 5em 0em 5em");
}
*/
/**************************************** /
/ mozilla vendor specific css extensions /
/ ****************************************/
/*
div.navfooter, div.footing{
-moz-opacity: 0.8em;
}
div.figure,
div.table,
div.informalfigure,
div.informaltable,
div.informalexample,
div.example,
.tip,
.warning,
.caution,
.note {
-moz-border-radius: 0.5em;
}
b.keycap,
.keycap {
-moz-border-radius: 0.3em;
}
*/
table tr td table tr td {
display: none;
}
hr {
display: none;
}
table {
border: 0em;
}
.photo {
float: right;
margin-left: 1.5em;
margin-bottom: 1.5em;
margin-top: 0em;
max-width: 17em;
border: 1px solid gray;
padding: 3px;
background: white;
}
.seperator {
padding-top: 2em;
clear: both;
}
#validators {
margin-top: 5em;
text-align: right;
color: #777;
}
@media print {
body {
font-size: 8pt;
}
.noprint {
display: none;
}
}
.tip,
.note {
background: #f0f0f2;
color: #333;
padding: 20px;
margin: 20px;
}
.tip h3,
.note h3 {
padding: 0em;
margin: 0em;
font-size: 2em;
font-weight: bold;
color: #333;
}
.tip a,
.note a {
color: #333;
text-decoration: underline;
}
.footnote {
font-size: small;
color: #333;
}
/* Changes the announcement text */
.tip h3,
.warning h3,
.caution h3,
.note h3 {
font-size:large;
color: #00557D;
}

104
documentation/kernel-dev/kernel-dev.xml Normal file
View File

@ -0,0 +1,104 @@
<!DOCTYPE book 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; ] >
<book id='kernel-manual' lang='en'
xmlns:xi="http://www.w3.org/2003/XInclude"
xmlns="http://docbook.org/ns/docbook"
>
<bookinfo>
<mediaobject>
<imageobject>
<imagedata fileref='figures/kernel-title.png'
format='SVG'
align='left' scalefit='1' width='100%'/>
</imageobject>
</mediaobject>
<title></title>
<authorgroup>
<author>
<firstname>Bruce</firstname> <surname>Ashfield</surname>
<affiliation>
<orgname>Wind River Corporation</orgname>
</affiliation>
<email>bruce.ashfield@windriver.com</email>
</author>
</authorgroup>
<revhistory>
<revision>
<revnumber>0.9</revnumber>
<date>24 November 2010</date>
<revremark>The initial document draft released with the Yocto Project 0.9 Release.</revremark>
</revision>
<revision>
<revnumber>1.0</revnumber>
<date>6 April 2011</date>
<revremark>Released with the Yocto Project 1.0 Release.</revremark>
</revision>
<revision>
<revnumber>1.0.1</revnumber>
<date>23 May 2011</date>
<revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
</revision>
<revision>
<revnumber>1.1</revnumber>
<date>6 October 2011</date>
<revremark>Released with the Yocto Project 1.1 Release.</revremark>
</revision>
<revision>
<revnumber>1.2</revnumber>
<date>April 2012</date>
<revremark>Released with the Yocto Project 1.2 Release.</revremark>
</revision>
<revision>
<revnumber>1.3</revnumber>
<date>October 2012</date>
<revremark>Released with the Yocto Project 1.3 Release.</revremark>
</revision>
<revision>
<revnumber>1.4</revnumber>
<date>Sometime in 2013</date>
<revremark>Released with the Yocto Project 1.4 Release.</revremark>
</revision>
</revhistory>
<copyright>
<year>&COPYRIGHT_YEAR;</year>
<holder>Linux Foundation</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this document under
the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
</para>
<note>
Due to production processes, there could be differences between the Yocto Project
documentation bundled in the release tarball and the
<ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink> on
the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
For the latest version of this manual, see the manual on the website.
</note>
</legalnotice>
</bookinfo>
<xi:include href="kernel-doc-intro.xml"/>
<xi:include href="kernel-concepts.xml"/>
<xi:include href="kernel-how-to.xml"/>
<!-- <index id='index'>
<title>Index</title>
</index>
-->
</book>
<!--
vim: expandtab tw=80 ts=4
-->