summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-03-21 09:04:24 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-03-25 09:41:13 +0100
commitce8c96481ea6aa3a391ac2936af6a472d903c4b4 (patch)
tree10558921370471d155d1378d20ab345eba1f9b92 /documentation
parentdcde1a9e336b0b52aa76c1c5a7a71f97f8c3e1e1 (diff)
downloadpoky-ce8c96481ea6aa3a391ac2936af6a472d903c4b4.tar.gz
bsp-guide: Updated BSP terminolgy and BBLAYERS ordering
Fixed the way we refer to a BSP name. It is really "meta-<bsp_root_name>" rather than "meta-<bsp_name>". The name is the whole string and not just the root name. Also added a tip on ordering the layers in the BBLAYERS variable in the bblayers.conf file. Order is important. (From yocto-docs rev: 9c56238295f5631c496377616ea98b860253e6f7) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/bsp-guide/bsp.xml110
1 files changed, 61 insertions, 49 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 787dc7bff1..f9455ed861 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -38,10 +38,10 @@
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'>
41 meta-<replaceable>bsp_name</replaceable> 41 meta-<replaceable>bsp_root_name</replaceable>
42 </literallayout> 42 </literallayout>
43 The string "meta-" is prepended to the machine or platform name, which is 43 The string "meta-" is prepended to the machine or platform name, which is
44 <replaceable>bsp_name</replaceable> in the above form. 44 <replaceable>bsp_root_name</replaceable> in the above form.
45 <note><title>Tip</title> 45 <note><title>Tip</title>
46 Because the BSP layer naming convention is well-established, 46 Because the BSP layer naming convention is well-established,
47 it is advisable to follow it when creating layers. 47 it is advisable to follow it when creating layers.
@@ -99,16 +99,16 @@
99 99
100 <para> 100 <para>
101 The layer's base directory 101 The layer's base directory
102 (<filename>meta-<replaceable>bsp_name</replaceable></filename>) 102 (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>)
103 is the root of the BSP Layer. 103 is the root directory of the BSP Layer.
104 This root is what you add to the 104 This directory is what you add to the
105 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> 105 <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 106 variable in the <filename>conf/bblayers.conf</filename> file found in the
107 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, 107 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
108 which is established after you run the OpenEmbedded build environment 108 which is established after you run the OpenEmbedded build environment
109 setup script (i.e. 109 setup script (i.e.
110 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). 110 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
111 Adding the root allows the 111 Adding the root directory allows the
112 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> 112 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
113 to recognize the BSP layer and from it build an image. 113 to recognize the BSP layer and from it build an image.
114 Here is an example: 114 Here is an example:
@@ -120,22 +120,34 @@
120 /usr/local/src/yocto/meta-mylayer \ 120 /usr/local/src/yocto/meta-mylayer \
121 " 121 "
122 </literallayout> 122 </literallayout>
123 <note><title>Tip</title>
124 Ordering and
125 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
126 for the layers listed in <filename>BBLAYERS</filename>
127 matter.
128 For example, if multiple layers define a machine
129 configuration, the OpenEmbedded build system uses
130 the last layer searched given similar layer
131 priorities.
132 The build system works from the top-down through
133 the layers listed in <filename>BBLAYERS</filename>.
134 </note>
123 </para> 135 </para>
124 136
125 <para> 137 <para>
126 Some BSPs require additional layers on 138 Some BSPs require or depend on additional layers
127 top of the BSP's root layer in order to be functional. 139 beyond the BSP's root layer in order to be functional.
128 For these cases, you also need to add those layers to the 140 In this case, you need to specify these layers in the
129 <filename>BBLAYERS</filename> variable in order to build the BSP. 141 <filename>README</filename> "Dependencies" section of the
130 You must also specify in the "Dependencies" section of the BSP's 142 BSP's root layer.
131 <filename>README</filename> file any requirements for additional 143 Additionally, if any build instructions exist for the
132 layers and, preferably, any 144 BSP, you must add them to the "Dependencies" section.
133 build instructions that might be contained elsewhere
134 in the <filename>README</filename> file.
135 </para> 145 </para>
136 146
137 <para> 147 <para>
138 Some layers function as a layer to hold other BSP layers. 148 Some layers function as a layer to hold other BSP layers.
149 These layers are knows as
150 "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>".
139 An example of this type of layer is the 151 An example of this type of layer is the
140 <filename>meta-intel</filename> layer. 152 <filename>meta-intel</filename> layer.
141 This layer contains BSP layers for the Intel-core2-32 153 This layer contains BSP layers for the Intel-core2-32
@@ -365,17 +377,17 @@
365 realize that the actual file structures for specific 377 realize that the actual file structures for specific
366 BSPs could differ. 378 BSPs could differ.
367 <literallayout class='monospaced'> 379 <literallayout class='monospaced'>
368 meta-<replaceable>bsp_name</replaceable>/ 380 meta-<replaceable>bsp_root_name</replaceable>/
369 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> 381 meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
370 meta-<replaceable>bsp_name</replaceable>/README 382 meta-<replaceable>bsp_root_name</replaceable>/README
371 meta-<replaceable>bsp_name</replaceable>/README.sources 383 meta-<replaceable>bsp_root_name</replaceable>/README.sources
372 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> 384 meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
373 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf 385 meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
374 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf 386 meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
375 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* 387 meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
376 meta-<replaceable>bsp_name</replaceable>/recipes-core/* 388 meta-<replaceable>bsp_root_name</replaceable>/recipes-core/*
377 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* 389 meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
378 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend 390 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
379 </literallayout> 391 </literallayout>
380 </para> 392 </para>
381 393
@@ -551,7 +563,7 @@
551 <para> 563 <para>
552 You can find these files in the BSP Layer at: 564 You can find these files in the BSP Layer at:
553 <literallayout class='monospaced'> 565 <literallayout class='monospaced'>
554 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> 566 meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
555 </literallayout> 567 </literallayout>
556 </para> 568 </para>
557 569
@@ -583,7 +595,7 @@
583 <para> 595 <para>
584 You can find this file in the BSP Layer at: 596 You can find this file in the BSP Layer at:
585 <literallayout class='monospaced'> 597 <literallayout class='monospaced'>
586 meta-<replaceable>bsp_name</replaceable>/README 598 meta-<replaceable>bsp_root_name</replaceable>/README
587 </literallayout> 599 </literallayout>
588 </para> 600 </para>
589 601
@@ -609,7 +621,7 @@
609 <para> 621 <para>
610 You can find this file in the BSP Layer at: 622 You can find this file in the BSP Layer at:
611 <literallayout class='monospaced'> 623 <literallayout class='monospaced'>
612 meta-<replaceable>bsp_name</replaceable>/README.sources 624 meta-<replaceable>bsp_root_name</replaceable>/README.sources
613 </literallayout> 625 </literallayout>
614 </para> 626 </para>
615 627
@@ -617,7 +629,7 @@
617 This file provides information on where to locate the BSP 629 This file provides information on where to locate the BSP
618 source files used to build the images (if any) that 630 source files used to build the images (if any) that
619 reside in 631 reside in
620 <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. 632 <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>.
621 Images in the <filename>binary</filename> would be images 633 Images in the <filename>binary</filename> would be images
622 released with the BSP. 634 released with the BSP.
623 The information in the <filename>README.sources</filename> 635 The information in the <filename>README.sources</filename>
@@ -639,7 +651,7 @@
639 <para> 651 <para>
640 You can find these files in the BSP Layer at: 652 You can find these files in the BSP Layer at:
641 <literallayout class='monospaced'> 653 <literallayout class='monospaced'>
642 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> 654 meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
643 </literallayout> 655 </literallayout>
644 </para> 656 </para>
645 657
@@ -677,7 +689,7 @@
677 <para> 689 <para>
678 You can find this file in the BSP Layer at: 690 You can find this file in the BSP Layer at:
679 <literallayout class='monospaced'> 691 <literallayout class='monospaced'>
680 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf 692 meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
681 </literallayout> 693 </literallayout>
682 </para> 694 </para>
683 695
@@ -692,7 +704,7 @@
692 In the following example, you would replace 704 In the following example, you would replace
693 <replaceable>bsp</replaceable> with the actual 705 <replaceable>bsp</replaceable> with the actual
694 name of the BSP (i.e. 706 name of the BSP (i.e.
695 <replaceable>bsp_name</replaceable> from the example 707 <replaceable>bsp_root_name</replaceable> from the example
696 template). 708 template).
697 </para> 709 </para>
698 710
@@ -752,7 +764,7 @@
752 <para> 764 <para>
753 You can find these files in the BSP Layer at: 765 You can find these files in the BSP Layer at:
754 <literallayout class='monospaced'> 766 <literallayout class='monospaced'>
755 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf 767 meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
756 </literallayout> 768 </literallayout>
757 </para> 769 </para>
758 770
@@ -819,7 +831,7 @@
819 <para> 831 <para>
820 You can find these files in the BSP Layer at: 832 You can find these files in the BSP Layer at:
821 <literallayout class='monospaced'> 833 <literallayout class='monospaced'>
822 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* 834 meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
823 </literallayout> 835 </literallayout>
824 </para> 836 </para>
825 837
@@ -864,7 +876,7 @@
864 <para> 876 <para>
865 You can find these files in the BSP Layer at: 877 You can find these files in the BSP Layer at:
866 <literallayout class='monospaced'> 878 <literallayout class='monospaced'>
867 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* 879 meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
868 </literallayout> 880 </literallayout>
869 </para> 881 </para>
870 882
@@ -883,8 +895,8 @@
883 <para> 895 <para>
884 You can find these files in the BSP Layer at: 896 You can find these files in the BSP Layer at:
885 <literallayout class='monospaced'> 897 <literallayout class='monospaced'>
886 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux*.bbappend 898 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend
887 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/*.bb 899 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb
888 </literallayout> 900 </literallayout>
889 </para> 901 </para>
890 902
@@ -907,7 +919,7 @@
907 kernel recipe by using a similarly named append 919 kernel recipe by using a similarly named append
908 file, which is located in the BSP Layer for your 920 file, which is located in the BSP Layer for your
909 target device (e.g. the 921 target device (e.g. the
910 <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). 922 <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory).
911 </para> 923 </para>
912 924
913 <para> 925 <para>
@@ -915,7 +927,7 @@
915 <filename>linux-yocto_4.4.bb</filename> recipe to 927 <filename>linux-yocto_4.4.bb</filename> recipe to
916 build the kernel. 928 build the kernel.
917 In other words, you have selected the kernel in your 929 In other words, you have selected the kernel in your
918 <replaceable>bsp_name</replaceable><filename>.conf</filename> 930 <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
919 file by adding 931 file by adding
920 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> 932 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
921 and 933 and
@@ -930,7 +942,7 @@
930 default, the 942 default, the
931 <filename>PREFERRED_PROVIDER</filename> 943 <filename>PREFERRED_PROVIDER</filename>
932 statement does not appear in the 944 statement does not appear in the
933 <replaceable>bsp_name</replaceable><filename>.conf</filename> file. 945 <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file.
934 </note> 946 </note>
935 You would use the 947 You would use the
936 <filename>linux-yocto_4.4.bbappend</filename> 948 <filename>linux-yocto_4.4.bbappend</filename>
@@ -1308,7 +1320,7 @@
1308 <listitem><para> 1320 <listitem><para>
1309 <emphasis>License File:</emphasis> 1321 <emphasis>License File:</emphasis>
1310 You must include a license file in the 1322 You must include a license file in the
1311 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1323 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1312 directory. 1324 directory.
1313 This license covers the BSP Metadata as a whole. 1325 This license covers the BSP Metadata as a whole.
1314 You must specify which license to use since no 1326 You must specify which license to use since no
@@ -1323,7 +1335,7 @@
1323 <emphasis>README File:</emphasis> 1335 <emphasis>README File:</emphasis>
1324 You must include a <filename>README</filename> 1336 You must include a <filename>README</filename>
1325 file in the 1337 file in the
1326 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1338 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1327 directory. 1339 directory.
1328 See the 1340 See the
1329 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink> 1341 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
@@ -1394,7 +1406,7 @@
1394 <filename>binary</filename> directory, you must 1406 <filename>binary</filename> directory, you must
1395 include a <filename>README.sources</filename> 1407 include a <filename>README.sources</filename>
1396 file in the 1408 file in the
1397 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1409 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1398 directory. 1410 directory.
1399 This file specifies exactly where you can find 1411 This file specifies exactly where you can find
1400 the sources used to generate the binary images. 1412 the sources used to generate the binary images.
@@ -1404,18 +1416,18 @@
1404 You must include a 1416 You must include a
1405 <filename>conf/layer.conf</filename> file in 1417 <filename>conf/layer.conf</filename> file in
1406 the 1418 the
1407 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1419 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1408 directory. 1420 directory.
1409 This file identifies the 1421 This file identifies the
1410 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1422 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1411 BSP layer as a layer to the build system. 1423 BSP layer as a layer to the build system.
1412 </para></listitem> 1424 </para></listitem>
1413 <listitem><para> 1425 <listitem><para>
1414 <emphasis>Machine Configuration File:</emphasis> 1426 <emphasis>Machine Configuration File:</emphasis>
1415 You must include one or more 1427 You must include one or more
1416 <filename>conf/machine/</filename><replaceable>bsp_name</replaceable><filename>.conf</filename> 1428 <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1417 files in the 1429 files in the
1418 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1430 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1419 directory. 1431 directory.
1420 These configuration files define machine targets 1432 These configuration files define machine targets
1421 that can be built using the BSP layer. 1433 that can be built using the BSP layer.
@@ -1475,7 +1487,7 @@
1475 within a 1487 within a
1476 <filename>binary/</filename> subdirectory located 1488 <filename>binary/</filename> subdirectory located
1477 in the 1489 in the
1478 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1490 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1479 directory. 1491 directory.
1480 <note> 1492 <note>
1481 If you do include a bootable image as part 1493 If you do include a bootable image as part