diff options
Diffstat (limited to 'documentation/bsp-guide/bsp.rst')
-rw-r--r-- | documentation/bsp-guide/bsp.rst | 315 |
1 files changed, 150 insertions, 165 deletions
diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst index 93e9182490..11ca5d8b76 100644 --- a/documentation/bsp-guide/bsp.rst +++ b/documentation/bsp-guide/bsp.rst | |||
@@ -1,8 +1,8 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | 1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK |
2 | 2 | ||
3 | ************************************************ | 3 | ************************************************** |
4 | Board Support Packages (BSP) - Developer's Guide | 4 | Board Support Packages (BSP) --- Developer's Guide |
5 | ************************************************ | 5 | ************************************************** |
6 | 6 | ||
7 | A Board Support Package (BSP) is a collection of information that | 7 | A Board Support Package (BSP) is a collection of information that |
8 | defines how to support a particular hardware device, set of devices, or | 8 | defines how to support a particular hardware device, set of devices, or |
@@ -26,7 +26,7 @@ A BSP consists of a file structure inside a base directory. | |||
26 | Collectively, you can think of the base directory, its file structure, | 26 | Collectively, you can think of the base directory, its file structure, |
27 | and the contents as a BSP layer. Although not a strict requirement, BSP | 27 | and the contents as a BSP layer. Although not a strict requirement, BSP |
28 | layers in the Yocto Project use the following well-established naming | 28 | layers in the Yocto Project use the following well-established naming |
29 | convention: :: | 29 | convention:: |
30 | 30 | ||
31 | meta-bsp_root_name | 31 | meta-bsp_root_name |
32 | 32 | ||
@@ -58,14 +58,14 @@ Each repository is a BSP layer supported by the Yocto Project (e.g. | |||
58 | ``meta-raspberrypi`` and ``meta-intel``). Each of these layers is a | 58 | ``meta-raspberrypi`` and ``meta-intel``). Each of these layers is a |
59 | repository unto itself and clicking on the layer name displays two URLs | 59 | repository unto itself and clicking on the layer name displays two URLs |
60 | from which you can clone the layer's repository to your local system. | 60 | from which you can clone the layer's repository to your local system. |
61 | Here is an example that clones the Raspberry Pi BSP layer: :: | 61 | Here is an example that clones the Raspberry Pi BSP layer:: |
62 | 62 | ||
63 | $ git clone git://git.yoctoproject.org/meta-raspberrypi | 63 | $ git clone git://git.yoctoproject.org/meta-raspberrypi |
64 | 64 | ||
65 | In addition to BSP layers, the ``meta-yocto-bsp`` layer is part of the | 65 | In addition to BSP layers, the ``meta-yocto-bsp`` layer is part of the |
66 | shipped ``poky`` repository. The ``meta-yocto-bsp`` layer maintains | 66 | shipped ``poky`` repository. The ``meta-yocto-bsp`` layer maintains |
67 | several "reference" BSPs including the ARM-based Beaglebone, MIPS-based | 67 | several "reference" BSPs including the ARM-based Beaglebone and generic |
68 | EdgeRouter, and generic versions of both 32-bit and 64-bit IA machines. | 68 | versions of both 32-bit and 64-bit IA machines. |
69 | 69 | ||
70 | For information on typical BSP development workflow, see the | 70 | For information on typical BSP development workflow, see the |
71 | :ref:`bsp-guide/bsp:developing a board support package (bsp)` | 71 | :ref:`bsp-guide/bsp:developing a board support package (bsp)` |
@@ -84,7 +84,7 @@ established after you run the OpenEmbedded build environment setup | |||
84 | script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). | 84 | script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). |
85 | Adding the root directory allows the :term:`OpenEmbedded Build System` | 85 | Adding the root directory allows the :term:`OpenEmbedded Build System` |
86 | to recognize the BSP | 86 | to recognize the BSP |
87 | layer and from it build an image. Here is an example: :: | 87 | layer and from it build an image. Here is an example:: |
88 | 88 | ||
89 | BBLAYERS ?= " \ | 89 | BBLAYERS ?= " \ |
90 | /usr/local/src/yocto/meta \ | 90 | /usr/local/src/yocto/meta \ |
@@ -95,11 +95,11 @@ layer and from it build an image. Here is an example: :: | |||
95 | 95 | ||
96 | .. note:: | 96 | .. note:: |
97 | 97 | ||
98 | Ordering and :term:`BBFILE_PRIORITY` for the layers listed in ``BBLAYERS`` | 98 | Ordering and :term:`BBFILE_PRIORITY` for the layers listed in :term:`BBLAYERS` |
99 | matter. For example, if multiple layers define a machine configuration, the | 99 | matter. For example, if multiple layers define a machine configuration, the |
100 | OpenEmbedded build system uses the last layer searched given similar layer | 100 | OpenEmbedded build system uses the last layer searched given similar layer |
101 | priorities. The build system works from the top-down through the layers | 101 | priorities. The build system works from the top-down through the layers |
102 | listed in ``BBLAYERS``. | 102 | listed in :term:`BBLAYERS`. |
103 | 103 | ||
104 | Some BSPs require or depend on additional layers beyond the BSP's root | 104 | Some BSPs require or depend on additional layers beyond the BSP's root |
105 | layer in order to be functional. In this case, you need to specify these | 105 | layer in order to be functional. In this case, you need to specify these |
@@ -109,11 +109,10 @@ them to the "Dependencies" section. | |||
109 | 109 | ||
110 | Some layers function as a layer to hold other BSP layers. These layers | 110 | Some layers function as a layer to hold other BSP layers. These layers |
111 | are known as ":term:`container layers <Container Layer>`". An example of | 111 | are known as ":term:`container layers <Container Layer>`". An example of |
112 | this type of layer is OpenEmbedded's | 112 | this type of layer is OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>` |
113 | `meta-openembedded <https://github.com/openembedded/meta-openembedded>`__ | ||
114 | layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers. | 113 | layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers. |
115 | In cases like this, you need to include the names of the actual layers | 114 | In cases like this, you need to include the names of the actual layers |
116 | you want to work with, such as: :: | 115 | you want to work with, such as:: |
117 | 116 | ||
118 | BBLAYERS ?= " \ | 117 | BBLAYERS ?= " \ |
119 | /usr/local/src/yocto/meta \ | 118 | /usr/local/src/yocto/meta \ |
@@ -128,7 +127,7 @@ you want to work with, such as: :: | |||
128 | and so on. | 127 | and so on. |
129 | 128 | ||
130 | For more information on layers, see the | 129 | For more information on layers, see the |
131 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 130 | ":ref:`dev-manual/layers:understanding and creating layers`" |
132 | section of the Yocto Project Development Tasks Manual. | 131 | section of the Yocto Project Development Tasks Manual. |
133 | 132 | ||
134 | Preparing Your Build Host to Work With BSP Layers | 133 | Preparing Your Build Host to Work With BSP Layers |
@@ -166,8 +165,9 @@ section. | |||
166 | #. *Determine the BSP Layer You Want:* The Yocto Project supports many | 165 | #. *Determine the BSP Layer You Want:* The Yocto Project supports many |
167 | BSPs, which are maintained in their own layers or in layers designed | 166 | BSPs, which are maintained in their own layers or in layers designed |
168 | to contain several BSPs. To get an idea of machine support through | 167 | to contain several BSPs. To get an idea of machine support through |
169 | BSP layers, you can look at the `index of | 168 | BSP layers, you can look at the |
170 | machines <&YOCTO_RELEASE_DL_URL;/machines>`__ for the release. | 169 | :yocto_dl:`index of machines </releases/yocto/yocto-&DISTRO;/machines>` |
170 | for the release. | ||
171 | 171 | ||
172 | #. *Optionally Clone the meta-intel BSP Layer:* If your hardware is | 172 | #. *Optionally Clone the meta-intel BSP Layer:* If your hardware is |
173 | 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 |
@@ -193,7 +193,7 @@ section. | |||
193 | 193 | ||
194 | #. *Check Out the Proper Branch:* The branch you check out for | 194 | #. *Check Out the Proper Branch:* The branch you check out for |
195 | ``meta-intel`` must match the same branch you are using for the | 195 | ``meta-intel`` must match the same branch you are using for the |
196 | Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``): :: | 196 | Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``):: |
197 | 197 | ||
198 | $ cd meta-intel | 198 | $ cd meta-intel |
199 | $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; | 199 | $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; |
@@ -216,7 +216,7 @@ section. | |||
216 | The process is identical to the process used for the ``meta-intel`` | 216 | The process is identical to the process used for the ``meta-intel`` |
217 | layer except for the layer's name. For example, if you determine that | 217 | layer except for the layer's name. For example, if you determine that |
218 | your hardware most closely matches the ``meta-raspberrypi``, clone | 218 | your hardware most closely matches the ``meta-raspberrypi``, clone |
219 | that layer: :: | 219 | that layer:: |
220 | 220 | ||
221 | $ git clone git://git.yoctoproject.org/meta-raspberrypi | 221 | $ git clone git://git.yoctoproject.org/meta-raspberrypi |
222 | Cloning into 'meta-raspberrypi'... | 222 | Cloning into 'meta-raspberrypi'... |
@@ -250,7 +250,7 @@ standardization of software support for hardware. | |||
250 | The proposed form described in this section does have elements that are | 250 | The proposed form described in this section does have elements that are |
251 | specific to the OpenEmbedded build system. It is intended that | 251 | specific to the OpenEmbedded build system. It is intended that |
252 | developers can use this structure with other build systems besides the | 252 | developers can use this structure with other build systems besides the |
253 | OpenEmbedded build system. It is also intended that it will be be simple | 253 | OpenEmbedded build system. It is also intended that it will be simple |
254 | to extract information and convert it to other formats if required. The | 254 | to extract information and convert it to other formats if required. The |
255 | OpenEmbedded build system, through its standard :ref:`layers mechanism | 255 | OpenEmbedded build system, through its standard :ref:`layers mechanism |
256 | <overview-manual/yp-intro:the yocto project layer model>`, can | 256 | <overview-manual/yp-intro:the yocto project layer model>`, can |
@@ -267,7 +267,7 @@ maintain the distinction that the BSP layer, a build system, and tools | |||
267 | are separate components that could be combined in certain end products. | 267 | are separate components that could be combined in certain end products. |
268 | 268 | ||
269 | Before looking at the recommended form for the directory structure | 269 | Before looking at the recommended form for the directory structure |
270 | inside a BSP layer, you should be aware that some requirements do exist | 270 | inside a BSP layer, you should be aware that there are some requirements |
271 | in order for a BSP layer to be considered compliant with the Yocto | 271 | in order for a BSP layer to be considered compliant with the Yocto |
272 | Project. For that list of requirements, see the | 272 | Project. For that list of requirements, see the |
273 | ":ref:`bsp-guide/bsp:released bsp requirements`" section. | 273 | ":ref:`bsp-guide/bsp:released bsp requirements`" section. |
@@ -289,7 +289,7 @@ individual BSPs could differ. :: | |||
289 | meta-bsp_root_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend | 289 | meta-bsp_root_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend |
290 | 290 | ||
291 | Below is an example of the Raspberry Pi BSP layer that is available from | 291 | Below is an example of the Raspberry Pi BSP layer that is available from |
292 | the :yocto_git:`Source Respositories <>`: | 292 | the :yocto_git:`Source Repositories <>`: |
293 | 293 | ||
294 | .. code-block:: none | 294 | .. code-block:: none |
295 | 295 | ||
@@ -336,7 +336,7 @@ the :yocto_git:`Source Respositories <>`: | |||
336 | meta-raspberrypi/recipes-bsp/formfactor/formfactor | 336 | meta-raspberrypi/recipes-bsp/formfactor/formfactor |
337 | meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi | 337 | meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi |
338 | meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig | 338 | meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig |
339 | meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend | 339 | meta-raspberrypi/recipes-bsp/formfactor/formfactor_%.bbappend |
340 | meta-raspberrypi/recipes-bsp/rpi-u-boot-src | 340 | meta-raspberrypi/recipes-bsp/rpi-u-boot-src |
341 | meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files | 341 | meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files |
342 | meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in | 342 | meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in |
@@ -451,7 +451,7 @@ The following sections describe each part of the proposed BSP format. | |||
451 | License Files | 451 | License Files |
452 | ------------- | 452 | ------------- |
453 | 453 | ||
454 | You can find these files in the BSP Layer at: :: | 454 | You can find these files in the BSP Layer at:: |
455 | 455 | ||
456 | meta-bsp_root_name/bsp_license_file | 456 | meta-bsp_root_name/bsp_license_file |
457 | 457 | ||
@@ -463,13 +463,13 @@ requirements are handled with the ``COPYING.MIT`` file. | |||
463 | Licensing files can be MIT, BSD, GPLv*, and so forth. These files are | 463 | Licensing files can be MIT, BSD, GPLv*, and so forth. These files are |
464 | recommended for the BSP but are optional and totally up to the BSP | 464 | recommended for the BSP but are optional and totally up to the BSP |
465 | developer. For information on how to maintain license compliance, see | 465 | developer. For information on how to maintain license compliance, see |
466 | the ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" | 466 | the ":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" |
467 | section in the Yocto Project Development Tasks Manual. | 467 | section in the Yocto Project Development Tasks Manual. |
468 | 468 | ||
469 | README File | 469 | README File |
470 | ----------- | 470 | ----------- |
471 | 471 | ||
472 | You can find this file in the BSP Layer at: :: | 472 | You can find this file in the BSP Layer at:: |
473 | 473 | ||
474 | meta-bsp_root_name/README | 474 | meta-bsp_root_name/README |
475 | 475 | ||
@@ -484,7 +484,7 @@ name of the BSP maintainer with his or her contact information. | |||
484 | README.sources File | 484 | README.sources File |
485 | ------------------- | 485 | ------------------- |
486 | 486 | ||
487 | You can find this file in the BSP Layer at: :: | 487 | You can find this file in the BSP Layer at:: |
488 | 488 | ||
489 | meta-bsp_root_name/README.sources | 489 | meta-bsp_root_name/README.sources |
490 | 490 | ||
@@ -503,7 +503,7 @@ used to generate the images that ship with the BSP. | |||
503 | Pre-built User Binaries | 503 | Pre-built User Binaries |
504 | ----------------------- | 504 | ----------------------- |
505 | 505 | ||
506 | You can find these files in the BSP Layer at: :: | 506 | You can find these files in the BSP Layer at:: |
507 | 507 | ||
508 | meta-bsp_root_name/binary/bootable_images | 508 | meta-bsp_root_name/binary/bootable_images |
509 | 509 | ||
@@ -526,7 +526,7 @@ information on the Metadata. | |||
526 | Layer Configuration File | 526 | Layer Configuration File |
527 | ------------------------ | 527 | ------------------------ |
528 | 528 | ||
529 | You can find this file in the BSP Layer at: :: | 529 | You can find this file in the BSP Layer at:: |
530 | 530 | ||
531 | meta-bsp_root_name/conf/layer.conf | 531 | meta-bsp_root_name/conf/layer.conf |
532 | 532 | ||
@@ -550,7 +550,7 @@ template). :: | |||
550 | LAYERDEPENDS_bsp = "intel" | 550 | LAYERDEPENDS_bsp = "intel" |
551 | 551 | ||
552 | To illustrate the string substitutions, here are the corresponding | 552 | To illustrate the string substitutions, here are the corresponding |
553 | statements from the Raspberry Pi ``conf/layer.conf`` file: :: | 553 | statements from the Raspberry Pi ``conf/layer.conf`` file:: |
554 | 554 | ||
555 | # We have a conf and classes directory, append to BBPATH | 555 | # We have a conf and classes directory, append to BBPATH |
556 | BBPATH .= ":${LAYERDIR}" | 556 | BBPATH .= ":${LAYERDIR}" |
@@ -576,7 +576,7 @@ recognize the BSP. | |||
576 | Hardware Configuration Options | 576 | Hardware Configuration Options |
577 | ------------------------------ | 577 | ------------------------------ |
578 | 578 | ||
579 | You can find these files in the BSP Layer at: :: | 579 | You can find these files in the BSP Layer at:: |
580 | 580 | ||
581 | meta-bsp_root_name/conf/machine/*.conf | 581 | meta-bsp_root_name/conf/machine/*.conf |
582 | 582 | ||
@@ -589,7 +589,7 @@ filenames correspond to the values to which users have set the | |||
589 | 589 | ||
590 | These files define things such as the kernel package to use | 590 | These files define things such as the kernel package to use |
591 | (:term:`PREFERRED_PROVIDER` of | 591 | (:term:`PREFERRED_PROVIDER` of |
592 | :ref:`virtual/kernel <dev-manual/common-tasks:using virtual providers>`), | 592 | :ref:`virtual/kernel <dev-manual/new-recipe:using virtual providers>`), |
593 | the hardware drivers to include in different types of images, any | 593 | the hardware drivers to include in different types of images, any |
594 | special software components that are needed, any bootloader information, | 594 | special software components that are needed, any bootloader information, |
595 | and also any special image format requirements. | 595 | and also any special image format requirements. |
@@ -607,24 +607,24 @@ For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``, | |||
607 | 607 | ||
608 | To use an include file, you simply include them in the machine | 608 | To use an include file, you simply include them in the machine |
609 | configuration file. For example, the Raspberry Pi BSP | 609 | configuration file. For example, the Raspberry Pi BSP |
610 | ``raspberrypi3.conf`` contains the following statement: :: | 610 | ``raspberrypi3.conf`` contains the following statement:: |
611 | 611 | ||
612 | include conf/machine/include/rpi-base.inc | 612 | include conf/machine/include/rpi-base.inc |
613 | 613 | ||
614 | Miscellaneous BSP-Specific Recipe Files | 614 | Miscellaneous BSP-Specific Recipe Files |
615 | --------------------------------------- | 615 | --------------------------------------- |
616 | 616 | ||
617 | You can find these files in the BSP Layer at: :: | 617 | You can find these files in the BSP Layer at:: |
618 | 618 | ||
619 | meta-bsp_root_name/recipes-bsp/* | 619 | meta-bsp_root_name/recipes-bsp/* |
620 | 620 | ||
621 | This optional directory contains miscellaneous recipe files for the BSP. | 621 | This optional directory contains miscellaneous recipe files for the BSP. |
622 | Most notably would be the formfactor files. For example, in the | 622 | Most notably would be the formfactor files. For example, in the |
623 | Raspberry Pi BSP, there is the ``formfactor_0.0.bbappend`` file, which | 623 | Raspberry Pi BSP, there is the ``formfactor_%.bbappend`` file, which |
624 | is an append file used to augment the recipe that starts the build. | 624 | is an append file used to augment the recipe that starts the build. |
625 | Furthermore, there are machine-specific settings used during the build | 625 | Furthermore, there are machine-specific settings used during the build |
626 | that are defined by the ``machconfig`` file further down in the | 626 | that are defined by the ``machconfig`` file further down in the |
627 | directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: :: | 627 | directory. Here is the ``machconfig`` file for the Raspberry Pi BSP:: |
628 | 628 | ||
629 | HAVE_TOUCHSCREEN=0 | 629 | HAVE_TOUCHSCREEN=0 |
630 | HAVE_KEYBOARD=1 | 630 | HAVE_KEYBOARD=1 |
@@ -644,7 +644,7 @@ directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: :: | |||
644 | Display Support Files | 644 | Display Support Files |
645 | --------------------- | 645 | --------------------- |
646 | 646 | ||
647 | You can find these files in the BSP Layer at: :: | 647 | You can find these files in the BSP Layer at:: |
648 | 648 | ||
649 | meta-bsp_root_name/recipes-graphics/* | 649 | meta-bsp_root_name/recipes-graphics/* |
650 | 650 | ||
@@ -655,7 +655,7 @@ to support a display are kept here. | |||
655 | Linux Kernel Configuration | 655 | Linux Kernel Configuration |
656 | -------------------------- | 656 | -------------------------- |
657 | 657 | ||
658 | You can find these files in the BSP Layer at: :: | 658 | You can find these files in the BSP Layer at:: |
659 | 659 | ||
660 | meta-bsp_root_name/recipes-kernel/linux/linux*.bbappend | 660 | meta-bsp_root_name/recipes-kernel/linux/linux*.bbappend |
661 | meta-bsp_root_name/recipes-kernel/linux/*.bb | 661 | meta-bsp_root_name/recipes-kernel/linux/*.bb |
@@ -678,14 +678,14 @@ Suppose you are using the ``linux-yocto_4.4.bb`` recipe to build the | |||
678 | kernel. In other words, you have selected the kernel in your | 678 | kernel. In other words, you have selected the kernel in your |
679 | ``"bsp_root_name".conf`` file by adding | 679 | ``"bsp_root_name".conf`` file by adding |
680 | :term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` | 680 | :term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` |
681 | statements as follows: :: | 681 | statements as follows:: |
682 | 682 | ||
683 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | 683 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
684 | PREFERRED_VERSION_linux-yocto ?= "4.4%" | 684 | PREFERRED_VERSION_linux-yocto ?= "4.4%" |
685 | 685 | ||
686 | .. note:: | 686 | .. note:: |
687 | 687 | ||
688 | When the preferred provider is assumed by default, the ``PREFERRED_PROVIDER`` | 688 | When the preferred provider is assumed by default, the :term:`PREFERRED_PROVIDER` |
689 | statement does not appear in the ``"bsp_root_name".conf`` file. | 689 | statement does not appear in the ``"bsp_root_name".conf`` file. |
690 | 690 | ||
691 | You would use the ``linux-yocto_4.4.bbappend`` file to append specific | 691 | You would use the ``linux-yocto_4.4.bbappend`` file to append specific |
@@ -698,7 +698,7 @@ in the Yocto Project Linux Kernel Development Manual. | |||
698 | 698 | ||
699 | An alternate scenario is when you create your own kernel recipe for the | 699 | An alternate scenario is when you create your own kernel recipe for the |
700 | BSP. A good example of this is the Raspberry Pi BSP. If you examine the | 700 | BSP. A good example of this is the Raspberry Pi BSP. If you examine the |
701 | ``recipes-kernel/linux`` directory you see the following: :: | 701 | ``recipes-kernel/linux`` directory you see the following:: |
702 | 702 | ||
703 | linux-raspberrypi-dev.bb | 703 | linux-raspberrypi-dev.bb |
704 | linux-raspberrypi.inc | 704 | linux-raspberrypi.inc |
@@ -724,6 +724,7 @@ workflow. | |||
724 | 724 | ||
725 | .. image:: figures/bsp-dev-flow.png | 725 | .. image:: figures/bsp-dev-flow.png |
726 | :align: center | 726 | :align: center |
727 | :width: 70% | ||
727 | 728 | ||
728 | #. *Set up Your Host Development System to Support Development Using the | 729 | #. *Set up Your Host Development System to Support Development Using the |
729 | Yocto Project*: See the ":ref:`dev-manual/start:preparing the build host`" | 730 | Yocto Project*: See the ":ref:`dev-manual/start:preparing the build host`" |
@@ -756,36 +757,20 @@ workflow. | |||
756 | OpenEmbedded build system knows about. For more information on | 757 | OpenEmbedded build system knows about. For more information on |
757 | layers, see the ":ref:`overview-manual/yp-intro:the yocto project layer model`" | 758 | layers, see the ":ref:`overview-manual/yp-intro:the yocto project layer model`" |
758 | section in the Yocto Project Overview and Concepts Manual. You can also | 759 | section in the Yocto Project Overview and Concepts Manual. You can also |
759 | reference the ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 760 | reference the ":ref:`dev-manual/layers:understanding and creating layers`" |
760 | section in the Yocto Project Development Tasks Manual. For more | 761 | section in the Yocto Project Development Tasks Manual. For more |
761 | information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" | 762 | information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" |
762 | section. | 763 | section. |
763 | 764 | ||
764 | .. note:: | 765 | .. note:: |
765 | 766 | ||
766 | - Four hardware reference BSPs exist that are part of the Yocto | 767 | - There are three hardware reference BSPs in the Yocto |
767 | Project release and are located in the ``poky/meta-yocto-bsp`` | 768 | Project release, located in the ``poky/meta-yocto-bsp`` |
768 | BSP layer: | 769 | BSP layer: |
769 | 770 | ||
770 | - Texas Instruments Beaglebone (``beaglebone-yocto``) | 771 | - Texas Instruments Beaglebone (``beaglebone-yocto``) |
771 | 772 | ||
772 | - Ubiquiti Networks EdgeRouter Lite (``edgerouter``) | 773 | - Two generic IA platforms (``genericx86`` and ``genericx86-64``) |
773 | |||
774 | - Two general IA platforms (``genericx86`` and ``genericx86-64``) | ||
775 | |||
776 | - Three core Intel BSPs exist as part of the Yocto Project | ||
777 | release in the ``meta-intel`` layer: | ||
778 | |||
779 | - ``intel-core2-32``, which is a BSP optimized for the Core2 | ||
780 | family of CPUs as well as all CPUs prior to the Silvermont | ||
781 | core. | ||
782 | |||
783 | - ``intel-corei7-64``, which is a BSP optimized for Nehalem | ||
784 | and later Core and Xeon CPUs as well as Silvermont and later | ||
785 | Atom CPUs, such as the Baytrail SoCs. | ||
786 | |||
787 | - ``intel-quark``, which is a BSP optimized for the Intel | ||
788 | Galileo gen1 & gen2 development boards. | ||
789 | 774 | ||
790 | When you set up a layer for a new BSP, you should follow a standard | 775 | When you set up a layer for a new BSP, you should follow a standard |
791 | layout. This layout is described in the ":ref:`bsp-guide/bsp:example filesystem layout`" | 776 | layout. This layout is described in the ":ref:`bsp-guide/bsp:example filesystem layout`" |
@@ -815,7 +800,7 @@ workflow. | |||
815 | key configuration files are configured appropriately: the | 800 | key configuration files are configured appropriately: the |
816 | ``conf/local.conf`` and the ``conf/bblayers.conf`` file. You must | 801 | ``conf/local.conf`` and the ``conf/bblayers.conf`` file. You must |
817 | make the OpenEmbedded build system aware of your new layer. See the | 802 | make the OpenEmbedded build system aware of your new layer. See the |
818 | ":ref:`dev-manual/common-tasks:enabling your layer`" | 803 | ":ref:`dev-manual/layers:enabling your layer`" |
819 | section in the Yocto Project Development Tasks Manual for information | 804 | section in the Yocto Project Development Tasks Manual for information |
820 | on how to let the build system know about your new layer. | 805 | on how to let the build system know about your new layer. |
821 | 806 | ||
@@ -832,10 +817,8 @@ workflow. | |||
832 | Requirements and Recommendations for Released BSPs | 817 | Requirements and Recommendations for Released BSPs |
833 | ================================================== | 818 | ================================================== |
834 | 819 | ||
835 | Certain requirements exist for a released BSP to be considered compliant | 820 | This section describes requirements and recommendations for a released |
836 | with the Yocto Project. Additionally, recommendations also exist. This | 821 | BSP to be considered compliant with the Yocto Project. |
837 | section describes the requirements and recommendations for released | ||
838 | BSPs. | ||
839 | 822 | ||
840 | Released BSP Requirements | 823 | Released BSP Requirements |
841 | ------------------------- | 824 | ------------------------- |
@@ -846,7 +829,7 @@ Before looking at BSP requirements, you should consider the following: | |||
846 | layer that can be added to the Yocto Project. For guidelines on | 829 | layer that can be added to the Yocto Project. For guidelines on |
847 | creating a layer that meets these base requirements, see the | 830 | creating a layer that meets these base requirements, see the |
848 | ":ref:`bsp-guide/bsp:bsp layers`" section in this manual and the | 831 | ":ref:`bsp-guide/bsp:bsp layers`" section in this manual and the |
849 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 832 | ":ref:`dev-manual/layers:understanding and creating layers`" |
850 | section in the Yocto Project Development Tasks Manual. | 833 | section in the Yocto Project Development Tasks Manual. |
851 | 834 | ||
852 | - The requirements in this section apply regardless of how you package | 835 | - The requirements in this section apply regardless of how you package |
@@ -864,12 +847,11 @@ Before looking at BSP requirements, you should consider the following: | |||
864 | 847 | ||
865 | - It is not required that specific packages or package modifications | 848 | - It is not required that specific packages or package modifications |
866 | exist in the BSP layer, beyond the requirements for general | 849 | exist in the BSP layer, beyond the requirements for general |
867 | compliance with the Yocto Project. For example, no requirement exists | 850 | compliance with the Yocto Project. For example, there is no requirement |
868 | dictating that a specific kernel or kernel version be used in a given | 851 | dictating that a specific kernel or kernel version be used in a given |
869 | BSP. | 852 | BSP. |
870 | 853 | ||
871 | Following are the requirements for a released BSP that conform to the | 854 | The requirements for a released BSP that conform to the Yocto Project are: |
872 | Yocto Project: | ||
873 | 855 | ||
874 | - *Layer Name:* The BSP must have a layer name that follows the Yocto | 856 | - *Layer Name:* The BSP must have a layer name that follows the Yocto |
875 | Project standards. For information on BSP layer names, see the | 857 | Project standards. For information on BSP layer names, see the |
@@ -879,7 +861,7 @@ Yocto Project: | |||
879 | your BSP layer as listed in the ``recipes.txt`` file, which is found | 861 | your BSP layer as listed in the ``recipes.txt`` file, which is found |
880 | in ``poky/meta`` directory of the :term:`Source Directory` | 862 | in ``poky/meta`` directory of the :term:`Source Directory` |
881 | or in the OpenEmbedded-Core Layer (``openembedded-core``) at | 863 | or in the OpenEmbedded-Core Layer (``openembedded-core``) at |
882 | https://git.openembedded.org/openembedded-core/tree/meta. | 864 | :oe_git:`/openembedded-core/tree/meta`. |
883 | 865 | ||
884 | You should place recipes (``*.bb`` files) and recipe modifications | 866 | You should place recipes (``*.bb`` files) and recipe modifications |
885 | (``*.bbappend`` files) into ``recipes-*`` subdirectories by | 867 | (``*.bbappend`` files) into ``recipes-*`` subdirectories by |
@@ -894,13 +876,13 @@ Yocto Project: | |||
894 | ``recipes-*`` subdirectories specific to the recipe's function, or | 876 | ``recipes-*`` subdirectories specific to the recipe's function, or |
895 | within a subdirectory containing a set of closely-related recipes. | 877 | within a subdirectory containing a set of closely-related recipes. |
896 | The recipes themselves should follow the general guidelines for | 878 | The recipes themselves should follow the general guidelines for |
897 | recipes used in the Yocto Project found in the ":oe_wiki:`OpenEmbedded | 879 | recipes found in the ":doc:`../contributor-guide/recipe-style-guide`" |
898 | Style Guide </Styleguide>`". | 880 | in the Yocto Project and OpenEmbedded Contributor Guide. |
899 | 881 | ||
900 | - *License File:* You must include a license file in the | 882 | - *License File:* You must include a license file in the |
901 | ``meta-bsp_root_name`` directory. This license covers the BSP | 883 | ``meta-bsp_root_name`` directory. This license covers the BSP |
902 | Metadata as a whole. You must specify which license to use since no | 884 | Metadata as a whole. You must specify which license to use since no |
903 | default license exists when one is not specified. See the | 885 | default license exists. See the |
904 | :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>` | 886 | :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>` |
905 | file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer | 887 | file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer |
906 | as an example. | 888 | as an example. |
@@ -928,8 +910,8 @@ Yocto Project: | |||
928 | - The name and contact information for the BSP layer maintainer. | 910 | - The name and contact information for the BSP layer maintainer. |
929 | This is the person to whom patches and questions should be sent. | 911 | This is the person to whom patches and questions should be sent. |
930 | For information on how to find the right person, see the | 912 | For information on how to find the right person, see the |
931 | ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" | 913 | :doc:`../contributor-guide/submit-changes` section in the Yocto Project and |
932 | section in the Yocto Project Development Tasks Manual. | 914 | OpenEmbedded Contributor Guide. |
933 | 915 | ||
934 | - Instructions on how to build the BSP using the BSP layer. | 916 | - Instructions on how to build the BSP using the BSP layer. |
935 | 917 | ||
@@ -973,7 +955,7 @@ Yocto Project: | |||
973 | Released BSP Recommendations | 955 | Released BSP Recommendations |
974 | ---------------------------- | 956 | ---------------------------- |
975 | 957 | ||
976 | Following are recommendations for released BSPs that conform to the | 958 | Here are recommendations for released BSPs that conform to the |
977 | Yocto Project: | 959 | Yocto Project: |
978 | 960 | ||
979 | - *Bootable Images:* Released BSPs can contain one or more bootable | 961 | - *Bootable Images:* Released BSPs can contain one or more bootable |
@@ -1013,9 +995,9 @@ If you plan on customizing a recipe for a particular BSP, you need to do | |||
1013 | the following: | 995 | the following: |
1014 | 996 | ||
1015 | - Create a ``*.bbappend`` file for the modified recipe. For information on using | 997 | - Create a ``*.bbappend`` file for the modified recipe. For information on using |
1016 | append files, see the ":ref:`dev-manual/common-tasks:using | 998 | append files, see the |
1017 | .bbappend files in your layer`" section in the Yocto Project Development | 999 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" |
1018 | Tasks Manual. | 1000 | section in the Yocto Project Development Tasks Manual. |
1019 | 1001 | ||
1020 | - Ensure your directory structure in the BSP layer that supports your | 1002 | - Ensure your directory structure in the BSP layer that supports your |
1021 | machine is such that the OpenEmbedded build system can find it. See | 1003 | machine is such that the OpenEmbedded build system can find it. See |
@@ -1035,29 +1017,29 @@ the following: | |||
1035 | that additional hierarchy and the files would obviously not be able | 1017 | that additional hierarchy and the files would obviously not be able |
1036 | to reside in a machine-specific directory. | 1018 | to reside in a machine-specific directory. |
1037 | 1019 | ||
1038 | Following is a specific example to help you better understand the | 1020 | Here is a specific example to help you better understand the |
1039 | process. This example customizes customizes a recipe by adding a | 1021 | process. This example customizes a recipe by adding a |
1040 | BSP-specific configuration file named ``interfaces`` to the | 1022 | BSP-specific configuration file named ``interfaces`` to the |
1041 | ``init-ifupdown_1.0.bb`` recipe for machine "xyz" where the BSP layer | 1023 | ``init-ifupdown_1.0.bb`` recipe for machine "xyz" where the BSP layer |
1042 | also supports several other machines: | 1024 | also supports several other machines: |
1043 | 1025 | ||
1044 | #. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the | 1026 | #. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the |
1045 | following: :: | 1027 | following:: |
1046 | 1028 | ||
1047 | FILESEXTRAPATHS_prepend := "${THISDIR}/files:" | 1029 | FILESEXTRAPATHS:prepend := "${THISDIR}/files:" |
1048 | 1030 | ||
1049 | The append file needs to be in the ``meta-xyz/recipes-core/init-ifupdown`` | 1031 | The append file needs to be in the ``meta-xyz/recipes-core/init-ifupdown`` |
1050 | directory. | 1032 | directory. |
1051 | 1033 | ||
1052 | #. Create and place the new ``interfaces`` configuration file in the | 1034 | #. Create and place the new ``interfaces`` configuration file in the |
1053 | BSP's layer here: :: | 1035 | BSP's layer here:: |
1054 | 1036 | ||
1055 | meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces | 1037 | meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces |
1056 | 1038 | ||
1057 | .. note:: | 1039 | .. note:: |
1058 | 1040 | ||
1059 | If the ``meta-xyz`` layer did not support multiple machines, you would place | 1041 | If the ``meta-xyz`` layer did not support multiple machines, you would place |
1060 | the interfaces configuration file in the layer here: :: | 1042 | the interfaces configuration file in the layer here:: |
1061 | 1043 | ||
1062 | meta-xyz/recipes-core/init-ifupdown/files/interfaces | 1044 | meta-xyz/recipes-core/init-ifupdown/files/interfaces |
1063 | 1045 | ||
@@ -1107,31 +1089,31 @@ system requirements. | |||
1107 | unsuitable functionality or quality, you can use an encumbered | 1089 | unsuitable functionality or quality, you can use an encumbered |
1108 | version. | 1090 | version. |
1109 | 1091 | ||
1110 | A couple different methods exist within the OpenEmbedded build system to | 1092 | There are two different methods within the OpenEmbedded build system to |
1111 | satisfy the licensing requirements for an encumbered BSP. The following | 1093 | satisfy the licensing requirements for an encumbered BSP. The following |
1112 | list describes them in order of preference: | 1094 | list describes them in order of preference: |
1113 | 1095 | ||
1114 | #. *Use the LICENSE_FLAGS Variable to Define the Recipes that Have Commercial or | 1096 | #. *Use the LICENSE_FLAGS Variable to Define the Recipes that Have Commercial or |
1115 | Other Types of Specially-Licensed Packages:* For each of those recipes, you can | 1097 | Other Types of Specially-Licensed Packages:* For each of those recipes, you can |
1116 | specify a matching license string in a ``local.conf`` variable named | 1098 | specify a matching license string in a ``local.conf`` variable named |
1117 | :term:`LICENSE_FLAGS_WHITELIST`. | 1099 | :term:`LICENSE_FLAGS_ACCEPTED`. |
1118 | Specifying the matching license string signifies that you agree to | 1100 | Specifying the matching license string signifies that you agree to |
1119 | the license. Thus, the build system can build the corresponding | 1101 | the license. Thus, the build system can build the corresponding |
1120 | recipe and include the component in the image. See the | 1102 | recipe and include the component in the image. See the |
1121 | ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`" | 1103 | ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" |
1122 | section in the Yocto Project Development Tasks Manual for details on | 1104 | section in the Yocto Project Development Tasks Manual for details on |
1123 | how to use these variables. | 1105 | how to use these variables. |
1124 | 1106 | ||
1125 | If you build as you normally would, without specifying any recipes in | 1107 | If you build as you normally would, without specifying any recipes in |
1126 | the ``LICENSE_FLAGS_WHITELIST``, the build stops and provides you | 1108 | the :term:`LICENSE_FLAGS_ACCEPTED` variable, the build stops and provides |
1127 | with the list of recipes that you have tried to include in the image | 1109 | you with the list of recipes that you have tried to include in the image |
1128 | that need entries in the ``LICENSE_FLAGS_WHITELIST``. Once you enter | 1110 | that need entries in the :term:`LICENSE_FLAGS_ACCEPTED` variable. Once you |
1129 | the appropriate license flags into the whitelist, restart the build | 1111 | enter the appropriate license flags into it, restart the build to continue |
1130 | to continue where it left off. During the build, the prompt will not | 1112 | where it left off. During the build, the prompt will not appear again since |
1131 | appear again since you have satisfied the requirement. | 1113 | you have satisfied the requirement. |
1132 | 1114 | ||
1133 | Once the appropriate license flags are on the white list in the | 1115 | Once the appropriate license flags are on the white list in the |
1134 | ``LICENSE_FLAGS_WHITELIST`` variable, you can build the encumbered | 1116 | :term:`LICENSE_FLAGS_ACCEPTED` variable, you can build the encumbered |
1135 | image with no change at all to the normal build process. | 1117 | image with no change at all to the normal build process. |
1136 | 1118 | ||
1137 | #. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by | 1119 | #. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by |
@@ -1144,7 +1126,7 @@ list describes them in order of preference: | |||
1144 | click-through license agreements presented by the website. If you | 1126 | click-through license agreements presented by the website. If you |
1145 | want to build the image yourself using the recipes contained within | 1127 | want to build the image yourself using the recipes contained within |
1146 | the BSP tarball, you will still need to create an appropriate | 1128 | the BSP tarball, you will still need to create an appropriate |
1147 | ``LICENSE_FLAGS_WHITELIST`` to match the encumbered recipes in the | 1129 | :term:`LICENSE_FLAGS_ACCEPTED` to match the encumbered recipes in the |
1148 | BSP. | 1130 | BSP. |
1149 | 1131 | ||
1150 | .. note:: | 1132 | .. note:: |
@@ -1170,7 +1152,7 @@ Use these steps to create a BSP layer: | |||
1170 | ``create-layer`` subcommand to create a new general layer. For | 1152 | ``create-layer`` subcommand to create a new general layer. For |
1171 | instructions on how to create a general layer using the | 1153 | instructions on how to create a general layer using the |
1172 | ``bitbake-layers`` script, see the | 1154 | ``bitbake-layers`` script, see the |
1173 | ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" | 1155 | ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" |
1174 | section in the Yocto Project Development Tasks Manual. | 1156 | section in the Yocto Project Development Tasks Manual. |
1175 | 1157 | ||
1176 | - *Create a Layer Configuration File:* Every layer needs a layer | 1158 | - *Create a Layer Configuration File:* Every layer needs a layer |
@@ -1180,22 +1162,22 @@ Use these steps to create a BSP layer: | |||
1180 | :yocto_git:`Source Repositories <>`. To get examples of what you need | 1162 | :yocto_git:`Source Repositories <>`. To get examples of what you need |
1181 | in your configuration file, locate a layer (e.g. "meta-ti") and | 1163 | in your configuration file, locate a layer (e.g. "meta-ti") and |
1182 | examine the | 1164 | examine the |
1183 | :yocto_git:`local.conf </meta-ti/tree/conf/layer.conf>` | 1165 | :yocto_git:`local.conf </meta-ti/tree/meta-ti-bsp/conf/layer.conf>` |
1184 | file. | 1166 | file. |
1185 | 1167 | ||
1186 | - *Create a Machine Configuration File:* Create a | 1168 | - *Create a Machine Configuration File:* Create a |
1187 | ``conf/machine/bsp_root_name.conf`` file. See | 1169 | ``conf/machine/bsp_root_name.conf`` file. See |
1188 | :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>` | 1170 | :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>` |
1189 | for sample ``bsp_root_name.conf`` files. Other samples such as | 1171 | for sample ``bsp_root_name.conf`` files. There are other samples such as |
1190 | :yocto_git:`meta-ti </meta-ti/tree/conf/machine>` | 1172 | :yocto_git:`meta-ti </meta-ti/tree/meta-ti-bsp/conf/machine>` |
1191 | and | 1173 | and |
1192 | :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>` | 1174 | :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>` |
1193 | exist from other vendors that have more specific machine and tuning | 1175 | from other vendors that have more specific machine and tuning |
1194 | examples. | 1176 | examples. |
1195 | 1177 | ||
1196 | - *Create a Kernel Recipe:* Create a kernel recipe in | 1178 | - *Create a Kernel Recipe:* Create a kernel recipe in |
1197 | ``recipes-kernel/linux`` by either using a kernel append file or a | 1179 | ``recipes-kernel/linux`` by either using a kernel append file or a |
1198 | new custom kernel recipe file (e.g. ``yocto-linux_4.12.bb``). The BSP | 1180 | new custom kernel recipe file (e.g. ``linux-yocto_4.12.bb``). The BSP |
1199 | layers mentioned in the previous step also contain different kernel | 1181 | layers mentioned in the previous step also contain different kernel |
1200 | examples. See the ":ref:`kernel-dev/common:modifying an existing recipe`" | 1182 | examples. See the ":ref:`kernel-dev/common:modifying an existing recipe`" |
1201 | section in the Yocto Project Linux Kernel Development Manual for | 1183 | section in the Yocto Project Linux Kernel Development Manual for |
@@ -1210,7 +1192,7 @@ BSP Layer Configuration Example | |||
1210 | ------------------------------- | 1192 | ------------------------------- |
1211 | 1193 | ||
1212 | The layer's ``conf`` directory contains the ``layer.conf`` configuration | 1194 | The layer's ``conf`` directory contains the ``layer.conf`` configuration |
1213 | file. In this example, the ``conf/layer.conf`` is the following: :: | 1195 | file. In this example, the ``conf/layer.conf`` file is the following:: |
1214 | 1196 | ||
1215 | # We have a conf and classes directory, add to BBPATH | 1197 | # We have a conf and classes directory, add to BBPATH |
1216 | BBPATH .= ":${LAYERDIR}" | 1198 | BBPATH .= ":${LAYERDIR}" |
@@ -1230,7 +1212,7 @@ configuration files is to examine various files for BSP from the | |||
1230 | :yocto_git:`Source Repositories <>`. | 1212 | :yocto_git:`Source Repositories <>`. |
1231 | 1213 | ||
1232 | For a detailed description of this particular layer configuration file, | 1214 | For a detailed description of this particular layer configuration file, |
1233 | see ":ref:`step 3 <dev-manual/common-tasks:creating your own layer>`" | 1215 | see ":ref:`step 3 <dev-manual/layers:creating your own layer>`" |
1234 | in the discussion that describes how to create layers in the Yocto | 1216 | in the discussion that describes how to create layers in the Yocto |
1235 | Project Development Tasks Manual. | 1217 | Project Development Tasks Manual. |
1236 | 1218 | ||
@@ -1241,8 +1223,8 @@ As mentioned earlier in this section, the existence of a machine | |||
1241 | configuration file is what makes a layer a BSP layer as compared to a | 1223 | configuration file is what makes a layer a BSP layer as compared to a |
1242 | general or kernel layer. | 1224 | general or kernel layer. |
1243 | 1225 | ||
1244 | One or more machine configuration files exist in the | 1226 | There are one or more machine configuration files in the |
1245 | ``bsp_layer/conf/machine/`` directory of the layer: :: | 1227 | ``bsp_layer/conf/machine/`` directory of the layer:: |
1246 | 1228 | ||
1247 | bsp_layer/conf/machine/machine1\.conf | 1229 | bsp_layer/conf/machine/machine1\.conf |
1248 | bsp_layer/conf/machine/machine2\.conf | 1230 | bsp_layer/conf/machine/machine2\.conf |
@@ -1251,41 +1233,39 @@ One or more machine configuration files exist in the | |||
1251 | 1233 | ||
1252 | For example, the machine configuration file for the `BeagleBone and | 1234 | For example, the machine configuration file for the `BeagleBone and |
1253 | BeagleBone Black development boards <https://beagleboard.org/bone>`__ is | 1235 | BeagleBone Black development boards <https://beagleboard.org/bone>`__ is |
1254 | located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named | 1236 | located in :yocto_git:`poky/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf |
1255 | ``beaglebone-yocto.conf``: :: | 1237 | </poky/tree/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf>`:: |
1256 | 1238 | ||
1257 | #@TYPE: Machine | 1239 | #@TYPE: Machine |
1258 | #@NAME: Beaglebone-yocto machine | 1240 | #@NAME: Beaglebone-yocto machine |
1259 | #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards | 1241 | #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards |
1260 | 1242 | ||
1261 | PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg" | 1243 | PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg" |
1262 | XSERVER ?= "xserver-xorg \ | ||
1263 | xf86-video-modesetting \ | ||
1264 | " | ||
1265 | 1244 | ||
1266 | MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree" | 1245 | MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree" |
1267 | 1246 | ||
1268 | EXTRA_IMAGEDEPENDS += "u-boot" | 1247 | EXTRA_IMAGEDEPENDS += "virtual/bootloader" |
1269 | 1248 | ||
1270 | DEFAULTTUNE ?= "cortexa8hf-neon" | 1249 | DEFAULTTUNE ?= "cortexa8hf-neon" |
1271 | include conf/machine/include/tune-cortexa8.inc | 1250 | include conf/machine/include/arm/armv7a/tune-cortexa8.inc |
1272 | 1251 | ||
1273 | IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" | 1252 | IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" |
1274 | EXTRA_IMAGECMD_jffs2 = "-lnp " | 1253 | EXTRA_IMAGECMD:jffs2 = "-lnp " |
1275 | WKS_FILE ?= "beaglebone-yocto.wks" | 1254 | WKS_FILE ?= "beaglebone-yocto.wks" |
1276 | IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage" | 1255 | MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-image kernel-devicetree" |
1277 | do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot" | 1256 | do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot virtual/bootloader:do_deploy" |
1278 | 1257 | ||
1279 | SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0" | 1258 | SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0 115200;ttyAMA0" |
1280 | SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}" | ||
1281 | 1259 | ||
1282 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | 1260 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
1283 | PREFERRED_VERSION_linux-yocto ?= "5.0%" | 1261 | PREFERRED_VERSION_linux-yocto ?= "6.1%" |
1284 | 1262 | ||
1285 | KERNEL_IMAGETYPE = "zImage" | 1263 | KERNEL_IMAGETYPE = "zImage" |
1286 | KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" | 1264 | KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" |
1287 | KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" | 1265 | KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" |
1288 | 1266 | ||
1267 | PREFERRED_PROVIDER_virtual/bootloader ?= "u-boot" | ||
1268 | |||
1289 | SPL_BINARY = "MLO" | 1269 | SPL_BINARY = "MLO" |
1290 | UBOOT_SUFFIX = "img" | 1270 | UBOOT_SUFFIX = "img" |
1291 | UBOOT_MACHINE = "am335x_evm_defconfig" | 1271 | UBOOT_MACHINE = "am335x_evm_defconfig" |
@@ -1294,7 +1274,24 @@ located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named | |||
1294 | 1274 | ||
1295 | MACHINE_FEATURES = "usbgadget usbhost vfat alsa" | 1275 | MACHINE_FEATURES = "usbgadget usbhost vfat alsa" |
1296 | 1276 | ||
1297 | IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" | 1277 | IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} ${SPL_BINARY} ${KERNEL_IMAGETYPE} ${KERNEL_DEVICETREE}" |
1278 | |||
1279 | # support runqemu | ||
1280 | EXTRA_IMAGEDEPENDS += "qemu-native qemu-helper-native" | ||
1281 | IMAGE_CLASSES += "qemuboot" | ||
1282 | QB_DEFAULT_FSTYPE = "wic" | ||
1283 | QB_FSINFO = "wic:no-kernel-in-fs" | ||
1284 | QB_KERNEL_ROOT = "/dev/vda2" | ||
1285 | QB_SYSTEM_NAME = "qemu-system-arm" | ||
1286 | QB_MACHINE = "-machine virt" | ||
1287 | QB_CPU = "-cpu cortex-a15" | ||
1288 | QB_KERNEL_CMDLINE_APPEND = "console=ttyAMA0 systemd.mask=systemd-networkd" | ||
1289 | QB_OPT_APPEND = "-device virtio-rng-device" | ||
1290 | QB_TAP_OPT = "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no" | ||
1291 | QB_NETWORK_DEVICE = "-device virtio-net-device,netdev=net0,mac=@MAC@" | ||
1292 | QB_ROOTFS_OPT = "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0" | ||
1293 | QB_SERIAL_OPT = "" | ||
1294 | QB_TCPSERIAL_OPT = "-device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon" | ||
1298 | 1295 | ||
1299 | The variables used to configure the machine define machine-specific properties; for | 1296 | The variables used to configure the machine define machine-specific properties; for |
1300 | example, machine-dependent packages, machine tunings, the type of kernel | 1297 | example, machine-dependent packages, machine tunings, the type of kernel |
@@ -1311,14 +1308,9 @@ Project Reference Manual. | |||
1311 | - :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`: | 1308 | - :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`: |
1312 | The recipe that provides "virtual/xserver" when more than one | 1309 | The recipe that provides "virtual/xserver" when more than one |
1313 | provider is found. In this case, the recipe that provides | 1310 | provider is found. In this case, the recipe that provides |
1314 | "virtual/xserver" is "xserver-xorg", which exists in | 1311 | "virtual/xserver" is "xserver-xorg", available in |
1315 | ``poky/meta/recipes-graphics/xorg-xserver``. | 1312 | ``poky/meta/recipes-graphics/xorg-xserver``. |
1316 | 1313 | ||
1317 | - :term:`XSERVER`: The packages that | ||
1318 | should be installed to provide an X server and drivers for the | ||
1319 | machine. In this example, the "xserver-xorg" and | ||
1320 | "xf86-video-modesetting" are installed. | ||
1321 | |||
1322 | - :term:`MACHINE_EXTRA_RRECOMMENDS`: | 1314 | - :term:`MACHINE_EXTRA_RRECOMMENDS`: |
1323 | A list of machine-dependent packages not essential for booting the | 1315 | A list of machine-dependent packages not essential for booting the |
1324 | image. Thus, the build does not fail if the packages do not exist. | 1316 | image. Thus, the build does not fail if the packages do not exist. |
@@ -1326,7 +1318,7 @@ Project Reference Manual. | |||
1326 | 1318 | ||
1327 | .. tip:: | 1319 | .. tip:: |
1328 | 1320 | ||
1329 | Many ``MACHINE*`` variables exist that help you configure a particular piece | 1321 | There are many ``MACHINE*`` variables that help you configure a particular piece |
1330 | of hardware. | 1322 | of hardware. |
1331 | 1323 | ||
1332 | - :term:`EXTRA_IMAGEDEPENDS`: | 1324 | - :term:`EXTRA_IMAGEDEPENDS`: |
@@ -1336,17 +1328,20 @@ Project Reference Manual. | |||
1336 | needed in the root filesystem. In this case, the U-Boot recipe must | 1328 | needed in the root filesystem. In this case, the U-Boot recipe must |
1337 | be built for the image. | 1329 | be built for the image. |
1338 | 1330 | ||
1331 | At the end of the file, we also use this setings to implement | ||
1332 | ``runqemu`` support on the host machine. | ||
1333 | |||
1339 | - :term:`DEFAULTTUNE`: Machines | 1334 | - :term:`DEFAULTTUNE`: Machines |
1340 | use tunings to optimize machine, CPU, and application performance. | 1335 | use tunings to optimize machine, CPU, and application performance. |
1341 | These features, which are collectively known as "tuning features", | 1336 | These features, which are collectively known as "tuning features", |
1342 | exist in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g. | 1337 | are set in the :term:`OpenEmbedded-Core (OE-Core)` layer. In this |
1343 | ``poky/meta/conf/machine/include``). In this example, the default | 1338 | example, the default tuning file is :oe_git:`tune-cortexa8 |
1344 | tuning file is "cortexa8hf-neon". | 1339 | </openembedded-core/tree/meta/conf/machine/include/arm/armv7a/tune-cortexa8.inc>`. |
1345 | 1340 | ||
1346 | .. note:: | 1341 | .. note:: |
1347 | 1342 | ||
1348 | The include statement that pulls in the | 1343 | The include statement that pulls in the |
1349 | ``conf/machine/include/tune-cortexa8.inc`` file provides many tuning | 1344 | ``conf/machine/include/arm/tune-cortexa8.inc`` file provides many tuning |
1350 | possibilities. | 1345 | possibilities. |
1351 | 1346 | ||
1352 | - :term:`IMAGE_FSTYPES`: The | 1347 | - :term:`IMAGE_FSTYPES`: The |
@@ -1357,17 +1352,11 @@ Project Reference Manual. | |||
1357 | - :term:`EXTRA_IMAGECMD`: | 1352 | - :term:`EXTRA_IMAGECMD`: |
1358 | Specifies additional options for image creation commands. In this | 1353 | Specifies additional options for image creation commands. In this |
1359 | example, the "-lnp " option is used when creating the | 1354 | example, the "-lnp " option is used when creating the |
1360 | `JFFS2 <https://en.wikipedia.org/wiki/JFFS2>`__ image. | 1355 | :wikipedia:`JFFS2 <JFFS2>` image. |
1361 | 1356 | ||
1362 | - :term:`WKS_FILE`: The location of | 1357 | - :term:`WKS_FILE`: The location of |
1363 | the :ref:`Wic kickstart <ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used | 1358 | the :ref:`Wic kickstart <ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used |
1364 | by the OpenEmbedded build system to create a partitioned image | 1359 | by the OpenEmbedded build system to create a partitioned image. |
1365 | (image.wic). | ||
1366 | |||
1367 | - :term:`IMAGE_INSTALL`: | ||
1368 | Specifies packages to install into an image through the | ||
1369 | :ref:`image <ref-classes-image>` class. Recipes | ||
1370 | use the ``IMAGE_INSTALL`` variable. | ||
1371 | 1360 | ||
1372 | - ``do_image_wic[depends]``: A task that is constructed during the | 1361 | - ``do_image_wic[depends]``: A task that is constructed during the |
1373 | build. In this example, the task depends on specific tools in order | 1362 | build. In this example, the task depends on specific tools in order |
@@ -1385,7 +1374,7 @@ Project Reference Manual. | |||
1385 | 1374 | ||
1386 | - :term:`PREFERRED_VERSION_linux-yocto <PREFERRED_VERSION>`: | 1375 | - :term:`PREFERRED_VERSION_linux-yocto <PREFERRED_VERSION>`: |
1387 | Defines the version of the recipe used to build the kernel, which is | 1376 | Defines the version of the recipe used to build the kernel, which is |
1388 | "5.0" in this case. | 1377 | "6.1" in this case. |
1389 | 1378 | ||
1390 | - :term:`KERNEL_IMAGETYPE`: | 1379 | - :term:`KERNEL_IMAGETYPE`: |
1391 | The type of kernel to build for the device. In this case, the | 1380 | The type of kernel to build for the device. In this case, the |
@@ -1407,7 +1396,7 @@ Project Reference Manual. | |||
1407 | 1396 | ||
1408 | The BeagleBone development board requires an SPL to boot and that SPL | 1397 | The BeagleBone development board requires an SPL to boot and that SPL |
1409 | file type must be MLO. Consequently, the machine configuration needs | 1398 | file type must be MLO. Consequently, the machine configuration needs |
1410 | to define ``SPL_BINARY`` as ``MLO``. | 1399 | to define :term:`SPL_BINARY` as ``MLO``. |
1411 | 1400 | ||
1412 | .. note:: | 1401 | .. note:: |
1413 | 1402 | ||
@@ -1447,42 +1436,38 @@ BSP Kernel Recipe Example | |||
1447 | ------------------------- | 1436 | ------------------------- |
1448 | 1437 | ||
1449 | The kernel recipe used to build the kernel image for the BeagleBone | 1438 | The kernel recipe used to build the kernel image for the BeagleBone |
1450 | device was established in the machine configuration: :: | 1439 | device was established in the machine configuration:: |
1451 | 1440 | ||
1452 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | 1441 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
1453 | PREFERRED_VERSION_linux-yocto ?= "5.0%" | 1442 | PREFERRED_VERSION_linux-yocto ?= "6.1%" |
1454 | 1443 | ||
1455 | The ``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains | 1444 | The ``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains |
1456 | metadata used to build the kernel. In this case, a kernel append file | 1445 | metadata used to build the kernel. In this case, a kernel append file |
1457 | (i.e. ``linux-yocto_5.0.bbappend``) is used to override an established | 1446 | (i.e. ``linux-yocto_6.1.bbappend``) is used to override an established |
1458 | kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in | 1447 | kernel recipe (i.e. ``linux-yocto_6.1.bb``), which is located in |
1459 | :yocto_git:`/poky/tree/meta/recipes-kernel/linux`. | 1448 | :yocto_git:`/poky/tree/meta/recipes-kernel/linux`. |
1460 | 1449 | ||
1461 | Following is the contents of the append file: :: | 1450 | The contents of the append file are:: |
1462 | 1451 | ||
1463 | KBRANCH_genericx86 = "v5.0/standard/base" | 1452 | KBRANCH:genericx86 = "v6.1/standard/base" |
1464 | KBRANCH_genericx86-64 = "v5.0/standard/base" | 1453 | KBRANCH:genericx86-64 = "v6.1/standard/base" |
1465 | KBRANCH_edgerouter = "v5.0/standard/edgerouter" | 1454 | KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" |
1466 | KBRANCH_beaglebone-yocto = "v5.0/standard/beaglebone" | ||
1467 | 1455 | ||
1468 | KMACHINE_genericx86 ?= "common-pc" | 1456 | KMACHINE:genericx86 ?= "common-pc" |
1469 | KMACHINE_genericx86-64 ?= "common-pc-64" | 1457 | KMACHINE:genericx86-64 ?= "common-pc-64" |
1470 | KMACHINE_beaglebone-yocto ?= "beaglebone" | 1458 | KMACHINE:beaglebone-yocto ?= "beaglebone" |
1471 | 1459 | ||
1472 | SRCREV_machine_genericx86 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" | 1460 | SRCREV_machine:genericx86 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" |
1473 | SRCREV_machine_genericx86-64 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" | 1461 | SRCREV_machine:genericx86-64 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" |
1474 | SRCREV_machine_edgerouter ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" | 1462 | SRCREV_machine:beaglebone-yocto ?= "423e1996694b61fbfc8ec3bf062fc6461d64fde1" |
1475 | SRCREV_machine_beaglebone-yocto ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" | ||
1476 | 1463 | ||
1477 | COMPATIBLE_MACHINE_genericx86 = "genericx86" | 1464 | COMPATIBLE_MACHINE:genericx86 = "genericx86" |
1478 | COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" | 1465 | COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64" |
1479 | COMPATIBLE_MACHINE_edgerouter = "edgerouter" | 1466 | COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto" |
1480 | COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto" | ||
1481 | 1467 | ||
1482 | LINUX_VERSION_genericx86 = "5.0.3" | 1468 | LINUX_VERSION:genericx86 = "6.1.30" |
1483 | LINUX_VERSION_genericx86-64 = "5.0.3" | 1469 | LINUX_VERSION:genericx86-64 = "6.1.30" |
1484 | LINUX_VERSION_edgerouter = "5.0.3" | 1470 | LINUX_VERSION:beaglebone-yocto = "6.1.20" |
1485 | LINUX_VERSION_beaglebone-yocto = "5.0.3" | ||
1486 | 1471 | ||
1487 | This particular append file works for all the machines that are | 1472 | This particular append file works for all the machines that are |
1488 | part of the ``meta-yocto-bsp`` layer. The relevant statements are | 1473 | part of the ``meta-yocto-bsp`` layer. The relevant statements are |