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