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
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<appendix id='kernel-dev-maint-appx'>
<title>Kernel Maintenance</title>
<section id='tree-construction'>
<title>Tree Construction</title>
<para>
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
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
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) is built.
</para>
<para>
The existence of this tree allows you to access and clone a
particular Yocto Project Linux kernel repository and use it to
build images based on their configurations and features.
</para>
<para>
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 Git tree.
For example, the following command clones the Yocto Project
baseline Linux kernel that branches off
<filename>linux.org</filename> version 4.12:
<literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/linux-yocto-4.12
</literallayout>
For more information on how to set up a local Git repository of
the Yocto Project Linux kernel files, see the
"<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
section.
</para>
<para>
Once you have cloned the kernel Git repository on your local
machine, you can discover the branches that are avilable in the
repository using the following Git command:
<literallayout class='monospaced'>
$ git branch -a
</literallayout>
Checking out a branch allows you to work with a particular
Yocto Linux kernel.
For example, the following command checks out the
<filename>standard/beagleboard</filename> branch of the
repository:
<literallayout class='monospaced'>
$ cd linux-yocto-4.12
$ git checkout -b my-kernel-4.12 standard/beagleboard
</literallayout>
Once you have checked out and switched to the
<filename>standard/beagleboard</filename> branch,
you can see a snapshot of all the kernel source files used to
used to build that particular Yocto Linux kernel for that
particular board.
</para>
<para>
To see the features and configurations for a particular Yocto
Linux kernel, you need to examine the
<filename>yocto-kernel-cache</filename> Git repository.
Branches in the <filename>yocto-kernel-cache</filename> repository
correspond to Yocto Linux kernel versions (e.g.
<filename>yocto-4.12</filename>).
Branches contain descriptions in the form of
<filename>.scc</filename> and <filename>.cfg</filename> files.
</para>
<para>
You should realize, however, that browsing your local
<filename>yocto-kernel-cache</filename> 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.
</note>
</para>
<para>
The following steps describe what happens when the Yocto Project
Team constructs the Yocto Project kernel source Git repository
(or tree) found at
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
introduction of a new top-level kernel feature or BSP.
These are the actions that effectively create the tree
that includes the new feature, patch or BSP:
<orderedlist>
<listitem><para>
A top-level kernel feature is passed to the kernel build
subsystem.
Normally, this feature is a BSP for a particular kernel
type.
</para></listitem>
<listitem><para>
The file that describes the top-level feature is located
by searching these system directories:
<itemizedlist>
<listitem><para>
The in-tree kernel-cache directories, which are
located in
<filename>yocto-kernel-cache/cfg/kernel-cache</filename>
</para></listitem>
<listitem><para>
Areas pointed to by <filename>SRC_URI</filename>
statements found in recipes
</para></listitem>
</itemizedlist>
For a typical build, the target of the search is a
feature description in an <filename>.scc</filename> file
whose name follows this format:
I AM HERE
<literallayout class='monospaced'>
<replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
</literallayout>
</para></listitem>
<listitem><para>Once located, the feature description is either compiled into a simple script
of actions, or into an existing equivalent script that is already part of the
shipped kernel.</para></listitem>
<listitem><para>Extra features are appended to the top-level feature description.
These features can come from the
<ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
variable in recipes.</para></listitem>
<listitem><para>Each extra feature is located, compiled and appended to the script
as described in step three.</para></listitem>
<listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
directories.
These directories 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.</para></listitem>
<listitem><para>The base repository is cloned, and the actions
listed in the <filename>meta-*</filename> directories are applied to the
tree.</para></listitem>
<listitem><para>The Git repository is left with the desired branch checked out and any
required branching, patching and tagging has been performed.</para></listitem>
</orderedlist>
</para>
<para>
The kernel tree is now ready for developer consumption to be locally cloned,
configured, and built into a Yocto Project kernel specific to some target hardware.
<note><para>The generated <filename>meta-*</filename> directories add 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
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
is the combination of all supported boards and configurations.</para>
<para>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.</para>
</note>
</para>
</section>
<section id='build-strategy'>
<title>Build Strategy</title>
<para>
Once a local Git repository of the Yocto Project kernel exists on a development system,
you can consider the compilation phase of kernel development - building a kernel image.
Some prerequisites exist that are validated by the build process before compilation
starts:
</para>
<itemizedlist>
<listitem><para>The
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
to the kernel Git repository.</para></listitem>
<listitem><para>A BSP build branch exists.
This branch has the following form:
<literallayout class='monospaced'>
<replaceable>kernel_type</replaceable>/<replaceable>bsp_name</replaceable>
</literallayout></para></listitem>
</itemizedlist>
<para>
The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
Other means, however, do exist, such as as bootstrapping a BSP.
</para>
<para>
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 <filename>.scc</filename>
files.
As the features are compiled, associated kernel configuration fragments are noted
and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
The fragments are migrated, pre-processed and passed to the Linux Kernel
Configuration subsystem (<filename>lkc</filename>) as raw input in the form
of a <filename>.config</filename> file.
The <filename>lkc</filename> uses its own internal dependency constraints to do the final
processing of that information and generates the final <filename>.config</filename> file
that is used during compilation.
</para>
<para>
Using the board's architecture and other relevant values from the board's template,
kernel compilation is started and a kernel image is produced.
</para>
<para>
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
<filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
of the Yocto Project supported kernel types (e.g. "standard"):
<literallayout class='monospaced'>
linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build
</literallayout>
</para>
<para>
The existing support in the <filename>kernel.org</filename> tree achieves this
default functionality.
</para>
<para>
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 <filename>.config</filename> file, all the <filename>.o</filename>
files, the <filename>.a</filename> files, and so forth.
Since each machine or BSP has its own separate
<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
in its own separate branch
of the Git repository, you can easily switch between different builds.
</para>
</section>
</appendix>
<!--
vim: expandtab tw=80 ts=4
-->
|
