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