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