documentation/kernel-dev/maint-appx.rst

1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
4 Kernel Maintenance
10 This section describes construction of the Yocto Project kernel source
12 Linux kernel repositories. These kernel repositories are found under the
13 heading "Yocto Linux Kernel" at :yocto_git:`/` and
16 for every BSP and feature in the product. Those feature descriptions
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.
23 particular Yocto Project Linux kernel repository and use it to build
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
30 kernel that branches off ``linux.org`` version 4.12 and the
31 ``yocto-kernel-cache``, which contains stores of kernel Metadata::
33    $ git clone git://git.yoctoproject.org/linux-yocto-4.12
34    $ git clone git://git.yoctoproject.org/linux-kernel-cache
37 how to set up a local Git repository of the Yocto Project Linux kernel
39 ":ref:`kernel-dev/common:preparing the build host to work on the kernel`"
42 Once you have cloned the kernel Git repository and the cache of Metadata
44 in the repository using the following Git command::
46    $ git branch -a
49 kernel. For example, the following commands check out the
50 "standard/beagleboard" branch of the Yocto Linux kernel repository and
51 the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository::
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
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).
64 see a snapshot of all the kernel source files used to build that
65 particular Yocto Linux kernel for a particular board.
68 kernel, you need to examine the ``yocto-kernel-cache`` Git repository.
69 As mentioned, branches in the ``yocto-kernel-cache`` repository
70 correspond to Yocto Linux kernel versions (e.g. ``yocto-4.12``).
71 Branches contain descriptions in the form of ``.scc`` and ``.cfg``
75 ``yocto-kernel-cache`` repository for feature descriptions and patches
76 is not an effective way to determine what is in a particular kernel
77 branch. Instead, you should use Git directly to discover the changes in
79 to the kernel.
83    Ground up reconstruction of the complete kernel tree is an action
85    cycle. When you create a clone of the kernel Git repository, you are
89 constructs the Yocto Project kernel source Git repository (or tree)
91 top-level kernel feature or BSP. The following actions effectively
95 1. *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.
99 2. *Locate Feature:* The file that describes the top-level feature is
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
107    -  Areas pointed to by :term:`SRC_URI` statements found in kernel recipes.
110    description in an ``.scc`` file whose name follows this format (e.g.
111    ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``)::
113       bsp_root_name-kernel_type.scc
117    equivalent script that is already part of the shipped kernel.
119 4. *Append Extra Features:* Extra features are appended to the top-level
122    variable in recipes.
125    located, expanded and appended to the script as described in step
129    ``.scc`` and ``.cfg`` files in appropriate directories of the
130    ``yocto-kernel-cache`` repository. These files are descriptions of
136    actions listed in the ``yocto-kernel-cache`` directories are applied
143 The kernel tree and cache are ready for developer consumption to be
144 locally cloned, configured, and built into a Yocto Project kernel
149    -  The generated ``yocto-kernel-cache`` repository adds to the kernel
150       as shipped with the Yocto Project release. Any add-ons and
152       The full repository generation that is found in the official Yocto
153       Project kernel repositories at :yocto_git:`/` is the
156    -  The technique the Yocto Project team uses is flexible and allows
158       patches specific to a deployment. Any additions to the kernel
161    -  The full kernel tree that you see on :yocto_git:`/` is
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>`
169    -  The steps used to construct the full kernel tree are the same
170       steps that BitBake uses when it builds a kernel image.
175 Once you have cloned a Yocto Linux kernel repository and the cache
176 repository (``yocto-kernel-cache``) onto your development system, you
177 can consider the compilation phase of kernel development, which is
178 building a kernel image. Some prerequisites are validated by
181 -  The :term:`SRC_URI` points to the
182    kernel Git repository.
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
187    ``yocto-kernel-cache/bsp`` directory. For example, features and
189    ``linux-yocto_4.12`` kernel reside in the following area of the
190    ``yocto-kernel-cache`` repository: yocto-kernel-cache/bsp/beaglebone
194       In the previous example, the "yocto-4.12" branch is checked out in
195       the ``yocto-kernel-cache`` repository.
201 Before building a kernel, the build process verifies the tree and
202 configures the kernel by processing all of the configuration "fragments"
203 specified by feature descriptions in the ``.scc`` files. As the features
204 are compiled, associated kernel configuration fragments are noted and
205 recorded in the series of directories in their compilation order. The
206 fragments are migrated, pre-processed and passed to the Linux Kernel
207 Configuration subsystem (``lkc``) as raw input in the form of a
213 board's template, kernel compilation is started and a kernel image is
216 The other thing that you notice once you configure a kernel is that the
217 build process generates a build tree that is separate from your kernel's
221 kernel types (e.g. "standard")::
223    linux-${MACHINE}-kernel_type-build
225 The existing support in the ``kernel.org`` tree achieves this default
229 machine or BSP are now in the build tree directory. The files include
232 :term:`Build Directory` in its own separate