1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3************ 4Introduction 5************ 6 7Overview 8======== 9 10Regardless of how you intend to make use of the Yocto Project, chances 11are you will work with the Linux kernel. This manual describes how to 12set up your build host to support kernel development, introduces the 13kernel development process, provides background information on the Yocto 14Linux kernel :term:`Metadata`, describes 15common tasks you can perform using the kernel tools, shows you how to 16use the kernel Metadata needed to work with the kernel inside the Yocto 17Project, and provides insight into how the Yocto Project team develops 18and maintains Yocto Linux kernel Git repositories and Metadata. 19 20Each Yocto Project release has a set of Yocto Linux kernel recipes, 21whose Git repositories you can view in the Yocto 22:yocto_git:`Source Repositories <>` under the "Yocto Linux Kernel" 23heading. New recipes for the release track the latest Linux kernel 24upstream developments from https://www.kernel.org and introduce 25newly-supported platforms. Previous recipes in the release are refreshed 26and supported for at least one additional Yocto Project release. As they 27align, these previous releases are updated to include the latest from 28the Long Term Support Initiative (LTSI) project. You can learn more 29about Yocto Linux kernels and LTSI in the 30":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`" section. 31 32Also included is a Yocto Linux kernel development recipe 33(``linux-yocto-dev.bb``) should you want to work with the very latest in 34upstream Yocto Linux kernel development and kernel Metadata development. 35 36.. note:: 37 38 For more on Yocto Linux kernels, see the 39 ":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`" 40 section. 41 42The Yocto Project also provides a powerful set of kernel tools for 43managing Yocto Linux kernel sources and configuration data. You can use 44these tools to make a single configuration change, apply multiple 45patches, or work with your own kernel sources. 46 47In particular, the kernel tools allow you to generate configuration 48fragments that specify only what you must, and nothing more. 49Configuration fragments only need to contain the highest level visible 50``CONFIG`` options as presented by the Yocto Linux kernel ``menuconfig`` 51system. Contrast this against a complete Yocto Linux kernel ``.config`` 52file, which includes all the automatically selected ``CONFIG`` options. 53This efficiency reduces your maintenance effort and allows you to 54further separate your configuration in ways that make sense for your 55project. A common split separates policy and hardware. For example, all 56your kernels might support the ``proc`` and ``sys`` filesystems, but 57only specific boards require sound, USB, or specific drivers. Specifying 58these configurations individually allows you to aggregate them together 59as needed, but maintains them in only one place. Similar logic applies 60to separating source changes. 61 62If you do not maintain your own kernel sources and need to make only 63minimal changes to the sources, the released recipes provide a vetted 64base upon which to layer your changes. Doing so allows you to benefit 65from the continual kernel integration and testing performed during 66development of the Yocto Project. 67 68If, instead, you have a very specific Linux kernel source tree and are 69unable to align with one of the official Yocto Linux kernel recipes, 70you have a way to use the Yocto Project Linux kernel tools with your 71own kernel sources. 72 73The remainder of this manual provides instructions for completing 74specific Linux kernel development tasks. These instructions assume you 75are comfortable working with :oe_wiki:`BitBake </Bitbake>` recipes and basic 76open-source development tools. Understanding these concepts will 77facilitate the process of working with the kernel recipes. If you find 78you need some additional background, please be sure to review and 79understand the following documentation: 80 81- :doc:`/brief-yoctoprojectqs/index` document. 82 83- :doc:`/overview-manual/index`. 84 85- :ref:`devtool 86 workflow <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>` 87 as described in the Yocto Project Application Development and the 88 Extensible Software Development Kit (eSDK) manual. 89 90- The ":ref:`dev-manual/layers:understanding and creating layers`" 91 section in the Yocto Project Development Tasks Manual. 92 93- The ":ref:`kernel-dev/intro:kernel modification workflow`" section. 94 95Kernel Modification Workflow 96============================ 97 98Kernel modification involves changing the Yocto Project kernel, which 99could involve changing configuration options as well as adding new 100kernel recipes. Configuration changes can be added in the form of 101configuration fragments, while recipe modification comes through the 102kernel's ``recipes-kernel`` area in a kernel layer you create. 103 104This section presents a high-level overview of the Yocto Project kernel 105modification workflow. The illustration and accompanying list provide 106general information and references for further information. 107 108.. image:: figures/kernel-dev-flow.png 109 :width: 100% 110 111#. *Set up Your Host Development System to Support Development Using the 112 Yocto Project*: See the ":doc:`/dev-manual/start`" section in 113 the Yocto Project Development Tasks Manual for options on how to get 114 a build host ready to use the Yocto Project. 115 116#. *Set Up Your Host Development System for Kernel Development:* It is 117 recommended that you use ``devtool`` for kernel 118 development. Alternatively, you can use traditional kernel 119 development methods with the Yocto Project. Either way, there are 120 steps you need to take to get the development environment ready. 121 122 Using ``devtool`` requires that you have a clean build 123 of the image. For 124 more information, see the 125 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" 126 section. 127 128 Using traditional kernel development requires that you have the 129 kernel source available in an isolated local Git repository. For more 130 information, see the 131 ":ref:`kernel-dev/common:getting ready for traditional kernel development`" 132 section. 133 134#. *Make Changes to the Kernel Source Code if applicable:* Modifying the 135 kernel does not always mean directly changing source files. However, 136 if you have to do this, you make the changes to the files in the 137 Yocto's :term:`Build Directory` if you are using ``devtool``. For more 138 information, see the 139 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" 140 section. 141 142 If you are using traditional kernel development, you edit the source 143 files in the kernel's local Git repository. For more information, see the 144 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" 145 section. 146 147#. *Make Kernel Configuration Changes if Applicable:* If your situation 148 calls for changing the kernel's configuration, you can use 149 :ref:`menuconfig <kernel-dev/common:using \`\`menuconfig\`\`>`, 150 which allows you to 151 interactively develop and test the configuration changes you are 152 making to the kernel. Saving changes you make with ``menuconfig`` 153 updates the kernel's ``.config`` file. 154 155 .. note:: 156 157 Try to resist the temptation to directly edit an existing ``.config`` 158 file, which is found in the :term:`Build Directory` among the source code 159 used for the build. Doing so, can produce unexpected results when 160 the OpenEmbedded build system regenerates the configuration file. 161 162 Once you are satisfied with the configuration changes made using 163 ``menuconfig`` and you have saved them, you can directly compare the 164 resulting ``.config`` file against an existing original and gather 165 those changes into a 166 :ref:`configuration fragment file <kernel-dev/common:creating configuration fragments>` to be 167 referenced from within the kernel's ``.bbappend`` file. 168 169 Additionally, if you are working in a BSP layer and need to modify 170 the BSP's kernel's configuration, you can use ``menuconfig``. 171 172#. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel 173 image applies your changes. Depending on your target hardware, you 174 can verify your changes on actual hardware or perhaps QEMU. 175 176The remainder of this developer's guide covers common tasks typically 177used during kernel development, advanced Metadata usage, and Yocto Linux 178kernel maintenance concepts. 179