diff options
| author | Nicolas Dechesne <nicolas.dechesne@linaro.org> | 2020-10-05 16:30:32 +0200 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2020-10-06 13:56:17 +0100 |
| commit | 43d07a285181e64c30d98d10ff93ef50391efe59 (patch) | |
| tree | 78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/kernel-dev/kernel-dev-concepts-appx.xml | |
| parent | 1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff) | |
| download | poky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz | |
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove
the deprecated DocBook files.
(From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
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 | --> | ||