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

bsp-guide, kernel-dev: Updates to how kernel metadata is found 

Fixes [YOCTO #10946]

There was insufficient information in the combination of the
BSP Guide and the Kernel Development Manual on just how to locate
and use kernel metadata.

 * bsp-guide - Removed the detailed append file example for the
   kernel recipe.  This is moved now to the chapter in the kernel
   manual that describes append files.

 * kernel-dev - Placed the example from the BSP Guide into the
   section that describes kernel append files.  Cleaned up some
   terminology issues throughout chapter 3.  Added information
   about how BitBake picks up kernel metadata when the metadata
   is in a hierarchical directory and not just a simple *.scc
   file.

(From yocto-docs rev: 1048acb7127e77ca9c1f524a208fe25344fcb57c)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2017-03-27 09:17:08 -07:00 committed by Richard Purdie
parent 730617f8d0
commit ed0d609c7c
3 changed files with 635 additions and 542 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

648
documentation/bsp-guide/bsp.xml
View File

@ -352,135 +352,139 @@
</para> </para>
<section id="bsp-filelayout-license"> <section id="bsp-filelayout-license">
<title>License Files</title> <title>License Files</title>
<para> <para>
You can find these files in the BSP Layer at: You can find these files in the BSP Layer at:
<literallayout class='monospaced'> <literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
</literallayout> </literallayout>
</para> </para>
<para> <para>
These optional files satisfy licensing requirements for the BSP. These optional files satisfy licensing requirements for the BSP.
The type or types of files here can vary depending on the licensing requirements. The type or types of files here can vary depending on the licensing requirements.
For example, in the Raspberry Pi BSP all licensing requirements are handled with the For example, in the Raspberry Pi BSP all licensing requirements are handled with the
<filename>COPYING.MIT</filename> file. <filename>COPYING.MIT</filename> file.
</para> </para>
<para> <para>
Licensing files can be MIT, BSD, GPLv*, and so forth. Licensing files can be MIT, BSD, GPLv*, and so forth.
These files are recommended for the BSP but are optional and totally up to the BSP developer. These files are recommended for the BSP but are optional and totally up to the BSP developer.
</para> </para>
</section> </section>
<section id="bsp-filelayout-readme"> <section id="bsp-filelayout-readme">
<title>README File</title> <title>README File</title>
<para>
You can find this file in the BSP Layer at: <para>
<literallayout class='monospaced'> You can find this file in the BSP Layer at:
<literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/README meta-<replaceable>bsp_name</replaceable>/README
</literallayout> </literallayout>
</para> </para>
<para> <para>
This file provides information on how to boot the live images that are optionally This file provides information on how to boot the live images that are optionally
included in the <filename>binary/</filename> directory. included in the <filename>binary/</filename> directory.
The <filename>README</filename> file also provides special information needed for The <filename>README</filename> file also provides special information needed for
building the image. building the image.
</para> </para>
<para> <para>
At a minimum, the <filename>README</filename> file must At a minimum, the <filename>README</filename> file must
contain a list of dependencies, such as the names of contain a list of dependencies, such as the names of
any other layers on which the BSP depends and the name of any other layers on which the BSP depends and the name of
the BSP maintainer with his or her contact information. the BSP maintainer with his or her contact information.
</para> </para>
</section> </section>
<section id="bsp-filelayout-readme-sources"> <section id="bsp-filelayout-readme-sources">
<title>README.sources File</title> <title>README.sources File</title>
<para>
You can find this file in the BSP Layer at:
<literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/README.sources
</literallayout>
</para>
<para> <para>
This file provides information on where to locate the BSP You can find this file in the BSP Layer at:
source files used to build the images (if any) that reside in <literallayout class='monospaced'>
<filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. meta-<replaceable>bsp_name</replaceable>/README.sources
Images in the <filename>binary</filename> would be images </literallayout>
released with the BSP. </para>
The information in the <filename>README.sources</filename>
file also helps you find the <para>
<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> This file provides information on where to locate the BSP
used to generate the images that ship with the BSP. source files used to build the images (if any) that reside in
<note> <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
If the BSP's <filename>binary</filename> directory is Images in the <filename>binary</filename> would be images
missing or the directory has no images, an existing released with the BSP.
<filename>README.sources</filename> file is The information in the <filename>README.sources</filename>
meaningless. file also helps you find the
</note> <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
</para> used to generate the images that ship with the BSP.
<note>
If the BSP's <filename>binary</filename> directory is
missing or the directory has no images, an existing
<filename>README.sources</filename> file is
meaningless.
</note>
</para>
</section> </section>
<section id="bsp-filelayout-binary"> <section id="bsp-filelayout-binary">
<title>Pre-built User Binaries</title> <title>Pre-built User Binaries</title>
<para>
You can find these files in the BSP Layer at: <para>
<literallayout class='monospaced'> You can find these files in the BSP Layer at:
<literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
</literallayout> </literallayout>
</para> </para>
<para> <para>
This optional area contains useful pre-built kernels and This optional area contains useful pre-built kernels and
user-space filesystem images released with the BSP that are user-space filesystem images released with the BSP that are
appropriate to the target system. appropriate to the target system.
This directory typically contains graphical (e.g. Sato) and This directory typically contains graphical (e.g. Sato) and
minimal live images when the BSP tarball has been created and minimal live images when the BSP tarball has been created and
made available in the made available in the
<ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
You can use these kernels and images to get a system running You can use these kernels and images to get a system running
and quickly get started on development tasks. and quickly get started on development tasks.
</para> </para>
<para> <para>
The exact types of binaries present are highly The exact types of binaries present are highly
hardware-dependent. hardware-dependent.
The <filename>README</filename> file should be present in the The <filename>README</filename> file should be present in the
BSP Layer and it will explain how to use the images with the BSP Layer and it will explain how to use the images with the
target hardware. target hardware.
Additionally, the <filename>README.sources</filename> file Additionally, the <filename>README.sources</filename> file
should be present to locate the sources used to build the should be present to locate the sources used to build the
images and provide information on the Metadata. images and provide information on the Metadata.
</para> </para>
</section> </section>
<section id='bsp-filelayout-layer'> <section id='bsp-filelayout-layer'>
<title>Layer Configuration File</title> <title>Layer Configuration File</title>
<para>
You can find this file in the BSP Layer at: <para>
<literallayout class='monospaced'> You can find this file in the BSP Layer at:
<literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/conf/layer.conf meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
</literallayout> </literallayout>
</para> </para>
<para> <para>
The <filename>conf/layer.conf</filename> file identifies the file structure as a The <filename>conf/layer.conf</filename> file identifies the file structure as a
layer, identifies the layer, identifies the
contents of the layer, and contains information about how the build contents of the layer, and contains information about how the build
system should use it. system should use it.
Generally, a standard boilerplate file such as the following works. Generally, a standard boilerplate file such as the following works.
In the following example, you would replace "<replaceable>bsp</replaceable>" and In the following example, you would replace "<replaceable>bsp</replaceable>" and
"<replaceable>_bsp</replaceable>" with the actual name "<replaceable>_bsp</replaceable>" with the actual name
of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template). of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template).
</para> </para>
<para> <para>
<literallayout class='monospaced'> <literallayout class='monospaced'>
# We have a conf and classes directory, add to BBPATH # We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}" BBPATH .= ":${LAYERDIR}"
@ -493,13 +497,13 @@
BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6" BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel" LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
</literallayout> </literallayout>
</para> </para>
<para> <para>
To illustrate the string substitutions, here are the corresponding statements To illustrate the string substitutions, here are the corresponding statements
from the Raspberry Pi <filename>conf/layer.conf</filename> file: from the Raspberry Pi <filename>conf/layer.conf</filename> file:
<literallayout class='monospaced'> <literallayout class='monospaced'>
# We have a conf and classes directory, append to BBPATH # We have a conf and classes directory, append to BBPATH
BBPATH .= ":${LAYERDIR}" BBPATH .= ":${LAYERDIR}"
@ -513,316 +517,196 @@
# Additional license directories. # Additional license directories.
LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
</literallayout> </literallayout>
</para> </para>
<para> <para>
This file simply makes This file simply makes
<ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
aware of the recipes and configuration directories. aware of the recipes and configuration directories.
The file must exist so that the OpenEmbedded build system can recognize the BSP. The file must exist so that the OpenEmbedded build system can recognize the BSP.
</para> </para>
</section> </section>
<section id="bsp-filelayout-machine"> <section id="bsp-filelayout-machine">
<title>Hardware Configuration Options</title> <title>Hardware Configuration Options</title>
<para>
You can find these files in the BSP Layer at: <para>
<literallayout class='monospaced'> You can find these files in the BSP Layer at:
<literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
</literallayout> </literallayout>
</para> </para>
<para> <para>
The machine files bind together all the information contained elsewhere The machine files bind together all the information contained elsewhere
in the BSP into a format that the build system can understand. in the BSP into a format that the build system can understand.
If the BSP supports multiple machines, multiple machine configuration files If the BSP supports multiple machines, multiple machine configuration files
can be present. can be present.
These filenames correspond to the values to which users have set the These filenames correspond to the values to which users have set the
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
</para> </para>
<para> <para>
These files define things such as the kernel package to use These files define things such as the kernel package to use
(<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
of virtual/kernel), the hardware drivers to of virtual/kernel), the hardware drivers to
include in different types of images, any special software components include in different types of images, any special software components
that are needed, any bootloader information, and also any special image that are needed, any bootloader information, and also any special image
format requirements. format requirements.
</para> </para>
<para> <para>
Each BSP Layer requires at least one machine file. Each BSP Layer requires at least one machine file.
However, you can supply more than one file. However, you can supply more than one file.
</para> </para>
<para> <para>
This configuration file could also include a hardware "tuning" This configuration file could also include a hardware "tuning"
file that is commonly used to define the package architecture file that is commonly used to define the package architecture
and specify optimization flags, which are carefully chosen and specify optimization flags, which are carefully chosen
to give best performance on a given processor. to give best performance on a given processor.
</para> </para>
<para> <para>
Tuning files are found in the <filename>meta/conf/machine/include</filename> Tuning files are found in the <filename>meta/conf/machine/include</filename>
directory within the directory within the
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
For example, the <filename>ia32-base.inc</filename> file resides in the For example, the <filename>ia32-base.inc</filename> file resides in the
<filename>meta/conf/machine/include</filename> directory. <filename>meta/conf/machine/include</filename> directory.
</para> </para>
<para> <para>
To use an include file, you simply include them in the To use an include file, you simply include them in the
machine configuration file. machine configuration file.
For example, the Raspberry Pi BSP For example, the Raspberry Pi BSP
<filename>raspberrypi3.conf</filename> contains the <filename>raspberrypi3.conf</filename> contains the
following statement: following statement:
<literallayout class='monospaced'> <literallayout class='monospaced'>
include conf/machine/raspberrypi2.conf include conf/machine/raspberrypi2.conf
</literallayout> </literallayout>
</para> </para>
</section> </section>
<section id='bsp-filelayout-misc-recipes'> <section id='bsp-filelayout-misc-recipes'>
<title>Miscellaneous BSP-Specific Recipe Files</title> <title>Miscellaneous BSP-Specific Recipe Files</title>
<para>
You can find these files in the BSP Layer at:
<literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
</literallayout>
</para>
<para> <para>
This optional directory contains miscellaneous recipe files for You can find these files in the BSP Layer at:
the BSP. <literallayout class='monospaced'>
Most notably would be the formfactor files. meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
For example, in the Raspberry Pi BSP there is the </literallayout>
<filename>formfactor_0.0.bbappend</filename> file, which is an </para>
append file used to augment the recipe that starts the build.
Furthermore, there are machine-specific settings used during <para>
the build that are defined by the This optional directory contains miscellaneous recipe files for
<filename>machconfig</filename> file further down in the the BSP.
directory. Most notably would be the formfactor files.
Here is the <filename>machconfig</filename> For example, in the Raspberry Pi BSP there is the
file for the Raspberry Pi BSP: <filename>formfactor_0.0.bbappend</filename> file, which is an
<literallayout class='monospaced'> append file used to augment the recipe that starts the build.
Furthermore, there are machine-specific settings used during
the build that are defined by the
<filename>machconfig</filename> file further down in the
directory.
Here is the <filename>machconfig</filename>
file for the Raspberry Pi BSP:
<literallayout class='monospaced'>
HAVE_TOUCHSCREEN=0 HAVE_TOUCHSCREEN=0
HAVE_KEYBOARD=1 HAVE_KEYBOARD=1
DISPLAY_CAN_ROTATE=0 DISPLAY_CAN_ROTATE=0
DISPLAY_ORIENTATION=0 DISPLAY_ORIENTATION=0
DISPLAY_DPI=133 DISPLAY_DPI=133
</literallayout> </literallayout>
</para> </para>
<note><para> <note><para>
If a BSP does not have a formfactor entry, defaults are established according to If a BSP does not have a formfactor entry, defaults are established according to
the formfactor configuration file that is installed by the main the formfactor configuration file that is installed by the main
formfactor recipe formfactor recipe
<filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
which is found in the which is found in the
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
</para></note> </para></note>
</section> </section>
<section id='bsp-filelayout-recipes-graphics'> <section id='bsp-filelayout-recipes-graphics'>
<title>Display Support Files</title> <title>Display Support Files</title>
<para>
You can find these files in the BSP Layer at:
<literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
</literallayout>
</para>
<para> <para>
This optional directory contains recipes for the BSP if it has You can find these files in the BSP Layer at:
special requirements for graphics support. <literallayout class='monospaced'>
All files that are needed for the BSP to support a display are meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
kept here. </literallayout>
</para> </para>
<para>
This optional directory contains recipes for the BSP if it has
special requirements for graphics support.
All files that are needed for the BSP to support a display are
kept here.
</para>
</section> </section>
<section id='bsp-filelayout-kernel'> <section id='bsp-filelayout-kernel'>
<title>Linux Kernel Configuration</title> <title>Linux Kernel Configuration</title>
<para>
You can find these files in the BSP Layer at:
<literallayout class='monospaced'>
meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
</literallayout>
</para>
<para> <para>
These files append your specific changes to the main kernel recipe you are using. You can find these files in the BSP Layer at:
</para> <literallayout class='monospaced'>
<para> meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the </literallayout>
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> </para>
at <filename>meta/recipes-kernel/linux</filename>.
You can append your specific changes to the kernel recipe by using a <para>
similarly named append file, which is located in the BSP Layer (e.g. These files append machine-specific changes to the main
the <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). kernel recipe you are using.
</para> </para>
<para>
Suppose you are using the <filename>linux-yocto_4.4.bb</filename> recipe to build <para>
the kernel. For your BSP, you typically want to use an existing Yocto
In other words, you have selected the kernel in your Project kernel recipe found in the
<replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
of statements: at <filename>meta/recipes-kernel/linux</filename>.
<literallayout class='monospaced'> You can append machine-specific changes to the kernel recipe
by using a similarly named append file, which is located in
the BSP Layer for your target device (e.g. the
<filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
</para>
<para>
Suppose you are using the <filename>linux-yocto_4.4.bb</filename>
recipe to build the kernel.
In other words, you have selected the kernel in your
<replaceable>bsp_name</replaceable><filename>.conf</filename>
file by adding
<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
and
<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
statements as follows:
<literallayout class='monospaced'>
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
PREFERRED_VERSION_linux-yocto ?= "4.4%" PREFERRED_VERSION_linux-yocto ?= "4.4%"
</literallayout> </literallayout>
<note> <note>
When the preferred provider is assumed by default, the When the preferred provider is assumed by default, the
<filename>PREFERRED_PROVIDER</filename> statement does not appear in the <filename>PREFERRED_PROVIDER</filename>
<replaceable>bsp_name</replaceable><filename>.conf</filename> file. statement does not appear in the
</note> <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
You would use the <filename>linux-yocto_4.4.bbappend</filename> </note>
file to append specific BSP settings to the kernel, thus You would use the <filename>linux-yocto_4.4.bbappend</filename>
configuring the kernel for your particular BSP. file to append specific BSP settings to the kernel, thus
</para> configuring the kernel for your particular BSP.
<para>
As an example, consider the following append file
used by the BSPs in <filename>meta-yocto-bsp</filename>:
<literallayout class='monospaced'>
meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend
</literallayout>
The following listing shows the file.
Be aware that the actual commit ID strings in this
example listing might be different than the actual strings
in the file from the <filename>meta-yocto-bsp</filename>
layer upstream.
<literallayout class='monospaced'>
KBRANCH_genericx86 = "standard/base"
KBRANCH_genericx86-64 = "standard/base"
KMACHINE_genericx86 ?= "common-pc"
KMACHINE_genericx86-64 ?= "common-pc-64"
KBRANCH_edgerouter = "standard/edgerouter"
KBRANCH_beaglebone = "standard/beaglebone"
KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
SRCREV_machine_genericx86 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
SRCREV_machine_genericx86-64 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
SRCREV_machine_edgerouter ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
SRCREV_machine_beaglebone ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
SRCREV_machine_mpc8315e-rdb ?= "df00877ef9387b38b9601c82db57de2a1b23ce53"
COMPATIBLE_MACHINE_genericx86 = "genericx86"
COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
COMPATIBLE_MACHINE_edgerouter = "edgerouter"
COMPATIBLE_MACHINE_beaglebone = "beaglebone"
COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
LINUX_VERSION_genericx86 = "4.4.3"
LINUX_VERSION_genericx86-64 = "4.4.3"
</literallayout>
This append file contains statements used to support
several BSPs that ship with the Yocto Project.
The file defines machines using the
<ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
variable and uses the
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
variable to ensure the machine name used by the OpenEmbedded
build system maps to the machine name used by the Linux Yocto
kernel.
The file also uses the optional
<ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
variable to ensure the build process uses the
appropriate kernel branch.
</para>
<para>
Although this particular example does not use it, the
<ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
variable could be used to enable features specific to
the kernel.
The append file points to specific commits in the
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
Git repository and the <filename>meta</filename> Git repository
branches to identify the exact kernel needed to build the
BSP.
</para>
<para>
One thing missing in this particular BSP, which you will
typically need when developing a BSP, is the kernel configuration
file (<filename>.config</filename>) for your BSP.
When developing a BSP, you probably have a kernel configuration
file or a set of kernel configuration files that, when taken
together, define the kernel configuration for your BSP.
You can accomplish this definition by putting the configurations
in a file or a set of files inside a directory located at the
same level as your kernel's append file and having the same
name as the kernel's main recipe file.
With all these conditions met, simply reference those files in the
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
statement in the append file.
</para>
<para>
For example, suppose you had some configuration options
in a file called <filename>network_configs.cfg</filename>.
You can place that file inside a directory named
<filename>linux-yocto</filename> and then add
a <filename>SRC_URI</filename> statement such as the
following to the append file.
When the OpenEmbedded build system builds the kernel, the
configuration options are picked up and applied.
<literallayout class='monospaced'>
SRC_URI += "file://network_configs.cfg"
</literallayout>
</para>
<para>
To group related configurations into multiple files, you
perform a similar procedure.
Here is an example that groups separate configurations
specifically for Ethernet and graphics into their own
files and adds the configurations by using a
<filename>SRC_URI</filename> statement like the following
in your append file:
<literallayout class='monospaced'>
SRC_URI += "file://myconfig.cfg \
file://eth.cfg \
file://gfx.cfg"
</literallayout>
</para>
<para>
Another variable you can use in your kernel recipe append
file is the
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
variable.
When you use this statement, you are extending the locations
used by the OpenEmbedded system to look for files and
patches as the recipe is processed.
</para>
<note>
<para>
Other methods exist to accomplish grouping and defining configuration options.
For example, if you are working with a local clone of the kernel repository,
you could checkout the kernel's <filename>meta</filename> branch, make your changes,
and then push the changes to the local bare clone of the kernel.
The result is that you directly add configuration options to the
<filename>meta</filename> branch for your BSP.
The configuration options will likely end up in that location anyway if the BSP gets
added to the Yocto Project.
</para> </para>
<para> <para>
In general, however, the Yocto Project maintainers take care of moving the You can find more information on what your append file
<filename>SRC_URI</filename>-specified should contain in the
configuration options to the kernel's <filename>meta</filename> branch. "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
Not only is it easier for BSP developers to not have to worry about putting those section in the Yocto Project Linux Kernel Development
configurations in the branch, but having the maintainers do it allows them to apply Manual.
'global' knowledge about the kinds of common configuration options multiple BSPs in
the tree are typically using.
This allows for promotion of common configurations into common features.
</para> </para>
</note>
</section> </section>
</section> </section>

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

@ -524,170 +524,219 @@
<title>BSP Descriptions</title> <title>BSP Descriptions</title>
<para> <para>
BSP descriptions combine kernel types with hardware-specific BSP descriptions (i.e. <filename>*.scc</filename> files)
features. combine kernel types with hardware-specific features.
The hardware-specific portion is typically defined The hardware-specific Metadata is typically defined
independently, and then aggregated with each supported kernel independently in the BSP layer, and then aggregated with each
type. supported kernel type.
Consider this simple BSP description that supports the
<replaceable>mybsp</replaceable> machine:
<literallayout class='monospaced'>
<replaceable>mybsp</replaceable>.scc:
define KMACHINE <replaceable>mybsp</replaceable>
define KTYPE standard
define KARCH i386
kconf <replaceable>mybsp</replaceable>.cfg
</literallayout>
Every BSP description should define the
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
variables.
These variables allow the OpenEmbedded build system to identify
the description as meeting the criteria set by the recipe being
built.
This simple example supports the "mybsp" machine for the "standard"
kernel and the "i386" architecture.
</para>
<para>
Be aware that a hard link between the
<filename>KTYPE</filename> variable and a kernel type
description file does not exist.
Thus, if you do not have kernel types defined in your kernel
Metadata, you only need to ensure that the kernel recipe's
<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
variable and the <filename>KTYPE</filename> variable in the
BSP description file match.
<note> <note>
Future versions of the tooling make the specification of For BSPs supported by the Yocto Project, the BSP description
<filename>KTYPE</filename> in the BSP optional. files are located in the <filename>bsp</filename> directory
of the <filename>yocto-kernel-cache</filename> repository
organized under the "Yocto Linux Kernel" heading in the
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
</note> </note>
</para> </para>
<para> <para>
If you did want to separate your kernel policy from your This section provides a BSP description structural overview along
hardware configuration, you could do so by specifying a kernel with aggregation concepts as well as a detailed example using
type, such as "standard" and including that description file a BSP supported by the Yocto Project (i.e. Minnow Board).
in the BSP description file.
See the "<link linkend='kernel-types'>Kernel Types</link>" section
for more information.
</para> </para>
<para> <section id='bsp-description-file-overview'>
You might also have multiple hardware configurations that you <title>Overview</title>
aggregate into a single hardware description file that you
could include in the BSP description file, rather than referencing
a single <filename>.cfg</filename> file.
Consider the following:
<literallayout class='monospaced'>
<replaceable>mybsp</replaceable>.scc:
define KMACHINE mybsp
define KTYPE standard
define KARCH i386
include standard.scc <para>
include <replaceable>mybsp</replaceable>-hw.scc For simplicity, consider the following top-level BSP
</literallayout> description file.
</para> Top-level BSP descriptions files employ both a structure
and naming convention for consistency.
The naming convention for the file is as follows:
<literallayout class='monospaced'>
<replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
</literallayout>
Here are some example top-level BSP filenames for the
Minnow Board BSP, which is supported by the Yocto Project:
<literallayout class='monospaced'>
minnow-standard.scc
minnow-preempt-rt.scc
minnow-tiny.scc
</literallayout>
Each file uses the BSP name followed by the kernel type.
</para>
<para> <para>
In the above example, <filename>standard.scc</filename> is simple BSP description file whose name has the
aggregates all the configuration fragments, patches, and form
features that make up your standard kernel policy whereas <replaceable>mybsp</replaceable><filename>-standard</filename>
<replaceable>mybsp</replaceable><filename>-hw.scc</filename> and supports the <replaceable>mybsp</replaceable> machine using
aggregates all those necessary a standard kernel:
to support the hardware available on the <literallayout class='monospaced'>
<replaceable>mybsp</replaceable> machine. define KMACHINE <replaceable>mybsp</replaceable>
For information on how to break a complete define KTYPE standard
<filename>.config</filename> file into the various define KARCH i386
configuration fragments, see the
"<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
section.
</para>
<para> include ktypes/standard
Many real-world examples are more complex.
Like any other <filename>.scc</filename> file, BSP include <replaceable>mybsp</replaceable>.scc
descriptions can aggregate features.
Consider the Minnow BSP definition from the kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
<filename>linux-yocto-3.19</filename> </literallayout>
Git repository: Every top-level BSP description file should define the
<literallayout class='monospaced'> <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
variables.
These variables allow the OpenEmbedded build system to identify
the description as meeting the criteria set by the recipe being
built.
This simple example supports the "mybsp" machine for the "standard"
kernel and the "i386" architecture.
</para>
<para>
Be aware that a hard link between the
<filename>KTYPE</filename> variable and a kernel type description
file does not exist.
Thus, if you do not have kernel types defined in your kernel
Metadata, you only need to ensure that the kernel recipe's
<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
variable and the <filename>KTYPE</filename> variable in the
BSP description file match.
<note>
Future versions of the tooling make the specification of
<filename>KTYPE</filename> in the BSP optional.
</note>
</para>
<para>
To separate your kernel policy from your hardware configuration,
you include a kernel type (<filename>ktype</filename>), such as
"standard".
In the previous example, this is done using the following:
<literallayout class='monospaced'>
include ktypes/standard
</literallayout>
In the previous example, <filename>ktypes/standard.scc</filename>
aggregates all the configuration fragments, patches, and
features that make up your standard kernel policy.
See the "<link linkend='kernel-types'>Kernel Types</link>" section
for more information.
</para>
<para>
To aggregate common configurations and features specific to the
kernel for <replaceable>mybsp</replaceable>, use the following:
<literallayout class='monospaced'>
include <replaceable>mybsp</replaceable>.scc
</literallayout>
For information on how to break a complete
<filename>.config</filename> file into the various
configuration fragments, see the
"<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
section.
</para>
<para>
Finally, if you have any configurations specific to the
hardware that are not in a <filename>*.scc</filename> file,
you can include them as follows:
<literallayout class='monospaced'>
kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
</literallayout>
</para>
</section>
<section id='bsp-description-file-example-minnow'>
<title>Example</title>
<para>
Many real-world examples are more complex.
Like any other <filename>.scc</filename> file, BSP
descriptions can aggregate features.
Consider the Minnow BSP definition from the
<filename>linux-yocto-4.4</filename> in the
Yocto Project
<ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
(i.e.
<filename>yocto-kernel-cache/bsp/minnow</filename>):
<literallayout class='monospaced'>
minnow.scc: minnow.scc:
include cfg/x86.scc include cfg/x86.scc
include features/eg20t/eg20t.scc include features/eg20t/eg20t.scc
include cfg/dmaengine.scc include cfg/dmaengine.scc
include features/power/intel.scc include features/power/intel.scc
include cfg/efi.scc include cfg/efi.scc
include features/usb/ehci-hcd.scc include features/usb/ehci-hcd.scc
include features/usb/ohci-hcd.scc include features/usb/ohci-hcd.scc
include features/usb/usb-gadgets.scc include features/usb/usb-gadgets.scc
include features/usb/touchscreen-composite.scc include features/usb/touchscreen-composite.scc
include cfg/timer/hpet.scc include cfg/timer/hpet.scc
include cfg/timer/rtc.scc include features/leds/leds.scc
include features/leds/leds.scc include features/spi/spidev.scc
include features/spi/spidev.scc include features/i2c/i2cdev.scc
include features/i2c/i2cdev.scc include features/mei/mei-txe.scc
# Earlyprintk and port debug requires 8250 # Earlyprintk and port debug requires 8250
kconf hardware cfg/8250.cfg kconf hardware cfg/8250.cfg
kconf hardware minnow.cfg kconf hardware minnow.cfg
kconf hardware minnow-dev.cfg kconf hardware minnow-dev.cfg
</literallayout> </literallayout>
</para> </para>
<para> <para>
The <filename>minnow.scc</filename> description file includes The <filename>minnow.scc</filename> description file includes
a hardware configuration fragment a hardware configuration fragment
(<filename>minnow.cfg</filename>) specific to the Minnow (<filename>minnow.cfg</filename>) specific to the Minnow
BSP as well as several more general configuration BSP as well as several more general configuration
fragments and features enabling hardware found on the fragments and features enabling hardware found on the
machine. machine.
This description file is then included in each of the three This <filename>minnow.scc</filename> description file is then
"minnow" description files for the supported kernel types included in each of the three
(i.e. "standard", "preempt-rt", and "tiny"). "minnow" description files for the supported kernel types
Consider the "minnow" description for the "standard" kernel (i.e. "standard", "preempt-rt", and "tiny").
type: Consider the "minnow" description for the "standard" kernel
<literallayout class='monospaced'> type:
<literallayout class='monospaced'>
minnow-standard.scc: minnow-standard.scc:
define KMACHINE minnow define KMACHINE minnow
define KTYPE standard define KTYPE standard
define KARCH i386 define KARCH i386
include ktypes/standard include ktypes/standard
include minnow.scc include minnow.scc
# Extra minnow configs above the minimal defined in minnow.scc # Extra minnow configs above the minimal defined in minnow.scc
include cfg/efi-ext.scc include cfg/efi-ext.scc
include features/media/media-all.scc include features/media/media-all.scc
include features/sound/snd_hda_intel.scc include features/sound/snd_hda_intel.scc
# The following should really be in standard.scc # The following should really be in standard.scc
# USB live-image support # USB live-image support
include cfg/usb-mass-storage.scc include cfg/usb-mass-storage.scc
include cfg/boot-live.scc include cfg/boot-live.scc
# Basic profiling # Basic profiling
include features/latencytop/latencytop.scc include features/latencytop/latencytop.scc
include features/profiling/profiling.scc include features/profiling/profiling.scc
# Requested drivers that don't have an existing scc # Requested drivers that don't have an existing scc
kconf hardware minnow-drivers-extra.cfg kconf hardware minnow-drivers-extra.cfg
</literallayout> </literallayout>
The <filename>include</filename> command midway through the file The <filename>include</filename> command midway through the file
includes the <filename>minnow.scc</filename> description that includes the <filename>minnow.scc</filename> description that
defines all hardware enablements for the BSP that is common to all defines all enabled hardware for the BSP that is common to
kernel types. all kernel types.
Using this command significantly reduces duplication. Using this command significantly reduces duplication.
</para> </para>
<para> <para>
Now consider the "minnow" description for the "tiny" kernel type: Now consider the "minnow" description for the "tiny" kernel
<literallayout class='monospaced'> type:
<literallayout class='monospaced'>
minnow-tiny.scc: minnow-tiny.scc:
define KMACHINE minnow define KMACHINE minnow
define KTYPE tiny define KTYPE tiny
@ -696,22 +745,24 @@
include ktypes/tiny include ktypes/tiny
include minnow.scc include minnow.scc
</literallayout> </literallayout>
As you might expect, the "tiny" description includes quite a As you might expect, the "tiny" description includes quite a
bit less. bit less.
In fact, it includes only the minimal policy defined by the In fact, it includes only the minimal policy defined by the
"tiny" kernel type and the hardware-specific configuration required "tiny" kernel type and the hardware-specific configuration
for booting the machine along with the most basic functionality of required for booting the machine along with the most basic
the system as defined in the base "minnow" description file. functionality of the system as defined in the base "minnow"
</para> description file.
</para>
<para> <para>
Notice again the three critical variables: Notice again the three critical variables:
<filename>KMACHINE</filename>, <filename>KTYPE</filename>, <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
and <filename>KARCH</filename>. and <filename>KARCH</filename>.
Of these variables, only the <filename>KTYPE</filename> has changed. Of these variables, only the <filename>KTYPE</filename> has changed.
It is now set to "tiny". It is now set to "tiny".
</para> </para>
</section>
</section> </section>
</section> </section>
@ -795,6 +846,18 @@
value when changing the content of files not explicitly listed value when changing the content of files not explicitly listed
in the <filename>SRC_URI</filename>. in the <filename>SRC_URI</filename>.
</para> </para>
<para>
If the kernel Metadata is in a layer, you cannot simply list the
<filename>*.scc</filename> in the <filename>SRC_URI</filename>
statement.
You need to use the following form from your kernel append file:
<literallayout class='monospaced'>
SRC_URI_append_<replaceable>myplatform</replaceable> = " \
file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \
"
</literallayout>
</para>
</section> </section>
<section id='metadata-outside-the-recipe-space'> <section id='metadata-outside-the-recipe-space'>
@ -817,7 +880,8 @@
<filename>${KMETA}</filename>, in this context, is simply used to <filename>${KMETA}</filename>, in this context, is simply used to
name the directory into which the Git fetcher places the Metadata. name the directory into which the Git fetcher places the Metadata.
This behavior is no different than any multi-repository This behavior is no different than any multi-repository
<filename>SRC_URI</filename> statement used in a recipe. <filename>SRC_URI</filename> statement used in a recipe (e.g.
see the previous section).
</para> </para>
<para> <para>

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

@ -84,11 +84,11 @@
You also name it accordingly based on the linux-yocto recipe You also name it accordingly based on the linux-yocto recipe
you are using. you are using.
For example, if you are modifying the For example, if you are modifying the
<filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename> <filename>meta/recipes-kernel/linux/linux-yocto_4.4.bb</filename>
recipe, the append file will typically be located as follows recipe, the append file will typically be located as follows
within your custom layer: within your custom layer:
<literallayout class='monospaced'> <literallayout class='monospaced'>
<replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.4.bbappend
</literallayout> </literallayout>
The append file should initially extend the The append file should initially extend the
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
@ -114,6 +114,151 @@
<ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
</note> </note>
</para> </para>
<para>
As an example, consider the following append file
used by the BSPs in <filename>meta-yocto-bsp</filename>:
<literallayout class='monospaced'>
meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend
</literallayout>
The following listing shows the file.
Be aware that the actual commit ID strings in this
example listing might be different than the actual strings
in the file from the <filename>meta-yocto-bsp</filename>
layer upstream.
<literallayout class='monospaced'>
KBRANCH_genericx86 = "standard/base"
KBRANCH_genericx86-64 = "standard/base"
KMACHINE_genericx86 ?= "common-pc"
KMACHINE_genericx86-64 ?= "common-pc-64"
KBRANCH_edgerouter = "standard/edgerouter"
KBRANCH_beaglebone = "standard/beaglebone"
KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
SRCREV_machine_genericx86 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
SRCREV_machine_genericx86-64 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
SRCREV_machine_edgerouter ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
SRCREV_machine_beaglebone ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
SRCREV_machine_mpc8315e-rdb ?= "06c0dbdcba374ca7f92a53d69292d6bb7bc9b0f3"
COMPATIBLE_MACHINE_genericx86 = "genericx86"
COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
COMPATIBLE_MACHINE_edgerouter = "edgerouter"
COMPATIBLE_MACHINE_beaglebone = "beaglebone"
COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
LINUX_VERSION_genericx86 = "4.4.41"
LINUX_VERSION_genericx86-64 = "4.4.41"
LINUX_VERSION_edgerouter = "4.4.53"
LINUX_VERSION_beaglebone = "4.4.53"
LINUX_VERSION_mpc8315e-rdb = "4.4.53"
</literallayout>
This append file contains statements used to support
several BSPs that ship with the Yocto Project.
The file defines machines using the
<ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
variable and uses the
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
variable to ensure the machine name used by the OpenEmbedded
build system maps to the machine name used by the Linux Yocto
kernel.
The file also uses the optional
<ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
variable to ensure the build process uses the
appropriate kernel branch.
</para>
<para>
Although this particular example does not use it, the
<ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
variable could be used to enable features specific to
the kernel.
The append file points to specific commits in the
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
Git repository and the <filename>meta</filename> Git repository
branches to identify the exact kernel needed to build the
BSP.
</para>
<para>
One thing missing in this particular BSP, which you will
typically need when developing a BSP, is the kernel configuration
file (<filename>.config</filename>) for your BSP.
When developing a BSP, you probably have a kernel configuration
file or a set of kernel configuration files that, when taken
together, define the kernel configuration for your BSP.
You can accomplish this definition by putting the configurations
in a file or a set of files inside a directory located at the
same level as your kernel's append file and having the same
name as the kernel's main recipe file.
With all these conditions met, simply reference those files in the
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
statement in the append file.
</para>
<para>
For example, suppose you had some configuration options
in a file called <filename>network_configs.cfg</filename>.
You can place that file inside a directory named
<filename>linux-yocto</filename> and then add
a <filename>SRC_URI</filename> statement such as the
following to the append file.
When the OpenEmbedded build system builds the kernel, the
configuration options are picked up and applied.
<literallayout class='monospaced'>
SRC_URI += "file://network_configs.cfg"
</literallayout>
</para>
<para>
To group related configurations into multiple files, you
perform a similar procedure.
Here is an example that groups separate configurations
specifically for Ethernet and graphics into their own
files and adds the configurations by using a
<filename>SRC_URI</filename> statement like the following
in your append file:
<literallayout class='monospaced'>
SRC_URI += "file://myconfig.cfg \
file://eth.cfg \
file://gfx.cfg"
</literallayout>
</para>
<para>
Another variable you can use in your kernel recipe append
file is the
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
variable.
When you use this statement, you are extending the locations
used by the OpenEmbedded system to look for files and
patches as the recipe is processed.
</para>
<note>
<para>
Other methods exist to accomplish grouping and defining configuration options.
For example, if you are working with a local clone of the kernel repository,
you could checkout the kernel's <filename>meta</filename> branch, make your changes,
and then push the changes to the local bare clone of the kernel.
The result is that you directly add configuration options to the
<filename>meta</filename> branch for your BSP.
The configuration options will likely end up in that location anyway if the BSP gets
added to the Yocto Project.
</para>
<para>
In general, however, the Yocto Project maintainers take care of moving the
<filename>SRC_URI</filename>-specified
configuration options to the kernel's <filename>meta</filename> branch.
Not only is it easier for BSP developers to not have to worry about putting those
configurations in the branch, but having the maintainers do it allows them to apply
'global' knowledge about the kinds of common configuration options multiple BSPs in
the tree are typically using.
This allows for promotion of common configurations into common features.
</para>
</note>
</section> </section>
<section id='applying-patches'> <section id='applying-patches'>