summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-maint-appx.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-maint-appx.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-maint-appx.xml357
1 files changed, 0 insertions, 357 deletions
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml
deleted file mode 100644
index 3d9c7c66fd..0000000000
--- a/documentation/kernel-dev/kernel-dev-maint-appx.xml
+++ /dev/null
@@ -1,357 +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<appendix id='kernel-dev-maint-appx'>
7<title>Kernel Maintenance</title>
8
9 <section id='tree-construction'>
10 <title>Tree Construction</title>
11
12 <para>
13 This section describes construction of the Yocto Project kernel
14 source repositories as accomplished by the Yocto Project team to
15 create Yocto Linux kernel repositories.
16 These kernel repositories are found under the heading "Yocto Linux
17 Kernel" at
18 <ulink url='&YOCTO_GIT_URL;'>&YOCTO_GIT_URL;</ulink>
19 and are shipped as part of a Yocto Project release.
20 The team creates these repositories by compiling and executing the
21 set of feature descriptions for every BSP and feature in the
22 product.
23 Those feature descriptions list all necessary patches,
24 configurations, branches, tags, and feature divisions found in a
25 Yocto Linux kernel.
26 Thus, the Yocto Project Linux kernel repository (or tree) and
27 accompanying Metadata in the
28 <filename>yocto-kernel-cache</filename> are built.
29 </para>
30
31 <para>
32 The existence of these repositories allow you to access and clone a
33 particular Yocto Project Linux kernel repository and use it to
34 build images based on their configurations and features.
35 </para>
36
37 <para>
38 You can find the files used to describe all the valid features and
39 BSPs in the Yocto Project Linux kernel in any clone of the Yocto
40 Project Linux kernel source repository and
41 <filename>yocto-kernel-cache</filename> Git trees.
42 For example, the following commands clone the Yocto Project
43 baseline Linux kernel that branches off
44 <filename>linux.org</filename> version 4.12 and the
45 <filename>yocto-kernel-cache</filename>, which contains stores of
46 kernel Metadata:
47 <literallayout class='monospaced'>
48 $ git clone git://git.yoctoproject.org/linux-yocto-4.12
49 $ git clone git://git.yoctoproject.org/linux-kernel-cache
50 </literallayout>
51 For more information on how to set up a local Git repository of
52 the Yocto Project Linux kernel files, see the
53 "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
54 section.
55 </para>
56
57 <para>
58 Once you have cloned the kernel Git repository and the
59 cache of Metadata on your local machine, you can discover the
60 branches that are available in the repository using the following
61 Git command:
62 <literallayout class='monospaced'>
63 $ git branch -a
64 </literallayout>
65 Checking out a branch allows you to work with a particular
66 Yocto Linux kernel.
67 For example, the following commands check out the
68 "standard/beagleboard" branch of the Yocto Linux kernel repository
69 and the "yocto-4.12" branch of the
70 <filename>yocto-kernel-cache</filename> repository:
71 <literallayout class='monospaced'>
72 $ cd ~/linux-yocto-4.12
73 $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
74 $ cd ~/linux-kernel-cache
75 $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12
76 </literallayout>
77 <note>
78 Branches in the <filename>yocto-kernel-cache</filename>
79 repository correspond to Yocto Linux kernel versions
80 (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
81 </note>
82 Once you have checked out and switched to appropriate branches,
83 you can see a snapshot of all the kernel source files used to
84 used to build that particular Yocto Linux kernel for a
85 particular board.
86 </para>
87
88 <para>
89 To see the features and configurations for a particular Yocto
90 Linux kernel, you need to examine the
91 <filename>yocto-kernel-cache</filename> Git repository.
92 As mentioned, branches in the
93 <filename>yocto-kernel-cache</filename> repository correspond to
94 Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>).
95 Branches contain descriptions in the form of
96 <filename>.scc</filename> and <filename>.cfg</filename> files.
97 </para>
98
99 <para>
100 You should realize, however, that browsing your local
101 <filename>yocto-kernel-cache</filename> repository for feature
102 descriptions and patches is not an effective way to determine what
103 is in a particular kernel branch.
104 Instead, you should use Git directly to discover the changes in
105 a branch.
106 Using Git is an efficient and flexible way to inspect changes to
107 the kernel.
108 <note>
109 Ground up reconstruction of the complete kernel tree is an
110 action only taken by the Yocto Project team during an active
111 development cycle.
112 When you create a clone of the kernel Git repository, you are
113 simply making it efficiently available for building and
114 development.
115 </note>
116 </para>
117
118 <para>
119 The following steps describe what happens when the Yocto Project
120 Team constructs the Yocto Project kernel source Git repository
121 (or tree) found at
122 <ulink url='&YOCTO_GIT_URL;'></ulink> given the
123 introduction of a new top-level kernel feature or BSP.
124 The following actions effectively provide the Metadata
125 and create the tree that includes the new feature, patch, or BSP:
126 <orderedlist>
127 <listitem><para>
128 <emphasis>Pass Feature to the OpenEmbedded Build System:</emphasis>
129 A top-level kernel feature is passed to the kernel build
130 subsystem.
131 Normally, this feature is a BSP for a particular kernel
132 type.
133 </para></listitem>
134 <listitem><para>
135 <emphasis>Locate Feature:</emphasis>
136 The file that describes the top-level feature is located
137 by searching these system directories:
138 <itemizedlist>
139 <listitem><para>
140 The in-tree kernel-cache directories, which are
141 located in the
142 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink>
143 repository organized under the "Yocto Linux Kernel"
144 heading in the
145 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
146 </para></listitem>
147 <listitem><para>
148 Areas pointed to by <filename>SRC_URI</filename>
149 statements found in kernel recipes
150 </para></listitem>
151 </itemizedlist>
152 For a typical build, the target of the search is a
153 feature description in an <filename>.scc</filename> file
154 whose name follows this format (e.g.
155 <filename>beaglebone-standard.scc</filename> and
156 <filename>beaglebone-preempt-rt.scc</filename>):
157 <literallayout class='monospaced'>
158 <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
159 </literallayout>
160 </para></listitem>
161 <listitem><para>
162 <emphasis>Expand Feature:</emphasis>
163 Once located, the feature description is either expanded
164 into a simple script of actions, or into an existing
165 equivalent script that is already part of the shipped
166 kernel.
167 </para></listitem>
168 <listitem><para>
169 <emphasis>Append Extra Features:</emphasis>
170 Extra features are appended to the top-level feature
171 description.
172 These features can come from the
173 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
174 variable in recipes.
175 </para></listitem>
176 <listitem><para>
177 <emphasis>Locate, Expand, and Append Each Feature:</emphasis>
178 Each extra feature is located, expanded and appended to
179 the script as described in step three.
180 </para></listitem>
181 <listitem><para>
182 <emphasis>Execute the Script:</emphasis>
183 The script is executed to produce files
184 <filename>.scc</filename> and <filename>.cfg</filename>
185 files in appropriate directories of the
186 <filename>yocto-kernel-cache</filename> repository.
187 These files are descriptions of all the branches, tags,
188 patches and configurations that need to be applied to the
189 base Git repository to completely create the
190 source (build) branch for the new BSP or feature.
191 </para></listitem>
192 <listitem><para>
193 <emphasis>Clone Base Repository:</emphasis>
194 The base repository is cloned, and the actions
195 listed in the <filename>yocto-kernel-cache</filename>
196 directories are applied to the tree.
197 </para></listitem>
198 <listitem><para>
199 <emphasis>Perform Cleanup:</emphasis>
200 The Git repositories are left with the desired branches
201 checked out and any required branching, patching and
202 tagging has been performed.
203 </para></listitem>
204 </orderedlist>
205 </para>
206
207 <para>
208 The kernel tree and cache are ready for developer consumption to
209 be locally cloned, configured, and built into a Yocto Project
210 kernel specific to some target hardware.
211 <note><title>Notes</title>
212 <itemizedlist>
213 <listitem><para>
214 The generated <filename>yocto-kernel-cache</filename>
215 repository adds to the kernel as shipped with the Yocto
216 Project release.
217 Any add-ons and configuration data are applied to the
218 end of an existing branch.
219 The full repository generation that is found in the
220 official Yocto Project kernel repositories at
221 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>
222 is the combination of all supported boards and
223 configurations.
224 </para></listitem>
225 <listitem><para>
226 The technique the Yocto Project team uses is flexible
227 and allows for seamless blending of an immutable
228 history with additional patches specific to a
229 deployment.
230 Any additions to the kernel become an integrated part
231 of the branches.
232 </para></listitem>
233 <listitem><para>
234 The full kernel tree that you see on
235 <ulink url='&YOCTO_GIT_URL;'></ulink> is
236 generated through repeating the above steps for all
237 valid BSPs.
238 The end result is a branched, clean history tree that
239 makes up the kernel for a given release.
240 You can see the script (<filename>kgit-scc</filename>)
241 responsible for this in the
242 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools'><filename>yocto-kernel-tools</filename></ulink>
243 repository.
244 </para></listitem>
245 <listitem><para>
246 The steps used to construct the full kernel tree are
247 the same steps that BitBake uses when it builds a
248 kernel image.
249 </para></listitem>
250 </itemizedlist>
251 </note>
252 </para>
253 </section>
254
255 <section id='build-strategy'>
256 <title>Build Strategy</title>
257
258 <para>
259 Once you have cloned a Yocto Linux kernel repository and the
260 cache repository (<filename>yocto-kernel-cache</filename>) onto
261 your development system, you can consider the compilation phase
262 of kernel development, which is building a kernel image.
263 Some prerequisites exist that are validated by the build process
264 before compilation starts:
265 </para>
266
267 <itemizedlist>
268 <listitem><para>
269 The
270 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
271 points to the kernel Git repository.
272 </para></listitem>
273 <listitem><para>
274 A BSP build branch with Metadata exists in the
275 <filename>yocto-kernel-cache</filename> repository.
276 The branch is based on the Yocto Linux kernel version and
277 has configurations and features grouped under the
278 <filename>yocto-kernel-cache/bsp</filename> directory.
279 For example, features and configurations for the
280 BeagleBone Board assuming a
281 <filename>linux-yocto_4.12</filename> kernel reside in the
282 following area of the <filename>yocto-kernel-cache</filename>
283 repository:
284 <literallayout class='monospaced'>
285 yocto-kernel-cache/bsp/beaglebone
286 </literallayout>
287 <note>
288 In the previous example, the "yocto-4.12" branch is
289 checked out in the <filename>yocto-kernel-cache</filename>
290 repository.
291 </note>
292 </para></listitem>
293 </itemizedlist>
294
295 <para>
296 The OpenEmbedded build system makes sure these conditions exist
297 before attempting compilation.
298 Other means, however, do exist, such as as bootstrapping a BSP.
299 </para>
300
301 <para>
302 Before building a kernel, the build process verifies the tree
303 and configures the kernel by processing all of the
304 configuration "fragments" specified by feature descriptions
305 in the <filename>.scc</filename> files.
306 As the features are compiled, associated kernel configuration
307 fragments are noted and recorded in the series of directories
308 in their compilation order.
309 The fragments are migrated, pre-processed and passed to the
310 Linux Kernel Configuration subsystem (<filename>lkc</filename>) as
311 raw input in the form of a <filename>.config</filename> file.
312 The <filename>lkc</filename> uses its own internal dependency
313 constraints to do the final processing of that information and
314 generates the final <filename>.config</filename> file that is used
315 during compilation.
316 </para>
317
318 <para>
319 Using the board's architecture and other relevant values from
320 the board's template, kernel compilation is started and a kernel
321 image is produced.
322 </para>
323
324 <para>
325 The other thing that you notice once you configure a kernel is that
326 the build process generates a build tree that is separate from
327 your kernel's local Git source repository tree.
328 This build tree has a name that uses the following form, where
329 <filename>${MACHINE}</filename> is the metadata name of the
330 machine (BSP) and "kernel_type" is one of the Yocto Project
331 supported kernel types (e.g. "standard"):
332 <literallayout class='monospaced'>
333 linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build
334 </literallayout>
335 </para>
336
337 <para>
338 The existing support in the <filename>kernel.org</filename> tree
339 achieves this default functionality.
340 </para>
341
342 <para>
343 This behavior means that all the generated files for a particular
344 machine or BSP are now in the build tree directory.
345 The files include the final <filename>.config</filename> file,
346 all the <filename>.o</filename> files, the <filename>.a</filename>
347 files, and so forth.
348 Since each machine or BSP has its own separate
349 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
350 in its own separate branch of the Git repository, you can easily
351 switch between different builds.
352 </para>
353 </section>
354</appendix>
355<!--
356vim: expandtab tw=80 ts=4
357-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-15 12:52:02 +0000