summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml170
1 files changed, 169 insertions, 1 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index f14ed69586..768b66450b 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -368,7 +368,7 @@ described in the following sections applies equally.
368 <filename>.scc</filename> files by the <filename>include</filename>, 368 <filename>.scc</filename> files by the <filename>include</filename>,
369 <filename>patch</filename>, or <filename>kconf</filename> commands. 369 <filename>patch</filename>, or <filename>kconf</filename> commands.
370 Because of this, it is necessary to bump the recipe 370 Because of this, it is necessary to bump the recipe
371 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> 371 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
372 value when changing the content of files not explicitly listed 372 value when changing the content of files not explicitly listed
373 in the SRC_URI. 373 in the SRC_URI.
374 </para> 374 </para>
@@ -501,6 +501,174 @@ git repository:
501 </section> 501 </section>
502</section> 502</section>
503 503
504<section id='metadata-syntax'>
505 <title>Metadata Syntax</title>
506
507 <para>
508 The Yocto Project Linux kernel tools metadata consists of three
509 primary types of files: <filename>scc</filename>
510 <footnote>
511 <para>
512 <filename>scc</filename> stands for Series Configuration
513 Control, but the naming has less significance in the
514 current implementation of the tooling than it had in the
515 past.
516 Consider it to be a description file.
517 </para>
518 </footnote>
519 description files, configuration fragments, and patches.
520 The <filename>scc</filename> files define variables and include or
521 otherwise reference any of the three file types.
522 The description files are used to aggregate all types of metadata into
523 what ultimately describes the sources and the configuration required
524 to build a Linux kernel tailored to a specific machine.
525 </para>
526
527 <para>
528 The <filename>scc</filename> description files are used to define two
529 fundamental types of metadata:
530 <itemizedlist>
531 <listitem><para>Features</para></listitem>
532 <listitem><para>Board Support Packages (BSPs)</para></listitem>
533 </itemizedlist>
534 </para>
535
536 <para>
537 Features aggregate sources in the form of patches and configuration
538 in the form of configuration fragments into a modular reusable unit.
539 Features are used to implement conceptually separate metadata
540 descriptions like pure configuration fragments, simple patches,
541 complex features, and kernel types (ktypes).
542 Kernel types define general kernel features and policy to be reused
543 in the BSPs.
544 </para>
545
546 <para>
547 BSPs define hardware-specific features and aggregate them with kernel
548 types to form the final description of what will be assembled and built.
549 </para>
550
551 <para>
552 While the metadata syntax does not enforce any logical separation of
553 configuration fragments, patches, features or kernel types, best
554 practices dictate a logical separation of these types of meta-data.
555 The following metadata file hierarchy is recommended:
556 <literallayout class='monospaced'>
557 &lt;base&gt;/
558 bsp/
559 cfg/
560 features/
561 ktypes/
562 patches/
563 </literallayout>
564 </para>
565
566 <para>
567 The <filename>bsp</filename> directory should contain the
568 BSP descriptions, described in detail in section 3.3.5.
569 The remaining directories all contain "features"; the separation
570 is meant to aid in conceptualizing their intended usage.
571 A simple guide to determine where your <filename>scc</filename>
572 description file should go is as follows.
573 If it contains only configuration fragments, it belongs in
574 <filename>cfg</filename>.
575 If it contains only source-code fixes, it belongs in
576 <filename>patches</filename>.
577 If it encapsulates a major feature, often combining sources and
578 configurations, it belongs in <filename>features</filename>.
579 If it aggregates non-hardware configuration and patches
580 in order to define a base kernel policy or major kernel type to
581 be reused across multiple BSPs, it belongs in
582 <filename>ktypes</filename>.
583 </para>
584
585 <para>
586 The lines between these can easily become blurred, especially as
587 out-of-tree features are slowly merged upstream over time.
588 Also remember that this is purely logical organization and has
589 no impact on the functionality of the metadata as
590 all of <filename>cfg</filename>, <filename>features</filename>,
591 <filename>patches</filename>, and <filename>ktypes</filename>,
592 contain "features" as far as the Yocto Project Linux kernel
593 tools are concerned.
594 </para>
595
596 <para>
597 Paths used in metadata files are relative to
598 <filename>&lt;base&gt;</filename>, which is either
599 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
600 if you are creating metadata in recipe-space as described in
601 section "<link linkend='recipe-space-metadata'>Recipe-Space Metadata</link>",
602 or <filename>meta/cfg/kernel-cache/</filename> if you are creating
603 metadata in-tree as described in
604 the "<link linkend='in-tree-metadata'>In-Tree Metadata</link>" section.
605 </para>
606
607 <para>
608 Original text:
609 <literallayout class='monospaced'>
610The Yocto Project Linux kernel tools meta-data consists of three primary types
611of files: scc* description files, configuration fragments, and patches. The scc
612files define variables and include or otherwise reference any of the three file
613types. The description files are used to aggregate all types of meta-data into
614what ultimately describes the sources and the configuration required to build a
615Linux kernel tailored to a specific machine.
616
617The scc description files are used to define two fundamental types of meta-data:
618 o Features
619 o BSPs
620
621Features aggregate sources in the form of patches and configuration in the form
622of configuration fragments into a modular reusable unit. Features are used to
623implement conceptually separate meta-data descriptions like pure configuration
624fragments, simple patches, complex features, and kernel types (ktypes). Kernel
625types define general kernel features and policy to be reused in the BSPs.
626
627BSPs define hardware-specific features and aggregate them with kernel types to
628form the final description of what will be assembled and built.
629
630While the meta-data syntax does not enforce any logical separation of
631configuration fragments, patches, features or kernel types, best practices
632dictate a logical separation of these types of meta-data. The following
633meta-data file hierarchy is recommended:
634
635 &lt;base&gt;/
636 bsp/
637 cfg/
638 features/
639 ktypes/
640 patches/
641
642The bsp directory should contain the BSP descriptions, described in detail in
6433.3.5. The remaining directories all contain "features"; the separation is meant
644to aid in conceptualizing their intended usage. A simple guide to determine
645where your scc description file should go is as follows. If it contains only
646configuration fragments, it belongs in cfg. If it contains only source-code
647fixes, it belongs in patches. If it encapsulates a major feature, often
648combining sources and configurations, it belongs in features. If it aggregates
649non-hardware configuration and patches in order to define a base kernel policy
650or major kernel type to be reused across multiple BSPs, it belongs in ktypes.
651The line between these can easily become blurred, especially as out-of-tree
652features are slowly merged upstream over time. Also remember that this is purely
653logical organization and has no impact on the functionality of the meta-data as
654all of cfg, features, patches, and ktypes, contain "features" as far as the
655Yocto Project Linux kernel tools are concerned.
656
657Paths used in meta-data files are relative to &lt;base&gt; which is either
658FILESEXTRAPATHS if you are creating meta-data in recipe-space (see 3.2.1), or
659meta/cfg/kernel-cache/ if you are creating meta-data in-tree (see 3.2.2).
660
661* scc stands for Series Configuration Control, but the naming has less
662 significance in the current implementation of the tooling than it had in the
663 past. Consider it to be a description file.
664 </literallayout>
665 </para>
666
667
668
669
670</section>
671
504</chapter> 672</chapter>
505<!-- 673<!--
506vim: expandtab tw=80 ts=4 674vim: expandtab tw=80 ts=4