diff options
Diffstat (limited to 'documentation/bsp-guide/bsp.rst')
| -rw-r--r-- | documentation/bsp-guide/bsp.rst | 452 |
1 files changed, 210 insertions, 242 deletions
diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst index 024a240c22..11ca5d8b76 100644 --- a/documentation/bsp-guide/bsp.rst +++ b/documentation/bsp-guide/bsp.rst @@ -1,8 +1,8 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK -************************************************ -Board Support Packages (BSP) - Developer's Guide -************************************************ +************************************************** +Board Support Packages (BSP) --- Developer's Guide +************************************************** A Board Support Package (BSP) is a collection of information that defines how to support a particular hardware device, set of devices, or @@ -26,25 +26,25 @@ A BSP consists of a file structure inside a base directory. Collectively, you can think of the base directory, its file structure, and the contents as a BSP layer. Although not a strict requirement, BSP layers in the Yocto Project use the following well-established naming -convention: :: +convention:: meta-bsp_root_name The string "meta-" is prepended to the -machine or platform name, which is bsp_root_name in the above form. +machine or platform name, which is "bsp_root_name" in the above form. .. note:: Because the BSP layer naming convention is well-established, it is advisable to follow it when creating layers. Technically speaking, a - BSP layer name does not need to start with - meta-. However, various scripts and tools in the Yocto Project development + BSP layer name does not need to start with ``meta-``. + However, various scripts and tools in the Yocto Project development environment assume this convention. To help understand the BSP layer concept, consider the BSPs that the Yocto Project supports and provides with each release. You can see the layers in the -:ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` +:ref:`overview-manual/development-environment:yocto project source repositories` through a web interface at :yocto_git:`/`. If you go to that interface, you will find a list of repositories under "Yocto Metadata Layers". @@ -58,21 +58,21 @@ Each repository is a BSP layer supported by the Yocto Project (e.g. ``meta-raspberrypi`` and ``meta-intel``). Each of these layers is a repository unto itself and clicking on the layer name displays two URLs from which you can clone the layer's repository to your local system. -Here is an example that clones the Raspberry Pi BSP layer: :: +Here is an example that clones the Raspberry Pi BSP layer:: $ git clone git://git.yoctoproject.org/meta-raspberrypi In addition to BSP layers, the ``meta-yocto-bsp`` layer is part of the shipped ``poky`` repository. The ``meta-yocto-bsp`` layer maintains -several "reference" BSPs including the ARM-based Beaglebone, MIPS-based -EdgeRouter, and generic versions of both 32-bit and 64-bit IA machines. +several "reference" BSPs including the ARM-based Beaglebone and generic +versions of both 32-bit and 64-bit IA machines. For information on typical BSP development workflow, see the :ref:`bsp-guide/bsp:developing a board support package (bsp)` section. For more information on how to set up a local copy of source files from a Git repository, see the -:ref:`dev-manual/dev-manual-start:locating yocto project source files` +:ref:`dev-manual/start:locating yocto project source files` section in the Yocto Project Development Tasks Manual. The BSP layer's base directory (``meta-bsp_root_name``) is the root @@ -81,10 +81,10 @@ directory of that Layer. This directory is what you add to the ``conf/bblayers.conf`` file found in your :term:`Build Directory`, which is established after you run the OpenEmbedded build environment setup -script (i.e. :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\`` ). +script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). Adding the root directory allows the :term:`OpenEmbedded Build System` to recognize the BSP -layer and from it build an image. Here is an example: :: +layer and from it build an image. Here is an example:: BBLAYERS ?= " \ /usr/local/src/yocto/meta \ @@ -95,10 +95,11 @@ layer and from it build an image. Here is an example: :: .. note:: - Ordering and ``BBFILE_PRIORITY`` for the layers listed in BBLAYERS matter. For - example, if multiple layers define a machine configuration, the OpenEmbedded - build system uses the last layer searched given similar layer priorities. The - build system works from the top-down through the layers listed in ``BBLAYERS``. + Ordering and :term:`BBFILE_PRIORITY` for the layers listed in :term:`BBLAYERS` + matter. For example, if multiple layers define a machine configuration, the + OpenEmbedded build system uses the last layer searched given similar layer + priorities. The build system works from the top-down through the layers + listed in :term:`BBLAYERS`. Some BSPs require or depend on additional layers beyond the BSP's root layer in order to be functional. In this case, you need to specify these @@ -107,12 +108,11 @@ Additionally, if any build instructions exist for the BSP, you must add them to the "Dependencies" section. Some layers function as a layer to hold other BSP layers. These layers -are knows as ":term:`container layers <Container Layer>`". An example of -this type of layer is OpenEmbedded's -`meta-openembedded <https://github.com/openembedded/meta-openembedded>`__ +are known as ":term:`container layers <Container Layer>`". An example of +this type of layer is OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>` layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers. In cases like this, you need to include the names of the actual layers -you want to work with, such as: :: +you want to work with, such as:: BBLAYERS ?= " \ /usr/local/src/yocto/meta \ @@ -127,7 +127,7 @@ you want to work with, such as: :: and so on. For more information on layers, see the -":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" +":ref:`dev-manual/layers:understanding and creating layers`" section of the Yocto Project Development Tasks Manual. Preparing Your Build Host to Work With BSP Layers @@ -141,22 +141,22 @@ section. .. note:: - For structural information on BSPs, see the Example Filesystem Layout - section. + For structural information on BSPs, see the + :ref:`bsp-guide/bsp:example filesystem layout` section. #. *Set Up the Build Environment:* Be sure you are set up to use BitBake - in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" + in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section in the Yocto Project Development Tasks Manual for information on how to get a build host ready that is either a native Linux machine or a machine that uses CROPS. -#. *Clone the ``poky`` Repository:* You need to have a local copy of the +#. *Clone the poky Repository:* You need to have a local copy of the Yocto Project :term:`Source Directory` (i.e. a local ``poky`` repository). See the - "ref:`dev-manual/dev-manual-start:cloning the ``poky`` repository`" and + ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and possibly the - ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" or - ":ref:`dev-manual/dev-manual-start:checking out by tag in poky`" + ":ref:`dev-manual/start:checking out by branch in poky`" or + ":ref:`dev-manual/start:checking out by tag in poky`" sections all in the Yocto Project Development Tasks Manual for information on how to clone the ``poky`` repository and check out the appropriate @@ -165,14 +165,14 @@ section. #. *Determine the BSP Layer You Want:* The Yocto Project supports many BSPs, which are maintained in their own layers or in layers designed to contain several BSPs. To get an idea of machine support through - BSP layers, you can look at the `index of - machines <&YOCTO_RELEASE_DL_URL;/machines>`__ for the release. + BSP layers, you can look at the + :yocto_dl:`index of machines </releases/yocto/yocto-&DISTRO;/machines>` + for the release. -#. *Optionally Clone the ``meta-intel`` BSP Layer:* If your hardware is +#. *Optionally Clone the meta-intel BSP Layer:* If your hardware is based on current Intel CPUs and devices, you can leverage this BSP layer. For details on the ``meta-intel`` BSP layer, see the layer's - `README <http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README>`__ - file. + :yocto_git:`README </meta-intel/tree/README>` file. #. *Navigate to Your Source Directory:* Typically, you set up the ``meta-intel`` Git repository inside the :term:`Source Directory` (e.g. @@ -193,7 +193,7 @@ section. #. *Check Out the Proper Branch:* The branch you check out for ``meta-intel`` must match the same branch you are using for the - Yocto Project release (e.g. &DISTRO_NAME_NO_CAP;): :: + Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``):: $ cd meta-intel $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; @@ -205,7 +205,7 @@ section. To see the available branch names in a cloned repository, use the ``git branch -al`` command. See the - ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" + ":ref:`dev-manual/start:checking out by branch in poky`" section in the Yocto Project Development Tasks Manual for more information. @@ -216,7 +216,7 @@ section. The process is identical to the process used for the ``meta-intel`` layer except for the layer's name. For example, if you determine that your hardware most closely matches the ``meta-raspberrypi``, clone - that layer: :: + that layer:: $ git clone git://git.yoctoproject.org/meta-raspberrypi Cloning into 'meta-raspberrypi'... @@ -229,19 +229,17 @@ section. #. *Initialize the Build Environment:* While in the root directory of the Source Directory (i.e. ``poky``), run the - :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\`` environment + :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment setup script to define the OpenEmbedded build environment on your build host. :: - $ source &OE_INIT_FILE; + $ source oe-init-build-env Among other things, the script creates the :term:`Build Directory`, which is ``build`` in this case and is located in the :term:`Source Directory`. After the script runs, your current working directory is set to the ``build`` directory. -.. _bsp-filelayout: - Example Filesystem Layout ========================= @@ -252,10 +250,10 @@ standardization of software support for hardware. The proposed form described in this section does have elements that are specific to the OpenEmbedded build system. It is intended that developers can use this structure with other build systems besides the -OpenEmbedded build system. It is also intended that it will be be simple +OpenEmbedded build system. It is also intended that it will be simple to extract information and convert it to other formats if required. The OpenEmbedded build system, through its standard :ref:`layers mechanism -<overview-manual/overview-manual-yp-intro:the yocto project layer model>`, can +<overview-manual/yp-intro:the yocto project layer model>`, can directly accept the format described as a layer. The BSP layer captures all the hardware-specific details in one place using a standard format, which is useful for any person wishing to use the hardware platform @@ -269,7 +267,7 @@ maintain the distinction that the BSP layer, a build system, and tools are separate components that could be combined in certain end products. Before looking at the recommended form for the directory structure -inside a BSP layer, you should be aware that some requirements do exist +inside a BSP layer, you should be aware that there are some requirements in order for a BSP layer to be considered compliant with the Yocto Project. For that list of requirements, see the ":ref:`bsp-guide/bsp:released bsp requirements`" section. @@ -291,7 +289,9 @@ individual BSPs could differ. :: meta-bsp_root_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend Below is an example of the Raspberry Pi BSP layer that is available from -the :yocto_git:`Source Respositories <>`: :: +the :yocto_git:`Source Repositories <>`: + +.. code-block:: none meta-raspberrypi/COPYING.MIT meta-raspberrypi/README.md @@ -336,7 +336,7 @@ the :yocto_git:`Source Respositories <>`: :: meta-raspberrypi/recipes-bsp/formfactor/formfactor meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig - meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend + meta-raspberrypi/recipes-bsp/formfactor/formfactor_%.bbappend meta-raspberrypi/recipes-bsp/rpi-u-boot-src meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in @@ -448,12 +448,10 @@ the :yocto_git:`Source Respositories <>`: :: The following sections describe each part of the proposed BSP format. -.. _bsp-filelayout-license: - License Files ------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/bsp_license_file @@ -465,15 +463,13 @@ requirements are handled with the ``COPYING.MIT`` file. Licensing files can be MIT, BSD, GPLv*, and so forth. These files are recommended for the BSP but are optional and totally up to the BSP developer. For information on how to maintain license compliance, see -the ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" +the ":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" section in the Yocto Project Development Tasks Manual. -.. _bsp-filelayout-readme: - README File ----------- -You can find this file in the BSP Layer at: :: +You can find this file in the BSP Layer at:: meta-bsp_root_name/README @@ -485,12 +481,10 @@ At a minimum, the ``README`` file must contain a list of dependencies, such as the names of any other layers on which the BSP depends and the name of the BSP maintainer with his or her contact information. -.. _bsp-filelayout-readme-sources: - README.sources File ------------------- -You can find this file in the BSP Layer at: :: +You can find this file in the BSP Layer at:: meta-bsp_root_name/README.sources @@ -506,12 +500,10 @@ used to generate the images that ship with the BSP. If the BSP's ``binary`` directory is missing or the directory has no images, an existing ``README.sources`` file is meaningless and usually does not exist. -.. _bsp-filelayout-binary: - Pre-built User Binaries ----------------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/binary/bootable_images @@ -531,12 +523,10 @@ hardware. Additionally, the present to locate the sources used to build the images and provide information on the Metadata. -.. _bsp-filelayout-layer: - Layer Configuration File ------------------------ -You can find this file in the BSP Layer at: :: +You can find this file in the BSP Layer at:: meta-bsp_root_name/conf/layer.conf @@ -544,13 +534,13 @@ The ``conf/layer.conf`` file identifies the file structure as a layer, identifies the contents of the layer, and contains information about how the build system should use it. Generally, a standard boilerplate file such as the following works. In the following example, you would replace -bsp with the actual name of the BSP (i.e. bsp_root_name from the example +"bsp" with the actual name of the BSP (i.e. "bsp_root_name" from the example template). :: # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" - # We have a recipes directory, add to BBFILES + # We have a recipes directory containing .bb and .bbappend files, add to BBFILES BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ ${LAYERDIR}/recipes-*/*/*.bbappend" @@ -560,7 +550,7 @@ template). :: LAYERDEPENDS_bsp = "intel" To illustrate the string substitutions, here are the corresponding -statements from the Raspberry Pi ``conf/layer.conf`` file: :: +statements from the Raspberry Pi ``conf/layer.conf`` file:: # We have a conf and classes directory, append to BBPATH BBPATH .= ":${LAYERDIR}" @@ -583,12 +573,10 @@ This file simply makes :term:`BitBake` aware of the recipes and configuration directories. The file must exist so that the OpenEmbedded build system can recognize the BSP. -.. _bsp-filelayout-machine: - Hardware Configuration Options ------------------------------ -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/conf/machine/*.conf @@ -601,7 +589,7 @@ filenames correspond to the values to which users have set the These files define things such as the kernel package to use (:term:`PREFERRED_PROVIDER` of -:ref:`virtual/kernel <dev-manual/dev-manual-common-tasks:using virtual providers>`), +:ref:`virtual/kernel <dev-manual/new-recipe:using virtual providers>`), the hardware drivers to include in different types of images, any special software components that are needed, any bootloader information, and also any special image format requirements. @@ -619,26 +607,24 @@ For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``, To use an include file, you simply include them in the machine configuration file. For example, the Raspberry Pi BSP -``raspberrypi3.conf`` contains the following statement: :: +``raspberrypi3.conf`` contains the following statement:: include conf/machine/include/rpi-base.inc -.. _bsp-filelayout-misc-recipes: - Miscellaneous BSP-Specific Recipe Files --------------------------------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/recipes-bsp/* This optional directory contains miscellaneous recipe files for the BSP. Most notably would be the formfactor files. For example, in the -Raspberry Pi BSP, there is the ``formfactor_0.0.bbappend`` file, which +Raspberry Pi BSP, there is the ``formfactor_%.bbappend`` file, which is an append file used to augment the recipe that starts the build. Furthermore, there are machine-specific settings used during the build that are defined by the ``machconfig`` file further down in the -directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: :: +directory. Here is the ``machconfig`` file for the Raspberry Pi BSP:: HAVE_TOUCHSCREEN=0 HAVE_KEYBOARD=1 @@ -655,12 +641,10 @@ directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: :: ``meta/recipes-bsp/formfactor/formfactor_0.0.bb``, which is found in the :term:`Source Directory`. -.. _bsp-filelayout-recipes-graphics: - Display Support Files --------------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/recipes-graphics/* @@ -668,12 +652,10 @@ This optional directory contains recipes for the BSP if it has special requirements for graphics support. All files that are needed for the BSP to support a display are kept here. -.. _bsp-filelayout-kernel: - Linux Kernel Configuration -------------------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/recipes-kernel/linux/linux*.bbappend meta-bsp_root_name/recipes-kernel/linux/*.bb @@ -694,29 +676,29 @@ located in the BSP Layer for your target device (e.g. the Suppose you are using the ``linux-yocto_4.4.bb`` recipe to build the kernel. In other words, you have selected the kernel in your -bsp_root_name\ ``.conf`` file by adding +``"bsp_root_name".conf`` file by adding :term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` -statements as follows: :: +statements as follows:: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" PREFERRED_VERSION_linux-yocto ?= "4.4%" .. note:: - When the preferred provider is assumed by default, the ``PREFERRED_PROVIDER`` - statement does not appear in the ``bsp_root_name`` .conf file. + When the preferred provider is assumed by default, the :term:`PREFERRED_PROVIDER` + statement does not appear in the ``"bsp_root_name".conf`` file. You would use the ``linux-yocto_4.4.bbappend`` file to append specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. You can find more information on what your append file should contain in -the ":ref:`kernel-dev/kernel-dev-common:creating the append file`" section +the ":ref:`kernel-dev/common:creating the append file`" section in the Yocto Project Linux Kernel Development Manual. An alternate scenario is when you create your own kernel recipe for the BSP. A good example of this is the Raspberry Pi BSP. If you examine the -``recipes-kernel/linux`` directory you see the following: :: +``recipes-kernel/linux`` directory you see the following:: linux-raspberrypi-dev.bb linux-raspberrypi.inc @@ -742,9 +724,10 @@ workflow. .. image:: figures/bsp-dev-flow.png :align: center + :width: 70% #. *Set up Your Host Development System to Support Development Using the - Yocto Project*: See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" + Yocto Project*: See the ":ref:`dev-manual/start:preparing the build host`" section in the Yocto Project Development Tasks Manual for options on how to get a system ready to use the Yocto Project. @@ -772,38 +755,22 @@ workflow. are kept. The key point for a layer is that it is an isolated area that contains all the relevant information for the project that the OpenEmbedded build system knows about. For more information on - layers, see the ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`" + layers, see the ":ref:`overview-manual/yp-intro:the yocto project layer model`" section in the Yocto Project Overview and Concepts Manual. You can also - reference the ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" + reference the ":ref:`dev-manual/layers:understanding and creating layers`" section in the Yocto Project Development Tasks Manual. For more information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" section. .. note:: - - Five hardware reference BSPs exist that are part of the Yocto - Project release and are located in the ``poky/meta-yocto-bsp`` + - There are three hardware reference BSPs in the Yocto + Project release, located in the ``poky/meta-yocto-bsp`` BSP layer: - Texas Instruments Beaglebone (``beaglebone-yocto``) - - Ubiquiti Networks EdgeRouter Lite (``edgerouter``) - - - Two general IA platforms (``genericx86`` and ``genericx86-64``) - - - Three core Intel BSPs exist as part of the Yocto Project - release in the ``meta-intel`` layer: - - - ``intel-core2-32``, which is a BSP optimized for the Core2 - family of CPUs as well as all CPUs prior to the Silvermont - core. - - - ``intel-corei7-64``, which is a BSP optimized for Nehalem - and later Core and Xeon CPUs as well as Silvermont and later - Atom CPUs, such as the Baytrail SoCs. - - - ``intel-quark``, which is a BSP optimized for the Intel - Galileo gen1 & gen2 development boards. + - Two generic IA platforms (``genericx86`` and ``genericx86-64``) When you set up a layer for a new BSP, you should follow a standard layout. This layout is described in the ":ref:`bsp-guide/bsp:example filesystem layout`" @@ -833,7 +800,7 @@ workflow. key configuration files are configured appropriately: the ``conf/local.conf`` and the ``conf/bblayers.conf`` file. You must make the OpenEmbedded build system aware of your new layer. See the - ":ref:`dev-manual/dev-manual-common-tasks:enabling your layer`" + ":ref:`dev-manual/layers:enabling your layer`" section in the Yocto Project Development Tasks Manual for information on how to let the build system know about your new layer. @@ -844,16 +811,14 @@ workflow. The build process supports several types of images to satisfy different needs. See the - ":ref:`ref-manual/ref-images:Images`" chapter in the Yocto + ":ref:`ref-manual/images:Images`" chapter in the Yocto Project Reference Manual for information on supported images. Requirements and Recommendations for Released BSPs ================================================== -Certain requirements exist for a released BSP to be considered compliant -with the Yocto Project. Additionally, recommendations also exist. This -section describes the requirements and recommendations for released -BSPs. +This section describes requirements and recommendations for a released +BSP to be considered compliant with the Yocto Project. Released BSP Requirements ------------------------- @@ -864,14 +829,14 @@ Before looking at BSP requirements, you should consider the following: layer that can be added to the Yocto Project. For guidelines on creating a layer that meets these base requirements, see the ":ref:`bsp-guide/bsp:bsp layers`" section in this manual and the - ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" + ":ref:`dev-manual/layers:understanding and creating layers`" section in the Yocto Project Development Tasks Manual. - The requirements in this section apply regardless of how you package a BSP. You should consult the packaging and distribution guidelines for your specific release process. For an example of packaging and - distribution requirements, see the "`Third Party BSP Release - Process <https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process>`__" + distribution requirements, see the ":yocto_wiki:`Third Party BSP Release + Process </Third_Party_BSP_Release_Process>`" wiki page. - The requirements for the BSP as it is made available to a developer @@ -882,12 +847,11 @@ Before looking at BSP requirements, you should consider the following: - It is not required that specific packages or package modifications exist in the BSP layer, beyond the requirements for general - compliance with the Yocto Project. For example, no requirement exists + compliance with the Yocto Project. For example, there is no requirement dictating that a specific kernel or kernel version be used in a given BSP. -Following are the requirements for a released BSP that conform to the -Yocto Project: +The requirements for a released BSP that conform to the Yocto Project are: - *Layer Name:* The BSP must have a layer name that follows the Yocto Project standards. For information on BSP layer names, see the @@ -897,7 +861,7 @@ Yocto Project: your BSP layer as listed in the ``recipes.txt`` file, which is found in ``poky/meta`` directory of the :term:`Source Directory` or in the OpenEmbedded-Core Layer (``openembedded-core``) at - http://git.openembedded.org/openembedded-core/tree/meta. + :oe_git:`/openembedded-core/tree/meta`. You should place recipes (``*.bb`` files) and recipe modifications (``*.bbappend`` files) into ``recipes-*`` subdirectories by @@ -912,20 +876,20 @@ Yocto Project: ``recipes-*`` subdirectories specific to the recipe's function, or within a subdirectory containing a set of closely-related recipes. The recipes themselves should follow the general guidelines for - recipes used in the Yocto Project found in the "`OpenEmbedded Style - Guide <http://openembedded.org/wiki/Styleguide>`__". + recipes found in the ":doc:`../contributor-guide/recipe-style-guide`" + in the Yocto Project and OpenEmbedded Contributor Guide. - *License File:* You must include a license file in the ``meta-bsp_root_name`` directory. This license covers the BSP Metadata as a whole. You must specify which license to use since no - default license exists when one is not specified. See the - :yocto_git:`COPYING.MIT </cgit.cgi/meta-raspberrypi/tree/COPYING.MIT>` + default license exists. See the + :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>` file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer as an example. - *README File:* You must include a ``README`` file in the ``meta-bsp_root_name`` directory. See the - :yocto_git:`README.md </cgit.cgi/meta-raspberrypi/tree/README.md>` + :yocto_git:`README.md </meta-raspberrypi/tree/README.md>` file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer as an example. @@ -946,8 +910,8 @@ Yocto Project: - The name and contact information for the BSP layer maintainer. This is the person to whom patches and questions should be sent. For information on how to find the right person, see the - ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" - section in the Yocto Project Development Tasks Manual. + :doc:`../contributor-guide/submit-changes` section in the Yocto Project and + OpenEmbedded Contributor Guide. - Instructions on how to build the BSP using the BSP layer. @@ -991,7 +955,7 @@ Yocto Project: Released BSP Recommendations ---------------------------- -Following are recommendations for released BSPs that conform to the +Here are recommendations for released BSPs that conform to the Yocto Project: - *Bootable Images:* Released BSPs can contain one or more bootable @@ -1031,9 +995,9 @@ If you plan on customizing a recipe for a particular BSP, you need to do the following: - Create a ``*.bbappend`` file for the modified recipe. For information on using - append files, see the ":ref:`dev-manual/dev-manual-common-tasks:using - .bbappend files in your layer`" section in the Yocto Project Development - Tasks Manual. + append files, see the + ":ref:`dev-manual/layers:appending other layers metadata with your layer`" + section in the Yocto Project Development Tasks Manual. - Ensure your directory structure in the BSP layer that supports your machine is such that the OpenEmbedded build system can find it. See @@ -1053,29 +1017,29 @@ the following: that additional hierarchy and the files would obviously not be able to reside in a machine-specific directory. -Following is a specific example to help you better understand the -process. This example customizes customizes a recipe by adding a +Here is a specific example to help you better understand the +process. This example customizes a recipe by adding a BSP-specific configuration file named ``interfaces`` to the ``init-ifupdown_1.0.bb`` recipe for machine "xyz" where the BSP layer also supports several other machines: #. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the - following: :: + following:: - FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + FILESEXTRAPATHS:prepend := "${THISDIR}/files:" The append file needs to be in the ``meta-xyz/recipes-core/init-ifupdown`` directory. #. Create and place the new ``interfaces`` configuration file in the - BSP's layer here: :: + BSP's layer here:: meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces .. note:: - If the meta-xyz layer did not support multiple machines, you would place - the interfaces configuration file in the layer here: :: + If the ``meta-xyz`` layer did not support multiple machines, you would place + the interfaces configuration file in the layer here:: meta-xyz/recipes-core/init-ifupdown/files/interfaces @@ -1125,31 +1089,31 @@ system requirements. unsuitable functionality or quality, you can use an encumbered version. -A couple different methods exist within the OpenEmbedded build system to +There are two different methods within the OpenEmbedded build system to satisfy the licensing requirements for an encumbered BSP. The following list describes them in order of preference: #. *Use the LICENSE_FLAGS Variable to Define the Recipes that Have Commercial or Other Types of Specially-Licensed Packages:* For each of those recipes, you can specify a matching license string in a ``local.conf`` variable named - :term:`LICENSE_FLAGS_WHITELIST`. + :term:`LICENSE_FLAGS_ACCEPTED`. Specifying the matching license string signifies that you agree to the license. Thus, the build system can build the corresponding recipe and include the component in the image. See the - ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`" + ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" section in the Yocto Project Development Tasks Manual for details on how to use these variables. If you build as you normally would, without specifying any recipes in - the ``LICENSE_FLAGS_WHITELIST``, the build stops and provides you - with the list of recipes that you have tried to include in the image - that need entries in the ``LICENSE_FLAGS_WHITELIST``. Once you enter - the appropriate license flags into the whitelist, restart the build - to continue where it left off. During the build, the prompt will not - appear again since you have satisfied the requirement. + the :term:`LICENSE_FLAGS_ACCEPTED` variable, the build stops and provides + you with the list of recipes that you have tried to include in the image + that need entries in the :term:`LICENSE_FLAGS_ACCEPTED` variable. Once you + enter the appropriate license flags into it, restart the build to continue + where it left off. During the build, the prompt will not appear again since + you have satisfied the requirement. Once the appropriate license flags are on the white list in the - ``LICENSE_FLAGS_WHITELIST`` variable, you can build the encumbered + :term:`LICENSE_FLAGS_ACCEPTED` variable, you can build the encumbered image with no change at all to the normal build process. #. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by @@ -1162,7 +1126,7 @@ list describes them in order of preference: click-through license agreements presented by the website. If you want to build the image yourself using the recipes contained within the BSP tarball, you will still need to create an appropriate - ``LICENSE_FLAGS_WHITELIST`` to match the encumbered recipes in the + :term:`LICENSE_FLAGS_ACCEPTED` to match the encumbered recipes in the BSP. .. note:: @@ -1188,7 +1152,7 @@ Use these steps to create a BSP layer: ``create-layer`` subcommand to create a new general layer. For instructions on how to create a general layer using the ``bitbake-layers`` script, see the - ":ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" + ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" section in the Yocto Project Development Tasks Manual. - *Create a Layer Configuration File:* Every layer needs a layer @@ -1198,42 +1162,42 @@ Use these steps to create a BSP layer: :yocto_git:`Source Repositories <>`. To get examples of what you need in your configuration file, locate a layer (e.g. "meta-ti") and examine the - :yocto_git:`local.conf </cgit/cgit.cgi/meta-ti/tree/conf/layer.conf>` + :yocto_git:`local.conf </meta-ti/tree/meta-ti-bsp/conf/layer.conf>` file. - *Create a Machine Configuration File:* Create a ``conf/machine/bsp_root_name.conf`` file. See - :yocto_git:`meta-yocto-bsp/conf/machine </cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine>` - for sample ``bsp_root_name.conf`` files. Other samples such as - :yocto_git:`meta-ti </cgit/cgit.cgi/meta-ti/tree/conf/machine>` + :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>` + for sample ``bsp_root_name.conf`` files. There are other samples such as + :yocto_git:`meta-ti </meta-ti/tree/meta-ti-bsp/conf/machine>` and - :yocto_git:`meta-freescale </cgit/cgit.cgi/meta-freescale/tree/conf/machine>` - exist from other vendors that have more specific machine and tuning + :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>` + from other vendors that have more specific machine and tuning examples. - *Create a Kernel Recipe:* Create a kernel recipe in ``recipes-kernel/linux`` by either using a kernel append file or a - new custom kernel recipe file (e.g. ``yocto-linux_4.12.bb``). The BSP + new custom kernel recipe file (e.g. ``linux-yocto_4.12.bb``). The BSP layers mentioned in the previous step also contain different kernel - examples. See the ":ref:`kernel-dev/kernel-dev-common:modifying an existing recipe`" + examples. See the ":ref:`kernel-dev/common:modifying an existing recipe`" section in the Yocto Project Linux Kernel Development Manual for information on how to create a custom kernel. The remainder of this section provides a description of the Yocto Project reference BSP for Beaglebone, which resides in the -:yocto_git:`meta-yocto-bsp </cgit/cgit.cgi/poky/tree/meta-yocto-bsp>` +:yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>` layer. BSP Layer Configuration Example ------------------------------- The layer's ``conf`` directory contains the ``layer.conf`` configuration -file. In this example, the ``conf/layer.conf`` is the following: :: +file. In this example, the ``conf/layer.conf`` file is the following:: # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" - # We have recipes-\* directories, add to BBFILES + # We have a recipes directory containing .bb and .bbappend files, add to BBFILES BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ ${LAYERDIR}/recipes-*/*/*.bbappend" @@ -1248,7 +1212,7 @@ configuration files is to examine various files for BSP from the :yocto_git:`Source Repositories <>`. For a detailed description of this particular layer configuration file, -see ":ref:`step 3 <dev-manual/dev-manual-common-tasks:creating your own layer>`" +see ":ref:`step 3 <dev-manual/layers:creating your own layer>`" in the discussion that describes how to create layers in the Yocto Project Development Tasks Manual. @@ -1259,51 +1223,49 @@ As mentioned earlier in this section, the existence of a machine configuration file is what makes a layer a BSP layer as compared to a general or kernel layer. -One or more machine configuration files exist in the -``bsp_layer/conf/machine/`` directory of the layer: :: +There are one or more machine configuration files in the +``bsp_layer/conf/machine/`` directory of the layer:: - bsp_layer/conf/machine/machine1\.conf`` - bsp_layer/conf/machine/machine2\.conf`` - bsp_layer/conf/machine/machine3\.conf`` + bsp_layer/conf/machine/machine1\.conf + bsp_layer/conf/machine/machine2\.conf + bsp_layer/conf/machine/machine3\.conf ... more ... For example, the machine configuration file for the `BeagleBone and -BeagleBone Black development boards <http://beagleboard.org/bone>`__ is -located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named -``beaglebone-yocto.conf``: :: +BeagleBone Black development boards <https://beagleboard.org/bone>`__ is +located in :yocto_git:`poky/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf +</poky/tree/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf>`:: #@TYPE: Machine #@NAME: Beaglebone-yocto machine #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg" - XSERVER ?= "xserver-xorg \ - xf86-video-modesetting \ - " MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree" - EXTRA_IMAGEDEPENDS += "u-boot" + EXTRA_IMAGEDEPENDS += "virtual/bootloader" DEFAULTTUNE ?= "cortexa8hf-neon" - include conf/machine/include/tune-cortexa8.inc + include conf/machine/include/arm/armv7a/tune-cortexa8.inc IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" - EXTRA_IMAGECMD_jffs2 = "-lnp " + EXTRA_IMAGECMD:jffs2 = "-lnp " WKS_FILE ?= "beaglebone-yocto.wks" - IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage" - do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot" + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-image kernel-devicetree" + do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot virtual/bootloader:do_deploy" - SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0" - SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}" + SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0 115200;ttyAMA0" PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" - PREFERRED_VERSION_linux-yocto ?= "5.0%" + PREFERRED_VERSION_linux-yocto ?= "6.1%" KERNEL_IMAGETYPE = "zImage" KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" + PREFERRED_PROVIDER_virtual/bootloader ?= "u-boot" + SPL_BINARY = "MLO" UBOOT_SUFFIX = "img" UBOOT_MACHINE = "am335x_evm_defconfig" @@ -1312,7 +1274,24 @@ located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named MACHINE_FEATURES = "usbgadget usbhost vfat alsa" - IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" + IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} ${SPL_BINARY} ${KERNEL_IMAGETYPE} ${KERNEL_DEVICETREE}" + + # support runqemu + EXTRA_IMAGEDEPENDS += "qemu-native qemu-helper-native" + IMAGE_CLASSES += "qemuboot" + QB_DEFAULT_FSTYPE = "wic" + QB_FSINFO = "wic:no-kernel-in-fs" + QB_KERNEL_ROOT = "/dev/vda2" + QB_SYSTEM_NAME = "qemu-system-arm" + QB_MACHINE = "-machine virt" + QB_CPU = "-cpu cortex-a15" + QB_KERNEL_CMDLINE_APPEND = "console=ttyAMA0 systemd.mask=systemd-networkd" + QB_OPT_APPEND = "-device virtio-rng-device" + QB_TAP_OPT = "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no" + QB_NETWORK_DEVICE = "-device virtio-net-device,netdev=net0,mac=@MAC@" + QB_ROOTFS_OPT = "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0" + QB_SERIAL_OPT = "" + QB_TCPSERIAL_OPT = "-device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon" The variables used to configure the machine define machine-specific properties; for example, machine-dependent packages, machine tunings, the type of kernel @@ -1323,20 +1302,15 @@ the example reference machine configuration file for the BeagleBone development boards. Realize that much more can be defined as part of a machine's configuration file. In general, you can learn about related variables that this example does not have by locating the variables in -the ":ref:`ref-manual/ref-variables:variables glossary`" in the Yocto +the ":ref:`ref-manual/variables:variables glossary`" in the Yocto Project Reference Manual. - :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`: The recipe that provides "virtual/xserver" when more than one provider is found. In this case, the recipe that provides - "virtual/xserver" is "xserver-xorg", which exists in + "virtual/xserver" is "xserver-xorg", available in ``poky/meta/recipes-graphics/xorg-xserver``. -- :term:`XSERVER`: The packages that - should be installed to provide an X server and drivers for the - machine. In this example, the "xserver-xorg" and - "xf86-video-modesetting" are installed. - - :term:`MACHINE_EXTRA_RRECOMMENDS`: A list of machine-dependent packages not essential for booting the image. Thus, the build does not fail if the packages do not exist. @@ -1344,7 +1318,7 @@ Project Reference Manual. .. tip:: - Many ``MACHINE\*`` variables exist that help you configure a particular piece + There are many ``MACHINE*`` variables that help you configure a particular piece of hardware. - :term:`EXTRA_IMAGEDEPENDS`: @@ -1354,17 +1328,20 @@ Project Reference Manual. needed in the root filesystem. In this case, the U-Boot recipe must be built for the image. + At the end of the file, we also use this setings to implement + ``runqemu`` support on the host machine. + - :term:`DEFAULTTUNE`: Machines use tunings to optimize machine, CPU, and application performance. These features, which are collectively known as "tuning features", - exist in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g. - ``poky/meta/conf/machine/include``). In this example, the default - tunning file is "cortexa8hf-neon". + are set in the :term:`OpenEmbedded-Core (OE-Core)` layer. In this + example, the default tuning file is :oe_git:`tune-cortexa8 + </openembedded-core/tree/meta/conf/machine/include/arm/armv7a/tune-cortexa8.inc>`. .. note:: The include statement that pulls in the - conf/machine/include/tune-cortexa8.inc file provides many tuning + ``conf/machine/include/arm/tune-cortexa8.inc`` file provides many tuning possibilities. - :term:`IMAGE_FSTYPES`: The @@ -1375,21 +1352,15 @@ Project Reference Manual. - :term:`EXTRA_IMAGECMD`: Specifies additional options for image creation commands. In this example, the "-lnp " option is used when creating the - `JFFS2 <https://en.wikipedia.org/wiki/JFFS2>`__ image. + :wikipedia:`JFFS2 <JFFS2>` image. - :term:`WKS_FILE`: The location of - the :ref:`Wic kickstart <ref-manual/ref-kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used - by the OpenEmbedded build system to create a partitioned image - (image.wic). - -- :term:`IMAGE_INSTALL`: - Specifies packages to install into an image through the - :ref:`image <ref-classes-image>` class. Recipes - use the ``IMAGE_INSTALL`` variable. + the :ref:`Wic kickstart <ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used + by the OpenEmbedded build system to create a partitioned image. - ``do_image_wic[depends]``: A task that is constructed during the build. In this example, the task depends on specific tools in order - to create the sysroot when buiding a Wic image. + to create the sysroot when building a Wic image. - :term:`SERIAL_CONSOLES`: Defines a serial console (TTY) to enable using getty. In this case, @@ -1403,7 +1374,7 @@ Project Reference Manual. - :term:`PREFERRED_VERSION_linux-yocto <PREFERRED_VERSION>`: Defines the version of the recipe used to build the kernel, which is - "5.0" in this case. + "6.1" in this case. - :term:`KERNEL_IMAGETYPE`: The type of kernel to build for the device. In this case, the @@ -1425,11 +1396,12 @@ Project Reference Manual. The BeagleBone development board requires an SPL to boot and that SPL file type must be MLO. Consequently, the machine configuration needs - to define ``SPL_BINARY`` as ``MLO``. + to define :term:`SPL_BINARY` as ``MLO``. .. note:: - For more information on how the SPL variables are used, see the u-boot.inc + For more information on how the SPL variables are used, see the + :yocto_git:`u-boot.inc </poky/tree/meta/recipes-bsp/u-boot/u-boot.inc>` include file. - :term:`UBOOT_* <UBOOT_ENTRYPOINT>`: Defines @@ -1464,42 +1436,38 @@ BSP Kernel Recipe Example ------------------------- The kernel recipe used to build the kernel image for the BeagleBone -device was established in the machine configuration: :: +device was established in the machine configuration:: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" - PREFERRED_VERSION_linux-yocto ?= "5.0%" + PREFERRED_VERSION_linux-yocto ?= "6.1%" The ``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains metadata used to build the kernel. In this case, a kernel append file -(i.e. ``linux-yocto_5.0.bbappend``) is used to override an established -kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in -https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux. - -Following is the contents of the append file: :: - - KBRANCH_genericx86 = "v5.0/standard/base" - KBRANCH_genericx86-64 = "v5.0/standard/base" - KBRANCH_edgerouter = "v5.0/standard/edgerouter" - KBRANCH_beaglebone-yocto = "v5.0/standard/beaglebone" - - KMACHINE_genericx86 ?= "common-pc" - KMACHINE_genericx86-64 ?= "common-pc-64" - KMACHINE_beaglebone-yocto ?= "beaglebone" - - SRCREV_machine_genericx86 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" - SRCREV_machine_genericx86-64 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" - SRCREV_machine_edgerouter ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" - SRCREV_machine_beaglebone-yocto ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" - - COMPATIBLE_MACHINE_genericx86 = "genericx86" - COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" - COMPATIBLE_MACHINE_edgerouter = "edgerouter" - COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto" - - LINUX_VERSION_genericx86 = "5.0.3" - LINUX_VERSION_genericx86-64 = "5.0.3" - LINUX_VERSION_edgerouter = "5.0.3" - LINUX_VERSION_beaglebone-yocto = "5.0.3" +(i.e. ``linux-yocto_6.1.bbappend``) is used to override an established +kernel recipe (i.e. ``linux-yocto_6.1.bb``), which is located in +:yocto_git:`/poky/tree/meta/recipes-kernel/linux`. + +The contents of the append file are:: + + KBRANCH:genericx86 = "v6.1/standard/base" + KBRANCH:genericx86-64 = "v6.1/standard/base" + KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" + + KMACHINE:genericx86 ?= "common-pc" + KMACHINE:genericx86-64 ?= "common-pc-64" + KMACHINE:beaglebone-yocto ?= "beaglebone" + + SRCREV_machine:genericx86 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" + SRCREV_machine:genericx86-64 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" + SRCREV_machine:beaglebone-yocto ?= "423e1996694b61fbfc8ec3bf062fc6461d64fde1" + + COMPATIBLE_MACHINE:genericx86 = "genericx86" + COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto" + + LINUX_VERSION:genericx86 = "6.1.30" + LINUX_VERSION:genericx86-64 = "6.1.30" + LINUX_VERSION:beaglebone-yocto = "6.1.20" This particular append file works for all the machines that are part of the ``meta-yocto-bsp`` layer. The relevant statements are |