diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-maint-appx.xml')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-maint-appx.xml | 357 |
1 files changed, 0 insertions, 357 deletions
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml deleted file mode 100644 index 3d9c7c66fd..0000000000 --- a/documentation/kernel-dev/kernel-dev-maint-appx.xml +++ /dev/null | |||
@@ -1,357 +0,0 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
5 | |||
6 | <appendix id='kernel-dev-maint-appx'> | ||
7 | <title>Kernel Maintenance</title> | ||
8 | |||
9 | <section id='tree-construction'> | ||
10 | <title>Tree Construction</title> | ||
11 | |||
12 | <para> | ||
13 | This section describes construction of the Yocto Project kernel | ||
14 | source repositories as accomplished by the Yocto Project team to | ||
15 | create Yocto Linux kernel repositories. | ||
16 | These kernel repositories are found under the heading "Yocto Linux | ||
17 | Kernel" at | ||
18 | <ulink url='&YOCTO_GIT_URL;'>&YOCTO_GIT_URL;</ulink> | ||
19 | and are shipped as part of a Yocto Project release. | ||
20 | The team creates these repositories by compiling and executing the | ||
21 | set of feature descriptions for every BSP and feature in the | ||
22 | product. | ||
23 | Those feature descriptions list all necessary patches, | ||
24 | configurations, branches, tags, and feature divisions found in a | ||
25 | Yocto Linux kernel. | ||
26 | Thus, the Yocto Project Linux kernel repository (or tree) and | ||
27 | accompanying Metadata in the | ||
28 | <filename>yocto-kernel-cache</filename> are built. | ||
29 | </para> | ||
30 | |||
31 | <para> | ||
32 | The existence of these repositories allow you to access and clone a | ||
33 | particular Yocto Project Linux kernel repository and use it to | ||
34 | build images based on their configurations and features. | ||
35 | </para> | ||
36 | |||
37 | <para> | ||
38 | You can find the files used to describe all the valid features and | ||
39 | BSPs in the Yocto Project Linux kernel in any clone of the Yocto | ||
40 | Project Linux kernel source repository and | ||
41 | <filename>yocto-kernel-cache</filename> Git trees. | ||
42 | For example, the following commands clone the Yocto Project | ||
43 | baseline Linux kernel that branches off | ||
44 | <filename>linux.org</filename> version 4.12 and the | ||
45 | <filename>yocto-kernel-cache</filename>, which contains stores of | ||
46 | kernel Metadata: | ||
47 | <literallayout class='monospaced'> | ||
48 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 | ||
49 | $ git clone git://git.yoctoproject.org/linux-kernel-cache | ||
50 | </literallayout> | ||
51 | For more information on how to set up a local Git repository of | ||
52 | the Yocto Project Linux kernel files, see the | ||
53 | "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>" | ||
54 | section. | ||
55 | </para> | ||
56 | |||
57 | <para> | ||
58 | Once you have cloned the kernel Git repository and the | ||
59 | cache of Metadata on your local machine, you can discover the | ||
60 | branches that are available in the repository using the following | ||
61 | Git command: | ||
62 | <literallayout class='monospaced'> | ||
63 | $ git branch -a | ||
64 | </literallayout> | ||
65 | Checking out a branch allows you to work with a particular | ||
66 | Yocto Linux kernel. | ||
67 | For example, the following commands check out the | ||
68 | "standard/beagleboard" branch of the Yocto Linux kernel repository | ||
69 | and the "yocto-4.12" branch of the | ||
70 | <filename>yocto-kernel-cache</filename> repository: | ||
71 | <literallayout class='monospaced'> | ||
72 | $ cd ~/linux-yocto-4.12 | ||
73 | $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard | ||
74 | $ cd ~/linux-kernel-cache | ||
75 | $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12 | ||
76 | </literallayout> | ||
77 | <note> | ||
78 | Branches in the <filename>yocto-kernel-cache</filename> | ||
79 | repository correspond to Yocto Linux kernel versions | ||
80 | (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth). | ||
81 | </note> | ||
82 | Once you have checked out and switched to appropriate branches, | ||
83 | you can see a snapshot of all the kernel source files used to | ||
84 | used to build that particular Yocto Linux kernel for a | ||
85 | particular board. | ||
86 | </para> | ||
87 | |||
88 | <para> | ||
89 | To see the features and configurations for a particular Yocto | ||
90 | Linux kernel, you need to examine the | ||
91 | <filename>yocto-kernel-cache</filename> Git repository. | ||
92 | As mentioned, branches in the | ||
93 | <filename>yocto-kernel-cache</filename> repository correspond to | ||
94 | Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>). | ||
95 | Branches contain descriptions in the form of | ||
96 | <filename>.scc</filename> and <filename>.cfg</filename> files. | ||
97 | </para> | ||
98 | |||
99 | <para> | ||
100 | You should realize, however, that browsing your local | ||
101 | <filename>yocto-kernel-cache</filename> repository for feature | ||
102 | descriptions and patches is not an effective way to determine what | ||
103 | is in a particular kernel branch. | ||
104 | Instead, you should use Git directly to discover the changes in | ||
105 | a branch. | ||
106 | Using Git is an efficient and flexible way to inspect changes to | ||
107 | the kernel. | ||
108 | <note> | ||
109 | Ground up reconstruction of the complete kernel tree is an | ||
110 | action only taken by the Yocto Project team during an active | ||
111 | development cycle. | ||
112 | When you create a clone of the kernel Git repository, you are | ||
113 | simply making it efficiently available for building and | ||
114 | development. | ||
115 | </note> | ||
116 | </para> | ||
117 | |||
118 | <para> | ||
119 | The following steps describe what happens when the Yocto Project | ||
120 | Team constructs the Yocto Project kernel source Git repository | ||
121 | (or tree) found at | ||
122 | <ulink url='&YOCTO_GIT_URL;'></ulink> given the | ||
123 | introduction of a new top-level kernel feature or BSP. | ||
124 | The following actions effectively provide the Metadata | ||
125 | and create the tree that includes the new feature, patch, or BSP: | ||
126 | <orderedlist> | ||
127 | <listitem><para> | ||
128 | <emphasis>Pass Feature to the OpenEmbedded Build System:</emphasis> | ||
129 | A top-level kernel feature is passed to the kernel build | ||
130 | subsystem. | ||
131 | Normally, this feature is a BSP for a particular kernel | ||
132 | type. | ||
133 | </para></listitem> | ||
134 | <listitem><para> | ||
135 | <emphasis>Locate Feature:</emphasis> | ||
136 | The file that describes the top-level feature is located | ||
137 | by searching these system directories: | ||
138 | <itemizedlist> | ||
139 | <listitem><para> | ||
140 | The in-tree kernel-cache directories, which are | ||
141 | located in the | ||
142 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink> | ||
143 | repository organized under the "Yocto Linux Kernel" | ||
144 | heading in the | ||
145 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. | ||
146 | </para></listitem> | ||
147 | <listitem><para> | ||
148 | Areas pointed to by <filename>SRC_URI</filename> | ||
149 | statements found in kernel recipes | ||
150 | </para></listitem> | ||
151 | </itemizedlist> | ||
152 | For a typical build, the target of the search is a | ||
153 | feature description in an <filename>.scc</filename> file | ||
154 | whose name follows this format (e.g. | ||
155 | <filename>beaglebone-standard.scc</filename> and | ||
156 | <filename>beaglebone-preempt-rt.scc</filename>): | ||
157 | <literallayout class='monospaced'> | ||
158 | <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc | ||
159 | </literallayout> | ||
160 | </para></listitem> | ||
161 | <listitem><para> | ||
162 | <emphasis>Expand Feature:</emphasis> | ||
163 | Once located, the feature description is either expanded | ||
164 | into a simple script of actions, or into an existing | ||
165 | equivalent script that is already part of the shipped | ||
166 | kernel. | ||
167 | </para></listitem> | ||
168 | <listitem><para> | ||
169 | <emphasis>Append Extra Features:</emphasis> | ||
170 | Extra features are appended to the top-level feature | ||
171 | description. | ||
172 | These features can come from the | ||
173 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> | ||
174 | variable in recipes. | ||
175 | </para></listitem> | ||
176 | <listitem><para> | ||
177 | <emphasis>Locate, Expand, and Append Each Feature:</emphasis> | ||
178 | Each extra feature is located, expanded and appended to | ||
179 | the script as described in step three. | ||
180 | </para></listitem> | ||
181 | <listitem><para> | ||
182 | <emphasis>Execute the Script:</emphasis> | ||
183 | The script is executed to produce files | ||
184 | <filename>.scc</filename> and <filename>.cfg</filename> | ||
185 | files in appropriate directories of the | ||
186 | <filename>yocto-kernel-cache</filename> repository. | ||
187 | These files are descriptions of all the branches, tags, | ||
188 | patches and configurations that need to be applied to the | ||
189 | base Git repository to completely create the | ||
190 | source (build) branch for the new BSP or feature. | ||
191 | </para></listitem> | ||
192 | <listitem><para> | ||
193 | <emphasis>Clone Base Repository:</emphasis> | ||
194 | The base repository is cloned, and the actions | ||
195 | listed in the <filename>yocto-kernel-cache</filename> | ||
196 | directories are applied to the tree. | ||
197 | </para></listitem> | ||
198 | <listitem><para> | ||
199 | <emphasis>Perform Cleanup:</emphasis> | ||
200 | The Git repositories are left with the desired branches | ||
201 | checked out and any required branching, patching and | ||
202 | tagging has been performed. | ||
203 | </para></listitem> | ||
204 | </orderedlist> | ||
205 | </para> | ||
206 | |||
207 | <para> | ||
208 | The kernel tree and cache are ready for developer consumption to | ||
209 | be locally cloned, configured, and built into a Yocto Project | ||
210 | kernel specific to some target hardware. | ||
211 | <note><title>Notes</title> | ||
212 | <itemizedlist> | ||
213 | <listitem><para> | ||
214 | The generated <filename>yocto-kernel-cache</filename> | ||
215 | repository adds to the kernel as shipped with the Yocto | ||
216 | Project release. | ||
217 | Any add-ons and configuration data are applied to the | ||
218 | end of an existing branch. | ||
219 | The full repository generation that is found in the | ||
220 | official Yocto Project kernel repositories at | ||
221 | <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink> | ||
222 | is the combination of all supported boards and | ||
223 | configurations. | ||
224 | </para></listitem> | ||
225 | <listitem><para> | ||
226 | The technique the Yocto Project team uses is flexible | ||
227 | and allows for seamless blending of an immutable | ||
228 | history with additional patches specific to a | ||
229 | deployment. | ||
230 | Any additions to the kernel become an integrated part | ||
231 | of the branches. | ||
232 | </para></listitem> | ||
233 | <listitem><para> | ||
234 | The full kernel tree that you see on | ||
235 | <ulink url='&YOCTO_GIT_URL;'></ulink> is | ||
236 | generated through repeating the above steps for all | ||
237 | valid BSPs. | ||
238 | The end result is a branched, clean history tree that | ||
239 | makes up the kernel for a given release. | ||
240 | You can see the script (<filename>kgit-scc</filename>) | ||
241 | responsible for this in the | ||
242 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools'><filename>yocto-kernel-tools</filename></ulink> | ||
243 | repository. | ||
244 | </para></listitem> | ||
245 | <listitem><para> | ||
246 | The steps used to construct the full kernel tree are | ||
247 | the same steps that BitBake uses when it builds a | ||
248 | kernel image. | ||
249 | </para></listitem> | ||
250 | </itemizedlist> | ||
251 | </note> | ||
252 | </para> | ||
253 | </section> | ||
254 | |||
255 | <section id='build-strategy'> | ||
256 | <title>Build Strategy</title> | ||
257 | |||
258 | <para> | ||
259 | Once you have cloned a Yocto Linux kernel repository and the | ||
260 | cache repository (<filename>yocto-kernel-cache</filename>) onto | ||
261 | your development system, you can consider the compilation phase | ||
262 | of kernel development, which is building a kernel image. | ||
263 | Some prerequisites exist that are validated by the build process | ||
264 | before compilation starts: | ||
265 | </para> | ||
266 | |||
267 | <itemizedlist> | ||
268 | <listitem><para> | ||
269 | The | ||
270 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
271 | points to the kernel Git repository. | ||
272 | </para></listitem> | ||
273 | <listitem><para> | ||
274 | A BSP build branch with Metadata exists in the | ||
275 | <filename>yocto-kernel-cache</filename> repository. | ||
276 | The branch is based on the Yocto Linux kernel version and | ||
277 | has configurations and features grouped under the | ||
278 | <filename>yocto-kernel-cache/bsp</filename> directory. | ||
279 | For example, features and configurations for the | ||
280 | BeagleBone Board assuming a | ||
281 | <filename>linux-yocto_4.12</filename> kernel reside in the | ||
282 | following area of the <filename>yocto-kernel-cache</filename> | ||
283 | repository: | ||
284 | <literallayout class='monospaced'> | ||
285 | yocto-kernel-cache/bsp/beaglebone | ||
286 | </literallayout> | ||
287 | <note> | ||
288 | In the previous example, the "yocto-4.12" branch is | ||
289 | checked out in the <filename>yocto-kernel-cache</filename> | ||
290 | repository. | ||
291 | </note> | ||
292 | </para></listitem> | ||
293 | </itemizedlist> | ||
294 | |||
295 | <para> | ||
296 | The OpenEmbedded build system makes sure these conditions exist | ||
297 | before attempting compilation. | ||
298 | Other means, however, do exist, such as as bootstrapping a BSP. | ||
299 | </para> | ||
300 | |||
301 | <para> | ||
302 | Before building a kernel, the build process verifies the tree | ||
303 | and configures the kernel by processing all of the | ||
304 | configuration "fragments" specified by feature descriptions | ||
305 | in the <filename>.scc</filename> files. | ||
306 | As the features are compiled, associated kernel configuration | ||
307 | fragments are noted and recorded in the series of directories | ||
308 | in their compilation order. | ||
309 | The fragments are migrated, pre-processed and passed to the | ||
310 | Linux Kernel Configuration subsystem (<filename>lkc</filename>) as | ||
311 | raw input in the form of a <filename>.config</filename> file. | ||
312 | The <filename>lkc</filename> uses its own internal dependency | ||
313 | constraints to do the final processing of that information and | ||
314 | generates the final <filename>.config</filename> file that is used | ||
315 | during compilation. | ||
316 | </para> | ||
317 | |||
318 | <para> | ||
319 | Using the board's architecture and other relevant values from | ||
320 | the board's template, kernel compilation is started and a kernel | ||
321 | image is produced. | ||
322 | </para> | ||
323 | |||
324 | <para> | ||
325 | The other thing that you notice once you configure a kernel is that | ||
326 | the build process generates a build tree that is separate from | ||
327 | your kernel's local Git source repository tree. | ||
328 | This build tree has a name that uses the following form, where | ||
329 | <filename>${MACHINE}</filename> is the metadata name of the | ||
330 | machine (BSP) and "kernel_type" is one of the Yocto Project | ||
331 | supported kernel types (e.g. "standard"): | ||
332 | <literallayout class='monospaced'> | ||
333 | linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build | ||
334 | </literallayout> | ||
335 | </para> | ||
336 | |||
337 | <para> | ||
338 | The existing support in the <filename>kernel.org</filename> tree | ||
339 | achieves this default functionality. | ||
340 | </para> | ||
341 | |||
342 | <para> | ||
343 | This behavior means that all the generated files for a particular | ||
344 | machine or BSP are now in the build tree directory. | ||
345 | The files include the final <filename>.config</filename> file, | ||
346 | all the <filename>.o</filename> files, the <filename>.a</filename> | ||
347 | files, and so forth. | ||
348 | Since each machine or BSP has its own separate | ||
349 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
350 | in its own separate branch of the Git repository, you can easily | ||
351 | switch between different builds. | ||
352 | </para> | ||
353 | </section> | ||
354 | </appendix> | ||
355 | <!-- | ||
356 | vim: expandtab tw=80 ts=4 | ||
357 | --> | ||