diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.xml')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-advanced.xml | 390 |
1 files changed, 227 insertions, 163 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 1c1b6366db..434c01fafb 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml | |||
@@ -524,170 +524,219 @@ | |||
524 | <title>BSP Descriptions</title> | 524 | <title>BSP Descriptions</title> |
525 | 525 | ||
526 | <para> | 526 | <para> |
527 | BSP descriptions combine kernel types with hardware-specific | 527 | BSP descriptions (i.e. <filename>*.scc</filename> files) |
528 | features. | 528 | combine kernel types with hardware-specific features. |
529 | The hardware-specific portion is typically defined | 529 | The hardware-specific Metadata is typically defined |
530 | independently, and then aggregated with each supported kernel | 530 | independently in the BSP layer, and then aggregated with each |
531 | type. | 531 | supported kernel type. |
532 | Consider this simple BSP description that supports the | ||
533 | <replaceable>mybsp</replaceable> machine: | ||
534 | <literallayout class='monospaced'> | ||
535 | <replaceable>mybsp</replaceable>.scc: | ||
536 | define KMACHINE <replaceable>mybsp</replaceable> | ||
537 | define KTYPE standard | ||
538 | define KARCH i386 | ||
539 | |||
540 | kconf <replaceable>mybsp</replaceable>.cfg | ||
541 | </literallayout> | ||
542 | Every BSP description should define the | ||
543 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, | ||
544 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, | ||
545 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink> | ||
546 | variables. | ||
547 | These variables allow the OpenEmbedded build system to identify | ||
548 | the description as meeting the criteria set by the recipe being | ||
549 | built. | ||
550 | This simple example supports the "mybsp" machine for the "standard" | ||
551 | kernel and the "i386" architecture. | ||
552 | </para> | ||
553 | |||
554 | <para> | ||
555 | Be aware that a hard link between the | ||
556 | <filename>KTYPE</filename> variable and a kernel type | ||
557 | description file does not exist. | ||
558 | Thus, if you do not have kernel types defined in your kernel | ||
559 | Metadata, you only need to ensure that the kernel recipe's | ||
560 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> | ||
561 | variable and the <filename>KTYPE</filename> variable in the | ||
562 | BSP description file match. | ||
563 | <note> | 532 | <note> |
564 | Future versions of the tooling make the specification of | 533 | For BSPs supported by the Yocto Project, the BSP description |
565 | <filename>KTYPE</filename> in the BSP optional. | 534 | files are located in the <filename>bsp</filename> directory |
535 | of the <filename>yocto-kernel-cache</filename> repository | ||
536 | organized under the "Yocto Linux Kernel" heading in the | ||
537 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. | ||
566 | </note> | 538 | </note> |
567 | </para> | 539 | </para> |
568 | 540 | ||
569 | <para> | 541 | <para> |
570 | If you did want to separate your kernel policy from your | 542 | This section provides a BSP description structural overview along |
571 | hardware configuration, you could do so by specifying a kernel | 543 | with aggregation concepts as well as a detailed example using |
572 | type, such as "standard" and including that description file | 544 | a BSP supported by the Yocto Project (i.e. Minnow Board). |
573 | in the BSP description file. | ||
574 | See the "<link linkend='kernel-types'>Kernel Types</link>" section | ||
575 | for more information. | ||
576 | </para> | 545 | </para> |
577 | 546 | ||
578 | <para> | 547 | <section id='bsp-description-file-overview'> |
579 | You might also have multiple hardware configurations that you | 548 | <title>Overview</title> |
580 | aggregate into a single hardware description file that you | ||
581 | could include in the BSP description file, rather than referencing | ||
582 | a single <filename>.cfg</filename> file. | ||
583 | Consider the following: | ||
584 | <literallayout class='monospaced'> | ||
585 | <replaceable>mybsp</replaceable>.scc: | ||
586 | define KMACHINE mybsp | ||
587 | define KTYPE standard | ||
588 | define KARCH i386 | ||
589 | |||
590 | include standard.scc | ||
591 | include <replaceable>mybsp</replaceable>-hw.scc | ||
592 | </literallayout> | ||
593 | </para> | ||
594 | 549 | ||
595 | <para> | 550 | <para> |
596 | In the above example, <filename>standard.scc</filename> | 551 | For simplicity, consider the following top-level BSP |
597 | aggregates all the configuration fragments, patches, and | 552 | description file. |
598 | features that make up your standard kernel policy whereas | 553 | Top-level BSP descriptions files employ both a structure |
599 | <replaceable>mybsp</replaceable><filename>-hw.scc</filename> | 554 | and naming convention for consistency. |
600 | aggregates all those necessary | 555 | The naming convention for the file is as follows: |
601 | to support the hardware available on the | 556 | <literallayout class='monospaced'> |
602 | <replaceable>mybsp</replaceable> machine. | 557 | <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc |
603 | For information on how to break a complete | 558 | </literallayout> |
604 | <filename>.config</filename> file into the various | 559 | Here are some example top-level BSP filenames for the |
605 | configuration fragments, see the | 560 | Minnow Board BSP, which is supported by the Yocto Project: |
606 | "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" | 561 | <literallayout class='monospaced'> |
607 | section. | 562 | minnow-standard.scc |
608 | </para> | 563 | minnow-preempt-rt.scc |
564 | minnow-tiny.scc | ||
565 | </literallayout> | ||
566 | Each file uses the BSP name followed by the kernel type. | ||
567 | </para> | ||
609 | 568 | ||
610 | <para> | 569 | <para> |
611 | Many real-world examples are more complex. | 570 | is simple BSP description file whose name has the |
612 | Like any other <filename>.scc</filename> file, BSP | 571 | form |
613 | descriptions can aggregate features. | 572 | <replaceable>mybsp</replaceable><filename>-standard</filename> |
614 | Consider the Minnow BSP definition from the | 573 | and supports the <replaceable>mybsp</replaceable> machine using |
615 | <filename>linux-yocto-3.19</filename> | 574 | a standard kernel: |
616 | Git repository: | 575 | <literallayout class='monospaced'> |
617 | <literallayout class='monospaced'> | 576 | define KMACHINE <replaceable>mybsp</replaceable> |
618 | minnow.scc: | 577 | define KTYPE standard |
619 | include cfg/x86.scc | 578 | define KARCH i386 |
620 | include features/eg20t/eg20t.scc | 579 | |
621 | include cfg/dmaengine.scc | 580 | include ktypes/standard |
622 | include features/power/intel.scc | 581 | |
623 | include cfg/efi.scc | 582 | include <replaceable>mybsp</replaceable>.scc |
624 | include features/usb/ehci-hcd.scc | 583 | |
625 | include features/usb/ohci-hcd.scc | 584 | kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg |
626 | include features/usb/usb-gadgets.scc | 585 | </literallayout> |
627 | include features/usb/touchscreen-composite.scc | 586 | Every top-level BSP description file should define the |
628 | include cfg/timer/hpet.scc | 587 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, |
629 | include cfg/timer/rtc.scc | 588 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, |
630 | include features/leds/leds.scc | 589 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink> |
631 | include features/spi/spidev.scc | 590 | variables. |
632 | include features/i2c/i2cdev.scc | 591 | These variables allow the OpenEmbedded build system to identify |
633 | 592 | the description as meeting the criteria set by the recipe being | |
634 | # Earlyprintk and port debug requires 8250 | 593 | built. |
635 | kconf hardware cfg/8250.cfg | 594 | This simple example supports the "mybsp" machine for the "standard" |
636 | 595 | kernel and the "i386" architecture. | |
637 | kconf hardware minnow.cfg | 596 | </para> |
638 | kconf hardware minnow-dev.cfg | ||
639 | </literallayout> | ||
640 | </para> | ||
641 | 597 | ||
642 | <para> | 598 | <para> |
643 | The <filename>minnow.scc</filename> description file includes | 599 | Be aware that a hard link between the |
644 | a hardware configuration fragment | 600 | <filename>KTYPE</filename> variable and a kernel type description |
645 | (<filename>minnow.cfg</filename>) specific to the Minnow | 601 | file does not exist. |
646 | BSP as well as several more general configuration | 602 | Thus, if you do not have kernel types defined in your kernel |
647 | fragments and features enabling hardware found on the | 603 | Metadata, you only need to ensure that the kernel recipe's |
648 | machine. | 604 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> |
649 | This description file is then included in each of the three | 605 | variable and the <filename>KTYPE</filename> variable in the |
650 | "minnow" description files for the supported kernel types | 606 | BSP description file match. |
651 | (i.e. "standard", "preempt-rt", and "tiny"). | 607 | <note> |
652 | Consider the "minnow" description for the "standard" kernel | 608 | Future versions of the tooling make the specification of |
653 | type: | 609 | <filename>KTYPE</filename> in the BSP optional. |
654 | <literallayout class='monospaced'> | 610 | </note> |
655 | minnow-standard.scc: | 611 | </para> |
656 | define KMACHINE minnow | ||
657 | define KTYPE standard | ||
658 | define KARCH i386 | ||
659 | 612 | ||
660 | include ktypes/standard | 613 | <para> |
614 | To separate your kernel policy from your hardware configuration, | ||
615 | you include a kernel type (<filename>ktype</filename>), such as | ||
616 | "standard". | ||
617 | In the previous example, this is done using the following: | ||
618 | <literallayout class='monospaced'> | ||
619 | include ktypes/standard | ||
620 | </literallayout> | ||
621 | In the previous example, <filename>ktypes/standard.scc</filename> | ||
622 | aggregates all the configuration fragments, patches, and | ||
623 | features that make up your standard kernel policy. | ||
624 | See the "<link linkend='kernel-types'>Kernel Types</link>" section | ||
625 | for more information. | ||
626 | </para> | ||
661 | 627 | ||
662 | include minnow.scc | 628 | <para> |
629 | To aggregate common configurations and features specific to the | ||
630 | kernel for <replaceable>mybsp</replaceable>, use the following: | ||
631 | <literallayout class='monospaced'> | ||
632 | include <replaceable>mybsp</replaceable>.scc | ||
633 | </literallayout> | ||
634 | For information on how to break a complete | ||
635 | <filename>.config</filename> file into the various | ||
636 | configuration fragments, see the | ||
637 | "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" | ||
638 | section. | ||
639 | </para> | ||
663 | 640 | ||
664 | # Extra minnow configs above the minimal defined in minnow.scc | 641 | <para> |
665 | include cfg/efi-ext.scc | 642 | Finally, if you have any configurations specific to the |
666 | include features/media/media-all.scc | 643 | hardware that are not in a <filename>*.scc</filename> file, |
667 | include features/sound/snd_hda_intel.scc | 644 | you can include them as follows: |
645 | <literallayout class='monospaced'> | ||
646 | kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg | ||
647 | </literallayout> | ||
648 | </para> | ||
649 | </section> | ||
668 | 650 | ||
669 | # The following should really be in standard.scc | 651 | <section id='bsp-description-file-example-minnow'> |
670 | # USB live-image support | 652 | <title>Example</title> |
671 | include cfg/usb-mass-storage.scc | ||
672 | include cfg/boot-live.scc | ||
673 | 653 | ||
674 | # Basic profiling | 654 | <para> |
675 | include features/latencytop/latencytop.scc | 655 | Many real-world examples are more complex. |
676 | include features/profiling/profiling.scc | 656 | Like any other <filename>.scc</filename> file, BSP |
657 | descriptions can aggregate features. | ||
658 | Consider the Minnow BSP definition from the | ||
659 | <filename>linux-yocto-4.4</filename> in the | ||
660 | Yocto Project | ||
661 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink> | ||
662 | (i.e. | ||
663 | <filename>yocto-kernel-cache/bsp/minnow</filename>): | ||
664 | <literallayout class='monospaced'> | ||
665 | minnow.scc: | ||
666 | include cfg/x86.scc | ||
667 | include features/eg20t/eg20t.scc | ||
668 | include cfg/dmaengine.scc | ||
669 | include features/power/intel.scc | ||
670 | include cfg/efi.scc | ||
671 | include features/usb/ehci-hcd.scc | ||
672 | include features/usb/ohci-hcd.scc | ||
673 | include features/usb/usb-gadgets.scc | ||
674 | include features/usb/touchscreen-composite.scc | ||
675 | include cfg/timer/hpet.scc | ||
676 | include features/leds/leds.scc | ||
677 | include features/spi/spidev.scc | ||
678 | include features/i2c/i2cdev.scc | ||
679 | include features/mei/mei-txe.scc | ||
680 | |||
681 | # Earlyprintk and port debug requires 8250 | ||
682 | kconf hardware cfg/8250.cfg | ||
683 | |||
684 | kconf hardware minnow.cfg | ||
685 | kconf hardware minnow-dev.cfg | ||
686 | </literallayout> | ||
687 | </para> | ||
677 | 688 | ||
678 | # Requested drivers that don't have an existing scc | 689 | <para> |
679 | kconf hardware minnow-drivers-extra.cfg | 690 | The <filename>minnow.scc</filename> description file includes |
680 | </literallayout> | 691 | a hardware configuration fragment |
681 | The <filename>include</filename> command midway through the file | 692 | (<filename>minnow.cfg</filename>) specific to the Minnow |
682 | includes the <filename>minnow.scc</filename> description that | 693 | BSP as well as several more general configuration |
683 | defines all hardware enablements for the BSP that is common to all | 694 | fragments and features enabling hardware found on the |
684 | kernel types. | 695 | machine. |
685 | Using this command significantly reduces duplication. | 696 | This <filename>minnow.scc</filename> description file is then |
686 | </para> | 697 | included in each of the three |
698 | "minnow" description files for the supported kernel types | ||
699 | (i.e. "standard", "preempt-rt", and "tiny"). | ||
700 | Consider the "minnow" description for the "standard" kernel | ||
701 | type: | ||
702 | <literallayout class='monospaced'> | ||
703 | minnow-standard.scc: | ||
704 | define KMACHINE minnow | ||
705 | define KTYPE standard | ||
706 | define KARCH i386 | ||
707 | |||
708 | include ktypes/standard | ||
709 | |||
710 | include minnow.scc | ||
711 | |||
712 | # Extra minnow configs above the minimal defined in minnow.scc | ||
713 | include cfg/efi-ext.scc | ||
714 | include features/media/media-all.scc | ||
715 | include features/sound/snd_hda_intel.scc | ||
716 | |||
717 | # The following should really be in standard.scc | ||
718 | # USB live-image support | ||
719 | include cfg/usb-mass-storage.scc | ||
720 | include cfg/boot-live.scc | ||
721 | |||
722 | # Basic profiling | ||
723 | include features/latencytop/latencytop.scc | ||
724 | include features/profiling/profiling.scc | ||
725 | |||
726 | # Requested drivers that don't have an existing scc | ||
727 | kconf hardware minnow-drivers-extra.cfg | ||
728 | </literallayout> | ||
729 | The <filename>include</filename> command midway through the file | ||
730 | includes the <filename>minnow.scc</filename> description that | ||
731 | defines all enabled hardware for the BSP that is common to | ||
732 | all kernel types. | ||
733 | Using this command significantly reduces duplication. | ||
734 | </para> | ||
687 | 735 | ||
688 | <para> | 736 | <para> |
689 | Now consider the "minnow" description for the "tiny" kernel type: | 737 | Now consider the "minnow" description for the "tiny" kernel |
690 | <literallayout class='monospaced'> | 738 | type: |
739 | <literallayout class='monospaced'> | ||
691 | minnow-tiny.scc: | 740 | minnow-tiny.scc: |
692 | define KMACHINE minnow | 741 | define KMACHINE minnow |
693 | define KTYPE tiny | 742 | define KTYPE tiny |
@@ -696,22 +745,24 @@ | |||
696 | include ktypes/tiny | 745 | include ktypes/tiny |
697 | 746 | ||
698 | include minnow.scc | 747 | include minnow.scc |
699 | </literallayout> | 748 | </literallayout> |
700 | As you might expect, the "tiny" description includes quite a | 749 | As you might expect, the "tiny" description includes quite a |
701 | bit less. | 750 | bit less. |
702 | In fact, it includes only the minimal policy defined by the | 751 | In fact, it includes only the minimal policy defined by the |
703 | "tiny" kernel type and the hardware-specific configuration required | 752 | "tiny" kernel type and the hardware-specific configuration |
704 | for booting the machine along with the most basic functionality of | 753 | required for booting the machine along with the most basic |
705 | the system as defined in the base "minnow" description file. | 754 | functionality of the system as defined in the base "minnow" |
706 | </para> | 755 | description file. |
756 | </para> | ||
707 | 757 | ||
708 | <para> | 758 | <para> |
709 | Notice again the three critical variables: | 759 | Notice again the three critical variables: |
710 | <filename>KMACHINE</filename>, <filename>KTYPE</filename>, | 760 | <filename>KMACHINE</filename>, <filename>KTYPE</filename>, |
711 | and <filename>KARCH</filename>. | 761 | and <filename>KARCH</filename>. |
712 | Of these variables, only the <filename>KTYPE</filename> has changed. | 762 | Of these variables, only the <filename>KTYPE</filename> has changed. |
713 | It is now set to "tiny". | 763 | It is now set to "tiny". |
714 | </para> | 764 | </para> |
765 | </section> | ||
715 | </section> | 766 | </section> |
716 | </section> | 767 | </section> |
717 | 768 | ||
@@ -795,6 +846,18 @@ | |||
795 | value when changing the content of files not explicitly listed | 846 | value when changing the content of files not explicitly listed |
796 | in the <filename>SRC_URI</filename>. | 847 | in the <filename>SRC_URI</filename>. |
797 | </para> | 848 | </para> |
849 | |||
850 | <para> | ||
851 | If the kernel Metadata is in a layer, you cannot simply list the | ||
852 | <filename>*.scc</filename> in the <filename>SRC_URI</filename> | ||
853 | statement. | ||
854 | You need to use the following form from your kernel append file: | ||
855 | <literallayout class='monospaced'> | ||
856 | SRC_URI_append_<replaceable>myplatform</replaceable> = " \ | ||
857 | file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \ | ||
858 | " | ||
859 | </literallayout> | ||
860 | </para> | ||
798 | </section> | 861 | </section> |
799 | 862 | ||
800 | <section id='metadata-outside-the-recipe-space'> | 863 | <section id='metadata-outside-the-recipe-space'> |
@@ -817,7 +880,8 @@ | |||
817 | <filename>${KMETA}</filename>, in this context, is simply used to | 880 | <filename>${KMETA}</filename>, in this context, is simply used to |
818 | name the directory into which the Git fetcher places the Metadata. | 881 | name the directory into which the Git fetcher places the Metadata. |
819 | This behavior is no different than any multi-repository | 882 | This behavior is no different than any multi-repository |
820 | <filename>SRC_URI</filename> statement used in a recipe. | 883 | <filename>SRC_URI</filename> statement used in a recipe (e.g. |
884 | see the previous section). | ||
821 | </para> | 885 | </para> |
822 | 886 | ||
823 | <para> | 887 | <para> |