summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/bsp-guide/bsp.xml102
1 files changed, 54 insertions, 48 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 8223954f04..0159f48848 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -505,10 +505,10 @@
505 </para> 505 </para>
506 506
507 <para> 507 <para>
508 These files append your specific changes to the kernel you are using. 508 These files append your specific changes to the main kernel recipe you are using.
509 </para> 509 </para>
510 <para> 510 <para>
511 For your BSP, you typically want to use an existing Yocto Project kernel found in the 511 For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the
512 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> 512 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>
513 at <filename>meta/recipes-kernel/linux</filename>. 513 at <filename>meta/recipes-kernel/linux</filename>.
514 You can append your specific changes to the kernel recipe by using a 514 You can append your specific changes to the kernel recipe by using a
@@ -516,22 +516,22 @@
516 the <filename>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> directory). 516 the <filename>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> directory).
517 </para> 517 </para>
518 <para> 518 <para>
519 Suppose you are using the <filename>linux-yocto_3.2.bb</filename> recipe to build 519 Suppose you are using the <filename>linux-yocto_3.4.bb</filename> recipe to build
520 the kernel. 520 the kernel.
521 In other words, you have selected the kernel in your 521 In other words, you have selected the kernel in your
522 <filename>&lt;bsp_name&gt;.conf</filename> file by adding the following statements: 522 <filename>&lt;bsp_name&gt;.conf</filename> file by adding the following statements:
523 <literallayout class='monospaced'> 523 <literallayout class='monospaced'>
524 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 524 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
525 PREFERRED_VERSION_linux-yocto = "3.2%" 525 PREFERRED_VERSION_linux-yocto = "3.4%"
526 </literallayout> 526 </literallayout>
527 You would use the <filename>linux-yocto_3.2.bbappend</filename> file to append 527 You would use the <filename>linux-yocto_3.4.bbappend</filename> file to append
528 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. 528 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.
529 </para> 529 </para>
530 <para> 530 <para>
531 As an example, look at the existing Crown Bay BSP. 531 As an example, look at the existing Crown Bay BSP.
532 The append file used is: 532 The append file used is:
533 <literallayout class='monospaced'> 533 <literallayout class='monospaced'>
534 meta-crownbay/recipes-kernel/linux/linux-yocto_3.2.bbappend 534 meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend
535 </literallayout> 535 </literallayout>
536 The following listing shows the file. 536 The following listing shows the file.
537 Be aware that the actual commit ID strings in this example listing might be different 537 Be aware that the actual commit ID strings in this example listing might be different
@@ -558,7 +558,7 @@
558 <trademark class='registered'>Intel</trademark> EMGD and the VESA graphics. 558 <trademark class='registered'>Intel</trademark> EMGD and the VESA graphics.
559 The build process, in this case, recognizes and uses only the statements that 559 The build process, in this case, recognizes and uses only the statements that
560 apply to the defined machine name - <filename>crownbay</filename> in this case. 560 apply to the defined machine name - <filename>crownbay</filename> in this case.
561 So, the applicable statements in the <filename>linux-yocto_3.2.bbappend</filename> 561 So, the applicable statements in the <filename>linux-yocto_3.4.bbappend</filename>
562 file are follows: 562 file are follows:
563 <literallayout class='monospaced'> 563 <literallayout class='monospaced'>
564 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 564 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@@ -570,41 +570,42 @@
570 SRCREV_machine_pn-linux-yocto_crownbay ?= "48101e609711fcfe8d5e737a37a5a69f4bd57d9a" 570 SRCREV_machine_pn-linux-yocto_crownbay ?= "48101e609711fcfe8d5e737a37a5a69f4bd57d9a"
571 SRCREV_meta_pn-linux-yocto_crownbay ?= "5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b" 571 SRCREV_meta_pn-linux-yocto_crownbay ?= "5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b"
572 </literallayout> 572 </literallayout>
573 The append file defines <filename>crownbay</filename> as the compatible machine and 573 The append file defines <filename>crownbay</filename> as the
574 defines the <filename>KMACHINE</filename>. 574 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
575 The file also points to some configuration fragments to use by setting the 575 and defines the <filename>KMACHINE</filename>.
576 <filename>KERNEL_FEATURES</filename> variable. 576 The file also uses the optional
577 The location for the configuration fragments is the kernel tree itself in the 577 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> variable
578 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink> 578 to ensure the build process uses the <filename>standard/default/crownbay</filename>
579 under <filename>linux/meta</filename>. 579 kernel branch.
580 Finally, the append file points to the specific commits in the 580 Finally, the append file points to the specific top commits in the
581 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> Git 581 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> Git
582 repository and the <filename>meta</filename> Git repository branches to identify the 582 repository and the <filename>meta</filename> Git repository branches to identify the
583 exact kernel needed to build the Crown Bay BSP. 583 exact kernel needed to build the Crown Bay BSP.
584 </para> 584 </para>
585
585 <para> 586 <para>
586 One thing missing in this particular BSP, which you will typically need when 587 One thing missing in this particular BSP, which you will typically need when
587 developing a BSP, is the kernel configuration file (<filename>.config</filename>) for your BSP. 588 developing a BSP, is the kernel configuration file (<filename>.config</filename>) for your BSP.
588 When developing a BSP, you probably have a kernel configuration file or a set of kernel 589 When developing a BSP, you probably have a kernel configuration file or a set of kernel
589 configuration files that, when taken together, define the kernel configuration for your BSP. 590 configuration files that, when taken together, define the kernel configuration for your BSP.
590 You can accomplish this definition by putting the configurations in a file or a set of files 591 You can accomplish this definition by putting the configurations in a file or a set of files
591 inside a directory located at the same level as your append file and having the same name 592 inside a directory located at the same level as your kernel's append file and having the same
592 as the kernel. 593 name as the kernel's main recipe file.
593 With all these conditions met simply reference those files in a 594 With all these conditions met, simply reference those files in a
594 <filename>SRC_URI</filename> statement in the append file. 595 <filename>SRC_URI</filename> statement in the append file.
595 </para> 596 </para>
597
596 <para> 598 <para>
597 For example, suppose you had a set of configuration options in a file called 599 For example, suppose you had a set of configuration options in a file called
598 <filename>myconfig</filename>. 600 <filename>myconfig.cfg</filename>.
599 If you put that file inside a directory named 601 If you put that file inside a directory named <filename>/linux-yocto</filename> and then added
600 <filename>/linux-yocto</filename> and then added
601 a <filename>SRC_URI</filename> statement such as the following to the append file, 602 a <filename>SRC_URI</filename> statement such as the following to the append file,
602 those configuration 603 those configuration options will be picked up and applied when the kernel is built.
603 options will be picked up and applied when the kernel is built.
604 <literallayout class='monospaced'> 604 <literallayout class='monospaced'>
605 SRC_URI += "file://myconfig" 605 SRC_URI += "file://myconfig.cfg"
606 </literallayout> 606 </literallayout>
607 </para> 607 </para>
608
608 <para> 609 <para>
609 As mentioned earlier, you can group related configurations into multiple files and 610 As mentioned earlier, you can group related configurations into multiple files and
610 name them all in the <filename>SRC_URI</filename> statement as well. 611 name them all in the <filename>SRC_URI</filename> statement as well.
@@ -612,11 +613,12 @@
612 into their own files and add those by using a <filename>SRC_URI</filename> statement like the 613 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
613 following in your append file: 614 following in your append file:
614 <literallayout class='monospaced'> 615 <literallayout class='monospaced'>
615 SRC_URI += "file://myconfig \ 616 SRC_URI += "file://myconfig.cfg \
616 file://eth.cfg \ 617 file://eth.cfg \
617 file://gfx.cfg" 618 file://gfx.cfg"
618 </literallayout> 619 </literallayout>
619 </para> 620 </para>
621
620 <para> 622 <para>
621 The <filename>FILESEXTRAPATHS</filename> variable is in boilerplate form in the 623 The <filename>FILESEXTRAPATHS</filename> variable is in boilerplate form in the
622 previous example in order to make it easy to do that. 624 previous example in order to make it easy to do that.
@@ -625,32 +627,36 @@
625 The <filename>FILESEXTRAPATHS</filename> variable enables the build process to 627 The <filename>FILESEXTRAPATHS</filename> variable enables the build process to
626 find those configuration files. 628 find those configuration files.
627 </para> 629 </para>
630
628 <note> 631 <note>
629 <para> 632 <para>
630 Other methods exist to accomplish grouping and defining configuration options. 633 Other methods exist to accomplish grouping and defining configuration options.
631 For example, if you are working with a local clone of the kernel repository, 634 For example, if you are working with a local clone of the kernel repository,
632 you could checkout the kernel's <filename>meta</filename> branch, make your changes, 635 you could checkout the kernel's <filename>meta</filename> branch, make your changes,
633 and then push the changes to the local bare clone of the kernel. 636 and then push the changes to the local bare clone of the kernel.
634 The result is that you directly add configuration options to the 637 The result is that you directly add configuration options to the
635 <filename>meta</filename> branch for your BSP. 638 <filename>meta</filename> branch for your BSP.
636 The configuration options will likely end up in that location anyway if the BSP gets 639 The configuration options will likely end up in that location anyway if the BSP gets
637 added to the Yocto Project. 640 added to the Yocto Project.
638 For an example showing how to change the BSP configuration, see the 641 For an example showing how to change the BSP configuration, see the
639 "<ulink url='&YOCTO_DOCS_DEV_URL;#changing-the-bsp-configuration'>Changing the BSP Configuration</ulink>" 642 "<ulink url='&YOCTO_DOCS_DEV_URL;#changing-the-bsp-configuration'>Changing the BSP Configuration</ulink>"
640 section in the Yocto Project Development Manual. 643 section in the Yocto Project Development Manual.
641 For a better understanding of working with a local clone of the kernel repository 644 For a better understanding of working with a local clone of the kernel repository
642 and a local bare clone of the kernel, see the 645 and a local bare clone of the kernel, see the
643 "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel-source-code'>Modifying the Kernel 646 "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel-source-code'>Modifying the Kernel
644 Source Code</ulink>" section also in the Yocto Project Development Manual.</para> 647 Source Code</ulink>" section also in the Yocto Project Development Manual.
648 </para>
649
645 <para> 650 <para>
646 In general, however, the Yocto Project maintainers take care of moving the 651 In general, however, the Yocto Project maintainers take care of moving the
647 <filename>SRC_URI</filename>-specified 652 <filename>SRC_URI</filename>-specified
648 configuration options to the kernel's <filename>meta</filename> branch. 653 configuration options to the kernel's <filename>meta</filename> branch.
649 Not only is it easier for BSP developers to not have to worry about putting those 654 Not only is it easier for BSP developers to not have to worry about putting those
650 configurations in the branch, but having the maintainers do it allows them to apply 655 configurations in the branch, but having the maintainers do it allows them to apply
651 'global' knowledge about the kinds of common configuration options multiple BSPs in 656 'global' knowledge about the kinds of common configuration options multiple BSPs in
652 the tree are typically using. 657 the tree are typically using.
653 This allows for promotion of common configurations into common features.</para> 658 This allows for promotion of common configurations into common features.
659 </para>
654 </note> 660 </note>
655 </section> 661 </section>
656 </section> 662 </section>