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