summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-advanced.xml
diff options
context:
space:
mode:
authorscott-lenovo <scott-lenovo@ubuntu.(none)>2013-01-08 07:51:34 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-16 15:59:16 +0000
commitd176d86a4c4f3eea54bc8da8c61338e2ef39d68c (patch)
tree06d7567b04b52071472dc9e9e93d0aaab066e0a1 /documentation/kernel-dev/kernel-dev-advanced.xml
parent545f79bfdd85c98c4a5901334e77534b49ccc631 (diff)
downloadpoky-d176d86a4c4f3eea54bc8da8c61338e2ef39d68c.tar.gz
kernel-dev: edits to the "Kernel Metadata Syntax" section.
First real re-write of this section. (From yocto-docs rev: 41c79da0832c0b290b21cc2aff87091d7243fafa) Signed-off-by: scott-lenovo <scott-lenovo@ubuntu.(none)> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml147
1 files changed, 82 insertions, 65 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index 87819903bb..c069ddfb08 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -188,7 +188,7 @@ to source changes.
188 and "cfg" are subdirectories within the 188 and "cfg" are subdirectories within the
189 <filename>meta/cfg/kernel-cache</filename> directory. 189 <filename>meta/cfg/kernel-cache</filename> directory.
190 For more information, see the 190 For more information, see the
191 "<link linkend='metadata-syntax'>Metadata Syntax</link>" section. 191 "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section.
192 <note> 192 <note>
193 The processing of the these variables has evolved some between the 193 The processing of the these variables has evolved some between the
194 0.9 and 1.3 releases of the Yocto Project and associated 194 0.9 and 1.3 releases of the Yocto Project and associated
@@ -421,24 +421,27 @@ value when changing the content of files not explicitly listed in the SRC_URI.
421 <title>In-Tree Metadata</title> 421 <title>In-Tree Metadata</title>
422 422
423 <para> 423 <para>
424 When stored in-tree, the metadata files reside in the 424 When stored in-tree, the kernel Metadata files reside in the
425 "meta" directory of the Linux kernel sources. 425 <filename>meta</filename> directory of the Linux kernel sources.
426 They may be present in the same branch as the sources, 426 The <filename>meta</filename> directory can be present in the
427 such as "master", or in their own orphan branch, 427 same repository branch as the sources,
428 typically named "meta". 428 such as "master", or <filename>meta</filename> can be its own
429 An orphan branch in Git is a branch with unique history and 429 orphan branch.
430 content to the other branches in the repository. 430 <note>
431 This is useful to track metadata changes independently from the 431 An orphan branch in Git is a branch with unique history and
432 sources of the Linux kernel, while still keeping them 432 content to the other branches in the repository.
433 together in the same repository. 433 Orphan branches are useful to track Metadata changes
434 independently from the sources of the Linux kernel, while
435 still keeping them together in the same repository.
436 </note>
434 For the purposes of this document, we will discuss all 437 For the purposes of this document, we will discuss all
435 in-tree metadata as residing below the 438 in-tree Metadata as residing below the
436 <filename>meta/cfg/kernel-cache</filename> directory. 439 <filename>meta/cfg/kernel-cache</filename> directory.
437 </para> 440 </para>
438 441
439 <para> 442 <para>
440 By way of example, a trivial tree of metadata stored in a custom 443 Following is an example that shows how a trivial tree of Metadata
441 Linux kernel Git repository might look like the following: 444 is stored in a custom Linux kernel Git repository:
442 <literallayout class='monospaced'> 445 <literallayout class='monospaced'>
443 meta/ 446 meta/
444 `-- cfg 447 `-- cfg
@@ -450,20 +453,21 @@ value when changing the content of files not explicitly listed in the SRC_URI.
450 </para> 453 </para>
451 454
452 <para> 455 <para>
453 To use a specific branch for the metadata, specify the branch 456 To use a branch different from where the sources reside,
454 in the <filename>KMETA</filename> variable in your Linux kernel 457 specify the branch in the <filename>KMETA</filename> variable
455 recipe, for example: 458 in your Linux kernel recipe.
459 Here is an example:
456 <literallayout class='monospaced'> 460 <literallayout class='monospaced'>
457 KMETA = "meta" 461 KMETA = "meta"
458 </literallayout> 462 </literallayout>
459 To use the same branch as the sources, set 463 To use the same branch as the sources, set
460 <filename>KMETA</filename> to the empty string: 464 <filename>KMETA</filename> to an empty string:
461 <literallayout class='monospaced'> 465 <literallayout class='monospaced'>
462 KMETA = "" 466 KMETA = ""
463 </literallayout> 467 </literallayout>
464 If you are working with your own sources and want to create an 468 If you are working with your own sources and want to create an
465 orphan <filename>meta</filename> branch, you can do so using the 469 orphan <filename>meta</filename> branch, use these commands
466 following commands from within your Linux kernel Git repository: 470 from within your Linux kernel Git repository:
467 <literallayout class='monospaced'> 471 <literallayout class='monospaced'>
468 $ git checkout --orphan meta 472 $ git checkout --orphan meta
469 $ git rm -rf . 473 $ git rm -rf .
@@ -515,32 +519,33 @@ git repository:
515 </section> 519 </section>
516</section> 520</section>
517 521
518<section id='metadata-syntax'> 522<section id='kernel-metadata-syntax'>
519 <title>Metadata Syntax</title> 523 <title>Kernel Metadata Syntax</title>
520 524
521 <para> 525 <para>
522 The Yocto Project Linux kernel tools metadata consists of three 526 The kernel Metadata consists of three primary types of files:
523 primary types of files: <filename>scc</filename> 527 <filename>scc</filename>
524 <footnote> 528 <footnote>
525 <para> 529 <para>
526 <filename>scc</filename> stands for Series Configuration 530 <filename>scc</filename> stands for Series Configuration
527 Control, but the naming has less significance in the 531 Control, but the naming has less significance in the
528 current implementation of the tooling than it had in the 532 current implementation of the tooling than it had in the
529 past. 533 past.
530 Consider it to be a description file. 534 Consider <filename>scc</filename> files to be description files.
531 </para> 535 </para>
532 </footnote> 536 </footnote>
533 description files, configuration fragments, and patches. 537 description files, configuration fragments, and patches.
534 The <filename>scc</filename> files define variables and include or 538 The <filename>scc</filename> files define variables and include or
535 otherwise reference any of the three file types. 539 otherwise reference any of the three file types.
536 The description files are used to aggregate all types of metadata into 540 The description files are used to aggregate all types of kernel
541 Metadata into
537 what ultimately describes the sources and the configuration required 542 what ultimately describes the sources and the configuration required
538 to build a Linux kernel tailored to a specific machine. 543 to build a Linux kernel tailored to a specific machine.
539 </para> 544 </para>
540 545
541 <para> 546 <para>
542 The <filename>scc</filename> description files are used to define two 547 The <filename>scc</filename> description files are used to define two
543 fundamental types of metadata: 548 fundamental types of kernel Metadata:
544 <itemizedlist> 549 <itemizedlist>
545 <listitem><para>Features</para></listitem> 550 <listitem><para>Features</para></listitem>
546 <listitem><para>Board Support Packages (BSPs)</para></listitem> 551 <listitem><para>Board Support Packages (BSPs)</para></listitem>
@@ -549,12 +554,12 @@ git repository:
549 554
550 <para> 555 <para>
551 Features aggregate sources in the form of patches and configuration 556 Features aggregate sources in the form of patches and configuration
552 in the form of configuration fragments into a modular reusable unit. 557 fragments into a modular reusable unit.
553 Features are used to implement conceptually separate metadata 558 You can use features to implement conceptually separate kernel
554 descriptions like pure configuration fragments, simple patches, 559 Metadata descriptions such as pure configuration fragments,
555 complex features, and kernel types (ktypes). 560 simple patches, complex features, and kernel types.
556 Kernel types define general kernel features and policy to be reused 561 <link linkend='kernel-types'>Kernel types</link> define general
557 in the BSPs. 562 kernel features and policy to be reused in the BSPs.
558 </para> 563 </para>
559 564
560 <para> 565 <para>
@@ -563,10 +568,11 @@ git repository:
563 </para> 568 </para>
564 569
565 <para> 570 <para>
566 While the metadata syntax does not enforce any logical separation of 571 While the kernel Metadata syntax does not enforce any logical
567 configuration fragments, patches, features or kernel types, best 572 separation of configuration fragments, patches, features or kernel
568 practices dictate a logical separation of these types of meta-data. 573 types, best practices dictate a logical separation of these types
569 The following metadata file hierarchy is recommended: 574 of Metadata.
575 The following Metadata file hierarchy is recommended:
570 <literallayout class='monospaced'> 576 <literallayout class='monospaced'>
571 &lt;base&gt;/ 577 &lt;base&gt;/
572 bsp/ 578 bsp/
@@ -578,44 +584,55 @@ git repository:
578 </para> 584 </para>
579 585
580 <para> 586 <para>
581 The <filename>bsp</filename> directory should contain the 587 The <filename>bsp</filename> directory contains the
582 BSP descriptions, described in detail in section 3.3.5. 588 <link linkend='bsp-descriptions'>BSP descriptions</link>.
583 The remaining directories all contain "features"; the separation 589 The remaining directories all contain "features".
584 is meant to aid in conceptualizing their intended usage. 590 Separating <filename>bsp</filename> from the rest of the structure
585 A simple guide to determine where your <filename>scc</filename> 591 aids conceptualizing intended usage.
586 description file should go is as follows. 592 </para>
587 If it contains only configuration fragments, it belongs in 593
588 <filename>cfg</filename>. 594 <para>
589 If it contains only source-code fixes, it belongs in 595 Use these guidelines to help place your <filename>scc</filename>
590 <filename>patches</filename>. 596 description files within the structure:
591 If it encapsulates a major feature, often combining sources and 597 <itemizedlist>
592 configurations, it belongs in <filename>features</filename>. 598 <listitem><para>If your file contains
593 If it aggregates non-hardware configuration and patches 599 only configuration fragments, place the file in
594 in order to define a base kernel policy or major kernel type to 600 <filename>cfg</filename>.</para></listitem>
595 be reused across multiple BSPs, it belongs in 601 <listitem><para>If your file contains
596 <filename>ktypes</filename>. 602 only source-code fixes, place the file in
603 <filename>patches</filename>.</para></listitem>
604 <listitem><para>If your file encapsulates
605 a major feature, often combining sources and configurations,
606 place the file in <filename>features</filename>.
607 </para></listitem>
608 <listitem><para>If your file aggregates
609 non-hardware configuration and patches in order to define a
610 base kernel policy or major kernel type to be reused across
611 multiple BSPs, place the file in <filename>ktypes</filename>.
612 </para></listitem>
613 </itemizedlist>
597 </para> 614 </para>
598 615
599 <para> 616 <para>
600 The lines between these can easily become blurred, especially as 617 These distinctions can easily become blurred - especially as
601 out-of-tree features are slowly merged upstream over time. 618 out-of-tree features slowly merge upstream over time.
602 Also remember that this is purely logical organization and has 619 Also, remember that how the description files are placed is
603 no impact on the functionality of the metadata as 620 a purely logical organization and has no impact on the functionality
604 all of <filename>cfg</filename>, <filename>features</filename>, 621 of the kernel Metadata.
605 <filename>patches</filename>, and <filename>ktypes</filename>, 622 There is no impact because all of <filename>cfg</filename>,
606 contain "features" as far as the Yocto Project Linux kernel 623 <filename>features</filename>, <filename>patches</filename>, and
624 <filename>ktypes</filename>, contain "features" as far as the kernel
607 tools are concerned. 625 tools are concerned.
608 </para> 626 </para>
609 627
610 <para> 628 <para>
611 Paths used in metadata files are relative to 629 Paths used in kernel Metadata files are relative to
612 <filename>&lt;base&gt;</filename>, which is either 630 <filename>&lt;base&gt;</filename>, which is either
613 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> 631 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
614 if you are creating metadata in recipe-space as described in 632 if you are creating Metadata in
615 section "<link linkend='recipe-space-metadata'>Recipe-Space Metadata</link>", 633 <link linkend='recipe-space-metadata'>recipe-space</link>,
616 or <filename>meta/cfg/kernel-cache/</filename> if you are creating 634 or <filename>meta/cfg/kernel-cache/</filename> if you are creating
617 metadata in-tree as described in 635 Metadata <link linkend='in-tree-metadata'>in-tree</link>.
618 the "<link linkend='in-tree-metadata'>In-Tree Metadata</link>" section.
619 </para> 636 </para>
620 637
621 <para> 638 <para>