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-intro.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml
index 263e500..dba4549 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml
@@ -5,144 +5,263 @@
<chapter id='kernel-dev-intro'>
<title>Introduction</title>
-<!--
-<para>
- <emphasis>AR - Darren Hart:</emphasis> See if the concepts in these
- three bullets are adequately covered in somewhere in this manual:
- <itemizedlist>
- <listitem><para>Do we convey that our kernel Git repositories
- have a clear and continuous history, similar to the way the
- kernel Git repositories for <filename>kernel.org</filename>
- do.
- </para></listitem>
- <listitem><para>Does the manual note that Yocto Project delivers
- a key set of supported kernel types, where
- each type is tailored to meet a specific use (e.g. networking,
- consumer, devices, and so forth).</para></listitem>
- <listitem><para>Do we convey that the Yocto Project uses a
- Git branching strategy that, from a
- developer's point of view, results in a linear path from the
- baseline kernel.org, through a select group of features and
- ends with their BSP-specific commits.</para></listitem>
- </itemizedlist>
-</para>
--->
+<section id='kernel-dev-overview'>
+ <title>Overview</title>
- <section id='kernel-dev-overview'>
- <title>Overview</title>
+ <para>
+ Regardless of how you intend to make use of the Yocto Project,
+ chances are you will work with the Linux kernel.
+ This manual describes how to set up your build host to support
+ kernel development, introduces the kernel development process,
+ provides background information on the Yocto Linux kernel
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
+ describes common tasks you can perform using the kernel tools,
+ shows you how to use the kernel Metadata needed to work with
+ the kernel inside the Yocto Project, and provides insight into how
+ the Yocto Project team develops and maintains Yocto Linux kernel
+ Git repositories and Metadata.
+ </para>
- <para>
- Regardless of how you intend to make use of the Yocto Project,
- chances are you will work with the Linux kernel.
- This manual provides background information on the Yocto Linux kernel
- <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
- describes common tasks you can perform using the kernel tools,
- and shows you how to use the kernel Metadata needed to work with
- the kernel inside the Yocto Project.
- </para>
+ <para>
+ Each Yocto Project release has a set of Yocto Linux kernel recipes,
+ whose Git repositories you can view in the Yocto
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
+ the "Yocto Linux Kernel" heading.
+ New recipes for the release track the latest Linux kernel
+ upstream developments from
+ <ulink url='http://www.kernel.org'></ulink> and introduce
+ newly-supported platforms.
+ Previous recipes in the release are refreshed and supported for at
+ least one additional Yocto Project release.
+ As they align, these previous releases are updated to include the
+ latest from the Long Term Support Initiative (LTSI) project.
+ You can learn more about Yocto Linux kernels and LTSI in the
+ "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>"
+ section.
+ </para>
- <para>
- Each Yocto Project release has a set of linux-yocto recipes, whose
- Git repositories you can view in the Yocto
- <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
- the "Yocto Linux Kernel" heading.
- New recipes for the release track the latest upstream developments
- and introduce newly-supported platforms.
- Previous recipes in the release are refreshed and supported for at
- least one additional release.
- As they align, these previous releases are updated to include the
- latest from the
- <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink>
- (LTSI) project.
- Also included is a linux-yocto development recipe
- (<filename>linux-yocto-dev.bb</filename>) should you want to work
- with the very latest in upstream Linux kernel development and
- kernel Metadata development.
- </para>
+ <para>
+ Also included is a Yocto Linux kernel development recipe
+ (<filename>linux-yocto-dev.bb</filename>) should you want to work
+ with the very latest in upstream Yocto Linux kernel development and
+ kernel Metadata development.
+ <note>
+ For more on Yocto Linux kernels, see the
+ "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>
+ section.
+ </note>
+ </para>
- <para>
- The Yocto Project also provides a powerful set of kernel
- tools for managing Linux kernel sources and configuration data.
- You can use these tools to make a single configuration change,
- apply multiple patches, or work with your own kernel sources.
- </para>
+ <para>
+ The Yocto Project also provides a powerful set of kernel
+ tools for managing Yocto Linux kernel sources and configuration data.
+ You can use these tools to make a single configuration change,
+ apply multiple patches, or work with your own kernel sources.
+ </para>
- <para>
- In particular, the kernel tools allow you to generate configuration
- fragments that specify only what you must, and nothing more.
- Configuration fragments only need to contain the highest level
- visible <filename>CONFIG</filename> options as presented by the Linux
- kernel <filename>menuconfig</filename> system.
- Contrast this against a complete Linux kernel
- <filename>.config</filename>, which includes all the automatically
- selected <filename>CONFIG</filename> options.
- This efficiency reduces your maintenance effort and allows you
- to further separate your configuration in ways that make sense for
- your project.
- A common split separates policy and hardware.
- For example, all your kernels might support
- the <filename>proc</filename> and <filename>sys</filename> filesystems,
- but only specific boards require sound, USB, or specific drivers.
- Specifying these configurations individually allows you to aggregate
- them together as needed, but maintains them in only one place.
- Similar logic applies to separating source changes.
- </para>
+ <para>
+ In particular, the kernel tools allow you to generate configuration
+ fragments that specify only what you must, and nothing more.
+ Configuration fragments only need to contain the highest level
+ visible <filename>CONFIG</filename> options as presented by the
+ Yocto Linux kernel <filename>menuconfig</filename> system.
+ Contrast this against a complete Yocto Linux kernel
+ <filename>.config</filename> file, which includes all the automatically
+ selected <filename>CONFIG</filename> options.
+ This efficiency reduces your maintenance effort and allows you
+ to further separate your configuration in ways that make sense for
+ your project.
+ A common split separates policy and hardware.
+ For example, all your kernels might support the
+ <filename>proc</filename> and <filename>sys</filename> filesystems,
+ but only specific boards require sound, USB, or specific drivers.
+ Specifying these configurations individually allows you to aggregate
+ them together as needed, but maintains them in only one place.
+ Similar logic applies to separating source changes.
+ </para>
- <para>
- If you do not maintain your own kernel sources and need to make
- only minimal changes to the sources, the released recipes provide a
- vetted base upon which to layer your changes.
- Doing so allows you to benefit from the continual kernel
- integration and testing performed during development of the
- Yocto Project.
- </para>
+ <para>
+ If you do not maintain your own kernel sources and need to make
+ only minimal changes to the sources, the released recipes provide a
+ vetted base upon which to layer your changes.
+ Doing so allows you to benefit from the continual kernel
+ integration and testing performed during development of the
+ Yocto Project.
+ </para>
- <para>
- If, instead, you have a very specific Linux kernel source tree
- and are unable to align with one of the official linux-yocto
- recipes, an alternative exists by which you can use the Yocto
- Project Linux kernel tools with your own kernel sources.
- </para>
- </section>
+ <para>
+ If, instead, you have a very specific Linux kernel source tree
+ and are unable to align with one of the official Yocto Linux kernel
+ recipes, an alternative exists by which you can use the Yocto
+ Project Linux kernel tools with your own kernel sources.
+ </para>
- <section id='kernel-dev-other-resources'>
- <title>Other Resources</title>
+ <para>
+ The remainder of this manual provides instructions for completing
+ specific Linux kernel development tasks.
+ These instructions assume you are comfortable working with
+ <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
+ recipes and basic open-source development tools.
+ Understanding these concepts will facilitate the process of working
+ with the kernel recipes.
+ If you find you need some additional background, please be sure to
+ review and understand the following documentation:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
+ as described in the Yocto Project Application Development and
+ the Extensible Software Development Kit (eSDK) manual.
+ </para></listitem>
+ <listitem><para>
+ The
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ The
+ "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
+ section.
+ </para></listitem>
+ </itemizedlist>
+ </para>
- <para>
- The sections that follow provide instructions for completing
- specific Linux kernel development tasks.
- These instructions assume you are comfortable working with
- <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
- recipes and basic open-source development tools.
- Understanding these concepts will facilitate the process of working
- with the kernel recipes.
- If you find you need some additional background, please be sure to
- review and understand the following documentation:
- <itemizedlist>
- <listitem><para><ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
- </para></listitem>
- <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-modifying-source-code'>Modifying Source Code</ulink>"
- section in the Yocto Project Development Manual
- </para></listitem>
- <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section
- in the Yocto Project Development Manual</para></listitem>
- <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section
- in the Yocto Project Development Manual.</para></listitem>
- </itemizedlist>
- </para>
+ <para>
+ Finally, while this document focuses on the manual creation of
+ recipes, patches, and configuration files, the Yocto Project
+ Board Support Package (BSP) tools are available to automate
+ this process with existing content and work well to create the
+ initial framework and boilerplate code.
+ For details on these tools, see the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
+ section in the Yocto Project Board Support Package (BSP) Developer's
+ Guide.
+ </para>
+</section>
- <para>
- Finally, while this document focuses on the manual creation of
- recipes, patches, and configuration files, the Yocto Project
- Board Support Package (BSP) tools are available to automate
- this process with existing content and work well to create the
- initial framework and boilerplate code.
- For details on these tools, see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
- section in the Yocto Project Board Support Package (BSP) Developer's
- Guide.
- </para>
- </section>
+<section id='kernel-modification-workflow'>
+ <title>Kernel Modification Workflow</title>
+
+ <para>
+ Kernel modification involves changing the Yocto Project kernel,
+ which could involve changing configuration options as well as adding
+ new kernel recipes.
+ Configuration changes can be added in the form of configuration
+ fragments, while recipe modification comes through the kernel's
+ <filename>recipes-kernel</filename> area in a kernel layer you create.
+ </para>
+
+ <para>
+ This section presents a high-level overview of the Yocto Project
+ kernel modification workflow.
+ The illustration and accompanying list provide general information
+ and references for further information.
+ <imagedata fileref="figures/kernel-dev-flow.png"
+ width="9in" depth="5in" align="center" scalefit="1" />
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set Up Your Host Development System to Support
+ Development Using the Yocto Project:</emphasis>
+ See the
+ "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
+ section in the Yocto Project Quick Start for options on how
+ to get a build host ready to use the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set Up Your Host Development System for Kernel Development:</emphasis>
+ It is recommended that you use <filename>devtool</filename>
+ and an extensible SDK for kernel development.
+ Alternatively, you can use traditional kernel development
+ methods with the Yocto Project.
+ Either way, there are steps you need to take to get the
+ development environment ready.</para>
+
+ <para>Using <filename>devtool</filename> and the eSDK requires
+ that you have a clean build of the image and that you are
+ set up with the appropriate eSDK.
+ For more information, see the
+ "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
+ section.</para>
+
+ <para>Using traditional kernel development requires that you
+ have the kernel source available in an isolated local Git
+ repository.
+ For more information, see the
+ "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Changes to the Kernel Source Code if
+ applicable:</emphasis>
+ Modifying the kernel does not always mean directly
+ changing source files.
+ However, if you have to do this, you make the changes to the
+ files in the eSDK's Build Directory if you are using
+ <filename>devtool</filename>.
+ For more information, see the
+ "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
+ section.</para>
+
+ <para>If you are using traditional kernel development, you
+ edit the source files in the kernel's local Git repository.
+ For more information, see the
+ "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Kernel Configuration Changes if
+ Applicable:</emphasis>
+ If your situation calls for changing the kernel's
+ configuration, you can use
+ <link linkend='using-menuconfig'><filename>menuconfig</filename></link>,
+ which allows you to interactively develop and test the
+ configuration changes you are making to the kernel.
+ Saving changes you make with <filename>menuconfig</filename>
+ updates the kernel's <filename>.config</filename> file.
+ <note><title>Warning</title>
+ Try to resist the temptation to directly edit an
+ existing <filename>.config</filename> file, which is
+ found in the Build Directory among the source code
+ used for the build.
+ Doing so, can produce unexpected results when the
+ OpenEmbedded build system regenerates the configuration
+ file.
+ </note>
+ Once you are satisfied with the configuration
+ changes made using <filename>menuconfig</filename>
+ and you have saved them, you can directly compare the
+ resulting <filename>.config</filename> file against an
+ existing original and gather those changes into a
+ <link linkend='creating-config-fragments'>configuration fragment file</link>
+ to be referenced from within the kernel's
+ <filename>.bbappend</filename> file.</para>
+
+ <para>Additionally, if you are working in a BSP layer
+ and need to modify the BSP's kernel's configuration,
+ you can use the
+ <ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink>
+ script as well as <filename>menuconfig</filename>.
+ The <filename>yocto-kernel</filename> script lets
+ you interactively set up kernel configurations.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Rebuild the Kernel Image With Your Changes:</emphasis>
+ Rebuilding the kernel image applies your changes.
+ Depending on your target hardware, you can verify your changes
+ on actual hardware or perhaps QEMU.
+ </para></listitem>
+ </orderedlist>
+ The remainder of this developer's guide covers common tasks typically
+ used during kernel development, advanced Metadata usage, and Yocto Linux
+ kernel maintenance concepts.
+ </para>
+</section>
+
</chapter>
<!--
vim: expandtab tw=80 ts=4