summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-intro.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-intro.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml260
1 files changed, 0 insertions, 260 deletions
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
deleted file mode 100644
index 7c1ea0e510..0000000000
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ /dev/null
@@ -1,260 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='kernel-dev-intro'>
7<title>Introduction</title>
8
9<section id='kernel-dev-overview'>
10 <title>Overview</title>
11
12 <para>
13 Regardless of how you intend to make use of the Yocto Project,
14 chances are you will work with the Linux kernel.
15 This manual describes how to set up your build host to support
16 kernel development, introduces the kernel development process,
17 provides background information on the Yocto Linux kernel
18 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
19 describes common tasks you can perform using the kernel tools,
20 shows you how to use the kernel Metadata needed to work with
21 the kernel inside the Yocto Project, and provides insight into how
22 the Yocto Project team develops and maintains Yocto Linux kernel
23 Git repositories and Metadata.
24 </para>
25
26 <para>
27 Each Yocto Project release has a set of Yocto Linux kernel recipes,
28 whose Git repositories you can view in the Yocto
29 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
30 the "Yocto Linux Kernel" heading.
31 New recipes for the release track the latest Linux kernel
32 upstream developments from
33 <ulink url='http://www.kernel.org'></ulink> and introduce
34 newly-supported platforms.
35 Previous recipes in the release are refreshed and supported for at
36 least one additional Yocto Project release.
37 As they align, these previous releases are updated to include the
38 latest from the Long Term Support Initiative (LTSI) project.
39 You can learn more about Yocto Linux kernels and LTSI in the
40 "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>"
41 section.
42 </para>
43
44 <para>
45 Also included is a Yocto Linux kernel development recipe
46 (<filename>linux-yocto-dev.bb</filename>) should you want to work
47 with the very latest in upstream Yocto Linux kernel development and
48 kernel Metadata development.
49 <note>
50 For more on Yocto Linux kernels, see the
51 "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>
52 section.
53 </note>
54 </para>
55
56 <para>
57 The Yocto Project also provides a powerful set of kernel
58 tools for managing Yocto Linux kernel sources and configuration data.
59 You can use these tools to make a single configuration change,
60 apply multiple patches, or work with your own kernel sources.
61 </para>
62
63 <para>
64 In particular, the kernel tools allow you to generate configuration
65 fragments that specify only what you must, and nothing more.
66 Configuration fragments only need to contain the highest level
67 visible <filename>CONFIG</filename> options as presented by the
68 Yocto Linux kernel <filename>menuconfig</filename> system.
69 Contrast this against a complete Yocto Linux kernel
70 <filename>.config</filename> file, which includes all the automatically
71 selected <filename>CONFIG</filename> options.
72 This efficiency reduces your maintenance effort and allows you
73 to further separate your configuration in ways that make sense for
74 your project.
75 A common split separates policy and hardware.
76 For example, all your kernels might support the
77 <filename>proc</filename> and <filename>sys</filename> filesystems,
78 but only specific boards require sound, USB, or specific drivers.
79 Specifying these configurations individually allows you to aggregate
80 them together as needed, but maintains them in only one place.
81 Similar logic applies to separating source changes.
82 </para>
83
84 <para>
85 If you do not maintain your own kernel sources and need to make
86 only minimal changes to the sources, the released recipes provide a
87 vetted base upon which to layer your changes.
88 Doing so allows you to benefit from the continual kernel
89 integration and testing performed during development of the
90 Yocto Project.
91 </para>
92
93 <para>
94 If, instead, you have a very specific Linux kernel source tree
95 and are unable to align with one of the official Yocto Linux kernel
96 recipes, an alternative exists by which you can use the Yocto
97 Project Linux kernel tools with your own kernel sources.
98 </para>
99
100 <para>
101 The remainder of this manual provides instructions for completing
102 specific Linux kernel development tasks.
103 These instructions assume you are comfortable working with
104 <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink>
105 recipes and basic open-source development tools.
106 Understanding these concepts will facilitate the process of working
107 with the kernel recipes.
108 If you find you need some additional background, please be sure to
109 review and understand the following documentation:
110 <itemizedlist>
111 <listitem><para>
112 <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
113 document.
114 </para></listitem>
115 <listitem><para>
116 <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
117 </para></listitem>
118 <listitem><para>
119 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
120 as described in the Yocto Project Application Development and
121 the Extensible Software Development Kit (eSDK) manual.
122 </para></listitem>
123 <listitem><para>
124 The
125 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
126 section in the Yocto Project Development Tasks Manual.
127 </para></listitem>
128 <listitem><para>
129 The
130 "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
131 section.
132 </para></listitem>
133 </itemizedlist>
134 </para>
135</section>
136
137<section id='kernel-modification-workflow'>
138 <title>Kernel Modification Workflow</title>
139
140 <para>
141 Kernel modification involves changing the Yocto Project kernel,
142 which could involve changing configuration options as well as adding
143 new kernel recipes.
144 Configuration changes can be added in the form of configuration
145 fragments, while recipe modification comes through the kernel's
146 <filename>recipes-kernel</filename> area in a kernel layer you create.
147 </para>
148
149 <para>
150 This section presents a high-level overview of the Yocto Project
151 kernel modification workflow.
152 The illustration and accompanying list provide general information
153 and references for further information.
154 <imagedata fileref="figures/kernel-dev-flow.png"
155 width="9in" depth="5in" align="center" scalefit="1" />
156 </para>
157
158 <para>
159 <orderedlist>
160 <listitem><para>
161
162
163 <emphasis>Set up Your Host Development System to Support
164 Development Using the Yocto Project</emphasis>:
165 See the
166 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>"
167 section in the Yocto Project Development Tasks Manual for
168 options on how to get a build host ready to use the Yocto
169 Project.
170 </para></listitem>
171 <listitem><para>
172 <emphasis>Set Up Your Host Development System for Kernel Development:</emphasis>
173 It is recommended that you use <filename>devtool</filename>
174 and an extensible SDK for kernel development.
175 Alternatively, you can use traditional kernel development
176 methods with the Yocto Project.
177 Either way, there are steps you need to take to get the
178 development environment ready.</para>
179
180 <para>Using <filename>devtool</filename> and the eSDK requires
181 that you have a clean build of the image and that you are
182 set up with the appropriate eSDK.
183 For more information, see the
184 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
185 section.</para>
186
187 <para>Using traditional kernel development requires that you
188 have the kernel source available in an isolated local Git
189 repository.
190 For more information, see the
191 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
192 section.
193 </para></listitem>
194 <listitem><para>
195 <emphasis>Make Changes to the Kernel Source Code if
196 applicable:</emphasis>
197 Modifying the kernel does not always mean directly
198 changing source files.
199 However, if you have to do this, you make the changes to the
200 files in the eSDK's Build Directory if you are using
201 <filename>devtool</filename>.
202 For more information, see the
203 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
204 section.</para>
205
206 <para>If you are using traditional kernel development, you
207 edit the source files in the kernel's local Git repository.
208 For more information, see the
209 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
210 section.
211 </para></listitem>
212 <listitem><para>
213 <emphasis>Make Kernel Configuration Changes if
214 Applicable:</emphasis>
215 If your situation calls for changing the kernel's
216 configuration, you can use
217 <link linkend='using-menuconfig'><filename>menuconfig</filename></link>,
218 which allows you to interactively develop and test the
219 configuration changes you are making to the kernel.
220 Saving changes you make with <filename>menuconfig</filename>
221 updates the kernel's <filename>.config</filename> file.
222 <note><title>Warning</title>
223 Try to resist the temptation to directly edit an
224 existing <filename>.config</filename> file, which is
225 found in the Build Directory among the source code
226 used for the build.
227 Doing so, can produce unexpected results when the
228 OpenEmbedded build system regenerates the configuration
229 file.
230 </note>
231 Once you are satisfied with the configuration
232 changes made using <filename>menuconfig</filename>
233 and you have saved them, you can directly compare the
234 resulting <filename>.config</filename> file against an
235 existing original and gather those changes into a
236 <link linkend='creating-config-fragments'>configuration fragment file</link>
237 to be referenced from within the kernel's
238 <filename>.bbappend</filename> file.</para>
239
240 <para>Additionally, if you are working in a BSP layer
241 and need to modify the BSP's kernel's configuration,
242 you can use <filename>menuconfig</filename>.
243 </para></listitem>
244 <listitem><para>
245 <emphasis>Rebuild the Kernel Image With Your Changes:</emphasis>
246 Rebuilding the kernel image applies your changes.
247 Depending on your target hardware, you can verify your changes
248 on actual hardware or perhaps QEMU.
249 </para></listitem>
250 </orderedlist>
251 The remainder of this developer's guide covers common tasks typically
252 used during kernel development, advanced Metadata usage, and Yocto Linux
253 kernel maintenance concepts.
254 </para>
255</section>
256
257</chapter>
258<!--
259vim: expandtab tw=80 ts=4
260-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-03 02:13:49 +0000