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