blob: a663733a1df982d96f67f3f29f84e99a33b1ad73 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3************
4Introduction
5************
6
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007Overview
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050024upstream developments from https://www.kernel.org and introduce
Andrew Geisslerc9f78652020-09-18 14:11:35 -050025newly-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
Andrew Geissler6ce62a22020-11-30 19:58:47 -060029about Yocto Linux kernels and LTSI in the
Andrew Geissler09209ee2020-12-13 08:44:15 -060030":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050031
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050038 For more on Yocto Linux kernels, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060039 ":ref:`kernel-dev/concepts-appx:yocto project kernel development and maintenance`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050040 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -070069unable 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.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072
73The remainder of this manual provides instructions for completing
74specific Linux kernel development tasks. These instructions assume you
Andrew Geisslerd1e89492021-02-12 15:35:20 -060075are comfortable working with :oe_wiki:`BitBake </Bitbake>` recipes and basic
Andrew Geisslerc9f78652020-09-18 14:11:35 -050076open-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
Andrew Geissler09209ee2020-12-13 08:44:15 -060081- :doc:`/brief-yoctoprojectqs/index` document.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050082
Andrew Geissler09209ee2020-12-13 08:44:15 -060083- :doc:`/overview-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050084
85- :ref:`devtool
Andrew Geissler09209ee2020-12-13 08:44:15 -060086 workflow <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050087 as described in the Yocto Project Application Development and the
88 Extensible Software Development Kit (eSDK) manual.
89
Andrew Geissler517393d2023-01-13 08:55:19 -060090- The ":ref:`dev-manual/layers:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050091 section in the Yocto Project Development Tasks Manual.
92
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050093- The ":ref:`kernel-dev/intro:kernel modification workflow`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050094
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
Andrew Geisslerd5838332022-05-27 11:33:10 -0500109 :width: 100%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500110
Andrew Geissler517393d2023-01-13 08:55:19 -0600111#. *Set up Your Host Development System to Support Development Using the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600112 Yocto Project*: See the ":doc:`/dev-manual/start`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113 the Yocto Project Development Tasks Manual for options on how to get
114 a build host ready to use the Yocto Project.
115
Andrew Geissler517393d2023-01-13 08:55:19 -0600116#. *Set Up Your Host Development System for Kernel Development:* It is
Patrick Williams92b42cb2022-09-03 06:53:57 -0500117 recommended that you use ``devtool`` for kernel
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500118 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
Patrick Williams92b42cb2022-09-03 06:53:57 -0500122 Using ``devtool`` requires that you have a clean build
123 of the image. For
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500124 more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600125 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500126 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600131 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500132 section.
133
Andrew Geissler517393d2023-01-13 08:55:19 -0600134#. *Make Changes to the Kernel Source Code if applicable:* Modifying the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500135 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
Patrick Williams2390b1b2022-11-03 13:47:49 -0500137 Yocto's :term:`Build Directory` if you are using ``devtool``. For more
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500138 information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600139 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500140 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600144 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145 section.
146
Andrew Geissler517393d2023-01-13 08:55:19 -0600147#. *Make Kernel Configuration Changes if Applicable:* If your situation
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500148 calls for changing the kernel's configuration, you can use
Andrew Geissler09209ee2020-12-13 08:44:15 -0600149 :ref:`menuconfig <kernel-dev/common:using \`\`menuconfig\`\`>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500150 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500157 Try to resist the temptation to directly edit an existing ``.config``
Patrick Williams2390b1b2022-11-03 13:47:49 -0500158 file, which is found in the :term:`Build Directory` among the source code
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500159 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500165 those changes into a
Andrew Geissler09209ee2020-12-13 08:44:15 -0600166 :ref:`configuration fragment file <kernel-dev/common:creating configuration fragments>` to be
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500167 referenced from within the kernel's ``.bbappend`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500168
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
Andrew Geissler517393d2023-01-13 08:55:19 -0600172#. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173 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.