Yocto 2.3
Move OpenBMC to Yocto 2.3(pyro).
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I50744030e771f4850afc2a93a10d3507e76d36bc
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Resolves: openbmc/openbmc#2461
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml
index 9e15f17..a5ccfdc 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -83,13 +83,14 @@
The linux-yocto style recipes can optionally define the following
variables:
<literallayout class='monospaced'>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink>
+ KERNEL_FEATURES
+ LINUX_KERNEL_TYPE
</literallayout>
</para>
<para>
- <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
+ defines the kernel type to be
used in assembling the configuration.
If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
it defaults to "standard".
@@ -134,7 +135,9 @@
</para>
<para>
- You can use the <filename>KERNEL_FEATURES</filename> variable
+ You can use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
+ variable
to include features (configuration fragments, patches, or both) that
are not already included by the <filename>KMACHINE</filename> and
<filename>LINUX_KERNEL_TYPE</filename> variable combination.
@@ -167,175 +170,6 @@
</para>
</section>
-<section id='kernel-metadata-location'>
- <title>Kernel Metadata Location</title>
-
- <para>
- Kernel Metadata always exists outside of the kernel tree either
- defined in a kernel recipe (recipe-space) or outside of the recipe.
- Where you choose to define the Metadata depends on what you want
- to do and how you intend to work.
- Regardless of where you define the kernel Metadata, the syntax used
- applies equally.
- </para>
-
- <para>
- If you are unfamiliar with the Linux kernel and only wish
- to apply a configuration and possibly a couple of patches provided to
- you by others, the recipe-space method is recommended.
- This method is also a good approach if you are working with Linux kernel
- sources you do not control or if you just do not want to maintain a
- Linux kernel Git repository on your own.
- For partial information on how you can define kernel Metadata in
- the recipe-space, see the
- "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
- section.
- </para>
-
- <para>
- Conversely, if you are actively developing a kernel and are already
- maintaining a Linux kernel Git repository of your own, you might find
- it more convenient to work with kernel Metadata kept outside the
- recipe-space.
- Working with Metadata in this area can make iterative development of
- the Linux kernel more efficient outside of the BitBake environment.
- </para>
-
- <section id='recipe-space-metadata'>
- <title>Recipe-Space Metadata</title>
-
- <para>
- When stored in recipe-space, the kernel Metadata files reside in a
- directory hierarchy below
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
- For a linux-yocto recipe or for a Linux kernel recipe derived
- by copying and modifying
- <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
- to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
- is typically set to
- <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>.
- See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
- section for more information.
- </para>
-
- <para>
- Here is an example that shows a trivial tree of kernel Metadata
- stored in recipe-space within a BSP layer:
- <literallayout class='monospaced'>
- meta-<replaceable>my_bsp_layer</replaceable>/
- `-- recipes-kernel
- `-- linux
- `-- linux-yocto
- |-- bsp-standard.scc
- |-- bsp.cfg
- `-- standard.cfg
- </literallayout>
- </para>
-
- <para>
- When the Metadata is stored in recipe-space, you must take
- steps to ensure BitBake has the necessary information to decide
- what files to fetch and when they need to be fetched again.
- It is only necessary to specify the <filename>.scc</filename>
- files on the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
- BitBake parses them and fetches any files referenced in the
- <filename>.scc</filename> files by the <filename>include</filename>,
- <filename>patch</filename>, or <filename>kconf</filename> commands.
- Because of this, it is necessary to bump the recipe
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
- value when changing the content of files not explicitly listed
- in the <filename>SRC_URI</filename>.
- </para>
- </section>
-
- <section id='metadata-outside-the-recipe-space'>
- <title>Metadata Outside the Recipe-Space</title>
-
- <para>
- When stored outside of the recipe-space, the kernel Metadata
- files reside in a separate repository.
- The OpenEmbedded build system adds the Metadata to the build as
- a "ktype=meta" repository through the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- variable.
- As an example, consider the following <filename>SRC_URI</filename>
- statement from the <filename>linux-yocto_4.4.bb</filename>
- kernel recipe:
- <literallayout class='monospaced'>
- SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \
- git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}"
- </literallayout>
- <filename>${KMETA}</filename>, in this context, is simply used to
- name the directory into which the Git fetcher places the Metadata.
- This behavior is no different than any multi-repository
- <filename>SRC_URI</filename> statement used in a recipe.
- </para>
-
- <para>
- You can keep kernel Metadata in a "kernel-cache", which is a
- directory containing configuration fragments.
- As with any Metadata kept outside the recipe-space, you simply
- need to use the <filename>SRC_URI</filename> statement with the
- "type=kmeta" attribute.
- Doing so makes the kernel Metadata available during the
- configuration phase.
- </para>
-
-<!--
-
-
- <para>
- Following is an example that shows how a trivial tree of Metadata
- is stored in a custom Linux kernel Git repository:
- <literallayout class='monospaced'>
- meta/
- `‐‐ cfg
- `‐‐ kernel-cache
- |‐‐ bsp-standard.scc
- |‐‐ bsp.cfg
- `‐‐ standard.cfg
- </literallayout>
- </para>
-
- <para>
- To use a branch different from where the sources reside,
- specify the branch in the <filename>KMETA</filename> variable
- in your Linux kernel recipe.
- Here is an example:
- <literallayout class='monospaced'>
- KMETA = "meta"
- </literallayout>
- To use the same branch as the sources, set
- <filename>KMETA</filename> to an empty string:
- <literallayout class='monospaced'>
- KMETA = ""
- </literallayout>
- If you are working with your own sources and want to create an
- orphan <filename>meta</filename> branch, use these commands
- from within your Linux kernel Git repository:
- <literallayout class='monospaced'>
- $ git checkout ‐‐orphan meta
- $ git rm -rf .
- $ git commit ‐‐allow-empty -m "Create orphan meta branch"
- </literallayout>
- </para>
--->
-
- <para>
- If you modify the Metadata, you must not forget to update the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
- statements in the kernel's recipe.
- In particular, you need to update the
- <filename>SRCREV_meta</filename> variable to match the commit in
- the <filename>KMETA</filename> branch you wish to use.
- Changing the data in these branches and not updating the
- <filename>SRCREV</filename> statements to match will cause the
- build to fetch an older commit.
- </para>
- </section>
-</section>
-
<section id='kernel-metadata-syntax'>
<title>Kernel Metadata Syntax</title>
@@ -690,170 +524,219 @@
<title>BSP Descriptions</title>
<para>
- BSP descriptions combine kernel types with hardware-specific
- features.
- The hardware-specific portion is typically defined
- independently, and then aggregated with each 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.
+ BSP descriptions (i.e. <filename>*.scc</filename> files)
+ combine kernel types with hardware-specific features.
+ The hardware-specific Metadata is typically defined
+ independently in the BSP layer, and then aggregated with each
+ supported kernel type.
<note>
- Future versions of the tooling make the specification of
- <filename>KTYPE</filename> in the BSP optional.
+ For BSPs supported by the Yocto Project, the BSP description
+ 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>
</para>
<para>
- If you did want to separate your kernel policy from your
- hardware configuration, you could do so by specifying a kernel
- type, such as "standard" and including that description file
- in the BSP description file.
- See the "<link linkend='kernel-types'>Kernel Types</link>" section
- for more information.
+ This section provides a BSP description structural overview along
+ with aggregation concepts as well as a detailed example using
+ a BSP supported by the Yocto Project (i.e. Minnow Board).
</para>
- <para>
- You might also have multiple hardware configurations that you
- 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
+ <section id='bsp-description-file-overview'>
+ <title>Overview</title>
- include standard.scc
- include <replaceable>mybsp</replaceable>-hw.scc
- </literallayout>
- </para>
+ <para>
+ For simplicity, consider the following top-level BSP
+ description file.
+ 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>
- In the above example, <filename>standard.scc</filename>
- aggregates all the configuration fragments, patches, and
- features that make up your standard kernel policy whereas
- <replaceable>mybsp</replaceable><filename>-hw.scc</filename>
- aggregates all those necessary
- to support the hardware available on the
- <replaceable>mybsp</replaceable> machine.
- 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>
+ is simple BSP description file whose name has the
+ form
+ <replaceable>mybsp</replaceable><filename>-standard</filename>
+ and supports the <replaceable>mybsp</replaceable> machine using
+ a standard kernel:
+ <literallayout class='monospaced'>
+ define KMACHINE <replaceable>mybsp</replaceable>
+ define KTYPE standard
+ define KARCH i386
- <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-3.19</filename>
- Git repository:
- <literallayout class='monospaced'>
+ include ktypes/standard
+
+ include <replaceable>mybsp</replaceable>.scc
+
+ kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
+ </literallayout>
+ Every top-level BSP description file 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>
+ 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:
- include cfg/x86.scc
- include features/eg20t/eg20t.scc
- include cfg/dmaengine.scc
- include features/power/intel.scc
- include cfg/efi.scc
- include features/usb/ehci-hcd.scc
- include features/usb/ohci-hcd.scc
- include features/usb/usb-gadgets.scc
- include features/usb/touchscreen-composite.scc
- include cfg/timer/hpet.scc
- include cfg/timer/rtc.scc
- include features/leds/leds.scc
- include features/spi/spidev.scc
- include features/i2c/i2cdev.scc
+ include cfg/x86.scc
+ include features/eg20t/eg20t.scc
+ include cfg/dmaengine.scc
+ include features/power/intel.scc
+ include cfg/efi.scc
+ include features/usb/ehci-hcd.scc
+ include features/usb/ohci-hcd.scc
+ include features/usb/usb-gadgets.scc
+ include features/usb/touchscreen-composite.scc
+ include cfg/timer/hpet.scc
+ include features/leds/leds.scc
+ include features/spi/spidev.scc
+ include features/i2c/i2cdev.scc
+ include features/mei/mei-txe.scc
- # Earlyprintk and port debug requires 8250
- kconf hardware cfg/8250.cfg
+ # Earlyprintk and port debug requires 8250
+ kconf hardware cfg/8250.cfg
- kconf hardware minnow.cfg
- kconf hardware minnow-dev.cfg
- </literallayout>
- </para>
+ kconf hardware minnow.cfg
+ kconf hardware minnow-dev.cfg
+ </literallayout>
+ </para>
- <para>
- The <filename>minnow.scc</filename> description file includes
- a hardware configuration fragment
- (<filename>minnow.cfg</filename>) specific to the Minnow
- BSP as well as several more general configuration
- fragments and features enabling hardware found on the
- machine.
- This description file is then included in each of the three
- "minnow" description files for the supported kernel types
- (i.e. "standard", "preempt-rt", and "tiny").
- Consider the "minnow" description for the "standard" kernel
- type:
- <literallayout class='monospaced'>
+ <para>
+ The <filename>minnow.scc</filename> description file includes
+ a hardware configuration fragment
+ (<filename>minnow.cfg</filename>) specific to the Minnow
+ BSP as well as several more general configuration
+ fragments and features enabling hardware found on the
+ machine.
+ This <filename>minnow.scc</filename> description file is then
+ included in each of the three
+ "minnow" description files for the supported kernel types
+ (i.e. "standard", "preempt-rt", and "tiny").
+ Consider the "minnow" description for the "standard" kernel
+ type:
+ <literallayout class='monospaced'>
minnow-standard.scc:
- define KMACHINE minnow
- define KTYPE standard
- define KARCH i386
+ define KMACHINE minnow
+ define KTYPE standard
+ 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
- include cfg/efi-ext.scc
- include features/media/media-all.scc
- include features/sound/snd_hda_intel.scc
+ # Extra minnow configs above the minimal defined in minnow.scc
+ include cfg/efi-ext.scc
+ include features/media/media-all.scc
+ include features/sound/snd_hda_intel.scc
- # The following should really be in standard.scc
- # USB live-image support
- include cfg/usb-mass-storage.scc
- include cfg/boot-live.scc
+ # The following should really be in standard.scc
+ # USB live-image support
+ include cfg/usb-mass-storage.scc
+ include cfg/boot-live.scc
- # Basic profiling
- include features/latencytop/latencytop.scc
- include features/profiling/profiling.scc
+ # Basic profiling
+ include features/latencytop/latencytop.scc
+ include features/profiling/profiling.scc
- # Requested drivers that don't have an existing scc
- kconf hardware minnow-drivers-extra.cfg
- </literallayout>
- The <filename>include</filename> command midway through the file
- includes the <filename>minnow.scc</filename> description that
- defines all hardware enablements for the BSP that is common to all
- kernel types.
- Using this command significantly reduces duplication.
- </para>
+ # Requested drivers that don't have an existing scc
+ kconf hardware minnow-drivers-extra.cfg
+ </literallayout>
+ The <filename>include</filename> command midway through the file
+ includes the <filename>minnow.scc</filename> description that
+ defines all enabled hardware for the BSP that is common to
+ all kernel types.
+ Using this command significantly reduces duplication.
+ </para>
- <para>
- Now consider the "minnow" description for the "tiny" kernel type:
- <literallayout class='monospaced'>
+ <para>
+ Now consider the "minnow" description for the "tiny" kernel
+ type:
+ <literallayout class='monospaced'>
minnow-tiny.scc:
define KMACHINE minnow
define KTYPE tiny
@@ -862,21 +745,205 @@
include ktypes/tiny
include minnow.scc
- </literallayout>
- As you might expect, the "tiny" description includes quite a
- bit less.
- In fact, it includes only the minimal policy defined by the
- "tiny" kernel type and the hardware-specific configuration required
- for booting the machine along with the most basic functionality of
- the system as defined in the base "minnow" description file.
+ </literallayout>
+ As you might expect, the "tiny" description includes quite a
+ bit less.
+ In fact, it includes only the minimal policy defined by the
+ "tiny" kernel type and the hardware-specific configuration
+ required for booting the machine along with the most basic
+ functionality of the system as defined in the base "minnow"
+ description file.
+ </para>
+
+ <para>
+ Notice again the three critical variables:
+ <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
+ and <filename>KARCH</filename>.
+ Of these variables, only the <filename>KTYPE</filename> has changed.
+ It is now set to "tiny".
+ </para>
+ </section>
+ </section>
+</section>
+
+<section id='kernel-metadata-location'>
+ <title>Kernel Metadata Location</title>
+
+ <para>
+ Kernel Metadata always exists outside of the kernel tree either
+ defined in a kernel recipe (recipe-space) or outside of the recipe.
+ Where you choose to define the Metadata depends on what you want
+ to do and how you intend to work.
+ Regardless of where you define the kernel Metadata, the syntax used
+ applies equally.
+ </para>
+
+ <para>
+ If you are unfamiliar with the Linux kernel and only wish
+ to apply a configuration and possibly a couple of patches provided to
+ you by others, the recipe-space method is recommended.
+ This method is also a good approach if you are working with Linux kernel
+ sources you do not control or if you just do not want to maintain a
+ Linux kernel Git repository on your own.
+ For partial information on how you can define kernel Metadata in
+ the recipe-space, see the
+ "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
+ section.
+ </para>
+
+ <para>
+ Conversely, if you are actively developing a kernel and are already
+ maintaining a Linux kernel Git repository of your own, you might find
+ it more convenient to work with kernel Metadata kept outside the
+ recipe-space.
+ Working with Metadata in this area can make iterative development of
+ the Linux kernel more efficient outside of the BitBake environment.
+ </para>
+
+ <section id='recipe-space-metadata'>
+ <title>Recipe-Space Metadata</title>
+
+ <para>
+ When stored in recipe-space, the kernel Metadata files reside in a
+ directory hierarchy below
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
+ For a linux-yocto recipe or for a Linux kernel recipe derived
+ by copying and modifying
+ <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
+ to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
+ is typically set to
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>.
+ See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
+ section for more information.
</para>
<para>
- Notice again the three critical variables:
- <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
- and <filename>KARCH</filename>.
- Of these variables, only the <filename>KTYPE</filename> has changed.
- It is now set to "tiny".
+ Here is an example that shows a trivial tree of kernel Metadata
+ stored in recipe-space within a BSP layer:
+ <literallayout class='monospaced'>
+ meta-<replaceable>my_bsp_layer</replaceable>/
+ `-- recipes-kernel
+ `-- linux
+ `-- linux-yocto
+ |-- bsp-standard.scc
+ |-- bsp.cfg
+ `-- standard.cfg
+ </literallayout>
+ </para>
+
+ <para>
+ When the Metadata is stored in recipe-space, you must take
+ steps to ensure BitBake has the necessary information to decide
+ what files to fetch and when they need to be fetched again.
+ It is only necessary to specify the <filename>.scc</filename>
+ files on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
+ BitBake parses them and fetches any files referenced in the
+ <filename>.scc</filename> files by the <filename>include</filename>,
+ <filename>patch</filename>, or <filename>kconf</filename> commands.
+ Because of this, it is necessary to bump the recipe
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+ value when changing the content of files not explicitly listed
+ in the <filename>SRC_URI</filename>.
+ </para>
+
+ <para>
+ If the BSP description is in recipe space, 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 id='metadata-outside-the-recipe-space'>
+ <title>Metadata Outside the Recipe-Space</title>
+
+ <para>
+ When stored outside of the recipe-space, the kernel Metadata
+ files reside in a separate repository.
+ The OpenEmbedded build system adds the Metadata to the build as
+ a "ktype=meta" repository through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ variable.
+ As an example, consider the following <filename>SRC_URI</filename>
+ statement from the <filename>linux-yocto_4.4.bb</filename>
+ kernel recipe:
+ <literallayout class='monospaced'>
+ SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \
+ git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}"
+ </literallayout>
+ <filename>${KMETA}</filename>, in this context, is simply used to
+ name the directory into which the Git fetcher places the Metadata.
+ This behavior is no different than any multi-repository
+ <filename>SRC_URI</filename> statement used in a recipe (e.g.
+ see the previous section).
+ </para>
+
+ <para>
+ You can keep kernel Metadata in a "kernel-cache", which is a
+ directory containing configuration fragments.
+ As with any Metadata kept outside the recipe-space, you simply
+ need to use the <filename>SRC_URI</filename> statement with the
+ "type=kmeta" attribute.
+ Doing so makes the kernel Metadata available during the
+ configuration phase.
+ </para>
+
+<!--
+
+
+ <para>
+ Following is an example that shows how a trivial tree of Metadata
+ is stored in a custom Linux kernel Git repository:
+ <literallayout class='monospaced'>
+ meta/
+ `‐‐ cfg
+ `‐‐ kernel-cache
+ |‐‐ bsp-standard.scc
+ |‐‐ bsp.cfg
+ `‐‐ standard.cfg
+ </literallayout>
+ </para>
+
+ <para>
+ To use a branch different from where the sources reside,
+ specify the branch in the <filename>KMETA</filename> variable
+ in your Linux kernel recipe.
+ Here is an example:
+ <literallayout class='monospaced'>
+ KMETA = "meta"
+ </literallayout>
+ To use the same branch as the sources, set
+ <filename>KMETA</filename> to an empty string:
+ <literallayout class='monospaced'>
+ KMETA = ""
+ </literallayout>
+ If you are working with your own sources and want to create an
+ orphan <filename>meta</filename> branch, use these commands
+ from within your Linux kernel Git repository:
+ <literallayout class='monospaced'>
+ $ git checkout ‐‐orphan meta
+ $ git rm -rf .
+ $ git commit ‐‐allow-empty -m "Create orphan meta branch"
+ </literallayout>
+ </para>
+-->
+
+ <para>
+ If you modify the Metadata, you must not forget to update the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+ statements in the kernel's recipe.
+ In particular, you need to update the
+ <filename>SRCREV_meta</filename> variable to match the commit in
+ the <filename>KMETA</filename> branch you wish to use.
+ Changing the data in these branches and not updating the
+ <filename>SRCREV</filename> statements to match will cause the
+ build to fetch an older commit.
</para>
</section>
</section>
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml
index a9aafd3..aa40fc8 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml
@@ -31,15 +31,19 @@
(<filename>.bbappend</filename>) and provides a convenient
mechanism to create your own recipe files
(<filename>.bb</filename>).
- For details on how to create and work with layers, see the following
- sections in the Yocto Project Development Manual:
- <itemizedlist>
- <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for
- general information on layers and how to create layers.</para></listitem>
- <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for
- specific instructions on setting up a layer for kernel
- development.</para></listitem>
- </itemizedlist>
+ For details on how to create and work with layers, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Manual.
+ <note><title>Tip</title>
+ The Yocto Project comes with many tools that simplify
+ tasks you need to perform.
+ One such tool is the <filename>yocto-layer create</filename>
+ script, which simplifies creating a new layer.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
+ section in the Yocto Project Development Manual for more
+ information.
+ </note>
</para>
</section>
@@ -84,11 +88,11 @@
You also name it accordingly based on the linux-yocto recipe
you are using.
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
within your custom layer:
<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>
The append file should initially extend the
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
@@ -114,6 +118,151 @@
<ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
</note>
</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 id='applying-patches'>
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml
index 2b99ad2..9e0517d 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml
@@ -72,7 +72,7 @@
<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</ulink>"
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
section in the Yocto Project Development Manual for information on
how to use an append file to override metadata.
</para>
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml
index b96acd6..28a3364 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml
@@ -77,14 +77,29 @@
<revremark>Released with the Yocto Project 2.2 Release.</revremark>
</revision>
<revision>
- <revnumber>2.2.1</revnumber>
- <date>January 2017</date>
- <revremark>Released with the Yocto Project 2.2.1 Release.</revremark>
+ <revnumber>2.3</revnumber>
+ <date>May 2017</date>
+ <revremark>Released with the Yocto Project 2.3 Release.</revremark>
</revision>
<revision>
- <revnumber>2.2.2</revnumber>
+ <revnumber>2.3.1</revnumber>
<date>June 2017</date>
- <revremark>Released with the Yocto Project 2.2.2 Release.</revremark>
+ <revremark>Released with the Yocto Project 2.3.1 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.3.2</revnumber>
+ <date>September 2017</date>
+ <revremark>Released with the Yocto Project 2.3.2 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.3.3</revnumber>
+ <date>January 2018</date>
+ <revremark>Released with the Yocto Project 2.3.3 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>2.3.4</revnumber>
+ <date>April 2018</date>
+ <revremark>Released with the Yocto Project 2.3.4 Release.</revremark>
</revision>
</revhistory>
@@ -98,12 +113,33 @@
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 & Wales</ulink> as published by Creative Commons.
</para>
- <note>
- For the latest version of this manual associated with this
- Yocto Project release, see the
- <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>
- from the Yocto Project website.
- </note>
+ <note><title>Manual Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ For the latest version of the Yocto Project Linux
+ Kernel Development Manual associated with this Yocto
+ Project release (version &YOCTO_DOC_VERSION;),
+ see the Yocto Project Linux Kernel Development
+ Manual from the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
+ </para></listitem>
+ <listitem><para>
+ This version of the manual is version
+ &YOCTO_DOC_VERSION;.
+ For later releases of the Yocto Project (if they exist),
+ go to the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and use the drop-down "Active Releases" button
+ and choose the Yocto Project version for which you want
+ the manual.
+ </para></listitem>
+ <listitem><para>
+ For an in-development version of the Yocto Project
+ Linux Kernel Development Manual, see
+ <ulink url='&YOCTO_DOCS_URL;/latest/kernel-dev/kernel-dev.html'></ulink>.
+ </para></listitem>
+ </itemizedlist>
+ </note>
</legalnotice>
</bookinfo>