diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.rst')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-advanced.rst | 983 |
1 files changed, 983 insertions, 0 deletions
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 | |||