diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-concepts-appx.xml')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-concepts-appx.xml | 622 |
1 files changed, 0 insertions, 622 deletions
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml deleted file mode 100644 index bf0c525caf..0000000000 --- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml +++ /dev/null | |||
@@ -1,622 +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-concepts-appx'> | ||
7 | <title>Advanced Kernel Concepts</title> | ||
8 | |||
9 | <section id='kernel-big-picture'> | ||
10 | <title>Yocto Project Kernel Development and Maintenance</title> | ||
11 | |||
12 | <para> | ||
13 | Kernels available through the Yocto Project (Yocto Linux kernels), | ||
14 | like other kernels, are based off the Linux kernel releases from | ||
15 | <ulink url='http://www.kernel.org'></ulink>. | ||
16 | At the beginning of a major Linux kernel development cycle, the | ||
17 | Yocto Project team chooses a Linux kernel based on factors such as | ||
18 | release timing, the anticipated release timing of final upstream | ||
19 | <filename>kernel.org</filename> versions, and Yocto Project | ||
20 | feature requirements. | ||
21 | Typically, the Linux kernel chosen is in the final stages of | ||
22 | development by the Linux community. | ||
23 | In other words, the Linux kernel is in the release candidate | ||
24 | or "rc" phase and has yet to reach final release. | ||
25 | But, by being in the final stages of external development, the | ||
26 | team knows that the <filename>kernel.org</filename> final release | ||
27 | will clearly be within the early stages of the Yocto Project | ||
28 | development window. | ||
29 | </para> | ||
30 | |||
31 | <para> | ||
32 | This balance allows the Yocto Project team to deliver the most | ||
33 | up-to-date Yocto Linux kernel possible, while still ensuring that | ||
34 | the team has a stable official release for the baseline Linux | ||
35 | kernel version. | ||
36 | </para> | ||
37 | |||
38 | <para> | ||
39 | As implied earlier, the ultimate source for Yocto Linux kernels | ||
40 | are released kernels from <filename>kernel.org</filename>. | ||
41 | In addition to a foundational kernel from | ||
42 | <filename>kernel.org</filename>, the available Yocto Linux kernels | ||
43 | contain a mix of important new mainline developments, non-mainline | ||
44 | developments (when no alternative exists), Board Support Package | ||
45 | (BSP) developments, and custom features. | ||
46 | These additions result in a commercially released Yocto | ||
47 | Project Linux kernel that caters to specific embedded designer | ||
48 | needs for targeted hardware. | ||
49 | </para> | ||
50 | |||
51 | <para> | ||
52 | You can find a web interface to the Yocto Linux kernels in the | ||
53 | <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> | ||
54 | at | ||
55 | <ulink url='&YOCTO_GIT_URL;'></ulink>. | ||
56 | If you look at the interface, you will see to the left a | ||
57 | grouping of Git repositories titled "Yocto Linux Kernel". | ||
58 | Within this group, you will find several Linux Yocto kernels | ||
59 | developed and included with Yocto Project releases: | ||
60 | <itemizedlist> | ||
61 | <listitem><para> | ||
62 | <emphasis><filename>linux-yocto-4.1</filename>:</emphasis> | ||
63 | The stable Yocto Project kernel to use with the Yocto | ||
64 | Project Release 2.0. | ||
65 | This kernel is based on the Linux 4.1 released kernel. | ||
66 | </para></listitem> | ||
67 | <listitem><para> | ||
68 | <emphasis><filename>linux-yocto-4.4</filename>:</emphasis> | ||
69 | The stable Yocto Project kernel to use with the Yocto | ||
70 | Project Release 2.1. | ||
71 | This kernel is based on the Linux 4.4 released kernel. | ||
72 | </para></listitem> | ||
73 | <listitem><para> | ||
74 | <emphasis><filename>linux-yocto-4.6</filename>:</emphasis> | ||
75 | A temporary kernel that is not tied to any Yocto Project | ||
76 | release. | ||
77 | </para></listitem> | ||
78 | <listitem><para> | ||
79 | <emphasis><filename>linux-yocto-4.8</filename>:</emphasis> | ||
80 | The stable yocto Project kernel to use with the Yocto | ||
81 | Project Release 2.2. | ||
82 | </para></listitem> | ||
83 | <listitem><para> | ||
84 | <emphasis><filename>linux-yocto-4.9</filename>:</emphasis> | ||
85 | The stable Yocto Project kernel to use with the Yocto | ||
86 | Project Release 2.3. | ||
87 | This kernel is based on the Linux 4.9 released kernel. | ||
88 | </para></listitem> | ||
89 | <listitem><para> | ||
90 | <emphasis><filename>linux-yocto-4.10</filename>:</emphasis> | ||
91 | The default stable Yocto Project kernel to use with the | ||
92 | Yocto Project Release 2.3. | ||
93 | This kernel is based on the Linux 4.10 released kernel. | ||
94 | </para></listitem> | ||
95 | <listitem><para> | ||
96 | <emphasis><filename>linux-yocto-4.12</filename>:</emphasis> | ||
97 | The default stable Yocto Project kernel to use with the | ||
98 | Yocto Project Release 2.4. | ||
99 | This kernel is based on the Linux 4.12 released kernel. | ||
100 | </para></listitem> | ||
101 | <listitem><para> | ||
102 | <emphasis><filename>yocto-kernel-cache</filename>:</emphasis> | ||
103 | The <filename>linux-yocto-cache</filename> contains | ||
104 | patches and configurations for the linux-yocto kernel | ||
105 | tree. | ||
106 | This repository is useful when working on the linux-yocto | ||
107 | kernel. | ||
108 | For more information on this "Advanced Kernel Metadata", | ||
109 | see the | ||
110 | "<link linkend='kernel-dev-advanced'>Working With Advanced Metadata (<filename>yocto-kernel-cache</filename>)</link>" | ||
111 | Chapter. | ||
112 | </para></listitem> | ||
113 | <listitem><para> | ||
114 | <emphasis><filename>linux-yocto-dev</filename>:</emphasis> | ||
115 | A development kernel based on the latest upstream release | ||
116 | candidate available. | ||
117 | </para></listitem> | ||
118 | </itemizedlist> | ||
119 | <note><title>Notes</title> | ||
120 | Long Term Support Initiative (LTSI) for Yocto Linux | ||
121 | kernels is as follows: | ||
122 | <itemizedlist> | ||
123 | <listitem><para> | ||
124 | For Yocto Project releases 1.7, 1.8, and 2.0, | ||
125 | the LTSI kernel is | ||
126 | <filename>linux-yocto-3.14</filename>. | ||
127 | </para></listitem> | ||
128 | <listitem><para> | ||
129 | For Yocto Project releases 2.1, 2.2, and 2.3, | ||
130 | the LTSI kernel is <filename>linux-yocto-4.1</filename>. | ||
131 | </para></listitem> | ||
132 | <listitem><para> | ||
133 | For Yocto Project release 2.4, the LTSI kernel is | ||
134 | <filename>linux-yocto-4.9</filename> | ||
135 | </para></listitem> | ||
136 | <listitem><para> | ||
137 | <filename>linux-yocto-4.4</filename> is an LTS | ||
138 | kernel. | ||
139 | </para></listitem> | ||
140 | </itemizedlist> | ||
141 | </note> | ||
142 | </para> | ||
143 | |||
144 | <para> | ||
145 | Once a Yocto Linux kernel is officially released, the Yocto | ||
146 | Project team goes into their next development cycle, or upward | ||
147 | revision (uprev) cycle, while still continuing maintenance on the | ||
148 | released kernel. | ||
149 | It is important to note that the most sustainable and stable way | ||
150 | to include feature development upstream is through a kernel uprev | ||
151 | process. | ||
152 | Back-porting hundreds of individual fixes and minor features from | ||
153 | various kernel versions is not sustainable and can easily | ||
154 | compromise quality. | ||
155 | </para> | ||
156 | |||
157 | <para> | ||
158 | During the uprev cycle, the Yocto Project team uses an ongoing | ||
159 | analysis of Linux kernel development, BSP support, and release | ||
160 | timing to select the best possible <filename>kernel.org</filename> | ||
161 | Linux kernel version on which to base subsequent Yocto Linux | ||
162 | kernel development. | ||
163 | The team continually monitors Linux community kernel development | ||
164 | to look for significant features of interest. | ||
165 | The team does consider back-porting large features if they have a | ||
166 | significant advantage. | ||
167 | User or community demand can also trigger a back-port or creation | ||
168 | of new functionality in the Yocto Project baseline kernel during | ||
169 | the uprev cycle. | ||
170 | </para> | ||
171 | |||
172 | <para> | ||
173 | Generally speaking, every new Linux kernel both adds features and | ||
174 | introduces new bugs. | ||
175 | These consequences are the basic properties of upstream | ||
176 | Linux kernel development and are managed by the Yocto Project | ||
177 | team's Yocto Linux kernel development strategy. | ||
178 | It is the Yocto Project team's policy to not back-port minor | ||
179 | features to the released Yocto Linux kernel. | ||
180 | They only consider back-porting significant technological | ||
181 | jumps ‐ and, that is done after a complete gap analysis. | ||
182 | The reason for this policy is that back-porting any small to | ||
183 | medium sized change from an evolving Linux kernel can easily | ||
184 | create mismatches, incompatibilities and very subtle errors. | ||
185 | </para> | ||
186 | |||
187 | <para> | ||
188 | The policies described in this section result in both a stable | ||
189 | and a cutting edge Yocto Linux kernel that mixes forward ports of | ||
190 | existing Linux kernel features and significant and critical new | ||
191 | functionality. | ||
192 | Forward porting Linux kernel functionality into the Yocto Linux | ||
193 | kernels available through the Yocto Project can be thought of as | ||
194 | a "micro uprev." | ||
195 | The many "micro uprevs" produce a Yocto Linux kernel version with | ||
196 | a mix of important new mainline, non-mainline, BSP developments | ||
197 | and feature integrations. | ||
198 | This Yocto Linux kernel gives insight into new features and | ||
199 | allows focused amounts of testing to be done on the kernel, | ||
200 | which prevents surprises when selecting the next major uprev. | ||
201 | The quality of these cutting edge Yocto Linux kernels is evolving | ||
202 | and the kernels are used in leading edge feature and BSP | ||
203 | development. | ||
204 | </para> | ||
205 | </section> | ||
206 | |||
207 | <section id='yocto-linux-kernel-architecture-and-branching-strategies'> | ||
208 | <title>Yocto Linux Kernel Architecture and Branching Strategies</title> | ||
209 | |||
210 | <para> | ||
211 | As mentioned earlier, a key goal of the Yocto Project is | ||
212 | to present the developer with a kernel that has a clear and | ||
213 | continuous history that is visible to the user. | ||
214 | The architecture and mechanisms, in particular the branching | ||
215 | strategies, used achieve that goal in a manner similar to | ||
216 | upstream Linux kernel development in | ||
217 | <filename>kernel.org</filename>. | ||
218 | </para> | ||
219 | |||
220 | <para> | ||
221 | You can think of a Yocto Linux kernel as consisting of a | ||
222 | baseline Linux kernel with added features logically structured | ||
223 | on top of the baseline. | ||
224 | The features are tagged and organized by way of a branching | ||
225 | strategy implemented by the Yocto Project team using the | ||
226 | Source Code Manager (SCM) Git. | ||
227 | <note><title>Notes</title> | ||
228 | <itemizedlist> | ||
229 | <listitem><para> | ||
230 | Git is the obvious SCM for meeting the Yocto Linux | ||
231 | kernel organizational and structural goals described | ||
232 | in this section. | ||
233 | Not only is Git the SCM for Linux kernel development in | ||
234 | <filename>kernel.org</filename> but, Git continues to | ||
235 | grow in popularity and supports many different work | ||
236 | flows, front-ends and management techniques. | ||
237 | </para></listitem> | ||
238 | <listitem><para> | ||
239 | You can find documentation on Git at | ||
240 | <ulink url='http://git-scm.com/documentation'></ulink>. | ||
241 | You can also get an introduction to Git as it | ||
242 | applies to the Yocto Project in the | ||
243 | "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>" | ||
244 | section in the Yocto Project Overview and Concepts | ||
245 | Manual. | ||
246 | The latter reference provides an overview of | ||
247 | Git and presents a minimal set of Git commands | ||
248 | that allows you to be functional using Git. | ||
249 | You can use as much, or as little, of what Git | ||
250 | has to offer to accomplish what you need for your | ||
251 | project. | ||
252 | You do not have to be a "Git Expert" in order to | ||
253 | use it with the Yocto Project. | ||
254 | </para></listitem> | ||
255 | </itemizedlist> | ||
256 | </note> | ||
257 | </para> | ||
258 | |||
259 | <para> | ||
260 | Using Git's tagging and branching features, the Yocto Project | ||
261 | team creates kernel branches at points where functionality is | ||
262 | no longer shared and thus, needs to be isolated. | ||
263 | For example, board-specific incompatibilities would require | ||
264 | different functionality and would require a branch to | ||
265 | separate the features. | ||
266 | Likewise, for specific kernel features, the same branching | ||
267 | strategy is used. | ||
268 | </para> | ||
269 | |||
270 | <para> | ||
271 | This "tree-like" architecture results in a structure that has | ||
272 | features organized to be specific for particular functionality, | ||
273 | single kernel types, or a subset of kernel types. | ||
274 | Thus, the user has the ability to see the added features and the | ||
275 | commits that make up those features. | ||
276 | In addition to being able to see added features, the user | ||
277 | can also view the history of what made up the baseline | ||
278 | Linux kernel. | ||
279 | </para> | ||
280 | |||
281 | <para> | ||
282 | Another consequence of this strategy results in not having to | ||
283 | store the same feature twice internally in the tree. | ||
284 | Rather, the kernel team stores the unique differences required | ||
285 | to apply the feature onto the kernel type in question. | ||
286 | <note> | ||
287 | The Yocto Project team strives to place features in the tree | ||
288 | such that features can be shared by all boards and kernel | ||
289 | types where possible. | ||
290 | However, during development cycles or when large features | ||
291 | are merged, the team cannot always follow this practice. | ||
292 | In those cases, the team uses isolated branches to merge | ||
293 | features. | ||
294 | </note> | ||
295 | </para> | ||
296 | |||
297 | <para> | ||
298 | BSP-specific code additions are handled in a similar manner to | ||
299 | kernel-specific additions. | ||
300 | Some BSPs only make sense given certain kernel types. | ||
301 | So, for these types, the team creates branches off the end | ||
302 | of that kernel type for all of the BSPs that are supported on | ||
303 | that kernel type. | ||
304 | From the perspective of the tools that create the BSP branch, | ||
305 | the BSP is really no different than a feature. | ||
306 | Consequently, the same branching strategy applies to BSPs as | ||
307 | it does to kernel features. | ||
308 | So again, rather than store the BSP twice, the team only | ||
309 | stores the unique differences for the BSP across the supported | ||
310 | multiple kernels. | ||
311 | </para> | ||
312 | |||
313 | <para> | ||
314 | While this strategy can result in a tree with a significant number | ||
315 | of branches, it is important to realize that from the developer's | ||
316 | point of view, there is a linear path that travels from the | ||
317 | baseline <filename>kernel.org</filename>, through a select | ||
318 | group of features and ends with their BSP-specific commits. | ||
319 | In other words, the divisions of the kernel are transparent and | ||
320 | are not relevant to the developer on a day-to-day basis. | ||
321 | From the developer's perspective, this path is the "master" branch | ||
322 | in Git terms. | ||
323 | The developer does not need to be aware of the existence of any | ||
324 | other branches at all. | ||
325 | Of course, value exists in the having these branches in the tree, | ||
326 | should a person decide to explore them. | ||
327 | For example, a comparison between two BSPs at either the commit | ||
328 | level or at the line-by-line code <filename>diff</filename> level | ||
329 | is now a trivial operation. | ||
330 | </para> | ||
331 | |||
332 | <para> | ||
333 | The following illustration shows the conceptual Yocto | ||
334 | Linux kernel. | ||
335 | <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" /> | ||
336 | </para> | ||
337 | |||
338 | <para> | ||
339 | In the illustration, the "Kernel.org Branch Point" marks the | ||
340 | specific spot (or Linux kernel release) from which the | ||
341 | Yocto Linux kernel is created. | ||
342 | From this point forward in the tree, features and differences | ||
343 | are organized and tagged. | ||
344 | </para> | ||
345 | |||
346 | <para> | ||
347 | The "Yocto Project Baseline Kernel" contains functionality that | ||
348 | is common to every kernel type and BSP that is organized | ||
349 | further along in the tree. | ||
350 | Placing these common features in the tree this way means | ||
351 | features do not have to be duplicated along individual | ||
352 | branches of the tree structure. | ||
353 | </para> | ||
354 | |||
355 | <para> | ||
356 | From the "Yocto Project Baseline Kernel", branch points represent | ||
357 | specific functionality for individual Board Support Packages | ||
358 | (BSPs) as well as real-time kernels. | ||
359 | The illustration represents this through three BSP-specific | ||
360 | branches and a real-time kernel branch. | ||
361 | Each branch represents some unique functionality for the BSP | ||
362 | or for a real-time Yocto Linux kernel. | ||
363 | </para> | ||
364 | |||
365 | <para> | ||
366 | In this example structure, the "Real-time (rt) Kernel" branch has | ||
367 | common features for all real-time Yocto Linux kernels and | ||
368 | contains more branches for individual BSP-specific real-time | ||
369 | kernels. | ||
370 | The illustration shows three branches as an example. | ||
371 | Each branch points the way to specific, unique features for a | ||
372 | respective real-time kernel as they apply to a given BSP. | ||
373 | </para> | ||
374 | |||
375 | <para> | ||
376 | The resulting tree structure presents a clear path of markers | ||
377 | (or branches) to the developer that, for all practical | ||
378 | purposes, is the Yocto Linux kernel needed for any given set of | ||
379 | requirements. | ||
380 | <note> | ||
381 | Keep in mind the figure does not take into account all the | ||
382 | supported Yocto Linux kernels, but rather shows a single | ||
383 | generic kernel just for conceptual purposes. | ||
384 | Also keep in mind that this structure represents the Yocto | ||
385 | Project | ||
386 | <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> | ||
387 | that are either pulled from during the build or established | ||
388 | on the host development system prior to the build by either | ||
389 | cloning a particular kernel's Git repository or by | ||
390 | downloading and unpacking a tarball. | ||
391 | </note> | ||
392 | </para> | ||
393 | |||
394 | <para> | ||
395 | Working with the kernel as a structured tree follows recognized | ||
396 | community best practices. | ||
397 | In particular, the kernel as shipped with the product, should be | ||
398 | considered an "upstream source" and viewed as a series of | ||
399 | historical and documented modifications (commits). | ||
400 | These modifications represent the development and stabilization | ||
401 | done by the Yocto Project kernel development team. | ||
402 | </para> | ||
403 | |||
404 | <para> | ||
405 | Because commits only change at significant release points in the | ||
406 | product life cycle, developers can work on a branch created | ||
407 | from the last relevant commit in the shipped Yocto Project Linux | ||
408 | kernel. | ||
409 | As mentioned previously, the structure is transparent to the | ||
410 | developer because the kernel tree is left in this state after | ||
411 | cloning and building the kernel. | ||
412 | </para> | ||
413 | </section> | ||
414 | |||
415 | <section id='kernel-build-file-hierarchy'> | ||
416 | <title>Kernel Build File Hierarchy</title> | ||
417 | |||
418 | <para> | ||
419 | Upstream storage of all the available kernel source code is | ||
420 | one thing, while representing and using the code on your host | ||
421 | development system is another. | ||
422 | Conceptually, you can think of the kernel source repositories | ||
423 | as all the source files necessary for all the supported | ||
424 | Yocto Linux kernels. | ||
425 | As a developer, you are just interested in the source files | ||
426 | for the kernel on which you are working. | ||
427 | And, furthermore, you need them available on your host system. | ||
428 | </para> | ||
429 | |||
430 | <para> | ||
431 | Kernel source code is available on your host system several | ||
432 | different ways: | ||
433 | <itemizedlist> | ||
434 | <listitem><para> | ||
435 | <emphasis>Files Accessed While using <filename>devtool</filename>:</emphasis> | ||
436 | <filename>devtool</filename>, which is available with the | ||
437 | Yocto Project, is the preferred method by which to | ||
438 | modify the kernel. | ||
439 | See the | ||
440 | "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" | ||
441 | section. | ||
442 | </para></listitem> | ||
443 | <listitem><para> | ||
444 | <emphasis>Cloned Repository:</emphasis> | ||
445 | If you are working in the kernel all the time, you probably | ||
446 | would want to set up your own local Git repository of the | ||
447 | Yocto Linux kernel tree. | ||
448 | For information on how to clone a Yocto Linux kernel | ||
449 | Git repository, see the | ||
450 | "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>" | ||
451 | section. | ||
452 | </para></listitem> | ||
453 | <listitem><para> | ||
454 | <emphasis>Temporary Source Files from a Build:</emphasis> | ||
455 | If you just need to make some patches to the kernel using | ||
456 | a traditional BitBake workflow (i.e. not using the | ||
457 | <filename>devtool</filename>), you can access temporary | ||
458 | kernel source files that were extracted and used during | ||
459 | a kernel build. | ||
460 | </para></listitem> | ||
461 | </itemizedlist> | ||
462 | </para> | ||
463 | |||
464 | <para> | ||
465 | The temporary kernel source files resulting from a build using | ||
466 | BitBake have a particular hierarchy. | ||
467 | When you build the kernel on your development system, all files | ||
468 | needed for the build are taken from the source repositories | ||
469 | pointed to by the | ||
470 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
471 | variable and gathered in a temporary work area where they are | ||
472 | subsequently used to create the unique kernel. | ||
473 | Thus, in a sense, the process constructs a local source tree | ||
474 | specific to your kernel from which to generate the new kernel | ||
475 | image. | ||
476 | </para> | ||
477 | |||
478 | <para> | ||
479 | The following figure shows the temporary file structure | ||
480 | created on your host system when you build the kernel using | ||
481 | Bitbake. | ||
482 | This | ||
483 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
484 | contains all the source files used during the build. | ||
485 | <imagedata fileref="figures/kernel-overview-2-generic.png" | ||
486 | width="6in" depth="5in" align="center" scale="100" /> | ||
487 | </para> | ||
488 | |||
489 | <para> | ||
490 | Again, for additional information on the Yocto Project kernel's | ||
491 | architecture and its branching strategy, see the | ||
492 | "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>" | ||
493 | section. | ||
494 | You can also reference the | ||
495 | "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" | ||
496 | and | ||
497 | "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>" | ||
498 | sections for detailed example that modifies the kernel. | ||
499 | </para> | ||
500 | </section> | ||
501 | |||
502 | <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'> | ||
503 | <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title> | ||
504 | |||
505 | <para> | ||
506 | This section describes part of the kernel configuration audit | ||
507 | phase that most developers can ignore. | ||
508 | For general information on kernel configuration including | ||
509 | <filename>menuconfig</filename>, <filename>defconfig</filename> | ||
510 | files, and configuration fragments, see the | ||
511 | "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" | ||
512 | section. | ||
513 | </para> | ||
514 | |||
515 | <para> | ||
516 | During this part of the audit phase, the contents of the final | ||
517 | <filename>.config</filename> file are compared against the | ||
518 | fragments specified by the system. | ||
519 | These fragments can be system fragments, distro fragments, | ||
520 | or user-specified configuration elements. | ||
521 | Regardless of their origin, the OpenEmbedded build system | ||
522 | warns the user if a specific option is not included in the | ||
523 | final kernel configuration. | ||
524 | </para> | ||
525 | |||
526 | <para> | ||
527 | By default, in order to not overwhelm the user with | ||
528 | configuration warnings, the system only reports missing | ||
529 | "hardware" options as they could result in a boot | ||
530 | failure or indicate that important hardware is not available. | ||
531 | </para> | ||
532 | |||
533 | <para> | ||
534 | To determine whether or not a given option is "hardware" or | ||
535 | "non-hardware", the kernel Metadata in | ||
536 | <filename>yocto-kernel-cache</filename> contains files that | ||
537 | classify individual or groups of options as either hardware | ||
538 | or non-hardware. | ||
539 | To better show this, consider a situation where the | ||
540 | <filename>yocto-kernel-cache</filename> contains the following | ||
541 | files: | ||
542 | <literallayout class='monospaced'> | ||
543 | yocto-kernel-cache/features/drm-psb/hardware.cfg | ||
544 | yocto-kernel-cache/features/kgdb/hardware.cfg | ||
545 | yocto-kernel-cache/ktypes/base/hardware.cfg | ||
546 | yocto-kernel-cache/bsp/mti-malta32/hardware.cfg | ||
547 | yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg | ||
548 | yocto-kernel-cache/bsp/qemuarma9/hardware.cfg | ||
549 | yocto-kernel-cache/bsp/mti-malta64/hardware.cfg | ||
550 | yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg | ||
551 | yocto-kernel-cache/bsp/common-pc/hardware.cfg | ||
552 | yocto-kernel-cache/bsp/common-pc-64/hardware.cfg | ||
553 | yocto-kernel-cache/features/rfkill/non-hardware.cfg | ||
554 | yocto-kernel-cache/ktypes/base/non-hardware.cfg | ||
555 | yocto-kernel-cache/features/aufs/non-hardware.kcf | ||
556 | yocto-kernel-cache/features/ocf/non-hardware.kcf | ||
557 | yocto-kernel-cache/ktypes/base/non-hardware.kcf | ||
558 | yocto-kernel-cache/ktypes/base/hardware.kcf | ||
559 | yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf | ||
560 | </literallayout> | ||
561 | The following list provides explanations for the various | ||
562 | files: | ||
563 | <itemizedlist> | ||
564 | <listitem><para> | ||
565 | <filename>hardware.kcf</filename>: | ||
566 | Specifies a list of kernel Kconfig files that contain | ||
567 | hardware options only. | ||
568 | </para></listitem> | ||
569 | <listitem><para> | ||
570 | <filename>non-hardware.kcf</filename>: | ||
571 | Specifies a list of kernel Kconfig files that contain | ||
572 | non-hardware options only. | ||
573 | </para></listitem> | ||
574 | <listitem><para> | ||
575 | <filename>hardware.cfg</filename>: | ||
576 | Specifies a list of kernel <filename>CONFIG_</filename> | ||
577 | options that are hardware, regardless of whether or not | ||
578 | they are within a Kconfig file specified by a hardware | ||
579 | or non-hardware Kconfig file (i.e. | ||
580 | <filename>hardware.kcf</filename> or | ||
581 | <filename>non-hardware.kcf</filename>). | ||
582 | </para></listitem> | ||
583 | <listitem><para> | ||
584 | <filename>non-hardware.cfg</filename>: | ||
585 | Specifies a list of kernel <filename>CONFIG_</filename> | ||
586 | options that are not hardware, regardless of whether or | ||
587 | not they are within a Kconfig file specified by a | ||
588 | hardware or non-hardware Kconfig file (i.e. | ||
589 | <filename>hardware.kcf</filename> or | ||
590 | <filename>non-hardware.kcf</filename>). | ||
591 | </para></listitem> | ||
592 | </itemizedlist> | ||
593 | Here is a specific example using the | ||
594 | <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>: | ||
595 | <literallayout class='monospaced'> | ||
596 | CONFIG_SERIAL_8250 | ||
597 | CONFIG_SERIAL_8250_CONSOLE | ||
598 | CONFIG_SERIAL_8250_NR_UARTS | ||
599 | CONFIG_SERIAL_8250_PCI | ||
600 | CONFIG_SERIAL_CORE | ||
601 | CONFIG_SERIAL_CORE_CONSOLE | ||
602 | CONFIG_VGA_ARB | ||
603 | </literallayout> | ||
604 | The kernel configuration audit automatically detects these | ||
605 | files (hence the names must be exactly the ones discussed here), | ||
606 | and uses them as inputs when generating warnings about the | ||
607 | final <filename>.config</filename> file. | ||
608 | </para> | ||
609 | |||
610 | <para> | ||
611 | A user-specified kernel Metadata repository, or recipe space | ||
612 | feature, can use these same files to classify options that are | ||
613 | found within its <filename>.cfg</filename> files as hardware | ||
614 | or non-hardware, to prevent the OpenEmbedded build system from | ||
615 | producing an error or warning when an option is not in the | ||
616 | final <filename>.config</filename> file. | ||
617 | </para> | ||
618 | </section> | ||
619 | </appendix> | ||
620 | <!-- | ||
621 | vim: expandtab tw=80 ts=4 | ||
622 | --> | ||