1 files changed, 178 insertions, 0 deletions
diff --git a/documentation/kernel-dev/intro.rst b/documentation/kernel-dev/intro.rst
new file mode 100644
index 0000000000..a663733a1d
--- /dev/null
+++ b/documentation/kernel-dev/intro.rst
@@ -0,0 +1,178 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+************
+Introduction
+************
+
+Overview
+========
+
+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 :term:`Metadata`, 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.
+
+Each Yocto Project release has a set of Yocto Linux kernel recipes,
+whose Git repositories you can view in the Yocto
+:yocto_git:`Source Repositories <>` under the "Yocto Linux Kernel"
+heading. New recipes for the release track the latest Linux kernel
+upstream developments from https://www.kernel.org 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
+":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`" section.
+
+Also included is a Yocto Linux kernel development recipe
+(``linux-yocto-dev.bb``) 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
+   ":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`"
+   section.
+
+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.
+
+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
+``CONFIG`` options as presented by the Yocto Linux kernel ``menuconfig``
+system. Contrast this against a complete Yocto Linux kernel ``.config``
+file, which includes all the automatically selected ``CONFIG`` 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 ``proc`` and ``sys`` 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.
+
+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.
+
+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,
+you have a way to use the Yocto Project Linux kernel tools with your
+own kernel sources.
+
+The remainder of this manual provides instructions for completing
+specific Linux kernel development tasks. These instructions assume you
+are comfortable working with :oe_wiki:`BitBake </Bitbake>` 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:
+
+-  :doc:`/brief-yoctoprojectqs/index` document.
+
+-  :doc:`/overview-manual/index`.
+
+-  :ref:`devtool
+   workflow <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>`
+   as described in the Yocto Project Application Development and the
+   Extensible Software Development Kit (eSDK) manual.
+
+-  The ":ref:`dev-manual/layers:understanding and creating layers`"
+   section in the Yocto Project Development Tasks Manual.
+
+-  The ":ref:`kernel-dev/intro:kernel modification workflow`" section.
+
+Kernel Modification Workflow
+============================
+
+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 ``recipes-kernel`` area in a kernel layer you create.
+
+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.
+
+.. image:: figures/kernel-dev-flow.png
+   :width: 100%
+
+#. *Set up Your Host Development System to Support Development Using the
+   Yocto Project*: See the ":doc:`/dev-manual/start`" section in
+   the Yocto Project Development Tasks Manual for options on how to get
+   a build host ready to use the Yocto Project.
+
+#. *Set Up Your Host Development System for Kernel Development:* It is
+   recommended that you use ``devtool`` 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.
+
+   Using ``devtool`` requires that you have a clean build
+   of the image. For
+   more information, see the
+   ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
+   section.
+
+   Using traditional kernel development requires that you have the
+   kernel source available in an isolated local Git repository. For more
+   information, see the
+   ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
+   section.
+
+#. *Make Changes to the Kernel Source Code if applicable:* 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
+   Yocto's :term:`Build Directory` if you are using ``devtool``. For more
+   information, see the
+   ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
+   section.
+
+   If you are using traditional kernel development, you edit the source
+   files in the kernel's local Git repository. For more information, see the
+   ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
+   section.
+
+#. *Make Kernel Configuration Changes if Applicable:* If your situation
+   calls for changing the kernel's configuration, you can use
+   :ref:`menuconfig <kernel-dev/common:using \`\`menuconfig\`\`>`,
+   which allows you to
+   interactively develop and test the configuration changes you are
+   making to the kernel. Saving changes you make with ``menuconfig``
+   updates the kernel's ``.config`` file.
+
+   .. note::
+
+      Try to resist the temptation to directly edit an existing ``.config``
+      file, which is found in the :term:`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.
+
+   Once you are satisfied with the configuration changes made using
+   ``menuconfig`` and you have saved them, you can directly compare the
+   resulting ``.config`` file against an existing original and gather
+   those changes into a
+   :ref:`configuration fragment file <kernel-dev/common:creating configuration fragments>` to be
+   referenced from within the kernel's ``.bbappend`` file.
+
+   Additionally, if you are working in a BSP layer and need to modify
+   the BSP's kernel's configuration, you can use ``menuconfig``.
+
+#. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel
+   image applies your changes. Depending on your target hardware, you
+   can verify your changes on actual hardware or perhaps QEMU.
+
+The remainder of this developer's guide covers common tasks typically
+used during kernel development, advanced Metadata usage, and Yocto Linux
+kernel maintenance concepts.