1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 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 $ 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 39":ref:`kernel-dev/common:preparing the build host to work on the kernel`" 40section. 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 44in the repository using the following Git command:: 45 46 $ git branch -a 47 48Checking 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 51the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository:: 52 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 60 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). 62 63Once you have checked out and switched to appropriate branches, you can 64see a snapshot of all the kernel source files used to build that 65particular 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 95#. *Pass Feature to the OpenEmbedded Build System:* A top-level kernel 96 feature is passed to the kernel build subsystem. Normally, this 97 feature is a BSP for a particular kernel type. 98 99#. *Locate Feature:* The file that describes the top-level feature is 100 located by searching these system directories: 101 102 - The in-tree kernel-cache directories, which are located in the 103 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/bsp>` 104 repository organized under the "Yocto Linux Kernel" heading in the 105 :yocto_git:`Yocto Project Source Repositories <>`. 106 107 - Areas pointed to by :term:`SRC_URI` statements found in kernel recipes. 108 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. 111 ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``):: 112 113 bsp_root_name-kernel_type.scc 114 115#. *Expand Feature:* Once located, the feature description is either 116 expanded into a simple script of actions, or into an existing 117 equivalent script that is already part of the shipped kernel. 118 119#. *Append Extra Features:* Extra features are appended to the top-level 120 feature description. These features can come from the 121 :term:`KERNEL_FEATURES` 122 variable in recipes. 123 124#. *Locate, Expand, and Append Each Feature:* Each extra feature is 125 located, expanded and appended to the script as described in step 126 three. 127 128#. *Execute the Script:* The script is executed to produce files 129 ``.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 135#. *Clone Base Repository:* The base repository is cloned, and the 136 actions listed in the ``yocto-kernel-cache`` directories are applied 137 to the tree. 138 139#. *Perform Cleanup:* The Git repositories are left with the desired 140 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 166 :yocto_git:`yocto-kernel-tools </yocto-kernel-tools/tree/tools>` 167 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 178building a kernel image. Some prerequisites are validated by 179the 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 195 the ``yocto-kernel-cache`` repository. 196 197The OpenEmbedded build system makes sure these conditions are satisfied before 198attempting compilation. Other means, however, do exist, such as 199bootstrapping 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 221kernel types (e.g. "standard"):: 222 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 232:term:`Build Directory` in its own separate branch of the Git repository, 233you can easily switch between different builds. 234