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