aboutsummaryrefslogtreecommitdiffstats
path: root/documentation/kernel-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-manual')
-rw-r--r--documentation/kernel-manual/kernel-concepts.xml194
-rw-r--r--documentation/kernel-manual/kernel-doc-intro.xml28
-rw-r--r--documentation/kernel-manual/kernel-how-to.xml1691
3 files changed, 351 insertions, 1562 deletions
diff --git a/documentation/kernel-manual/kernel-concepts.xml b/documentation/kernel-manual/kernel-concepts.xml
index eede5a2e59..bcda78c4e1 100644
--- a/documentation/kernel-manual/kernel-concepts.xml
+++ b/documentation/kernel-manual/kernel-concepts.xml
@@ -46,12 +46,14 @@
the baseline kernel is the most stable official release.</para></listitem>
<listitem><para>Include major technological features as part of Yocto Project's up-rev
strategy.</para></listitem>
- <listitem><para>Present a Git tree, that just like the upstream kernel.org tree, has a
- clear and continuous history.</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 a specific use case (i.e. networking, consumer, devices, and so forth).</para></listitem>
- <listitem><para>Employ a Git branching strategy that from a customer's point of view
- results in a linear path from the baseline kernel.org, through a select group of features and
+ to a specific use case (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>
@@ -60,27 +62,29 @@
<section id='kernel-big-picture'>
<title>Yocto Project Kernel Development and Maintenance Overview</title>
<para>
- Yocto Project kernel, like other kernels, is based off the Linux kernel release
+ The Yocto Project kernel, like other kernels, is based off the Linux kernel release
from <ulink url='http://www.kernel.org'></ulink>.
- At the beginning of our major development cycle, we choose our Yocto Project kernel
- based on factors like release timing, the anticipated release timing of "final" (i.e. non "rc")
- upstream kernel.org versions, and Yocto Project feature requirements.
- Typically this will be a kernel that is in the
- final stages of development by the community (i.e. still in the release
- candidate or "rc" phase) and not yet a final release.
- But by being in the final stages of external development, we know that the
- kernel.org final release will clearly land within the early stages of
+ At the beginning of a major development cycle, the Yocto Project team
+ chooses its Yocto Project kernel
+ based on factors like 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 us to deliver the most up-to-date kernel
- as possible, while still ensuring that we have a stable official release as
- our baseline kernel version.
+ This balance allows the team to deliver the most up-to-date kernel
+ as possible, while still ensuring that the team has a stable official release as
+ the baseline kernel version.
</para>
<para>
The ultimate source for the Yocto Project kernel is a released kernel
- from kernel.org.
- In addition to a foundational kernel from kernel.org the released
+ from <filename>kernel.org</filename>.
+ In addition to a foundational kernel from <filename>kernel.org</filename>, the released
Yocto Project kernel contains a mix of important new mainline
developments, non-mainline developments (when there is no alternative),
Board Support Package (BSP) developments,
@@ -88,37 +92,21 @@
These additions result in a commercially released Yocto Project kernel that caters
to specific embedded designer needs for targeted hardware.
</para>
-<!-- <para>
- The following figure represents the overall place the Yocto Project kernel fills.
- </para>
- <para>
- <imagedata fileref="figures/kernel-big-picture.png" width="6in" depth="6in" align="center" scale="100" />
- </para>
- <para>
- In the figure the ultimate source for the Yocto Project kernel is a released kernel
- from kernel.org.
- In addition to a foundational kernel from kernel.org the commercially released
- Yocto Project kernel contains a mix of important new mainline
- developments, non-mainline developments, Board Support Package (BSP) developments,
- and custom features.
- These additions result in a commercially released Yocto Project kernel that caters
- to specific embedded designer needs for targeted hardware.
- </para> -->
<para>
- Once a Yocto Project kernel is officially released the Yocto Project team goes into
- their next development cycle, or "uprev" cycle while continuing maintenance on the
+ Once a Yocto Project kernel is officially released, the Yocto Project team goes into
+ their next development cycle, or "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 of hundreds of individual fixes and minor features from various
- kernel versions is not sustainable and can easily compromise quality.
+ 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 kernel.org version.
+ possible <filename>kernel.org</filename> version.
The team continually monitors community kernel
development to look for significant features of interest.
-<!-- The illustration depicts this by showing the team looking back to kernel.org for new features,
- BSP features, and significant bug fixes. -->
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.
@@ -130,7 +118,7 @@
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 simply back-porting any small to medium sized change
+ 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>
@@ -163,18 +151,23 @@
As mentioned earlier, a key goal of 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 kernel.org.
-
+ upstream <filename>kernel.org</filename>.
</para>
<para>
You can think of the Yocto Project kernel as consisting of a baseline 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.
+ source code manager (SCM) Git.
+ For information on Git as applied to the Yocto Project, see the
+ "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#git'>Git</ulink>"
+ section in <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The
+ Yocto Project Development Manual</ulink>.
+ </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 as well.
+ made up the baseline kernel.
</para>
<para>
The following illustration shows the conceptual Yocto Project kernel.
@@ -183,18 +176,20 @@
<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.
+ In the illustration, the "<filename>kernel.org</filename> 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
+ 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
+ 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.
@@ -209,8 +204,9 @@
kernel as they apply to a given BSP.
</para>
<para>
- The resulting tree structure presents a clear path of markers (or branches) to the user
- that for all practical purposes is the kernel needed for any given set of requirements.
+ 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>
@@ -221,50 +217,52 @@
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.
+ 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 results in not having to store the same feature twice internally in the
- tree.
- Rather we store the unique differences required to apply the feature onto the kernel type
- in question.
+ 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>
- <note><para>
- 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 this practice
- cannot always be followed.
- In those cases isolated branches are used for feature merging.
- </para></note>
<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, we create branches off the end of that kernel type for all
+ 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, only the unique differences for the BSP across
- the supported multiple kernels are uniquely stored.
+ 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 user's point of view, there is a linear
- path that travels from the baseline kernel.org, through a select group of features and
- ends with their BSP-specific commits.
+ 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 user's perspective, this is the "master" branch.
- They do not need not be aware of the existence of any other branches at all.
- Of course there is value in the existence of these branches
+ From the developer's perspective, this path is the "master" branch.
+ The developer does not need not 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 diff level is now a trivial operation.
+ 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
+ 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.
@@ -273,7 +271,7 @@
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 user
+ 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>
@@ -281,20 +279,26 @@
<section id='source-code-manager-git'>
<title>Source Code Manager - Git</title>
<para>
- The Source Code Manager (SCM) is Git and it is the obvious mechanism for meeting the
- previously mentioned goals.
- Not only is it the SCM for kernel.org but Git continues to grow in popularity and
- supports many different work flows, front-ends and management techniques.
+ 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>.
- Also, the Yocto Project Development manual has an introduction to Git and describes a
- minimal set of commands that allow you to be functional with Git.
+ You can also get an introduction to Git as it applies to the Yocto Project in the
+ "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#git'>Git</ulink>"
+ section in <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The
+ Yocto Project Development Manual</ulink>.
+ This section overviews Git and describes a minimal set of commands that allow 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>
- <note><para>
- It should be noted that you can use as much, or as little, of what Git has to offer
- as is appropriate to your project.
- </para></note>
</section>
</section>
@@ -307,17 +311,19 @@
present a simplified view of the kernel for ease of use.
</para>
<para>
- The fundamental properties of the tools that manage and construct the
- Yocto Project kernel are:
+ 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 configuration to kernel patches and 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 kernel.org history and development.</para></listitem>
+ with the <filename>kernel.org</filename> history and development.</para></listitem>
</itemizedlist>
</para>
<!--<para>
+WRITER NOTE: Put this in for post 1.1 if possible:
+
The tools that construct a kernel tree will be discussed later in this
document. The following tools form the foundation of the Yocto Project
kernel toolkit:
diff --git a/documentation/kernel-manual/kernel-doc-intro.xml b/documentation/kernel-manual/kernel-doc-intro.xml
index e119068393..a9e51725da 100644
--- a/documentation/kernel-manual/kernel-doc-intro.xml
+++ b/documentation/kernel-manual/kernel-doc-intro.xml
@@ -20,17 +20,20 @@
on its history, organization, benefits, and use.
The manual consists of two sections:
<itemizedlist>
- <listitem><para>Concepts - Describes concepts behind the kernel.
+ <listitem><para><emphasis>Concepts:</emphasis> Describes concepts behind the kernel.
You will understand how the kernel is organized and why it is organized in
the way it is. You will understand the benefits of the 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>Using the Kernel - Describes best practices and "how-to" information
- that lets you put the kernel to practical use. Some examples are "How to Build a
- Project Specific Tree", "How to Examine Changes in a Branch", and "Saving Kernel
- Modifications."</para></listitem>
+ <listitem><para><emphasis>Using the Kernel:</emphasis> Describes best practices
+ and "how-to" information
+ that lets you put the kernel to practical use.
+ Some examples are "How to Build a
+ Project Specific Tree", "How to Examine Changes in a Branch", and "How to
+ Save Kernel Modifications."</para></listitem>
</itemizedlist>
</para>
+
<para>
For more information on the kernel, see the following links:
<itemizedlist>
@@ -38,10 +41,19 @@
<listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem>
<listitem><para><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>
- You can find more information on Yocto Project by visiting the website at
+ </para>
+
+ <para>
+ For more discussion on the Yocto Project kernel, you can also see the
+ "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#kernel-overview'>Kernel Overview</ulink>",
+ "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#kernel-modification-workflow'>Kernel Modification Workflow</ulink>", and
+ "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#dev-manual-kernel-appendix'>Kernel Modification Example</ulink>" sections all in
+ <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The Yocto Project Development Manual</ulink>.
+ </para>
+
+ <para>
+ For general information on the Yocto Project, visit the website at
<ulink url='http://www.yoctoproject.org'></ulink>.
- </para>
</para>
</section>
diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
index 86e455357a..e62cfad655 100644
--- a/documentation/kernel-manual/kernel-how-to.xml
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -16,18 +16,7 @@
<itemizedlist>
<listitem><para>Tree construction</para></listitem>
<listitem><para>Build strategies</para></listitem>
-<!-- <listitem><para>Series &amp; Configuration Compiler</para></listitem>
- <listitem><para>kgit</para></listitem> -->
<listitem><para>Workflow examples</para></listitem>
-<!-- <listitem><para>Source Code Manager (SCM)</para></listitem>
- <listitem><para>Board Support Package (BSP) template migration</para></listitem>
- <listitem><para>BSP creation</para></listitem>
- <listitem><para>Patching</para></listitem>
- <listitem><para>Updating BSP patches and configuration</para></listitem>
- <listitem><para>guilt</para></listitem>
- <listitem><para>scc file example</para></listitem>
- <listitem><para>"dirty" string</para></listitem>
- <listitem><para>Transition kernel layer</para></listitem> -->
</itemizedlist>
</para>
</section>
@@ -35,65 +24,73 @@
<section id='tree-construction'>
<title>Tree Construction</title>
<para>
- The Yocto Project kernel repository, as shipped with the product, is created by
+ This section describes construction of the Yocto Project kernel repositories as accomplished
+ by the Yocto Project team to create kernel repositories, which are found at
+ <ulink url='http://git.yoctoproject.org/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>,
+ that 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 the kernel.
Thus, the Yocto Project kernel repository (or tree) is built.
- The existence of this tree allows you to build images based on your configurations
+ </para>
+ <para>
+ The existence of this tree allows you to access and clone a particular
+ Linux Yocto 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 kernel Git tree.
+ You can find the files used to describe all the valid features and BSPs
+ in the Yocto Project kernel in any clone of the Linux Yocto kernel source repository Git tree.
For example, the following command clones the Yocto Project baseline kernel that
- branched off of linux.org version 2.6.37:
+ branched off of <filename>linux.org</filename> version 3.0:
<literallayout class='monospaced'>
- $ git clone http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37
- </literallayout>
- After you switch to the <filename>meta</filename> branch within the repository
- you can see a snapshot of all the kernel configuration and feature descriptions that are
+ $ git clone git://git.yoctoproject.org/linux-yocto-3.0
+ </literallayout>
+ For another example of how to set up a local Git repository of the Linux Yocto
+ kernel files, see the
+ "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#local-kernel-files'>Linux Yocto Kernel</ulink>" bulleted item in
+ <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The Yocto Project Development Manual</ulink>.
+ </para>
+ <para>
+ Once the Git repository is set up on your local machine, you can switch to the
+ <filename>meta</filename> branch within the repository.
+ Here, you can see a snapshot of all the kernel configuration and feature descriptions that are
used to build the kernel repository.
These descriptions are in the form of <filename>.scc</filename> files.
</para>
<para>
- You should realize, however, that browsing the snapshot of feature
+ You should realize, however, that browsing your local snapshot of 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.
+ 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>
- <note><para>
- Ground up reconstruction of the complete kernel tree is an action only taken by the
- Yocto Project team during an active development cycle.
- Creating a project simply clones this tree to make it efficiently available for building
- and development.
- </para></note>
<para>
- The following steps describe what happens during tree construction given the introduction
- of a new top-level kernel feature or BSP.
+ The following steps describe what happens when the Yocto kernel team constructs
+ the kernel tree 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 is a BSP for a particular kernel type.</para></listitem>
-
+ 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>kernel-*-cache directories in layers</para></listitem> -->
<listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
found in recipes</para></listitem>
-<!-- <listitem><para>configured and default templates</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:
@@ -101,85 +98,60 @@
&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 <filename>KERNEL_FEATURES</filename> 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 meta-series.
- The meta-series is a description of all the branches, tags, patches and configurations that
+ <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 meta-series are applied to the tree.</para></listitem>
-
+ 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 tree is now ready for configuration and compilation.
+ The kernel tree is now ready for developer consumption to be locally cloned,
+ configured, and built into a Linux Yocto 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='http://git.yoctoproject.org/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 deployment specific patches.
+ Any additions to the kernel become an integrated part of the branches.</para>
+ </note>
</para>
-
- <note><para>The end-user generated meta-series adds to the kernel as shipped with
- the Yocto Project release.
- Any add-ons and configuration data are applied to the end of an existing branch.
- The full repository generation that is found in the
- official Yocto Project kernel repositories is the combination of all
- supported boards and configurations.</para>
-
- <para>This technique is flexible and allows for seamless blending of an immutable
- history with additional deployment specific patches.
- Any additions to the kernel become an integrated part of the branches.
- </para></note>
-
-<!-- <note><para>It is key that feature descriptions indicate if any branches are
- required, since the build system cannot automatically decide where a
- BSP should branch or if that branch point needs a name with
- significance. There is a single restriction enforced by the compilation
- phase:
- </para>
- <para>A BSP must create a branch of the format &lt;bsp name&gt;-&lt;kernel type&gt;.</para>
-
- <para>This means that all merged/support BSPs must indicate where to start
- its branch from, with the right name, in its .scc files. The scc
- section describes the available branching commands in more detail.
- </para>
-</note> -->
-
-<!-- <para>
-A summary of end user tree construction activities follow:
-<itemizedlist>
- <listitem><para>compile and link a full top-down kernel description from feature descriptions</para></listitem>
- <listitem><para>execute the complete description to generate a meta-series</para></listitem>
- <listitem><para>interpret the meta-series to create a customized Git repository for the
- board</para></listitem>
- <listitem><para>migrate configuration fragments and configure the kernel</para></listitem>
- <listitem><para>checkout the BSP branch and build</para></listitem>
-</itemizedlist>
-</para> -->
</section>
<section id='build-strategy'>
<title>Build Strategy</title>
<para>
- There are some prerequisites that must be met before starting the compilation
+ Once a local Git repository of the Linux Yocto kernel exists on a development system,
+ you can consider the compilation phase of kernel development - building a kernel image.
+ Some prerequisites exist that must be met before starting the compilation
phase of the kernel build system:
</para>
<itemizedlist>
- <listitem><para>There must be a kernel Git repository indicated in the SRC_URI.</para></listitem>
- <listitem><para>There must be a BSP build branch - &lt;bsp name&gt;-&lt;kernel type&gt; in 0.9 or
- &lt;kernel type&gt;/&lt;bsp name&gt; in 1.0.</para></listitem>
+ <listitem><para>The <filename>SRC_URI</filename> must point to the kernel Git
+ repository.</para></listitem>
+ <listitem><para>A BSP build branch must exist.
+ This branch has the following form:
+ <literallayout class='monospaced'>
+ &lt;kernel_type&gt;/&lt;bsp_name&gt;
+ </literallayout></para></listitem>
</itemizedlist>
<para>
@@ -187,15 +159,15 @@ A summary of end user tree construction activities follow:
of the build system.
However, other means do exist.
For examples of alternate workflows such as bootstrapping a BSP, see
- the<link linkend='workflow-examples'> Workflow Examples</link> section in this manual.
+ the "<link linkend='workflow-examples'>Workflow Examples</link>".
</para>
<para>
- Before building a kernel it is configured by processing all of the
- configuration "fragments" specified by feature descriptions in the <filename>scc</filename>
+ Before building a kernel, the build process 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 meta-series in their compilation order.
+ 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.
@@ -205,201 +177,47 @@ A summary of end user tree construction activities follow:
</para>
<para>
- Using the board's architecture and other relevant values from the board's template
- the Kernel compilation is started and a kernel image is produced.
+ 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 will first see once you configure a kernel is that
- it will generate a build tree that is separate from your Git source tree.
- This build tree has the name using the following form:
+ <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-&lt;BSPname&gt;-&lt;kerntype&gt;-build
+ linux-${MACHINE}-&lt;kernel_type&gt;-build
</literallayout>
- "kerntype" is one of the standard kernel types.
</para>
<para>
- The existing support in the kernel.org tree achieves this default functionality.
+ The existing support in the <filename>kernel.org</filename> tree achieves this
+ default functionality.
</para>
<para>
- What this means, is that all the generated files for a particular BSP are now in this directory.
- The files include the final <filename>.config</filename>, all the <filename>.o</filename>
+ What this means, is 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 BSP has its own separate build directory in its own separate branch
- of the Git tree you can easily switch between different BSP builds.
+ 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='scc'>
- <title>Series &amp; Configuration Compiler (SCC)</title>
-<para>
-In early versions of the product, kernel patches were simply listed in a flat
-file called "patches.list", and then quilt was added as a tool to help
-traverse this list, which in quilt terms was called a "series" file.
-</para>
-<para>
-Before the 2.0 release, it was already apparent that a static series file was
-too inflexible, and that the series file had to become more dynamic and rely
-on certain state (like kernel type) in order to determine whether a patch was
-to be used or not. The 2.0 release already made use of some stateful
-construction of series files, but since the delivery mechanism was unchanged
-(tar + patches + series files), most people were not aware of anything really
-different. The 3.0 release continues with this stateful construction of
-series files, but since the delivery mechanism is changed (Git + branches) it
-now is more apparent to people.
-</para>
-<para>
-As was previously mentioned, scc is a "series and configuration
-compiler". Its role is to combine feature descriptions into a format that can
-be used to generate a meta-series. A meta series contains all the required
-information to construct a complete set of branches that are required to
-build a desired board and feature set. The meta series is interpreted by the
-kgit tools to create a Git repository that could be built.
-</para>
-<para>
-To illustrate how scc works, a feature description must first be understood.
-A feature description is simply a small bash shell script that is executed by
-scc in a controlled environment. Each feature description describes a set of
-operations that add patches, modify existing patches or configure the
-kernel. It is key that feature descriptions can include other features, and
-hence allow the division of patches and configuration into named, reusable
-containers.
-</para>
-<para>
-Each feature description can use any of the following valid scc commands:
-<itemizedlist>
- <listitem><para>shell constructs: bash conditionals and other utilities can be used in a feature
- description. During compilation, the working directory is the feature
- description itself, so any command that is "raw shell" and not from the
- list of supported commands, can not directly modify a Git repository.</para></listitem>
-
- <listitem><para>patch &lt;relative path&gt;/&lt;patch name&gt;: outputs a patch to be included in a feature's patch set. Only the name of
- the patch is supplied, the path is calculated from the currently set
- patch directory, which is normally the feature directory itself.</para></listitem>
-
- <listitem><para>patch_trigger &gt;condition&lt; &gt;action&lt; &lt;tgt&gt;: indicate that a trigger should be set to perform an action on a
- patch.</para>
-
-<para>The conditions can be:
-
- <itemizedlist>
- <listitem><para>arch:&lt;comma separated arch list or "all"&gt;</para></listitem>
- <listitem><para>plat:&lt;comma separated platform list or "all"&gt;</para></listitem>
- </itemizedlist></para>
-<para>The action can be:
- <itemizedlist>
- <listitem><para>exclude: This is used in exceptional situations where a patch
- cannot be applied for certain reasons (arch or platform).
- When the trigger is satisfied the patch will be removed from
- the patch list.</para></listitem>
- <listitem><para>include: This is used to include a patch only for a specific trigger.
- Like exclude, this should only be used when necessary.
- It takes 1 argument, the patch to include.</para></listitem>
- </itemizedlist></para></listitem>
-
- <listitem><para>include &lt;feature name&gt; [after &lt;feature&gt;]: includes a feature for processing. The feature is "expanded" at the
- position of the include directive. This means that any patches,
- configuration or sub-includes of the feature will appear in the final
- series before the commands that follow the include.</para>
- <para>
- include searches the include directories for a matching feature name,
- include directories are passed to scc by the caller using -I &lt;path&gt; and
- is transparent to the feature script. This means that &lt;feature name&gt; must
- be relative to one of the search paths. For example, if
- /opt/kernel-cache/feat/sched.scc is to be included and scc is invoked
- with -I /opt/kernel-cache, then a feature would issue "include
- feat/sched.scc" to include the feature.
-</para>
-<para>
- The optional "after" directive allows a feature to modify the existing
- order of includes and insert a feature after the named feature is
- processed. Note: the "include foo after bar" must be issued before "bar"
- is processed, so is normally only used by a new top level feature to
- modify the order of features in something it is including.</para></listitem>
-
- <listitem><para>exclude &lt;feature name&gt;: Indicates that a particular feature should *not* be included even if an
- 'include' directive is found. The exclude must be issued before the
- include is processed, so is normally only used by a new top level feature
- to modify the order of features in something it is including.</para></listitem>
-
- <listitem><para>git &lt;command&gt;: Issues any Git command during tree construction. Note: this command is
- not validated/sanitized so care must be taken to not damage the
- tree. This can be used to script branching, tagging, pulls or other Git
- operations.</para></listitem>
-
- <listitem><para>dir &lt;directory&gt;: changes the working directory for "patch" directives. This can be used to
- shorten a long sequence of patches by not requiring a common relative
- directory to be issued each time.</para></listitem>
-
- <listitem><para>kconf &lt;type&gt; &lt;fragment name&gt;: associates a kernel config frag with the feature.
- &lt;type&gt; can be
- "hardware" or "non-hardware" and is used by the kernel configuration
- subsystem to audit configuration. &lt;fragment name&gt; is the name of a file
- in the current feature directory that contains a series of kernel
- configuration options. There is no restriction on the chosen fragment
- name, although a suffix of ".cfg" is recommended. Multiple fragment
- specifications are supported.</para></listitem>
-
- <listitem><para>branch &lt;branch name&gt;: creates a branch in the tree. All subsequent patch commands will be
- applied to the new branch and changes isolated from the rest of the
- repository.</para></listitem>
-
- <listitem><para>scc_leaf &lt;base feature&gt; &lt;branch name&gt;: Performs a combination feature include and branch. This is mainly a
- convenience directive, but has significance to some build system bindings
- as a sentinel to indicate that this intends to create a branch that is
- valid for kernel compilation.</para></listitem>
-
- <listitem><para>tag &lt;tag name&gt;: Tags the tree. The tag will be applied in processing order, so will
- be after already applied patches and precede patches yet to be applied.</para></listitem>
-
- <listitem><para>define &lt;var&gt; &lt;value&gt;: Creates a variable with a particular value that can be used in subsequent
- feature descriptions.</para></listitem>
-</itemizedlist>
-
-</para>
- </section> -->
-
-<!-- <section id='kgit-tools'>
- <title>kgit Tools</title>
-<para>
-The kgit tools are responsible for constructing and maintaining the Wind
-River kernel repository. These activities include importing, exporting, and
-applying patches as well as sanity checking and branch management. From the
-developers perspective, the kgit tools are hidden and rarely require
-interactive use. But one tool in particular that warrants further description
-is "kgit-meta".
-</para>
-<para>
-kgit-meta is the actual application of feature description(s) to a kernel repo.
-In other words, it is responsible for interpreting the meta series generated
-from a scc compiled script. As a result, kgit-meta is coupled to the set of
-commands permitted in a .scc feature description (listed in the scc section).
-kgit-meta understands both the meta series format and how to use Git and
-guilt to modify a base Git repository. It processes a meta-series line by
-line, branching, tagging, patching and tracking changes that are made to the
-base Git repository.
-</para>
-<para>
-Once kgit-meta has processed a meta-series, it leaves the repository with the
-last branch checked out, and creates the necessary guilt infrastructure to
-inspect the tree, or add to it via using guilt. As was previously mentioned,
-guilt is not required, but is provided as a convenience. Other utilities such
-as quilt, stgit, Git or others can also be used to manipulate the Git
-repository.
-</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.
- Yocto Project has not made changes to Git or to other tools that
+ 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
+ only core Git functionality, thus allowing any number of tools or front ends to use the
resulting tree.
</para>
@@ -417,7 +235,7 @@ repository.
<para>
In projects that have a collection of directories that
- contain patches to the kernel it is possible to inspect or "grep" the contents
+ 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.
@@ -441,15 +259,12 @@ repository.
Note that because the Yocto Project Git repository does not break existing Git
functionality and because there exists many permutations of these types of
commands there are many more methods to discover changes.
- </para>
-
- <note><para>
- Unless you provide a commit range
- (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), kernel.org history
- is blended with Yocto Project changes.
- </para></note>
-
- <literallayout class='monospaced'>
+ <note>
+ Unless you provide a commit range
+ (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), <filename>kernel.org</filename> history
+ is blended with Yocto Project changes.
+ </note>
+ <literallayout class='monospaced'>
# full description of the changes
&gt; git whatchanged &lt;kernel type&gt;..&lt;kernel type&gt;/&lt;bsp&gt;
&gt; eg: git whatchanged yocto/standard/base..yocto/standard/common-pc/base
@@ -469,7 +284,8 @@ repository.
# determine the commits which touch each line in a file
&gt; git blame &lt;path to file&gt;
- </literallayout>
+ </literallayout>
+ </para>
</section>
<section id='show-a-particular-feature-or-branch-change'>
@@ -479,13 +295,11 @@ repository.
Significant features or branches are tagged in the Yocto Project tree to divide
changes.
Remember to first determine (or add) the tag of interest.
- </para>
-
- <note><para>
- Because BSP branch, kernel.org, and feature tags are all present, there are many tags.
- </para></note>
-
- <literallayout class='monospaced'>
+ <note>
+ Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
+ present, there could be many tags.
+ </note>
+ <literallayout class='monospaced'>
# show the changes tagged by a feature
&gt; git show &lt;tag&gt;
&gt; eg: git show yaffs2
@@ -496,11 +310,13 @@ repository.
# show the changes in a kernel type
&gt; git whatchanged yocto/base..&lt;kernel type&gt;
&gt; eg: git whatchanged yocto/base..yocto/standard/base
- </literallayout>
+ </literallayout>
+ </para>
<para>
You can use many other comparisons to isolate BSP changes.
- For example, you can compare against kernel.org tags (e.g. v2.6.27.18, etc), or
+ For example, you can compare against <filename>kernel.org</filename> tags
+ (e.g. v2.6.27.18, etc), or
you can compare against subsystems (e.g. <filename>git whatchanged mm</filename>).
</para>
</section>
@@ -510,8 +326,8 @@ repository.
<title>Development: Saving Kernel Modifications</title>
<para>
- Another common operation is to build a BSP supplied by Yocto Project, make some
- changes, rebuild and then test.
+ 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>
@@ -519,7 +335,7 @@ repository.
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 the changes should be saved.
+ 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>
@@ -529,45 +345,43 @@ repository.
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 SCM</para></listitem>
- </itemizedlist>
+ <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>
+ <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 export in "bulk" changes that have not
+ 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.
- </para>
-
- <note><para>
- 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.
- </para></note>
-
- <literallayout class='monospaced'>
+ <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
@@ -575,7 +389,8 @@ repository.
&gt; git commit -s -a -m &gt;commit message&lt;
or
&gt; git commit -s -a # and interact with $EDITOR
- </literallayout>
+ </literallayout>
+ </para>
<para>
The previous operations capture all the local changes in the project source
@@ -596,18 +411,19 @@ repository.
<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 changes have been incrementally committed
- to the tree during development and now need to be exported. The sections that follow
+ 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 man pages or to an online resource such
- as <ulink url='http://github.com'></ulink>.
+ 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'>
+ <literallayout class='monospaced'>
# edit a file
&gt; vi &gt;path&lt;/file
# stage the change
@@ -620,11 +436,11 @@ repository.
&gt; git commit -s
... etc.
- </literallayout>
+ </literallayout>
</para>
<para>
- Distributed development with git is possible when you use a universally
+ 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
@@ -632,7 +448,8 @@ repository.
a commit.
As an individual in isolation, this is of no interest.
However, if you
- intend to share your tree with normal git push and pull operations for
+ 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>
@@ -642,19 +459,19 @@ repository.
another repository, you can update both the commit content and commit messages
associated with development by using the following commands:
- <literallayout class='monospaced'>
+ <literallayout class='monospaced'>
&gt; Git add &gt;path&lt;/file
&gt; Git commit --amend
&gt; Git rebase or Git rebase -i
- </literallayout>
+ </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
+ no pending works-in-progress exists (use <filename>git status</filename> to check), then
you can revert (undo) commits by using the following commands:
- <literallayout class='monospaced'>
+ <literallayout class='monospaced'>
# remove the commit, update working tree and remove all
# traces of the change
&gt; git reset --hard HEAD^
@@ -662,26 +479,26 @@ repository.
&gt; git reset --soft HEAD^
# remove the commit, leave file change, but not staged for commit
&gt; git reset --mixed HEAD^
- </literallayout>
+ </literallayout>
</para>
<para>
- You can create branches, "cherry-pick" changes or perform any number of Git
+ 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 push or pull, commits are normally considered
+ After a <filename>push</filename> or <filename>pull</filename> command,
+ commits are normally considered
"permanent" and you should not modify them.
- If they need to be changed you can incrementally do so with new commits.
- These practices follow the standard Git workflow and the kernel.org best
+ 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 Yocto Project recommends.
+ <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>
-
- <note><para>
- 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.
- </para></note>
<section id='export-internally-via-patches'>
<title>Exporting Changes Internally by Using Patches</title>
@@ -699,27 +516,23 @@ repository.
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.
- </para>
-
- <note><para>
- 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.
- </para></note>
-
- <para>
- <literallayout class='monospaced'>
+ <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.
&gt; git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
- </literallayout>
+ </literallayout>
</para>
<para>
In other words:
- <literallayout class='monospaced'>
+ <literallayout class='monospaced'>
# Identify commits of interest.
# If the tree was tagged before development
@@ -731,13 +544,8 @@ repository.
&gt; git whatchanged # identify last commit
&gt; git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
&gt; git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
- </literallayout>
+ </literallayout>
</para>
-
- <!--<para>
- See the "template patching" example for how to use the patches to
- automatically apply to a new kernel build.
- </para>-->
</section>
<section id='export-internally-via-git'>
@@ -746,44 +554,38 @@ repository.
<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 in the master repository you can then
+ Once you have pushed the changes in 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'>
+ <literallayout class='monospaced'>
&gt; git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
&lt;local_branch&gt;:&lt;remote_branch&gt;
- </literallayout>
+ </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-2.6.37</filename>.
- <literallayout class='monospaced'>
- &gt; git push ssh://git.mycompany.com/pub/git/kernel-2.6.37 \
+ in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.0</filename>.
+ <literallayout class='monospaced'>
+ &gt; git push ssh://git.mycompany.com/pub/git/kernel-3.0 \
yocto/standard/common-pc/base:yocto/standard/common-pc/base
- </literallayout>
+ </literallayout>
</para>
<para>
- A pull request entails using <filename>git request-pull</filename> to compose an email to the
+ A pull request entails using <filename>git request-pull</filename> 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>
-
- <note><para>
- Other commands such as <filename>git stash</filename> or branching can also be used to save
- changes, but are not covered in this document.
- </para></note>
-
- <!--<para>
- See the section "importing from another SCM" for how a Git push to the
- default_kernel, can be used to automatically update the builds of all users
- of a central Git repository.
- </para>-->
</section>
</section>
@@ -794,26 +596,29 @@ repository.
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 sent patches as an email series.
+ 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://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem>
+ <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>
- <note><para>
- 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://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem>
- <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>
- </para></note>
-
<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.
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
+ 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>
@@ -821,13 +626,14 @@ repository.
<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
+ 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'>
+ <literallayout class='monospaced'>
# dump the last 4 commits
&gt; git format-patch --thread -n -o ~/rr/ HEAD^^^^
&gt; git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
@@ -835,7 +641,7 @@ repository.
--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>
+ </literallayout>
</para>
</section>
@@ -844,12 +650,12 @@ repository.
<para>
When you want to export changes for import into another
- Source Code Manager (SCM) you can use any of the previously discussed
+ 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
+ that tree is checked into the SCM, you can lose change information such as
commit logs.
- Yocto Project does not recommend this process.
+ The Yocto Project does not recommend this process.
</para>
<para>
@@ -864,16 +670,16 @@ repository.
<title>Working with the Yocto Project Kernel in Another SCM</title>
<para>
- This section describes kernel development in another SCM, which is not the same
- as exporting changes to another SCM.
- For this scenario you use the Yocto Project build system to
+ 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 Yocto Project 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>
+ SCM.</para></listitem>
<listitem><para>Development must be exported from that secondary SCM into a
- format that can be used by the Yocto Project build system.</para></listitem>
+ format that can be used by the Yocto Project build system.</para></listitem>
</itemizedlist>
</para>
@@ -881,7 +687,7 @@ repository.
<title>Exporting the Delivered Kernel to the SCM</title>
<para>
- Depending on the SCM it might be possible to export the entire Yocto Project
+ 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.
@@ -894,12 +700,13 @@ repository.
<para>
The following commands illustrate some of the steps you could use to
- import the yocto/standard/common-pc/base kernel into a secondary SCM:
- <literallayout class='monospaced'>
+ import the <filename>yocto/standard/common-pc/base</filename>
+ kernel into a secondary SCM:
+ <literallayout class='monospaced'>
&gt; git checkout yocto/standard/common-pc/base
&gt; cd .. ; echo linux/.git &gt; .cvsignore
&gt; cvs import -m "initial import" linux MY_COMPANY start
- </literallayout>
+ </literallayout>
</para>
<para>
@@ -908,13 +715,13 @@ repository.
<para>
The following commands illustrate how you can condense and merge two BSPs into a second SCM:
- <literallayout class='monospaced'>
+ <literallayout class='monospaced'>
&gt; git checkout yocto/standard/common-pc/base
&gt; git merge yocto/standard/common-pc-64/base
# resolve any conflicts and commit them
&gt; cd .. ; echo linux/.git &gt; .cvsignore
&gt; cvs import -m "initial import" linux MY_COMPANY start
- </literallayout>
+ </literallayout>
</para>
</section>
@@ -924,112 +731,12 @@ repository.
<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
+ To export them, place the changes in a recipe and
automatically apply them to the kernel during patching.
</para>
-<!--<para>
-If changes are imported directly into Git, they must be propagated to the
-wrll-linux-2.6.27/git/default_kernel bare clone of each individual build
-to be present when the kernel is checked out.
-</para>
-<para>
-The following example illustrates one variant of this workflow:
-<literallayout class='monospaced'>
- # on master Git repository
- &gt; cd linux-2.6.27
- &gt; git tag -d common_pc-standard-mark
- &gt; git pull ssh://&lt;foo&gt;@&lt;bar&gt;/pub/git/kernel-2.6.27 common_pc-standard:common_pc-standard
- &gt; git tag common_pc-standard-mark
-
- # on each build machine (or NFS share, etc)
- &gt; cd wrll-linux-2.6.27/git/default_kernel
- &gt; git fetch ssh://&lt;foo&gt;@&lt;master server&gt;/pub/git/kernel-2.6.27
-
- # in the build, perform a from-scratch build of Linux and the new changes
- # will be checked out and built.
- &gt; make linux
-</literallayout>
-</para> -->
</section>
</section>
-<!-- <section id='bsp-template-migration-from-2'>
- <title>BSP: Template Migration from 2.0</title>
-<para>
-The move to a Git-backed kernel build system in 3.0 introduced a small new
-requirement for any BSP that is not integrated into the GA release of the
-product: branching information.
-</para>
-<para>
-As was previously mentioned in the background sections, branching information
-is always required, since the kernel build system cannot make intelligent
-branching decisions and must rely on the developer. This branching
-information is provided via a .scc file.
-</para>
-<para>
-A BSP template in 2.0 contained build system information (config.sh, etc) and
-kernel patching information in the 'linux' subdirectory. The same holds true
-in 3.0, with only minor changes in the kernel patching directory.
-The ".smudge" files are now ".scc" files and now contain a full description
- of the kernel branching, patching and configuration for the BSP. Where in
- 2.0, they only contained kernel patching information.
-</para>
-<para>
-The following illustrates the migration of a simple 2.0 BSP template to the
-new 3.0 kernel build system.
-</para>
-<note><para>
-Note: all operations are from the root of a customer layer.
-</para></note>
-<literallayout class='monospaced'>
- templates/
- `&dash;&dash; board
- `&dash;&dash; my_board
- |&dash;&dash; config.sh
- |&dash;&dash; include
- `&dash;&dash; linux
- `&dash;&dash; 2.6.x
- |&dash;&dash; knl-base.cfg
- |&dash;&dash; bsp.patch
- `&dash;&dash; my_bsp.smudge
-
- &gt; mv templates/board/my_board/linux/2.6.x/* templates/board/my_board/linux
- &gt; rm -rf templates/board/my_board/linux/2.6.x/
- &gt; mv templates/board/my_board/linux/my_bsp.smudge \
- templates/board/my_board/linux/my_bsp-standard.scc
- &gt; echo "kconf hardware knl-base.cfg" &gt;&gt; \
- templates/board/my_board/linux/my_bsp-standard.scc
- &gt; vi templates/board/my_board/linux/my_bsp-standard.scc
- # add the following at the top of the file
- scc_leaf ktypes/standard my_bsp-standard
-
- templates/
- `&dash;&dash; board
- `&dash;&dash; my_board
- |&dash;&dash; config.sh
- |&dash;&dash; include
- `&dash;&dash; linux
- |&dash;&dash; knl-base.cfg
- |&dash;&dash; bsp.patch
- `&dash;&dash; my_bsp-standard.scc
-</literallayout>
-<para>
-That's it. Configure and build.
-</para>
-<note><para>There is a naming convention for the .scc file, which allows the build
- system to locate suitable feature descriptions for a board:
-</para></note>
-<literallayout class='monospaced'>
- &lt;bsp name&gt;-&lt;kernel type&gt;.scc
-</literallayout>
-<para>
- if this naming convention isn't followed your feature description will
- not be located and a build error thrown.
-</para>
- </section> -->
-
-
-
<section id='bsp-creating'>
<title>Creating a BSP Based on an Existing Similar BSP</title>
@@ -1037,19 +744,21 @@ That's it. Configure and build.
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 BSP given an existing similar BSP
- see the Yocto Project Development Manual [NEED LINK] or the
- <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'></ulink>
+ For detailed information on how to create a BSP given an existing similar BSP, see
+ the "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#dev-manual-bsp-appendix'>BSP Development Example</ulink>" appendix in
+ <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The
+ Yocto Project Development Manual</ulink>, or see the
+ <ulink url='https://wiki.yoctoproject.org/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>Make sure you have the Yocto Project source tree available.
+ <listitem><para><emphasis>Make sure you have the Yocto Project source tree available:</emphasis>
You should either create a Yocto Project Git repository (recommended), or
you should get the Yocto Project release tarball and extract it.</para></listitem>
- <listitem><para>Choose an existing BSP available with the Yocto Project.
+ <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
@@ -1057,13 +766,14 @@ That's it. Configure and build.
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='http://www.yoctoproject.org/download'></ulink>.</para></listitem>
- <listitem><para>Be sure you have the Base BSP.
+ <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
You need to either have the Yocto Project Git repository set up or download
the tarball of the base BSP.
Either method gives you access to the BSP source files.</para></listitem>
- <listitem><para>Make a copy of the existing BSP, thus isolating your new BSP work.
+ <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
+ BSP work:</emphasis>
Copying the existing BSP structure gives you a new area in which to work.</para></listitem>
- <listitem><para>Make configuration and recipe changes to your new BSP.
+ <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
@@ -1071,13 +781,13 @@ That's it. Configure and build.
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>Prepare for the build.
- Before you actually initiate the build you need to set up the build environment
+ <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
+ 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>Build the image.
+ <listitem><para><emphasis>Build the image:</emphasis>
The Yocto Project uses the BitBake tool 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>
@@ -1086,746 +796,6 @@ That's it. Configure and build.
</para>
</section>
-
-<!--
- <section id='bsp-creating-bsp-without-a-local-kernel-repo'>
- <title>Creating a BSP Based on an Existing Similar BSP Without a Local Kernel Repository</title>
-
- <para>
- If you are creating a BSP based on an existing similar BSP but you do not have
- a local kernel repository, the process is very similar to the process in
- the previous section (<xref linkend='bsp-creating'/>).
- </para>
-
- <para>
- Follow the exact same process as described in the previous section with
- these slight modifications:
- </para>
- <orderedlist>
- <listitem><para>Perform Step 1 as is from the previous section.</para></listitem>
- <listitem><para>Perform Step 2 as is from the previous section.</para></listitem>
- <listitem><para>Perform Step 3 but do not modify the
- KSRC line in the bbappend file.</para></listitem>
- <listitem><para>Edit the <filename>local.conf</filename> so
- that it contains the following:
- <literallayout class='monospaced'>
- YOCTO_KERNEL_EXTERNAL_BRANCH="&lt;your-machine&gt;-standard
- </literallayout></para>
- <para>Adding this statement to the file triggers BSP bootstrapping
- to occur and the correct branches and base configuration to be used.
- </para></listitem>
- <listitem><para>Perform Step 4 as is from the previous section.</para></listitem>
- <listitem><para>Perform Step 5 as is from the previous section.</para></listitem>
- </orderedlist>
- </section>
-
-
-
- <section id='bsp-creating-a-new-bsp'>
- <title>BSP: Creating a New BSP</title>
-<para>
-Although it is obvious that the structure of a new BSP uses the migrated
-directory structure from the previous example,the first question is whether
-or not the BSP is started from scratch.
-</para>
-<para>
-If Yocto Project has a similar BSP, it is often easier to clone and update,
-rather than start from scratch. If the mainline kernel has support, it is
-easier to branch from the -standard kernel and begin development (and not be
-concerned with undoing existing changes). This section covers both options.
-</para>
-<para>
-In almost every scenario, the LDAT build system bindings must be completed
-before either cloning or starting a new BSP from scratch. This is simply
-because the board template files are required to configure a project/build
-and create the necessary environment to begin working directly with the
-kernel. If it is desired to start immediately with kernel development and
-then add LDAT bindings, see the "bootstrapping a BSP" section.
-</para>
- <section id='creating-from-scratch'>
- <title>Creating the BSP from Scratch</title>
-<para>
-To create the BSP from scratch you need to do the following:
-<orderedlist>
- <listitem><para>Create a board template for the new BSP in a layer.</para></listitem>
- <listitem><para>Configure a build with the board.</para></listitem>
- <listitem><para>Configure a kernel.</para></listitem>
-</orderedlist>
-</para>
-<para>
-Following is an example showing all three steps. You start by creating a board template for the new BSP in a layer.
-<literallayout class='monospaced'>
- templates/
- `&dash;&dash; board
- `&dash;&dash; my_bsp
- |&dash;&dash; include
- |&dash;&dash; config.sh
- `&dash;&dash; linux
- |&dash;&dash; my_bsp.cfg
- `&dash;&dash; my_bsp-standard.scc
-
- &gt; cat config.sh
- TARGET_BOARD="my_bsp"
- TARGET_LINUX_LINKS="bzImage"
- TARGET_SUPPORTED_KERNEL="standard"
- TARGET_SUPPORTED_ROOTFS="glibc_std"
- BANNER="This BSP is *NOT* supported"
- TARGET_PROCFAM="pentium4"
- TARGET_PLATFORMS="GPP"
-
- &gt; cat include
- cpu/x86_32_i686
- karch/i386
-
- &gt; cat linux/my_bsp-standard.scc
- scc_leaf ktypes/standard/standard.scc my_bsp-standard
-
- &gt; cat linux/my_bsp.cfg
- CONFIG_X86=y
- CONFIG_SMP=y
- CONFIG_VT=y
- # etc, etc, etc
-</literallayout>
-</para>
-<para>
-Something like the following can now be added to a board build, and
-a project can be started:
-<literallayout class='monospaced'>
- &dash;&dash;enable-board=my_bsp \
- &dash;&dash;with-layer=custom_bsp
-</literallayout>
-</para>
-<para>
-Now you can configure a kernel:
-<literallayout class='monospaced'>
- &gt; make -C build linux.config
-</literallayout>
-</para>
-<para>
-You now have a kernel tree, which is branched and has no patches, ready for
-development.
-</para>
- </section> -->
-
-<!-- <section id='cloning-an-existing-bsp'>
- <title>Cloning an Existing BSP</title>
-<para>
-Cloning an existing BSP from the shipped product is similar to the "from
-scratch" option and there are two distinct ways to achieve this goal:
-<itemizedlist>
- <listitem><para>Create a board template for the new BSP in a layer.</para></listitem>
- <listitem><para>Clone the .scc and board config.</para></listitem>
-</itemizedlist>
-</para>
-<para>
-The first method is similar to the from scratch BSP where you create a board template for the new
-BSP. Although in this case, copying an existing board template from
-wrll-wrlinux/templates/board would be appropriate, since we are cloning an
-existing BSP. Edit the config.sh, include and other board options for the new
-BSP.
-</para>
-<para>
-The second method is to clone the .scc and board config.
-To do this, in the newly created board template, create a linux subdirectory and export
-the .scc and configuration from the source BSP in the published Yocto Project
-kernel. During construction, all of the configuration and patches were
-captured, so it is simply a matter of extracting them.
-</para>
-<para>
-Extraction can be accomplished using four different techniques:
-<itemizedlist>
- <listitem><para>Config and patches from the bare default_kernel.</para></listitem>
- <listitem><para>Clone default_kernel and checkout wrs_base.</para></listitem>
- <listitem><para>Clone default_kernel and checkout BSP branch.</para></listitem>
- <listitem><para>Branch from the Yocto Project BSP.</para></listitem>
-</itemizedlist>
-</para>
-<para>
-Technique 1: config and patches from the bare default_kernel
-<literallayout class='monospaced'>
- &gt; cd layers/wrll-linux-2.6.27/git/default_kernel
- &gt; git show checkpoint_end | filterdiff -i '*common_pc*' | patch -s -p2 -d /tmp
-
- # This will create two directories: cfg and patches.
-
- &gt; cd /tmp/cfg/kernel-cache/bsp/common_pc/
-
- # This directory contains all the patches and .scc files used to construct
- # the BSP in the shipped tree. Copy the patches to the new BSP template,
- # and add them to the .scc file created above. See "template patching" if
- # more details are required.
-</literallayout>
-</para>
-<para>
-Technique 2: clone default_kernel and checkout wrs_base
-<literallayout class='monospaced'>
- &gt; git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27
- &gt; cd windriver-2.6.27
- &gt; git checkout wrs_base
- &gt; cd wrs/cfg/kernel-cache/bsp/common_pc
-
-# again, this directory has all the patches and .scc files used to construct
-# the BSP
-</literallayout>
-</para>
-<para>
-Technique 3: clone default_kernel and checkout BSP branch
-<literallayout class='monospaced'>
- &gt; git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27
- &gt; cd windriver-2.6.27
- &gt; git checkout common_pc-standard
- &gt; git whatchanged
- # browse patches and determine which ones are of interest, say there are
- # 3 patches of interest
- &gt; git format-patch -o &lt;path to BSP template&gt;/linux HEAD^^^
- # update the .scc file to add the patches, see "template patches" if
- # more details are required
-</literallayout>
-</para>
-<para>
-Technique #4: branch from the Yocto Project BSP
-<note><para>This is potentially the most "different" technique, but is actually
- the easiest to support and leverages the infrastructure. rtcore BSPs
- are created in a similar manner to this.
-</para></note>
-</para>
-<para>
-In this technique the .scc file in the board template is slightly different
- and indicates that the BSP should branch after the base Yocto Project BSP
- of the correct kernel type, so to start a new BSP that inherits the
- kernel patches of the common_pc-standard, the following would be done:
-<literallayout class='monospaced'>
- &gt; cat linux/my_bsp-standard.scc
- scc_leaf bsp/common_pc/common_pc-standard.scc my_bsp-standard
-</literallayout>
-</para>
-<para>
- And only kernel configuration (not patches) need be contained in the
- board template.
-</para>
-<para>
- This has the advantage of automatically picking up updates to the BSP
- and not duplicating any patches for a similar board.
-</para>
- </section> -->
-
- <!-- <section id='bsp-bootstrapping'>
- <title>BSP: Bootstrapping</title>
-<para>
-The previous examples created the board templates and configured a build
-before beginning work on a new BSP. It is also possible for advanced users to
-simply treat the Yocto Project Git repository as an upstream source and begin
-BSP development directly on the repository. This is the closest match to how
-the kernel community at large would operate.
-</para>
-<para>
-Two techniques exist to accomplish this:
-</para>
-<para>
-Technique 1: upstream workflow
-<literallayout class='monospaced'>
- &gt; git clone layers/wrll-linux-2.6.27/git/default_kernel windriver-2.6.27
- &gt; cd windriver-2.6.27
- &gt; git checkout -b my_bsp-standard common_pc-standard
-
- # edit files, import patches, generally do BSP development
-
- # at this point we can create the BSP template, and export the kernel
- # changes using one of the techniques discussed in that section. For
- # example, It is possible to push these changes, directly into the
- # default_kernel and never directly manipulate or export patch files
-</literallayout>
-</para>
-<para>
-Technique 2: Yocto Project kernel build workflow
-</para>
-<para>
- Create the BSP branch from the appropriate kernel type
-<literallayout class='monospaced'>
- &gt; cd linux
- # the naming convention for auto-build is &lt;bsp&gt;-&lt;kernel type&gt;
- &gt; git checkout -b my_bsp-standard standard
-</literallayout>
-</para>
-<para>
-Make changes, import patches, etc.
-<literallayout class='monospaced'>
- &gt; ../../host-cross/bin/guilt init
- # 'wrs/patches/my_bsp-standard' has now been created to
- # manage the branches patches
-
- # option 1: edit files, guilt import
- &gt; ../../host-cross/bin/guilt new extra-version.patch
- &gt; vi Makefile
- &gt; ../../host-cross/bin/guilt refresh
- # add a header
- &gt; ../../host-cross/bin/guilt header -e
- # describe the patch using best practices, like the example below:
-
- &dash;&dash;&dash;&gt;&dash;&dash;&dash;&gt;&dash;&dash;&dash;&gt; cut here
- From: Bruce Ashfield &lt;bruce.ashfield@windriver.com&gt;
-
- Adds an extra version to the kernel
-
- Modify the main EXTRAVERSION to show our bsp name
-
- Signed-off-by: Bruce Ashfield &lt;bruce.ashfield@windriver.com&gt;
- &dash;&dash;&dash;&gt;&dash;&dash;&dash;&gt;&dash;&dash;&dash;&gt; cut here
-
- # option 2: import patches
- &gt; git am &lt;patch&gt;
- or
- &gt; git apply &lt;patch&gt;
- &gt; git add &lt;files&gt;
- &gt; git commit -s
-
- # configure the board, save relevant options
- &gt; make ARCH=&lt;arch&gt; menuconfig
-
- # save the cfg changes for reconfiguration
- &gt; mkdir wrs/cfg/&lt;cache&gt;/my_bsp
- &gt; vi wrs/cfg/&lt;cache&gt;/my_bsp/my_bsp.cfg
-
- # classify the patches
- &gt; ../../host-cross/bin/kgit classify create &lt;kernel-foo-cache&gt;/my_bsp/my_bsp
- # test build
- &gt; cd ..
- &gt; make linux TARGET_BOARD=my_bsp kprofile=my_bsp use_current_branch=1
-</literallayout>
-</para>
-<para>
- Assuming the patches have been exported to the correct location, Future
- builds will now find the board, apply the patches to the base tree and make
- the relevant branches and structures and the special build options are no
- longer required.
-</para>
- </section>
- </section> -->
-
-<!-- <section id='patching'>
- <title>Patching</title>
-<para>
-The most common way to apply patches to the kernel is via a template.
-However, for more advanced applications (such as the sharing of patches between
-multiple sub-features) it is possible to patch the kernel-cache.
-This section covers both scenarios.
-</para>
- <section id='patching-template'>
- <title>Patching: Template</title>
-<para>
-kernel
-templates follow the same rules as any LDAT template. A directory should be
-created in a recognized template location, with a 'linux' subdirectory. The
-'linux' directory triggers LDAT to pass the dir as a potential patch location
-to the kernel build system. Any .scc files found in that directory, will be
-automatically appended to the end of the BSP branch (for the configured
-board).
-</para>
-<para>
-This behavior is essentially the same since previous product
-releases. The only exception is the use of ".scc", which allows kernel
-configuration AND patches to be applied in a template.
-</para>
-<note><para>
-If creating a full template is not required, a .scc file can be placed at
-the top of the build, along with configuration and patches. The build
-system will pickup the .scc and add it onto the patch list automatically
-</para></note>
-<para>
-As an example, consider a simple template to update a BP:
-<literallayout class='monospaced'>
- &gt; cat templates/feature/extra_version/linux/extra_version.scc
- patch 0001-extraversion-add-Wind-River-identifier.patch
-</literallayout>
-</para>
-<para>
-To illustrate how the previous template patch was created, the following
-steps were performed:
-<literallayout class='monospaced'>
- &gt; cd &lt;board build&gt;/build/linux
- &gt; vi Makefile
- # modify EXTRAVERSION to have a unique string
- &gt; git commit -s -m "extraversion: add Yocto Project identifier" Makefile
- &gt; git format-patch -o &lt;path to layer&gt;/templates/feature/extra_version/linux/
- &gt; echo "patch 0001-extraversion-add-Wind-River-identifier.patch" &gt; \
- &lt;path to layer&gt;/templates/feature/extra_version/linux/extra_version.scc
-</literallayout>
-</para>
-<para>
-This next example creates a template with a linux subdirectory, just as we
- always have for previous releases.
-<literallayout class='monospaced'>
- &gt; mkdir templates/features/my_feature/linux
-</literallayout>
-</para>
-<para>
- In that directory place your feature description, your
- patch and configuration (if required).
-<literallayout class='monospaced'>
- &gt; ls templates/features/my_feature/linux
-
- version.patch
- my_feature.scc
- my_feature.cfg
-</literallayout>
-</para>
-<para>
- The .scc file describes the patches, configuration and
- where in the patch order the feature should be inserted.
-<literallayout class='monospaced'>
- patch version.patch
- kconf non-hardware my_feature.cfg
-</literallayout>
-</para>
-<para>
- Configure your build with the new template
-<literallayout class='monospaced'>
- &dash;&dash;with-template=features/my_feature
-</literallayout>
-</para>
-<para>
-Build the kernel
-<literallayout class='monospaced'>
- &gt; make linux
-</literallayout>
-</para>
- </section>
-
- <section id='patching-kernel-cache'>
- <title>Patching: Kernel Cache</title>
-<para>
-As previously mentioned, this example is included for completeness, and is for more advanced
-applications (such as the sharing of patches between multiple sub-features).
-Most patching should be done via templates, since that interface is
-guaranteed not to change and the kernel-cache interface carries no such
-guarantee.
-</para>
-<para>
-At the top of a layer, create a kernel cache. The build system will recognize
-any directory of the name 'kernel-*-cache' as a kernel cache.
-<literallayout class='monospaced'>
- &gt; cd &lt;my layer&gt;
- &gt;mkdir kernel-temp-cache
-</literallayout>
-</para>
-<para>
-Make a directory with the BSP
-<literallayout class='monospaced'>
- &gt; mkdir kernel-temp-cache
- &gt; mkdir kernel-temp-cache/my_feat
-</literallayout>
-</para>
-<para>
-Create the feature files as they were in technique #1
-<literallayout class='monospaced'>
- &gt; echo "patch my_patch.path" &gt; kernel-temp-cache/my_feat/my_feature.scc
-</literallayout>
-</para>
-<para>
-Configure the build with the feature added to the kernel type
-<literallayout class='monospaced'>
- &dash;&dash;with-kernel=standard+my_feat/my_feature.scc
-</literallayout>
-</para>
-<para>
-Build the kernel
-<literallayout class='monospaced'>
- &gt; make linux
-</literallayout>
-</para>
- </section>
- </section>
-
- <section id='bsp-updating-patches-and-configuration'>
- <title>BSP: Updating Patches and Configuration</title>
-<para>
-As was described in the "template patching" example, it is simple
-to add patches to a BSP via a template, but often, it is desirable
-to experiment and test patches before committing them to a template.
-You can do this by modifying the BSP source.
-</para>
-<para>
-Start as follows:
-<literallayout class='monospaced'>
- &gt; cd linux
- &gt; git checkout &lt;bspname&gt;-&lt;kernel name&gt;
-
- &gt; git am &lt;patch&gt;
-</literallayout>
-</para>
-<para>
-Or you can do this:
-<literallayout class='monospaced'>
- &gt; kgit-import -t patch &lt;patch&gt;
-
- &gt; cd ..
- &gt; make linux
-</literallayout>
-</para>
-<para>
-For details on conflict resolution and patch application, see the
-Git manual, or other suitable online references.
-<literallayout class='monospaced'>
- &gt; git am &lt;mbox&gt;
- # conflict
- &gt; git apply &dash;&dash;reject .git/rebase-apply/0001
- # resolve conflict
- &gt; git am &dash;&dash;resolved (or git am &dash;&dash;skip, git am &dash;&dash;abort)
- # continue until complete
-</literallayout>
-</para>
-<para>
-Here is another example:
-<literallayout class='monospaced'>
- # merge the patches
- # 1) single patch
- &gt; git am &lt;mbox&gt;
- &gt; git apply &lt;patch&lt;
- &gt; kgit import -t patch &lt;patch&gt;
-
- # 2) multiple patches
- &gt; git am &lt;mbox&gt;
- &gt; kgit import -t dir &lt;dir&gt;
-
- # if kgit -t dir is used, a patch resolution cycle such
- # as this can be used:
-
- &gt; kgit import -t dir &lt;dir&gt;
- # locate rejects and resolve
- # options:
- &gt; wiggle &dash;&dash;replace &lt;path to file&gt; &lt;path to reject&gt;
- &gt; guilt refresh
- or
- &gt; # manual resolution
- &gt; git add &lt;files&gt;
- &gt; git commit -s
- or
- &gt; git apply &dash;&dash;reject .git/rebase-apply/0001
- &gt; git add &lt;files&gt;
- &gt; git am &dash;&dash;resolved
- or
- &gt; # merge tool of choice
-
- # continue series:
-
- &gt; kgit import -t dir &lt;dir&gt;
- or
- &gt; git am &dash;&dash;continue
-</literallayout>
-</para>
-<para>
-Once all the patches have been tested and are satisfactory, they
-should be exported via the techniques described in "saving kernel
-modifications."
-</para>
-<para>
-Once the kernel has been patched and configured for a BSP, it's
-configuration commonly needs to be modified. This can be done by
-running [menu|x]config on the kernel tree, or working with
-configuration fragments.
-</para>
-<para>
-Using menuconfig, the operation is as follows:
-<literallayout class='monospaced'>
- &gt; make linux.menuconfig
- &gt; make linux.rebuild
-</literallayout>
-</para>
-<para>
-Once complete, the changes are in linux-&lt;bsp&gt;-&lt;kernel type&gt;-build/.config.
-To permanently save these changes, compare the .config before and after the
-menuconfig, and place those changes in a configuration fragment in the
-template of your choice.
-</para>
-<para>
-Using configuration fragments, the operation is as follows (using the
-si_is8620 as an example BSP):
-<literallayout class='monospaced'>
- &gt; vi linux/wrs/cfg/kernel-cache/bsp/si_is8620/si_is8620.cfg
- &gt; make linux.reconfig
- &gt; make linux.rebuild
-</literallayout>
-</para>
-<para>
-The modified configuration fragment can simply be copied out of the
-linux/wrs/.. directory and placed in the appropriate template for future
-application.
-</para>
- </section>
-
- <section id='tools-guilt'>
- <title>Tools: guilt</title>
-<para>
-Yocto Project has guilt integrated as a kernel tool; therefore users that are
-familiar with quilt may wish to use this tool to pop, push and refresh
-their patches. Note: guilt should only be used for local operations, once
-a set of changes has been pushed or pulled, they should no longer be popped
-or refresh by guilt, since popping, refreshing and re-pushing patches
-changes their commit IDs and creating non-fast forward branches.
-</para>
-<para>
-The following example illustrates how to add patches a Yocto Project
-BSP branch via guilt:
-<literallayout class='monospaced'>
- &gt; cd build/linux
- &gt; git checkout common_pc-standard
- &gt; guilt new extra.patch
- # edit files, make changes, etc
- &gt; guilt refresh
- &gt; guilt top
- extra.patch
-
- # export that patch to an external location
- &gt; kgit export -p top /tmp
-</literallayout>
-</para>
-<para>
-Other guilt operations of interest are:
-<literallayout class='monospaced'>
- > guilt push, guilt push -a
- > guilt pop
- > guilt applied, guilt unapplied
- > guilt top
- > guilt refresh
- > guilt header -e
- > guilt next
-</literallayout>
-</para>
-<note><para>
-Guilt only uses Git commands and Git plumbing to perform its operations,
-anything that guilt does can also be done using Git directly. It is provided
-as a convenience utility, but is not required and the developer can use whatever
-tools or workflow they wish.
-</para></note>
-<para>
-The following builds from the above instructions to show how guilt can be
-used to assist in getting your BSP kernel patches ready. You should follow
-the above instructions up to and including 'make linux.config'. In this
-example I will create a new commit (patch) from scratch and import another
-fictitious patch from some external public Git tree (ie, a commit with full
-message, signoff etc.). Please ensure you have host-cross/bin in your path.
-<literallayout class='monospaced'>
- %> cd linux
- %> guilt-init
- %> guilt-new -m fill_me_in_please first_one.patch
- %> touch somefile.txt
- %> guilt-add somefile.txt
- %> guilt-header -e
- %> guilt-refresh
- %> guilt-import path_to_some_patch/patch_filename
- %> guilt-push
-</literallayout>
-</para>
-<para>
-Here are a few notes about the above:
-<itemizedlist>
- <listitem><para>guilt-header -e &dash;&dash; this will open editing of the patch header in
- EDITOR. As with a Git commit the first line is the short log and
- should be just that short and concise message about the commit. Follow
- the short log with lines of text that will be the long description but
- note Do not put a blank line after the short log. As usual you will
- want to follow this with a blank line and then a signoff line.</para></listitem>
-
- <listitem><para>The last line in the example above has 2 dots on the end. If you
- don't add the 2 periods on the end guilt will think you are sending
- just one patch. The wrong one!</para></listitem>
-
- <listitem><para>The advantage to using guilt over not using guilt is that if you have a
- review comment in the first patch (first_one.patch in the case of this
- example) it is very easy to use guilt to pop the other patches off
- allowing you to make the necessary changes without having to use more
- inventive Git type strategies.</para></listitem>
-</itemizedlist>
-</para>
- </section>
-
- <section id='tools-scc-file-example'>
- <title>Tools: scc File Example</title>
-<para>
-This section provides some scc file examples: leaf node, 'normal' mode, and transforms.
-</para>
- <section id='leaf-node'>
- <title>Leaf Node</title>
-<para>
-The following example is a BSP branch with no child branches - a leaf on the tree.
-<literallayout class='monospaced'>
- # these are optional, but allow standalone tree construction
- define WRS_BOARD &lt;name&gt;
- define WRS_KERNEL &lt;kern type&gt;
- define WRS_ARCH &lt;arch&gt;
-
- scc_leaf ktypes/standard common_pc-standard
- # ^ ^
- # +&dash;&dash; parent + branch name
-
- include common_pc.scc
- # ^
- # +&dash;&dash;&dash; include another feature
-</literallayout>
-</para>
- </section>
-
- <section id='normal-mode'>
- <title>'Normal' Mode</title>
-<para>
-Here is an example of 'normal' mode:
-<literallayout class='monospaced'>
- # +&dash;&dash;&dash;&dash; name of file to read
- # v
- kconf hardware common_pc.cfg
- # ^ ^
- # | +&dash;&dash; 'type: hardware or non-hardware
- # |
- # +&dash;&dash;&dash; kernel config
-
- # patches
- patch 0002-atl2-add-atl2-driver.patch
- patch 0003-net-remove-LLTX-in-atl2-driver.patch
- patch 0004-net-add-net-poll-support-for-atl2-driver.patch
-</literallayout>
-</para>
-
- </section>
-
- <section id='transforms'>
- <title>Transforms</title>
-<para>
-This section shows an example of transforms:
-<literallayout class='monospaced'>
- # either of the next two options will trigger an 'auto'
- # branch from existing ones, since they change the commit
- # order and hence must construct their own branch
-
- # this changes the order of future includes, if the
- # passed feature is detected, the first feature is
- # included AFTER it
- include features/rt/rt.scc after features/kgdb/kgdb
- # this also changes the order of existing branches
- # this prevents the named feature from ever being
- # included
- exclude features/dynamic_ftrace/dynamic_ftrace.scc
-
- # inherit the standard kernel
- include ktypes/standard/standard
-
-
- # LTT supplies this, so we don't want the sub-chunk from RT.
- patch_trigger arch:all exclude ftrace-upstream-tracepoints.patch
- # ...but we still want the one unique tracepoint it added.
- patch tracepoint-add-for-sched_resched_task.patch
-
- # these will change the named patches in the series into
- # &lt;patch name&gt;.patch.&lt;feature name&gt;
- # where the substituted patch is in this directory
- patch_trigger arch:all ctx_mod dynamic_printk.patch
- patch_trigger arch:all ctx_mod 0001-Implement-futex-macros-for-ARM.patch
- # unconditionally exclude a patch
- patch_trigger arch:all exclude ftrace-fix-ARM-crash.patch
-</literallayout>
-</para>
- </section>
- </section> -->
-
<section id='tip-dirty-string'>
<title>"-dirty" String</title>
@@ -1839,14 +809,14 @@ This section shows an example of transforms:
</para>
<para>
- You can use the Git command above to report modified, removed, or added files.
+ 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:
+ To brute force pickup and commit all such pending changes, enter the following:
<literallayout class='monospaced'>
&gt; git add .
&gt; git commit -s -a -m "getting rid of -dirty"
@@ -1857,206 +827,7 @@ This section shows an example of transforms:
Next, rebuild the kernel.
</para>
</section>
-
-<!-- <section id='kernel-transition-kernel-layer'>
- <title>Creating a Transition Kernel Layer</title>
-
- <para>
- You can temporarily use a different base kernel in Yocto Project by doing the following:
-
- <orderedlist>
- <listitem><para>Create a custom kernel layer.</para></listitem>
- <listitem><para>Create a Git repository of the transition kernel.</para></listitem>
- </orderedlist>
- </para>
-
- <para>
- Once you meet those requirements you can build multiple boards and kernels.
- You pay the setup cost only once.
- You can then add additional BSPs and options.
- </para>
-
- <para>
- Once you have the transition kernel layer in place you can evaluate
- another kernel's functionality with the goal of easing transition to an integrated and validated
- Yocto Project kernel.
- </para> -->
-
-<!--<para>
-The next few sections describe the process:
-</para> -->
- <!-- <section id='creating-a-custom-kernel-layer'>
- <title>Creating a Custom Kernel Layer</title>
-<para>
-The custom kernel layer must have the following minimum
-elements:
-<itemizedlist>
- <listitem><para>An include of the shipped Yocto Project kernel layer.</para></listitem>
- <listitem><para>A kernel-cache with an override of the standard kernel type.</para></listitem>
-</itemizedlist>
-</para>
-<para>
-This allows the inheritance of the kernel build infrastructure,
-while overriding the list of patches that should be applied to
-the base kernel.
-</para>
-<para>
-The kernel layer can optionally include an override to the base
-Yocto Project Linux BSP to inhibit the application of BSP specific
-patches. If a custom BSP is being used, this is not required.
-</para>
- </section> -->
-
- <!-- <section id='git-repo-of-the-transition-kernel'>
- <title>Git Repo of the Transition Kernel</title>
-<para>
-The kernel build system requires a base kernel repository to
-seed the build process. This repository must be found in the
-same layer as the build infrastructure (i.e wrll-linux-2.6.27)
-in the <filename>.git</filename> subdir, with the name 'default_kernel'
-</para>
-<para>Since Yocto Project Linux ships with a default_kernel
-(the validated Yocto Project kernel) in the wrll-linux-2.6.27
-kernel layer, that must be removed and replaced with the
-transition kernel.
-</para>
-<para>If the Yocto Project install cannot be directly modified
-with the new default kernel, then the path to the transition
-kernel layer's <filename>.git</filename> subdir must be passed to the build
-process via:
-<programlisting>
-linux_GIT_BASE=&lt;absolute path to layer&gt;/git
-</programlisting>
-</para>
-<para>
-If the transition kernel has not been delivered via Git,
-then a Git repo should be created, and bare cloned into
-place. Creating this repository is as simple as:
-<literallayout class='monospaced'>
- &gt; tar zxvf temp_kernel.tgz
- &gt; cd temp_kernel
- &gt; git init
- &gt; git add .
- &gt; git commit -a -m "Transition kernel baseline"
-
- 'temp_kernel' can now be cloned into place via:
-
- &gt; cd &lt;path to git base&gt;/git
- &gt; git clone &dash;&dash;bare &lt;path to temp_kernel/temp_kernel default_kernel
-</literallayout>
-</para>
- </section> -->
-
- <!-- <section id='building-the-kernel'>
- <title>Building the Kernel</title>
-<para>
-Once these prerequisites have been met, the kernel can be
-built with:
-<literallayout class='monospaced'>
- &gt; make linux
-</literallayout>
-</para>
-<para>
-The new base kernel will be cloned into place and have any patches
-indicated in the transition kernel's cache (or templates) applied.
-The kernel build will detect the non-Yocto Project base repo and
-use the HEAD of the tree for the build.
-</para>
- </section> -->
-
- <!-- <section id='example'>
- <title>Example</title>
-<para>
-This example creates a kernel layer to build the latest
-kernel.org tree as the 'common_pc' BSP.
-<literallayout class='monospaced'>
- &gt; cd &lt;path to layers&gt;
- &gt; mkdir wrll-linux-my_version
- &gt; cd wrll-linux-my_version
- &gt; echo "wrll-linux-2.6.27" &gt; include
- &gt; mkdir -p kernel-cache/ktypes/standard
- &gt; mkdir -p kernel-cache/bsp/common_pc
- &gt; echo "v2.6.29" &gt; kernel-cache/kver
- &gt; echo "branch common_pc-standard" &gt; kernel-cache/bsp/common_pc/common_pc.scc
- &gt; echo "kconf hardware common_pc.cfg" &gt;&gt; kernel-cache/bsp/common_pc/common_pc.scc
- &gt; echo "CONFIG_FOO=y" &gt; kernel-cache/bsp/common_pc/common_pc.cfg
- &gt; mkdir git
- &gt; cd git
- &gt; git clone &dash;&dash;bare git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git default_kernel
-</literallayout>
-</para>
-<para>
-Configure a build to use the new layer. This means that:
-<literallayout class='monospaced'>
- &dash;&dash;enable-kernel-version=my_version
-</literallayout>
-</para>
-<para>
-Should be used to override the shipped default.
-</para>
-<para>
-To build the kernel:
-<literallayout class='monospaced'>
- &gt; cd build
- &gt; make linux_GIT_BASE=&lt;layer path&gt;/wrll-linux-my_version/git linux
-</literallayout>
-</para>
-<para>
-If this is to build without some user intervention (passing of the
-GIT_BASE), you must do the clone into the <filename>wrll-linux-2.6.27/.git</filename> directory.
-</para>
-<note><para>Unless you define valid "hardware.kcf" and "non-hardware.kcf" some
-non fatal warnings will be seen. They can be fixed by populating these
-files in the kernel-cache with valid hardware and non hardware config
-options.
-</para></note>
- </section> -->
-<!-- </section> -->
</section>
-
-
-
-
-
-<!-- <itemizedlist>
- <listitem><para>Introduction to this section.</para></listitem>
- <listitem><para>Constructing a project-specific kernel tree.</para></listitem>
- <listitem><para>Building the kernel.</para></listitem>
- <listitem><para>Seeing what has changed.</para></listitem>
- <listitem><para>Seeing what has changed in a particular branch.</para></listitem>
- <listitem><para>Modifying the kernel.</para></listitem>
- <listitem><para>Saving modifications.</para></listitem>
- <listitem><para>Storing patches outside of the kernel source repository (bulk export).</para></listitem>
- <listitem><para>Working with incremental changes.</para></listitem>
- <listitem><para>Extracting commited changes from a working directory (exporting internally through
- patches.</para></listitem>
- <listitem><para>Pushing commited changes.</para></listitem>
- <listitem><para>Exporting for external (upstream) submission.</para></listitem>
- <listitem><para>Exporting for import into another Source Control Manager (SCM).</para></listitem>
- <listitem><para>Working with the Yocto Project kernel in another SCM.</para>
- <itemizedlist>
- <listitem><para>Exporting the delivered kernel to an SCM.</para></listitem>
- <listitem><para>Importing changed for the build.</para></listitem>
- </itemizedlist></listitem>
- <listitem><para>Migrating templates from version 2.0.</para></listitem>
- <listitem><para>Creating a new Board Support Package (BSP).</para>
- <itemizedlist>
- <listitem><para>Creating from scratch.</para></listitem>
- <listitem><para>Cloning.</para></listitem>
- </itemizedlist></listitem>
- <listitem><para>BSP bootstrapping.</para></listitem>
- <listitem><para>Applying patches to the kernel through a template.</para></listitem>
- <listitem><para>Applying patches to the kernel without using a template.</para></listitem>
- <listitem><para>Updating patches and configurations for a BSP.</para></listitem>
- <listitem><para>Using guilt to add and export patches.</para></listitem>
- <listitem><para>Using scc.</para></listitem>
- <listitem><para>Building a 'dirty' image.</para></listitem>
- <listitem><para>Temporarily using a different base kernel.</para></listitem>
- <listitem><para>Creating a custom kernel layer.</para></listitem>
- <listitem><para>Creating the Git repository of the transition kernel.</para></listitem>
- </itemizedlist> -->
-
-
</chapter>
<!--
vim: expandtab tw=80 ts=4