diff options
Diffstat (limited to 'documentation/kernel-dev/advanced.rst')
-rw-r--r-- | documentation/kernel-dev/advanced.rst | 949 |
1 files changed, 949 insertions, 0 deletions
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst new file mode 100644 index 0000000000..163560b691 --- /dev/null +++ b/documentation/kernel-dev/advanced.rst | |||
@@ -0,0 +1,949 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | ******************************************************* | ||
4 | Working with Advanced Metadata (``yocto-kernel-cache``) | ||
5 | ******************************************************* | ||
6 | |||
7 | Overview | ||
8 | ======== | ||
9 | |||
10 | In addition to supporting configuration fragments and patches, the Yocto | ||
11 | Project kernel tools also support rich | ||
12 | :term:`Metadata` that you can use to define | ||
13 | complex policies and Board Support Package (BSP) support. The purpose of | ||
14 | the Metadata and the tools that manage it is to help you manage the | ||
15 | complexity of the configuration and sources used to support multiple | ||
16 | BSPs and Linux kernel types. | ||
17 | |||
18 | Kernel Metadata exists in many places. One area in the | ||
19 | :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` | ||
20 | is the ``yocto-kernel-cache`` Git repository. You can find this repository | ||
21 | grouped under the "Yocto Linux Kernel" heading in the | ||
22 | :yocto_git:`Yocto Project Source Repositories <>`. | ||
23 | |||
24 | Kernel development tools ("kern-tools") exist also in the Yocto Project | ||
25 | Source Repositories under the "Yocto Linux Kernel" heading in the | ||
26 | ``yocto-kernel-tools`` Git repository. The recipe that builds these | ||
27 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in | ||
28 | the :term:`Source Directory` (e.g. | ||
29 | ``poky``). | ||
30 | |||
31 | Using Kernel Metadata in a Recipe | ||
32 | ================================= | ||
33 | |||
34 | As mentioned in the introduction, the Yocto Project contains kernel | ||
35 | Metadata, which is located in the ``yocto-kernel-cache`` Git repository. | ||
36 | This Metadata defines Board Support Packages (BSPs) that correspond to | ||
37 | definitions in linux-yocto recipes for corresponding BSPs. A BSP | ||
38 | consists of an aggregation of kernel policy and enabled | ||
39 | hardware-specific features. The BSP can be influenced from within the | ||
40 | linux-yocto recipe. | ||
41 | |||
42 | .. note:: | ||
43 | |||
44 | A Linux kernel recipe that contains kernel Metadata (e.g. inherits | ||
45 | from the ``linux-yocto.inc`` file) is said to be a "linux-yocto style" recipe. | ||
46 | |||
47 | Every linux-yocto style recipe must define the | ||
48 | :term:`KMACHINE` variable. This | ||
49 | variable is typically set to the same value as the ``MACHINE`` variable, | ||
50 | which is used by :term:`BitBake`. | ||
51 | However, in some cases, the variable might instead refer to the | ||
52 | underlying platform of the ``MACHINE``. | ||
53 | |||
54 | Multiple BSPs can reuse the same ``KMACHINE`` name if they are built | ||
55 | using the same BSP description. Multiple Corei7-based BSPs could share | ||
56 | the same "intel-corei7-64" value for ``KMACHINE``. It is important to | ||
57 | realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE`` | ||
58 | is the machine type within a BSP Layer. Even with this distinction, | ||
59 | however, these two variables can hold the same value. See the `BSP | ||
60 | Descriptions <#bsp-descriptions>`__ section for more information. | ||
61 | |||
62 | Every linux-yocto style recipe must also indicate the Linux kernel | ||
63 | source repository branch used to build the Linux kernel. The | ||
64 | :term:`KBRANCH` variable must be set | ||
65 | to indicate the branch. | ||
66 | |||
67 | .. note:: | ||
68 | |||
69 | You can use the ``KBRANCH`` value to define an alternate branch typically | ||
70 | with a machine override as shown here from the ``meta-yocto-bsp`` layer: | ||
71 | :: | ||
72 | |||
73 | KBRANCH_edgerouter = "standard/edgerouter" | ||
74 | |||
75 | |||
76 | The linux-yocto style recipes can optionally define the following | ||
77 | variables: | ||
78 | |||
79 | - :term:`KERNEL_FEATURES` | ||
80 | |||
81 | - :term:`LINUX_KERNEL_TYPE` | ||
82 | |||
83 | :term:`LINUX_KERNEL_TYPE` | ||
84 | defines the kernel type to be used in assembling the configuration. If | ||
85 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". | ||
86 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search | ||
87 | arguments used by the kernel tools to find the appropriate description | ||
88 | within the kernel Metadata with which to build out the sources and | ||
89 | configuration. The linux-yocto recipes define "standard", "tiny", and | ||
90 | "preempt-rt" kernel types. See the "`Kernel Types <#kernel-types>`__" | ||
91 | section for more information on kernel types. | ||
92 | |||
93 | During the build, the kern-tools search for the BSP description file | ||
94 | that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE`` | ||
95 | variables passed in from the recipe. The tools use the first BSP | ||
96 | description they find that matches both variables. If the tools cannot find | ||
97 | a match, they issue a warning. | ||
98 | |||
99 | The tools first search for the ``KMACHINE`` and then for the | ||
100 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they | ||
101 | will use the sources from the ``KBRANCH`` and any configuration | ||
102 | specified in the :term:`SRC_URI`. | ||
103 | |||
104 | You can use the | ||
105 | :term:`KERNEL_FEATURES` | ||
106 | variable to include features (configuration fragments, patches, or both) | ||
107 | that are not already included by the ``KMACHINE`` and | ||
108 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a | ||
109 | feature specified as "features/netfilter/netfilter.scc", specify: | ||
110 | :: | ||
111 | |||
112 | KERNEL_FEATURES += "features/netfilter/netfilter.scc" | ||
113 | |||
114 | To include a | ||
115 | feature called "cfg/sound.scc" just for the ``qemux86`` machine, | ||
116 | specify: | ||
117 | :: | ||
118 | |||
119 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" | ||
120 | |||
121 | The value of | ||
122 | the entries in ``KERNEL_FEATURES`` are dependent on their location | ||
123 | within the kernel Metadata itself. The examples here are taken from the | ||
124 | ``yocto-kernel-cache`` repository. Each branch of this repository | ||
125 | contains "features" and "cfg" subdirectories at the top-level. For more | ||
126 | information, see the "`Kernel Metadata | ||
127 | Syntax <#kernel-metadata-syntax>`__" section. | ||
128 | |||
129 | Kernel Metadata Syntax | ||
130 | ====================== | ||
131 | |||
132 | The kernel Metadata consists of three primary types of files: ``scc`` | ||
133 | [1]_ description files, configuration fragments, and patches. The | ||
134 | ``scc`` files define variables and include or otherwise reference any of | ||
135 | the three file types. The description files are used to aggregate all | ||
136 | types of kernel Metadata into what ultimately describes the sources and | ||
137 | the configuration required to build a Linux kernel tailored to a | ||
138 | specific machine. | ||
139 | |||
140 | The ``scc`` description files are used to define two fundamental types | ||
141 | of kernel Metadata: | ||
142 | |||
143 | - Features | ||
144 | |||
145 | - Board Support Packages (BSPs) | ||
146 | |||
147 | Features aggregate sources in the form of patches and configuration | ||
148 | fragments into a modular reusable unit. You can use features to | ||
149 | implement conceptually separate kernel Metadata descriptions such as | ||
150 | pure configuration fragments, simple patches, complex features, and | ||
151 | kernel types. `Kernel types <#kernel-types>`__ define general kernel | ||
152 | features and policy to be reused in the BSPs. | ||
153 | |||
154 | BSPs define hardware-specific features and aggregate them with kernel | ||
155 | types to form the final description of what will be assembled and built. | ||
156 | |||
157 | While the kernel Metadata syntax does not enforce any logical separation | ||
158 | of configuration fragments, patches, features or kernel types, best | ||
159 | practices dictate a logical separation of these types of Metadata. The | ||
160 | following Metadata file hierarchy is recommended: | ||
161 | :: | ||
162 | |||
163 | base/ | ||
164 | bsp/ | ||
165 | cfg/ | ||
166 | features/ | ||
167 | ktypes/ | ||
168 | patches/ | ||
169 | |||
170 | The ``bsp`` directory contains the `BSP | ||
171 | descriptions <#bsp-descriptions>`__. The remaining directories all | ||
172 | contain "features". Separating ``bsp`` from the rest of the structure | ||
173 | aids conceptualizing intended usage. | ||
174 | |||
175 | Use these guidelines to help place your ``scc`` description files within | ||
176 | the structure: | ||
177 | |||
178 | - If your file contains only configuration fragments, place the file in | ||
179 | the ``cfg`` directory. | ||
180 | |||
181 | - If your file contains only source-code fixes, place the file in the | ||
182 | ``patches`` directory. | ||
183 | |||
184 | - If your file encapsulates a major feature, often combining sources | ||
185 | and configurations, place the file in ``features`` directory. | ||
186 | |||
187 | - If your file aggregates non-hardware configuration and patches in | ||
188 | order to define a base kernel policy or major kernel type to be | ||
189 | reused across multiple BSPs, place the file in ``ktypes`` directory. | ||
190 | |||
191 | These distinctions can easily become blurred - especially as out-of-tree | ||
192 | features slowly merge upstream over time. Also, remember that how the | ||
193 | description files are placed is a purely logical organization and has no | ||
194 | impact on the functionality of the kernel Metadata. There is no impact | ||
195 | because all of ``cfg``, ``features``, ``patches``, and ``ktypes``, | ||
196 | contain "features" as far as the kernel tools are concerned. | ||
197 | |||
198 | Paths used in kernel Metadata files are relative to base, which is | ||
199 | either | ||
200 | :term:`FILESEXTRAPATHS` if | ||
201 | you are creating Metadata in `recipe-space <#recipe-space-metadata>`__, | ||
202 | or the top level of | ||
203 | :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>` | ||
204 | if you are creating `Metadata outside of the | ||
205 | recipe-space <#metadata-outside-the-recipe-space>`__. | ||
206 | |||
207 | .. [1] | ||
208 | ``scc`` stands for Series Configuration Control, but the naming has | ||
209 | less significance in the current implementation of the tooling than | ||
210 | it had in the past. Consider ``scc`` files to be description files. | ||
211 | |||
212 | Configuration | ||
213 | ------------- | ||
214 | |||
215 | The simplest unit of kernel Metadata is the configuration-only feature. | ||
216 | This feature consists of one or more Linux kernel configuration | ||
217 | parameters in a configuration fragment file (``.cfg``) and a ``.scc`` | ||
218 | file that describes the fragment. | ||
219 | |||
220 | As an example, consider the Symmetric Multi-Processing (SMP) fragment | ||
221 | used with the ``linux-yocto-4.12`` kernel as defined outside of the | ||
222 | recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of | ||
223 | two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the | ||
224 | ``cfg`` directory of the ``yocto-4.12`` branch in the | ||
225 | ``yocto-kernel-cache`` Git repository: | ||
226 | :: | ||
227 | |||
228 | cfg/smp.scc: | ||
229 | define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" | ||
230 | define KFEATURE_COMPATIBILITY all | ||
231 | |||
232 | kconf hardware smp.cfg | ||
233 | |||
234 | cfg/smp.cfg: | ||
235 | CONFIG_SMP=y | ||
236 | CONFIG_SCHED_SMT=y | ||
237 | # Increase default NR_CPUS from 8 to 64 so that platform with | ||
238 | # more than 8 processors can be all activated at boot time | ||
239 | CONFIG_NR_CPUS=64 | ||
240 | # The following is needed when setting NR_CPUS to something | ||
241 | # greater than 8 on x86 architectures, it should be automatically | ||
242 | # disregarded by Kconfig when using a different arch | ||
243 | CONFIG_X86_BIGSMP=y | ||
244 | |||
245 | You can find general information on configuration | ||
246 | fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section. | ||
247 | |||
248 | Within the ``smp.scc`` file, the | ||
249 | :term:`KFEATURE_DESCRIPTION` | ||
250 | statement provides a short description of the fragment. Higher level | ||
251 | kernel tools use this description. | ||
252 | |||
253 | Also within the ``smp.scc`` file, the ``kconf`` command includes the | ||
254 | actual configuration fragment in an ``.scc`` file, and the "hardware" | ||
255 | keyword identifies the fragment as being hardware enabling, as opposed | ||
256 | to general policy, which would use the "non-hardware" keyword. The | ||
257 | distinction is made for the benefit of the configuration validation | ||
258 | tools, which warn you if a hardware fragment overrides a policy set by a | ||
259 | non-hardware fragment. | ||
260 | |||
261 | .. note:: | ||
262 | |||
263 | The description file can include multiple ``kconf`` statements, one per | ||
264 | fragment. | ||
265 | |||
266 | As described in the | ||
267 | ":ref:`kernel-dev/common:validating configuration`" section, you can | ||
268 | use the following BitBake command to audit your configuration: | ||
269 | :: | ||
270 | |||
271 | $ bitbake linux-yocto -c kernel_configcheck -f | ||
272 | |||
273 | Patches | ||
274 | ------- | ||
275 | |||
276 | Patch descriptions are very similar to configuration fragment | ||
277 | descriptions, which are described in the previous section. However, | ||
278 | instead of a ``.cfg`` file, these descriptions work with source patches | ||
279 | (i.e. ``.patch`` files). | ||
280 | |||
281 | A typical patch includes a description file and the patch itself. As an | ||
282 | example, consider the build patches used with the ``linux-yocto-4.12`` | ||
283 | kernel as defined outside of the recipe space (i.e. | ||
284 | ``yocto-kernel-cache``). This Metadata consists of several files: | ||
285 | ``build.scc`` and a set of ``*.patch`` files. You can find these files | ||
286 | in the ``patches/build`` directory of the ``yocto-4.12`` branch in the | ||
287 | ``yocto-kernel-cache`` Git repository. | ||
288 | |||
289 | The following listings show the ``build.scc`` file and part of the | ||
290 | ``modpost-mask-trivial-warnings.patch`` file: | ||
291 | :: | ||
292 | |||
293 | patches/build/build.scc: | ||
294 | patch arm-serialize-build-targets.patch | ||
295 | patch powerpc-serialize-image-targets.patch | ||
296 | patch kbuild-exclude-meta-directory-from-distclean-processi.patch | ||
297 | |||
298 | # applied by kgit | ||
299 | # patch kbuild-add-meta-files-to-the-ignore-li.patch | ||
300 | |||
301 | patch modpost-mask-trivial-warnings.patch | ||
302 | patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch | ||
303 | |||
304 | patches/build/modpost-mask-trivial-warnings.patch: | ||
305 | From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001 | ||
306 | From: Paul Gortmaker <paul.gortmaker@windriver.com> | ||
307 | Date: Sun, 25 Jan 2009 17:58:09 -0500 | ||
308 | Subject: [PATCH] modpost: mask trivial warnings | ||
309 | |||
310 | Newer HOSTCC will complain about various stdio fcns because | ||
311 | . | ||
312 | . | ||
313 | . | ||
314 | char *dump_write = NULL, *files_source = NULL; | ||
315 | int opt; | ||
316 | -- | ||
317 | 2.10.1 | ||
318 | |||
319 | generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT) | ||
320 | |||
321 | The description file can | ||
322 | include multiple patch statements where each statement handles a single | ||
323 | patch. In the example ``build.scc`` file, five patch statements exist | ||
324 | for the five patches in the directory. | ||
325 | |||
326 | You can create a typical ``.patch`` file using ``diff -Nurp`` or | ||
327 | ``git format-patch`` commands. For information on how to create patches, | ||
328 | see the ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | ||
329 | and ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" | ||
330 | sections. | ||
331 | |||
332 | Features | ||
333 | -------- | ||
334 | |||
335 | Features are complex kernel Metadata types that consist of configuration | ||
336 | fragments, patches, and possibly other feature description files. As an | ||
337 | example, consider the following generic listing: | ||
338 | :: | ||
339 | |||
340 | features/myfeature.scc | ||
341 | define KFEATURE_DESCRIPTION "Enable myfeature" | ||
342 | |||
343 | patch 0001-myfeature-core.patch | ||
344 | patch 0002-myfeature-interface.patch | ||
345 | |||
346 | include cfg/myfeature_dependency.scc | ||
347 | kconf non-hardware myfeature.cfg | ||
348 | |||
349 | This example shows how the ``patch`` and ``kconf`` commands are used as well | ||
350 | as how an additional feature description file is included with the | ||
351 | ``include`` command. | ||
352 | |||
353 | Typically, features are less granular than configuration fragments and | ||
354 | are more likely than configuration fragments and patches to be the types | ||
355 | of things you want to specify in the ``KERNEL_FEATURES`` variable of the | ||
356 | Linux kernel recipe. See the "`Using Kernel Metadata in a | ||
357 | Recipe <#using-kernel-metadata-in-a-recipe>`__" section earlier in the | ||
358 | manual. | ||
359 | |||
360 | Kernel Types | ||
361 | ------------ | ||
362 | |||
363 | A kernel type defines a high-level kernel policy by aggregating | ||
364 | non-hardware configuration fragments with patches you want to use when | ||
365 | building a Linux kernel of a specific type (e.g. a real-time kernel). | ||
366 | Syntactically, kernel types are no different than features as described | ||
367 | in the "`Features <#features>`__" section. The | ||
368 | :term:`LINUX_KERNEL_TYPE` | ||
369 | variable in the kernel recipe selects the kernel type. For example, in | ||
370 | the ``linux-yocto_4.12.bb`` kernel recipe found in | ||
371 | ``poky/meta/recipes-kernel/linux``, a | ||
372 | :ref:`require <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directive | ||
373 | includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file, | ||
374 | which has the following statement that defines the default kernel type: | ||
375 | :: | ||
376 | |||
377 | LINUX_KERNEL_TYPE ??= "standard" | ||
378 | |||
379 | Another example would be the real-time kernel (i.e. | ||
380 | ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel | ||
381 | type as follows: | ||
382 | :: | ||
383 | |||
384 | LINUX_KERNEL_TYPE = "preempt-rt" | ||
385 | |||
386 | .. note:: | ||
387 | |||
388 | You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory | ||
389 | of the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` | ||
390 | (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the | ||
391 | ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" | ||
392 | section for more information. | ||
393 | |||
394 | Three kernel types ("standard", "tiny", and "preempt-rt") are supported | ||
395 | for Linux Yocto kernels: | ||
396 | |||
397 | - "standard": Includes the generic Linux kernel policy of the Yocto | ||
398 | Project linux-yocto kernel recipes. This policy includes, among other | ||
399 | things, which file systems, networking options, core kernel features, | ||
400 | and debugging and tracing options are supported. | ||
401 | |||
402 | - "preempt-rt": Applies the ``PREEMPT_RT`` patches and the | ||
403 | configuration options required to build a real-time Linux kernel. | ||
404 | This kernel type inherits from the "standard" kernel type. | ||
405 | |||
406 | - "tiny": Defines a bare minimum configuration meant to serve as a base | ||
407 | for very small Linux kernels. The "tiny" kernel type is independent | ||
408 | from the "standard" configuration. Although the "tiny" kernel type | ||
409 | does not currently include any source changes, it might in the | ||
410 | future. | ||
411 | |||
412 | For any given kernel type, the Metadata is defined by the ``.scc`` (e.g. | ||
413 | ``standard.scc``). Here is a partial listing for the ``standard.scc`` | ||
414 | file, which is found in the ``ktypes/standard`` directory of the | ||
415 | ``yocto-kernel-cache`` Git repository: | ||
416 | :: | ||
417 | |||
418 | # Include this kernel type fragment to get the standard features and | ||
419 | # configuration values. | ||
420 | |||
421 | # Note: if only the features are desired, but not the configuration | ||
422 | # then this should be included as: | ||
423 | # include ktypes/standard/standard.scc nocfg | ||
424 | # if no chained configuration is desired, include it as: | ||
425 | # include ktypes/standard/standard.scc nocfg inherit | ||
426 | |||
427 | |||
428 | |||
429 | include ktypes/base/base.scc | ||
430 | branch standard | ||
431 | |||
432 | kconf non-hardware standard.cfg | ||
433 | |||
434 | include features/kgdb/kgdb.scc | ||
435 | . | ||
436 | . | ||
437 | . | ||
438 | |||
439 | include cfg/net/ip6_nf.scc | ||
440 | include cfg/net/bridge.scc | ||
441 | |||
442 | include cfg/systemd.scc | ||
443 | |||
444 | include features/rfkill/rfkill.scc | ||
445 | |||
446 | As with any ``.scc`` file, a kernel type definition can aggregate other | ||
447 | ``.scc`` files with ``include`` commands. These definitions can also | ||
448 | directly pull in configuration fragments and patches with the ``kconf`` | ||
449 | and ``patch`` commands, respectively. | ||
450 | |||
451 | .. note:: | ||
452 | |||
453 | It is not strictly necessary to create a kernel type ``.scc`` | ||
454 | file. The Board Support Package (BSP) file can implicitly define the | ||
455 | kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the | ||
456 | ":ref:`kernel-dev/advanced:bsp descriptions`" section for more | ||
457 | information. | ||
458 | |||
459 | BSP Descriptions | ||
460 | ---------------- | ||
461 | |||
462 | BSP descriptions (i.e. ``*.scc`` files) combine kernel types with | ||
463 | hardware-specific features. The hardware-specific Metadata is typically | ||
464 | defined independently in the BSP layer, and then aggregated with each | ||
465 | supported kernel type. | ||
466 | |||
467 | .. note:: | ||
468 | |||
469 | For BSPs supported by the Yocto Project, the BSP description files | ||
470 | are located in the ``bsp`` directory of the ``yocto-kernel-cache`` | ||
471 | repository organized under the "Yocto Linux Kernel" heading in the | ||
472 | :yocto_git:`Yocto Project Source Repositories <>`. | ||
473 | |||
474 | This section overviews the BSP description structure, the aggregation | ||
475 | concepts, and presents a detailed example using a BSP supported by the | ||
476 | Yocto Project (i.e. BeagleBone Board). For complete information on BSP | ||
477 | layer file hierarchy, see the :doc:`/bsp-guide/index`. | ||
478 | |||
479 | Description Overview | ||
480 | ~~~~~~~~~~~~~~~~~~~~ | ||
481 | |||
482 | For simplicity, consider the following root BSP layer description files | ||
483 | for the BeagleBone board. These files employ both a structure and naming | ||
484 | convention for consistency. The naming convention for the file is as | ||
485 | follows: | ||
486 | :: | ||
487 | |||
488 | bsp_root_name-kernel_type.scc | ||
489 | |||
490 | Here are some example root layer | ||
491 | BSP filenames for the BeagleBone Board BSP, which is supported by the | ||
492 | Yocto Project: | ||
493 | :: | ||
494 | |||
495 | beaglebone-standard.scc | ||
496 | beaglebone-preempt-rt.scc | ||
497 | |||
498 | Each file uses the root name (i.e "beaglebone") BSP name followed by the | ||
499 | kernel type. | ||
500 | |||
501 | Examine the ``beaglebone-standard.scc`` file: | ||
502 | :: | ||
503 | |||
504 | define KMACHINE beaglebone | ||
505 | define KTYPE standard | ||
506 | define KARCH arm | ||
507 | |||
508 | include ktypes/standard/standard.scc | ||
509 | branch beaglebone | ||
510 | |||
511 | include beaglebone.scc | ||
512 | |||
513 | # default policy for standard kernels | ||
514 | include features/latencytop/latencytop.scc | ||
515 | include features/profiling/profiling.scc | ||
516 | |||
517 | Every top-level BSP description file | ||
518 | should define the :term:`KMACHINE`, | ||
519 | :term:`KTYPE`, and | ||
520 | :term:`KARCH` variables. These | ||
521 | variables allow the OpenEmbedded build system to identify the | ||
522 | description as meeting the criteria set by the recipe being built. This | ||
523 | example supports the "beaglebone" machine for the "standard" kernel and | ||
524 | the "arm" architecture. | ||
525 | |||
526 | Be aware that a hard link between the ``KTYPE`` variable and a kernel | ||
527 | type description file does not exist. Thus, if you do not have the | ||
528 | kernel type defined in your kernel Metadata as it is here, you only need | ||
529 | to ensure that the | ||
530 | :term:`LINUX_KERNEL_TYPE` | ||
531 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP | ||
532 | description file match. | ||
533 | |||
534 | To separate your kernel policy from your hardware configuration, you | ||
535 | include a kernel type (``ktype``), such as "standard". In the previous | ||
536 | example, this is done using the following: | ||
537 | :: | ||
538 | |||
539 | include ktypes/standard/standard.scc | ||
540 | |||
541 | This file aggregates all the configuration | ||
542 | fragments, patches, and features that make up your standard kernel | ||
543 | policy. See the "`Kernel Types <#kernel-types>`__" section for more | ||
544 | information. | ||
545 | |||
546 | To aggregate common configurations and features specific to the kernel | ||
547 | for `mybsp`, use the following: | ||
548 | :: | ||
549 | |||
550 | include mybsp.scc | ||
551 | |||
552 | You can see that in the BeagleBone example with the following: | ||
553 | :: | ||
554 | |||
555 | include beaglebone.scc | ||
556 | |||
557 | For information on how to break a complete ``.config`` file into the various | ||
558 | configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section. | ||
559 | |||
560 | Finally, if you have any configurations specific to the hardware that | ||
561 | are not in a ``*.scc`` file, you can include them as follows: | ||
562 | :: | ||
563 | |||
564 | kconf hardware mybsp-extra.cfg | ||
565 | |||
566 | The BeagleBone example does not include these | ||
567 | types of configurations. However, the Malta 32-bit board does | ||
568 | ("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file: | ||
569 | :: | ||
570 | |||
571 | define KMACHINE mti-malta32-le | ||
572 | define KMACHINE qemumipsel | ||
573 | define KTYPE standard | ||
574 | define KARCH mips | ||
575 | |||
576 | include ktypes/standard/standard.scc | ||
577 | branch mti-malta32 | ||
578 | |||
579 | include mti-malta32.scc | ||
580 | kconf hardware mti-malta32-le.cfg | ||
581 | |||
582 | Example | ||
583 | ~~~~~~~ | ||
584 | |||
585 | Many real-world examples are more complex. Like any other ``.scc`` file, | ||
586 | BSP descriptions can aggregate features. Consider the Minnow BSP | ||
587 | definition given the ``linux-yocto-4.4`` branch of the | ||
588 | ``yocto-kernel-cache`` (i.e. | ||
589 | ``yocto-kernel-cache/bsp/minnow/minnow.scc``): | ||
590 | |||
591 | .. note:: | ||
592 | |||
593 | Although the Minnow Board BSP is unused, the Metadata remains and is | ||
594 | being used here just as an example. | ||
595 | |||
596 | :: | ||
597 | |||
598 | include cfg/x86.scc | ||
599 | include features/eg20t/eg20t.scc | ||
600 | include cfg/dmaengine.scc | ||
601 | include features/power/intel.scc | ||
602 | include cfg/efi.scc | ||
603 | include features/usb/ehci-hcd.scc | ||
604 | include features/usb/ohci-hcd.scc | ||
605 | include features/usb/usb-gadgets.scc | ||
606 | include features/usb/touchscreen-composite.scc | ||
607 | include cfg/timer/hpet.scc | ||
608 | include features/leds/leds.scc | ||
609 | include features/spi/spidev.scc | ||
610 | include features/i2c/i2cdev.scc | ||
611 | include features/mei/mei-txe.scc | ||
612 | |||
613 | # Earlyprintk and port debug requires 8250 | ||
614 | kconf hardware cfg/8250.cfg | ||
615 | |||
616 | kconf hardware minnow.cfg | ||
617 | kconf hardware minnow-dev.cfg | ||
618 | |||
619 | The ``minnow.scc`` description file includes a hardware configuration | ||
620 | fragment (``minnow.cfg``) specific to the Minnow BSP as well as several | ||
621 | more general configuration fragments and features enabling hardware | ||
622 | found on the machine. This ``minnow.scc`` description file is then | ||
623 | included in each of the three "minnow" description files for the | ||
624 | supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). | ||
625 | Consider the "minnow" description for the "standard" kernel type (i.e. | ||
626 | ``minnow-standard.scc``): | ||
627 | :: | ||
628 | |||
629 | define KMACHINE minnow | ||
630 | define KTYPE standard | ||
631 | define KARCH i386 | ||
632 | |||
633 | include ktypes/standard | ||
634 | |||
635 | include minnow.scc | ||
636 | |||
637 | # Extra minnow configs above the minimal defined in minnow.scc | ||
638 | include cfg/efi-ext.scc | ||
639 | include features/media/media-all.scc | ||
640 | include features/sound/snd_hda_intel.scc | ||
641 | |||
642 | # The following should really be in standard.scc | ||
643 | # USB live-image support | ||
644 | include cfg/usb-mass-storage.scc | ||
645 | include cfg/boot-live.scc | ||
646 | |||
647 | # Basic profiling | ||
648 | include features/latencytop/latencytop.scc | ||
649 | include features/profiling/profiling.scc | ||
650 | |||
651 | # Requested drivers that don't have an existing scc | ||
652 | kconf hardware minnow-drivers-extra.cfg | ||
653 | |||
654 | The ``include`` command midway through the file includes the ``minnow.scc`` description | ||
655 | that defines all enabled hardware for the BSP that is common to all | ||
656 | kernel types. Using this command significantly reduces duplication. | ||
657 | |||
658 | Now consider the "minnow" description for the "tiny" kernel type (i.e. | ||
659 | ``minnow-tiny.scc``): | ||
660 | :: | ||
661 | |||
662 | define KMACHINE minnow | ||
663 | define KTYPE tiny | ||
664 | define KARCH i386 | ||
665 | |||
666 | include ktypes/tiny | ||
667 | |||
668 | include minnow.scc | ||
669 | |||
670 | As you might expect, | ||
671 | the "tiny" description includes quite a bit less. In fact, it includes | ||
672 | only the minimal policy defined by the "tiny" kernel type and the | ||
673 | hardware-specific configuration required for booting the machine along | ||
674 | with the most basic functionality of the system as defined in the base | ||
675 | "minnow" description file. | ||
676 | |||
677 | Notice again the three critical variables: | ||
678 | :term:`KMACHINE`, | ||
679 | :term:`KTYPE`, and | ||
680 | :term:`KARCH`. Of these variables, only | ||
681 | ``KTYPE`` has changed to specify the "tiny" kernel type. | ||
682 | |||
683 | Kernel Metadata Location | ||
684 | ======================== | ||
685 | |||
686 | Kernel Metadata always exists outside of the kernel tree either defined | ||
687 | in a kernel recipe (recipe-space) or outside of the recipe. Where you | ||
688 | choose to define the Metadata depends on what you want to do and how you | ||
689 | intend to work. Regardless of where you define the kernel Metadata, the | ||
690 | syntax used applies equally. | ||
691 | |||
692 | If you are unfamiliar with the Linux kernel and only wish to apply a | ||
693 | configuration and possibly a couple of patches provided to you by | ||
694 | others, the recipe-space method is recommended. This method is also a | ||
695 | good approach if you are working with Linux kernel sources you do not | ||
696 | control or if you just do not want to maintain a Linux kernel Git | ||
697 | repository on your own. For partial information on how you can define | ||
698 | kernel Metadata in the recipe-space, see the | ||
699 | ":ref:`kernel-dev/common:modifying an existing recipe`" section. | ||
700 | |||
701 | Conversely, if you are actively developing a kernel and are already | ||
702 | maintaining a Linux kernel Git repository of your own, you might find it | ||
703 | more convenient to work with kernel Metadata kept outside the | ||
704 | recipe-space. Working with Metadata in this area can make iterative | ||
705 | development of the Linux kernel more efficient outside of the BitBake | ||
706 | environment. | ||
707 | |||
708 | Recipe-Space Metadata | ||
709 | --------------------- | ||
710 | |||
711 | When stored in recipe-space, the kernel Metadata files reside in a | ||
712 | directory hierarchy below | ||
713 | :term:`FILESEXTRAPATHS`. For | ||
714 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and | ||
715 | modifying | ||
716 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to | ||
717 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to | ||
718 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. | ||
719 | See the ":ref:`kernel-dev/common:modifying an existing recipe`" | ||
720 | section for more information. | ||
721 | |||
722 | Here is an example that shows a trivial tree of kernel Metadata stored | ||
723 | in recipe-space within a BSP layer: | ||
724 | :: | ||
725 | |||
726 | meta-my_bsp_layer/ | ||
727 | `-- recipes-kernel | ||
728 | `-- linux | ||
729 | `-- linux-yocto | ||
730 | |-- bsp-standard.scc | ||
731 | |-- bsp.cfg | ||
732 | `-- standard.cfg | ||
733 | |||
734 | When the Metadata is stored in recipe-space, you must take steps to | ||
735 | ensure BitBake has the necessary information to decide what files to | ||
736 | fetch and when they need to be fetched again. It is only necessary to | ||
737 | specify the ``.scc`` files on the | ||
738 | :term:`SRC_URI`. BitBake parses them | ||
739 | and fetches any files referenced in the ``.scc`` files by the | ||
740 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is | ||
741 | necessary to bump the recipe :term:`PR` | ||
742 | value when changing the content of files not explicitly listed in the | ||
743 | ``SRC_URI``. | ||
744 | |||
745 | If the BSP description is in recipe space, you cannot simply list the | ||
746 | ``*.scc`` in the ``SRC_URI`` statement. You need to use the following | ||
747 | form from your kernel append file: | ||
748 | :: | ||
749 | |||
750 | SRC_URI_append_myplatform = " \ | ||
751 | file://myplatform;type=kmeta;destsuffix=myplatform \ | ||
752 | " | ||
753 | |||
754 | Metadata Outside the Recipe-Space | ||
755 | --------------------------------- | ||
756 | |||
757 | When stored outside of the recipe-space, the kernel Metadata files | ||
758 | reside in a separate repository. The OpenEmbedded build system adds the | ||
759 | Metadata to the build as a "type=kmeta" repository through the | ||
760 | :term:`SRC_URI` variable. As an | ||
761 | example, consider the following ``SRC_URI`` statement from the | ||
762 | ``linux-yocto_4.12.bb`` kernel recipe: | ||
763 | :: | ||
764 | |||
765 | SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ | ||
766 | git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" | ||
767 | |||
768 | |||
769 | ``${KMETA}``, in this context, is simply used to name the directory into | ||
770 | which the Git fetcher places the Metadata. This behavior is no different | ||
771 | than any multi-repository ``SRC_URI`` statement used in a recipe (e.g. | ||
772 | see the previous section). | ||
773 | |||
774 | You can keep kernel Metadata in a "kernel-cache", which is a directory | ||
775 | containing configuration fragments. As with any Metadata kept outside | ||
776 | the recipe-space, you simply need to use the ``SRC_URI`` statement with | ||
777 | the "type=kmeta" attribute. Doing so makes the kernel Metadata available | ||
778 | during the configuration phase. | ||
779 | |||
780 | If you modify the Metadata, you must not forget to update the ``SRCREV`` | ||
781 | statements in the kernel's recipe. In particular, you need to update the | ||
782 | ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you | ||
783 | wish to use. Changing the data in these branches and not updating the | ||
784 | ``SRCREV`` statements to match will cause the build to fetch an older | ||
785 | commit. | ||
786 | |||
787 | Organizing Your Source | ||
788 | ====================== | ||
789 | |||
790 | Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux | ||
791 | kernel sources that have only a single branch - "master". This type of | ||
792 | repository structure is fine for linear development supporting a single | ||
793 | machine and architecture. However, if you work with multiple boards and | ||
794 | architectures, a kernel source repository with multiple branches is more | ||
795 | efficient. For example, suppose you need a series of patches for one | ||
796 | board to boot. Sometimes, these patches are works-in-progress or | ||
797 | fundamentally wrong, yet they are still necessary for specific boards. | ||
798 | In these situations, you most likely do not want to include these | ||
799 | patches in every kernel you build (i.e. have the patches as part of the | ||
800 | lone "master" branch). It is situations like these that give rise to | ||
801 | multiple branches used within a Linux kernel sources Git repository. | ||
802 | |||
803 | Repository organization strategies exist that maximize source reuse, | ||
804 | remove redundancy, and logically order your changes. This section | ||
805 | presents strategies for the following cases: | ||
806 | |||
807 | - Encapsulating patches in a feature description and only including the | ||
808 | patches in the BSP descriptions of the applicable boards. | ||
809 | |||
810 | - Creating a machine branch in your kernel source repository and | ||
811 | applying the patches on that branch only. | ||
812 | |||
813 | - Creating a feature branch in your kernel source repository and | ||
814 | merging that branch into your BSP when needed. | ||
815 | |||
816 | The approach you take is entirely up to you and depends on what works | ||
817 | best for your development model. | ||
818 | |||
819 | Encapsulating Patches | ||
820 | --------------------- | ||
821 | |||
822 | If you are reusing patches from an external tree and are not working on | ||
823 | the patches, you might find the encapsulated feature to be appropriate. | ||
824 | Given this scenario, you do not need to create any branches in the | ||
825 | source repository. Rather, you just take the static patches you need and | ||
826 | encapsulate them within a feature description. Once you have the feature | ||
827 | description, you simply include that into the BSP description as | ||
828 | described in the "`BSP Descriptions <#bsp-descriptions>`__" section. | ||
829 | |||
830 | You can find information on how to create patches and BSP descriptions | ||
831 | in the "`Patches <#patches>`__" and "`BSP | ||
832 | Descriptions <#bsp-descriptions>`__" sections. | ||
833 | |||
834 | Machine Branches | ||
835 | ---------------- | ||
836 | |||
837 | When you have multiple machines and architectures to support, or you are | ||
838 | actively working on board support, it is more efficient to create | ||
839 | branches in the repository based on individual machines. Having machine | ||
840 | branches allows common source to remain in the "master" branch with any | ||
841 | features specific to a machine stored in the appropriate machine branch. | ||
842 | This organization method frees you from continually reintegrating your | ||
843 | patches into a feature. | ||
844 | |||
845 | Once you have a new branch, you can set up your kernel Metadata to use | ||
846 | the branch a couple different ways. In the recipe, you can specify the | ||
847 | new branch as the ``KBRANCH`` to use for the board as follows: | ||
848 | :: | ||
849 | |||
850 | KBRANCH = "mynewbranch" | ||
851 | |||
852 | Another method is to use the ``branch`` command in the BSP | ||
853 | description: | ||
854 | :: | ||
855 | |||
856 | mybsp.scc: | ||
857 | define KMACHINE mybsp | ||
858 | define KTYPE standard | ||
859 | define KARCH i386 | ||
860 | include standard.scc | ||
861 | |||
862 | branch mynewbranch | ||
863 | |||
864 | include mybsp-hw.scc | ||
865 | |||
866 | If you find yourself with numerous branches, you might consider using a | ||
867 | hierarchical branching system similar to what the Yocto Linux Kernel Git | ||
868 | repositories use: | ||
869 | :: | ||
870 | |||
871 | common/kernel_type/machine | ||
872 | |||
873 | If you had two kernel types, "standard" and "small" for instance, three | ||
874 | machines, and common as ``mydir``, the branches in your Git repository | ||
875 | might look like this: | ||
876 | :: | ||
877 | |||
878 | mydir/base | ||
879 | mydir/standard/base | ||
880 | mydir/standard/machine_a | ||
881 | mydir/standard/machine_b | ||
882 | mydir/standard/machine_c | ||
883 | mydir/small/base | ||
884 | mydir/small/machine_a | ||
885 | |||
886 | This organization can help clarify the branch relationships. In this | ||
887 | case, ``mydir/standard/machine_a`` includes everything in ``mydir/base`` | ||
888 | and ``mydir/standard/base``. The "standard" and "small" branches add | ||
889 | sources specific to those kernel types that for whatever reason are not | ||
890 | appropriate for the other branches. | ||
891 | |||
892 | .. note:: | ||
893 | |||
894 | The "base" branches are an artifact of the way Git manages its data | ||
895 | internally on the filesystem: Git will not allow you to use | ||
896 | ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to | ||
897 | create a file and a directory named "standard". | ||
898 | |||
899 | Feature Branches | ||
900 | ---------------- | ||
901 | |||
902 | When you are actively developing new features, it can be more efficient | ||
903 | to work with that feature as a branch, rather than as a set of patches | ||
904 | that have to be regularly updated. The Yocto Project Linux kernel tools | ||
905 | provide for this with the ``git merge`` command. | ||
906 | |||
907 | To merge a feature branch into a BSP, insert the ``git merge`` command | ||
908 | after any ``branch`` commands: | ||
909 | :: | ||
910 | |||
911 | mybsp.scc: | ||
912 | define KMACHINE mybsp | ||
913 | define KTYPE standard | ||
914 | define KARCH i386 | ||
915 | include standard.scc | ||
916 | |||
917 | branch mynewbranch | ||
918 | git merge myfeature | ||
919 | |||
920 | include mybsp-hw.scc | ||
921 | |||
922 | SCC Description File Reference | ||
923 | ============================== | ||
924 | |||
925 | This section provides a brief reference for the commands you can use | ||
926 | within an SCC description file (``.scc``): | ||
927 | |||
928 | - ``branch [ref]``: Creates a new branch relative to the current branch | ||
929 | (typically ``${KTYPE}``) using the currently checked-out branch, or | ||
930 | "ref" if specified. | ||
931 | |||
932 | - ``define``: Defines variables, such as | ||
933 | :term:`KMACHINE`, | ||
934 | :term:`KTYPE`, | ||
935 | :term:`KARCH`, and | ||
936 | :term:`KFEATURE_DESCRIPTION`. | ||
937 | |||
938 | - ``include SCC_FILE``: Includes an SCC file in the current file. The | ||
939 | file is parsed as if you had inserted it inline. | ||
940 | |||
941 | - ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration | ||
942 | fragment for merging into the final Linux ``.config`` file. | ||
943 | |||
944 | - ``git merge GIT_BRANCH``: Merges the feature branch into the current | ||
945 | branch. | ||
946 | |||
947 | - ``patch PATCH_FILE``: Applies the patch to the current Git branch. | ||
948 | |||
949 | |||