Yocto 2.4
Move OpenBMC to Yocto 2.4(rocko)
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I12057b18610d6fb0e6903c60213690301e9b0c67
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index ac91749..fbecc13 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -7,245 +7,613 @@
<section id='kernel-big-picture'>
<title>Yocto Project Kernel Development and Maintenance</title>
+
<para>
- Kernels available through the Yocto Project, like other kernels, are based off the Linux
- kernel releases from <ulink url='http://www.kernel.org'></ulink>.
- At the beginning of a major development cycle, the Yocto Project team
- chooses its kernel based on factors such as release timing, the anticipated release
- timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
+ Kernels available through the Yocto Project (Yocto Linux kernels),
+ like other kernels, are based off the Linux kernel releases from
+ <ulink url='http://www.kernel.org'></ulink>.
+ At the beginning of a major Linux kernel development cycle, the
+ Yocto Project team chooses a Linux kernel based on factors such as
+ release timing, the anticipated release timing of final upstream
+ <filename>kernel.org</filename> versions, and Yocto Project
feature requirements.
- Typically, the kernel chosen is in the
- final stages of development by the community.
- In other words, the kernel is in the release
- candidate or "rc" phase and not yet a final release.
- But, by being in the final stages of external development, the team knows that the
- <filename>kernel.org</filename> final release will clearly be within the early stages of
- the Yocto Project development window.
+ Typically, the Linux kernel chosen is in the final stages of
+ development by the Linux community.
+ In other words, the Linux kernel is in the release candidate
+ or "rc" phase and has yet to reach final release.
+ But, by being in the final stages of external development, the
+ team knows that the <filename>kernel.org</filename> final release
+ will clearly be within the early stages of the Yocto Project
+ development window.
</para>
+
<para>
- This balance allows the team to deliver the most up-to-date kernel
- possible, while still ensuring that the team has a stable official release for
- the baseline Linux kernel version.
+ This balance allows the Yocto Project team to deliver the most
+ up-to-date Yocto Linux kernel possible, while still ensuring that
+ the team has a stable official release for the baseline Linux
+ kernel version.
</para>
+
<para>
- The ultimate source for kernels available through the Yocto Project are released kernels
- from <filename>kernel.org</filename>.
- In addition to a foundational kernel from <filename>kernel.org</filename>, the
- kernels available contain a mix of important new mainline
- developments, non-mainline developments (when there is no alternative),
- Board Support Package (BSP) developments,
- and custom features.
- These additions result in a commercially released Yocto Project Linux kernel that caters
- to specific embedded designer needs for targeted hardware.
+ As implied earlier, the ultimate source for Yocto Linux kernels
+ are released kernels from <filename>kernel.org</filename>.
+ In addition to a foundational kernel from
+ <filename>kernel.org</filename>, the available Yocto Linux kernels
+ contain a mix of important new mainline developments, non-mainline
+ developments (when no alternative exists), Board Support Package
+ (BSP) developments, and custom features.
+ These additions result in a commercially released Yocto
+ Project Linux kernel that caters to specific embedded designer
+ needs for targeted hardware.
</para>
+
<para>
- Once a kernel is officially released, the Yocto Project team goes into
- their next development cycle, or upward revision (uprev) cycle, while still
- continuing maintenance on the released kernel.
+ You can find a web interface to the Yocto Linux kernels in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ at
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
+ If you look at the interface, you will see to the left a
+ grouping of Git repositories titled "Yocto Linux Kernel".
+ Within this group, you will find several Linux Yocto kernels
+ developed and included with Yocto Project releases:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>linux-yocto-4.1</filename>:</emphasis>
+ The stable Yocto Project kernel to use with the Yocto
+ Project Release 2.0.
+ This kernel is based on the Linux 4.1 released kernel.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>linux-yocto-4.4</filename>:</emphasis>
+ The stable Yocto Project kernel to use with the Yocto
+ Project Release 2.1.
+ This kernel is based on the Linux 4.4 released kernel.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>linux-yocto-4.6</filename>:</emphasis>
+ A temporary kernel that is not tied to any Yocto Project
+ release.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>linux-yocto-4.8</filename>:</emphasis>
+ The stable yocto Project kernel to use with the Yocto
+ Project Release 2.2.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>linux-yocto-4.9</filename>:</emphasis>
+ The stable Yocto Project kernel to use with the Yocto
+ Project Release 2.3.
+ This kernel is based on the Linux 4.9 released kernel.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>linux-yocto-4.10</filename>:</emphasis>
+ The default stable Yocto Project kernel to use with the
+ Yocto Project Release 2.3.
+ This kernel is based on the Linux 4.10 released kernel.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>linux-yocto-4.12</filename>:</emphasis>
+ The default stable Yocto Project kernel to use with the
+ Yocto Project Release 2.4.
+ This kernel is based on the Linux 4.12 released kernel.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>yocto-kernel-cache</filename>:</emphasis>
+ The <filename>linux-yocto-cache</filename> contains
+ patches and configurations for the linux-yocto kernel
+ tree.
+ This repository is useful when working on the linux-yocto
+ kernel.
+ For more information on this "Advanced Kernel Metadata",
+ see the
+ "<link linkend='kernel-dev-advanced'>Working With Advanced Metadata (<filename>yocto-kernel-cache</filename>)</link>"
+ Chapter.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>linux-yocto-dev</filename>:</emphasis>
+ A development kernel based on the latest upstream release
+ candidate available.
+ </para></listitem>
+ </itemizedlist>
+ <note><title>Notes</title>
+ Long Term Support Initiative (LTSI) for Yocto Linux
+ kernels is as follows:
+ <itemizedlist>
+ <listitem><para>
+ For Yocto Project releases 1.7, 1.8, and 2.0,
+ the LTSI kernel is
+ <filename>linux-yocto-3.14</filename>.
+ </para></listitem>
+ <listitem><para>
+ For Yocto Project releases 2.1, 2.2, and 2.3,
+ the LTSI kernel is <filename>linux-yocto-4.1</filename>.
+ </para></listitem>
+ <listitem><para>
+ For Yocto Project release 2.4, the LTSI kernel is
+ <filename>linux-yocto-4.9</filename>
+ </para></listitem>
+ <listitem><para>
+ <filename>linux-yocto-4.4</filename> is an LTS
+ kernel.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ Once a Yocto Linux kernel is officially released, the Yocto
+ Project team goes into their next development cycle, or upward
+ revision (uprev) cycle, while still continuing maintenance on the
+ released kernel.
It is important to note that the most sustainable and stable way
- to include feature development upstream is through a kernel uprev process.
- Back-porting hundreds of individual fixes and minor features from various
- kernel versions is not sustainable and can easily compromise quality.
+ to include feature development upstream is through a kernel uprev
+ process.
+ Back-porting hundreds of individual fixes and minor features from
+ various kernel versions is not sustainable and can easily
+ compromise quality.
</para>
+
<para>
- During the uprev cycle, the Yocto Project team uses an ongoing analysis of
- kernel development, BSP support, and release timing to select the best
- possible <filename>kernel.org</filename> version.
- The team continually monitors community kernel
- development to look for significant features of interest.
- The team does consider back-porting large features if they have a significant advantage.
- User or community demand can also trigger a back-port or creation of new
- functionality in the Yocto Project baseline kernel during the uprev cycle.
+ During the uprev cycle, the Yocto Project team uses an ongoing
+ analysis of Linux kernel development, BSP support, and release
+ timing to select the best possible <filename>kernel.org</filename>
+ Linux kernel version on which to base subsequent Yocto Linux
+ kernel development.
+ The team continually monitors Linux community kernel development
+ to look for significant features of interest.
+ The team does consider back-porting large features if they have a
+ significant advantage.
+ User or community demand can also trigger a back-port or creation
+ of new functionality in the Yocto Project baseline kernel during
+ the uprev cycle.
</para>
+
<para>
- Generally speaking, every new kernel both adds features and introduces new bugs.
- These consequences are the basic properties of upstream kernel development and are
- managed by the Yocto Project team's kernel strategy.
- It is the Yocto Project team's policy to not back-port minor features to the released kernel.
- They only consider back-porting significant technological jumps - and, that is done
- after a complete gap analysis.
- The reason for this policy is that back-porting any small to medium sized change
- from an evolving kernel can easily create mismatches, incompatibilities and very
- subtle errors.
+ Generally speaking, every new Linux kernel both adds features and
+ introduces new bugs.
+ These consequences are the basic properties of upstream
+ Linux kernel development and are managed by the Yocto Project
+ team's Yocto Linux kernel development strategy.
+ It is the Yocto Project team's policy to not back-port minor
+ features to the released Yocto Linux kernel.
+ They only consider back-porting significant technological
+ jumps ‐ and, that is done after a complete gap analysis.
+ The reason for this policy is that back-porting any small to
+ medium sized change from an evolving Linux kernel can easily
+ create mismatches, incompatibilities and very subtle errors.
</para>
+
<para>
- These policies result in both a stable and a cutting
- edge kernel that mixes forward ports of existing features and significant and critical
- new functionality.
- Forward porting functionality in the kernels available through the Yocto Project kernel
- can be thought of as a "micro uprev."
- The many “micro uprevs” produce a kernel version with a mix of
- important new mainline, non-mainline, BSP developments and feature integrations.
- This kernel gives insight into new features and allows focused
- amounts of testing to be done on the kernel, which prevents
- surprises when selecting the next major uprev.
- The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
- feature and BSP development.
+ The policies described in this section result in both a stable
+ and a cutting edge Yocto Linux kernel that mixes forward ports of
+ existing Linux kernel features and significant and critical new
+ functionality.
+ Forward porting Linux kernel functionality into the Yocto Linux
+ kernels available through the Yocto Project can be thought of as
+ a "micro uprev."
+ The many “micro uprevs” produce a Yocto Linux kernel version with
+ a mix of important new mainline, non-mainline, BSP developments
+ and feature integrations.
+ This Yocto Linux kernel gives insight into new features and
+ allows focused amounts of testing to be done on the kernel,
+ which prevents surprises when selecting the next major uprev.
+ The quality of these cutting edge Yocto Linux kernels is evolving
+ and the kernels are used in leading edge feature and BSP
+ development.
</para>
</section>
- <section id='kernel-architecture'>
- <title>Kernel Architecture</title>
+ <section id='yocto-linux-kernel-architecture-and-branching-strategies'>
+ <title>Yocto Linux Kernel Architecture and Branching Strategies</title>
+
<para>
- This section describes the architecture of the kernels available through the
- Yocto Project and provides information
- on the mechanisms used to achieve that architecture.
+ As mentioned earlier, a key goal of the Yocto Project is
+ to present the developer with a kernel that has a clear and
+ continuous history that is visible to the user.
+ The architecture and mechanisms, in particular the branching
+ strategies, used achieve that goal in a manner similar to
+ upstream Linux kernel development in
+ <filename>kernel.org</filename>.
</para>
- <section id='architecture-overview'>
- <title>Overview</title>
- <para>
- As mentioned earlier, a key goal of the Yocto Project is to present the
- developer with
- a kernel that has a clear and continuous history that is visible to the user.
- The architecture and mechanisms used achieve that goal in a manner similar to the
- upstream <filename>kernel.org</filename>.
- </para>
- <para>
- You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
- added features logically structured on top of the baseline.
- The features are tagged and organized by way of a branching strategy implemented by the
- source code manager (SCM) Git.
- For information on Git as applied to the Yocto Project, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
- Yocto Project Development Manual.
- </para>
- <para>
- The result is that the user has the ability to see the added features and
- the commits that make up those features.
- In addition to being able to see added features, the user can also view the history of what
- made up the baseline kernel.
- </para>
- <para>
- The following illustration shows the conceptual Yocto Project kernel.
- </para>
- <para>
- <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
- </para>
- <para>
- In the illustration, the "Kernel.org Branch Point"
- marks the specific spot (or release) from
- which the Yocto Project kernel is created.
- From this point "up" in the tree, features and differences are organized and tagged.
- </para>
- <para>
- The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
- type and BSP that is organized further up the tree.
- Placing these common features in the
- tree this way means features do not have to be duplicated along individual branches of the
- structure.
- </para>
- <para>
- From the Yocto Project Baseline Kernel, branch points represent specific functionality
- for individual BSPs as well as real-time kernels.
- The illustration represents this through three BSP-specific branches and a real-time
- kernel branch.
- Each branch represents some unique functionality for the BSP or a real-time kernel.
- </para>
- <para>
- In this example structure, the real-time kernel branch has common features for all
- real-time kernels and contains
- more branches for individual BSP-specific real-time kernels.
- The illustration shows three branches as an example.
- Each branch points the way to specific, unique features for a respective real-time
- kernel as they apply to a given BSP.
- </para>
- <para>
- The resulting tree structure presents a clear path of markers (or branches) to the
- developer that, for all practical purposes, is the kernel needed for any given set
- of requirements.
- </para>
- </section>
+ <para>
+ You can think of a Yocto Linux kernel as consisting of a
+ baseline Linux kernel with added features logically structured
+ on top of the baseline.
+ The features are tagged and organized by way of a branching
+ strategy implemented by the Yocto Project team using the
+ Source Code Manager (SCM) Git.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Git is the obvious SCM for meeting the Yocto Linux
+ kernel organizational and structural goals described
+ in this section.
+ Not only is Git the SCM for Linux kernel development in
+ <filename>kernel.org</filename> but, Git continues to
+ grow in popularity and supports many different work
+ flows, front-ends and management techniques.
+ </para></listitem>
+ <listitem><para>
+ You can find documentation on Git at
+ <ulink url='http://git-scm.com/documentation'></ulink>.
+ You can also get an introduction to Git as it
+ applies to the Yocto Project in the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
+ section in the Yocto Project Reference Manual.
+ The latter reference provides an overview of
+ Git and presents a minimal set of Git commands
+ that allows you to be functional using Git.
+ 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 Expert" in order to
+ use it with the Yocto Project.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
- <section id='branching-and-workflow'>
- <title>Branching Strategy and Workflow</title>
- <para>
- The Yocto Project team creates kernel branches at points where functionality is
- no longer shared and thus, needs to be isolated.
- For example, board-specific incompatibilities would require different functionality
- and would require a branch to separate the features.
- Likewise, for specific kernel features, the same branching strategy is used.
- </para>
- <para>
- This branching strategy results in a tree that has features organized to be specific
- for particular functionality, single kernel types, or a subset of kernel types.
- This strategy also results in not having to store the same feature twice
- internally in the tree.
- Rather, the kernel team stores the unique differences required to apply the
- feature onto the kernel type in question.
- <note>
- The Yocto Project team strives to place features in the tree such that they can be
- shared by all boards and kernel types where possible.
- However, during development cycles or when large features are merged,
- the team cannot always follow this practice.
- In those cases, the team uses isolated branches to merge features.
- </note>
- </para>
- <para>
- BSP-specific code additions are handled in a similar manner to kernel-specific additions.
- Some BSPs only make sense given certain kernel types.
- So, for these types, the team creates branches off the end of that kernel type for all
- of the BSPs that are supported on that kernel type.
- From the perspective of the tools that create the BSP branch, the BSP is really no
- different than a feature.
- Consequently, the same branching strategy applies to BSPs as it does to features.
- So again, rather than store the BSP twice, the team only stores the unique
- differences for the BSP across the supported multiple kernels.
- </para>
- <para>
- While this strategy can result in a tree with a significant number of branches, it is
- important to realize that from the developer's point of view, there is a linear
- path that travels from the baseline <filename>kernel.org</filename>, through a select
- group of features and ends with their BSP-specific commits.
- In other words, the divisions of the kernel are transparent and are not relevant
- to the developer on a day-to-day basis.
- From the developer's perspective, this path is the "master" branch.
- The developer does not need to be aware of the existence of any other branches at all.
- Of course, there is value in the existence of these branches
- in the tree, should a person decide to explore them.
- For example, a comparison between two BSPs at either the commit level or at the line-by-line
- code <filename>diff</filename> level is now a trivial operation.
- </para>
- <para>
- Working with the kernel as a structured tree follows recognized community best practices.
- In particular, the kernel as shipped with the product, should be
- considered an "upstream source" and viewed as a series of
- historical and documented modifications (commits).
- These modifications represent the development and stabilization done
- by the Yocto Project kernel development team.
- </para>
- <para>
- Because commits only change at significant release points in the product life cycle,
- developers can work on a branch created
- from the last relevant commit in the shipped Yocto Project kernel.
- As mentioned previously, the structure is transparent to the developer
- because the kernel tree is left in this state after cloning and building the kernel.
- </para>
- </section>
+ <para>
+ Using Git's tagging and branching features, the Yocto Project
+ team creates kernel branches at points where functionality is
+ no longer shared and thus, needs to be isolated.
+ For example, board-specific incompatibilities would require
+ different functionality and would require a branch to
+ separate the features.
+ Likewise, for specific kernel features, the same branching
+ strategy is used.
+ </para>
- <section id='source-code-manager-git'>
- <title>Source Code Manager - Git</title>
- <para>
- The Source Code Manager (SCM) is Git.
- This SCM is the obvious mechanism for meeting the previously mentioned goals.
- Not only is it the SCM for <filename>kernel.org</filename> but,
- Git continues to grow in popularity and supports many different work flows,
- front-ends and management techniques.
- </para>
- <para>
- You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
- You can also get an introduction to Git as it applies to the Yocto Project in the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
- section in the Yocto Project Development Manual.
- These referenced sections overview Git and describe a minimal set of
- commands that allows you to be functional using Git.
- <note>
- You can use as much, or as little, of what Git has to offer to accomplish what
- you need for your project.
- You do not have to be a "Git Master" in order to use it with the Yocto Project.
- </note>
- </para>
- </section>
+ <para>
+ This "tree-like" architecture results in a structure that has
+ features organized to be specific for particular functionality,
+ single kernel types, or a subset of kernel types.
+ Thus, 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
+ Linux kernel.
+ </para>
+
+ <para>
+ Another consequence of this strategy 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 features can be shared by all boards and kernel
+ types where possible.
+ However, during development cycles or when large features
+ are merged, the team cannot always follow this practice.
+ In those cases, the team uses isolated branches to merge
+ features.
+ </note>
+ </para>
+
+ <para>
+ BSP-specific code additions are handled in a similar manner to
+ kernel-specific additions.
+ Some BSPs only make sense given certain kernel types.
+ So, for these types, the team creates branches off the end
+ of that kernel type for all of the BSPs that are supported on
+ that kernel type.
+ From the perspective of the tools that create the BSP branch,
+ the BSP is really no different than a feature.
+ Consequently, the same branching strategy applies to BSPs as
+ it does to kernel features.
+ So again, rather than store the BSP twice, the team only
+ stores the unique differences for the BSP across the supported
+ multiple kernels.
+ </para>
+
+ <para>
+ While this strategy can result in a tree with a significant number
+ of branches, it is important to realize that from the developer's
+ point of view, there is a linear path that travels from the
+ baseline <filename>kernel.org</filename>, through a select
+ group of features and ends with their BSP-specific commits.
+ In other words, the divisions of the kernel are transparent and
+ are not relevant to the developer on a day-to-day basis.
+ From the developer's perspective, this path is the "master" branch
+ in Git terms.
+ The developer does not need to be aware of the existence of any
+ other branches at all.
+ Of course, value exists in the having these branches in the tree,
+ should a person decide to explore them.
+ For example, a comparison between two BSPs at either the commit
+ level or at the line-by-line code <filename>diff</filename> level
+ is now a trivial operation.
+ </para>
+
+ <para>
+ The following illustration shows the conceptual Yocto
+ Linux kernel.
+ <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 Linux kernel release) from which the
+ Yocto Linux kernel is created.
+ From this point forward 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 along in the tree.
+ Placing these common features in the tree this way means
+ features do not have to be duplicated along individual
+ branches of the tree structure.
+ </para>
+
+ <para>
+ From the "Yocto Project Baseline Kernel", branch points represent
+ specific functionality for individual Board Support Packages
+ (BSPs) as well as real-time kernels.
+ The illustration represents this through three BSP-specific
+ branches and a real-time kernel branch.
+ Each branch represents some unique functionality for the BSP
+ or for a real-time Yocto Linux kernel.
+ </para>
+
+ <para>
+ In this example structure, the "Real-time (rt) Kernel" branch has
+ common features for all real-time Yocto Linux kernels and
+ contains more branches for individual BSP-specific real-time
+ kernels.
+ The illustration shows three branches as an example.
+ Each branch points the way to specific, unique features for a
+ respective real-time kernel as they apply to a given BSP.
+ </para>
+
+ <para>
+ The resulting tree structure presents a clear path of markers
+ (or branches) to the developer that, for all practical
+ purposes, is the Yocto Linux kernel needed for any given set of
+ requirements.
+ <note>
+ Keep in mind the figure does not take into account all the
+ supported Yocto Linux kernels, but rather shows a single
+ generic kernel just for conceptual purposes.
+ Also keep in mind that this structure represents the Yocto
+ Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ that are either pulled from during the build or established
+ on the host development system prior to the build by either
+ cloning a particular kernel's Git repository or by
+ downloading and unpacking a tarball.
+ </note>
+ </para>
+
+ <para>
+ Working with the kernel as a structured tree follows recognized
+ community best practices.
+ In particular, the kernel as shipped with the product, should be
+ considered an "upstream source" and viewed as a series of
+ historical and documented modifications (commits).
+ These modifications represent the development and stabilization
+ done by the Yocto Project kernel development team.
+ </para>
+
+ <para>
+ Because commits only change at significant release points in the
+ product life cycle, developers can work on a branch created
+ from the last relevant commit in the shipped Yocto Project Linux
+ kernel.
+ As mentioned previously, the structure is transparent to the
+ developer because the kernel tree is left in this state after
+ cloning and building the kernel.
+ </para>
+ </section>
+
+ <section id='kernel-build-file-hierarchy'>
+ <title>Kernel Build File Hierarchy</title>
+
+ <para>
+ Upstream storage of all the available kernel source code is
+ one thing, while representing and using the code on your host
+ development system is another.
+ Conceptually, you can think of the kernel source repositories
+ as all the source files necessary for all the supported
+ Yocto Linux kernels.
+ As a developer, you are just interested in the source files
+ for the kernel on which you are working.
+ And, furthermore, you need them available on your host system.
+ </para>
+
+ <para>
+ Kernel source code is available on your host system several
+ different ways:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Files Accessed While using <filename>devtool</filename>:</emphasis>
+ <filename>devtool</filename>, which is available with the
+ Yocto Project, is the preferred method by which to
+ modify the kernel.
+ See the
+ "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Cloned Repository:</emphasis>
+ If you are working in the kernel all the time, you probably
+ would want to set up your own local Git repository of the
+ Yocto Linux kernel tree.
+ For information on how to clone a Yocto Linux kernel
+ Git repository, see the
+ "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Temporary Source Files from a Build:</emphasis>
+ If you just need to make some patches to the kernel using
+ a traditional BitBake workflow (i.e. not using the
+ <filename>devtool</filename>), you can access temporary
+ kernel source files that were extracted and used during
+ a kernel build.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The temporary kernel source files resulting from a build using
+ BitBake have a particular hierarchy.
+ When you build the kernel on your development system, all files
+ needed for the build are taken from the source repositories
+ pointed to by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ variable and gathered in a temporary work area where they are
+ subsequently used to create the unique kernel.
+ Thus, in a sense, the process constructs a local source tree
+ specific to your kernel from which to generate the new kernel
+ image.
+ </para>
+
+ <para>
+ The following figure shows the temporary file structure
+ created on your host system when you build the kernel using
+ Bitbake.
+ This
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ contains all the source files used during the build.
+ <imagedata fileref="figures/kernel-overview-2-generic.png"
+ width="6in" depth="5in" align="center" scale="100" />
+ </para>
+
+ <para>
+ Again, for additional information on the Yocto Project kernel's
+ architecture and its branching strategy, see the
+ "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>"
+ section.
+ You can also reference the
+ "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
+ and
+ "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
+ sections for detailed example that modifies the kernel.
+ </para>
+ </section>
+
+ <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'>
+ <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title>
+
+ <para>
+ This section describes part of the kernel configuration audit
+ phase that most developers can ignore.
+ For general information on kernel configuration including
+ <filename>menuconfig</filename>, <filename>defconfig</filename>
+ files, and configuration fragments, see the
+ "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
+ section.
+ </para>
+
+ <para>
+ During this part of the audit phase, the contents of the final
+ <filename>.config</filename> file are compared against the
+ fragments specified by the system.
+ These fragments can be system fragments, distro fragments,
+ or user-specified configuration elements.
+ Regardless of their origin, the OpenEmbedded build system
+ warns the user if a specific option is not included in the
+ final kernel configuration.
+ </para>
+
+ <para>
+ By default, in order to not overwhelm the user with
+ configuration warnings, the system only reports missing
+ "hardware" options as they could result in a boot
+ failure or indicate that important hardware is not available.
+ </para>
+
+ <para>
+ To determine whether or not a given option is "hardware" or
+ "non-hardware", the kernel Metadata in
+ <filename>yocto-kernel-cache</filename> contains files that
+ classify individual or groups of options as either hardware
+ or non-hardware.
+ To better show this, consider a situation where the
+ <filename>yocto-kernel-cache</filename> contains the following
+ files:
+ <literallayout class='monospaced'>
+ yocto-kernel-cache/features/drm-psb/hardware.cfg
+ yocto-kernel-cache/features/kgdb/hardware.cfg
+ yocto-kernel-cache/ktypes/base/hardware.cfg
+ yocto-kernel-cache/bsp/mti-malta32/hardware.cfg
+ yocto-kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg
+ yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg
+ yocto-kernel-cache/bsp/qemuarma9/hardware.cfg
+ yocto-kernel-cache/bsp/mti-malta64/hardware.cfg
+ yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg
+ yocto-kernel-cache/bsp/common-pc/hardware.cfg
+ yocto-kernel-cache/bsp/common-pc-64/hardware.cfg
+ yocto-kernel-cache/features/rfkill/non-hardware.cfg
+ yocto-kernel-cache/ktypes/base/non-hardware.cfg
+ yocto-kernel-cache/features/aufs/non-hardware.kcf
+ yocto-kernel-cache/features/ocf/non-hardware.kcf
+ yocto-kernel-cache/ktypes/base/non-hardware.kcf
+ yocto-kernel-cache/ktypes/base/hardware.kcf
+ yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf
+ </literallayout>
+ The following list provides explanations for the various
+ files:
+ <itemizedlist>
+ <listitem><para>
+ <filename>hardware.kcf</filename>:
+ Specifies a list of kernel Kconfig files that contain
+ hardware options only.
+ </para></listitem>
+ <listitem><para>
+ <filename>non-hardware.kcf</filename>:
+ Specifies a list of kernel Kconfig files that contain
+ non-hardware options only.
+ </para></listitem>
+ <listitem><para>
+ <filename>hardware.cfg</filename>:
+ Specifies a list of kernel <filename>CONFIG_</filename>
+ options that are hardware, regardless of whether or not
+ they are within a Kconfig file specified by a hardware
+ or non-hardware Kconfig file (i.e.
+ <filename>hardware.kcf</filename> or
+ <filename>non-hardware.kcf</filename>).
+ </para></listitem>
+ <listitem><para>
+ <filename>non-hardware.cfg</filename>:
+ Specifies a list of kernel <filename>CONFIG_</filename>
+ options that are not hardware, regardless of whether or
+ not they are within a Kconfig file specified by a
+ hardware or non-hardware Kconfig file (i.e.
+ <filename>hardware.kcf</filename> or
+ <filename>non-hardware.kcf</filename>).
+ </para></listitem>
+ </itemizedlist>
+ Here is a specific example using the
+ <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>:
+ <literallayout class='monospaced'>
+ CONFIG_SERIAL_8250
+ CONFIG_SERIAL_8250_CONSOLE
+ CONFIG_SERIAL_8250_NR_UARTS
+ CONFIG_SERIAL_8250_PCI
+ CONFIG_SERIAL_CORE
+ CONFIG_SERIAL_CORE_CONSOLE
+ CONFIG_VGA_ARB
+ </literallayout>
+ The kernel configuration audit automatically detects these
+ files (hence the names must be exactly the ones discussed here),
+ and uses them as inputs when generating warnings about the
+ final <filename>.config</filename> file.
+ </para>
+
+ <para>
+ A user-specified kernel Metadata repository, or recipe space
+ feature, can use these same files to classify options that are
+ found within its <filename>.cfg</filename> files as hardware
+ or non-hardware, to prevent the OpenEmbedded build system from
+ producing an error or warning when an option is not in the
+ final <filename>.config</filename> file.
+ </para>
</section>
</appendix>
<!--