summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-advanced.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml1257
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 &lt;paul.gortmaker@windriver.com&gt;
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<!--
1256vim: expandtab tw=80 ts=4
1257-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-15 08:12:27 +0000