blob: 69f680688f79e3b5e9d2144a64b28b7e999528fc [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******************
4Kernel Maintenance
5******************
6
7Tree Construction
8=================
9
10This section describes construction of the Yocto Project kernel source
11repositories as accomplished by the Yocto Project team to create Yocto
12Linux kernel repositories. These kernel repositories are found under the
13heading "Yocto Linux Kernel" at :yocto_git:`/` and
14are shipped as part of a Yocto Project release. The team creates these
15repositories by compiling and executing the set of feature descriptions
16for every BSP and feature in the product. Those feature descriptions
17list all necessary patches, configurations, branches, tags, and feature
18divisions found in a Yocto Linux kernel. Thus, the Yocto Project Linux
19kernel repository (or tree) and accompanying Metadata in the
20``yocto-kernel-cache`` are built.
21
22The existence of these repositories allow you to access and clone a
23particular Yocto Project Linux kernel repository and use it to build
24images based on their configurations and features.
25
26You can find the files used to describe all the valid features and BSPs
27in the Yocto Project Linux kernel in any clone of the Yocto Project
28Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For
29example, the following commands clone the Yocto Project baseline Linux
30kernel that branches off ``linux.org`` version 4.12 and the
31``yocto-kernel-cache``, which contains stores of kernel Metadata:
32::
33
34 $ git clone git://git.yoctoproject.org/linux-yocto-4.12
35 $ git clone git://git.yoctoproject.org/linux-kernel-cache
36
37For more information on
38how to set up a local Git repository of the Yocto Project Linux kernel
39files, see the
40":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
41section.
42
43Once you have cloned the kernel Git repository and the cache of Metadata
44on your local machine, you can discover the branches that are available
Andrew Geissler4c19ea12020-10-27 13:52:24 -050045in the repository using the following Git command:
46::
47
48 $ git branch -a
49
Andrew Geisslerc9f78652020-09-18 14:11:35 -050050Checking out a branch allows you to work with a particular Yocto Linux
51kernel. For example, the following commands check out the
52"standard/beagleboard" branch of the Yocto Linux kernel repository and
53the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository:
54::
55
56 $ cd ~/linux-yocto-4.12
57 $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
58 $ cd ~/linux-kernel-cache
59 $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12
60
61.. note::
62
Andrew Geissler4c19ea12020-10-27 13:52:24 -050063 Branches in the ``yocto-kernel-cache`` repository correspond to Yocto Linux
64 kernel versions (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050065
66Once you have checked out and switched to appropriate branches, you can
67see a snapshot of all the kernel source files used to used to build that
68particular Yocto Linux kernel for a particular board.
69
70To see the features and configurations for a particular Yocto Linux
71kernel, you need to examine the ``yocto-kernel-cache`` Git repository.
72As mentioned, branches in the ``yocto-kernel-cache`` repository
73correspond to Yocto Linux kernel versions (e.g. ``yocto-4.12``).
74Branches contain descriptions in the form of ``.scc`` and ``.cfg``
75files.
76
77You should realize, however, that browsing your local
78``yocto-kernel-cache`` repository for feature descriptions and patches
79is not an effective way to determine what is in a particular kernel
80branch. Instead, you should use Git directly to discover the changes in
81a branch. Using Git is an efficient and flexible way to inspect changes
82to the kernel.
83
84.. note::
85
86 Ground up reconstruction of the complete kernel tree is an action
87 only taken by the Yocto Project team during an active development
88 cycle. When you create a clone of the kernel Git repository, you are
89 simply making it efficiently available for building and development.
90
91The following steps describe what happens when the Yocto Project Team
92constructs the Yocto Project kernel source Git repository (or tree)
93found at :yocto_git:`/` given the introduction of a new
94top-level kernel feature or BSP. The following actions effectively
95provide the Metadata and create the tree that includes the new feature,
96patch, or BSP:
97
981. *Pass Feature to the OpenEmbedded Build System:* A top-level kernel
99 feature is passed to the kernel build subsystem. Normally, this
100 feature is a BSP for a particular kernel type.
101
1022. *Locate Feature:* The file that describes the top-level feature is
103 located by searching these system directories:
104
105 - The in-tree kernel-cache directories, which are located in the
106 :yocto_git:`yocto-kernel-cache </cgit/cgit.cgi/yocto-kernel-cache/tree/bsp>`
107 repository organized under the "Yocto Linux Kernel" heading in the
108 :yocto_git:`Yocto Project Source Repositories <>`.
109
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500110 - Areas pointed to by ``SRC_URI`` statements found in kernel recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500111
112 For a typical build, the target of the search is a feature
113 description in an ``.scc`` file whose name follows this format (e.g.
114 ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``):
115 ::
116
117 bsp_root_name-kernel_type.scc
118
1193. *Expand Feature:* Once located, the feature description is either
120 expanded into a simple script of actions, or into an existing
121 equivalent script that is already part of the shipped kernel.
122
1234. *Append Extra Features:* Extra features are appended to the top-level
124 feature description. These features can come from the
125 :term:`KERNEL_FEATURES`
126 variable in recipes.
127
1285. *Locate, Expand, and Append Each Feature:* Each extra feature is
129 located, expanded and appended to the script as described in step
130 three.
131
1326. *Execute the Script:* The script is executed to produce files
133 ``.scc`` and ``.cfg`` files in appropriate directories of the
134 ``yocto-kernel-cache`` repository. These files are descriptions of
135 all the branches, tags, patches and configurations that need to be
136 applied to the base Git repository to completely create the source
137 (build) branch for the new BSP or feature.
138
1397. *Clone Base Repository:* The base repository is cloned, and the
140 actions listed in the ``yocto-kernel-cache`` directories are applied
141 to the tree.
142
1438. *Perform Cleanup:* The Git repositories are left with the desired
144 branches checked out and any required branching, patching and tagging
145 has been performed.
146
147The kernel tree and cache are ready for developer consumption to be
148locally cloned, configured, and built into a Yocto Project kernel
149specific to some target hardware.
150
151.. note::
152
153 - The generated ``yocto-kernel-cache`` repository adds to the kernel
154 as shipped with the Yocto Project release. Any add-ons and
155 configuration data are applied to the end of an existing branch.
156 The full repository generation that is found in the official Yocto
157 Project kernel repositories at :yocto_git:`/` is the
158 combination of all supported boards and configurations.
159
160 - The technique the Yocto Project team uses is flexible and allows
161 for seamless blending of an immutable history with additional
162 patches specific to a deployment. Any additions to the kernel
163 become an integrated part of the branches.
164
165 - The full kernel tree that you see on :yocto_git:`/` is
166 generated through repeating the above steps for all valid BSPs.
167 The end result is a branched, clean history tree that makes up the
168 kernel for a given release. You can see the script (``kgit-scc``)
169 responsible for this in the
170 :yocto_git:`yocto-kernel-tools </cgit.cgi/yocto-kernel-tools/tree/tools>`
171 repository.
172
173 - The steps used to construct the full kernel tree are the same
174 steps that BitBake uses when it builds a kernel image.
175
176Build Strategy
177==============
178
179Once you have cloned a Yocto Linux kernel repository and the cache
180repository (``yocto-kernel-cache``) onto your development system, you
181can consider the compilation phase of kernel development, which is
182building a kernel image. Some prerequisites exist that are validated by
183the build process before compilation starts:
184
185- The :term:`SRC_URI` points to the
186 kernel Git repository.
187
188- A BSP build branch with Metadata exists in the ``yocto-kernel-cache``
189 repository. The branch is based on the Yocto Linux kernel version and
190 has configurations and features grouped under the
191 ``yocto-kernel-cache/bsp`` directory. For example, features and
192 configurations for the BeagleBone Board assuming a
193 ``linux-yocto_4.12`` kernel reside in the following area of the
194 ``yocto-kernel-cache`` repository: yocto-kernel-cache/bsp/beaglebone
195
196 .. note::
197
198 In the previous example, the "yocto-4.12" branch is checked out in
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500199 the ``yocto-kernel-cache`` repository.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500200
201The OpenEmbedded build system makes sure these conditions exist before
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500202attempting compilation. Other means, however, do exist, such as
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500203bootstrapping a BSP.
204
205Before building a kernel, the build process verifies the tree and
206configures the kernel by processing all of the configuration "fragments"
207specified by feature descriptions in the ``.scc`` files. As the features
208are compiled, associated kernel configuration fragments are noted and
209recorded in the series of directories in their compilation order. The
210fragments are migrated, pre-processed and passed to the Linux Kernel
211Configuration subsystem (``lkc``) as raw input in the form of a
212``.config`` file. The ``lkc`` uses its own internal dependency
213constraints to do the final processing of that information and generates
214the final ``.config`` file that is used during compilation.
215
216Using the board's architecture and other relevant values from the
217board's template, kernel compilation is started and a kernel image is
218produced.
219
220The other thing that you notice once you configure a kernel is that the
221build process generates a build tree that is separate from your kernel's
222local Git source repository tree. This build tree has a name that uses
223the following form, where ``${MACHINE}`` is the metadata name of the
224machine (BSP) and "kernel_type" is one of the Yocto Project supported
225kernel types (e.g. "standard"):
226::
227
228 linux-${MACHINE}-kernel_type-build
229
230The existing support in the ``kernel.org`` tree achieves this default
231functionality.
232
233This behavior means that all the generated files for a particular
234machine or BSP are now in the build tree directory. The files include
235the final ``.config`` file, all the ``.o`` files, the ``.a`` files, and
236so forth. Since each machine or BSP has its own separate
237:term:`Build Directory` in its own separate
238branch of the Git repository, you can easily switch between different
239builds.