summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/bsp-guide')
-rw-r--r--documentation/bsp-guide/bsp.xml89
1 files changed, 52 insertions, 37 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index e76dd57e77..96c0455f67 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -19,7 +19,7 @@
19</para> 19</para>
20 20
21<para> 21<para>
22 This guide presents information about BSP Layers, defines a structure for components 22 This guide presents information about BSP layers, defines a structure for components
23 so that BSPs follow a commonly understood layout, discusses how to customize 23 so that BSPs follow a commonly understood layout, discusses how to customize
24 a recipe for a BSP, addresses BSP licensing, and provides information that 24 a recipe for a BSP, addresses BSP licensing, and provides information that
25 shows you how to create a 25 shows you how to create a
@@ -34,7 +34,7 @@
34 <para> 34 <para>
35 A BSP consists of a file structure inside a base directory. 35 A BSP consists of a file structure inside a base directory.
36 Collectively, you can think of the base directory, its file structure, 36 Collectively, you can think of the base directory, its file structure,
37 and the contents as a BSP Layer. 37 and the contents as a <firstterm>BSP layer</firstterm>.
38 Although not a strict requirement, BSP layers in the Yocto Project 38 Although not a strict requirement, BSP layers in the Yocto Project
39 use the following well-established naming convention: 39 use the following well-established naming convention:
40 <literallayout class='monospaced'> 40 <literallayout class='monospaced'>
@@ -69,9 +69,9 @@
69 Each repository is a BSP layer supported by the Yocto Project 69 Each repository is a BSP layer supported by the Yocto Project
70 (e.g. <filename>meta-raspberrypi</filename> and 70 (e.g. <filename>meta-raspberrypi</filename> and
71 <filename>meta-intel</filename>). 71 <filename>meta-intel</filename>).
72 Each of these layers is a repository unto itself and clicking on a 72 Each of these layers is a repository unto itself and clicking on
73 layer reveals information that includes two links from which you can choose 73 the layer name displays two URLs from which you can
74 to set up a clone of the layer's repository on your local host system. 74 clone the layer's repository to your local system.
75 Here is an example that clones the Raspberry Pi BSP layer: 75 Here is an example that clones the Raspberry Pi BSP layer:
76 <literallayout class='monospaced'> 76 <literallayout class='monospaced'>
77 $ git clone git://git.yoctoproject.org/meta-raspberrypi 77 $ git clone git://git.yoctoproject.org/meta-raspberrypi
@@ -83,12 +83,13 @@
83 <filename>meta-yocto-bsp</filename> layer is part of the 83 <filename>meta-yocto-bsp</filename> layer is part of the
84 shipped <filename>poky</filename> repository. 84 shipped <filename>poky</filename> repository.
85 The <filename>meta-yocto-bsp</filename> layer maintains several 85 The <filename>meta-yocto-bsp</filename> layer maintains several
86 BSPs such as the Beaglebone, EdgeRouter, and generic versions of 86 "reference" BSPs including the ARM-based Beaglebone, MIPS-based
87 EdgeRouter, and generic versions of
87 both 32-bit and 64-bit IA machines. 88 both 32-bit and 64-bit IA machines.
88 </para> 89 </para>
89 90
90 <para> 91 <para>
91 For information on the BSP development workflow, see the 92 For information on typical BSP development workflow, see the
92 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>" 93 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
93 section. 94 section.
94 For more information on how to set up a local copy of source files 95 For more information on how to set up a local copy of source files
@@ -98,12 +99,12 @@
98 </para> 99 </para>
99 100
100 <para> 101 <para>
101 The layer's base directory 102 The BSP layer's base directory
102 (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>) 103 (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>)
103 is the root directory of the BSP Layer. 104 is the root directory of that Layer.
104 This directory is what you add to the 105 This directory is what you add to the
105 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> 106 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
106 variable in the <filename>conf/bblayers.conf</filename> file found in the 107 variable in the <filename>conf/bblayers.conf</filename> file found in your
107 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, 108 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
108 which is established after you run the OpenEmbedded build environment 109 which is established after you run the OpenEmbedded build environment
109 setup script (i.e. 110 setup script (i.e.
@@ -153,6 +154,20 @@
153 layer. 154 layer.
154 The <filename>meta-openembedded</filename> layer contains 155 The <filename>meta-openembedded</filename> layer contains
155 many <filename>meta-*</filename> layers. 156 many <filename>meta-*</filename> layers.
157 In cases like this, you need to include the names of the actual
158 layers you want to work with, such as:
159 <literallayout class='monospaced'>
160 BBLAYERS ?= " \
161 /usr/local/src/yocto/meta \
162 /usr/local/src/yocto/meta-poky \
163 /usr/local/src/yocto/meta-yocto-bsp \
164 /usr/local/src/yocto/meta-mylayer \
165 .../meta-openembedded/meta-oe \
166 .../meta-openembedded/meta-perl \
167 .../meta-openembedded/meta-networking \
168 "
169 </literallayout>
170 and so on.
156 </para> 171 </para>
157 172
158 <para> 173 <para>
@@ -351,25 +366,24 @@
351 layer combined with a build system and other tools. 366 layer combined with a build system and other tools.
352 Realize that it is important to maintain the distinction 367 Realize that it is important to maintain the distinction
353 that the BSP layer, a build system, and tools are 368 that the BSP layer, a build system, and tools are
354 separate components that could to be combined in 369 separate components that could be combined in
355 certain end products. 370 certain end products.
356 </para> 371 </para>
357 372
358 <para> 373 <para>
359 Before looking at the common form for the file structure 374 Before looking at the recommended form for the directory structure
360 inside a BSP Layer, you should be aware that some 375 inside a BSP layer, you should be aware that some
361 requirements do exist in order for a BSP layer to 376 requirements do exist in order for a BSP layer to
362 be considered compliant with the Yocto Project. 377 be considered <firstterm>compliant</firstterm> with the Yocto Project.
363 For that list of requirements, see the 378 For that list of requirements, see the
364 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>" 379 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
365 section. 380 section.
366 </para> 381 </para>
367 382
368 <para> 383 <para>
369 Below is the common form for the file structure 384 Below is the typical directory structure for a BSP layer.
370 inside a BSP Layer.
371 While this basic form represents the standard, 385 While this basic form represents the standard,
372 realize that the actual file structures for specific 386 realize that the actual layout for individual
373 BSPs could differ. 387 BSPs could differ.
374 <literallayout class='monospaced'> 388 <literallayout class='monospaced'>
375 meta-<replaceable>bsp_root_name</replaceable>/ 389 meta-<replaceable>bsp_root_name</replaceable>/
@@ -567,7 +581,7 @@
567 for the BSP. 581 for the BSP.
568 The type or types of files here can vary depending 582 The type or types of files here can vary depending
569 on the licensing requirements. 583 on the licensing requirements.
570 For example, in the Raspberry Pi BSP all licensing 584 For example, in the Raspberry Pi BSP, all licensing
571 requirements are handled with the 585 requirements are handled with the
572 <filename>COPYING.MIT</filename> file. 586 <filename>COPYING.MIT</filename> file.
573 </para> 587 </para>
@@ -802,7 +816,7 @@
802 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 816 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
803 For example, many <filename>tune-*</filename> files 817 For example, many <filename>tune-*</filename> files
804 (e.g. <filename>tune-arm1136jf-s.inc</filename>, 818 (e.g. <filename>tune-arm1136jf-s.inc</filename>,
805 <filename>tun-1586-nlp.inc</filename>, and so forth) 819 <filename>tune-1586-nlp.inc</filename>, and so forth)
806 reside in the 820 reside in the
807 <filename>poky/meta/conf/machine/include</filename> 821 <filename>poky/meta/conf/machine/include</filename>
808 directory. 822 directory.
@@ -834,7 +848,7 @@
834 This optional directory contains miscellaneous recipe 848 This optional directory contains miscellaneous recipe
835 files for the BSP. 849 files for the BSP.
836 Most notably would be the formfactor files. 850 Most notably would be the formfactor files.
837 For example, in the Raspberry Pi BSP there is the 851 For example, in the Raspberry Pi BSP, there is the
838 <filename>formfactor_0.0.bbappend</filename> file, 852 <filename>formfactor_0.0.bbappend</filename> file,
839 which is an append file used to augment the recipe 853 which is an append file used to augment the recipe
840 that starts the build. 854 that starts the build.
@@ -901,7 +915,7 @@
901 The <filename>*.bb</filename> files would be a 915 The <filename>*.bb</filename> files would be a
902 developer-supplied kernel recipe. 916 developer-supplied kernel recipe.
903 This area of the BSP hierarchy can contain both these 917 This area of the BSP hierarchy can contain both these
904 types of files, although in practice, it is likely that 918 types of files although, in practice, it is likely that
905 you would have one or the other. 919 you would have one or the other.
906 </para> 920 </para>
907 921
@@ -976,7 +990,7 @@
976 <title>Developing a Board Support Package (BSP)</title> 990 <title>Developing a Board Support Package (BSP)</title>
977 991
978 <para> 992 <para>
979 This section contains the high-level procedure you can 993 This section describes the high-level procedure you can
980 follow to create a BSP. 994 follow to create a BSP.
981 Although not required for BSP creation, the 995 Although not required for BSP creation, the
982 <filename>meta-intel</filename> repository, which 996 <filename>meta-intel</filename> repository, which
@@ -1298,7 +1312,7 @@
1298 (<filename>openembedded-core</filename>) 1312 (<filename>openembedded-core</filename>)
1299 or the Source Directory (<filename>poky</filename>). 1313 or the Source Directory (<filename>poky</filename>).
1300 In other words, make sure you place related 1314 In other words, make sure you place related
1301 files in appropriately related 1315 files in appropriately-related
1302 <filename>recipes-*</filename> subdirectories 1316 <filename>recipes-*</filename> subdirectories
1303 specific to the recipe's function, or within 1317 specific to the recipe's function, or within
1304 a subdirectory containing a set of closely-related 1318 a subdirectory containing a set of closely-related
@@ -1315,7 +1329,7 @@
1315 directory. 1329 directory.
1316 This license covers the BSP Metadata as a whole. 1330 This license covers the BSP Metadata as a whole.
1317 You must specify which license to use since no 1331 You must specify which license to use since no
1318 default license exists when one not specified. 1332 default license exists when one is not specified.
1319 See the 1333 See the
1320 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink> 1334 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
1321 file for the Raspberry Pi BSP in the 1335 file for the Raspberry Pi BSP in the
@@ -1338,12 +1352,10 @@
1338 file should contain the following: 1352 file should contain the following:
1339 <itemizedlist> 1353 <itemizedlist>
1340 <listitem><para> 1354 <listitem><para>
1341 A brief description about the hardware the BSP 1355 A brief description of the target hardware.
1342 targets.
1343 </para></listitem> 1356 </para></listitem>
1344 <listitem><para> 1357 <listitem><para>
1345 A list of all the dependencies 1358 A list of all the dependencies of the BSP.
1346 on which a BSP layer depends.
1347 These dependencies are typically a list 1359 These dependencies are typically a list
1348 of required layers needed to build the 1360 of required layers needed to build the
1349 BSP. 1361 BSP.
@@ -1606,7 +1618,7 @@
1606 <title>BSP Licensing Considerations</title> 1618 <title>BSP Licensing Considerations</title>
1607 1619
1608 <para> 1620 <para>
1609 In some cases, a BSP contains separately licensed 1621 In some cases, a BSP contains separately-licensed
1610 Intellectual Property (IP) for a component or components. 1622 Intellectual Property (IP) for a component or components.
1611 For these cases, you are required to accept the terms 1623 For these cases, you are required to accept the terms
1612 of a commercial or other type of license that requires 1624 of a commercial or other type of license that requires
@@ -1619,7 +1631,7 @@
1619 </para> 1631 </para>
1620 1632
1621 <para> 1633 <para>
1622 You could find that some separately licensed components 1634 You could find that some separately-licensed components
1623 that are essential for normal operation of the system might 1635 that are essential for normal operation of the system might
1624 not have an unencumbered (or free) substitute. 1636 not have an unencumbered (or free) substitute.
1625 Without these essential components, the system would be 1637 Without these essential components, the system would be
@@ -1627,7 +1639,7 @@
1627 Then again, you might find that other licensed components 1639 Then again, you might find that other licensed components
1628 that are simply 'good-to-have' or purely elective do have 1640 that are simply 'good-to-have' or purely elective do have
1629 an unencumbered, free replacement component that you can 1641 an unencumbered, free replacement component that you can
1630 use rather than agreeing to the separately licensed 1642 use rather than agreeing to the separately-licensed
1631 component. 1643 component.
1632 Even for components essential to the system, you might 1644 Even for components essential to the system, you might
1633 find an unencumbered component that is not identical but 1645 find an unencumbered component that is not identical but
@@ -1740,7 +1752,7 @@
1740 <para> 1752 <para>
1741 The <filename>bitbake-layers create-layer</filename> script 1753 The <filename>bitbake-layers create-layer</filename> script
1742 automates creating a BSP layer. 1754 automates creating a BSP layer.
1743 What makes a layer a "BSP layer", is the presence of a machine 1755 What makes a layer a "BSP layer" is the presence of at least one machine
1744 configuration file. 1756 configuration file.
1745 Additionally, a BSP layer usually has a kernel recipe 1757 Additionally, a BSP layer usually has a kernel recipe
1746 or an append file that leverages off an existing kernel recipe. 1758 or an append file that leverages off an existing kernel recipe.
@@ -1864,11 +1876,14 @@
1864 </para> 1876 </para>
1865 1877
1866 <para> 1878 <para>
1867 Machine configuration files exist in the 1879 One or more machine configuration files exist in the
1868 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename> 1880 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
1869 directory of the layer: 1881 directory of the layer:
1870 <literallayout class='monospaced'> 1882 <literallayout class='monospaced'>
1871 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine</replaceable><filename>.conf</filename> 1883 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine1</replaceable><filename>.conf</filename>
1884 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine2</replaceable><filename>.conf</filename>
1885 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine3</replaceable><filename>.conf</filename>
1886 ... more ...
1872 </literallayout> 1887 </literallayout>
1873 For example, the machine configuration file for the 1888 For example, the machine configuration file for the
1874 <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink> 1889 <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
@@ -1919,8 +1934,8 @@
1919 IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" 1934 IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
1920 </literallayout> 1935 </literallayout>
1921 The variables used to configure the machine define 1936 The variables used to configure the machine define
1922 machine-specific properties. 1937 machine-specific properties;
1923 For example, machine-dependent packages, machine 1938 for example, machine-dependent packages, machine
1924 tunings, the type of kernel to build, and 1939 tunings, the type of kernel to build, and
1925 U-Boot configurations. 1940 U-Boot configurations.
1926 </para> 1941 </para>
@@ -1931,7 +1946,7 @@
1931 machine configuration file for the BeagleBone 1946 machine configuration file for the BeagleBone
1932 development boards. 1947 development boards.
1933 Realize that much more can be defined as part of 1948 Realize that much more can be defined as part of
1934 a machines configuration file. 1949 a machine's configuration file.
1935 In general, you can learn about related variables 1950 In general, you can learn about related variables
1936 that this example does not have by locating the 1951 that this example does not have by locating the
1937 variables in the 1952 variables in the