mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-04-17 18:32:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

sphinx: remove DocBook files

Browse Source 
The Yocto Project documentation was migrated to Sphinx. Let's remove
the deprecated DocBook files.

(From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Nicolas Dechesne
2020-10-05 16:30:32 +02:00
committed by Richard Purdie
parent 1fd9c4b2c0
commit 43d07a2851
208 changed files with 0 additions and 100194 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1257
documentation/kernel-dev/kernel-dev-advanced.xml
View File

File diff suppressed because it is too large Load Diff

2730
documentation/kernel-dev/kernel-dev-common.xml
View File

File diff suppressed because it is too large Load Diff

622
documentation/kernel-dev/kernel-dev-concepts-appx.xml
View File

@@ -1,622 +0,0 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
<appendix id='kernel-dev-concepts-appx'>
<title>Advanced Kernel Concepts</title>
<section id='kernel-big-picture'>
<title>Yocto Project Kernel Development and Maintenance</title>
<para>
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 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 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>
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>
You can find a web interface to the Yocto Linux kernels in the
<ulink url='&YOCTO_DOCS_OM_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.
</para>
<para>
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 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 &dash; 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>
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='yocto-linux-kernel-architecture-and-branching-strategies'>
<title>Yocto Linux Kernel Architecture and Branching Strategies</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, in particular the branching
strategies, used achieve that goal in a manner similar to
upstream Linux kernel development in
<filename>kernel.org</filename>.
</para>
<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_OM_URL;#git'>Git</ulink>"
section in the Yocto Project Overview and Concepts
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>
<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>
<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_OM_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/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>
<!--
vim: expandtab tw=80 ts=4
-->

28
documentation/kernel-dev/kernel-dev-customization.xsl
View File

@@ -1,28 +0,0 @@
<?xml version='1.0'?>
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
<xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
<!--
<xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
<xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-->
<xsl:include href="../template/permalinks.xsl"/>
<xsl:include href="../template/section.title.xsl"/>
<xsl:include href="../template/component.title.xsl"/>
<xsl:include href="../template/division.title.xsl"/>
<xsl:include href="../template/formal.object.heading.xsl"/>
<xsl:param name="html.stylesheet" select="'kernel-dev-style.css'" />
<xsl:param name="chapter.autolabel" select="1" />
<xsl:param name="appendix.autolabel">A</xsl:param>
<xsl:param name="section.autolabel" select="1" />
<xsl:param name="section.label.includes.component.label" select="1" />
</xsl:stylesheet>

143
documentation/kernel-dev/kernel-dev-faq.xml
View File

@@ -1,143 +0,0 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
<appendix id='kernel-dev-faq'>
<title>Kernel Development FAQ</title>
<section id='kernel-dev-faq-section'>
<title>Common Questions and Solutions</title>
<para>
The following lists some solutions for common questions.
<qandaset>
<qandaentry>
<question>
<para>
How do I use my own Linux kernel <filename>.config</filename>
file?
</para>
</question>
<answer>
<para>
Refer to the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
section for information.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I create configuration fragments?
</para>
</question>
<answer>
<para>
Refer to the
"<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
section for information.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I use my own Linux kernel sources?
</para>
</question>
<answer>
<para>
Refer to the "<link linkend='working-with-your-own-sources'>Working With Your Own Sources</link>"
section for information.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I install/not-install the kernel image on the rootfs?
</para>
</question>
<answer>
<para>
The kernel image (e.g. <filename>vmlinuz</filename>) is provided
by the <filename>kernel-image</filename> package.
Image recipes depend on <filename>kernel-base</filename>.
To specify whether or not the kernel
image is installed in the generated root filesystem, override
<filename>RDEPENDS_kernel-base</filename> to include or not
include "kernel-image".</para>
<para>See the
"<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
section in the Yocto Project Development Tasks Manual
for information on how to use an append file to
override metadata.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I install a specific kernel module?
</para>
</question>
<answer>
<para>
Linux kernel modules are packaged individually.
To ensure a specific kernel module is included in an image,
include it in the appropriate machine
<ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
variable.</para>
<para>These other variables are useful for installing specific
modules:
<literallayout class='monospaced'>
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
</literallayout>
For example, set the following in the <filename>qemux86.conf</filename>
file to include the <filename>ab123</filename> kernel modules
with images built for the <filename>qemux86</filename> machine:
<literallayout class='monospaced'>
MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
</literallayout>
For more information, see the
"<link linkend='incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</link>"
section.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I change the Linux kernel command line?
</para>
</question>
<answer>
<para>
The Linux kernel command line is typically specified in
the machine config using the <filename>APPEND</filename> variable.
For example, you can add some helpful debug information doing
the following:
<literallayout class='monospaced'>
APPEND += "printk.time=y initcall_debug debug"
</literallayout>
</para>
</answer>
</qandaentry>
</qandaset>
</para>
</section>
</appendix>
<!--
vim: expandtab tw=80 ts=4
-->

260
documentation/kernel-dev/kernel-dev-intro.xml
View File

@@ -1,260 +0,0 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
<chapter id='kernel-dev-intro'>
<title>Introduction</title>
<section id='kernel-dev-overview'>
<title>Overview</title>
<para>
Regardless of how you intend to make use of the Yocto Project,
chances are you will work with the Linux kernel.
This manual describes how to set up your build host to support
kernel development, introduces the kernel development process,
provides background information on the Yocto Linux kernel
<ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
describes common tasks you can perform using the kernel tools,
shows you how to use the kernel Metadata needed to work with
the kernel inside the Yocto Project, and provides insight into how
the Yocto Project team develops and maintains Yocto Linux kernel
Git repositories and Metadata.
</para>
<para>
Each Yocto Project release has a set of Yocto Linux kernel recipes,
whose Git repositories you can view in the Yocto
<ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
the "Yocto Linux Kernel" heading.
New recipes for the release track the latest Linux kernel
upstream developments from
<ulink url='http://www.kernel.org'></ulink> and introduce
newly-supported platforms.
Previous recipes in the release are refreshed and supported for at
least one additional Yocto Project release.
As they align, these previous releases are updated to include the
latest from the Long Term Support Initiative (LTSI) project.
You can learn more about Yocto Linux kernels and LTSI in the
"<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>"
section.
</para>
<para>
Also included is a Yocto Linux kernel development recipe
(<filename>linux-yocto-dev.bb</filename>) should you want to work
with the very latest in upstream Yocto Linux kernel development and
kernel Metadata development.
<note>
For more on Yocto Linux kernels, see the
"<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>
section.
</note>
</para>
<para>
The Yocto Project also provides a powerful set of kernel
tools for managing Yocto Linux kernel sources and configuration data.
You can use these tools to make a single configuration change,
apply multiple patches, or work with your own kernel sources.
</para>
<para>
In particular, the kernel tools allow you to generate configuration
fragments that specify only what you must, and nothing more.
Configuration fragments only need to contain the highest level
visible <filename>CONFIG</filename> options as presented by the
Yocto Linux kernel <filename>menuconfig</filename> system.
Contrast this against a complete Yocto Linux kernel
<filename>.config</filename> file, which includes all the automatically
selected <filename>CONFIG</filename> options.
This efficiency reduces your maintenance effort and allows you
to further separate your configuration in ways that make sense for
your project.
A common split separates policy and hardware.
For example, all your kernels might support the
<filename>proc</filename> and <filename>sys</filename> filesystems,
but only specific boards require sound, USB, or specific drivers.
Specifying these configurations individually allows you to aggregate
them together as needed, but maintains them in only one place.
Similar logic applies to separating source changes.
</para>
<para>
If you do not maintain your own kernel sources and need to make
only minimal changes to the sources, the released recipes provide a
vetted base upon which to layer your changes.
Doing so allows you to benefit from the continual kernel
integration and testing performed during development of the
Yocto Project.
</para>
<para>
If, instead, you have a very specific Linux kernel source tree
and are unable to align with one of the official Yocto Linux kernel
recipes, an alternative exists by which you can use the Yocto
Project Linux kernel tools with your own kernel sources.
</para>
<para>
The remainder of this manual provides instructions for completing
specific Linux kernel development tasks.
These instructions assume you are comfortable working with
<ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
recipes and basic open-source development tools.
Understanding these concepts will facilitate the process of working
with the kernel recipes.
If you find you need some additional background, please be sure to
review and understand the following documentation:
<itemizedlist>
<listitem><para>
<ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
document.
</para></listitem>
<listitem><para>
<ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
</para></listitem>
<listitem><para>
<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
as described in the Yocto Project Application Development and
the Extensible Software Development Kit (eSDK) manual.
</para></listitem>
<listitem><para>
The
"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
section in the Yocto Project Development Tasks Manual.
</para></listitem>
<listitem><para>
The
"<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
section.
</para></listitem>
</itemizedlist>
</para>
</section>
<section id='kernel-modification-workflow'>
<title>Kernel Modification Workflow</title>
<para>
Kernel modification involves changing the Yocto Project kernel,
which could involve changing configuration options as well as adding
new kernel recipes.
Configuration changes can be added in the form of configuration
fragments, while recipe modification comes through the kernel's
<filename>recipes-kernel</filename> area in a kernel layer you create.
</para>
<para>
This section presents a high-level overview of the Yocto Project
kernel modification workflow.
The illustration and accompanying list provide general information
and references for further information.
<imagedata fileref="figures/kernel-dev-flow.png"
width="9in" depth="5in" align="center" scalefit="1" />
</para>
<para>
<orderedlist>
<listitem><para>
<emphasis>Set up Your Host Development System to Support
Development Using the Yocto Project</emphasis>:
See the
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>"
section in the Yocto Project Development Tasks Manual for
options on how to get a build host ready to use the Yocto
Project.
</para></listitem>
<listitem><para>
<emphasis>Set Up Your Host Development System for Kernel Development:</emphasis>
It is recommended that you use <filename>devtool</filename>
and an extensible SDK for kernel development.
Alternatively, you can use traditional kernel development
methods with the Yocto Project.
Either way, there are steps you need to take to get the
development environment ready.</para>
<para>Using <filename>devtool</filename> and the eSDK requires
that you have a clean build of the image and that you are
set up with the appropriate eSDK.
For more information, see the
"<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
section.</para>
<para>Using traditional kernel development requires that you
have the kernel source available in an isolated local Git
repository.
For more information, see the
"<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
section.
</para></listitem>
<listitem><para>
<emphasis>Make Changes to the Kernel Source Code if
applicable:</emphasis>
Modifying the kernel does not always mean directly
changing source files.
However, if you have to do this, you make the changes to the
files in the eSDK's Build Directory if you are using
<filename>devtool</filename>.
For more information, see the
"<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
section.</para>
<para>If you are using traditional kernel development, you
edit the source files in the kernel's local Git repository.
For more information, see the
"<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
section.
</para></listitem>
<listitem><para>
<emphasis>Make Kernel Configuration Changes if
Applicable:</emphasis>
If your situation calls for changing the kernel's
configuration, you can use
<link linkend='using-menuconfig'><filename>menuconfig</filename></link>,
which allows you to interactively develop and test the
configuration changes you are making to the kernel.
Saving changes you make with <filename>menuconfig</filename>
updates the kernel's <filename>.config</filename> file.
<note><title>Warning</title>
Try to resist the temptation to directly edit an
existing <filename>.config</filename> file, which is
found in the Build Directory among the source code
used for the build.
Doing so, can produce unexpected results when the
OpenEmbedded build system regenerates the configuration
file.
</note>
Once you are satisfied with the configuration
changes made using <filename>menuconfig</filename>
and you have saved them, you can directly compare the
resulting <filename>.config</filename> file against an
existing original and gather those changes into a
<link linkend='creating-config-fragments'>configuration fragment file</link>
to be referenced from within the kernel's
<filename>.bbappend</filename> file.</para>
<para>Additionally, if you are working in a BSP layer
and need to modify the BSP's kernel's configuration,
you can use <filename>menuconfig</filename>.
</para></listitem>
<listitem><para>
<emphasis>Rebuild the Kernel Image With Your Changes:</emphasis>
Rebuilding the kernel image applies your changes.
Depending on your target hardware, you can verify your changes
on actual hardware or perhaps QEMU.
</para></listitem>
</orderedlist>
The remainder of this developer's guide covers common tasks typically
used during kernel development, advanced Metadata usage, and Yocto Linux
kernel maintenance concepts.
</para>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->

357
documentation/kernel-dev/kernel-dev-maint-appx.xml
View File

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

991
documentation/kernel-dev/kernel-dev-style.css
View File

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

187
documentation/kernel-dev/kernel-dev.xml
View File

@@ -1,187 +0,0 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
<book id='kernel-dev' lang='en'
xmlns:xi="http://www.w3.org/2003/XInclude"
xmlns="http://docbook.org/ns/docbook"
>
<bookinfo>
<mediaobject>
<imageobject>
<imagedata fileref='figures/kernel-dev-title.png'
format='SVG'
align='left' scalefit='1' width='100%'/>
</imageobject>
</mediaobject>
<title>
Yocto Project Linux Kernel Development Manual
</title>
<authorgroup>
<author>
<affiliation>
<orgname>&ORGNAME;</orgname>
</affiliation>
<email>&ORGEMAIL;</email>
</author>
</authorgroup>
<revhistory>
<revision>
<revnumber>1.4</revnumber>
<date>April 2013</date>
<revremark>The initial document released with the Yocto Project 1.4 Release.</revremark>
</revision>
<revision>
<revnumber>1.5</revnumber>
<date>October 2013</date>
<revremark>Released with the Yocto Project 1.5 Release.</revremark>
</revision>
<revision>
<revnumber>1.6</revnumber>
<date>April 2014</date>
<revremark>Released with the Yocto Project 1.6 Release.</revremark>
</revision>
<revision>
<revnumber>1.7</revnumber>
<date>October 2014</date>
<revremark>Released with the Yocto Project 1.7 Release.</revremark>
</revision>
<revision>
<revnumber>1.8</revnumber>
<date>April 2015</date>
<revremark>Released with the Yocto Project 1.8 Release.</revremark>
</revision>
<revision>
<revnumber>2.0</revnumber>
<date>October 2015</date>
<revremark>Released with the Yocto Project 2.0 Release.</revremark>
</revision>
<revision>
<revnumber>2.1</revnumber>
<date>April 2016</date>
<revremark>Released with the Yocto Project 2.1 Release.</revremark>
</revision>
<revision>
<revnumber>2.2</revnumber>
<date>October 2016</date>
<revremark>Released with the Yocto Project 2.2 Release.</revremark>
</revision>
<revision>
<revnumber>2.3</revnumber>
<date>May 2017</date>
<revremark>Released with the Yocto Project 2.3 Release.</revremark>
</revision>
<revision>
<revnumber>2.4</revnumber>
<date>October 2017</date>
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
<revnumber>2.5</revnumber>
<date>May 2018</date>
<revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
<revision>
<revnumber>2.6</revnumber>
<date>November 2018</date>
<revremark>Released with the Yocto Project 2.6 Release.</revremark>
</revision>
<revision>
<revnumber>2.7</revnumber>
<date>May 2019</date>
<revremark>Released with the Yocto Project 2.7 Release.</revremark>
</revision>
<revision>
<revnumber>3.0</revnumber>
<date>October 2019</date>
<revremark>Released with the Yocto Project 3.0 Release.</revremark>
</revision>
<revision>
<revnumber>3.1</revnumber>
<date>&REL_MONTH_YEAR;</date>
<revremark>Released with the Yocto Project 3.1 Release.</revremark>
</revision>
</revhistory>
<copyright>
<year>&COPYRIGHT_YEAR;</year>
<holder>Linux Foundation</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this document under
the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
</para>
<note><title>Manual Notes</title>
<itemizedlist>
<listitem><para>
This version of the
<emphasis>Yocto Project Linux Kernel Development Manual</emphasis>
is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
for this release, go to the
<ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
and select the manual from that site.
Manuals from the site are more up-to-date than manuals
derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
If you located this manual through a web search, the
version of the manual might not be the one you want
(e.g. the search might have returned a manual much
older than the Yocto Project version with which you
are working).
You can see all Yocto Project major releases by
visiting the
<ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
page.
If you need a version of this manual for a different
Yocto Project release, visit the
<ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
and select the manual set by using the
"ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
pull-down menus.
</para></listitem>
<listitem>
<para>
To report any inaccuracies or problems with this
(or any other Yocto Project) manual, send an email to
the Yocto Project documentation mailing list at
<filename>docs@lists.yoctoproject.org</filename> or
log into the freenode <filename>#yocto</filename> channel.
</para>
</listitem>
</itemizedlist>
</note>
</legalnotice>
</bookinfo>
<xi:include href="kernel-dev-intro.xml"/>
<xi:include href="kernel-dev-common.xml"/>
<xi:include href="kernel-dev-advanced.xml"/>
<xi:include href="kernel-dev-concepts-appx.xml"/>
<xi:include href="kernel-dev-maint-appx.xml"/>
<xi:include href="kernel-dev-faq.xml"/>
<!-- <index id='index'>
<title>Index</title>
</index>
-->
</book>
<!--
vim: expandtab tw=80 ts=4
-->