summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-06-05 10:03:06 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-06-15 17:18:25 +0100
commit4969df1279080c6596e3ca830bb683bbbbb37f96 (patch)
tree2f00dc935204e1f375d01b1e2a0ce160de692ca4 /documentation/bsp-guide
parentc29a721a68e3ce0d1cd9ed8c4ecdb9b32ccd82fb (diff)
downloadpoky-4969df1279080c6596e3ca830bb683bbbbb37f96.tar.gz
documentation/bsp-guide/bsp.xml: BSP recommendations section added
Added the "Requirements and Recommendations for Released BSPs" section. This section was requested by Dave Stewart based on community input for direction on how to create a BSP that was compliant with the Yocto Project. The input for the section came from Tom Zanussi. A spell-check was performed also prior to this commit that addressed a few spelling issues across the file. (From yocto-docs rev: 7ed0dd1093b33491231dec06f7b5f8e76004130d) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/bsp-guide')
-rw-r--r--documentation/bsp-guide/bsp.xml206
1 files changed, 201 insertions, 5 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index a2453326d9..1b5f0f5b2a 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -75,7 +75,7 @@
75 75
76 <para> 76 <para>
77 Some layers function as a layer to hold other BSP layers. 77 Some layers function as a layer to hold other BSP layers.
78 An example of this type of layers is the <filename>meta-intel</filename> layer. 78 An example of this type of layer is the <filename>meta-intel</filename> layer.
79 The <filename>meta-intel</filename> layer contains over 10 individual BSP layers. 79 The <filename>meta-intel</filename> layer contains over 10 individual BSP layers.
80 </para> 80 </para>
81 81
@@ -122,6 +122,15 @@
122 </para> 122 </para>
123 123
124 <para> 124 <para>
125 Before looking at the common form for the file structure inside a BSP Layer,
126 you should be aware that some requirements do exist in order for a BSP to
127 be considered compliant with the Yocto Project.
128 For that list of requirements, see the
129 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
130 section.
131 </para>
132
133 <para>
125 Below is the common form for the file structure inside a BSP Layer. 134 Below is the common form for the file structure inside a BSP Layer.
126 While you can use this basic form for the standard, realize that the actual structures 135 While you can use this basic form for the standard, realize that the actual structures
127 for specific BSPs could differ. 136 for specific BSPs could differ.
@@ -644,6 +653,193 @@
644 </section> 653 </section>
645 </section> 654 </section>
646 655
656 <section id='requirements-and-recommendations-for-released-bsps'>
657 <title>Requirements and Recommendations for Released BSPs</title>
658
659 <para>
660 Certain requirements exist for a released BSP to be considered
661 compliant with the Yocto Project.
662 Additionally, a single recommendation also exists.
663 This section describes the requirements and recommendation for
664 released BSPs.
665 </para>
666
667 <section id='released-bsp-requirements'>
668 <title>Released BSP Requirements</title>
669
670 <para>
671 Before looking at BSP requirements, you should consider the following:
672 <itemizedlist>
673 <listitem><para>The requirements here assume the base Yocto Project requirements
674 for the BSP layer are already met.
675 For example, requirements for working with the
676 <filename>oe-core</filename> and standard toolchain layers.</para></listitem>
677 <listitem><para>The requirements in this section apply regardless of how you
678 ultimately package a BSP.
679 You should consult the packaging and distribution guidelines for your
680 specific release process.
681 For an example of packaging and distribution requirements, see the
682 <ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third
683 Party BSP Release Process</ulink> wiki page.</para></listitem>
684 <listitem><para>The requirements for the BSP as it is made available to a developer
685 are completely independent of the released form of the BSP.
686 For example, the BSP metadata can be contained within a Git repository
687 and could have a directory structure completely different from what appears
688 in the officially released BSP layer.</para></listitem>
689 <listitem><para>No requirement stipulates that specific packages or package
690 modifications exist in the BSP layer, beyond the requirements for general
691 compliance with the Yocto Project.
692 For example, no requirement exists dictating that a specific kernel or
693 kernel version be used in a given BSP.</para></listitem>
694 </itemizedlist>
695 </para>
696
697 <para>
698 Following are the requirements for a released BSP that conforms to the
699 Yocto Project:
700 <itemizedlist>
701 <listitem><para><emphasis>Layer Name:</emphasis>
702 The BSP must have a layer name that follows the Yocto
703 Project standards.
704 For information on BSP layer names, see the
705 "<link linkend='bsp-layers'>BSP Layers</link>" section.
706 </para></listitem>
707 <listitem><para><emphasis>File System Layout:</emphasis>
708 In general, the filesystem layout for the BSP layer
709 should use the same directory names
710 as listed in <filename>recipes.txt</filename>.
711 You can find <filename>recipes.txt</filename> in the
712 <filename>meta</filename> directory of the
713 <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-files'>Yocto
714 Project Files</ulink>, or in the OpenEmbedded Core Layer
715 (<filename>openembedded-core</filename>) found at
716 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
717 </para>
718 <para>In particular, you should place recipes
719 (<filename>.bb</filename> files) and recipe
720 modifications (<filename>.bbappend</filename> files) into
721 <filename>recipes-*</filename> subdirectories by functional area
722 as outlined in <filename>recipes.txt</filename>.
723 If none of the categories fits a particular recipe, you can
724 make up your own <filename>recipe-*</filename> subdirectory.</para>
725 <para>Within any particular <filename>recipes-*</filename> category, the layout
726 should match what is found in the OpenEmbedded Core
727 Git repository (<filename>openembedded-core</filename>)
728 or the Yocto Project Files (<filename>poky</filename>).
729 In other words, make sure you place related files in appropriately
730 related <filename>recipes-*</filename> subdirectories specific to the
731 recipe's function, or within a subdirectory containing a set of closely-related
732 recipes.
733 The recipes themselves should follow the general guidelines
734 for recipes used in the Yocto Project found in the
735 <ulink url='https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide'>Yocto
736 Recipe and Patch Style Guide</ulink>.</para></listitem>
737 <listitem><para><emphasis>License File:</emphasis>
738 You must include a license file in the
739 <filename>meta-&lt;bsp_name&gt;</filename> directory.
740 This license covers the BSP metadata as a whole.
741 You must specify which license to use since there is no
742 default license if one is not specified.</para></listitem>
743 <listitem><para><emphasis>README File:</emphasis>
744 You must include a <filename>README</filename> file in the
745 <filename>meta-&lt;bsp_name&gt;</filename> directory.
746 At a minimum, the <filename>README</filename> file should
747 contain the following:
748 <itemizedlist>
749 <listitem><para>A brief description about the hardware the BSP
750 targets.</para></listitem>
751 <listitem><para>A list of all the dependencies a
752 on which a BSP layer depends.
753 These dependencies are typically a list of required layers needed
754 to build the BSP.
755 However, the dependencies should also contain information regarding
756 any other dependencies the BSP might have.</para></listitem>
757 <listitem><para>Any required special licensing information.
758 For example, this information includes information on
759 special variables needed to satisfy a EULA,
760 or instructions on information needed to build or distribute
761 binaries built from the BSP metadata.</para></listitem>
762 <listitem><para>The name and contact information for the
763 BSP layer maintainer.
764 This is the person to whom patches and questions should
765 be sent.</para></listitem>
766 <listitem><para>Instructions on how to build the BSP using the BSP
767 layer.</para></listitem>
768 <listitem><para>Instructions on how to boot the BSP build from
769 the BSP layer.</para></listitem>
770 <listitem><para>Instructions on how to boot the binary images
771 contained in the <filename>/binary</filename> directory,
772 if present.</para></listitem>
773 <listitem><para>Information on any known bugs or issues that users
774 should know about when either building or booting the BSP
775 binaries.</para></listitem>
776 </itemizedlist></para></listitem>
777 <listitem><para><emphasis>README.sources File:</emphasis>
778 You must include a <filename>README.sources</filename> in the
779 <filename>meta-&lt;bsp_name&gt;</filename> directory.
780 This file specifies exactly where you can find the sources used to
781 generate the binary images contained in the
782 <filename>/binary</filename> directory, if present.</para></listitem>
783 <listitem><para><emphasis>Layer Configuration File:</emphasis>
784 You must include a <filename>conf/layer.conf</filename> in the
785 <filename>meta-&lt;bsp_name&gt;</filename> directory.
786 This file identifies the <filename>meta-&lt;bsp_name&gt;</filename>
787 BSP layer as a layer to the build system.</para></listitem>
788 <listitem><para><emphasis>Machine Configuration File:</emphasis>
789 You must include a <filename>conf/machine/&lt;bsp_name&gt;.conf</filename>
790 in the <filename>meta-&lt;bsp_name&gt;</filename> directory.
791 This configuration file defines a machine target that can be built
792 using the BSP layer.
793 Multiple machine configuration files define variations of machine
794 configurations that are supported by the BSP.
795 If a BSP supports more multiple machine variations, you need to
796 adequately describe each variation in the BSP
797 <filename>README</filename> file.
798 Do not use multiple machine configuration files to describe disparate
799 hardware.
800 Multiple machine configuration files should describe very similar targets.
801 If you do have very different targets, you should create a separate
802 BSP.
803 <note>It is completely possible for a developer to structure the
804 working repository as a conglomeration of unrelated BSP
805 files, and to possibly generate specifically targeted 'release' BSPs
806 from that directory using scripts or some other mechanism.
807 Such considerations are outside the scope of this document.</note>
808 </para></listitem>
809 </itemizedlist>
810 </para>
811 </section>
812
813 <section id='released-bsp-recommendations'>
814 <title>Released BSP Recommendations</title>
815
816 <para>
817 One recommendation for BSP releases is that they contain
818 one or more bootable images.
819 Including bootable images allows users to easily try out the BSP
820 on their own hardware.
821 </para>
822
823 <para>
824 In some cases, it might not be convenient to include a
825 bootable image.
826 In this case, you might want to make two versions of the
827 BSP available: one that contains binary images, and one
828 that does not.
829 The version that does not contain bootable images avoids
830 unnecessary download times for users not interested in the images.
831 </para>
832
833 <para>
834 If you need to distribute a BSP and include bootable images or build kernel and
835 filesystems meant to allow users to boot the BSP for evaluation
836 purposes, you should put the images and artifacts within a
837 <filename>binary/</filename> subdirectory located in the
838 <filename>meta-&lt;bsp_name&gt;</filename> directory.
839 </para>
840 </section>
841 </section>
842
647 <section id='customizing-a-recipe-for-a-bsp'> 843 <section id='customizing-a-recipe-for-a-bsp'>
648 <title>Customizing a Recipe for a BSP</title> 844 <title>Customizing a Recipe for a BSP</title>
649 845
@@ -760,7 +956,7 @@
760 restart the build to continue where it left off. 956 restart the build to continue where it left off.
761 During the build, the prompt will not appear again 957 During the build, the prompt will not appear again
762 since you have satisfied the requirement.</para> 958 since you have satisfied the requirement.</para>
763 <para>Once the appropriate license flags are whitelisted 959 <para>Once the appropriate license flags are on the white list
764 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you 960 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
765 can build the encumbered image with no change at all 961 can build the encumbered image with no change at all
766 to the normal build process.</para></listitem> 962 to the normal build process.</para></listitem>
@@ -931,7 +1127,7 @@
931 <para> 1127 <para>
932 Now that you know where these two commands reside and how to access information 1128 Now that you know where these two commands reside and how to access information
933 on them, you should find it relatively straightforward to discover the commands 1129 on them, you should find it relatively straightforward to discover the commands
934 necessary to create a BSP and perform basic kernel maintainence on that BSP using 1130 necessary to create a BSP and perform basic kernel maintenance on that BSP using
935 the tools. 1131 the tools.
936 The next sections provide a concrete starting point to expand on a few points that 1132 The next sections provide a concrete starting point to expand on a few points that
937 might not be immediately obvious or that could use further explanation. 1133 might not be immediately obvious or that could use further explanation.
@@ -990,7 +1186,7 @@
990 In every other way, this architecture is representative of how creating a BSP for 1186 In every other way, this architecture is representative of how creating a BSP for
991 a 'real' machine would work. 1187 a 'real' machine would work.
992 The reason the example uses this architecture is because it is an emulated architecture 1188 The reason the example uses this architecture is because it is an emulated architecture
993 and can easily be followed without requireing actual hardware. 1189 and can easily be followed without requiring actual hardware.
994 </para> 1190 </para>
995 1191
996 <para> 1192 <para>
@@ -1059,7 +1255,7 @@
1059 If you enter 'n', the script prompts you to further enter the kernel 1255 If you enter 'n', the script prompts you to further enter the kernel
1060 you do want to use (e.g. 3.0, 3.2_preempt-rt, etc.).</para></listitem> 1256 you do want to use (e.g. 3.0, 3.2_preempt-rt, etc.).</para></listitem>
1061 <listitem><para>Next, the script asks whether you would like to have a new 1257 <listitem><para>Next, the script asks whether you would like to have a new
1062 branch created especially for your BSPin the local 1258 branch created especially for your BSP in the local
1063 <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink> 1259 <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink>
1064 Git repository . 1260 Git repository .
1065 If not, then the script re-uses an existing branch.</para> 1261 If not, then the script re-uses an existing branch.</para>