diff options
Diffstat (limited to 'documentation/kernel-dev')
17 files changed, 4083 insertions, 22 deletions
diff --git a/documentation/kernel-dev/history.rst b/documentation/kernel-dev/history.rst new file mode 100644 index 0000000000..3ffb7eacb8 --- /dev/null +++ b/documentation/kernel-dev/history.rst | |||
@@ -0,0 +1,58 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | *********************** | ||
4 | Manual Revision History | ||
5 | *********************** | ||
6 | |||
7 | .. list-table:: | ||
8 | :widths: 10 15 40 | ||
9 | :header-rows: 1 | ||
10 | |||
11 | * - Revision | ||
12 | - Date | ||
13 | - Note | ||
14 | * - 1.4 | ||
15 | - April 2013 | ||
16 | - The initial document released with the Yocto Project 1.4 Release | ||
17 | * - 1.5 | ||
18 | - October 2013 | ||
19 | - Released with the Yocto Project 1.5 Release. | ||
20 | * - 1.6 | ||
21 | - April 2014 | ||
22 | - Released with the Yocto Project 1.6 Release. | ||
23 | * - 1.7 | ||
24 | - October 2014 | ||
25 | - Released with the Yocto Project 1.7 Release. | ||
26 | * - 1.8 | ||
27 | - April 2015 | ||
28 | - Released with the Yocto Project 1.8 Release. | ||
29 | * - 2.0 | ||
30 | - October 2015 | ||
31 | - Released with the Yocto Project 2.0 Release. | ||
32 | * - 2.1 | ||
33 | - April 2016 | ||
34 | - Released with the Yocto Project 2.1 Release. | ||
35 | * - 2.2 | ||
36 | - October 2016 | ||
37 | - Released with the Yocto Project 2.2 Release. | ||
38 | * - 2.3 | ||
39 | - May 2017 | ||
40 | - Released with the Yocto Project 2.3 Release. | ||
41 | * - 2.4 | ||
42 | - October 2017 | ||
43 | - Released with the Yocto Project 2.4 Release. | ||
44 | * - 2.5 | ||
45 | - May 2018 | ||
46 | - Released with the Yocto Project 2.5 Release. | ||
47 | * - 2.6 | ||
48 | - November 2018 | ||
49 | - Released with the Yocto Project 2.6 Release. | ||
50 | * - 2.7 | ||
51 | - May 2019 | ||
52 | - Released with the Yocto Project 2.7 Release. | ||
53 | * - 3.0 | ||
54 | - October 2019 | ||
55 | - Released with the Yocto Project 3.0 Release. | ||
56 | * - 3.1 | ||
57 | - April 2020 | ||
58 | - Released with the Yocto Project 3.1 Release. | ||
diff --git a/documentation/kernel-dev/kernel-dev-advanced.rst b/documentation/kernel-dev/kernel-dev-advanced.rst new file mode 100644 index 0000000000..36133caae3 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-advanced.rst | |||
@@ -0,0 +1,983 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******************************************************* | ||
4 | Working with Advanced Metadata (``yocto-kernel-cache``) | ||
5 | ******************************************************* | ||
6 | |||
7 | .. _kernel-dev-advanced-overview: | ||
8 | |||
9 | Overview | ||
10 | ======== | ||
11 | |||
12 | In addition to supporting configuration fragments and patches, the Yocto | ||
13 | Project kernel tools also support rich | ||
14 | :term:`Metadata` that you can use to define | ||
15 | complex policies and Board Support Package (BSP) support. The purpose of | ||
16 | the Metadata and the tools that manage it is to help you manage the | ||
17 | complexity of the configuration and sources used to support multiple | ||
18 | BSPs and Linux kernel types. | ||
19 | |||
20 | Kernel Metadata exists in many places. One area in the | ||
21 | :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` | ||
22 | is the ``yocto-kernel-cache`` Git repository. You can find this repository | ||
23 | grouped under the "Yocto Linux Kernel" heading in the | ||
24 | :yocto_git:`Yocto Project Source Repositories <>`. | ||
25 | |||
26 | Kernel development tools ("kern-tools") exist also in the Yocto Project | ||
27 | Source Repositories under the "Yocto Linux Kernel" heading in the | ||
28 | ``yocto-kernel-tools`` Git repository. The recipe that builds these | ||
29 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in | ||
30 | the :term:`Source Directory` (e.g. | ||
31 | ``poky``). | ||
32 | |||
33 | Using Kernel Metadata in a Recipe | ||
34 | ================================= | ||
35 | |||
36 | As mentioned in the introduction, the Yocto Project contains kernel | ||
37 | Metadata, which is located in the ``yocto-kernel-cache`` Git repository. | ||
38 | This Metadata defines Board Support Packages (BSPs) that correspond to | ||
39 | definitions in linux-yocto recipes for corresponding BSPs. A BSP | ||
40 | consists of an aggregation of kernel policy and enabled | ||
41 | hardware-specific features. The BSP can be influenced from within the | ||
42 | linux-yocto recipe. | ||
43 | |||
44 | .. note:: | ||
45 | |||
46 | A Linux kernel recipe that contains kernel Metadata (e.g. inherits | ||
47 | from the | ||
48 | linux-yocto.inc | ||
49 | file) is said to be a "linux-yocto style" recipe. | ||
50 | |||
51 | Every linux-yocto style recipe must define the | ||
52 | :term:`KMACHINE` variable. This | ||
53 | variable is typically set to the same value as the ``MACHINE`` variable, | ||
54 | which is used by :term:`BitBake`. | ||
55 | However, in some cases, the variable might instead refer to the | ||
56 | underlying platform of the ``MACHINE``. | ||
57 | |||
58 | Multiple BSPs can reuse the same ``KMACHINE`` name if they are built | ||
59 | using the same BSP description. Multiple Corei7-based BSPs could share | ||
60 | the same "intel-corei7-64" value for ``KMACHINE``. It is important to | ||
61 | realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE`` | ||
62 | is the machine type within a BSP Layer. Even with this distinction, | ||
63 | however, these two variables can hold the same value. See the `BSP | ||
64 | Descriptions <#bsp-descriptions>`__ section for more information. | ||
65 | |||
66 | Every linux-yocto style recipe must also indicate the Linux kernel | ||
67 | source repository branch used to build the Linux kernel. The | ||
68 | :term:`KBRANCH` variable must be set | ||
69 | to indicate the branch. | ||
70 | |||
71 | .. note:: | ||
72 | |||
73 | You can use the | ||
74 | KBRANCH | ||
75 | value to define an alternate branch typically with a machine override | ||
76 | as shown here from the | ||
77 | meta-yocto-bsp | ||
78 | layer: | ||
79 | :: | ||
80 | |||
81 | KBRANCH_edgerouter = "standard/edgerouter" | ||
82 | |||
83 | |||
84 | The linux-yocto style recipes can optionally define the following | ||
85 | variables: | ||
86 | |||
87 | - :term:`KERNEL_FEATURES` | ||
88 | |||
89 | - :term:`LINUX_KERNEL_TYPE` | ||
90 | |||
91 | :term:`LINUX_KERNEL_TYPE` | ||
92 | defines the kernel type to be used in assembling the configuration. If | ||
93 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". | ||
94 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search | ||
95 | arguments used by the kernel tools to find the appropriate description | ||
96 | within the kernel Metadata with which to build out the sources and | ||
97 | configuration. The linux-yocto recipes define "standard", "tiny", and | ||
98 | "preempt-rt" kernel types. See the "`Kernel Types <#kernel-types>`__" | ||
99 | section for more information on kernel types. | ||
100 | |||
101 | During the build, the kern-tools search for the BSP description file | ||
102 | that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE`` | ||
103 | variables passed in from the recipe. The tools use the first BSP | ||
104 | description it finds that match both variables. If the tools cannot find | ||
105 | a match, they issue a warning. | ||
106 | |||
107 | The tools first search for the ``KMACHINE`` and then for the | ||
108 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they | ||
109 | will use the sources from the ``KBRANCH`` and any configuration | ||
110 | specified in the :term:`SRC_URI`. | ||
111 | |||
112 | You can use the | ||
113 | :term:`KERNEL_FEATURES` | ||
114 | variable to include features (configuration fragments, patches, or both) | ||
115 | that are not already included by the ``KMACHINE`` and | ||
116 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a | ||
117 | feature specified as "features/netfilter/netfilter.scc", specify: | ||
118 | :: | ||
119 | |||
120 | KERNEL_FEATURES += "features/netfilter/netfilter.scc" | ||
121 | |||
122 | To include a | ||
123 | feature called "cfg/sound.scc" just for the ``qemux86`` machine, | ||
124 | specify: | ||
125 | :: | ||
126 | |||
127 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" | ||
128 | |||
129 | The value of | ||
130 | the entries in ``KERNEL_FEATURES`` are dependent on their location | ||
131 | within the kernel Metadata itself. The examples here are taken from the | ||
132 | ``yocto-kernel-cache`` repository. Each branch of this repository | ||
133 | contains "features" and "cfg" subdirectories at the top-level. For more | ||
134 | information, see the "`Kernel Metadata | ||
135 | Syntax <#kernel-metadata-syntax>`__" section. | ||
136 | |||
137 | Kernel Metadata Syntax | ||
138 | ====================== | ||
139 | |||
140 | The kernel Metadata consists of three primary types of files: ``scc`` | ||
141 | [1]_ description files, configuration fragments, and patches. The | ||
142 | ``scc`` files define variables and include or otherwise reference any of | ||
143 | the three file types. The description files are used to aggregate all | ||
144 | types of kernel Metadata into what ultimately describes the sources and | ||
145 | the configuration required to build a Linux kernel tailored to a | ||
146 | specific machine. | ||
147 | |||
148 | The ``scc`` description files are used to define two fundamental types | ||
149 | of kernel Metadata: | ||
150 | |||
151 | - Features | ||
152 | |||
153 | - Board Support Packages (BSPs) | ||
154 | |||
155 | Features aggregate sources in the form of patches and configuration | ||
156 | fragments into a modular reusable unit. You can use features to | ||
157 | implement conceptually separate kernel Metadata descriptions such as | ||
158 | pure configuration fragments, simple patches, complex features, and | ||
159 | kernel types. `Kernel types <#kernel-types>`__ define general kernel | ||
160 | features and policy to be reused in the BSPs. | ||
161 | |||
162 | BSPs define hardware-specific features and aggregate them with kernel | ||
163 | types to form the final description of what will be assembled and built. | ||
164 | |||
165 | While the kernel Metadata syntax does not enforce any logical separation | ||
166 | of configuration fragments, patches, features or kernel types, best | ||
167 | practices dictate a logical separation of these types of Metadata. The | ||
168 | following Metadata file hierarchy is recommended: | ||
169 | :: | ||
170 | |||
171 | base/ | ||
172 | bsp/ | ||
173 | cfg/ | ||
174 | features/ | ||
175 | ktypes/ | ||
176 | patches/ | ||
177 | |||
178 | The ``bsp`` directory contains the `BSP | ||
179 | descriptions <#bsp-descriptions>`__. The remaining directories all | ||
180 | contain "features". Separating ``bsp`` from the rest of the structure | ||
181 | aids conceptualizing intended usage. | ||
182 | |||
183 | Use these guidelines to help place your ``scc`` description files within | ||
184 | the structure: | ||
185 | |||
186 | - If your file contains only configuration fragments, place the file in | ||
187 | the ``cfg`` directory. | ||
188 | |||
189 | - If your file contains only source-code fixes, place the file in the | ||
190 | ``patches`` directory. | ||
191 | |||
192 | - If your file encapsulates a major feature, often combining sources | ||
193 | and configurations, place the file in ``features`` directory. | ||
194 | |||
195 | - If your file aggregates non-hardware configuration and patches in | ||
196 | order to define a base kernel policy or major kernel type to be | ||
197 | reused across multiple BSPs, place the file in ``ktypes`` directory. | ||
198 | |||
199 | These distinctions can easily become blurred - especially as out-of-tree | ||
200 | features slowly merge upstream over time. Also, remember that how the | ||
201 | description files are placed is a purely logical organization and has no | ||
202 | impact on the functionality of the kernel Metadata. There is no impact | ||
203 | because all of ``cfg``, ``features``, ``patches``, and ``ktypes``, | ||
204 | contain "features" as far as the kernel tools are concerned. | ||
205 | |||
206 | Paths used in kernel Metadata files are relative to base, which is | ||
207 | either | ||
208 | :term:`FILESEXTRAPATHS` if | ||
209 | you are creating Metadata in `recipe-space <#recipe-space-metadata>`__, | ||
210 | or the top level of | ||
211 | :yocto_git:`yocto-kernel-cache </cgit/cgit.cgi/yocto-kernel-cache/tree/>` | ||
212 | if you are creating `Metadata outside of the | ||
213 | recipe-space <#metadata-outside-the-recipe-space>`__. | ||
214 | |||
215 | .. [1] | ||
216 | ``scc`` stands for Series Configuration Control, but the naming has | ||
217 | less significance in the current implementation of the tooling than | ||
218 | it had in the past. Consider ``scc`` files to be description files. | ||
219 | |||
220 | Configuration | ||
221 | ------------- | ||
222 | |||
223 | The simplest unit of kernel Metadata is the configuration-only feature. | ||
224 | This feature consists of one or more Linux kernel configuration | ||
225 | parameters in a configuration fragment file (``.cfg``) and a ``.scc`` | ||
226 | file that describes the fragment. | ||
227 | |||
228 | As an example, consider the Symmetric Multi-Processing (SMP) fragment | ||
229 | used with the ``linux-yocto-4.12`` kernel as defined outside of the | ||
230 | recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of | ||
231 | two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the | ||
232 | ``cfg`` directory of the ``yocto-4.12`` branch in the | ||
233 | ``yocto-kernel-cache`` Git repository: | ||
234 | :: | ||
235 | |||
236 | cfg/smp.scc: | ||
237 | define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" | ||
238 | define KFEATURE_COMPATIBILITY all | ||
239 | |||
240 | kconf hardware smp.cfg | ||
241 | |||
242 | cfg/smp.cfg: | ||
243 | CONFIG_SMP=y | ||
244 | CONFIG_SCHED_SMT=y | ||
245 | # Increase default NR_CPUS from 8 to 64 so that platform with | ||
246 | # more than 8 processors can be all activated at boot time | ||
247 | CONFIG_NR_CPUS=64 | ||
248 | # The following is needed when setting NR_CPUS to something | ||
249 | # greater than 8 on x86 architectures, it should be automatically | ||
250 | # disregarded by Kconfig when using a different arch | ||
251 | CONFIG_X86_BIGSMP=y | ||
252 | |||
253 | You can find general information on configuration | ||
254 | fragment files in the "`Creating Configuration | ||
255 | Fragments <#creating-config-fragments>`__" section. | ||
256 | |||
257 | Within the ``smp.scc`` file, the | ||
258 | :term:`KFEATURE_DESCRIPTION` | ||
259 | statement provides a short description of the fragment. Higher level | ||
260 | kernel tools use this description. | ||
261 | |||
262 | Also within the ``smp.scc`` file, the ``kconf`` command includes the | ||
263 | actual configuration fragment in an ``.scc`` file, and the "hardware" | ||
264 | keyword identifies the fragment as being hardware enabling, as opposed | ||
265 | to general policy, which would use the "non-hardware" keyword. The | ||
266 | distinction is made for the benefit of the configuration validation | ||
267 | tools, which warn you if a hardware fragment overrides a policy set by a | ||
268 | non-hardware fragment. | ||
269 | |||
270 | .. note:: | ||
271 | |||
272 | The description file can include multiple | ||
273 | kconf | ||
274 | statements, one per fragment. | ||
275 | |||
276 | As described in the "`Validating | ||
277 | Configuration <#validating-configuration>`__" section, you can use the | ||
278 | following BitBake command to audit your configuration: | ||
279 | :: | ||
280 | |||
281 | $ bitbake linux-yocto -c kernel_configcheck -f | ||
282 | |||
283 | Patches | ||
284 | ------- | ||
285 | |||
286 | Patch descriptions are very similar to configuration fragment | ||
287 | descriptions, which are described in the previous section. However, | ||
288 | instead of a ``.cfg`` file, these descriptions work with source patches | ||
289 | (i.e. ``.patch`` files). | ||
290 | |||
291 | A typical patch includes a description file and the patch itself. As an | ||
292 | example, consider the build patches used with the ``linux-yocto-4.12`` | ||
293 | kernel as defined outside of the recipe space (i.e. | ||
294 | ``yocto-kernel-cache``). This Metadata consists of several files: | ||
295 | ``build.scc`` and a set of ``*.patch`` files. You can find these files | ||
296 | in the ``patches/build`` directory of the ``yocto-4.12`` branch in the | ||
297 | ``yocto-kernel-cache`` Git repository. | ||
298 | |||
299 | The following listings show the ``build.scc`` file and part of the | ||
300 | ``modpost-mask-trivial-warnings.patch`` file: | ||
301 | :: | ||
302 | |||
303 | patches/build/build.scc: | ||
304 | patch arm-serialize-build-targets.patch | ||
305 | patch powerpc-serialize-image-targets.patch | ||
306 | patch kbuild-exclude-meta-directory-from-distclean-processi.patch | ||
307 | |||
308 | # applied by kgit | ||
309 | # patch kbuild-add-meta-files-to-the-ignore-li.patch | ||
310 | |||
311 | patch modpost-mask-trivial-warnings.patch | ||
312 | patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch | ||
313 | |||
314 | patches/build/modpost-mask-trivial-warnings.patch: | ||
315 | From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001 | ||
316 | From: Paul Gortmaker <paul.gortmaker@windriver.com> | ||
317 | Date: Sun, 25 Jan 2009 17:58:09 -0500 | ||
318 | Subject: [PATCH] modpost: mask trivial warnings | ||
319 | |||
320 | Newer HOSTCC will complain about various stdio fcns because | ||
321 | . | ||
322 | . | ||
323 | . | ||
324 | char *dump_write = NULL, *files_source = NULL; | ||
325 | int opt; | ||
326 | -- | ||
327 | 2.10.1 | ||
328 | |||
329 | generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT) | ||
330 | |||
331 | The description file can | ||
332 | include multiple patch statements where each statement handles a single | ||
333 | patch. In the example ``build.scc`` file, five patch statements exist | ||
334 | for the five patches in the directory. | ||
335 | |||
336 | You can create a typical ``.patch`` file using ``diff -Nurp`` or | ||
337 | ``git format-patch`` commands. For information on how to create patches, | ||
338 | see the "`Using ``devtool`` to Patch the | ||
339 | Kernel <#using-devtool-to-patch-the-kernel>`__" and "`Using Traditional | ||
340 | Kernel Development to Patch the | ||
341 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
342 | sections. | ||
343 | |||
344 | Features | ||
345 | -------- | ||
346 | |||
347 | Features are complex kernel Metadata types that consist of configuration | ||
348 | fragments, patches, and possibly other feature description files. As an | ||
349 | example, consider the following generic listing: | ||
350 | :: | ||
351 | |||
352 | features/myfeature.scc | ||
353 | define KFEATURE_DESCRIPTION "Enable myfeature" | ||
354 | |||
355 | patch 0001-myfeature-core.patch | ||
356 | patch 0002-myfeature-interface.patch | ||
357 | |||
358 | include cfg/myfeature_dependency.scc | ||
359 | kconf non-hardware myfeature.cfg | ||
360 | |||
361 | This example shows how the ``patch`` and ``kconf`` commands are used as well | ||
362 | as how an additional feature description file is included with the | ||
363 | ``include`` command. | ||
364 | |||
365 | Typically, features are less granular than configuration fragments and | ||
366 | are more likely than configuration fragments and patches to be the types | ||
367 | of things you want to specify in the ``KERNEL_FEATURES`` variable of the | ||
368 | Linux kernel recipe. See the "`Using Kernel Metadata in a | ||
369 | Recipe <#using-kernel-metadata-in-a-recipe>`__" section earlier in the | ||
370 | manual. | ||
371 | |||
372 | Kernel Types | ||
373 | ------------ | ||
374 | |||
375 | A kernel type defines a high-level kernel policy by aggregating | ||
376 | non-hardware configuration fragments with patches you want to use when | ||
377 | building a Linux kernel of a specific type (e.g. a real-time kernel). | ||
378 | Syntactically, kernel types are no different than features as described | ||
379 | in the "`Features <#features>`__" section. The | ||
380 | :term:`LINUX_KERNEL_TYPE` | ||
381 | variable in the kernel recipe selects the kernel type. For example, in | ||
382 | the ``linux-yocto_4.12.bb`` kernel recipe found in | ||
383 | ``poky/meta/recipes-kernel/linux``, a | ||
384 | :ref:`require <bitbake:require-inclusion>` directive | ||
385 | includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file, | ||
386 | which has the following statement that defines the default kernel type: | ||
387 | :: | ||
388 | |||
389 | LINUX_KERNEL_TYPE ??= "standard" | ||
390 | |||
391 | Another example would be the real-time kernel (i.e. | ||
392 | ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel | ||
393 | type as follows: | ||
394 | :: | ||
395 | |||
396 | LINUX_KERNEL_TYPE = "preempt-rt" | ||
397 | |||
398 | .. note:: | ||
399 | |||
400 | You can find kernel recipes in the | ||
401 | meta/recipes-kernel/linux | ||
402 | directory of the | ||
403 | Source Directory | ||
404 | (e.g. | ||
405 | poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb | ||
406 | ). See the " | ||
407 | Using Kernel Metadata in a Recipe | ||
408 | " section for more information. | ||
409 | |||
410 | Three kernel types ("standard", "tiny", and "preempt-rt") are supported | ||
411 | for Linux Yocto kernels: | ||
412 | |||
413 | - "standard": Includes the generic Linux kernel policy of the Yocto | ||
414 | Project linux-yocto kernel recipes. This policy includes, among other | ||
415 | things, which file systems, networking options, core kernel features, | ||
416 | and debugging and tracing options are supported. | ||
417 | |||
418 | - "preempt-rt": Applies the ``PREEMPT_RT`` patches and the | ||
419 | configuration options required to build a real-time Linux kernel. | ||
420 | This kernel type inherits from the "standard" kernel type. | ||
421 | |||
422 | - "tiny": Defines a bare minimum configuration meant to serve as a base | ||
423 | for very small Linux kernels. The "tiny" kernel type is independent | ||
424 | from the "standard" configuration. Although the "tiny" kernel type | ||
425 | does not currently include any source changes, it might in the | ||
426 | future. | ||
427 | |||
428 | For any given kernel type, the Metadata is defined by the ``.scc`` (e.g. | ||
429 | ``standard.scc``). Here is a partial listing for the ``standard.scc`` | ||
430 | file, which is found in the ``ktypes/standard`` directory of the | ||
431 | ``yocto-kernel-cache`` Git repository: | ||
432 | :: | ||
433 | |||
434 | # Include this kernel type fragment to get the standard features and | ||
435 | # configuration values. | ||
436 | |||
437 | # Note: if only the features are desired, but not the configuration | ||
438 | # then this should be included as: | ||
439 | # include ktypes/standard/standard.scc nocfg | ||
440 | # if no chained configuration is desired, include it as: | ||
441 | # include ktypes/standard/standard.scc nocfg inherit | ||
442 | |||
443 | |||
444 | |||
445 | include ktypes/base/base.scc | ||
446 | branch standard | ||
447 | |||
448 | kconf non-hardware standard.cfg | ||
449 | |||
450 | include features/kgdb/kgdb.scc | ||
451 | . | ||
452 | . | ||
453 | . | ||
454 | |||
455 | include cfg/net/ip6_nf.scc | ||
456 | include cfg/net/bridge.scc | ||
457 | |||
458 | include cfg/systemd.scc | ||
459 | |||
460 | include features/rfkill/rfkill.scc | ||
461 | |||
462 | As with any ``.scc`` file, a kernel type definition can aggregate other | ||
463 | ``.scc`` files with ``include`` commands. These definitions can also | ||
464 | directly pull in configuration fragments and patches with the ``kconf`` | ||
465 | and ``patch`` commands, respectively. | ||
466 | |||
467 | .. note:: | ||
468 | |||
469 | It is not strictly necessary to create a kernel type | ||
470 | .scc | ||
471 | file. The Board Support Package (BSP) file can implicitly define the | ||
472 | kernel type using a | ||
473 | define | ||
474 | KTYPE | ||
475 | myktype | ||
476 | line. See the " | ||
477 | BSP Descriptions | ||
478 | " section for more information. | ||
479 | |||
480 | BSP Descriptions | ||
481 | ---------------- | ||
482 | |||
483 | BSP descriptions (i.e. ``*.scc`` files) combine kernel types with | ||
484 | hardware-specific features. The hardware-specific Metadata is typically | ||
485 | defined independently in the BSP layer, and then aggregated with each | ||
486 | supported kernel type. | ||
487 | |||
488 | .. note:: | ||
489 | |||
490 | For BSPs supported by the Yocto Project, the BSP description files | ||
491 | are located in the | ||
492 | bsp | ||
493 | directory of the | ||
494 | yocto-kernel-cache | ||
495 | repository organized under the "Yocto Linux Kernel" heading in the | ||
496 | Yocto Project Source Repositories | ||
497 | . | ||
498 | |||
499 | This section overviews the BSP description structure, the aggregation | ||
500 | concepts, and presents a detailed example using a BSP supported by the | ||
501 | Yocto Project (i.e. BeagleBone Board). For complete information on BSP | ||
502 | layer file hierarchy, see the :doc:`../bsp-guide/bsp-guide`. | ||
503 | |||
504 | .. _bsp-description-file-overview: | ||
505 | |||
506 | Description Overview | ||
507 | ~~~~~~~~~~~~~~~~~~~~ | ||
508 | |||
509 | For simplicity, consider the following root BSP layer description files | ||
510 | for the BeagleBone board. These files employ both a structure and naming | ||
511 | convention for consistency. The naming convention for the file is as | ||
512 | follows: | ||
513 | :: | ||
514 | |||
515 | bsp_root_name-kernel_type.scc | ||
516 | |||
517 | Here are some example root layer | ||
518 | BSP filenames for the BeagleBone Board BSP, which is supported by the | ||
519 | Yocto Project: | ||
520 | :: | ||
521 | |||
522 | beaglebone-standard.scc | ||
523 | beaglebone-preempt-rt.scc | ||
524 | |||
525 | Each file uses the root name (i.e "beaglebone") BSP name followed by the | ||
526 | kernel type. | ||
527 | |||
528 | Examine the ``beaglebone-standard.scc`` file: | ||
529 | :: | ||
530 | |||
531 | define KMACHINE beaglebone | ||
532 | define KTYPE standard | ||
533 | define KARCH arm | ||
534 | |||
535 | include ktypes/standard/standard.scc | ||
536 | branch beaglebone | ||
537 | |||
538 | include beaglebone.scc | ||
539 | |||
540 | # default policy for standard kernels | ||
541 | include features/latencytop/latencytop.scc | ||
542 | include features/profiling/profiling.scc | ||
543 | |||
544 | Every top-level BSP description file | ||
545 | should define the :term:`KMACHINE`, | ||
546 | :term:`KTYPE`, and | ||
547 | :term:`KARCH` variables. These | ||
548 | variables allow the OpenEmbedded build system to identify the | ||
549 | description as meeting the criteria set by the recipe being built. This | ||
550 | example supports the "beaglebone" machine for the "standard" kernel and | ||
551 | the "arm" architecture. | ||
552 | |||
553 | Be aware that a hard link between the ``KTYPE`` variable and a kernel | ||
554 | type description file does not exist. Thus, if you do not have the | ||
555 | kernel type defined in your kernel Metadata as it is here, you only need | ||
556 | to ensure that the | ||
557 | :term:`LINUX_KERNEL_TYPE` | ||
558 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP | ||
559 | description file match. | ||
560 | |||
561 | To separate your kernel policy from your hardware configuration, you | ||
562 | include a kernel type (``ktype``), such as "standard". In the previous | ||
563 | example, this is done using the following: | ||
564 | :: | ||
565 | |||
566 | include ktypes/standard/standard.scc | ||
567 | |||
568 | This file aggregates all the configuration | ||
569 | fragments, patches, and features that make up your standard kernel | ||
570 | policy. See the "`Kernel Types <#kernel-types>`__" section for more | ||
571 | information. | ||
572 | |||
573 | To aggregate common configurations and features specific to the kernel | ||
574 | for mybsp, use the following: | ||
575 | :: | ||
576 | |||
577 | include mybsp.scc | ||
578 | |||
579 | You can see that in the BeagleBone example with the following: | ||
580 | :: | ||
581 | |||
582 | include beaglebone.scc | ||
583 | |||
584 | For information on how to break a complete ``.config`` file into the various | ||
585 | configuration fragments, see the "`Creating Configuration | ||
586 | Fragments <#creating-config-fragments>`__" section. | ||
587 | |||
588 | Finally, if you have any configurations specific to the hardware that | ||
589 | are not in a ``*.scc`` file, you can include them as follows: | ||
590 | :: | ||
591 | |||
592 | kconf hardware mybsp-extra.cfg | ||
593 | |||
594 | The BeagleBone example does not include these | ||
595 | types of configurations. However, the Malta 32-bit board does | ||
596 | ("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file: | ||
597 | :: | ||
598 | |||
599 | define KMACHINE mti-malta32-le | ||
600 | define KMACHINE qemumipsel | ||
601 | define KTYPE standard | ||
602 | define KARCH mips | ||
603 | |||
604 | include ktypes/standard/standard.scc | ||
605 | branch mti-malta32 | ||
606 | |||
607 | include mti-malta32.scc | ||
608 | kconf hardware mti-malta32-le.cfg | ||
609 | |||
610 | .. _bsp-description-file-example-minnow: | ||
611 | |||
612 | Example | ||
613 | ~~~~~~~ | ||
614 | |||
615 | Many real-world examples are more complex. Like any other ``.scc`` file, | ||
616 | BSP descriptions can aggregate features. Consider the Minnow BSP | ||
617 | definition given the ``linux-yocto-4.4`` branch of the | ||
618 | ``yocto-kernel-cache`` (i.e. | ||
619 | ``yocto-kernel-cache/bsp/minnow/minnow.scc``): | ||
620 | |||
621 | .. note:: | ||
622 | |||
623 | Although the Minnow Board BSP is unused, the Metadata remains and is | ||
624 | being used here just as an example. | ||
625 | |||
626 | :: | ||
627 | |||
628 | include cfg/x86.scc | ||
629 | include features/eg20t/eg20t.scc | ||
630 | include cfg/dmaengine.scc | ||
631 | include features/power/intel.scc | ||
632 | include cfg/efi.scc | ||
633 | include features/usb/ehci-hcd.scc | ||
634 | include features/usb/ohci-hcd.scc | ||
635 | include features/usb/usb-gadgets.scc | ||
636 | include features/usb/touchscreen-composite.scc | ||
637 | include cfg/timer/hpet.scc | ||
638 | include features/leds/leds.scc | ||
639 | include features/spi/spidev.scc | ||
640 | include features/i2c/i2cdev.scc | ||
641 | include features/mei/mei-txe.scc | ||
642 | |||
643 | # Earlyprintk and port debug requires 8250 | ||
644 | kconf hardware cfg/8250.cfg | ||
645 | |||
646 | kconf hardware minnow.cfg | ||
647 | kconf hardware minnow-dev.cfg | ||
648 | |||
649 | The ``minnow.scc`` description file includes a hardware configuration | ||
650 | fragment (``minnow.cfg``) specific to the Minnow BSP as well as several | ||
651 | more general configuration fragments and features enabling hardware | ||
652 | found on the machine. This ``minnow.scc`` description file is then | ||
653 | included in each of the three "minnow" description files for the | ||
654 | supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). | ||
655 | Consider the "minnow" description for the "standard" kernel type (i.e. | ||
656 | ``minnow-standard.scc``: | ||
657 | :: | ||
658 | |||
659 | define KMACHINE minnow | ||
660 | define KTYPE standard | ||
661 | define KARCH i386 | ||
662 | |||
663 | include ktypes/standard | ||
664 | |||
665 | include minnow.scc | ||
666 | |||
667 | # Extra minnow configs above the minimal defined in minnow.scc | ||
668 | include cfg/efi-ext.scc | ||
669 | include features/media/media-all.scc | ||
670 | include features/sound/snd_hda_intel.scc | ||
671 | |||
672 | # The following should really be in standard.scc | ||
673 | # USB live-image support | ||
674 | include cfg/usb-mass-storage.scc | ||
675 | include cfg/boot-live.scc | ||
676 | |||
677 | # Basic profiling | ||
678 | include features/latencytop/latencytop.scc | ||
679 | include features/profiling/profiling.scc | ||
680 | |||
681 | # Requested drivers that don't have an existing scc | ||
682 | kconf hardware minnow-drivers-extra.cfg | ||
683 | |||
684 | The ``include`` command midway through the file includes the ``minnow.scc`` description | ||
685 | that defines all enabled hardware for the BSP that is common to all | ||
686 | kernel types. Using this command significantly reduces duplication. | ||
687 | |||
688 | Now consider the "minnow" description for the "tiny" kernel type (i.e. | ||
689 | ``minnow-tiny.scc``): | ||
690 | :: | ||
691 | |||
692 | define KMACHINE minnow | ||
693 | define KTYPE tiny | ||
694 | define KARCH i386 | ||
695 | |||
696 | include ktypes/tiny | ||
697 | |||
698 | include minnow.scc | ||
699 | |||
700 | As you might expect, | ||
701 | the "tiny" description includes quite a bit less. In fact, it includes | ||
702 | only the minimal policy defined by the "tiny" kernel type and the | ||
703 | hardware-specific configuration required for booting the machine along | ||
704 | with the most basic functionality of the system as defined in the base | ||
705 | "minnow" description file. | ||
706 | |||
707 | Notice again the three critical variables: | ||
708 | :term:`KMACHINE`, | ||
709 | :term:`KTYPE`, and | ||
710 | :term:`KARCH`. Of these variables, only | ||
711 | ``KTYPE`` has changed to specify the "tiny" kernel type. | ||
712 | |||
713 | Kernel Metadata Location | ||
714 | ======================== | ||
715 | |||
716 | Kernel Metadata always exists outside of the kernel tree either defined | ||
717 | in a kernel recipe (recipe-space) or outside of the recipe. Where you | ||
718 | choose to define the Metadata depends on what you want to do and how you | ||
719 | intend to work. Regardless of where you define the kernel Metadata, the | ||
720 | syntax used applies equally. | ||
721 | |||
722 | If you are unfamiliar with the Linux kernel and only wish to apply a | ||
723 | configuration and possibly a couple of patches provided to you by | ||
724 | others, the recipe-space method is recommended. This method is also a | ||
725 | good approach if you are working with Linux kernel sources you do not | ||
726 | control or if you just do not want to maintain a Linux kernel Git | ||
727 | repository on your own. For partial information on how you can define | ||
728 | kernel Metadata in the recipe-space, see the "`Modifying an Existing | ||
729 | Recipe <#modifying-an-existing-recipe>`__" section. | ||
730 | |||
731 | Conversely, if you are actively developing a kernel and are already | ||
732 | maintaining a Linux kernel Git repository of your own, you might find it | ||
733 | more convenient to work with kernel Metadata kept outside the | ||
734 | recipe-space. Working with Metadata in this area can make iterative | ||
735 | development of the Linux kernel more efficient outside of the BitBake | ||
736 | environment. | ||
737 | |||
738 | Recipe-Space Metadata | ||
739 | --------------------- | ||
740 | |||
741 | When stored in recipe-space, the kernel Metadata files reside in a | ||
742 | directory hierarchy below | ||
743 | :term:`FILESEXTRAPATHS`. For | ||
744 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and | ||
745 | modifying | ||
746 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to | ||
747 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to | ||
748 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. | ||
749 | See the "`Modifying an Existing | ||
750 | Recipe <#modifying-an-existing-recipe>`__" section for more information. | ||
751 | |||
752 | Here is an example that shows a trivial tree of kernel Metadata stored | ||
753 | in recipe-space within a BSP layer: | ||
754 | :: | ||
755 | |||
756 | meta-my_bsp_layer/ | ||
757 | `-- recipes-kernel | ||
758 | `-- linux | ||
759 | `-- linux-yocto | ||
760 | |-- bsp-standard.scc | ||
761 | |-- bsp.cfg | ||
762 | `-- standard.cfg | ||
763 | |||
764 | When the Metadata is stored in recipe-space, you must take steps to | ||
765 | ensure BitBake has the necessary information to decide what files to | ||
766 | fetch and when they need to be fetched again. It is only necessary to | ||
767 | specify the ``.scc`` files on the | ||
768 | :term:`SRC_URI`. BitBake parses them | ||
769 | and fetches any files referenced in the ``.scc`` files by the | ||
770 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is | ||
771 | necessary to bump the recipe :term:`PR` | ||
772 | value when changing the content of files not explicitly listed in the | ||
773 | ``SRC_URI``. | ||
774 | |||
775 | If the BSP description is in recipe space, you cannot simply list the | ||
776 | ``*.scc`` in the ``SRC_URI`` statement. You need to use the following | ||
777 | form from your kernel append file: | ||
778 | :: | ||
779 | |||
780 | SRC_URI_append_myplatform = " \ | ||
781 | file://myplatform;type=kmeta;destsuffix=myplatform \ | ||
782 | " | ||
783 | |||
784 | Metadata Outside the Recipe-Space | ||
785 | --------------------------------- | ||
786 | |||
787 | When stored outside of the recipe-space, the kernel Metadata files | ||
788 | reside in a separate repository. The OpenEmbedded build system adds the | ||
789 | Metadata to the build as a "type=kmeta" repository through the | ||
790 | :term:`SRC_URI` variable. As an | ||
791 | example, consider the following ``SRC_URI`` statement from the | ||
792 | ``linux-yocto_4.12.bb`` kernel recipe: | ||
793 | :: | ||
794 | |||
795 | SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ | ||
796 | git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" | ||
797 | |||
798 | |||
799 | ``${KMETA}``, in this context, is simply used to name the directory into | ||
800 | which the Git fetcher places the Metadata. This behavior is no different | ||
801 | than any multi-repository ``SRC_URI`` statement used in a recipe (e.g. | ||
802 | see the previous section). | ||
803 | |||
804 | You can keep kernel Metadata in a "kernel-cache", which is a directory | ||
805 | containing configuration fragments. As with any Metadata kept outside | ||
806 | the recipe-space, you simply need to use the ``SRC_URI`` statement with | ||
807 | the "type=kmeta" attribute. Doing so makes the kernel Metadata available | ||
808 | during the configuration phase. | ||
809 | |||
810 | If you modify the Metadata, you must not forget to update the ``SRCREV`` | ||
811 | statements in the kernel's recipe. In particular, you need to update the | ||
812 | ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you | ||
813 | wish to use. Changing the data in these branches and not updating the | ||
814 | ``SRCREV`` statements to match will cause the build to fetch an older | ||
815 | commit. | ||
816 | |||
817 | Organizing Your Source | ||
818 | ====================== | ||
819 | |||
820 | Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux | ||
821 | kernel sources that have only a single branch - "master". This type of | ||
822 | repository structure is fine for linear development supporting a single | ||
823 | machine and architecture. However, if you work with multiple boards and | ||
824 | architectures, a kernel source repository with multiple branches is more | ||
825 | efficient. For example, suppose you need a series of patches for one | ||
826 | board to boot. Sometimes, these patches are works-in-progress or | ||
827 | fundamentally wrong, yet they are still necessary for specific boards. | ||
828 | In these situations, you most likely do not want to include these | ||
829 | patches in every kernel you build (i.e. have the patches as part of the | ||
830 | lone "master" branch). It is situations like these that give rise to | ||
831 | multiple branches used within a Linux kernel sources Git repository. | ||
832 | |||
833 | Repository organization strategies exist that maximize source reuse, | ||
834 | remove redundancy, and logically order your changes. This section | ||
835 | presents strategies for the following cases: | ||
836 | |||
837 | - Encapsulating patches in a feature description and only including the | ||
838 | patches in the BSP descriptions of the applicable boards. | ||
839 | |||
840 | - Creating a machine branch in your kernel source repository and | ||
841 | applying the patches on that branch only. | ||
842 | |||
843 | - Creating a feature branch in your kernel source repository and | ||
844 | merging that branch into your BSP when needed. | ||
845 | |||
846 | The approach you take is entirely up to you and depends on what works | ||
847 | best for your development model. | ||
848 | |||
849 | Encapsulating Patches | ||
850 | --------------------- | ||
851 | |||
852 | if you are reusing patches from an external tree and are not working on | ||
853 | the patches, you might find the encapsulated feature to be appropriate. | ||
854 | Given this scenario, you do not need to create any branches in the | ||
855 | source repository. Rather, you just take the static patches you need and | ||
856 | encapsulate them within a feature description. Once you have the feature | ||
857 | description, you simply include that into the BSP description as | ||
858 | described in the "`BSP Descriptions <#bsp-descriptions>`__" section. | ||
859 | |||
860 | You can find information on how to create patches and BSP descriptions | ||
861 | in the "`Patches <#patches>`__" and "`BSP | ||
862 | Descriptions <#bsp-descriptions>`__" sections. | ||
863 | |||
864 | Machine Branches | ||
865 | ---------------- | ||
866 | |||
867 | When you have multiple machines and architectures to support, or you are | ||
868 | actively working on board support, it is more efficient to create | ||
869 | branches in the repository based on individual machines. Having machine | ||
870 | branches allows common source to remain in the "master" branch with any | ||
871 | features specific to a machine stored in the appropriate machine branch. | ||
872 | This organization method frees you from continually reintegrating your | ||
873 | patches into a feature. | ||
874 | |||
875 | Once you have a new branch, you can set up your kernel Metadata to use | ||
876 | the branch a couple different ways. In the recipe, you can specify the | ||
877 | new branch as the ``KBRANCH`` to use for the board as follows: | ||
878 | :: | ||
879 | |||
880 | KBRANCH = "mynewbranch" | ||
881 | |||
882 | Another method is to use the ``branch`` command in the BSP | ||
883 | description: | ||
884 | |||
885 | mybsp.scc: | ||
886 | define KMACHINE mybsp | ||
887 | define KTYPE standard | ||
888 | define KARCH i386 | ||
889 | include standard.scc | ||
890 | |||
891 | branch mynewbranch | ||
892 | |||
893 | include mybsp-hw.scc | ||
894 | |||
895 | If you find yourself with numerous branches, you might consider using a | ||
896 | hierarchical branching system similar to what the Yocto Linux Kernel Git | ||
897 | repositories use: | ||
898 | :: | ||
899 | |||
900 | common/kernel_type/machine | ||
901 | |||
902 | If you had two kernel types, "standard" and "small" for instance, three | ||
903 | machines, and common as ``mydir``, the branches in your Git repository | ||
904 | might look like this: | ||
905 | : | ||
906 | |||
907 | mydir/base | ||
908 | mydir/standard/base | ||
909 | mydir/standard/machine_a | ||
910 | mydir/standard/machine_b | ||
911 | mydir/standard/machine_c | ||
912 | mydir/small/base | ||
913 | mydir/small/machine_a | ||
914 | |||
915 | This organization can help clarify the branch relationships. In this | ||
916 | case, ``mydir/standard/machine_a`` includes everything in ``mydir/base`` | ||
917 | and ``mydir/standard/base``. The "standard" and "small" branches add | ||
918 | sources specific to those kernel types that for whatever reason are not | ||
919 | appropriate for the other branches. | ||
920 | |||
921 | .. note:: | ||
922 | |||
923 | The "base" branches are an artifact of the way Git manages its data | ||
924 | internally on the filesystem: Git will not allow you to use | ||
925 | mydir/standard | ||
926 | and | ||
927 | mydir/standard/machine_a | ||
928 | because it would have to create a file and a directory named | ||
929 | "standard". | ||
930 | |||
931 | Feature Branches | ||
932 | ---------------- | ||
933 | |||
934 | When you are actively developing new features, it can be more efficient | ||
935 | to work with that feature as a branch, rather than as a set of patches | ||
936 | that have to be regularly updated. The Yocto Project Linux kernel tools | ||
937 | provide for this with the ``git merge`` command. | ||
938 | |||
939 | To merge a feature branch into a BSP, insert the ``git merge`` command | ||
940 | after any ``branch`` commands: | ||
941 | :: | ||
942 | |||
943 | mybsp.scc: | ||
944 | define KMACHINE mybsp | ||
945 | define KTYPE standard | ||
946 | define KARCH i386 | ||
947 | include standard.scc | ||
948 | |||
949 | branch mynewbranch | ||
950 | git merge myfeature | ||
951 | |||
952 | include mybsp-hw.scc | ||
953 | |||
954 | .. _scc-reference: | ||
955 | |||
956 | SCC Description File Reference | ||
957 | ============================== | ||
958 | |||
959 | This section provides a brief reference for the commands you can use | ||
960 | within an SCC description file (``.scc``): | ||
961 | |||
962 | - ``branch [ref]``: Creates a new branch relative to the current branch | ||
963 | (typically ``${KTYPE}``) using the currently checked-out branch, or | ||
964 | "ref" if specified. | ||
965 | |||
966 | - ``define``: Defines variables, such as | ||
967 | :term:`KMACHINE`, | ||
968 | :term:`KTYPE`, | ||
969 | :term:`KARCH`, and | ||
970 | :term:`KFEATURE_DESCRIPTION`. | ||
971 | |||
972 | - ``include SCC_FILE``: Includes an SCC file in the current file. The | ||
973 | file is parsed as if you had inserted it inline. | ||
974 | |||
975 | - ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration | ||
976 | fragment for merging into the final Linux ``.config`` file. | ||
977 | |||
978 | - ``git merge GIT_BRANCH``: Merges the feature branch into the current | ||
979 | branch. | ||
980 | |||
981 | - ``patch PATCH_FILE``: Applies the patch to the current Git branch. | ||
982 | |||
983 | |||
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 5c76ed2391..37177966bf 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='kernel-dev-advanced'> | 6 | <chapter id='kernel-dev-advanced'> |
6 | <title>Working with Advanced Metadata (<filename>yocto-kernel-cache</filename>)</title> | 7 | <title>Working with Advanced Metadata (<filename>yocto-kernel-cache</filename>)</title> |
diff --git a/documentation/kernel-dev/kernel-dev-common.rst b/documentation/kernel-dev/kernel-dev-common.rst new file mode 100644 index 0000000000..d4b60a9dc9 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-common.rst | |||
@@ -0,0 +1,2078 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ************ | ||
4 | Common Tasks | ||
5 | ************ | ||
6 | |||
7 | This chapter presents several common tasks you perform when you work | ||
8 | with the Yocto Project Linux kernel. These tasks include preparing your | ||
9 | host development system for kernel development, preparing a layer, | ||
10 | modifying an existing recipe, patching the kernel, configuring the | ||
11 | kernel, iterative development, working with your own sources, and | ||
12 | incorporating out-of-tree modules. | ||
13 | |||
14 | .. note:: | ||
15 | |||
16 | The examples presented in this chapter work with the Yocto Project | ||
17 | 2.4 Release and forward. | ||
18 | |||
19 | Preparing the Build Host to Work on the Kernel | ||
20 | ============================================== | ||
21 | |||
22 | Before you can do any kernel development, you need to be sure your build | ||
23 | host is set up to use the Yocto Project. For information on how to get | ||
24 | set up, see the ":doc:`../dev-manual/dev-manual-start`" section in | ||
25 | the Yocto Project Development Tasks Manual. Part of preparing the system | ||
26 | is creating a local Git repository of the | ||
27 | :term:`Source Directory` (``poky``) on your system. Follow the steps in the | ||
28 | ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" | ||
29 | section in the Yocto Project Development Tasks Manual to set up your | ||
30 | Source Directory. | ||
31 | |||
32 | .. note:: | ||
33 | |||
34 | Be sure you check out the appropriate development branch or you | ||
35 | create your local branch by checking out a specific tag to get the | ||
36 | desired version of Yocto Project. See the " | ||
37 | Checking Out by Branch in Poky | ||
38 | " and " | ||
39 | Checking Out by Tag in Poky | ||
40 | " sections in the Yocto Project Development Tasks Manual for more | ||
41 | information. | ||
42 | |||
43 | Kernel development is best accomplished using | ||
44 | :ref:`devtool <sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow>` | ||
45 | and not through traditional kernel workflow methods. The remainder of | ||
46 | this section provides information for both scenarios. | ||
47 | |||
48 | Getting Ready to Develop Using ``devtool`` | ||
49 | ------------------------------------------ | ||
50 | |||
51 | Follow these steps to prepare to update the kernel image using | ||
52 | ``devtool``. Completing this procedure leaves you with a clean kernel | ||
53 | image and ready to make modifications as described in the " | ||
54 | :ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`" | ||
55 | section: | ||
56 | |||
57 | 1. *Initialize the BitBake Environment:* Before building an extensible | ||
58 | SDK, you need to initialize the BitBake build environment by sourcing | ||
59 | the build environment script (i.e. :ref:`structure-core-script`): | ||
60 | :: | ||
61 | |||
62 | $ cd ~/poky | ||
63 | $ source oe-init-build-env | ||
64 | |||
65 | .. note:: | ||
66 | |||
67 | The previous commands assume the | ||
68 | Source Repositories | ||
69 | (i.e. | ||
70 | poky | ||
71 | ) have been cloned using Git and the local repository is named | ||
72 | "poky". | ||
73 | |||
74 | 2. *Prepare Your local.conf File:* By default, the | ||
75 | :term:`MACHINE` variable is set to | ||
76 | "qemux86-64", which is fine if you are building for the QEMU emulator | ||
77 | in 64-bit mode. However, if you are not, you need to set the | ||
78 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file | ||
79 | found in the | ||
80 | :term:`Build Directory` (i.e. | ||
81 | ``~/poky/build`` in this example). | ||
82 | |||
83 | Also, since you are preparing to work on the kernel image, you need | ||
84 | to set the | ||
85 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` | ||
86 | variable to include kernel modules. | ||
87 | |||
88 | In this example we wish to build for qemux86 so we must set the | ||
89 | ``MACHINE`` variable to "qemux86" and also add the "kernel-modules". | ||
90 | As described we do this by appending to ``conf/local.conf``: | ||
91 | :: | ||
92 | |||
93 | MACHINE = "qemux86" | ||
94 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" | ||
95 | |||
96 | 3. *Create a Layer for Patches:* You need to create a layer to hold | ||
97 | patches created for the kernel image. You can use the | ||
98 | ``bitbake-layers create-layer`` command as follows: | ||
99 | :: | ||
100 | |||
101 | $ cd ~/poky/build | ||
102 | $ bitbake-layers create-layer ../../meta-mylayer | ||
103 | NOTE: Starting bitbake server... | ||
104 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' | ||
105 | $ | ||
106 | |||
107 | .. note:: | ||
108 | |||
109 | For background information on working with common and BSP layers, | ||
110 | see the " | ||
111 | Understanding and Creating Layers | ||
112 | " section in the Yocto Project Development Tasks Manual and the " | ||
113 | BSP Layers | ||
114 | " section in the Yocto Project Board Support (BSP) Developer's | ||
115 | Guide, respectively. For information on how to use the | ||
116 | bitbake-layers create-layer | ||
117 | command to quickly set up a layer, see the " | ||
118 | Creating a General Layer Using the | ||
119 | bitbake-layers | ||
120 | Script | ||
121 | " section in the Yocto Project Development Tasks Manual. | ||
122 | |||
123 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed | ||
124 | when you created your layer, you need to add the layer to the | ||
125 | :term:`BBLAYERS` variable in the | ||
126 | ``bblayers.conf`` file as follows: | ||
127 | :: | ||
128 | |||
129 | $ cd ~/poky/build | ||
130 | $ bitbake-layers add-layer ../../meta-mylayer | ||
131 | NOTE: Starting bitbake server... | ||
132 | $ | ||
133 | |||
134 | 5. *Build the Extensible SDK:* Use BitBake to build the extensible SDK | ||
135 | specifically for use with images to be run using QEMU: | ||
136 | :: | ||
137 | |||
138 | $ cd ~/poky/build | ||
139 | $ bitbake core-image-minimal -c populate_sdk_ext | ||
140 | |||
141 | Once | ||
142 | the build finishes, you can find the SDK installer file (i.e. | ||
143 | ``*.sh`` file) in the following directory: | ||
144 | ~/poky/build/tmp/deploy/sdk For this example, the installer file is | ||
145 | named | ||
146 | ``poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-DISTRO.sh`` | ||
147 | |||
148 | 6. *Install the Extensible SDK:* Use the following command to install | ||
149 | the SDK. For this example, install the SDK in the default | ||
150 | ``~/poky_sdk`` directory: | ||
151 | :: | ||
152 | |||
153 | $ cd ~/poky/build/tmp/deploy/sdk | ||
154 | $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-3.1.2.sh | ||
155 | Poky (Yocto Project Reference Distro) Extensible SDK installer version 3.1.2 | ||
156 | ============================================================================ | ||
157 | Enter target directory for SDK (default: ~/poky_sdk): | ||
158 | You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y | ||
159 | Extracting SDK......................................done | ||
160 | Setting it up... | ||
161 | Extracting buildtools... | ||
162 | Preparing build system... | ||
163 | Parsing recipes: 100% |#################################################################| Time: 0:00:52 | ||
164 | Initializing tasks: 100% |############## ###############################################| Time: 0:00:04 | ||
165 | Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00 | ||
166 | Parsing recipes: 100% |#################################################################| Time: 0:00:33 | ||
167 | Initializing tasks: 100% |##############################################################| Time: 0:00:00 | ||
168 | done | ||
169 | SDK has been successfully set up and is ready to be used. | ||
170 | Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. | ||
171 | $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux | ||
172 | |||
173 | |||
174 | 7. *Set Up a New Terminal to Work With the Extensible SDK:* You must set | ||
175 | up a new terminal to work with the SDK. You cannot use the same | ||
176 | BitBake shell used to build the installer. | ||
177 | |||
178 | After opening a new shell, run the SDK environment setup script as | ||
179 | directed by the output from installing the SDK: | ||
180 | :: | ||
181 | |||
182 | $ source ~/poky_sdk/environment-setup-i586-poky-linux | ||
183 | "SDK environment now set up; additionally you may now run devtool to perform development tasks. | ||
184 | Run devtool --help for further details. | ||
185 | |||
186 | .. note:: | ||
187 | |||
188 | If you get a warning about attempting to use the extensible SDK in | ||
189 | an environment set up to run BitBake, you did not use a new shell. | ||
190 | |||
191 | 8. *Build the Clean Image:* The final step in preparing to work on the | ||
192 | kernel is to build an initial image using ``devtool`` in the new | ||
193 | terminal you just set up and initialized for SDK work: | ||
194 | :: | ||
195 | |||
196 | $ devtool build-image | ||
197 | Parsing recipes: 100% |##########################################| Time: 0:00:05 | ||
198 | Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors. | ||
199 | WARNING: No packages to add, building image core-image-minimal unmodified | ||
200 | Loading cache: 100% |############################################| Time: 0:00:00 | ||
201 | Loaded 1299 entries from dependency cache. | ||
202 | NOTE: Resolving any missing task queue dependencies | ||
203 | Initializing tasks: 100% |#######################################| Time: 0:00:07 | ||
204 | Checking sstate mirror object availability: 100% |###############| Time: 0:00:00 | ||
205 | NOTE: Executing SetScene Tasks | ||
206 | NOTE: Executing RunQueue Tasks | ||
207 | NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. | ||
208 | NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86 | ||
209 | |||
210 | If you were | ||
211 | building for actual hardware and not for emulation, you could flash | ||
212 | the image to a USB stick on ``/dev/sdd`` and boot your device. For an | ||
213 | example that uses a Minnowboard, see the | ||
214 | `TipsAndTricks/KernelDevelopmentWithEsdk <https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk>`__ | ||
215 | Wiki page. | ||
216 | |||
217 | At this point you have set up to start making modifications to the | ||
218 | kernel by using the extensible SDK. For a continued example, see the | ||
219 | ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`" | ||
220 | section. | ||
221 | |||
222 | Getting Ready for Traditional Kernel Development | ||
223 | ------------------------------------------------ | ||
224 | |||
225 | Getting ready for traditional kernel development using the Yocto Project | ||
226 | involves many of the same steps as described in the previous section. | ||
227 | However, you need to establish a local copy of the kernel source since | ||
228 | you will be editing these files. | ||
229 | |||
230 | Follow these steps to prepare to update the kernel image using | ||
231 | traditional kernel development flow with the Yocto Project. Completing | ||
232 | this procedure leaves you ready to make modifications to the kernel | ||
233 | source as described in the ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`" | ||
234 | section: | ||
235 | |||
236 | 1. *Initialize the BitBake Environment:* Before you can do anything | ||
237 | using BitBake, you need to initialize the BitBake build environment | ||
238 | by sourcing the build environment script (i.e. | ||
239 | :ref:`structure-core-script`). | ||
240 | Also, for this example, be sure that the local branch you have | ||
241 | checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If | ||
242 | you need to checkout out the &DISTRO_NAME; branch, see the | ||
243 | ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" | ||
244 | section in the Yocto Project Development Tasks Manual. | ||
245 | :: | ||
246 | |||
247 | $ cd ~/poky | ||
248 | $ git branch | ||
249 | master | ||
250 | * &DISTRO_NAME; | ||
251 | $ source oe-init-build-env | ||
252 | |||
253 | .. note:: | ||
254 | |||
255 | The previous commands assume the | ||
256 | Source Repositories | ||
257 | (i.e. | ||
258 | poky | ||
259 | ) have been cloned using Git and the local repository is named | ||
260 | "poky". | ||
261 | |||
262 | 2. *Prepare Your local.conf File:* By default, the | ||
263 | :term:`MACHINE` variable is set to | ||
264 | "qemux86-64", which is fine if you are building for the QEMU emulator | ||
265 | in 64-bit mode. However, if you are not, you need to set the | ||
266 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file | ||
267 | found in the | ||
268 | :term:`Build Directory` (i.e. | ||
269 | ``~/poky/build`` in this example). | ||
270 | |||
271 | Also, since you are preparing to work on the kernel image, you need | ||
272 | to set the | ||
273 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` | ||
274 | variable to include kernel modules. | ||
275 | |||
276 | In this example we wish to build for qemux86 so we must set the | ||
277 | ``MACHINE`` variable to "qemux86" and also add the "kernel-modules". | ||
278 | As described we do this by appending to ``conf/local.conf``: | ||
279 | :: | ||
280 | |||
281 | MACHINE = "qemux86" | ||
282 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" | ||
283 | |||
284 | 3. *Create a Layer for Patches:* You need to create a layer to hold | ||
285 | patches created for the kernel image. You can use the | ||
286 | ``bitbake-layers create-layer`` command as follows: | ||
287 | :: | ||
288 | |||
289 | $ cd ~/poky/build | ||
290 | $ bitbake-layers create-layer ../../meta-mylayer | ||
291 | NOTE: Starting bitbake server... | ||
292 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' | ||
293 | |||
294 | .. note:: | ||
295 | |||
296 | For background information on working with common and BSP layers, | ||
297 | see the " | ||
298 | Understanding and Creating Layers | ||
299 | " section in the Yocto Project Development Tasks Manual and the " | ||
300 | BSP Layers | ||
301 | " section in the Yocto Project Board Support (BSP) Developer's | ||
302 | Guide, respectively. For information on how to use the | ||
303 | bitbake-layers create-layer | ||
304 | command to quickly set up a layer, see the " | ||
305 | Creating a General Layer Using the | ||
306 | bitbake-layers | ||
307 | Script | ||
308 | " section in the Yocto Project Development Tasks Manual. | ||
309 | |||
310 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed | ||
311 | when you created your layer, you need to add the layer to the | ||
312 | :term:`BBLAYERS` variable in the | ||
313 | ``bblayers.conf`` file as follows: | ||
314 | :: | ||
315 | |||
316 | $ cd ~/poky/build | ||
317 | $ bitbake-layers add-layer ../../meta-mylayer | ||
318 | NOTE: Starting bitbake server ... | ||
319 | $ | ||
320 | |||
321 | 5. *Create a Local Copy of the Kernel Git Repository:* You can find Git | ||
322 | repositories of supported Yocto Project kernels organized under | ||
323 | "Yocto Linux Kernel" in the Yocto Project Source Repositories at | ||
324 | :yocto_git:`/`. | ||
325 | |||
326 | For simplicity, it is recommended that you create your copy of the | ||
327 | kernel Git repository outside of the | ||
328 | :term:`Source Directory`, which is | ||
329 | usually named ``poky``. Also, be sure you are in the | ||
330 | ``standard/base`` branch. | ||
331 | |||
332 | The following commands show how to create a local copy of the | ||
333 | ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch. | ||
334 | |||
335 | .. note:: | ||
336 | |||
337 | The | ||
338 | linux-yocto-4.12 | ||
339 | kernel can be used with the Yocto Project 2.4 release and forward. | ||
340 | You cannot use the | ||
341 | linux-yocto-4.12 | ||
342 | kernel with releases prior to Yocto Project 2.4: | ||
343 | |||
344 | :: | ||
345 | |||
346 | $ cd ~ | ||
347 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base | ||
348 | Cloning into 'linux-yocto-4.12'... | ||
349 | remote: Counting objects: 6097195, done. | ||
350 | remote: Compressing objects: 100% (901026/901026), done. | ||
351 | remote: Total 6097195 (delta 5152604), reused 6096847 (delta 5152256) | ||
352 | Receiving objects: 100% (6097195/6097195), 1.24 GiB | 7.81 MiB/s, done. | ||
353 | Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done. | ||
354 | Checking out files: 100% (59846/59846), done. | ||
355 | |||
356 | 6. *Create a Local Copy of the Kernel Cache Git Repository:* For | ||
357 | simplicity, it is recommended that you create your copy of the kernel | ||
358 | cache Git repository outside of the | ||
359 | :term:`Source Directory`, which is | ||
360 | usually named ``poky``. Also, for this example, be sure you are in | ||
361 | the ``yocto-4.12`` branch. | ||
362 | |||
363 | The following commands show how to create a local copy of the | ||
364 | ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch: | ||
365 | :: | ||
366 | |||
367 | $ cd ~ | ||
368 | $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 | ||
369 | Cloning into 'yocto-kernel-cache'... | ||
370 | remote: Counting objects: 22639, done. | ||
371 | remote: Compressing objects: 100% (9761/9761), done. | ||
372 | remote: Total 22639 (delta 12400), reused 22586 (delta 12347) | ||
373 | Receiving objects: 100% (22639/22639), 22.34 MiB | 6.27 MiB/s, done. | ||
374 | Resolving deltas: 100% (12400/12400), done. | ||
375 | Checking connectivity... done. | ||
376 | |||
377 | At this point, you are ready to start making modifications to the kernel | ||
378 | using traditional kernel development steps. For a continued example, see | ||
379 | the "`Using Traditional Kernel Development to Patch the | ||
380 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
381 | section. | ||
382 | |||
383 | Creating and Preparing a Layer | ||
384 | ============================== | ||
385 | |||
386 | If you are going to be modifying kernel recipes, it is recommended that | ||
387 | you create and prepare your own layer in which to do your work. Your | ||
388 | layer contains its own :term:`BitBake` | ||
389 | append files (``.bbappend``) and provides a convenient mechanism to | ||
390 | create your own recipe files (``.bb``) as well as store and use kernel | ||
391 | patch files. For background information on working with layers, see the | ||
392 | ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" | ||
393 | section in the Yocto Project Development Tasks Manual. | ||
394 | |||
395 | .. note:: | ||
396 | |||
397 | The Yocto Project comes with many tools that simplify tasks you need | ||
398 | to perform. One such tool is the | ||
399 | bitbake-layers create-layer | ||
400 | command, which simplifies creating a new layer. See the " | ||
401 | Creating a General Layer Using the | ||
402 | bitbake-layers | ||
403 | Script | ||
404 | " section in the Yocto Project Development Tasks Manual for | ||
405 | information on how to use this script to quick set up a new layer. | ||
406 | |||
407 | To better understand the layer you create for kernel development, the | ||
408 | following section describes how to create a layer without the aid of | ||
409 | tools. These steps assume creation of a layer named ``mylayer`` in your | ||
410 | home directory: | ||
411 | |||
412 | 1. *Create Structure*: Create the layer's structure: | ||
413 | :: | ||
414 | |||
415 | $ cd $HOME | ||
416 | $ mkdir meta-mylayer | ||
417 | $ mkdir meta-mylayer/conf | ||
418 | $ mkdir meta-mylayer/recipes-kernel | ||
419 | $ mkdir meta-mylayer/recipes-kernel/linux | ||
420 | $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto | ||
421 | |||
422 | The ``conf`` directory holds your configuration files, while the | ||
423 | ``recipes-kernel`` directory holds your append file and eventual | ||
424 | patch files. | ||
425 | |||
426 | 2. *Create the Layer Configuration File*: Move to the | ||
427 | ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as | ||
428 | follows: | ||
429 | :: | ||
430 | |||
431 | # We have a conf and classes directory, add to BBPATH | ||
432 | BBPATH .= ":${LAYERDIR}" | ||
433 | |||
434 | # We have recipes-* directories, add to BBFILES | ||
435 | BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ | ||
436 | ${LAYERDIR}/recipes-*/*/*.bbappend" | ||
437 | |||
438 | BBFILE_COLLECTIONS += "mylayer" | ||
439 | BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" | ||
440 | BBFILE_PRIORITY_mylayer = "5" | ||
441 | |||
442 | Notice ``mylayer`` as part of the last three statements. | ||
443 | |||
444 | 3. *Create the Kernel Recipe Append File*: Move to the | ||
445 | ``meta-mylayer/recipes-kernel/linux`` directory and create the | ||
446 | kernel's append file. This example uses the ``linux-yocto-4.12`` | ||
447 | kernel. Thus, the name of the append file is | ||
448 | ``linux-yocto_4.12.bbappend``: | ||
449 | :: | ||
450 | |||
451 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
452 | |||
453 | SRC_URI_append = " file://patch-file-one" | ||
454 | SRC_URI_append = " file://patch-file-two" | ||
455 | SRC_URI_append = " file://patch-file-three" | ||
456 | |||
457 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements | ||
458 | enable the OpenEmbedded build system to find patch files. For more | ||
459 | information on using append files, see the | ||
460 | ":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`" | ||
461 | section in the Yocto Project Development Tasks Manual. | ||
462 | |||
463 | Modifying an Existing Recipe | ||
464 | ============================ | ||
465 | |||
466 | In many cases, you can customize an existing linux-yocto recipe to meet | ||
467 | the needs of your project. Each release of the Yocto Project provides a | ||
468 | few Linux kernel recipes from which you can choose. These are located in | ||
469 | the :term:`Source Directory` in | ||
470 | ``meta/recipes-kernel/linux``. | ||
471 | |||
472 | Modifying an existing recipe can consist of the following: | ||
473 | |||
474 | - Creating the append file | ||
475 | |||
476 | - Applying patches | ||
477 | |||
478 | - Changing the configuration | ||
479 | |||
480 | Before modifying an existing recipe, be sure that you have created a | ||
481 | minimal, custom layer from which you can work. See the "`Creating and | ||
482 | Preparing a Layer <#creating-and-preparing-a-layer>`__" section for | ||
483 | information. | ||
484 | |||
485 | Creating the Append File | ||
486 | ------------------------ | ||
487 | |||
488 | You create this file in your custom layer. You also name it accordingly | ||
489 | based on the linux-yocto recipe you are using. For example, if you are | ||
490 | modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe, | ||
491 | the append file will typically be located as follows within your custom | ||
492 | layer: | ||
493 | :: | ||
494 | |||
495 | your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend | ||
496 | |||
497 | The append file should initially extend the | ||
498 | :term:`FILESPATH` search path by | ||
499 | prepending the directory that contains your files to the | ||
500 | :term:`FILESEXTRAPATHS` | ||
501 | variable as follows: | ||
502 | :: | ||
503 | |||
504 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
505 | |||
506 | The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` | ||
507 | expands to "linux-yocto" in the current directory for this example. If | ||
508 | you add any new files that modify the kernel recipe and you have | ||
509 | extended ``FILESPATH`` as described above, you must place the files in | ||
510 | your layer in the following area: | ||
511 | :: | ||
512 | |||
513 | your-layer/recipes-kernel/linux/linux-yocto/ | ||
514 | |||
515 | .. note:: | ||
516 | |||
517 | If you are working on a new machine Board Support Package (BSP), be | ||
518 | sure to refer to the | ||
519 | Yocto Project Board Support Package (BSP) Developer's Guide | ||
520 | . | ||
521 | |||
522 | As an example, consider the following append file used by the BSPs in | ||
523 | ``meta-yocto-bsp``: | ||
524 | :: | ||
525 | |||
526 | meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend | ||
527 | |||
528 | The following listing shows the file. Be aware that the actual commit ID | ||
529 | strings in this example listing might be different than the actual | ||
530 | strings in the file from the ``meta-yocto-bsp`` layer upstream. | ||
531 | :: | ||
532 | |||
533 | KBRANCH_genericx86 = "standard/base" | ||
534 | KBRANCH_genericx86-64 = "standard/base" | ||
535 | |||
536 | KMACHINE_genericx86 ?= "common-pc" | ||
537 | KMACHINE_genericx86-64 ?= "common-pc-64" | ||
538 | KBRANCH_edgerouter = "standard/edgerouter" | ||
539 | KBRANCH_beaglebone = "standard/beaglebone" | ||
540 | |||
541 | SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" | ||
542 | SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" | ||
543 | SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" | ||
544 | SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" | ||
545 | |||
546 | |||
547 | COMPATIBLE_MACHINE_genericx86 = "genericx86" | ||
548 | COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" | ||
549 | COMPATIBLE_MACHINE_edgerouter = "edgerouter" | ||
550 | COMPATIBLE_MACHINE_beaglebone = "beaglebone" | ||
551 | |||
552 | LINUX_VERSION_genericx86 = "4.12.7" | ||
553 | LINUX_VERSION_genericx86-64 = "4.12.7" | ||
554 | LINUX_VERSION_edgerouter = "4.12.10" | ||
555 | LINUX_VERSION_beaglebone = "4.12.10" | ||
556 | |||
557 | This append file | ||
558 | contains statements used to support several BSPs that ship with the | ||
559 | Yocto Project. The file defines machines using the | ||
560 | :term:`COMPATIBLE_MACHINE` | ||
561 | variable and uses the | ||
562 | :term:`KMACHINE` variable to ensure | ||
563 | the machine name used by the OpenEmbedded build system maps to the | ||
564 | machine name used by the Linux Yocto kernel. The file also uses the | ||
565 | optional :term:`KBRANCH` variable to | ||
566 | ensure the build process uses the appropriate kernel branch. | ||
567 | |||
568 | Although this particular example does not use it, the | ||
569 | :term:`KERNEL_FEATURES` | ||
570 | variable could be used to enable features specific to the kernel. The | ||
571 | append file points to specific commits in the | ||
572 | :term:`Source Directory` Git repository and | ||
573 | the ``meta`` Git repository branches to identify the exact kernel needed | ||
574 | to build the BSP. | ||
575 | |||
576 | One thing missing in this particular BSP, which you will typically need | ||
577 | when developing a BSP, is the kernel configuration file (``.config``) | ||
578 | for your BSP. When developing a BSP, you probably have a kernel | ||
579 | configuration file or a set of kernel configuration files that, when | ||
580 | taken together, define the kernel configuration for your BSP. You can | ||
581 | accomplish this definition by putting the configurations in a file or a | ||
582 | set of files inside a directory located at the same level as your | ||
583 | kernel's append file and having the same name as the kernel's main | ||
584 | recipe file. With all these conditions met, simply reference those files | ||
585 | in the :term:`SRC_URI` statement in | ||
586 | the append file. | ||
587 | |||
588 | For example, suppose you had some configuration options in a file called | ||
589 | ``network_configs.cfg``. You can place that file inside a directory | ||
590 | named ``linux-yocto`` and then add a ``SRC_URI`` statement such as the | ||
591 | following to the append file. When the OpenEmbedded build system builds | ||
592 | the kernel, the configuration options are picked up and applied. | ||
593 | :: | ||
594 | |||
595 | SRC_URI += "file://network_configs.cfg" | ||
596 | |||
597 | To group related configurations into multiple files, you perform a | ||
598 | similar procedure. Here is an example that groups separate | ||
599 | configurations specifically for Ethernet and graphics into their own | ||
600 | files and adds the configurations by using a ``SRC_URI`` statement like | ||
601 | the following in your append file: | ||
602 | :: | ||
603 | |||
604 | SRC_URI += "file://myconfig.cfg \ | ||
605 | file://eth.cfg \ | ||
606 | file://gfx.cfg" | ||
607 | |||
608 | Another variable you can use in your kernel recipe append file is the | ||
609 | :term:`FILESEXTRAPATHS` | ||
610 | variable. When you use this statement, you are extending the locations | ||
611 | used by the OpenEmbedded system to look for files and patches as the | ||
612 | recipe is processed. | ||
613 | |||
614 | .. note:: | ||
615 | |||
616 | Other methods exist to accomplish grouping and defining configuration | ||
617 | options. For example, if you are working with a local clone of the | ||
618 | kernel repository, you could checkout the kernel's ``meta`` branch, | ||
619 | make your changes, and then push the changes to the local bare clone | ||
620 | of the kernel. The result is that you directly add configuration | ||
621 | options to the ``meta`` branch for your BSP. The configuration | ||
622 | options will likely end up in that location anyway if the BSP gets | ||
623 | added to the Yocto Project. | ||
624 | |||
625 | In general, however, the Yocto Project maintainers take care of | ||
626 | moving the ``SRC_URI``-specified configuration options to the | ||
627 | kernel's ``meta`` branch. Not only is it easier for BSP developers to | ||
628 | not have to worry about putting those configurations in the branch, | ||
629 | but having the maintainers do it allows them to apply 'global' | ||
630 | knowledge about the kinds of common configuration options multiple | ||
631 | BSPs in the tree are typically using. This allows for promotion of | ||
632 | common configurations into common features. | ||
633 | |||
634 | Applying Patches | ||
635 | ---------------- | ||
636 | |||
637 | If you have a single patch or a small series of patches that you want to | ||
638 | apply to the Linux kernel source, you can do so just as you would with | ||
639 | any other recipe. You first copy the patches to the path added to | ||
640 | :term:`FILESEXTRAPATHS` in | ||
641 | your ``.bbappend`` file as described in the previous section, and then | ||
642 | reference them in :term:`SRC_URI` | ||
643 | statements. | ||
644 | |||
645 | For example, you can apply a three-patch series by adding the following | ||
646 | lines to your linux-yocto ``.bbappend`` file in your layer: | ||
647 | :: | ||
648 | |||
649 | SRC_URI += "file://0001-first-change.patch" | ||
650 | SRC_URI += "file://0002-second-change.patch" | ||
651 | SRC_URI += "file://0003-third-change.patch" | ||
652 | |||
653 | The next time you run BitBake to build | ||
654 | the Linux kernel, BitBake detects the change in the recipe and fetches | ||
655 | and applies the patches before building the kernel. | ||
656 | |||
657 | For a detailed example showing how to patch the kernel using | ||
658 | ``devtool``, see the | ||
659 | ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`" | ||
660 | and | ||
661 | ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`" | ||
662 | sections. | ||
663 | |||
664 | Changing the Configuration | ||
665 | -------------------------- | ||
666 | |||
667 | You can make wholesale or incremental changes to the final ``.config`` | ||
668 | file used for the eventual Linux kernel configuration by including a | ||
669 | ``defconfig`` file and by specifying configuration fragments in the | ||
670 | :term:`SRC_URI` to be applied to that | ||
671 | file. | ||
672 | |||
673 | If you have a complete, working Linux kernel ``.config`` file you want | ||
674 | to use for the configuration, as before, copy that file to the | ||
675 | appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` | ||
676 | directory, and rename the copied file to "defconfig". Then, add the | ||
677 | following lines to the linux-yocto ``.bbappend`` file in your layer: | ||
678 | :: | ||
679 | |||
680 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
681 | SRC_URI += "file://defconfig" | ||
682 | |||
683 | The ``SRC_URI`` tells the build system how to search | ||
684 | for the file, while the | ||
685 | :term:`FILESEXTRAPATHS` | ||
686 | extends the :term:`FILESPATH` | ||
687 | variable (search directories) to include the ``${PN}`` directory you | ||
688 | created to hold the configuration changes. | ||
689 | |||
690 | .. note:: | ||
691 | |||
692 | The build system applies the configurations from the | ||
693 | defconfig | ||
694 | file before applying any subsequent configuration fragments. The | ||
695 | final kernel configuration is a combination of the configurations in | ||
696 | the | ||
697 | defconfig | ||
698 | file and any configuration fragments you provide. You need to realize | ||
699 | that if you have any configuration fragments, the build system | ||
700 | applies these on top of and after applying the existing | ||
701 | defconfig | ||
702 | file configurations. | ||
703 | |||
704 | Generally speaking, the preferred approach is to determine the | ||
705 | incremental change you want to make and add that as a configuration | ||
706 | fragment. For example, if you want to add support for a basic serial | ||
707 | console, create a file named ``8250.cfg`` in the ``${PN}`` directory | ||
708 | with the following content (without indentation): | ||
709 | :: | ||
710 | |||
711 | CONFIG_SERIAL_8250=y | ||
712 | CONFIG_SERIAL_8250_CONSOLE=y | ||
713 | CONFIG_SERIAL_8250_PCI=y | ||
714 | CONFIG_SERIAL_8250_NR_UARTS=4 | ||
715 | CONFIG_SERIAL_8250_RUNTIME_UARTS=4 | ||
716 | CONFIG_SERIAL_CORE=y | ||
717 | CONFIG_SERIAL_CORE_CONSOLE=y | ||
718 | |||
719 | Next, include this | ||
720 | configuration fragment and extend the ``FILESPATH`` variable in your | ||
721 | ``.bbappend`` file: | ||
722 | :: | ||
723 | |||
724 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
725 | SRC_URI += "file://8250.cfg" | ||
726 | |||
727 | The next time you run BitBake to build the | ||
728 | Linux kernel, BitBake detects the change in the recipe and fetches and | ||
729 | applies the new configuration before building the kernel. | ||
730 | |||
731 | For a detailed example showing how to configure the kernel, see the | ||
732 | "`Configuring the Kernel <#configuring-the-kernel>`__" section. | ||
733 | |||
734 | Using an "In-Tree" ``defconfig`` File | ||
735 | -------------------------------------- | ||
736 | |||
737 | It might be desirable to have kernel configuration fragment support | ||
738 | through a ``defconfig`` file that is pulled from the kernel source tree | ||
739 | for the configured machine. By default, the OpenEmbedded build system | ||
740 | looks for ``defconfig`` files in the layer used for Metadata, which is | ||
741 | "out-of-tree", and then configures them using the following: | ||
742 | :: | ||
743 | |||
744 | SRC_URI += "file://defconfig" | ||
745 | |||
746 | If you do not want to maintain copies of | ||
747 | ``defconfig`` files in your layer but would rather allow users to use | ||
748 | the default configuration from the kernel tree and still be able to add | ||
749 | configuration fragments to the | ||
750 | :term:`SRC_URI` through, for example, | ||
751 | append files, you can direct the OpenEmbedded build system to use a | ||
752 | ``defconfig`` file that is "in-tree". | ||
753 | |||
754 | To specify an "in-tree" ``defconfig`` file, use the following statement | ||
755 | form: | ||
756 | :: | ||
757 | |||
758 | KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file | ||
759 | |||
760 | Here is an example | ||
761 | that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2" | ||
762 | and provides the path to the "in-tree" ``defconfig`` file to be used for | ||
763 | a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset: | ||
764 | :: | ||
765 | |||
766 | KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig" | ||
767 | |||
768 | Aside from modifying your kernel recipe and providing your own | ||
769 | ``defconfig`` file, you need to be sure no files or statements set | ||
770 | ``SRC_URI`` to use a ``defconfig`` other than your "in-tree" file (e.g. | ||
771 | a kernel's ``linux-``\ machine\ ``.inc`` file). In other words, if the | ||
772 | build system detects a statement that identifies an "out-of-tree" | ||
773 | ``defconfig`` file, that statement will override your | ||
774 | ``KBUILD_DEFCONFIG`` variable. | ||
775 | |||
776 | See the | ||
777 | :term:`KBUILD_DEFCONFIG` | ||
778 | variable description for more information. | ||
779 | |||
780 | Using ``devtool`` to Patch the Kernel | ||
781 | ===================================== | ||
782 | |||
783 | The steps in this procedure show you how you can patch the kernel using | ||
784 | the extensible SDK and ``devtool``. | ||
785 | |||
786 | .. note:: | ||
787 | |||
788 | Before attempting this procedure, be sure you have performed the | ||
789 | steps to get ready for updating the kernel as described in the " | ||
790 | Getting Ready to Develop Using | ||
791 | devtool | ||
792 | " section. | ||
793 | |||
794 | Patching the kernel involves changing or adding configurations to an | ||
795 | existing kernel, changing or adding recipes to the kernel that are | ||
796 | needed to support specific hardware features, or even altering the | ||
797 | source code itself. | ||
798 | |||
799 | This example creates a simple patch by adding some QEMU emulator console | ||
800 | output at boot time through ``printk`` statements in the kernel's | ||
801 | ``calibrate.c`` source code file. Applying the patch and booting the | ||
802 | modified image causes the added messages to appear on the emulator's | ||
803 | console. The example is a continuation of the setup procedure found in | ||
804 | the ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devtool\`\``" Section. | ||
805 | |||
806 | 1. *Check Out the Kernel Source Files:* First you must use ``devtool`` | ||
807 | to checkout the kernel source code in its workspace. Be sure you are | ||
808 | in the terminal set up to do work with the extensible SDK. | ||
809 | |||
810 | .. note:: | ||
811 | |||
812 | See this | ||
813 | step | ||
814 | in the " | ||
815 | Getting Ready to Develop Using | ||
816 | devtool | ||
817 | " section for more information. | ||
818 | |||
819 | Use the following ``devtool`` command to check out the code: | ||
820 | :: | ||
821 | |||
822 | $ devtool modify linux-yocto | ||
823 | |||
824 | .. note:: | ||
825 | |||
826 | During the checkout operation, a bug exists that could cause | ||
827 | errors such as the following to appear: | ||
828 | :: | ||
829 | |||
830 | ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus | ||
831 | be3a89ce7c47178880ba7bf6293d7404 for | ||
832 | /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack | ||
833 | |||
834 | |||
835 | You can safely ignore these messages. The source code is correctly | ||
836 | checked out. | ||
837 | |||
838 | 2. *Edit the Source Files* Follow these steps to make some simple | ||
839 | changes to the source files: | ||
840 | |||
841 | 1. *Change the working directory*: In the previous step, the output | ||
842 | noted where you can find the source files (e.g. | ||
843 | ``~/poky_sdk/workspace/sources/linux-yocto``). Change to where the | ||
844 | kernel source code is before making your edits to the | ||
845 | ``calibrate.c`` file: | ||
846 | :: | ||
847 | |||
848 | $ cd ~/poky_sdk/workspace/sources/linux-yocto | ||
849 | |||
850 | 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have | ||
851 | the following changes: | ||
852 | :: | ||
853 | |||
854 | void calibrate_delay(void) | ||
855 | { | ||
856 | unsigned long lpj; | ||
857 | static bool printed; | ||
858 | int this_cpu = smp_processor_id(); | ||
859 | |||
860 | printk("*************************************\n"); | ||
861 | printk("* *\n"); | ||
862 | printk("* HELLO YOCTO KERNEL *\n"); | ||
863 | printk("* *\n"); | ||
864 | printk("*************************************\n"); | ||
865 | |||
866 | if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { | ||
867 | . | ||
868 | . | ||
869 | . | ||
870 | |||
871 | 3. *Build the Updated Kernel Source:* To build the updated kernel | ||
872 | source, use ``devtool``: | ||
873 | :: | ||
874 | |||
875 | $ devtool build linux-yocto | ||
876 | |||
877 | 4. *Create the Image With the New Kernel:* Use the | ||
878 | ``devtool build-image`` command to create a new image that has the | ||
879 | new kernel. | ||
880 | |||
881 | .. note:: | ||
882 | |||
883 | If the image you originally created resulted in a Wic file, you | ||
884 | can use an alternate method to create the new image with the | ||
885 | updated kernel. For an example, see the steps in the | ||
886 | TipsAndTricks/KernelDevelopmentWithEsdk | ||
887 | Wiki Page. | ||
888 | |||
889 | :: | ||
890 | |||
891 | $ cd ~ | ||
892 | $ devtool build-image core-image-minimal | ||
893 | |||
894 | 5. *Test the New Image:* For this example, you can run the new image | ||
895 | using QEMU to verify your changes: | ||
896 | |||
897 | 1. *Boot the image*: Boot the modified image in the QEMU emulator | ||
898 | using this command: | ||
899 | :: | ||
900 | |||
901 | $ runqemu qemux86 | ||
902 | |||
903 | 2. *Verify the changes*: Log into the machine using ``root`` with no | ||
904 | password and then use the following shell command to scroll | ||
905 | through the console's boot output. | ||
906 | :: | ||
907 | |||
908 | # dmesg | less | ||
909 | |||
910 | You should see | ||
911 | the results of your ``printk`` statements as part of the output | ||
912 | when you scroll down the console window. | ||
913 | |||
914 | 6. *Stage and commit your changes*: Within your eSDK terminal, change | ||
915 | your working directory to where you modified the ``calibrate.c`` file | ||
916 | and use these Git commands to stage and commit your changes: | ||
917 | :: | ||
918 | |||
919 | $ cd ~/poky_sdk/workspace/sources/linux-yocto | ||
920 | $ git status | ||
921 | $ git add init/calibrate.c | ||
922 | $ git commit -m "calibrate: Add printk example" | ||
923 | |||
924 | 7. *Export the Patches and Create an Append File:* To export your | ||
925 | commits as patches and create a ``.bbappend`` file, use the following | ||
926 | command in the terminal used to work with the extensible SDK. This | ||
927 | example uses the previously established layer named ``meta-mylayer``. | ||
928 | |||
929 | .. note:: | ||
930 | |||
931 | See Step 3 of the " | ||
932 | Getting Ready to Develop Using devtool | ||
933 | " section for information on setting up this layer. | ||
934 | |||
935 | $ devtool finish linux-yocto ~/meta-mylayer | ||
936 | |||
937 | Once the command | ||
938 | finishes, the patches and the ``.bbappend`` file are located in the | ||
939 | ``~/meta-mylayer/recipes-kernel/linux`` directory. | ||
940 | |||
941 | 8. *Build the Image With Your Modified Kernel:* You can now build an | ||
942 | image that includes your kernel patches. Execute the following | ||
943 | command from your | ||
944 | :term:`Build Directory` in the terminal | ||
945 | set up to run BitBake: | ||
946 | :: | ||
947 | |||
948 | $ cd ~/poky/build | ||
949 | $ bitbake core-image-minimal | ||
950 | |||
951 | Using Traditional Kernel Development to Patch the Kernel | ||
952 | ======================================================== | ||
953 | |||
954 | The steps in this procedure show you how you can patch the kernel using | ||
955 | traditional kernel development (i.e. not using ``devtool`` and the | ||
956 | extensible SDK as described in the | ||
957 | ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`" | ||
958 | section). | ||
959 | |||
960 | .. note:: | ||
961 | |||
962 | Before attempting this procedure, be sure you have performed the | ||
963 | steps to get ready for updating the kernel as described in the " | ||
964 | Getting Ready for Traditional Kernel Development | ||
965 | " section. | ||
966 | |||
967 | Patching the kernel involves changing or adding configurations to an | ||
968 | existing kernel, changing or adding recipes to the kernel that are | ||
969 | needed to support specific hardware features, or even altering the | ||
970 | source code itself. | ||
971 | |||
972 | The example in this section creates a simple patch by adding some QEMU | ||
973 | emulator console output at boot time through ``printk`` statements in | ||
974 | the kernel's ``calibrate.c`` source code file. Applying the patch and | ||
975 | booting the modified image causes the added messages to appear on the | ||
976 | emulator's console. The example is a continuation of the setup procedure | ||
977 | found in the "`Getting Ready for Traditional Kernel | ||
978 | Development <#getting-ready-for-traditional-kernel-development>`__" | ||
979 | Section. | ||
980 | |||
981 | 1. *Edit the Source Files* Prior to this step, you should have used Git | ||
982 | to create a local copy of the repository for your kernel. Assuming | ||
983 | you created the repository as directed in the "`Getting Ready for | ||
984 | Traditional Kernel | ||
985 | Development <#getting-ready-for-traditional-kernel-development>`__" | ||
986 | section, use the following commands to edit the ``calibrate.c`` file: | ||
987 | |||
988 | 1. *Change the working directory*: You need to locate the source | ||
989 | files in the local copy of the kernel Git repository: Change to | ||
990 | where the kernel source code is before making your edits to the | ||
991 | ``calibrate.c`` file: | ||
992 | :: | ||
993 | |||
994 | $ cd ~/linux-yocto-4.12/init | ||
995 | |||
996 | 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the | ||
997 | following changes: | ||
998 | :: | ||
999 | |||
1000 | void calibrate_delay(void) | ||
1001 | { | ||
1002 | unsigned long lpj; | ||
1003 | static bool printed; | ||
1004 | int this_cpu = smp_processor_id(); | ||
1005 | |||
1006 | printk("*************************************\n"); | ||
1007 | printk("* *\n"); | ||
1008 | printk("* HELLO YOCTO KERNEL *\n"); | ||
1009 | printk("* *\n"); | ||
1010 | printk("*************************************\n"); | ||
1011 | |||
1012 | if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { | ||
1013 | . | ||
1014 | . | ||
1015 | . | ||
1016 | |||
1017 | 2. *Stage and Commit Your Changes:* Use standard Git commands to stage | ||
1018 | and commit the changes you just made: | ||
1019 | :: | ||
1020 | |||
1021 | $ git add calibrate.c | ||
1022 | $ git commit -m "calibrate.c - Added some printk statements" | ||
1023 | |||
1024 | If you do not | ||
1025 | stage and commit your changes, the OpenEmbedded Build System will not | ||
1026 | pick up the changes. | ||
1027 | |||
1028 | 3. *Update Your local.conf File to Point to Your Source Files:* In | ||
1029 | addition to your ``local.conf`` file specifying to use | ||
1030 | "kernel-modules" and the "qemux86" machine, it must also point to the | ||
1031 | updated kernel source files. Add | ||
1032 | :term:`SRC_URI` and | ||
1033 | :term:`SRCREV` statements similar | ||
1034 | to the following to your ``local.conf``: | ||
1035 | :: | ||
1036 | |||
1037 | $ cd ~/poky/build/conf | ||
1038 | |||
1039 | Add the following to the ``local.conf``: | ||
1040 | :: | ||
1041 | |||
1042 | SRC_URI_pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ | ||
1043 | git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" | ||
1044 | SRCREV_meta_qemux86 = "${AUTOREV}" | ||
1045 | SRCREV_machine_qemux86 = "${AUTOREV}" | ||
1046 | |||
1047 | .. note:: | ||
1048 | |||
1049 | Be sure to replace | ||
1050 | path-to | ||
1051 | with the pathname to your local Git repositories. Also, you must | ||
1052 | be sure to specify the correct branch and machine types. For this | ||
1053 | example, the branch is | ||
1054 | standard/base | ||
1055 | and the machine is "qemux86". | ||
1056 | |||
1057 | 4. *Build the Image:* With the source modified, your changes staged and | ||
1058 | committed, and the ``local.conf`` file pointing to the kernel files, | ||
1059 | you can now use BitBake to build the image: | ||
1060 | :: | ||
1061 | |||
1062 | $ cd ~/poky/build | ||
1063 | $ bitbake core-image-minimal | ||
1064 | |||
1065 | 5. *Boot the image*: Boot the modified image in the QEMU emulator using | ||
1066 | this command. When prompted to login to the QEMU console, use "root" | ||
1067 | with no password: | ||
1068 | :: | ||
1069 | |||
1070 | $ cd ~/poky/build | ||
1071 | $ runqemu qemux86 | ||
1072 | |||
1073 | 6. *Look for Your Changes:* As QEMU booted, you might have seen your | ||
1074 | changes rapidly scroll by. If not, use these commands to see your | ||
1075 | changes: | ||
1076 | :: | ||
1077 | |||
1078 | # dmesg | less | ||
1079 | |||
1080 | You should see the results of your | ||
1081 | ``printk`` statements as part of the output when you scroll down the | ||
1082 | console window. | ||
1083 | |||
1084 | 7. *Generate the Patch File:* Once you are sure that your patch works | ||
1085 | correctly, you can generate a ``*.patch`` file in the kernel source | ||
1086 | repository: | ||
1087 | :: | ||
1088 | |||
1089 | $ cd ~/linux-yocto-4.12/init | ||
1090 | $ git format-patch -1 | ||
1091 | 0001-calibrate.c-Added-some-printk-statements.patch | ||
1092 | |||
1093 | 8. *Move the Patch File to Your Layer:* In order for subsequent builds | ||
1094 | to pick up patches, you need to move the patch file you created in | ||
1095 | the previous step to your layer ``meta-mylayer``. For this example, | ||
1096 | the layer created earlier is located in your home directory as | ||
1097 | ``meta-mylayer``. When the layer was created using the | ||
1098 | ``yocto-create`` script, no additional hierarchy was created to | ||
1099 | support patches. Before moving the patch file, you need to add | ||
1100 | additional structure to your layer using the following commands: | ||
1101 | :: | ||
1102 | |||
1103 | $ cd ~/meta-mylayer | ||
1104 | $ mkdir recipes-kernel | ||
1105 | $ mkdir recipes-kernel/linux | ||
1106 | $ mkdir recipes-kernel/linux/linux-yocto | ||
1107 | |||
1108 | Once you have created this | ||
1109 | hierarchy in your layer, you can move the patch file using the | ||
1110 | following command: | ||
1111 | :: | ||
1112 | |||
1113 | $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto | ||
1114 | |||
1115 | 9. *Create the Append File:* Finally, you need to create the | ||
1116 | ``linux-yocto_4.12.bbappend`` file and insert statements that allow | ||
1117 | the OpenEmbedded build system to find the patch. The append file | ||
1118 | needs to be in your layer's ``recipes-kernel/linux`` directory and it | ||
1119 | must be named ``linux-yocto_4.12.bbappend`` and have the following | ||
1120 | contents: | ||
1121 | :: | ||
1122 | |||
1123 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
1124 | SRC_URI_append = "file://0001-calibrate.c-Added-some-printk-statements.patch" | ||
1125 | |||
1126 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements | ||
1127 | enable the OpenEmbedded build system to find the patch file. | ||
1128 | |||
1129 | For more information on append files and patches, see the "`Creating | ||
1130 | the Append File <#creating-the-append-file>`__" and "`Applying | ||
1131 | Patches <#applying-patches>`__" sections. You can also see the | ||
1132 | ":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`" | ||
1133 | section in the Yocto Project Development Tasks Manual. | ||
1134 | |||
1135 | .. note:: | ||
1136 | |||
1137 | To build | ||
1138 | core-image-minimal | ||
1139 | again and see the effects of your patch, you can essentially | ||
1140 | eliminate the temporary source files saved in | ||
1141 | poky/build/tmp/work/... | ||
1142 | and residual effects of the build by entering the following | ||
1143 | sequence of commands: | ||
1144 | :: | ||
1145 | |||
1146 | $ cd ~/poky/build | ||
1147 | $ bitbake -c cleanall yocto-linux | ||
1148 | $ bitbake core-image-minimal -c cleanall | ||
1149 | $ bitbake core-image-minimal | ||
1150 | $ runqemu qemux86 | ||
1151 | |||
1152 | |||
1153 | Configuring the Kernel | ||
1154 | ====================== | ||
1155 | |||
1156 | Configuring the Yocto Project kernel consists of making sure the | ||
1157 | ``.config`` file has all the right information in it for the image you | ||
1158 | are building. You can use the ``menuconfig`` tool and configuration | ||
1159 | fragments to make sure your ``.config`` file is just how you need it. | ||
1160 | You can also save known configurations in a ``defconfig`` file that the | ||
1161 | build system can use for kernel configuration. | ||
1162 | |||
1163 | This section describes how to use ``menuconfig``, create and use | ||
1164 | configuration fragments, and how to interactively modify your | ||
1165 | ``.config`` file to create the leanest kernel configuration file | ||
1166 | possible. | ||
1167 | |||
1168 | For more information on kernel configuration, see the "`Changing the | ||
1169 | Configuration <#changing-the-configuration>`__" section. | ||
1170 | |||
1171 | Using ``menuconfig`` | ||
1172 | --------------------- | ||
1173 | |||
1174 | The easiest way to define kernel configurations is to set them through | ||
1175 | the ``menuconfig`` tool. This tool provides an interactive method with | ||
1176 | which to set kernel configurations. For general information on | ||
1177 | ``menuconfig``, see http://en.wikipedia.org/wiki/Menuconfig. | ||
1178 | |||
1179 | To use the ``menuconfig`` tool in the Yocto Project development | ||
1180 | environment, you must do the following: | ||
1181 | |||
1182 | - Because you launch ``menuconfig`` using BitBake, you must be sure to | ||
1183 | set up your environment by running the | ||
1184 | :ref:`structure-core-script` script found in | ||
1185 | the :term:`Build Directory`. | ||
1186 | |||
1187 | - You must be sure of the state of your build's configuration in the | ||
1188 | :term:`Source Directory`. | ||
1189 | |||
1190 | - Your build host must have the following two packages installed: | ||
1191 | :: | ||
1192 | |||
1193 | libncurses5-dev | ||
1194 | libtinfo-dev | ||
1195 | |||
1196 | The following commands initialize the BitBake environment, run the | ||
1197 | :ref:`ref-tasks-kernel_configme` | ||
1198 | task, and launch ``menuconfig``. These commands assume the Source | ||
1199 | Directory's top-level folder is ``~/poky``: | ||
1200 | :: | ||
1201 | |||
1202 | $ cd poky | ||
1203 | $ source oe-init-build-env | ||
1204 | $ bitbake linux-yocto -c kernel_configme -f | ||
1205 | $ bitbake linux-yocto -c menuconfig | ||
1206 | |||
1207 | Once ``menuconfig`` comes up, its standard | ||
1208 | interface allows you to interactively examine and configure all the | ||
1209 | kernel configuration parameters. After making your changes, simply exit | ||
1210 | the tool and save your changes to create an updated version of the | ||
1211 | ``.config`` configuration file. | ||
1212 | |||
1213 | .. note:: | ||
1214 | |||
1215 | You can use the entire | ||
1216 | .config | ||
1217 | file as the | ||
1218 | defconfig | ||
1219 | file. For information on | ||
1220 | defconfig | ||
1221 | files, see the " | ||
1222 | Changing the Configuration | ||
1223 | ", " | ||
1224 | Using an In-Tree | ||
1225 | defconfig | ||
1226 | File | ||
1227 | , and " | ||
1228 | Creating a | ||
1229 | defconfig | ||
1230 | File | ||
1231 | " sections. | ||
1232 | |||
1233 | Consider an example that configures the "CONFIG_SMP" setting for the | ||
1234 | ``linux-yocto-4.12`` kernel. | ||
1235 | |||
1236 | .. note:: | ||
1237 | |||
1238 | The OpenEmbedded build system recognizes this kernel as | ||
1239 | linux-yocto | ||
1240 | through Metadata (e.g. | ||
1241 | PREFERRED_VERSION | ||
1242 | \_linux-yocto ?= "12.4%" | ||
1243 | ). | ||
1244 | |||
1245 | Once ``menuconfig`` launches, use the interface to navigate through the | ||
1246 | selections to find the configuration settings in which you are | ||
1247 | interested. For this example, you deselect "CONFIG_SMP" by clearing the | ||
1248 | "Symmetric Multi-Processing Support" option. Using the interface, you | ||
1249 | can find the option under "Processor Type and Features". To deselect | ||
1250 | "CONFIG_SMP", use the arrow keys to highlight "Symmetric | ||
1251 | Multi-Processing Support" and enter "N" to clear the asterisk. When you | ||
1252 | are finished, exit out and save the change. | ||
1253 | |||
1254 | Saving the selections updates the ``.config`` configuration file. This | ||
1255 | is the file that the OpenEmbedded build system uses to configure the | ||
1256 | kernel during the build. You can find and examine this file in the Build | ||
1257 | Directory in ``tmp/work/``. The actual ``.config`` is located in the | ||
1258 | area where the specific kernel is built. For example, if you were | ||
1259 | building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel | ||
1260 | and you were building a QEMU image targeted for ``x86`` architecture, | ||
1261 | the ``.config`` file would be: | ||
1262 | :: | ||
1263 | |||
1264 | poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18... | ||
1265 | ...967-r0/linux-qemux86-standard-build/.config | ||
1266 | |||
1267 | .. note:: | ||
1268 | |||
1269 | The previous example directory is artificially split and many of the | ||
1270 | characters in the actual filename are omitted in order to make it | ||
1271 | more readable. Also, depending on the kernel you are using, the exact | ||
1272 | pathname might differ. | ||
1273 | |||
1274 | Within the ``.config`` file, you can see the kernel settings. For | ||
1275 | example, the following entry shows that symmetric multi-processor | ||
1276 | support is not set: | ||
1277 | :: | ||
1278 | |||
1279 | # CONFIG_SMP is not set | ||
1280 | |||
1281 | A good method to isolate changed configurations is to use a combination | ||
1282 | of the ``menuconfig`` tool and simple shell commands. Before changing | ||
1283 | configurations with ``menuconfig``, copy the existing ``.config`` and | ||
1284 | rename it to something else, use ``menuconfig`` to make as many changes | ||
1285 | as you want and save them, then compare the renamed configuration file | ||
1286 | against the newly created file. You can use the resulting differences as | ||
1287 | your base to create configuration fragments to permanently save in your | ||
1288 | kernel layer. | ||
1289 | |||
1290 | .. note:: | ||
1291 | |||
1292 | Be sure to make a copy of the | ||
1293 | .config | ||
1294 | file and do not just rename it. The build system needs an existing | ||
1295 | .config | ||
1296 | file from which to work. | ||
1297 | |||
1298 | Creating a ``defconfig`` File | ||
1299 | ------------------------------ | ||
1300 | |||
1301 | A ``defconfig`` file in the context of the Yocto Project is often a | ||
1302 | ``.config`` file that is copied from a build or a ``defconfig`` taken | ||
1303 | from the kernel tree and moved into recipe space. You can use a | ||
1304 | ``defconfig`` file to retain a known set of kernel configurations from | ||
1305 | which the OpenEmbedded build system can draw to create the final | ||
1306 | ``.config`` file. | ||
1307 | |||
1308 | .. note:: | ||
1309 | |||
1310 | Out-of-the-box, the Yocto Project never ships a | ||
1311 | defconfig | ||
1312 | or | ||
1313 | .config | ||
1314 | file. The OpenEmbedded build system creates the final | ||
1315 | .config | ||
1316 | file used to configure the kernel. | ||
1317 | |||
1318 | To create a ``defconfig``, start with a complete, working Linux kernel | ||
1319 | ``.config`` file. Copy that file to the appropriate | ||
1320 | ``${``\ :term:`PN`\ ``}`` directory in | ||
1321 | your layer's ``recipes-kernel/linux`` directory, and rename the copied | ||
1322 | file to "defconfig" (e.g. | ||
1323 | ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, | ||
1324 | add the following lines to the linux-yocto ``.bbappend`` file in your | ||
1325 | layer: | ||
1326 | :: | ||
1327 | |||
1328 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
1329 | SRC_URI += "file://defconfig" | ||
1330 | |||
1331 | The :term:`SRC_URI` tells the build system how to search for the file, while the | ||
1332 | :term:`FILESEXTRAPATHS` extends the :term:`FILESPATH` | ||
1333 | variable (search directories) to include the ``${PN}`` directory you | ||
1334 | created to hold the configuration changes. | ||
1335 | |||
1336 | .. note:: | ||
1337 | |||
1338 | The build system applies the configurations from the | ||
1339 | defconfig | ||
1340 | file before applying any subsequent configuration fragments. The | ||
1341 | final kernel configuration is a combination of the configurations in | ||
1342 | the | ||
1343 | defconfig | ||
1344 | file and any configuration fragments you provide. You need to realize | ||
1345 | that if you have any configuration fragments, the build system | ||
1346 | applies these on top of and after applying the existing defconfig | ||
1347 | file configurations. | ||
1348 | |||
1349 | For more information on configuring the kernel, see the "`Changing the | ||
1350 | Configuration <#changing-the-configuration>`__" section. | ||
1351 | |||
1352 | .. _creating-config-fragments: | ||
1353 | |||
1354 | Creating Configuration Fragments | ||
1355 | -------------------------------- | ||
1356 | |||
1357 | Configuration fragments are simply kernel options that appear in a file | ||
1358 | placed where the OpenEmbedded build system can find and apply them. The | ||
1359 | build system applies configuration fragments after applying | ||
1360 | configurations from a ``defconfig`` file. Thus, the final kernel | ||
1361 | configuration is a combination of the configurations in the | ||
1362 | ``defconfig`` file and then any configuration fragments you provide. The | ||
1363 | build system applies fragments on top of and after applying the existing | ||
1364 | defconfig file configurations. | ||
1365 | |||
1366 | Syntactically, the configuration statement is identical to what would | ||
1367 | appear in the ``.config`` file, which is in the :term:`Build Directory`. | ||
1368 | |||
1369 | .. note:: | ||
1370 | |||
1371 | For more information about where the | ||
1372 | .config | ||
1373 | file is located, see the example in the | ||
1374 | ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" | ||
1375 | section. | ||
1376 | |||
1377 | It is simple to create a configuration fragment. One method is to use | ||
1378 | shell commands. For example, issuing the following from the shell | ||
1379 | creates a configuration fragment file named ``my_smp.cfg`` that enables | ||
1380 | multi-processor support within the kernel: | ||
1381 | :: | ||
1382 | |||
1383 | $ echo "CONFIG_SMP=y" >> my_smp.cfg | ||
1384 | |||
1385 | .. note:: | ||
1386 | |||
1387 | All configuration fragment files must use the | ||
1388 | .cfg | ||
1389 | extension in order for the OpenEmbedded build system to recognize | ||
1390 | them as a configuration fragment. | ||
1391 | |||
1392 | Another method is to create a configuration fragment using the | ||
1393 | differences between two configuration files: one previously created and | ||
1394 | saved, and one freshly created using the ``menuconfig`` tool. | ||
1395 | |||
1396 | To create a configuration fragment using this method, follow these | ||
1397 | steps: | ||
1398 | |||
1399 | 1. *Complete a Build Through Kernel Configuration:* Complete a build at | ||
1400 | least through the kernel configuration task as follows: | ||
1401 | :: | ||
1402 | |||
1403 | $ bitbake linux-yocto -c kernel_configme -f | ||
1404 | |||
1405 | This step ensures that you create a | ||
1406 | ``.config`` file from a known state. Because situations exist where | ||
1407 | your build state might become unknown, it is best to run this task | ||
1408 | prior to starting ``menuconfig``. | ||
1409 | |||
1410 | 2. *Launch menuconfig:* Run the ``menuconfig`` command: | ||
1411 | :: | ||
1412 | |||
1413 | $ bitbake linux-yocto -c menuconfig | ||
1414 | |||
1415 | 3. *Create the Configuration Fragment:* Run the ``diffconfig`` command | ||
1416 | to prepare a configuration fragment. The resulting file | ||
1417 | ``fragment.cfg`` is placed in the | ||
1418 | ``${``\ :term:`WORKDIR`\ ``}`` | ||
1419 | directory: | ||
1420 | :: | ||
1421 | |||
1422 | $ bitbake linux-yocto -c diffconfig | ||
1423 | |||
1424 | The ``diffconfig`` command creates a file that is a list of Linux kernel | ||
1425 | ``CONFIG_`` assignments. See the "`Changing the | ||
1426 | Configuration <#changing-the-configuration>`__" section for additional | ||
1427 | information on how to use the output as a configuration fragment. | ||
1428 | |||
1429 | .. note:: | ||
1430 | |||
1431 | You can also use this method to create configuration fragments for a | ||
1432 | BSP. See the " | ||
1433 | BSP Descriptions | ||
1434 | " section for more information. | ||
1435 | |||
1436 | Where do you put your configuration fragment files? You can place these | ||
1437 | files in an area pointed to by | ||
1438 | :term:`SRC_URI` as directed by your | ||
1439 | ``bblayers.conf`` file, which is located in your layer. The OpenEmbedded | ||
1440 | build system picks up the configuration and adds it to the kernel's | ||
1441 | configuration. For example, suppose you had a set of configuration | ||
1442 | options in a file called ``myconfig.cfg``. If you put that file inside a | ||
1443 | directory named ``linux-yocto`` that resides in the same directory as | ||
1444 | the kernel's append file within your layer and then add the following | ||
1445 | statements to the kernel's append file, those configuration options will | ||
1446 | be picked up and applied when the kernel is built: | ||
1447 | :: | ||
1448 | |||
1449 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
1450 | SRC_URI += "file://myconfig.cfg" | ||
1451 | |||
1452 | As mentioned earlier, you can group related configurations into multiple | ||
1453 | files and name them all in the ``SRC_URI`` statement as well. For | ||
1454 | example, you could group separate configurations specifically for | ||
1455 | Ethernet and graphics into their own files and add those by using a | ||
1456 | ``SRC_URI`` statement like the following in your append file: | ||
1457 | :: | ||
1458 | |||
1459 | SRC_URI += "file://myconfig.cfg \ | ||
1460 | file://eth.cfg \ | ||
1461 | file://gfx.cfg" | ||
1462 | |||
1463 | Validating Configuration | ||
1464 | ------------------------ | ||
1465 | |||
1466 | You can use the | ||
1467 | :ref:`ref-tasks-kernel_configcheck` | ||
1468 | task to provide configuration validation: | ||
1469 | :: | ||
1470 | |||
1471 | $ bitbake linux-yocto -c kernel_configcheck -f | ||
1472 | |||
1473 | Running this task produces warnings for when a | ||
1474 | requested configuration does not appear in the final ``.config`` file or | ||
1475 | when you override a policy configuration in a hardware configuration | ||
1476 | fragment. | ||
1477 | |||
1478 | In order to run this task, you must have an existing ``.config`` file. | ||
1479 | See the ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" section for | ||
1480 | information on how to create a configuration file. | ||
1481 | |||
1482 | Following is sample output from the ``do_kernel_configcheck`` task: | ||
1483 | :: | ||
1484 | |||
1485 | Loading cache: 100% |########################################################| Time: 0:00:00 | ||
1486 | Loaded 1275 entries from dependency cache. | ||
1487 | NOTE: Resolving any missing task queue dependencies | ||
1488 | |||
1489 | Build Configuration: | ||
1490 | . | ||
1491 | . | ||
1492 | . | ||
1493 | |||
1494 | NOTE: Executing SetScene Tasks | ||
1495 | NOTE: Executing RunQueue Tasks | ||
1496 | WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck: | ||
1497 | [kernel config]: specified values did not make it into the kernel's final configuration: | ||
1498 | |||
1499 | ---------- CONFIG_X86_TSC ----------------- | ||
1500 | Config: CONFIG_X86_TSC | ||
1501 | From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg | ||
1502 | Requested value: CONFIG_X86_TSC=y | ||
1503 | Actual value: | ||
1504 | |||
1505 | |||
1506 | ---------- CONFIG_X86_BIGSMP ----------------- | ||
1507 | Config: CONFIG_X86_BIGSMP | ||
1508 | From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg | ||
1509 | /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig | ||
1510 | Requested value: # CONFIG_X86_BIGSMP is not set | ||
1511 | Actual value: | ||
1512 | |||
1513 | |||
1514 | ---------- CONFIG_NR_CPUS ----------------- | ||
1515 | Config: CONFIG_NR_CPUS | ||
1516 | From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg | ||
1517 | /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg | ||
1518 | /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig | ||
1519 | Requested value: CONFIG_NR_CPUS=8 | ||
1520 | Actual value: CONFIG_NR_CPUS=1 | ||
1521 | |||
1522 | |||
1523 | ---------- CONFIG_SCHED_SMT ----------------- | ||
1524 | Config: CONFIG_SCHED_SMT | ||
1525 | From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg | ||
1526 | /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig | ||
1527 | Requested value: CONFIG_SCHED_SMT=y | ||
1528 | Actual value: | ||
1529 | |||
1530 | |||
1531 | |||
1532 | NOTE: Tasks Summary: Attempted 288 tasks of which 285 didn't need to be rerun and all succeeded. | ||
1533 | |||
1534 | Summary: There were 3 WARNING messages shown. | ||
1535 | |||
1536 | .. note:: | ||
1537 | |||
1538 | The previous output example has artificial line breaks to make it | ||
1539 | more readable. | ||
1540 | |||
1541 | The output describes the various problems that you can encounter along | ||
1542 | with where to find the offending configuration items. You can use the | ||
1543 | information in the logs to adjust your configuration files and then | ||
1544 | repeat the | ||
1545 | :ref:`ref-tasks-kernel_configme` | ||
1546 | and | ||
1547 | :ref:`ref-tasks-kernel_configcheck` | ||
1548 | tasks until they produce no warnings. | ||
1549 | |||
1550 | For more information on how to use the ``menuconfig`` tool, see the | ||
1551 | :ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\`` section. | ||
1552 | |||
1553 | Fine-Tuning the Kernel Configuration File | ||
1554 | ----------------------------------------- | ||
1555 | |||
1556 | You can make sure the ``.config`` file is as lean or efficient as | ||
1557 | possible by reading the output of the kernel configuration fragment | ||
1558 | audit, noting any issues, making changes to correct the issues, and then | ||
1559 | repeating. | ||
1560 | |||
1561 | As part of the kernel build process, the ``do_kernel_configcheck`` task | ||
1562 | runs. This task validates the kernel configuration by checking the final | ||
1563 | ``.config`` file against the input files. During the check, the task | ||
1564 | produces warning messages for the following issues: | ||
1565 | |||
1566 | - Requested options that did not make the final ``.config`` file. | ||
1567 | |||
1568 | - Configuration items that appear twice in the same configuration | ||
1569 | fragment. | ||
1570 | |||
1571 | - Configuration items tagged as "required" that were overridden. | ||
1572 | |||
1573 | - A board overrides a non-board specific option. | ||
1574 | |||
1575 | - Listed options not valid for the kernel being processed. In other | ||
1576 | words, the option does not appear anywhere. | ||
1577 | |||
1578 | .. note:: | ||
1579 | |||
1580 | The | ||
1581 | do_kernel_configcheck | ||
1582 | task can also optionally report if an option is overridden during | ||
1583 | processing. | ||
1584 | |||
1585 | For each output warning, a message points to the file that contains a | ||
1586 | list of the options and a pointer to the configuration fragment that | ||
1587 | defines them. Collectively, the files are the key to streamlining the | ||
1588 | configuration. | ||
1589 | |||
1590 | To streamline the configuration, do the following: | ||
1591 | |||
1592 | 1. *Use a Working Configuration:* Start with a full configuration that | ||
1593 | you know works. Be sure the configuration builds and boots | ||
1594 | successfully. Use this configuration file as your baseline. | ||
1595 | |||
1596 | 2. *Run Configure and Check Tasks:* Separately run the | ||
1597 | ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks: | ||
1598 | :: | ||
1599 | |||
1600 | $ bitbake linux-yocto -c kernel_configme -f | ||
1601 | $ bitbake linux-yocto -c kernel_configcheck -f | ||
1602 | |||
1603 | 3. *Process the Results:* Take the resulting list of files from the | ||
1604 | ``do_kernel_configcheck`` task warnings and do the following: | ||
1605 | |||
1606 | - Drop values that are redefined in the fragment but do not change | ||
1607 | the final ``.config`` file. | ||
1608 | |||
1609 | - Analyze and potentially drop values from the ``.config`` file that | ||
1610 | override required configurations. | ||
1611 | |||
1612 | - Analyze and potentially remove non-board specific options. | ||
1613 | |||
1614 | - Remove repeated and invalid options. | ||
1615 | |||
1616 | 4. *Re-Run Configure and Check Tasks:* After you have worked through the | ||
1617 | output of the kernel configuration audit, you can re-run the | ||
1618 | ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the | ||
1619 | results of your changes. If you have more issues, you can deal with | ||
1620 | them as described in the previous step. | ||
1621 | |||
1622 | Iteratively working through steps two through four eventually yields a | ||
1623 | minimal, streamlined configuration file. Once you have the best | ||
1624 | ``.config``, you can build the Linux Yocto kernel. | ||
1625 | |||
1626 | Expanding Variables | ||
1627 | =================== | ||
1628 | |||
1629 | Sometimes it is helpful to determine what a variable expands to during a | ||
1630 | build. You can do examine the values of variables by examining the | ||
1631 | output of the ``bitbake -e`` command. The output is long and is more | ||
1632 | easily managed in a text file, which allows for easy searches: | ||
1633 | :: | ||
1634 | |||
1635 | $ bitbake -e virtual/kernel > some_text_file | ||
1636 | |||
1637 | Within the text file, you can see | ||
1638 | exactly how each variable is expanded and used by the OpenEmbedded build | ||
1639 | system. | ||
1640 | |||
1641 | Working with a "Dirty" Kernel Version String | ||
1642 | ============================================ | ||
1643 | |||
1644 | If you build a kernel image and the version string has a "+" or a | ||
1645 | "-dirty" at the end, uncommitted modifications exist in the kernel's | ||
1646 | source directory. Follow these steps to clean up the version string: | ||
1647 | |||
1648 | 1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned | ||
1649 | Git repository (source directory) and use the following Git command | ||
1650 | to list the files that have been changed, added, or removed: | ||
1651 | :: | ||
1652 | |||
1653 | $ git status | ||
1654 | |||
1655 | 2. *Commit the Changes:* You should commit those changes to the kernel | ||
1656 | source tree regardless of whether or not you will save, export, or | ||
1657 | use the changes: | ||
1658 | :: | ||
1659 | |||
1660 | $ git add | ||
1661 | $ git commit -s -a -m "getting rid of -dirty" | ||
1662 | |||
1663 | 3. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the | ||
1664 | kernel. | ||
1665 | |||
1666 | Depending on your particular kernel development workflow, the | ||
1667 | commands you use to rebuild the kernel might differ. For information | ||
1668 | on building the kernel image when using ``devtool``, see the | ||
1669 | ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`" | ||
1670 | section. For | ||
1671 | information on building the kernel image when using Bitbake, see the | ||
1672 | "`Using Traditional Kernel Development to Patch the | ||
1673 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
1674 | section. | ||
1675 | |||
1676 | Working With Your Own Sources | ||
1677 | ============================= | ||
1678 | |||
1679 | If you cannot work with one of the Linux kernel versions supported by | ||
1680 | existing linux-yocto recipes, you can still make use of the Yocto | ||
1681 | Project Linux kernel tooling by working with your own sources. When you | ||
1682 | use your own sources, you will not be able to leverage the existing | ||
1683 | kernel :term:`Metadata` and stabilization | ||
1684 | work of the linux-yocto sources. However, you will be able to manage | ||
1685 | your own Metadata in the same format as the linux-yocto sources. | ||
1686 | Maintaining format compatibility facilitates converging with linux-yocto | ||
1687 | on a future, mutually-supported kernel version. | ||
1688 | |||
1689 | To help you use your own sources, the Yocto Project provides a | ||
1690 | linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses | ||
1691 | ``kernel.org`` sources and the Yocto Project Linux kernel tools for | ||
1692 | managing kernel Metadata. You can find this recipe in the ``poky`` Git | ||
1693 | repository of the Yocto Project :yocto_git:`Source Repository <>` | ||
1694 | at: | ||
1695 | :: | ||
1696 | |||
1697 | poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb | ||
1698 | |||
1699 | Here are some basic steps you can use to work with your own sources: | ||
1700 | |||
1701 | 1. *Create a Copy of the Kernel Recipe:* Copy the | ||
1702 | ``linux-yocto-custom.bb`` recipe to your layer and give it a | ||
1703 | meaningful name. The name should include the version of the Yocto | ||
1704 | Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``, | ||
1705 | where "4.12" is the base version of the Linux kernel with which you | ||
1706 | would be working). | ||
1707 | |||
1708 | 2. *Create a Directory for Your Patches:* In the same directory inside | ||
1709 | your layer, create a matching directory to store your patches and | ||
1710 | configuration files (e.g. ``linux-yocto-myproject``). | ||
1711 | |||
1712 | 3. *Ensure You Have Configurations:* Make sure you have either a | ||
1713 | ``defconfig`` file or configuration fragment files in your layer. | ||
1714 | When you use the ``linux-yocto-custom.bb`` recipe, you must specify a | ||
1715 | configuration. If you do not have a ``defconfig`` file, you can run | ||
1716 | the following: | ||
1717 | :: | ||
1718 | |||
1719 | $ make defconfig | ||
1720 | |||
1721 | After running the command, copy the | ||
1722 | resulting ``.config`` file to the ``files`` directory in your layer | ||
1723 | as "defconfig" and then add it to the | ||
1724 | :term:`SRC_URI` variable in the | ||
1725 | recipe. | ||
1726 | |||
1727 | Running the ``make defconfig`` command results in the default | ||
1728 | configuration for your architecture as defined by your kernel. | ||
1729 | However, no guarantee exists that this configuration is valid for | ||
1730 | your use case, or that your board will even boot. This is | ||
1731 | particularly true for non-x86 architectures. | ||
1732 | |||
1733 | To use non-x86 ``defconfig`` files, you need to be more specific and | ||
1734 | find one that matches your board (i.e. for arm, you look in | ||
1735 | ``arch/arm/configs`` and use the one that is the best starting point | ||
1736 | for your board). | ||
1737 | |||
1738 | 4. *Edit the Recipe:* Edit the following variables in your recipe as | ||
1739 | appropriate for your project: | ||
1740 | |||
1741 | - :term:`SRC_URI`: The | ||
1742 | ``SRC_URI`` should specify a Git repository that uses one of the | ||
1743 | supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, | ||
1744 | and so forth). The ``SRC_URI`` variable should also specify either | ||
1745 | a ``defconfig`` file or some configuration fragment files. The | ||
1746 | skeleton recipe provides an example ``SRC_URI`` as a syntax | ||
1747 | reference. | ||
1748 | |||
1749 | - :term:`LINUX_VERSION`: | ||
1750 | The Linux kernel version you are using (e.g. "4.12"). | ||
1751 | |||
1752 | - :term:`LINUX_VERSION_EXTENSION`: | ||
1753 | The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the | ||
1754 | resulting kernel and visible through the ``uname`` command. | ||
1755 | |||
1756 | - :term:`SRCREV`: The commit ID | ||
1757 | from which you want to build. | ||
1758 | |||
1759 | - :term:`PR`: Treat this variable the | ||
1760 | same as you would in any other recipe. Increment the variable to | ||
1761 | indicate to the OpenEmbedded build system that the recipe has | ||
1762 | changed. | ||
1763 | |||
1764 | - :term:`PV`: The default ``PV`` | ||
1765 | assignment is typically adequate. It combines the | ||
1766 | ``LINUX_VERSION`` with the Source Control Manager (SCM) revision | ||
1767 | as derived from the :term:`SRCPV` | ||
1768 | variable. The combined results are a string with the following | ||
1769 | form: | ||
1770 | 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 | ||
1771 | While lengthy, the extra verbosity in ``PV`` helps ensure you are | ||
1772 | using the exact sources from which you intend to build. | ||
1773 | |||
1774 | - :term:`COMPATIBLE_MACHINE`: | ||
1775 | A list of the machines supported by your new recipe. This variable | ||
1776 | in the example recipe is set by default to a regular expression | ||
1777 | that matches only the empty string, "(^$)". This default setting | ||
1778 | triggers an explicit build failure. You must change it to match a | ||
1779 | list of the machines that your new recipe supports. For example, | ||
1780 | to support the ``qemux86`` and ``qemux86-64`` machines, use the | ||
1781 | following form: COMPATIBLE_MACHINE = "qemux86|qemux86-64" | ||
1782 | |||
1783 | 5. *Customize Your Recipe as Needed:* Provide further customizations to | ||
1784 | your recipe as needed just as you would customize an existing | ||
1785 | linux-yocto recipe. See the "`Modifying an Existing | ||
1786 | Recipe <#modifying-an-existing-recipe>`__" section for information. | ||
1787 | |||
1788 | Working with Out-of-Tree Modules | ||
1789 | ================================ | ||
1790 | |||
1791 | This section describes steps to build out-of-tree modules on your target | ||
1792 | and describes how to incorporate out-of-tree modules in the build. | ||
1793 | |||
1794 | Building Out-of-Tree Modules on the Target | ||
1795 | ------------------------------------------ | ||
1796 | |||
1797 | While the traditional Yocto Project development model would be to | ||
1798 | include kernel modules as part of the normal build process, you might | ||
1799 | find it useful to build modules on the target. This could be the case if | ||
1800 | your target system is capable and powerful enough to handle the | ||
1801 | necessary compilation. Before deciding to build on your target, however, | ||
1802 | you should consider the benefits of using a proper cross-development | ||
1803 | environment from your build host. | ||
1804 | |||
1805 | If you want to be able to build out-of-tree modules on the target, there | ||
1806 | are some steps you need to take on the target that is running your SDK | ||
1807 | image. Briefly, the ``kernel-dev`` package is installed by default on | ||
1808 | all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on | ||
1809 | many of the ``*.sdk`` images. However, you need to create some scripts | ||
1810 | prior to attempting to build the out-of-tree modules on the target that | ||
1811 | is running that image. | ||
1812 | |||
1813 | Prior to attempting to build the out-of-tree modules, you need to be on | ||
1814 | the target as root and you need to change to the ``/usr/src/kernel`` | ||
1815 | directory. Next, ``make`` the scripts: | ||
1816 | :: | ||
1817 | |||
1818 | # cd /usr/src/kernel | ||
1819 | # make scripts | ||
1820 | |||
1821 | Because all SDK image recipes include ``dev-pkgs``, the | ||
1822 | ``kernel-dev`` packages will be installed as part of the SDK image and | ||
1823 | the ``kernel-devsrc`` packages will be installed as part of applicable | ||
1824 | SDK images. The SDK uses the scripts when building out-of-tree modules. | ||
1825 | Once you have switched to that directory and created the scripts, you | ||
1826 | should be able to build your out-of-tree modules on the target. | ||
1827 | |||
1828 | Incorporating Out-of-Tree Modules | ||
1829 | --------------------------------- | ||
1830 | |||
1831 | While it is always preferable to work with sources integrated into the | ||
1832 | Linux kernel sources, if you need an external kernel module, the | ||
1833 | ``hello-mod.bb`` recipe is available as a template from which you can | ||
1834 | create your own out-of-tree Linux kernel module recipe. | ||
1835 | |||
1836 | This template recipe is located in the ``poky`` Git repository of the | ||
1837 | Yocto Project :yocto_git:`Source Repository <>` at: | ||
1838 | :: | ||
1839 | |||
1840 | poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb | ||
1841 | |||
1842 | To get started, copy this recipe to your layer and give it a meaningful | ||
1843 | name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new | ||
1844 | directory named ``files`` where you can store any source files, patches, | ||
1845 | or other files necessary for building the module that do not come with | ||
1846 | the sources. Finally, update the recipe as needed for the module. | ||
1847 | Typically, you will need to set the following variables: | ||
1848 | |||
1849 | - :term:`DESCRIPTION` | ||
1850 | |||
1851 | - :term:`LICENSE* <LICENSE>` | ||
1852 | |||
1853 | - :term:`SRC_URI` | ||
1854 | |||
1855 | - :term:`PV` | ||
1856 | |||
1857 | Depending on the build system used by the module sources, you might need | ||
1858 | to make some adjustments. For example, a typical module ``Makefile`` | ||
1859 | looks much like the one provided with the ``hello-mod`` template: | ||
1860 | :: | ||
1861 | |||
1862 | obj-m := hello.o | ||
1863 | |||
1864 | SRC := $(shell pwd) | ||
1865 | |||
1866 | all: | ||
1867 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) | ||
1868 | |||
1869 | modules_install: | ||
1870 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install | ||
1871 | ... | ||
1872 | |||
1873 | The important point to note here is the :term:`KERNEL_SRC` variable. The | ||
1874 | :ref:`module <ref-classes-module>` class sets this variable and the | ||
1875 | :term:`KERNEL_PATH` variable to | ||
1876 | ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build | ||
1877 | information to build modules. If your module ``Makefile`` uses a | ||
1878 | different variable, you might want to override the | ||
1879 | :ref:`ref-tasks-compile` step, or | ||
1880 | create a patch to the ``Makefile`` to work with the more typical | ||
1881 | ``KERNEL_SRC`` or ``KERNEL_PATH`` variables. | ||
1882 | |||
1883 | After you have prepared your recipe, you will likely want to include the | ||
1884 | module in your images. To do this, see the documentation for the | ||
1885 | following variables in the Yocto Project Reference Manual and set one of | ||
1886 | them appropriately for your machine configuration file: | ||
1887 | |||
1888 | - :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` | ||
1889 | |||
1890 | - :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` | ||
1891 | |||
1892 | - :term:`MACHINE_EXTRA_RDEPENDS` | ||
1893 | |||
1894 | - :term:`MACHINE_EXTRA_RRECOMMENDS` | ||
1895 | |||
1896 | Modules are often not required for boot and can be excluded from certain | ||
1897 | build configurations. The following allows for the most flexibility: | ||
1898 | :: | ||
1899 | |||
1900 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" | ||
1901 | |||
1902 | The value is | ||
1903 | derived by appending the module filename without the ``.ko`` extension | ||
1904 | to the string "kernel-module-". | ||
1905 | |||
1906 | Because the variable is | ||
1907 | :term:`RRECOMMENDS` and not a | ||
1908 | :term:`RDEPENDS` variable, the build | ||
1909 | will not fail if this module is not available to include in the image. | ||
1910 | |||
1911 | Inspecting Changes and Commits | ||
1912 | ============================== | ||
1913 | |||
1914 | A common question when working with a kernel is: "What changes have been | ||
1915 | applied to this tree?" Rather than using "grep" across directories to | ||
1916 | see what has changed, you can use Git to inspect or search the kernel | ||
1917 | tree. Using Git is an efficient way to see what has changed in the tree. | ||
1918 | |||
1919 | What Changed in a Kernel? | ||
1920 | ------------------------- | ||
1921 | |||
1922 | Following are a few examples that show how to use Git commands to | ||
1923 | examine changes. These examples are by no means the only way to see | ||
1924 | changes. | ||
1925 | |||
1926 | .. note:: | ||
1927 | |||
1928 | In the following examples, unless you provide a commit range, | ||
1929 | kernel.org | ||
1930 | history is blended with Yocto Project kernel changes. You can form | ||
1931 | ranges by using branch names from the kernel tree as the upper and | ||
1932 | lower commit markers with the Git commands. You can see the branch | ||
1933 | names through the web interface to the Yocto Project source | ||
1934 | repositories at | ||
1935 | . | ||
1936 | |||
1937 | To see a full range of the changes, use the ``git whatchanged`` command | ||
1938 | and specify a commit range for the branch (commit\ ``..``\ commit). | ||
1939 | |||
1940 | Here is an example that looks at what has changed in the ``emenlow`` | ||
1941 | branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the | ||
1942 | commit associated with the ``standard/base`` branch, while the upper | ||
1943 | commit range is the commit associated with the ``standard/emenlow`` | ||
1944 | branch. | ||
1945 | :: | ||
1946 | |||
1947 | $ git whatchanged origin/standard/base..origin/standard/emenlow | ||
1948 | |||
1949 | To see short, one line summaries of changes use the ``git log`` command: | ||
1950 | :: | ||
1951 | |||
1952 | $ git log --oneline origin/standard/base..origin/standard/emenlow | ||
1953 | |||
1954 | Use this command to see code differences for the changes: | ||
1955 | :: | ||
1956 | |||
1957 | $ git diff origin/standard/base..origin/standard/emenlow | ||
1958 | |||
1959 | Use this command to see the commit log messages and the text | ||
1960 | differences: | ||
1961 | :: | ||
1962 | |||
1963 | $ git show origin/standard/base..origin/standard/emenlow | ||
1964 | |||
1965 | Use this command to create individual patches for each change. Here is | ||
1966 | an example that that creates patch files for each commit and places them | ||
1967 | in your ``Documents`` directory: | ||
1968 | :: | ||
1969 | |||
1970 | $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow | ||
1971 | |||
1972 | Showing a Particular Feature or Branch Change | ||
1973 | --------------------------------------------- | ||
1974 | |||
1975 | Tags in the Yocto Project kernel tree divide changes for significant | ||
1976 | features or branches. The ``git show`` tag command shows changes based | ||
1977 | on a tag. Here is an example that shows ``systemtap`` changes: | ||
1978 | :: | ||
1979 | |||
1980 | $ git show systemtap | ||
1981 | |||
1982 | You can use the ``git branch --contains`` tag command to | ||
1983 | show the branches that contain a particular feature. This command shows | ||
1984 | the branches that contain the ``systemtap`` feature: | ||
1985 | :: | ||
1986 | |||
1987 | $ git branch --contains systemtap | ||
1988 | |||
1989 | Adding Recipe-Space Kernel Features | ||
1990 | =================================== | ||
1991 | |||
1992 | You can add kernel features in the | ||
1993 | `recipe-space <#recipe-space-metadata>`__ by using the | ||
1994 | :term:`KERNEL_FEATURES` | ||
1995 | variable and by specifying the feature's ``.scc`` file path in the | ||
1996 | :term:`SRC_URI` statement. When you | ||
1997 | add features using this method, the OpenEmbedded build system checks to | ||
1998 | be sure the features are present. If the features are not present, the | ||
1999 | build stops. Kernel features are the last elements processed for | ||
2000 | configuring and patching the kernel. Therefore, adding features in this | ||
2001 | manner is a way to enforce specific features are present and enabled | ||
2002 | without needing to do a full audit of any other layer's additions to the | ||
2003 | ``SRC_URI`` statement. | ||
2004 | |||
2005 | You add a kernel feature by providing the feature as part of the | ||
2006 | ``KERNEL_FEATURES`` variable and by providing the path to the feature's | ||
2007 | ``.scc`` file, which is relative to the root of the kernel Metadata. The | ||
2008 | OpenEmbedded build system searches all forms of kernel Metadata on the | ||
2009 | ``SRC_URI`` statement regardless of whether the Metadata is in the | ||
2010 | "kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e. | ||
2011 | part of the kernel recipe). See the "`Kernel Metadata | ||
2012 | Location <#kernel-metadata-location>`__" section for additional | ||
2013 | information. | ||
2014 | |||
2015 | When you specify the feature's ``.scc`` file on the ``SRC_URI`` | ||
2016 | statement, the OpenEmbedded build system adds the directory of that | ||
2017 | ``.scc`` file along with all its subdirectories to the kernel feature | ||
2018 | search path. Because subdirectories are searched, you can reference a | ||
2019 | single ``.scc`` file in the ``SRC_URI`` statement to reference multiple | ||
2020 | kernel features. | ||
2021 | |||
2022 | Consider the following example that adds the "test.scc" feature to the | ||
2023 | build. | ||
2024 | |||
2025 | 1. *Create the Feature File:* Create a ``.scc`` file and locate it just | ||
2026 | as you would any other patch file, ``.cfg`` file, or fetcher item you | ||
2027 | specify in the ``SRC_URI`` statement. | ||
2028 | |||
2029 | .. note:: | ||
2030 | |||
2031 | - You must add the directory of the ``.scc`` file to the | ||
2032 | fetcher's search path in the same manner as you would add a | ||
2033 | ``.patch`` file. | ||
2034 | |||
2035 | - You can create additional ``.scc`` files beneath the directory | ||
2036 | that contains the file you are adding. All subdirectories are | ||
2037 | searched during the build as potential feature directories. | ||
2038 | |||
2039 | Continuing with the example, suppose the "test.scc" feature you are | ||
2040 | adding has a ``test.scc`` file in the following directory: | ||
2041 | :: | ||
2042 | |||
2043 | my_recipe | ||
2044 | | | ||
2045 | +-linux-yocto | ||
2046 | | | ||
2047 | +-test.cfg | ||
2048 | +-test.scc | ||
2049 | |||
2050 | In this example, the | ||
2051 | ``linux-yocto`` directory has both the feature ``test.scc`` file and | ||
2052 | a similarly named configuration fragment file ``test.cfg``. | ||
2053 | |||
2054 | 2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the | ||
2055 | recipe's ``SRC_URI`` statement: | ||
2056 | :: | ||
2057 | |||
2058 | SRC_URI_append = " file://test.scc" | ||
2059 | |||
2060 | The leading space before the path is important as the path is | ||
2061 | appended to the existing path. | ||
2062 | |||
2063 | 3. *Specify the Feature as a Kernel Feature:* Use the | ||
2064 | ``KERNEL_FEATURES`` statement to specify the feature as a kernel | ||
2065 | feature: | ||
2066 | :: | ||
2067 | |||
2068 | KERNEL_FEATURES_append = " test.scc" | ||
2069 | |||
2070 | The OpenEmbedded build | ||
2071 | system processes the kernel feature when it builds the kernel. | ||
2072 | |||
2073 | .. note:: | ||
2074 | |||
2075 | If other features are contained below "test.scc", then their | ||
2076 | directories are relative to the directory containing the | ||
2077 | test.scc | ||
2078 | file. | ||
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index c1c2d6d703..8e8a6dbed4 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='kernel-dev-common'> | 6 | <chapter id='kernel-dev-common'> |
6 | <title>Common Tasks</title> | 7 | <title>Common Tasks</title> |
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.rst b/documentation/kernel-dev/kernel-dev-concepts-appx.rst new file mode 100644 index 0000000000..04cb1172b2 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.rst | |||
@@ -0,0 +1,426 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ************************ | ||
4 | Advanced Kernel Concepts | ||
5 | ************************ | ||
6 | |||
7 | .. _kernel-big-picture: | ||
8 | |||
9 | Yocto Project Kernel Development and Maintenance | ||
10 | ================================================ | ||
11 | |||
12 | Kernels available through the Yocto Project (Yocto Linux kernels), like | ||
13 | other kernels, are based off the Linux kernel releases from | ||
14 | http://www.kernel.org. At the beginning of a major Linux kernel | ||
15 | development cycle, the Yocto Project team chooses a Linux kernel based | ||
16 | on factors such as release timing, the anticipated release timing of | ||
17 | final upstream ``kernel.org`` versions, and Yocto Project feature | ||
18 | requirements. Typically, the Linux kernel chosen is in the final stages | ||
19 | of development by the Linux community. In other words, the Linux kernel | ||
20 | is in the release candidate or "rc" phase and has yet to reach final | ||
21 | release. But, by being in the final stages of external development, the | ||
22 | team knows that the ``kernel.org`` final release will clearly be within | ||
23 | the early stages of the Yocto Project development window. | ||
24 | |||
25 | This balance allows the Yocto Project team to deliver the most | ||
26 | up-to-date Yocto Linux kernel possible, while still ensuring that the | ||
27 | team has a stable official release for the baseline Linux kernel | ||
28 | version. | ||
29 | |||
30 | As implied earlier, the ultimate source for Yocto Linux kernels are | ||
31 | released kernels from ``kernel.org``. In addition to a foundational | ||
32 | kernel from ``kernel.org``, the available Yocto Linux kernels contain a | ||
33 | mix of important new mainline developments, non-mainline developments | ||
34 | (when no alternative exists), Board Support Package (BSP) developments, | ||
35 | and custom features. These additions result in a commercially released | ||
36 | Yocto Project Linux kernel that caters to specific embedded designer | ||
37 | needs for targeted hardware. | ||
38 | |||
39 | You can find a web interface to the Yocto Linux kernels in the | ||
40 | :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` | ||
41 | at :yocto_git:`/`. If you look at the interface, you will see to | ||
42 | the left a grouping of Git repositories titled "Yocto Linux Kernel". | ||
43 | Within this group, you will find several Linux Yocto kernels developed | ||
44 | and included with Yocto Project releases: | ||
45 | |||
46 | - *linux-yocto-4.1:* The stable Yocto Project kernel to use with | ||
47 | the Yocto Project Release 2.0. This kernel is based on the Linux 4.1 | ||
48 | released kernel. | ||
49 | |||
50 | - *linux-yocto-4.4:* The stable Yocto Project kernel to use with | ||
51 | the Yocto Project Release 2.1. This kernel is based on the Linux 4.4 | ||
52 | released kernel. | ||
53 | |||
54 | - *linux-yocto-4.6:* A temporary kernel that is not tied to any | ||
55 | Yocto Project release. | ||
56 | |||
57 | - *linux-yocto-4.8:* The stable yocto Project kernel to use with | ||
58 | the Yocto Project Release 2.2. | ||
59 | |||
60 | - *linux-yocto-4.9:* The stable Yocto Project kernel to use with | ||
61 | the Yocto Project Release 2.3. This kernel is based on the Linux 4.9 | ||
62 | released kernel. | ||
63 | |||
64 | - *linux-yocto-4.10:* The default stable Yocto Project kernel to | ||
65 | use with the Yocto Project Release 2.3. This kernel is based on the | ||
66 | Linux 4.10 released kernel. | ||
67 | |||
68 | - *linux-yocto-4.12:* The default stable Yocto Project kernel to | ||
69 | use with the Yocto Project Release 2.4. This kernel is based on the | ||
70 | Linux 4.12 released kernel. | ||
71 | |||
72 | - *yocto-kernel-cache:* The ``linux-yocto-cache`` contains patches | ||
73 | and configurations for the linux-yocto kernel tree. This repository | ||
74 | is useful when working on the linux-yocto kernel. For more | ||
75 | information on this "Advanced Kernel Metadata", see the | ||
76 | ":doc:`kernel-dev-advanced`" Chapter. | ||
77 | |||
78 | - *linux-yocto-dev:* A development kernel based on the latest | ||
79 | upstream release candidate available. | ||
80 | |||
81 | .. note:: | ||
82 | |||
83 | Long Term Support Initiative (LTSI) for Yocto Linux kernels is as | ||
84 | follows: | ||
85 | |||
86 | - For Yocto Project releases 1.7, 1.8, and 2.0, the LTSI kernel is | ||
87 | ``linux-yocto-3.14``. | ||
88 | |||
89 | - For Yocto Project releases 2.1, 2.2, and 2.3, the LTSI kernel is | ||
90 | ``linux-yocto-4.1``. | ||
91 | |||
92 | - For Yocto Project release 2.4, the LTSI kernel is | ||
93 | ``linux-yocto-4.9`` | ||
94 | |||
95 | - ``linux-yocto-4.4`` is an LTS kernel. | ||
96 | |||
97 | Once a Yocto Linux kernel is officially released, the Yocto Project team | ||
98 | goes into their next development cycle, or upward revision (uprev) | ||
99 | cycle, while still continuing maintenance on the released kernel. It is | ||
100 | important to note that the most sustainable and stable way to include | ||
101 | feature development upstream is through a kernel uprev process. | ||
102 | Back-porting hundreds of individual fixes and minor features from | ||
103 | various kernel versions is not sustainable and can easily compromise | ||
104 | quality. | ||
105 | |||
106 | During the uprev cycle, the Yocto Project team uses an ongoing analysis | ||
107 | of Linux kernel development, BSP support, and release timing to select | ||
108 | the best possible ``kernel.org`` Linux kernel version on which to base | ||
109 | subsequent Yocto Linux kernel development. The team continually monitors | ||
110 | Linux community kernel development to look for significant features of | ||
111 | interest. The team does consider back-porting large features if they | ||
112 | have a significant advantage. User or community demand can also trigger | ||
113 | a back-port or creation of new functionality in the Yocto Project | ||
114 | baseline kernel during the uprev cycle. | ||
115 | |||
116 | Generally speaking, every new Linux kernel both adds features and | ||
117 | introduces new bugs. These consequences are the basic properties of | ||
118 | upstream Linux kernel development and are managed by the Yocto Project | ||
119 | team's Yocto Linux kernel development strategy. It is the Yocto Project | ||
120 | team's policy to not back-port minor features to the released Yocto | ||
121 | Linux kernel. They only consider back-porting significant technological | ||
122 | jumps DASH and, that is done after a complete gap analysis. The reason | ||
123 | for this policy is that back-porting any small to medium sized change | ||
124 | from an evolving Linux kernel can easily create mismatches, | ||
125 | incompatibilities and very subtle errors. | ||
126 | |||
127 | The policies described in this section result in both a stable and a | ||
128 | cutting edge Yocto Linux kernel that mixes forward ports of existing | ||
129 | Linux kernel features and significant and critical new functionality. | ||
130 | Forward porting Linux kernel functionality into the Yocto Linux kernels | ||
131 | available through the Yocto Project can be thought of as a "micro | ||
132 | uprev." The many "micro uprevs" produce a Yocto Linux kernel version | ||
133 | with a mix of important new mainline, non-mainline, BSP developments and | ||
134 | feature integrations. This Yocto Linux kernel gives insight into new | ||
135 | features and allows focused amounts of testing to be done on the kernel, | ||
136 | which prevents surprises when selecting the next major uprev. The | ||
137 | quality of these cutting edge Yocto Linux kernels is evolving and the | ||
138 | kernels are used in leading edge feature and BSP development. | ||
139 | |||
140 | Yocto Linux Kernel Architecture and Branching Strategies | ||
141 | ======================================================== | ||
142 | |||
143 | As mentioned earlier, a key goal of the Yocto Project is to present the | ||
144 | developer with a kernel that has a clear and continuous history that is | ||
145 | visible to the user. The architecture and mechanisms, in particular the | ||
146 | branching strategies, used achieve that goal in a manner similar to | ||
147 | upstream Linux kernel development in ``kernel.org``. | ||
148 | |||
149 | You can think of a Yocto Linux kernel as consisting of a baseline Linux | ||
150 | kernel with added features logically structured on top of the baseline. | ||
151 | The features are tagged and organized by way of a branching strategy | ||
152 | implemented by the Yocto Project team using the Source Code Manager | ||
153 | (SCM) Git. | ||
154 | |||
155 | .. note:: | ||
156 | |||
157 | - Git is the obvious SCM for meeting the Yocto Linux kernel | ||
158 | organizational and structural goals described in this section. Not | ||
159 | only is Git the SCM for Linux kernel development in ``kernel.org`` | ||
160 | but, Git continues to grow in popularity and supports many | ||
161 | different work flows, front-ends and management techniques. | ||
162 | |||
163 | - You can find documentation on Git at | ||
164 | http://git-scm.com/documentation. You can also get an | ||
165 | introduction to Git as it applies to the Yocto Project in the | ||
166 | ":ref:`overview-manual/overview-manual-development-environment:git`" section in the Yocto Project | ||
167 | Overview and Concepts Manual. The latter reference provides an | ||
168 | overview of Git and presents a minimal set of Git commands that | ||
169 | allows you to be functional using Git. You can use as much, or as | ||
170 | little, of what Git has to offer to accomplish what you need for | ||
171 | your project. You do not have to be a "Git Expert" in order to use | ||
172 | it with the Yocto Project. | ||
173 | |||
174 | Using Git's tagging and branching features, the Yocto Project team | ||
175 | creates kernel branches at points where functionality is no longer | ||
176 | shared and thus, needs to be isolated. For example, board-specific | ||
177 | incompatibilities would require different functionality and would | ||
178 | require a branch to separate the features. Likewise, for specific kernel | ||
179 | features, the same branching strategy is used. | ||
180 | |||
181 | This "tree-like" architecture results in a structure that has features | ||
182 | organized to be specific for particular functionality, single kernel | ||
183 | types, or a subset of kernel types. Thus, the user has the ability to | ||
184 | see the added features and the commits that make up those features. In | ||
185 | addition to being able to see added features, the user can also view the | ||
186 | history of what made up the baseline Linux kernel. | ||
187 | |||
188 | Another consequence of this strategy results in not having to store the | ||
189 | same feature twice internally in the tree. Rather, the kernel team | ||
190 | stores the unique differences required to apply the feature onto the | ||
191 | kernel type in question. | ||
192 | |||
193 | .. note:: | ||
194 | |||
195 | The Yocto Project team strives to place features in the tree such | ||
196 | that features can be shared by all boards and kernel types where | ||
197 | possible. However, during development cycles or when large features | ||
198 | are merged, the team cannot always follow this practice. In those | ||
199 | cases, the team uses isolated branches to merge features. | ||
200 | |||
201 | BSP-specific code additions are handled in a similar manner to | ||
202 | kernel-specific additions. Some BSPs only make sense given certain | ||
203 | kernel types. So, for these types, the team creates branches off the end | ||
204 | of that kernel type for all of the BSPs that are supported on that | ||
205 | kernel type. From the perspective of the tools that create the BSP | ||
206 | branch, the BSP is really no different than a feature. Consequently, the | ||
207 | same branching strategy applies to BSPs as it does to kernel features. | ||
208 | So again, rather than store the BSP twice, the team only stores the | ||
209 | unique differences for the BSP across the supported multiple kernels. | ||
210 | |||
211 | While this strategy can result in a tree with a significant number of | ||
212 | branches, it is important to realize that from the developer's point of | ||
213 | view, there is a linear path that travels from the baseline | ||
214 | ``kernel.org``, through a select group of features and ends with their | ||
215 | BSP-specific commits. In other words, the divisions of the kernel are | ||
216 | transparent and are not relevant to the developer on a day-to-day basis. | ||
217 | From the developer's perspective, this path is the "master" branch in | ||
218 | Git terms. The developer does not need to be aware of the existence of | ||
219 | any other branches at all. Of course, value exists in the having these | ||
220 | branches in the tree, should a person decide to explore them. For | ||
221 | example, a comparison between two BSPs at either the commit level or at | ||
222 | the line-by-line code ``diff`` level is now a trivial operation. | ||
223 | |||
224 | The following illustration shows the conceptual Yocto Linux kernel. | ||
225 | |||
226 | .. image:: figures/kernel-architecture-overview.png | ||
227 | :align: center | ||
228 | |||
229 | In the illustration, the "Kernel.org Branch Point" marks the specific | ||
230 | spot (or Linux kernel release) from which the Yocto Linux kernel is | ||
231 | created. From this point forward in the tree, features and differences | ||
232 | are organized and tagged. | ||
233 | |||
234 | The "Yocto Project Baseline Kernel" contains functionality that is | ||
235 | common to every kernel type and BSP that is organized further along in | ||
236 | the tree. Placing these common features in the tree this way means | ||
237 | features do not have to be duplicated along individual branches of the | ||
238 | tree structure. | ||
239 | |||
240 | From the "Yocto Project Baseline Kernel", branch points represent | ||
241 | specific functionality for individual Board Support Packages (BSPs) as | ||
242 | well as real-time kernels. The illustration represents this through | ||
243 | three BSP-specific branches and a real-time kernel branch. Each branch | ||
244 | represents some unique functionality for the BSP or for a real-time | ||
245 | Yocto Linux kernel. | ||
246 | |||
247 | In this example structure, the "Real-time (rt) Kernel" branch has common | ||
248 | features for all real-time Yocto Linux kernels and contains more | ||
249 | branches for individual BSP-specific real-time kernels. The illustration | ||
250 | shows three branches as an example. Each branch points the way to | ||
251 | specific, unique features for a respective real-time kernel as they | ||
252 | apply to a given BSP. | ||
253 | |||
254 | The resulting tree structure presents a clear path of markers (or | ||
255 | branches) to the developer that, for all practical purposes, is the | ||
256 | Yocto Linux kernel needed for any given set of requirements. | ||
257 | |||
258 | .. note:: | ||
259 | |||
260 | Keep in mind the figure does not take into account all the supported | ||
261 | Yocto Linux kernels, but rather shows a single generic kernel just | ||
262 | for conceptual purposes. Also keep in mind that this structure | ||
263 | represents the Yocto Project | ||
264 | Source Repositories | ||
265 | that are either pulled from during the build or established on the | ||
266 | host development system prior to the build by either cloning a | ||
267 | particular kernel's Git repository or by downloading and unpacking a | ||
268 | tarball. | ||
269 | |||
270 | Working with the kernel as a structured tree follows recognized | ||
271 | community best practices. In particular, the kernel as shipped with the | ||
272 | product, should be considered an "upstream source" and viewed as a | ||
273 | series of historical and documented modifications (commits). These | ||
274 | modifications represent the development and stabilization done by the | ||
275 | Yocto Project kernel development team. | ||
276 | |||
277 | Because commits only change at significant release points in the product | ||
278 | life cycle, developers can work on a branch created from the last | ||
279 | relevant commit in the shipped Yocto Project Linux kernel. As mentioned | ||
280 | previously, the structure is transparent to the developer because the | ||
281 | kernel tree is left in this state after cloning and building the kernel. | ||
282 | |||
283 | Kernel Build File Hierarchy | ||
284 | =========================== | ||
285 | |||
286 | Upstream storage of all the available kernel source code is one thing, | ||
287 | while representing and using the code on your host development system is | ||
288 | another. Conceptually, you can think of the kernel source repositories | ||
289 | as all the source files necessary for all the supported Yocto Linux | ||
290 | kernels. As a developer, you are just interested in the source files for | ||
291 | the kernel on which you are working. And, furthermore, you need them | ||
292 | available on your host system. | ||
293 | |||
294 | Kernel source code is available on your host system several different | ||
295 | ways: | ||
296 | |||
297 | - *Files Accessed While using devtool:* ``devtool``, which is | ||
298 | available with the Yocto Project, is the preferred method by which to | ||
299 | modify the kernel. See the ":ref:`kernel-dev/kernel-dev-intro:kernel modification workflow`" section. | ||
300 | |||
301 | - *Cloned Repository:* If you are working in the kernel all the time, | ||
302 | you probably would want to set up your own local Git repository of | ||
303 | the Yocto Linux kernel tree. For information on how to clone a Yocto | ||
304 | Linux kernel Git repository, see the | ||
305 | ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`" | ||
306 | section. | ||
307 | |||
308 | - *Temporary Source Files from a Build:* If you just need to make some | ||
309 | patches to the kernel using a traditional BitBake workflow (i.e. not | ||
310 | using the ``devtool``), you can access temporary kernel source files | ||
311 | that were extracted and used during a kernel build. | ||
312 | |||
313 | The temporary kernel source files resulting from a build using BitBake | ||
314 | have a particular hierarchy. When you build the kernel on your | ||
315 | development system, all files needed for the build are taken from the | ||
316 | source repositories pointed to by the | ||
317 | :term:`SRC_URI` variable and gathered | ||
318 | in a temporary work area where they are subsequently used to create the | ||
319 | unique kernel. Thus, in a sense, the process constructs a local source | ||
320 | tree specific to your kernel from which to generate the new kernel | ||
321 | image. | ||
322 | |||
323 | The following figure shows the temporary file structure created on your | ||
324 | host system when you build the kernel using Bitbake. This | ||
325 | :term:`Build Directory` contains all the | ||
326 | source files used during the build. | ||
327 | |||
328 | .. image:: figures/kernel-overview-2-generic.png | ||
329 | :align: center | ||
330 | |||
331 | Again, for additional information on the Yocto Project kernel's | ||
332 | architecture and its branching strategy, see the | ||
333 | ":ref:`kernel-dev/kernel-dev-concepts-appx:yocto linux kernel architecture and branching strategies`" | ||
334 | section. You can also reference the | ||
335 | ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`" | ||
336 | and | ||
337 | ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`" | ||
338 | sections for detailed example that modifies the kernel. | ||
339 | |||
340 | Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase | ||
341 | ======================================================================================= | ||
342 | |||
343 | This section describes part of the kernel configuration audit phase that | ||
344 | most developers can ignore. For general information on kernel | ||
345 | configuration including ``menuconfig``, ``defconfig`` files, and | ||
346 | configuration fragments, see the | ||
347 | ":ref:`kernel-dev/kernel-dev-common:configuring the kernel`" section. | ||
348 | |||
349 | During this part of the audit phase, the contents of the final | ||
350 | ``.config`` file are compared against the fragments specified by the | ||
351 | system. These fragments can be system fragments, distro fragments, or | ||
352 | user-specified configuration elements. Regardless of their origin, the | ||
353 | OpenEmbedded build system warns the user if a specific option is not | ||
354 | included in the final kernel configuration. | ||
355 | |||
356 | By default, in order to not overwhelm the user with configuration | ||
357 | warnings, the system only reports missing "hardware" options as they | ||
358 | could result in a boot failure or indicate that important hardware is | ||
359 | not available. | ||
360 | |||
361 | To determine whether or not a given option is "hardware" or | ||
362 | "non-hardware", the kernel Metadata in ``yocto-kernel-cache`` contains | ||
363 | files that classify individual or groups of options as either hardware | ||
364 | or non-hardware. To better show this, consider a situation where the | ||
365 | ``yocto-kernel-cache`` contains the following files: | ||
366 | :: | ||
367 | |||
368 | yocto-kernel-cache/features/drm-psb/hardware.cfg | ||
369 | yocto-kernel-cache/features/kgdb/hardware.cfg | ||
370 | yocto-kernel-cache/ktypes/base/hardware.cfg | ||
371 | yocto-kernel-cache/bsp/mti-malta32/hardware.cfg | ||
372 | yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg | ||
373 | yocto-kernel-cache/bsp/qemuarma9/hardware.cfg | ||
374 | yocto-kernel-cache/bsp/mti-malta64/hardware.cfg | ||
375 | yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg | ||
376 | yocto-kernel-cache/bsp/common-pc/hardware.cfg | ||
377 | yocto-kernel-cache/bsp/common-pc-64/hardware.cfg | ||
378 | yocto-kernel-cache/features/rfkill/non-hardware.cfg | ||
379 | yocto-kernel-cache/ktypes/base/non-hardware.cfg | ||
380 | yocto-kernel-cache/features/aufs/non-hardware.kcf | ||
381 | yocto-kernel-cache/features/ocf/non-hardware.kcf | ||
382 | yocto-kernel-cache/ktypes/base/non-hardware.kcf | ||
383 | yocto-kernel-cache/ktypes/base/hardware.kcf | ||
384 | yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf | ||
385 | |||
386 | The following list | ||
387 | provides explanations for the various files: | ||
388 | |||
389 | - ``hardware.kcf``: Specifies a list of kernel Kconfig files that | ||
390 | contain hardware options only. | ||
391 | |||
392 | - ``non-hardware.kcf``: Specifies a list of kernel Kconfig files that | ||
393 | contain non-hardware options only. | ||
394 | |||
395 | - ``hardware.cfg``: Specifies a list of kernel ``CONFIG_`` options that | ||
396 | are hardware, regardless of whether or not they are within a Kconfig | ||
397 | file specified by a hardware or non-hardware Kconfig file (i.e. | ||
398 | ``hardware.kcf`` or ``non-hardware.kcf``). | ||
399 | |||
400 | - ``non-hardware.cfg``: Specifies a list of kernel ``CONFIG_`` options | ||
401 | that are not hardware, regardless of whether or not they are within a | ||
402 | Kconfig file specified by a hardware or non-hardware Kconfig file | ||
403 | (i.e. ``hardware.kcf`` or ``non-hardware.kcf``). | ||
404 | |||
405 | Here is a specific example using the | ||
406 | ``kernel-cache/bsp/mti-malta32/hardware.cfg``: | ||
407 | :: | ||
408 | |||
409 | CONFIG_SERIAL_8250 | ||
410 | CONFIG_SERIAL_8250_CONSOLE | ||
411 | CONFIG_SERIAL_8250_NR_UARTS | ||
412 | CONFIG_SERIAL_8250_PCI | ||
413 | CONFIG_SERIAL_CORE | ||
414 | CONFIG_SERIAL_CORE_CONSOLE | ||
415 | CONFIG_VGA_ARB | ||
416 | |||
417 | The kernel configuration audit automatically detects | ||
418 | these files (hence the names must be exactly the ones discussed here), | ||
419 | and uses them as inputs when generating warnings about the final | ||
420 | ``.config`` file. | ||
421 | |||
422 | A user-specified kernel Metadata repository, or recipe space feature, | ||
423 | can use these same files to classify options that are found within its | ||
424 | ``.cfg`` files as hardware or non-hardware, to prevent the OpenEmbedded | ||
425 | build system from producing an error or warning when an option is not in | ||
426 | the final ``.config`` file. | ||
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml index 62c68527d2..bf0c525caf 100644 --- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <appendix id='kernel-dev-concepts-appx'> | 6 | <appendix id='kernel-dev-concepts-appx'> |
6 | <title>Advanced Kernel Concepts</title> | 7 | <title>Advanced Kernel Concepts</title> |
@@ -191,7 +192,7 @@ | |||
191 | Forward porting Linux kernel functionality into the Yocto Linux | 192 | Forward porting Linux kernel functionality into the Yocto Linux |
192 | kernels available through the Yocto Project can be thought of as | 193 | kernels available through the Yocto Project can be thought of as |
193 | a "micro uprev." | 194 | a "micro uprev." |
194 | The many “micro uprevs” produce a Yocto Linux kernel version with | 195 | The many "micro uprevs" produce a Yocto Linux kernel version with |
195 | a mix of important new mainline, non-mainline, BSP developments | 196 | a mix of important new mainline, non-mainline, BSP developments |
196 | and feature integrations. | 197 | and feature integrations. |
197 | This Yocto Linux kernel gives insight into new features and | 198 | This Yocto Linux kernel gives insight into new features and |
diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl index 325b738e94..88bf7c678a 100644 --- a/documentation/kernel-dev/kernel-dev-customization.xsl +++ b/documentation/kernel-dev/kernel-dev-customization.xsl | |||
@@ -1,4 +1,6 @@ | |||
1 | <?xml version='1.0'?> | 1 | <?xml version='1.0'?> |
2 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
3 | |||
2 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> | 4 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> |
3 | 5 | ||
4 | <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> | 6 | <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> |
diff --git a/documentation/kernel-dev/kernel-dev-faq.rst b/documentation/kernel-dev/kernel-dev-faq.rst new file mode 100644 index 0000000000..b5e6a84eba --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-faq.rst | |||
@@ -0,0 +1,81 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ********************** | ||
4 | Kernel Development FAQ | ||
5 | ********************** | ||
6 | |||
7 | .. _kernel-dev-faq-section: | ||
8 | |||
9 | Common Questions and Solutions | ||
10 | ============================== | ||
11 | |||
12 | The following lists some solutions for common questions. | ||
13 | |||
14 | How do I use my own Linux kernel ``.config`` file? | ||
15 | -------------------------------------------------- | ||
16 | |||
17 | Refer to the | ||
18 | ":ref:`kernel-dev/kernel-dev-common:changing the configuration`" | ||
19 | section for information. | ||
20 | |||
21 | How do I create configuration fragments? | ||
22 | ---------------------------------------- | ||
23 | |||
24 | A: Refer to the | ||
25 | ":ref:`kernel-dev/kernel-dev-common:creating configuration fragments`" | ||
26 | section for information. | ||
27 | |||
28 | How do I use my own Linux kernel sources? | ||
29 | ----------------------------------------- | ||
30 | |||
31 | Refer to the | ||
32 | ":ref:`kernel-dev/kernel-dev-common:working with your own sources`" | ||
33 | section for information. | ||
34 | |||
35 | How do I install/not-install the kernel image on the rootfs? | ||
36 | ------------------------------------------------------------ | ||
37 | |||
38 | The kernel image (e.g. ``vmlinuz``) is provided by the | ||
39 | ``kernel-image`` package. Image recipes depend on ``kernel-base``. To | ||
40 | specify whether or not the kernel image is installed in the generated | ||
41 | root filesystem, override ``RDEPENDS_kernel-base`` to include or not | ||
42 | include "kernel-image". See the | ||
43 | ":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`" | ||
44 | section in the | ||
45 | Yocto Project Development Tasks Manual for information on how to use an | ||
46 | append file to override metadata. | ||
47 | |||
48 | How do I install a specific kernel module? | ||
49 | ------------------------------------------ | ||
50 | |||
51 | Linux kernel modules are packaged individually. To ensure a | ||
52 | specific kernel module is included in an image, include it in the | ||
53 | appropriate machine | ||
54 | :term:`RRECOMMENDS` variable. | ||
55 | These other variables are useful for installing specific modules: | ||
56 | :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` | ||
57 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` | ||
58 | :term:`MACHINE_EXTRA_RDEPENDS` | ||
59 | :term:`MACHINE_EXTRA_RRECOMMENDS` | ||
60 | For example, set the following in the ``qemux86.conf`` file to include | ||
61 | the ``ab123`` kernel modules with images built for the ``qemux86`` | ||
62 | machine: | ||
63 | :: | ||
64 | |||
65 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" | ||
66 | |||
67 | For more | ||
68 | information, see the "`Incorporating Out-of-Tree | ||
69 | Modules <#incorporating-out-of-tree-modules>`__" section. | ||
70 | |||
71 | How do I change the Linux kernel command line? | ||
72 | ---------------------------------------------- | ||
73 | |||
74 | The Linux kernel command line is | ||
75 | typically specified in the machine config using the ``APPEND`` variable. | ||
76 | For example, you can add some helpful debug information doing the | ||
77 | following: | ||
78 | :: | ||
79 | |||
80 | APPEND += "printk.time=y initcall_debug debug" | ||
81 | |||
diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml index c3a20465a0..d76f0a4e32 100644 --- a/documentation/kernel-dev/kernel-dev-faq.xml +++ b/documentation/kernel-dev/kernel-dev-faq.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <appendix id='kernel-dev-faq'> | 6 | <appendix id='kernel-dev-faq'> |
6 | <title>Kernel Development FAQ</title> | 7 | <title>Kernel Development FAQ</title> |
diff --git a/documentation/kernel-dev/kernel-dev-intro.rst b/documentation/kernel-dev/kernel-dev-intro.rst new file mode 100644 index 0000000000..21d43d5e80 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-intro.rst | |||
@@ -0,0 +1,183 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ************ | ||
4 | Introduction | ||
5 | ************ | ||
6 | |||
7 | .. _kernel-dev-overview: | ||
8 | |||
9 | Overview | ||
10 | ======== | ||
11 | |||
12 | Regardless of how you intend to make use of the Yocto Project, chances | ||
13 | are you will work with the Linux kernel. This manual describes how to | ||
14 | set up your build host to support kernel development, introduces the | ||
15 | kernel development process, provides background information on the Yocto | ||
16 | Linux kernel :term:`Metadata`, describes | ||
17 | common tasks you can perform using the kernel tools, shows you how to | ||
18 | use the kernel Metadata needed to work with the kernel inside the Yocto | ||
19 | Project, and provides insight into how the Yocto Project team develops | ||
20 | and maintains Yocto Linux kernel Git repositories and Metadata. | ||
21 | |||
22 | Each Yocto Project release has a set of Yocto Linux kernel recipes, | ||
23 | whose Git repositories you can view in the Yocto | ||
24 | :yocto_git:`Source Repositories <>` under the "Yocto Linux Kernel" | ||
25 | heading. New recipes for the release track the latest Linux kernel | ||
26 | upstream developments from http://www.kernel.org> and introduce | ||
27 | newly-supported platforms. Previous recipes in the release are refreshed | ||
28 | and supported for at least one additional Yocto Project release. As they | ||
29 | align, these previous releases are updated to include the latest from | ||
30 | the Long Term Support Initiative (LTSI) project. You can learn more | ||
31 | about Yocto Linux kernels and LTSI in the ":ref:`Yocto Project Kernel | ||
32 | Development and Maintenance <kernel-big-picture>`" section. | ||
33 | |||
34 | Also included is a Yocto Linux kernel development recipe | ||
35 | (``linux-yocto-dev.bb``) should you want to work with the very latest in | ||
36 | upstream Yocto Linux kernel development and kernel Metadata development. | ||
37 | |||
38 | .. note:: | ||
39 | |||
40 | For more on Yocto Linux kernels, see the " | ||
41 | Yocto Project Kernel Development and Maintenance | ||
42 | section. | ||
43 | |||
44 | The Yocto Project also provides a powerful set of kernel tools for | ||
45 | managing Yocto Linux kernel sources and configuration data. You can use | ||
46 | these tools to make a single configuration change, apply multiple | ||
47 | patches, or work with your own kernel sources. | ||
48 | |||
49 | In particular, the kernel tools allow you to generate configuration | ||
50 | fragments that specify only what you must, and nothing more. | ||
51 | Configuration fragments only need to contain the highest level visible | ||
52 | ``CONFIG`` options as presented by the Yocto Linux kernel ``menuconfig`` | ||
53 | system. Contrast this against a complete Yocto Linux kernel ``.config`` | ||
54 | file, which includes all the automatically selected ``CONFIG`` options. | ||
55 | This efficiency reduces your maintenance effort and allows you to | ||
56 | further separate your configuration in ways that make sense for your | ||
57 | project. A common split separates policy and hardware. For example, all | ||
58 | your kernels might support the ``proc`` and ``sys`` filesystems, but | ||
59 | only specific boards require sound, USB, or specific drivers. Specifying | ||
60 | these configurations individually allows you to aggregate them together | ||
61 | as needed, but maintains them in only one place. Similar logic applies | ||
62 | to separating source changes. | ||
63 | |||
64 | If you do not maintain your own kernel sources and need to make only | ||
65 | minimal changes to the sources, the released recipes provide a vetted | ||
66 | base upon which to layer your changes. Doing so allows you to benefit | ||
67 | from the continual kernel integration and testing performed during | ||
68 | development of the Yocto Project. | ||
69 | |||
70 | If, instead, you have a very specific Linux kernel source tree and are | ||
71 | unable to align with one of the official Yocto Linux kernel recipes, an | ||
72 | alternative exists by which you can use the Yocto Project Linux kernel | ||
73 | tools with your own kernel sources. | ||
74 | |||
75 | The remainder of this manual provides instructions for completing | ||
76 | specific Linux kernel development tasks. These instructions assume you | ||
77 | are comfortable working with | ||
78 | `BitBake <http://openembedded.org/wiki/Bitbake>`__ recipes and basic | ||
79 | open-source development tools. Understanding these concepts will | ||
80 | facilitate the process of working with the kernel recipes. If you find | ||
81 | you need some additional background, please be sure to review and | ||
82 | understand the following documentation: | ||
83 | |||
84 | - :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. | ||
85 | |||
86 | - :doc:`../overview-manual/overview-manual`. | ||
87 | |||
88 | - :ref:`devtool | ||
89 | workflow <sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow>` | ||
90 | as described in the Yocto Project Application Development and the | ||
91 | Extensible Software Development Kit (eSDK) manual. | ||
92 | |||
93 | - The ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" | ||
94 | section in the Yocto Project Development Tasks Manual. | ||
95 | |||
96 | - The "`Kernel Modification | ||
97 | Workflow <#kernel-modification-workflow>`__" section. | ||
98 | |||
99 | Kernel Modification Workflow | ||
100 | ============================ | ||
101 | |||
102 | Kernel modification involves changing the Yocto Project kernel, which | ||
103 | could involve changing configuration options as well as adding new | ||
104 | kernel recipes. Configuration changes can be added in the form of | ||
105 | configuration fragments, while recipe modification comes through the | ||
106 | kernel's ``recipes-kernel`` area in a kernel layer you create. | ||
107 | |||
108 | This section presents a high-level overview of the Yocto Project kernel | ||
109 | modification workflow. The illustration and accompanying list provide | ||
110 | general information and references for further information. | ||
111 | |||
112 | .. image:: figures/kernel-dev-flow.png | ||
113 | :align: center | ||
114 | |||
115 | 1. *Set up Your Host Development System to Support Development Using the | ||
116 | Yocto Project*: See the ":doc:`../dev-manual/dev-manual-start`" section in | ||
117 | the Yocto Project Development Tasks Manual for options on how to get | ||
118 | a build host ready to use the Yocto Project. | ||
119 | |||
120 | 2. *Set Up Your Host Development System for Kernel Development:* It is | ||
121 | recommended that you use ``devtool`` and an extensible SDK for kernel | ||
122 | development. Alternatively, you can use traditional kernel | ||
123 | development methods with the Yocto Project. Either way, there are | ||
124 | steps you need to take to get the development environment ready. | ||
125 | |||
126 | Using ``devtool`` and the eSDK requires that you have a clean build | ||
127 | of the image and that you are set up with the appropriate eSDK. For | ||
128 | more information, see the | ||
129 | ":ref:`kernel-dev/kernel-dev-common:getting ready to develop using \`\`devtool\`\``" | ||
130 | section. | ||
131 | |||
132 | Using traditional kernel development requires that you have the | ||
133 | kernel source available in an isolated local Git repository. For more | ||
134 | information, see the | ||
135 | ":ref:`kernel-dev/kernel-dev-common:getting ready for traditional kernel development`" | ||
136 | section. | ||
137 | |||
138 | 3. *Make Changes to the Kernel Source Code if applicable:* Modifying the | ||
139 | kernel does not always mean directly changing source files. However, | ||
140 | if you have to do this, you make the changes to the files in the | ||
141 | eSDK's Build Directory if you are using ``devtool``. For more | ||
142 | information, see the | ||
143 | ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`" | ||
144 | section. | ||
145 | |||
146 | If you are using traditional kernel development, you edit the source | ||
147 | files in the kernel's local Git repository. For more information, see the | ||
148 | ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`" | ||
149 | section. | ||
150 | |||
151 | 4. *Make Kernel Configuration Changes if Applicable:* If your situation | ||
152 | calls for changing the kernel's configuration, you can use | ||
153 | :ref:`menuconfig <kernel-dev/kernel-dev-common:using \`\`menuconfig\`\`>`, | ||
154 | which allows you to | ||
155 | interactively develop and test the configuration changes you are | ||
156 | making to the kernel. Saving changes you make with ``menuconfig`` | ||
157 | updates the kernel's ``.config`` file. | ||
158 | |||
159 | .. note:: | ||
160 | |||
161 | Try to resist the temptation to directly edit an existing | ||
162 | .config | ||
163 | file, which is found in the Build Directory among the source code | ||
164 | used for the build. Doing so, can produce unexpected results when | ||
165 | the OpenEmbedded build system regenerates the configuration file. | ||
166 | |||
167 | Once you are satisfied with the configuration changes made using | ||
168 | ``menuconfig`` and you have saved them, you can directly compare the | ||
169 | resulting ``.config`` file against an existing original and gather | ||
170 | those changes into a `configuration fragment | ||
171 | file <#creating-config-fragments>`__ to be referenced from within the | ||
172 | kernel's ``.bbappend`` file. | ||
173 | |||
174 | Additionally, if you are working in a BSP layer and need to modify | ||
175 | the BSP's kernel's configuration, you can use ``menuconfig``. | ||
176 | |||
177 | 5. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel | ||
178 | image applies your changes. Depending on your target hardware, you | ||
179 | can verify your changes on actual hardware or perhaps QEMU. | ||
180 | |||
181 | The remainder of this developer's guide covers common tasks typically | ||
182 | used during kernel development, advanced Metadata usage, and Yocto Linux | ||
183 | kernel maintenance concepts. | ||
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index 4e4fd282a5..7c1ea0e510 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='kernel-dev-intro'> | 6 | <chapter id='kernel-dev-intro'> |
6 | <title>Introduction</title> | 7 | <title>Introduction</title> |
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.rst b/documentation/kernel-dev/kernel-dev-maint-appx.rst new file mode 100644 index 0000000000..5514dac876 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-maint-appx.rst | |||
@@ -0,0 +1,239 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ****************** | ||
4 | Kernel Maintenance | ||
5 | ****************** | ||
6 | |||
7 | Tree Construction | ||
8 | ================= | ||
9 | |||
10 | This section describes construction of the Yocto Project kernel source | ||
11 | repositories as accomplished by the Yocto Project team to create Yocto | ||
12 | Linux kernel repositories. These kernel repositories are found under the | ||
13 | heading "Yocto Linux Kernel" at :yocto_git:`/` and | ||
14 | are shipped as part of a Yocto Project release. The team creates these | ||
15 | repositories by compiling and executing the set of feature descriptions | ||
16 | for every BSP and feature in the product. Those feature descriptions | ||
17 | list all necessary patches, configurations, branches, tags, and feature | ||
18 | divisions found in a Yocto Linux kernel. Thus, the Yocto Project Linux | ||
19 | kernel repository (or tree) and accompanying Metadata in the | ||
20 | ``yocto-kernel-cache`` are built. | ||
21 | |||
22 | The existence of these repositories allow you to access and clone a | ||
23 | particular Yocto Project Linux kernel repository and use it to build | ||
24 | images based on their configurations and features. | ||
25 | |||
26 | You can find the files used to describe all the valid features and BSPs | ||
27 | in the Yocto Project Linux kernel in any clone of the Yocto Project | ||
28 | Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For | ||
29 | example, the following commands clone the Yocto Project baseline Linux | ||
30 | kernel that branches off ``linux.org`` version 4.12 and the | ||
31 | ``yocto-kernel-cache``, which contains stores of kernel Metadata: | ||
32 | :: | ||
33 | |||
34 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 | ||
35 | $ git clone git://git.yoctoproject.org/linux-kernel-cache | ||
36 | |||
37 | For more information on | ||
38 | how to set up a local Git repository of the Yocto Project Linux kernel | ||
39 | files, see the | ||
40 | ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`" | ||
41 | section. | ||
42 | |||
43 | Once you have cloned the kernel Git repository and the cache of Metadata | ||
44 | on your local machine, you can discover the branches that are available | ||
45 | in the repository using the following Git command: $ git branch -a | ||
46 | Checking out a branch allows you to work with a particular Yocto Linux | ||
47 | kernel. For example, the following commands check out the | ||
48 | "standard/beagleboard" branch of the Yocto Linux kernel repository and | ||
49 | the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository: | ||
50 | :: | ||
51 | |||
52 | $ cd ~/linux-yocto-4.12 | ||
53 | $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard | ||
54 | $ cd ~/linux-kernel-cache | ||
55 | $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12 | ||
56 | |||
57 | .. note:: | ||
58 | |||
59 | Branches in the | ||
60 | yocto-kernel-cache | ||
61 | repository correspond to Yocto Linux kernel versions (e.g. | ||
62 | "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth). | ||
63 | |||
64 | Once you have checked out and switched to appropriate branches, you can | ||
65 | see a snapshot of all the kernel source files used to used to build that | ||
66 | particular Yocto Linux kernel for a particular board. | ||
67 | |||
68 | To see the features and configurations for a particular Yocto Linux | ||
69 | kernel, you need to examine the ``yocto-kernel-cache`` Git repository. | ||
70 | As mentioned, branches in the ``yocto-kernel-cache`` repository | ||
71 | correspond to Yocto Linux kernel versions (e.g. ``yocto-4.12``). | ||
72 | Branches contain descriptions in the form of ``.scc`` and ``.cfg`` | ||
73 | files. | ||
74 | |||
75 | You should realize, however, that browsing your local | ||
76 | ``yocto-kernel-cache`` repository for feature descriptions and patches | ||
77 | is not an effective way to determine what is in a particular kernel | ||
78 | branch. Instead, you should use Git directly to discover the changes in | ||
79 | a branch. Using Git is an efficient and flexible way to inspect changes | ||
80 | to the kernel. | ||
81 | |||
82 | .. note:: | ||
83 | |||
84 | Ground up reconstruction of the complete kernel tree is an action | ||
85 | only taken by the Yocto Project team during an active development | ||
86 | cycle. When you create a clone of the kernel Git repository, you are | ||
87 | simply making it efficiently available for building and development. | ||
88 | |||
89 | The following steps describe what happens when the Yocto Project Team | ||
90 | constructs the Yocto Project kernel source Git repository (or tree) | ||
91 | found at :yocto_git:`/` given the introduction of a new | ||
92 | top-level kernel feature or BSP. The following actions effectively | ||
93 | provide the Metadata and create the tree that includes the new feature, | ||
94 | patch, or BSP: | ||
95 | |||
96 | 1. *Pass Feature to the OpenEmbedded Build System:* A top-level kernel | ||
97 | feature is passed to the kernel build subsystem. Normally, this | ||
98 | feature is a BSP for a particular kernel type. | ||
99 | |||
100 | 2. *Locate Feature:* The file that describes the top-level feature is | ||
101 | located by searching these system directories: | ||
102 | |||
103 | - The in-tree kernel-cache directories, which are located in the | ||
104 | :yocto_git:`yocto-kernel-cache </cgit/cgit.cgi/yocto-kernel-cache/tree/bsp>` | ||
105 | repository organized under the "Yocto Linux Kernel" heading in the | ||
106 | :yocto_git:`Yocto Project Source Repositories <>`. | ||
107 | |||
108 | - Areas pointed to by ``SRC_URI`` statements found in kernel recipes | ||
109 | |||
110 | For a typical build, the target of the search is a feature | ||
111 | description in an ``.scc`` file whose name follows this format (e.g. | ||
112 | ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``): | ||
113 | :: | ||
114 | |||
115 | bsp_root_name-kernel_type.scc | ||
116 | |||
117 | 3. *Expand Feature:* Once located, the feature description is either | ||
118 | expanded into a simple script of actions, or into an existing | ||
119 | equivalent script that is already part of the shipped kernel. | ||
120 | |||
121 | 4. *Append Extra Features:* Extra features are appended to the top-level | ||
122 | feature description. These features can come from the | ||
123 | :term:`KERNEL_FEATURES` | ||
124 | variable in recipes. | ||
125 | |||
126 | 5. *Locate, Expand, and Append Each Feature:* Each extra feature is | ||
127 | located, expanded and appended to the script as described in step | ||
128 | three. | ||
129 | |||
130 | 6. *Execute the Script:* The script is executed to produce files | ||
131 | ``.scc`` and ``.cfg`` files in appropriate directories of the | ||
132 | ``yocto-kernel-cache`` repository. These files are descriptions of | ||
133 | all the branches, tags, patches and configurations that need to be | ||
134 | applied to the base Git repository to completely create the source | ||
135 | (build) branch for the new BSP or feature. | ||
136 | |||
137 | 7. *Clone Base Repository:* The base repository is cloned, and the | ||
138 | actions listed in the ``yocto-kernel-cache`` directories are applied | ||
139 | to the tree. | ||
140 | |||
141 | 8. *Perform Cleanup:* The Git repositories are left with the desired | ||
142 | branches checked out and any required branching, patching and tagging | ||
143 | has been performed. | ||
144 | |||
145 | The kernel tree and cache are ready for developer consumption to be | ||
146 | locally cloned, configured, and built into a Yocto Project kernel | ||
147 | specific to some target hardware. | ||
148 | |||
149 | .. note:: | ||
150 | |||
151 | - The generated ``yocto-kernel-cache`` repository adds to the kernel | ||
152 | as shipped with the Yocto Project release. Any add-ons and | ||
153 | configuration data are applied to the end of an existing branch. | ||
154 | The full repository generation that is found in the official Yocto | ||
155 | Project kernel repositories at :yocto_git:`/` is the | ||
156 | combination of all supported boards and configurations. | ||
157 | |||
158 | - The technique the Yocto Project team uses is flexible and allows | ||
159 | for seamless blending of an immutable history with additional | ||
160 | patches specific to a deployment. Any additions to the kernel | ||
161 | become an integrated part of the branches. | ||
162 | |||
163 | - The full kernel tree that you see on :yocto_git:`/` is | ||
164 | generated through repeating the above steps for all valid BSPs. | ||
165 | The end result is a branched, clean history tree that makes up the | ||
166 | kernel for a given release. You can see the script (``kgit-scc``) | ||
167 | responsible for this in the | ||
168 | :yocto_git:`yocto-kernel-tools </cgit.cgi/yocto-kernel-tools/tree/tools>` | ||
169 | repository. | ||
170 | |||
171 | - The steps used to construct the full kernel tree are the same | ||
172 | steps that BitBake uses when it builds a kernel image. | ||
173 | |||
174 | Build Strategy | ||
175 | ============== | ||
176 | |||
177 | Once you have cloned a Yocto Linux kernel repository and the cache | ||
178 | repository (``yocto-kernel-cache``) onto your development system, you | ||
179 | can consider the compilation phase of kernel development, which is | ||
180 | building a kernel image. Some prerequisites exist that are validated by | ||
181 | the build process before compilation starts: | ||
182 | |||
183 | - The :term:`SRC_URI` points to the | ||
184 | kernel Git repository. | ||
185 | |||
186 | - A BSP build branch with Metadata exists in the ``yocto-kernel-cache`` | ||
187 | repository. The branch is based on the Yocto Linux kernel version and | ||
188 | has configurations and features grouped under the | ||
189 | ``yocto-kernel-cache/bsp`` directory. For example, features and | ||
190 | configurations for the BeagleBone Board assuming a | ||
191 | ``linux-yocto_4.12`` kernel reside in the following area of the | ||
192 | ``yocto-kernel-cache`` repository: yocto-kernel-cache/bsp/beaglebone | ||
193 | |||
194 | .. note:: | ||
195 | |||
196 | In the previous example, the "yocto-4.12" branch is checked out in | ||
197 | the | ||
198 | yocto-kernel-cache | ||
199 | repository. | ||
200 | |||
201 | The OpenEmbedded build system makes sure these conditions exist before | ||
202 | attempting compilation. Other means, however, do exist, such as as | ||
203 | bootstrapping a BSP. | ||
204 | |||
205 | Before building a kernel, the build process verifies the tree and | ||
206 | configures the kernel by processing all of the configuration "fragments" | ||
207 | specified by feature descriptions in the ``.scc`` files. As the features | ||
208 | are compiled, associated kernel configuration fragments are noted and | ||
209 | recorded in the series of directories in their compilation order. The | ||
210 | fragments are migrated, pre-processed and passed to the Linux Kernel | ||
211 | Configuration subsystem (``lkc``) as raw input in the form of a | ||
212 | ``.config`` file. The ``lkc`` uses its own internal dependency | ||
213 | constraints to do the final processing of that information and generates | ||
214 | the final ``.config`` file that is used during compilation. | ||
215 | |||
216 | Using the board's architecture and other relevant values from the | ||
217 | board's template, kernel compilation is started and a kernel image is | ||
218 | produced. | ||
219 | |||
220 | The other thing that you notice once you configure a kernel is that the | ||
221 | build process generates a build tree that is separate from your kernel's | ||
222 | local Git source repository tree. This build tree has a name that uses | ||
223 | the following form, where ``${MACHINE}`` is the metadata name of the | ||
224 | machine (BSP) and "kernel_type" is one of the Yocto Project supported | ||
225 | kernel types (e.g. "standard"): | ||
226 | :: | ||
227 | |||
228 | linux-${MACHINE}-kernel_type-build | ||
229 | |||
230 | The existing support in the ``kernel.org`` tree achieves this default | ||
231 | functionality. | ||
232 | |||
233 | This behavior means that all the generated files for a particular | ||
234 | machine or BSP are now in the build tree directory. The files include | ||
235 | the final ``.config`` file, all the ``.o`` files, the ``.a`` files, and | ||
236 | so forth. Since each machine or BSP has its own separate | ||
237 | :term:`Build Directory` in its own separate | ||
238 | branch of the Git repository, you can easily switch between different | ||
239 | builds. | ||
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml index b825ae7ea5..3d9c7c66fd 100644 --- a/documentation/kernel-dev/kernel-dev-maint-appx.xml +++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <appendix id='kernel-dev-maint-appx'> | 6 | <appendix id='kernel-dev-maint-appx'> |
6 | <title>Kernel Maintenance</title> | 7 | <title>Kernel Maintenance</title> |
diff --git a/documentation/kernel-dev/kernel-dev-style.css b/documentation/kernel-dev/kernel-dev-style.css index 9c01aa7983..fc6fbb8de1 100644 --- a/documentation/kernel-dev/kernel-dev-style.css +++ b/documentation/kernel-dev/kernel-dev-style.css | |||
@@ -1,4 +1,7 @@ | |||
1 | /* | 1 | /* |
2 | |||
3 | SPDX-License-Identifier: CC-BY-2.0-UK | ||
4 | |||
2 | Generic XHTML / DocBook XHTML CSS Stylesheet. | 5 | Generic XHTML / DocBook XHTML CSS Stylesheet. |
3 | 6 | ||
4 | Browser wrangling and typographic design by | 7 | Browser wrangling and typographic design by |
diff --git a/documentation/kernel-dev/kernel-dev.rst b/documentation/kernel-dev/kernel-dev.rst new file mode 100644 index 0000000000..332e089b03 --- /dev/null +++ b/documentation/kernel-dev/kernel-dev.rst | |||
@@ -0,0 +1,21 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ============================================= | ||
4 | Yocto Project Linux Kernel Development Manual | ||
5 | ============================================= | ||
6 | |||
7 | | | ||
8 | |||
9 | .. toctree:: | ||
10 | :caption: Table of Contents | ||
11 | :numbered: | ||
12 | |||
13 | kernel-dev-intro | ||
14 | kernel-dev-common | ||
15 | kernel-dev-advanced | ||
16 | kernel-dev-concepts-appx | ||
17 | kernel-dev-maint-appx | ||
18 | kernel-dev-faq | ||
19 | history | ||
20 | |||
21 | .. include:: /boilerplate.rst | ||
diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml index 76256c9c3e..887ff836f1 100755 --- a/documentation/kernel-dev/kernel-dev.xml +++ b/documentation/kernel-dev/kernel-dev.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <book id='kernel-dev' lang='en' | 6 | <book id='kernel-dev' lang='en' |
6 | xmlns:xi="http://www.w3.org/2003/XInclude" | 7 | xmlns:xi="http://www.w3.org/2003/XInclude" |
@@ -102,28 +103,8 @@ | |||
102 | </revision> | 103 | </revision> |
103 | <revision> | 104 | <revision> |
104 | <revnumber>3.1</revnumber> | 105 | <revnumber>3.1</revnumber> |
105 | <date>April 2020</date> | ||
106 | <revremark>Released with the Yocto Project 3.1 Release.</revremark> | ||
107 | </revision> | ||
108 | <revision> | ||
109 | <revnumber>3.1.1</revnumber> | ||
110 | <date>June 2020</date> | ||
111 | <revremark>Released with the Yocto Project 3.1.1 Release.</revremark> | ||
112 | </revision> | ||
113 | <revision> | ||
114 | <revnumber>3.1.2</revnumber> | ||
115 | <date>August 2020</date> | ||
116 | <revremark>Released with the Yocto Project 3.1.2 Release.</revremark> | ||
117 | </revision> | ||
118 | <revision> | ||
119 | <revnumber>3.1.3</revnumber> | ||
120 | <date>October 2020</date> | ||
121 | <revremark>Released with the Yocto Project 3.1.3 Release.</revremark> | ||
122 | </revision> | ||
123 | <revision> | ||
124 | <revnumber>3.1.4</revnumber> | ||
125 | <date>&REL_MONTH_YEAR;</date> | 106 | <date>&REL_MONTH_YEAR;</date> |
126 | <revremark>Released with the Yocto Project 3.1.4 Release.</revremark> | 107 | <revremark>Released with the Yocto Project 3.1 Release.</revremark> |
127 | </revision> | 108 | </revision> |
128 | </revhistory> | 109 | </revhistory> |
129 | 110 | ||