summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-28 15:12:16 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-12 00:28:14 +0100
commit56b3c79a3e13c93d8f1aa5535e798783a8ef3769 (patch)
treeb3022b80064f9ba5f9231ef9ead0eca94add5eab /documentation/bsp-guide
parenta8c8680f84a9d3496676be4d30c52f90c1c7c1d1 (diff)
downloadpoky-56b3c79a3e13c93d8f1aa5535e798783a8ef3769.tar.gz
bsp-guide: Minor introduction rewrite and formatting BSP workflow.
(From yocto-docs rev: 697d8ce39a122a33faebf1ab66b6bb16bfab5986) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/bsp-guide')
-rw-r--r--documentation/bsp-guide/bsp.xml271
1 files changed, 149 insertions, 122 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index f452c6eaec..dacd077f2d 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -714,34 +714,25 @@
714 <title>Developing a Board Support Package (BSP)</title> 714 <title>Developing a Board Support Package (BSP)</title>
715 715
716 <para> 716 <para>
717 A BSP is a collection of recipes that, when applied during a build, results in 717 This section contains the high-level procedure you can follow
718 an image that you can run on a particular board. 718 to create a BSP using the Yocto Project's
719 Thus, the package when compiled into the new image, supports the operation of the board.
720 </para>
721
722 <note>
723 For a brief list of terms used when describing the development process in the Yocto Project,
724 see the
725 "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-terms'>Yocto Project Terms</ulink>" section.
726 </note>
727
728 <para>
729 The remainder of this section presents the basic
730 steps used to create a BSP using the Yocto Project's
731 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>. 719 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
732 Although not required for BSP creation, the 720 Although not required for BSP creation, the
733 <filename>meta-intel</filename> repository, which contains 721 <filename>meta-intel</filename> repository, which contains
734 many BSPs supported by the Yocto Project, is part of the example. 722 many BSPs supported by the Yocto Project, is part of the
723 example.
735 </para> 724 </para>
736 725
737 <para> 726 <para>
738 For an example that shows how to create a new layer using the tools, see the 727 For an example that shows how to create a new layer using
728 the tools, see the
739 "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>" 729 "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
740 section. 730 section.
741 </para> 731 </para>
742 732
743 <para> 733 <para>
744 The following illustration and list summarize the BSP creation general workflow. 734 The following illustration and list summarize the BSP
735 creation general workflow.
745 </para> 736 </para>
746 737
747 <para> 738 <para>
@@ -750,149 +741,185 @@
750 741
751 <para> 742 <para>
752 <orderedlist> 743 <orderedlist>
753 <listitem><para><emphasis>Set up your host development system to support 744 <listitem><para>
754 development using the Yocto Project</emphasis>: See the 745 <emphasis>Set Up Your Host Development System to Support
746 Development Using the Yocto Project:</emphasis>
747 See the
755 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" 748 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
756 and the 749 and the
757 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both 750 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
758 in the Yocto Project Quick Start for requirements.</para></listitem> 751 sections both in the Yocto Project Quick Start for
759 <listitem><para><emphasis>Establish a local copy of the project files on your 752 build host requirements.
760 system</emphasis>: You need this 753 </para></listitem>
754 <listitem><para>
755 <emphasis>Establish a Local Copy of the Project Files on
756 Your System:</emphasis>
757 You need this
761 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 758 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
762 available on your host system. 759 available on your host system.
763 Having these files on your system gives you access to the build 760 Having these files on your system gives you access to the
764 process and to the tools you need. 761 build process and to the tools you need.
765 For information on how to set up the Source Directory, 762 For information on how to set up the Source Directory,
766 see the 763 see the
767 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>" 764 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
768 section in the Yocto Project Development Manual. 765 section in the Yocto Project Development Manual.
769 </para></listitem> 766 </para></listitem>
770 <listitem><para><emphasis>Establish the <filename>meta-intel</filename> 767 <listitem><para>
771 repository on your system</emphasis>: Having local copies 768 <emphasis>Establish the <filename>meta-intel</filename>
772 of these supported BSP layers on your system gives you 769 Repository on Your System:</emphasis>
773 access to layers you might be able to build on or modify 770 Having local copies of these supported BSP layers on
774 to create your BSP. 771 your system gives you access to layers you might be able
772 to build on or modify to create your BSP.
775 For information on how to get these files, see the 773 For information on how to get these files, see the
776 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-bsp-layers'>Setting Up BSP Layers</ulink>" 774 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-bsp-layers'>Setting Up BSP Layers</ulink>"
777 section in the Yocto Project Development Manual. 775 section in the Yocto Project Development Manual.
778 </para></listitem> 776 </para></listitem>
779 <listitem><para><emphasis>Create your own BSP layer using the 777 <listitem><para>
780 <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></link> script</emphasis>: 778 <emphasis>Create Your Own BSP Layer Using the
781 Layers are ideal for 779 <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></link>
782 isolating and storing work for a given piece of hardware. 780 script:</emphasis>
783 A layer is really just a location or area in which you place 781 Layers are ideal for isolating and storing work for a
784 the recipes and configurations for your BSP. 782 given piece of hardware.
783 A layer is really just a location or area in which you
784 place the recipes and configurations for your BSP.
785 In fact, a BSP is, in itself, a special type of layer. 785 In fact, a BSP is, in itself, a special type of layer.
786 The simplest way to create a new BSP layer that is compliant with the 786 The simplest way to create a new BSP layer that is
787 Yocto Project is to use the <filename>yocto-bsp</filename> script. 787 compliant with the Yocto Project is to use the
788 <filename>yocto-bsp</filename> script.
788 For information about that script, see the 789 For information about that script, see the
789 "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>" 790 "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
791 section.</para>
792
793 <para>Another example that illustrates a layer
794 is an application.
795 Suppose you are creating an application that has
796 library or other dependencies in order for it to
797 compile and run.
798 The layer, in this case, would be where all the
799 recipes that define those dependencies are kept.
800 The key point for a layer is that it is an isolated
801 area that contains all the relevant information for
802 the project that the OpenEmbedded build system knows
803 about.
804 For more information on layers, see the
805 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
806 section in the Yocto Project Development Manual.
807 For more information on BSP layers, see the
808 "<link linkend='bsp-layers'>BSP Layers</link>"
790 section. 809 section.
791 </para> 810 <note><title>Notes</title>
811 <para>Five BSPs exist that are part of the Yocto
812 Project release:
813 <filename>beaglebone</filename> (ARM),
814 <filename>mpc8315e</filename> (PowerPC),
815 and <filename>edgerouter</filename> (MIPS).
816 The recipes and configurations for these five BSPs
817 are located and dispersed within the
818 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
819 </para>
792 820
793 <para> 821 <para>Three core Intel BSPs exist as part of the Yocto
794 Another example that illustrates a layer 822 Project release in the
795 is an application. 823 <filename>meta-intel</filename> layer:
796 Suppose you are creating an application that has 824 <itemizedlist>
797 library or other dependencies in order for it to 825 <listitem><para>
798 compile and run. 826 <filename>intel-core2-32</filename>,
799 The layer, in this case, would be where all the 827 which is a BSP optimized for the Core2 family of CPUs
800 recipes that define those dependencies are kept. 828 as well as all CPUs prior to the Silvermont core.
801 The key point for a layer is that it is an isolated 829 </para></listitem>
802 area that contains all the relevant information for 830 <listitem><para>
803 the project that the OpenEmbedded build system knows 831 <filename>intel-corei7-64</filename>,
804 about. 832 which is a BSP optimized for Nehalem and later
805 For more information on layers, see the 833 Core and Xeon CPUs as well as Silvermont and later
806 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" 834 Atom CPUs, such as the Baytrail SoCs.
807 section in the Yocto Project Development Manual. 835 </para></listitem>
808 For more information on BSP layers, see the 836 <listitem><para>
809 "<link linkend='bsp-layers'>BSP Layers</link>" 837 <filename>intel-quark</filename>,
810 section. 838 which is a BSP optimized for the Intel Galileo
811 <note> 839 gen1 &amp; gen2 development boards.
812 <para> 840 </para></listitem>
813 Five BSPs exist that are part of the Yocto Project release: 841 </itemizedlist></para>
814 <filename>beaglebone</filename> (ARM), 842 </note></para>
815 <filename>mpc8315e</filename> (PowerPC),
816 and <filename>edgerouter</filename> (MIPS).
817 The recipes and configurations for these five BSPs
818 are located and dispersed within the
819 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
820 </para>
821
822 <para>
823 Three core Intel BSPs exist as part of the Yocto
824 Project release in the
825 <filename>meta-intel</filename> layer:
826 <itemizedlist>
827 <listitem><para><filename>intel-core2-32</filename>,
828 which is a BSP optimized for the Core2 family of CPUs
829 as well as all CPUs prior to the Silvermont core.
830 </para></listitem>
831 <listitem><para><filename>intel-corei7-64</filename>,
832 which is a BSP optimized for Nehalem and later
833 Core and Xeon CPUs as well as Silvermont and later
834 Atom CPUs, such as the Baytrail SoCs.
835 </para></listitem>
836 <listitem><para><filename>intel-quark</filename>,
837 which is a BSP optimized for the Intel Galileo
838 gen1 &amp; gen2 development boards.
839 </para></listitem>
840 </itemizedlist>
841 </para>
842 </note>
843 </para>
844 843
845 <para>When you set up a layer for a new BSP, you should follow a standard layout. 844 <para>When you set up a layer for a new BSP, you should
845 follow a standard layout.
846 This layout is described in the 846 This layout is described in the
847 "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>" 847 "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
848 section. 848 section.
849 In the standard layout, you will notice a suggested structure for recipes and 849 In the standard layout, you will notice a suggested
850 configuration information. 850 structure for recipes and configuration information.
851 You can see the standard layout for a BSP by examining 851 You can see the standard layout for a BSP by examining
852 any supported BSP found in the <filename>meta-intel</filename> layer inside 852 any supported BSP found in the
853 the Source Directory.</para></listitem> 853 <filename>meta-intel</filename> layer inside the Source
854 <listitem><para><emphasis>Make configuration changes to your new BSP 854 Directory.
855 layer</emphasis>: The standard BSP layer structure organizes the files you need 855 </para></listitem>
856 to edit in <filename>conf</filename> and several <filename>recipes-*</filename> 856 <listitem><para>
857 <emphasis>Make Configuration Changes to Your New BSP
858 Layer:</emphasis>
859 The standard BSP layer structure organizes the files
860 you need to edit in <filename>conf</filename> and
861 several <filename>recipes-*</filename>
857 directories within the BSP layer. 862 directories within the BSP layer.
858 Configuration changes identify where your new layer is on the local system 863 Configuration changes identify where your new layer
859 and identify which kernel you are going to use. 864 is on the local system and identify which kernel you
860 When you run the <filename>yocto-bsp</filename> script, you are able to interactively 865 are going to use.
861 configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). 866 When you run the <filename>yocto-bsp</filename> script,
867 you are able to interactively configure many things for
868 the BSP (e.g. keyboard, touchscreen, and so forth).
862 </para></listitem> 869 </para></listitem>
863 <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe 870 <listitem><para>
864 changes include altering recipes (<filename>.bb</filename> files), removing 871 <emphasis>Make Recipe Changes to Your New BSP
865 recipes you do not use, and adding new recipes or append files 872 Layer:</emphasis>
866 (<filename>.bbappend</filename>) that you need to support your hardware. 873 Recipe changes include altering recipes
874 (<filename>.bb</filename> files), removing recipes you
875 do not use, and adding new recipes or append files
876 (<filename>.bbappend</filename>) that you need to
877 support your hardware.
867 </para></listitem> 878 </para></listitem>
868 <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the 879 <listitem><para>
869 changes to your BSP layer, there remains a few things 880 <emphasis>Prepare for the Build:</emphasis>
870 you need to do for the OpenEmbedded build system in order for it to create your image. 881 Once you have made all the changes to your BSP layer,
871 You need to get the build environment ready by sourcing an environment setup script 882 there remains a few things you need to do for the
883 OpenEmbedded build system in order for it to create
884 your image.
885 You need to get the build environment ready by
886 sourcing an environment setup script
872 (i.e. <filename>oe-init-build-env</filename> or 887 (i.e. <filename>oe-init-build-env</filename> or
873 <filename>oe-init-build-env-memres</filename>) 888 <filename>oe-init-build-env-memres</filename>)
874 and you need to be sure two key configuration files are configured appropriately: 889 and you need to be sure two key configuration
875 the <filename>conf/local.conf</filename> and the 890 files are configured appropriately: the
891 <filename>conf/local.conf</filename> and the
876 <filename>conf/bblayers.conf</filename> file. 892 <filename>conf/bblayers.conf</filename> file.
877 You must make the OpenEmbedded build system aware of your new layer. 893 You must make the OpenEmbedded build system aware
894 of your new layer.
878 See the 895 See the
879 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>" 896 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
880 section in the Yocto Project Development Manual 897 section in the Yocto Project Development Manual
881 for information on how to let the build system know about your new layer.</para> 898 for information on how to let the build system
882 <para>The entire process for building an image is overviewed in the section 899 know about your new layer.</para>
900
901 <para>The entire process for building an image is
902 overviewed in the section
883 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section 903 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section
884 of the Yocto Project Quick Start. 904 of the Yocto Project Quick Start.
885 You might want to reference this information.</para></listitem> 905 You might want to reference this information.
886 <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system 906 </para></listitem>
887 uses the BitBake tool to build images based on the type of image you want to create. 907 <listitem><para>
908 <emphasis>Build the Image:</emphasis>
909 The OpenEmbedded build system uses the BitBake tool
910 to build images based on the type of image you want to
911 create.
888 You can find more information about BitBake in the 912 You can find more information about BitBake in the
889 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. 913 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
890 </para> 914 </para>
891 <para>The build process supports several types of images to satisfy different needs. 915
916 <para>The build process supports several types of
917 images to satisfy different needs.
892 See the 918 See the
893 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter 919 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
894 in the Yocto Project Reference Manual for information on 920 chapter in the Yocto Project Reference Manual for
895 supported images.</para></listitem> 921 information on supported images.
922 </para></listitem>
896 </orderedlist> 923 </orderedlist>
897 </para> 924 </para>
898 </section> 925 </section>