blob: 53b73760897ecf1b65f73e1172ba862bdb10b2b2 [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
Andrew Geisslerc926e172021-05-07 16:11:35 -050031``yocto-kernel-cache``, which contains stores of kernel Metadata::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050032
33 $ git clone git://git.yoctoproject.org/linux-yocto-4.12
34 $ git clone git://git.yoctoproject.org/linux-kernel-cache
35
36For more information on
37how to set up a local Git repository of the Yocto Project Linux kernel
38files, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060039":ref:`kernel-dev/common:preparing the build host to work on the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050040section.
41
42Once you have cloned the kernel Git repository and the cache of Metadata
43on your local machine, you can discover the branches that are available
Andrew Geisslerc926e172021-05-07 16:11:35 -050044in the repository using the following Git command::
Andrew Geissler4c19ea12020-10-27 13:52:24 -050045
46 $ git branch -a
47
Andrew Geisslerc9f78652020-09-18 14:11:35 -050048Checking out a branch allows you to work with a particular Yocto Linux
49kernel. For example, the following commands check out the
50"standard/beagleboard" branch of the Yocto Linux kernel repository and
Andrew Geisslerc926e172021-05-07 16:11:35 -050051the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050052
53 $ cd ~/linux-yocto-4.12
54 $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
55 $ cd ~/linux-kernel-cache
56 $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12
57
58.. note::
59
Andrew Geissler4c19ea12020-10-27 13:52:24 -050060 Branches in the ``yocto-kernel-cache`` repository correspond to Yocto Linux
61 kernel versions (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062
63Once you have checked out and switched to appropriate branches, you can
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050064see a snapshot of all the kernel source files used to build that
Andrew Geisslerc9f78652020-09-18 14:11:35 -050065particular Yocto Linux kernel for a particular board.
66
67To see the features and configurations for a particular Yocto Linux
68kernel, you need to examine the ``yocto-kernel-cache`` Git repository.
69As mentioned, branches in the ``yocto-kernel-cache`` repository
70correspond to Yocto Linux kernel versions (e.g. ``yocto-4.12``).
71Branches contain descriptions in the form of ``.scc`` and ``.cfg``
72files.
73
74You should realize, however, that browsing your local
75``yocto-kernel-cache`` repository for feature descriptions and patches
76is not an effective way to determine what is in a particular kernel
77branch. Instead, you should use Git directly to discover the changes in
78a branch. Using Git is an efficient and flexible way to inspect changes
79to the kernel.
80
81.. note::
82
83 Ground up reconstruction of the complete kernel tree is an action
84 only taken by the Yocto Project team during an active development
85 cycle. When you create a clone of the kernel Git repository, you are
86 simply making it efficiently available for building and development.
87
88The following steps describe what happens when the Yocto Project Team
89constructs the Yocto Project kernel source Git repository (or tree)
90found at :yocto_git:`/` given the introduction of a new
91top-level kernel feature or BSP. The following actions effectively
92provide the Metadata and create the tree that includes the new feature,
93patch, or BSP:
94
Andrew Geissler517393d2023-01-13 08:55:19 -060095#. *Pass Feature to the OpenEmbedded Build System:* A top-level kernel
Andrew Geisslerc9f78652020-09-18 14:11:35 -050096 feature is passed to the kernel build subsystem. Normally, this
97 feature is a BSP for a particular kernel type.
98
Andrew Geissler517393d2023-01-13 08:55:19 -060099#. *Locate Feature:* The file that describes the top-level feature is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500100 located by searching these system directories:
101
102 - The in-tree kernel-cache directories, which are located in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600103 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/bsp>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500104 repository organized under the "Yocto Linux Kernel" heading in the
105 :yocto_git:`Yocto Project Source Repositories <>`.
106
Andrew Geissler09036742021-06-25 14:25:14 -0500107 - Areas pointed to by :term:`SRC_URI` statements found in kernel recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108
109 For a typical build, the target of the search is a feature
110 description in an ``.scc`` file whose name follows this format (e.g.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500111 ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112
113 bsp_root_name-kernel_type.scc
114
Andrew Geissler517393d2023-01-13 08:55:19 -0600115#. *Expand Feature:* Once located, the feature description is either
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500116 expanded into a simple script of actions, or into an existing
117 equivalent script that is already part of the shipped kernel.
118
Andrew Geissler517393d2023-01-13 08:55:19 -0600119#. *Append Extra Features:* Extra features are appended to the top-level
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500120 feature description. These features can come from the
121 :term:`KERNEL_FEATURES`
122 variable in recipes.
123
Andrew Geissler517393d2023-01-13 08:55:19 -0600124#. *Locate, Expand, and Append Each Feature:* Each extra feature is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500125 located, expanded and appended to the script as described in step
126 three.
127
Andrew Geissler517393d2023-01-13 08:55:19 -0600128#. *Execute the Script:* The script is executed to produce files
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500129 ``.scc`` and ``.cfg`` files in appropriate directories of the
130 ``yocto-kernel-cache`` repository. These files are descriptions of
131 all the branches, tags, patches and configurations that need to be
132 applied to the base Git repository to completely create the source
133 (build) branch for the new BSP or feature.
134
Andrew Geissler517393d2023-01-13 08:55:19 -0600135#. *Clone Base Repository:* The base repository is cloned, and the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500136 actions listed in the ``yocto-kernel-cache`` directories are applied
137 to the tree.
138
Andrew Geissler517393d2023-01-13 08:55:19 -0600139#. *Perform Cleanup:* The Git repositories are left with the desired
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500140 branches checked out and any required branching, patching and tagging
141 has been performed.
142
143The kernel tree and cache are ready for developer consumption to be
144locally cloned, configured, and built into a Yocto Project kernel
145specific to some target hardware.
146
147.. note::
148
149 - The generated ``yocto-kernel-cache`` repository adds to the kernel
150 as shipped with the Yocto Project release. Any add-ons and
151 configuration data are applied to the end of an existing branch.
152 The full repository generation that is found in the official Yocto
153 Project kernel repositories at :yocto_git:`/` is the
154 combination of all supported boards and configurations.
155
156 - The technique the Yocto Project team uses is flexible and allows
157 for seamless blending of an immutable history with additional
158 patches specific to a deployment. Any additions to the kernel
159 become an integrated part of the branches.
160
161 - The full kernel tree that you see on :yocto_git:`/` is
162 generated through repeating the above steps for all valid BSPs.
163 The end result is a branched, clean history tree that makes up the
164 kernel for a given release. You can see the script (``kgit-scc``)
165 responsible for this in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600166 :yocto_git:`yocto-kernel-tools </yocto-kernel-tools/tree/tools>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500167 repository.
168
169 - The steps used to construct the full kernel tree are the same
170 steps that BitBake uses when it builds a kernel image.
171
172Build Strategy
173==============
174
175Once you have cloned a Yocto Linux kernel repository and the cache
176repository (``yocto-kernel-cache``) onto your development system, you
177can consider the compilation phase of kernel development, which is
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700178building a kernel image. Some prerequisites are validated by
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179the build process before compilation starts:
180
181- The :term:`SRC_URI` points to the
182 kernel Git repository.
183
184- A BSP build branch with Metadata exists in the ``yocto-kernel-cache``
185 repository. The branch is based on the Yocto Linux kernel version and
186 has configurations and features grouped under the
187 ``yocto-kernel-cache/bsp`` directory. For example, features and
188 configurations for the BeagleBone Board assuming a
189 ``linux-yocto_4.12`` kernel reside in the following area of the
190 ``yocto-kernel-cache`` repository: yocto-kernel-cache/bsp/beaglebone
191
192 .. note::
193
194 In the previous example, the "yocto-4.12" branch is checked out in
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500195 the ``yocto-kernel-cache`` repository.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500196
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700197The OpenEmbedded build system makes sure these conditions are satisfied before
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500198attempting compilation. Other means, however, do exist, such as
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500199bootstrapping a BSP.
200
201Before building a kernel, the build process verifies the tree and
202configures the kernel by processing all of the configuration "fragments"
203specified by feature descriptions in the ``.scc`` files. As the features
204are compiled, associated kernel configuration fragments are noted and
205recorded in the series of directories in their compilation order. The
206fragments are migrated, pre-processed and passed to the Linux Kernel
207Configuration subsystem (``lkc``) as raw input in the form of a
208``.config`` file. The ``lkc`` uses its own internal dependency
209constraints to do the final processing of that information and generates
210the final ``.config`` file that is used during compilation.
211
212Using the board's architecture and other relevant values from the
213board's template, kernel compilation is started and a kernel image is
214produced.
215
216The other thing that you notice once you configure a kernel is that the
217build process generates a build tree that is separate from your kernel's
218local Git source repository tree. This build tree has a name that uses
219the following form, where ``${MACHINE}`` is the metadata name of the
220machine (BSP) and "kernel_type" is one of the Yocto Project supported
Andrew Geisslerc926e172021-05-07 16:11:35 -0500221kernel types (e.g. "standard")::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500222
223 linux-${MACHINE}-kernel_type-build
224
225The existing support in the ``kernel.org`` tree achieves this default
226functionality.
227
228This behavior means that all the generated files for a particular
229machine or BSP are now in the build tree directory. The files include
230the final ``.config`` file, all the ``.o`` files, the ``.a`` files, and
231so forth. Since each machine or BSP has its own separate
Patrick Williams2390b1b2022-11-03 13:47:49 -0500232:term:`Build Directory` in its own separate branch of the Git repository,
233you can easily switch between different builds.