summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/bsp-guide/bsp.rst76
1 files changed, 40 insertions, 36 deletions
diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
index 34206d1597..d0275eea9a 100644
--- a/documentation/bsp-guide/bsp.rst
+++ b/documentation/bsp-guide/bsp.rst
@@ -31,14 +31,14 @@ convention: ::
31 meta-bsp_root_name 31 meta-bsp_root_name
32 32
33The string "meta-" is prepended to the 33The string "meta-" is prepended to the
34machine or platform name, which is bsp_root_name in the above form. 34machine or platform name, which is "bsp_root_name" in the above form.
35 35
36.. note:: 36.. note::
37 37
38 Because the BSP layer naming convention is well-established, it is 38 Because the BSP layer naming convention is well-established, it is
39 advisable to follow it when creating layers. Technically speaking, a 39 advisable to follow it when creating layers. Technically speaking, a
40 BSP layer name does not need to start with 40 BSP layer name does not need to start with ``meta-``.
41 meta-. However, various scripts and tools in the Yocto Project development 41 However, various scripts and tools in the Yocto Project development
42 environment assume this convention. 42 environment assume this convention.
43 43
44To help understand the BSP layer concept, consider the BSPs that the 44To help understand the BSP layer concept, consider the BSPs that the
@@ -81,7 +81,7 @@ directory of that Layer. This directory is what you add to the
81``conf/bblayers.conf`` file found in your 81``conf/bblayers.conf`` file found in your
82:term:`Build Directory`, which is 82:term:`Build Directory`, which is
83established after you run the OpenEmbedded build environment setup 83established after you run the OpenEmbedded build environment setup
84script (i.e. :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\`` ). 84script (i.e. :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\``).
85Adding the root directory allows the :term:`OpenEmbedded Build System` 85Adding the root directory allows the :term:`OpenEmbedded Build System`
86to recognize the BSP 86to recognize the BSP
87layer and from it build an image. Here is an example: :: 87layer and from it build an image. Here is an example: ::
@@ -95,10 +95,11 @@ layer and from it build an image. Here is an example: ::
95 95
96.. note:: 96.. note::
97 97
98 Ordering and ``BBFILE_PRIORITY`` for the layers listed in BBLAYERS matter. For 98 Ordering and :term:`BBFILE_PRIORITY` for the layers listed in ``BBLAYERS``
99 example, if multiple layers define a machine configuration, the OpenEmbedded 99 matter. For example, if multiple layers define a machine configuration, the
100 build system uses the last layer searched given similar layer priorities. The 100 OpenEmbedded build system uses the last layer searched given similar layer
101 build system works from the top-down through the layers listed in ``BBLAYERS``. 101 priorities. The build system works from the top-down through the layers
102 listed in ``BBLAYERS``.
102 103
103Some BSPs require or depend on additional layers beyond the BSP's root 104Some BSPs require or depend on additional layers beyond the BSP's root
104layer in order to be functional. In this case, you need to specify these 105layer in order to be functional. In this case, you need to specify these
@@ -107,7 +108,7 @@ Additionally, if any build instructions exist for the BSP, you must add
107them to the "Dependencies" section. 108them to the "Dependencies" section.
108 109
109Some layers function as a layer to hold other BSP layers. These layers 110Some layers function as a layer to hold other BSP layers. These layers
110are knows as ":term:`container layers <Container Layer>`". An example of 111are known as ":term:`container layers <Container Layer>`". An example of
111this type of layer is OpenEmbedded's 112this type of layer is OpenEmbedded's
112`meta-openembedded <https://github.com/openembedded/meta-openembedded>`__ 113`meta-openembedded <https://github.com/openembedded/meta-openembedded>`__
113layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers. 114layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers.
@@ -141,8 +142,8 @@ section.
141 142
142.. note:: 143.. note::
143 144
144 For structural information on BSPs, see the Example Filesystem Layout 145 For structural information on BSPs, see the
145 section. 146 :ref:`bsp-guide/bsp:example filesystem layout` section.
146 147
147#. *Set Up the Build Environment:* Be sure you are set up to use BitBake 148#. *Set Up the Build Environment:* Be sure you are set up to use BitBake
148 in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" 149 in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`"
@@ -150,10 +151,10 @@ section.
150 to get a build host ready that is either a native Linux machine or a machine 151 to get a build host ready that is either a native Linux machine or a machine
151 that uses CROPS. 152 that uses CROPS.
152 153
153#. *Clone the ``poky`` Repository:* You need to have a local copy of the 154#. *Clone the poky Repository:* You need to have a local copy of the
154 Yocto Project :term:`Source Directory` (i.e. a local 155 Yocto Project :term:`Source Directory` (i.e. a local
155 ``poky`` repository). See the 156 ``poky`` repository). See the
156 "ref:`dev-manual/dev-manual-start:cloning the ``poky`` repository`" and 157 ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" and
157 possibly the 158 possibly the
158 ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" or 159 ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" or
159 ":ref:`dev-manual/dev-manual-start:checking out by tag in poky`" 160 ":ref:`dev-manual/dev-manual-start:checking out by tag in poky`"
@@ -168,7 +169,7 @@ section.
168 BSP layers, you can look at the `index of 169 BSP layers, you can look at the `index of
169 machines <&YOCTO_RELEASE_DL_URL;/machines>`__ for the release. 170 machines <&YOCTO_RELEASE_DL_URL;/machines>`__ for the release.
170 171
171#. *Optionally Clone the ``meta-intel`` BSP Layer:* If your hardware is 172#. *Optionally Clone the meta-intel BSP Layer:* If your hardware is
172 based on current Intel CPUs and devices, you can leverage this BSP 173 based on current Intel CPUs and devices, you can leverage this BSP
173 layer. For details on the ``meta-intel`` BSP layer, see the layer's 174 layer. For details on the ``meta-intel`` BSP layer, see the layer's
174 `README <http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README>`__ 175 `README <http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README>`__
@@ -193,7 +194,7 @@ section.
193 194
194 #. *Check Out the Proper Branch:* The branch you check out for 195 #. *Check Out the Proper Branch:* The branch you check out for
195 ``meta-intel`` must match the same branch you are using for the 196 ``meta-intel`` must match the same branch you are using for the
196 Yocto Project release (e.g. &DISTRO_NAME_NO_CAP;): :: 197 Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``): ::
197 198
198 $ cd meta-intel 199 $ cd meta-intel
199 $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; 200 $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP;
@@ -291,7 +292,9 @@ individual BSPs could differ. ::
291 meta-bsp_root_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend 292 meta-bsp_root_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend
292 293
293Below is an example of the Raspberry Pi BSP layer that is available from 294Below is an example of the Raspberry Pi BSP layer that is available from
294the :yocto_git:`Source Respositories <>`: :: 295the :yocto_git:`Source Respositories <>`:
296
297.. code-block:: none
295 298
296 meta-raspberrypi/COPYING.MIT 299 meta-raspberrypi/COPYING.MIT
297 meta-raspberrypi/README.md 300 meta-raspberrypi/README.md
@@ -544,13 +547,13 @@ The ``conf/layer.conf`` file identifies the file structure as a layer,
544identifies the contents of the layer, and contains information about how 547identifies the contents of the layer, and contains information about how
545the build system should use it. Generally, a standard boilerplate file 548the build system should use it. Generally, a standard boilerplate file
546such as the following works. In the following example, you would replace 549such as the following works. In the following example, you would replace
547bsp with the actual name of the BSP (i.e. bsp_root_name from the example 550"bsp" with the actual name of the BSP (i.e. "bsp_root_name" from the example
548template). :: 551template). ::
549 552
550 # We have a conf and classes directory, add to BBPATH 553 # We have a conf and classes directory, add to BBPATH
551 BBPATH .= ":${LAYERDIR}" 554 BBPATH .= ":${LAYERDIR}"
552 555
553 # We have a recipes directory, add to BBFILES 556 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
554 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ 557 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
555 ${LAYERDIR}/recipes-*/*/*.bbappend" 558 ${LAYERDIR}/recipes-*/*/*.bbappend"
556 559
@@ -694,7 +697,7 @@ located in the BSP Layer for your target device (e.g. the
694 697
695Suppose you are using the ``linux-yocto_4.4.bb`` recipe to build the 698Suppose you are using the ``linux-yocto_4.4.bb`` recipe to build the
696kernel. In other words, you have selected the kernel in your 699kernel. In other words, you have selected the kernel in your
697bsp_root_name\ ``.conf`` file by adding 700``"bsp_root_name".conf`` file by adding
698:term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` 701:term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION`
699statements as follows: :: 702statements as follows: ::
700 703
@@ -704,7 +707,7 @@ statements as follows: ::
704.. note:: 707.. note::
705 708
706 When the preferred provider is assumed by default, the ``PREFERRED_PROVIDER`` 709 When the preferred provider is assumed by default, the ``PREFERRED_PROVIDER``
707 statement does not appear in the ``bsp_root_name`` .conf file. 710 statement does not appear in the ``"bsp_root_name".conf`` file.
708 711
709You would use the ``linux-yocto_4.4.bbappend`` file to append specific 712You would use the ``linux-yocto_4.4.bbappend`` file to append specific
710BSP settings to the kernel, thus configuring the kernel for your 713BSP settings to the kernel, thus configuring the kernel for your
@@ -781,7 +784,7 @@ workflow.
781 784
782 .. note:: 785 .. note::
783 786
784 - Five hardware reference BSPs exist that are part of the Yocto 787 - Four hardware reference BSPs exist that are part of the Yocto
785 Project release and are located in the ``poky/meta-yocto-bsp`` 788 Project release and are located in the ``poky/meta-yocto-bsp``
786 BSP layer: 789 BSP layer:
787 790
@@ -870,8 +873,8 @@ Before looking at BSP requirements, you should consider the following:
870- The requirements in this section apply regardless of how you package 873- The requirements in this section apply regardless of how you package
871 a BSP. You should consult the packaging and distribution guidelines 874 a BSP. You should consult the packaging and distribution guidelines
872 for your specific release process. For an example of packaging and 875 for your specific release process. For an example of packaging and
873 distribution requirements, see the "`Third Party BSP Release 876 distribution requirements, see the ":yocto_wiki:`Third Party BSP Release
874 Process <https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process>`__" 877 Process </wiki/Third_Party_BSP_Release_Process>`"
875 wiki page. 878 wiki page.
876 879
877- The requirements for the BSP as it is made available to a developer 880- The requirements for the BSP as it is made available to a developer
@@ -897,7 +900,7 @@ Yocto Project:
897 your BSP layer as listed in the ``recipes.txt`` file, which is found 900 your BSP layer as listed in the ``recipes.txt`` file, which is found
898 in ``poky/meta`` directory of the :term:`Source Directory` 901 in ``poky/meta`` directory of the :term:`Source Directory`
899 or in the OpenEmbedded-Core Layer (``openembedded-core``) at 902 or in the OpenEmbedded-Core Layer (``openembedded-core``) at
900 http://git.openembedded.org/openembedded-core/tree/meta. 903 https://git.openembedded.org/openembedded-core/tree/meta.
901 904
902 You should place recipes (``*.bb`` files) and recipe modifications 905 You should place recipes (``*.bb`` files) and recipe modifications
903 (``*.bbappend`` files) into ``recipes-*`` subdirectories by 906 (``*.bbappend`` files) into ``recipes-*`` subdirectories by
@@ -1074,7 +1077,7 @@ also supports several other machines:
1074 1077
1075 .. note:: 1078 .. note::
1076 1079
1077 If the meta-xyz layer did not support multiple machines, you would place 1080 If the ``meta-xyz`` layer did not support multiple machines, you would place
1078 the interfaces configuration file in the layer here: :: 1081 the interfaces configuration file in the layer here: ::
1079 1082
1080 meta-xyz/recipes-core/init-ifupdown/files/interfaces 1083 meta-xyz/recipes-core/init-ifupdown/files/interfaces
@@ -1233,7 +1236,7 @@ file. In this example, the ``conf/layer.conf`` is the following: ::
1233 # We have a conf and classes directory, add to BBPATH 1236 # We have a conf and classes directory, add to BBPATH
1234 BBPATH .= ":${LAYERDIR}" 1237 BBPATH .= ":${LAYERDIR}"
1235 1238
1236 # We have recipes-\* directories, add to BBFILES 1239 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
1237 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ 1240 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1238 ${LAYERDIR}/recipes-*/*/*.bbappend" 1241 ${LAYERDIR}/recipes-*/*/*.bbappend"
1239 1242
@@ -1262,13 +1265,13 @@ general or kernel layer.
1262One or more machine configuration files exist in the 1265One or more machine configuration files exist in the
1263``bsp_layer/conf/machine/`` directory of the layer: :: 1266``bsp_layer/conf/machine/`` directory of the layer: ::
1264 1267
1265 bsp_layer/conf/machine/machine1\.conf`` 1268 bsp_layer/conf/machine/machine1\.conf
1266 bsp_layer/conf/machine/machine2\.conf`` 1269 bsp_layer/conf/machine/machine2\.conf
1267 bsp_layer/conf/machine/machine3\.conf`` 1270 bsp_layer/conf/machine/machine3\.conf
1268 ... more ... 1271 ... more ...
1269 1272
1270For example, the machine configuration file for the `BeagleBone and 1273For example, the machine configuration file for the `BeagleBone and
1271BeagleBone Black development boards <http://beagleboard.org/bone>`__ is 1274BeagleBone Black development boards <https://beagleboard.org/bone>`__ is
1272located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named 1275located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named
1273``beaglebone-yocto.conf``: :: 1276``beaglebone-yocto.conf``: ::
1274 1277
@@ -1344,7 +1347,7 @@ Project Reference Manual.
1344 1347
1345 .. tip:: 1348 .. tip::
1346 1349
1347 Many ``MACHINE\*`` variables exist that help you configure a particular piece 1350 Many ``MACHINE*`` variables exist that help you configure a particular piece
1348 of hardware. 1351 of hardware.
1349 1352
1350- :term:`EXTRA_IMAGEDEPENDS`: 1353- :term:`EXTRA_IMAGEDEPENDS`:
@@ -1359,12 +1362,12 @@ Project Reference Manual.
1359 These features, which are collectively known as "tuning features", 1362 These features, which are collectively known as "tuning features",
1360 exist in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g. 1363 exist in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g.
1361 ``poky/meta/conf/machine/include``). In this example, the default 1364 ``poky/meta/conf/machine/include``). In this example, the default
1362 tunning file is "cortexa8hf-neon". 1365 tuning file is "cortexa8hf-neon".
1363 1366
1364 .. note:: 1367 .. note::
1365 1368
1366 The include statement that pulls in the 1369 The include statement that pulls in the
1367 conf/machine/include/tune-cortexa8.inc file provides many tuning 1370 ``conf/machine/include/tune-cortexa8.inc`` file provides many tuning
1368 possibilities. 1371 possibilities.
1369 1372
1370- :term:`IMAGE_FSTYPES`: The 1373- :term:`IMAGE_FSTYPES`: The
@@ -1389,7 +1392,7 @@ Project Reference Manual.
1389 1392
1390- ``do_image_wic[depends]``: A task that is constructed during the 1393- ``do_image_wic[depends]``: A task that is constructed during the
1391 build. In this example, the task depends on specific tools in order 1394 build. In this example, the task depends on specific tools in order
1392 to create the sysroot when buiding a Wic image. 1395 to create the sysroot when building a Wic image.
1393 1396
1394- :term:`SERIAL_CONSOLES`: 1397- :term:`SERIAL_CONSOLES`:
1395 Defines a serial console (TTY) to enable using getty. In this case, 1398 Defines a serial console (TTY) to enable using getty. In this case,
@@ -1429,7 +1432,8 @@ Project Reference Manual.
1429 1432
1430 .. note:: 1433 .. note::
1431 1434
1432 For more information on how the SPL variables are used, see the u-boot.inc 1435 For more information on how the SPL variables are used, see the
1436 :yocto_git:`u-boot.inc </cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc>`
1433 include file. 1437 include file.
1434 1438
1435- :term:`UBOOT_* <UBOOT_ENTRYPOINT>`: Defines 1439- :term:`UBOOT_* <UBOOT_ENTRYPOINT>`: Defines
@@ -1473,7 +1477,7 @@ The ``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains
1473metadata used to build the kernel. In this case, a kernel append file 1477metadata used to build the kernel. In this case, a kernel append file
1474(i.e. ``linux-yocto_5.0.bbappend``) is used to override an established 1478(i.e. ``linux-yocto_5.0.bbappend``) is used to override an established
1475kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in 1479kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in
1476https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux. 1480:yocto_git:`/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux`.
1477 1481
1478Following is the contents of the append file: :: 1482Following is the contents of the append file: ::
1479 1483