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