From 9a569729dd1e190f528b9c1c63da88c2b83d8cff Mon Sep 17 00:00:00 2001 From: Nicolas Dechesne Date: Mon, 14 Sep 2020 22:48:21 +0200 Subject: sphinx: convert bsp-guide Last round of manual fixes for remaining links and conversion problems. (From yocto-docs rev: 954801327bf2574e6d7bc9275985be17cfd086f1) Signed-off-by: Nicolas Dechesne Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.rst | 1068 +++++++++++++++++++++------------------ 1 file changed, 571 insertions(+), 497 deletions(-) (limited to 'documentation/bsp-guide/bsp.rst') diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst index cdde41af63..024a240c22 100644 --- a/documentation/bsp-guide/bsp.rst +++ b/documentation/bsp-guide/bsp.rst @@ -15,9 +15,8 @@ Linux software stack for both essential and optional platform features. This guide presents information about BSP layers, defines a structure for components so that BSPs follow a commonly understood layout, discusses how to customize a recipe for a BSP, addresses BSP licensing, -and provides information that shows you how to create a `BSP -Layer <#bsp-layers>`__ using the -```bitbake-layers`` <#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__ +and provides information that shows you how to create a BSP +Layer using the :ref:`bitbake-layers ` tool. BSP Layers @@ -27,7 +26,11 @@ 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: meta-bsp_root_name The string "meta-" is prepended to the +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. .. note:: @@ -35,14 +38,14 @@ machine or platform name, which is bsp_root_name in the above form. 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 + 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 `Yocto Project Source -Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__ through +layers in the +:ref:`overview-manual/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". @@ -55,8 +58,9 @@ 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: $ git clone -git://git.yoctoproject.org/meta-raspberrypi +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 @@ -64,11 +68,11 @@ several "reference" BSPs including the ARM-based Beaglebone, MIPS-based EdgeRouter, and generic versions of both 32-bit and 64-bit IA machines. For information on typical BSP development workflow, see the -"`Developing a Board Support Package -(BSP) <#developing-a-board-support-package-bsp>`__" section. For more +: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 "`Locating Yocto Project Source -Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__" +repository, see the +:ref:`dev-manual/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 @@ -77,26 +81,24 @@ 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. ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__). +script (i.e. :ref:`ref-manual/ref-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: BBLAYERS ?= " \\ -/usr/local/src/yocto/meta \\ /usr/local/src/yocto/meta-poky \\ -/usr/local/src/yocto/meta-yocto-bsp \\ /usr/local/src/yocto/meta-mylayer -\\ " +layer and from it build an image. Here is an example: :: + + BBLAYERS ?= " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-poky \ + /usr/local/src/yocto/meta-yocto-bsp \ + /usr/local/src/yocto/meta-mylayer \ + " .. 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 ``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``. 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 @@ -105,20 +107,27 @@ 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 "`container -layers <&YOCTO_DOCS_REF_URL;#term-container-layer>`__". An example of +are knows as ":term:`container layers `". An example of this type of layer is OpenEmbedded's -```meta-openembedded`https://github.com/openembedded/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: BBLAYERS ?= " \\ -/usr/local/src/yocto/meta \\ /usr/local/src/yocto/meta-poky \\ -/usr/local/src/yocto/meta-yocto-bsp \\ /usr/local/src/yocto/meta-mylayer -\\ .../meta-openembedded/meta-oe \\ .../meta-openembedded/meta-perl \\ -.../meta-openembedded/meta-networking \\ " and so on. - -For more information on layers, see the "`Understanding and Creating -Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" +you want to work with, such as: :: + + BBLAYERS ?= " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-poky \ + /usr/local/src/yocto/meta-yocto-bsp \ + /usr/local/src/yocto/meta-mylayer \ + .../meta-openembedded/meta-oe \ + .../meta-openembedded/meta-perl \ + .../meta-openembedded/meta-networking \ + " + +and so on. + +For more information on layers, see the +":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" section of the Yocto Project Development Tasks Manual. Preparing Your Build Host to Work With BSP Layers @@ -126,101 +135,109 @@ Preparing Your Build Host to Work With BSP Layers This section describes how to get your build host ready to work with BSP layers. Once you have the host set up, you can create the layer as -described in the "`Creating a new BSP Layer Using the ``bitbake-layers`` -Script <#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__" +described in the +":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" section. .. note:: - For structural information on BSPs, see the - Example Filesystem Layout + For structural information on BSPs, see the Example Filesystem Layout section. -1. *Set Up the Build Environment:* Be sure you are set up to use BitBake - in a shell. See the "`Preparing the Build - Host <&YOCTO_DOCS_DEV_URL;#dev-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. +#. *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`" + 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. -2. *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 "`Cloning the ``poky`` - Repository <&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository>`__" and - possibly the "`Checking Out by Branch in - Poky <&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky>`__" or - "`Checking Out by Tag in - Poky <&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky>`__" sections + ``poky`` repository). See the + "ref:`dev-manual/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`" + sections all in the Yocto Project Development Tasks Manual for information on how to clone the ``poky`` repository and check out the appropriate branch for your work. -3. *Determine the BSP Layer You Want:* The Yocto Project supports many +#. *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. -4. *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 + `README `__ file. - 1. *Navigate to Your Source Directory:* Typically, you set up the + #. *Navigate to Your Source Directory:* Typically, you set up the ``meta-intel`` Git repository inside the :term:`Source Directory` (e.g. - ``poky``). $ cd /home/you/poky + ``poky``). :: - 2. *Clone the Layer:* $ git clone - git://git.yoctoproject.org/meta-intel.git Cloning into - 'meta-intel'... remote: Counting objects: 15585, done. remote: - Compressing objects: 100% (5056/5056), done. remote: Total 15585 - (delta 9123), reused 15329 (delta 8867) Receiving objects: 100% - (15585/15585), 4.51 MiB \| 3.19 MiB/s, done. Resolving deltas: - 100% (9123/9123), done. Checking connectivity... done. + $ cd /home/you/poky - 3. *Check Out the Proper Branch:* The branch you check out for + #. *Clone the Layer:* :: + + $ git clone git://git.yoctoproject.org/meta-intel.git + Cloning into 'meta-intel'... + remote: Counting objects: 15585, done. + remote: Compressing objects: 100% (5056/5056), done. + remote: Total 15585 (delta 9123), reused 15329 (delta 8867) + Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done. + Resolving deltas: 100% (9123/9123), done. + Checking connectivity... done. + + #. *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): $ cd meta-intel $ - git checkout -b DISTRO_NAME_NO_CAP - remotes/origin/DISTRO_NAME_NO_CAP Branch DISTRO_NAME_NO_CAP set up - to track remote branch DISTRO_NAME_NO_CAP from origin. Switched to - a new branch '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; + Branch &DISTRO_NAME_NO_CAP; set up to track remote branch + &DISTRO_NAME_NO_CAP; from origin. + Switched to a new branch '&DISTRO_NAME_NO_CAP;' .. note:: - To see the available branch names in a cloned repository, use - the - git branch -al - command. See the " - Checking Out By Branch in Poky - " section in the Yocto Project Development Tasks Manual for - more information. + 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`" + section in the Yocto Project Development Tasks Manual for more + information. -5. *Optionally Set Up an Alternative BSP Layer:* If your hardware can be +#. *Optionally Set Up an Alternative BSP Layer:* If your hardware can be more closely leveraged to an existing BSP not within the ``meta-intel`` BSP layer, you can clone that BSP layer. 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: $ git clone git://git.yoctoproject.org/meta-raspberrypi - Cloning into 'meta-raspberrypi'... remote: Counting objects: 4743, - done. remote: Compressing objects: 100% (2185/2185), done. remote: - Total 4743 (delta 2447), reused 4496 (delta 2258) Receiving objects: - 100% (4743/4743), 1.18 MiB \| 0 bytes/s, done. Resolving deltas: 100% - (2447/2447), done. Checking connectivity... done. - -6. *Initialize the Build Environment:* While in the root directory of + that layer: :: + + $ git clone git://git.yoctoproject.org/meta-raspberrypi + Cloning into 'meta-raspberrypi'... + remote: Counting objects: 4743, done. + remote: Compressing objects: 100% (2185/2185), done. + remote: Total 4743 (delta 2447), reused 4496 (delta 2258) + Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done. + Resolving deltas: 100% (2447/2447), done. + Checking connectivity... done. + +#. *Initialize the Build Environment:* While in the root directory of the Source Directory (i.e. ``poky``), run the - ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ environment + :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\`` environment setup script to define the OpenEmbedded build environment on your - build host. $ source OE_INIT_FILE 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`` + build host. :: + + $ source &OE_INIT_FILE; + + 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: @@ -237,8 +254,8 @@ 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 to extract information and convert it to other formats if required. The -OpenEmbedded build system, through its standard `layers -mechanism <&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model>`__, can +OpenEmbedded build system, through its standard :ref:`layers mechanism +`, 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 @@ -254,166 +271,180 @@ 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 in order for a BSP layer to be considered compliant with the Yocto -Project. For that list of requirements, see the "`Released BSP -Requirements <#released-bsp-requirements>`__" section. +Project. For that list of requirements, see the +":ref:`bsp-guide/bsp:released bsp requirements`" section. Below is the typical directory structure for a BSP layer. While this basic form represents the standard, realize that the actual layout for -individual BSPs could differ. meta-bsp_root_name/ -meta-bsp_root_name/bsp_license_file meta-bsp_root_name/README -meta-bsp_root_name/README.sources -meta-bsp_root_name/binary/bootable_images -meta-bsp_root_name/conf/layer.conf -meta-bsp_root_name/conf/machine/*.conf meta-bsp_root_name/recipes-bsp/\* -meta-bsp_root_name/recipes-core/\* -meta-bsp_root_name/recipes-graphics/\* -meta-bsp_root_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend +individual BSPs could differ. :: + + meta-bsp_root_name/ + meta-bsp_root_name/bsp_license_file + meta-bsp_root_name/README + meta-bsp_root_name/README.sources + meta-bsp_root_name/binary/bootable_images + meta-bsp_root_name/conf/layer.conf + meta-bsp_root_name/conf/machine/*.conf + meta-bsp_root_name/recipes-bsp/* + meta-bsp_root_name/recipes-core/* + meta-bsp_root_name/recipes-graphics/* + 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 <>`: -meta-raspberrypi/COPYING.MIT meta-raspberrypi/README.md -meta-raspberrypi/classes -meta-raspberrypi/classes/sdcard_image-rpi.bbclass meta-raspberrypi/conf/ -meta-raspberrypi/conf/layer.conf meta-raspberrypi/conf/machine/ -meta-raspberrypi/conf/machine/raspberrypi-cm.conf -meta-raspberrypi/conf/machine/raspberrypi-cm3.conf -meta-raspberrypi/conf/machine/raspberrypi.conf -meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf -meta-raspberrypi/conf/machine/raspberrypi0.conf -meta-raspberrypi/conf/machine/raspberrypi2.conf -meta-raspberrypi/conf/machine/raspberrypi3-64.conf -meta-raspberrypi/conf/machine/raspberrypi3.conf -meta-raspberrypi/conf/machine/include -meta-raspberrypi/conf/machine/include/rpi-base.inc -meta-raspberrypi/conf/machine/include/rpi-default-providers.inc -meta-raspberrypi/conf/machine/include/rpi-default-settings.inc -meta-raspberrypi/conf/machine/include/rpi-default-versions.inc -meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc -meta-raspberrypi/docs meta-raspberrypi/docs/Makefile -meta-raspberrypi/docs/conf.py meta-raspberrypi/docs/contributing.md -meta-raspberrypi/docs/extra-apps.md -meta-raspberrypi/docs/extra-build-config.md -meta-raspberrypi/docs/index.rst meta-raspberrypi/docs/layer-contents.md -meta-raspberrypi/docs/readme.md meta-raspberrypi/files -meta-raspberrypi/files/custom-licenses -meta-raspberrypi/files/custom-licenses/Broadcom -meta-raspberrypi/recipes-bsp meta-raspberrypi/recipes-bsp/bootfiles -meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb -meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb -meta-raspberrypi/recipes-bsp/common -meta-raspberrypi/recipes-bsp/common/firmware.inc -meta-raspberrypi/recipes-bsp/formfactor -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/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 -meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb -meta-raspberrypi/recipes-bsp/u-boot -meta-raspberrypi/recipes-bsp/u-boot/u-boot -meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch -meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend -meta-raspberrypi/recipes-connectivity -meta-raspberrypi/recipes-connectivity/bluez5 -meta-raspberrypi/recipes-connectivity/bluez5/bluez5 -meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch -meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd -meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service -meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend -meta-raspberrypi/recipes-core meta-raspberrypi/recipes-core/images -meta-raspberrypi/recipes-core/images/rpi-basic-image.bb -meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb -meta-raspberrypi/recipes-core/images/rpi-test-image.bb -meta-raspberrypi/recipes-core/packagegroups -meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb -meta-raspberrypi/recipes-core/psplash -meta-raspberrypi/recipes-core/psplash/files -meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h -meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend -meta-raspberrypi/recipes-core/udev -meta-raspberrypi/recipes-core/udev/udev-rules-rpi -meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules -meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb -meta-raspberrypi/recipes-devtools -meta-raspberrypi/recipes-devtools/bcm2835 -meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb -meta-raspberrypi/recipes-devtools/pi-blaster -meta-raspberrypi/recipes-devtools/pi-blaster/files -meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch -meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb -meta-raspberrypi/recipes-devtools/python -meta-raspberrypi/recipes-devtools/python/python-rtimu -meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch -meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb -meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb -meta-raspberrypi/recipes-devtools/python/rpi-gpio -meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch -meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb -meta-raspberrypi/recipes-devtools/python/rpio -meta-raspberrypi/recipes-devtools/python/rpio/*.patch -meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb -meta-raspberrypi/recipes-devtools/wiringPi -meta-raspberrypi/recipes-devtools/wiringPi/files -meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch -meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb -meta-raspberrypi/recipes-graphics -meta-raspberrypi/recipes-graphics/eglinfo -meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend -meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend -meta-raspberrypi/recipes-graphics/mesa -meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend -meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend -meta-raspberrypi/recipes-graphics/userland -meta-raspberrypi/recipes-graphics/userland/userland -meta-raspberrypi/recipes-graphics/userland/userland/*.patch -meta-raspberrypi/recipes-graphics/userland/userland_git.bb -meta-raspberrypi/recipes-graphics/vc-graphics -meta-raspberrypi/recipes-graphics/vc-graphics/files -meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc -meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh -meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb -meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb -meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc -meta-raspberrypi/recipes-graphics/wayland -meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend -meta-raspberrypi/recipes-graphics/xorg-xserver -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend -meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend -meta-raspberrypi/recipes-kernel -meta-raspberrypi/recipes-kernel/linux-firmware -meta-raspberrypi/recipes-kernel/linux-firmware/files -meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin -meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt -meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend -meta-raspberrypi/recipes-kernel/linux -meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb -meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc -meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb -meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb -meta-raspberrypi/recipes-multimedia -meta-raspberrypi/recipes-multimedia/gstreamer -meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx -meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch -meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend -meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend -meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12 -meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch -meta-raspberrypi/recipes-multimedia/omxplayer -meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer -meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch -meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb -meta-raspberrypi/recipes-multimedia/x264 -meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend -meta-raspberrypi/wic meta-raspberrypi/wic/sdimage-raspberrypi.wks +the :yocto_git:`Source Respositories <>`: :: + + meta-raspberrypi/COPYING.MIT + meta-raspberrypi/README.md + meta-raspberrypi/classes + meta-raspberrypi/classes/sdcard_image-rpi.bbclass + meta-raspberrypi/conf/ + meta-raspberrypi/conf/layer.conf + meta-raspberrypi/conf/machine/ + meta-raspberrypi/conf/machine/raspberrypi-cm.conf + meta-raspberrypi/conf/machine/raspberrypi-cm3.conf + meta-raspberrypi/conf/machine/raspberrypi.conf + meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf + meta-raspberrypi/conf/machine/raspberrypi0.conf + meta-raspberrypi/conf/machine/raspberrypi2.conf + meta-raspberrypi/conf/machine/raspberrypi3-64.conf + meta-raspberrypi/conf/machine/raspberrypi3.conf + meta-raspberrypi/conf/machine/include + meta-raspberrypi/conf/machine/include/rpi-base.inc + meta-raspberrypi/conf/machine/include/rpi-default-providers.inc + meta-raspberrypi/conf/machine/include/rpi-default-settings.inc + meta-raspberrypi/conf/machine/include/rpi-default-versions.inc + meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc + meta-raspberrypi/docs + meta-raspberrypi/docs/Makefile + meta-raspberrypi/docs/conf.py + meta-raspberrypi/docs/contributing.md + meta-raspberrypi/docs/extra-apps.md + meta-raspberrypi/docs/extra-build-config.md + meta-raspberrypi/docs/index.rst + meta-raspberrypi/docs/layer-contents.md + meta-raspberrypi/docs/readme.md + meta-raspberrypi/files + meta-raspberrypi/files/custom-licenses + meta-raspberrypi/files/custom-licenses/Broadcom + meta-raspberrypi/recipes-bsp + meta-raspberrypi/recipes-bsp/bootfiles + meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb + meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb + meta-raspberrypi/recipes-bsp/common + meta-raspberrypi/recipes-bsp/common/firmware.inc + meta-raspberrypi/recipes-bsp/formfactor + 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/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 + meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb + meta-raspberrypi/recipes-bsp/u-boot + meta-raspberrypi/recipes-bsp/u-boot/u-boot + meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch + meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend + meta-raspberrypi/recipes-connectivity + meta-raspberrypi/recipes-connectivity/bluez5 + meta-raspberrypi/recipes-connectivity/bluez5/bluez5 + meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch + meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd + meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service + meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend + meta-raspberrypi/recipes-core + meta-raspberrypi/recipes-core/images + meta-raspberrypi/recipes-core/images/rpi-basic-image.bb + meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb + meta-raspberrypi/recipes-core/images/rpi-test-image.bb + meta-raspberrypi/recipes-core/packagegroups + meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb + meta-raspberrypi/recipes-core/psplash + meta-raspberrypi/recipes-core/psplash/files + meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h + meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend + meta-raspberrypi/recipes-core/udev + meta-raspberrypi/recipes-core/udev/udev-rules-rpi + meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules + meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb + meta-raspberrypi/recipes-devtools + meta-raspberrypi/recipes-devtools/bcm2835 + meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb + meta-raspberrypi/recipes-devtools/pi-blaster + meta-raspberrypi/recipes-devtools/pi-blaster/files + meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch + meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb + meta-raspberrypi/recipes-devtools/python + meta-raspberrypi/recipes-devtools/python/python-rtimu + meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch + meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb + meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb + meta-raspberrypi/recipes-devtools/python/rpi-gpio + meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch + meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb + meta-raspberrypi/recipes-devtools/python/rpio + meta-raspberrypi/recipes-devtools/python/rpio/*.patch + meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb + meta-raspberrypi/recipes-devtools/wiringPi + meta-raspberrypi/recipes-devtools/wiringPi/files + meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch + meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb + meta-raspberrypi/recipes-graphics + meta-raspberrypi/recipes-graphics/eglinfo + meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend + meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend + meta-raspberrypi/recipes-graphics/mesa + meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend + meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend + meta-raspberrypi/recipes-graphics/userland + meta-raspberrypi/recipes-graphics/userland/userland + meta-raspberrypi/recipes-graphics/userland/userland/*.patch + meta-raspberrypi/recipes-graphics/userland/userland_git.bb + meta-raspberrypi/recipes-graphics/vc-graphics + meta-raspberrypi/recipes-graphics/vc-graphics/files + meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc + meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc + meta-raspberrypi/recipes-graphics/wayland + meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend + meta-raspberrypi/recipes-graphics/xorg-xserver + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend + meta-raspberrypi/recipes-kernel + meta-raspberrypi/recipes-kernel/linux-firmware + meta-raspberrypi/recipes-kernel/linux-firmware/files + meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin + meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt + meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend + meta-raspberrypi/recipes-kernel/linux + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb + meta-raspberrypi/recipes-multimedia + meta-raspberrypi/recipes-multimedia/gstreamer + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12 + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch + meta-raspberrypi/recipes-multimedia/omxplayer + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb + meta-raspberrypi/recipes-multimedia/x264 + meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend + meta-raspberrypi/wic meta-raspberrypi/wic/sdimage-raspberrypi.wks The following sections describe each part of the proposed BSP format. @@ -422,8 +453,9 @@ The following sections describe each part of the proposed BSP format. License Files ------------- -You can find these files in the BSP Layer at: -meta-bsp_root_name/bsp_license_file +You can find these files in the BSP Layer at: :: + + meta-bsp_root_name/bsp_license_file These optional files satisfy licensing requirements for the BSP. The type or types of files here can vary depending on the licensing @@ -433,8 +465,7 @@ 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 "`Maintaining Open Source License Compliance During Your Product's -Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__" +the ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" section in the Yocto Project Development Tasks Manual. .. _bsp-filelayout-readme: @@ -442,7 +473,9 @@ section in the Yocto Project Development Tasks Manual. README File ----------- -You can find this file in the BSP Layer at: meta-bsp_root_name/README +You can find this file in the BSP Layer at: :: + + meta-bsp_root_name/README This file provides information on how to boot the live images that are optionally included in the ``binary/`` directory. The ``README`` file @@ -457,8 +490,9 @@ name of the BSP maintainer with his or her contact information. README.sources File ------------------- -You can find this file in the BSP Layer at: -meta-bsp_root_name/README.sources +You can find this file in the BSP Layer at: :: + + meta-bsp_root_name/README.sources This file provides information on where to locate the BSP source files used to build the images (if any) that reside in @@ -469,19 +503,17 @@ used to generate the images that ship with the BSP. .. note:: - 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. + 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: -meta-bsp_root_name/binary/bootable_images +You can find these files in the BSP Layer at: :: + + meta-bsp_root_name/binary/bootable_images This optional area contains useful pre-built kernels and user-space filesystem images released with the BSP that are appropriate to the @@ -492,10 +524,10 @@ use these kernels and images to get a system running and quickly get started on development tasks. The exact types of binaries present are highly hardware-dependent. The -```README`` <#bsp-filelayout-readme>`__ file should be present in the +:ref:`README ` file should be present in the BSP Layer and it explains how to use the images with the target hardware. Additionally, the -```README.sources`` <#bsp-filelayout-readme-sources>`__ file should be +:ref:`README.sources ` file should be present to locate the sources used to build the images and provide information on the Metadata. @@ -504,43 +536,61 @@ information on the Metadata. Layer Configuration File ------------------------ -You can find this file in the BSP Layer at: -meta-bsp_root_name/conf/layer.conf +You can find this file in the BSP Layer at: :: + + meta-bsp_root_name/conf/layer.conf 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 -template). +template). :: + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have a recipes directory, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" -# We have a conf and classes directory, add to BBPATH BBPATH .= -":${LAYERDIR}" # We have a recipes directory, add to BBFILES BBFILES += -"${LAYERDIR}/recipes-*/*/*.bb \\ ${LAYERDIR}/recipes-*/*/*.bbappend" -BBFILE_COLLECTIONS += "bsp" BBFILE_PATTERN_bsp = "^${LAYERDIR}/" -BBFILE_PRIORITY_bsp = "6" LAYERDEPENDS_bsp = "intel" + BBFILE_COLLECTIONS += "bsp" + BBFILE_PATTERN_bsp = "^${LAYERDIR}/" + BBFILE_PRIORITY_bsp = "6" + LAYERDEPENDS_bsp = "intel" To illustrate the string substitutions, here are the corresponding -statements from the Raspberry Pi ``conf/layer.conf`` file: # We have a -conf and classes directory, append to BBPATH BBPATH .= ":${LAYERDIR}" # -We have a recipes directory containing .bb and .bbappend files, add to -BBFILES BBFILES += "${LAYERDIR}/recipes*/*/*.bb \\ -${LAYERDIR}/recipes*/*/*.bbappend" BBFILE_COLLECTIONS += "raspberrypi" -BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/" -BBFILE_PRIORITY_raspberrypi = "9" # Additional license directories. -LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" . . . - -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. +statements from the Raspberry Pi ``conf/layer.conf`` file: :: + + # We have a conf and classes directory, append to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have a recipes directory containing .bb and .bbappend files, add to BBFILES + BBFILES += "${LAYERDIR}/recipes*/*/*.bb \ + ${LAYERDIR}/recipes*/*/*.bbappend" + + BBFILE_COLLECTIONS += "raspberrypi" + BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/" + BBFILE_PRIORITY_raspberrypi = "9" + + # Additional license directories. + LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" + . + . + . + +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: -meta-bsp_root_name/conf/machine/*.conf +You can find these files in the BSP Layer at: :: + + meta-bsp_root_name/conf/machine/*.conf The machine files bind together all the information contained elsewhere in the BSP into a format that the build system can understand. Each BSP @@ -550,9 +600,8 @@ filenames correspond to the values to which users have set the :term:`MACHINE` variable. These files define things such as the kernel package to use -(:term:`PREFERRED_PROVIDER` -of -`virtual/kernel <&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers>`__), +(:term:`PREFERRED_PROVIDER` of +:ref:`virtual/kernel `), 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. @@ -570,16 +619,18 @@ 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: include -conf/machine/include/rpi-base.inc +``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: -meta-bsp_root_name/recipes-bsp/\* +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 @@ -587,9 +638,14 @@ Raspberry Pi BSP, there is the ``formfactor_0.0.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: -HAVE_TOUCHSCREEN=0 HAVE_KEYBOARD=1 DISPLAY_CAN_ROTATE=0 -DISPLAY_ORIENTATION=0 DISPLAY_DPI=133 +directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: :: + + HAVE_TOUCHSCREEN=0 + HAVE_KEYBOARD=1 + + DISPLAY_CAN_ROTATE=0 + DISPLAY_ORIENTATION=0 + DISPLAY_DPI=133 .. note:: @@ -604,8 +660,9 @@ DISPLAY_ORIENTATION=0 DISPLAY_DPI=133 Display Support Files --------------------- -You can find these files in the BSP Layer at: -meta-bsp_root_name/recipes-graphics/\* +You can find these files in the BSP Layer at: :: + + meta-bsp_root_name/recipes-graphics/* This optional directory contains recipes for the BSP if it has special requirements for graphics support. All files that are needed for the BSP @@ -616,9 +673,10 @@ to support a display are kept here. Linux Kernel Configuration -------------------------- -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 +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 Append files (``*.bbappend``) modify the main kernel recipe being used to build the image. The ``*.bb`` files would be a developer-supplied @@ -637,36 +695,35 @@ 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 -:term:`PREFERRED_PROVIDER` -and -:term:`PREFERRED_VERSION` -statements as follows: PREFERRED_PROVIDER_virtual/kernel ?= -"linux-yocto" PREFERRED_VERSION_linux-yocto ?= "4.4%" +:term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` +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 ``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 "`Creating the Append -File <&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file>`__" section +the ":ref:`kernel-dev/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: -linux-raspberrypi-dev.bb linux-raspberrypi.inc linux-raspberrypi_4.14.bb -linux-raspberrypi_4.9.bb The directory contains three kernel recipes and -a common include file. +``recipes-kernel/linux`` directory you see the following: :: + + linux-raspberrypi-dev.bb + linux-raspberrypi.inc + linux-raspberrypi_4.14.bb + linux-raspberrypi_4.9.bb + +The directory contains three kernel recipes and a common include file. Developing a Board Support Package (BSP) ======================================== @@ -677,8 +734,7 @@ repository, which contains many BSPs supported by the Yocto Project, is part of the example. For an example that shows how to create a new layer using the tools, see -the "`Creating a New BSP Layer Using the ``bitbake-layers`` -Script <#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__" +the ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" section. The following illustration and list summarize the BSP creation general @@ -687,29 +743,26 @@ workflow. .. image:: figures/bsp-dev-flow.png :align: center -1. *Set up Your Host Development System to Support Development Using the - Yocto Project*: See the "`Preparing the Build - Host <&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host>`__" section - in the Yocto Project Development Tasks Manual for options on how to +#. *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`" + section in the Yocto Project Development Tasks Manual for options on how to get a system ready to use the Yocto Project. -2. *Establish the ``meta-intel`` Repository on Your System:* Having +#. *Establish the meta-intel Repository on Your System:* Having local copies of these supported BSP layers on your system gives you access to layers you might be able to leverage when creating your - BSP. For information on how to get these files, see the "`Preparing - Your Build Host to Work with BSP - Layers <#preparing-your-build-host-to-work-with-bsp-layers>`__" + BSP. For information on how to get these files, see the + ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`" section. -3. *Create Your Own BSP Layer Using the ``bitbake-layers`` Script:* +#. *Create Your Own BSP Layer Using the bitbake-layers Script:* Layers are ideal for isolating and storing work for a given piece of hardware. A layer is really just a location or area in which you place the recipes and configurations for your BSP. In fact, a BSP is, in itself, a special type of layer. The simplest way to create a new BSP layer that is compliant with the Yocto Project is to use the ``bitbake-layers`` script. For information about that script, see the - "`Creating a New BSP Layer Using the ``bitbake-layers`` - Script <#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__" + ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" section. Another example that illustrates a layer is an application. Suppose @@ -719,13 +772,11 @@ 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 "`The Yocto Project Layer - Model <&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model>`__" section - in the Yocto Project Overview and Concepts Manual. You can also - reference the "`Understanding and Creating - Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" + layers, see the ":ref:`overview-manual/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`" section in the Yocto Project Development Tasks Manual. For more - information on BSP layers, see the "`BSP Layers <#bsp-layers>`__" + information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" section. .. note:: @@ -738,8 +789,7 @@ workflow. - Ubiquiti Networks EdgeRouter Lite (``edgerouter``) - - Two general IA platforms (``genericx86`` and - ``genericx86-64``) + - 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: @@ -756,13 +806,13 @@ workflow. Galileo gen1 & gen2 development boards. When you set up a layer for a new BSP, you should follow a standard - layout. This layout is described in the "`Example Filesystem - Layout <#bsp-filelayout>`__" section. In the standard layout, notice + layout. This layout is described in the ":ref:`bsp-guide/bsp:example filesystem layout`" + section. In the standard layout, notice the suggested structure for recipes and configuration information. You can see the standard layout for a BSP by examining any supported BSP found in the ``meta-intel`` layer inside the Source Directory. -4. *Make Configuration Changes to Your New BSP Layer:* The standard BSP +#. *Make Configuration Changes to Your New BSP Layer:* The standard BSP layer structure organizes the files you need to edit in ``conf`` and several ``recipes-*`` directories within the BSP layer. Configuration changes identify where your new layer is on the local system and @@ -770,12 +820,12 @@ workflow. ``bitbake-layers`` script, you are able to interactively configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). -5. *Make Recipe Changes to Your New BSP Layer:* Recipe changes include +#. *Make Recipe Changes to Your New BSP Layer:* Recipe changes include altering recipes (``*.bb`` files), removing recipes you do not use, and adding new recipes or append files (``.bbappend``) that support your hardware. -6. *Prepare for the Build:* Once you have made all the changes to your +#. *Prepare for the Build:* Once you have made all the changes to your BSP layer, there remains a few things you need to do for the OpenEmbedded build system in order for it to create your image. You need to get the build environment ready by sourcing an environment @@ -783,11 +833,11 @@ 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 - "`Enabling Your Layer <&YOCTO_DOCS_DEV_URL;#enabling-your-layer>`__" + ":ref:`dev-manual/dev-manual-common-tasks: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. -7. *Build the Image:* The OpenEmbedded build system uses the BitBake +#. *Build the Image:* The OpenEmbedded build system uses the BitBake tool to build images based on the type of image you want to create. You can find more information about BitBake in the :doc:`BitBake User Manual `. @@ -812,10 +862,9 @@ Before looking at BSP requirements, you should consider the following: - The requirements here assume the BSP layer is a well-formed, "legal" layer that can be added to the Yocto Project. For guidelines on - creating a layer that meets these base requirements, see the "`BSP - Layers <#bsp-layers>`__" section in this manual and the - "`Understanding and Creating - Layers" <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" + 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`" section in the Yocto Project Development Tasks Manual. - The requirements in this section apply regardless of how you package @@ -841,14 +890,13 @@ Following are the requirements for a released BSP that conform to the Yocto Project: - *Layer Name:* The BSP must have a layer name that follows the Yocto - Project standards. For information on BSP layer names, see the "`BSP - Layers <#bsp-layers>`__" section. + Project standards. For information on BSP layer names, see the + ":ref:`bsp-guide/bsp:bsp layers`" section. - *File System Layout:* When possible, use the same directory names in 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 + or in the OpenEmbedded-Core Layer (``openembedded-core``) at http://git.openembedded.org/openembedded-core/tree/meta. You should place recipes (``*.bb`` files) and recipe modifications @@ -868,7 +916,7 @@ Yocto Project: Guide `__". - *License File:* You must include a license file in the - ``meta-``\ bsp_root_name directory. This license covers the BSP + ``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 ` @@ -876,7 +924,7 @@ Yocto Project: as an example. - *README File:* You must include a ``README`` file in the - ``meta-``\ bsp_root_name directory. See the + ``meta-bsp_root_name`` directory. See the :yocto_git:`README.md ` file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer as an example. @@ -898,9 +946,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 - "`Submitting a Change to the Yocto - Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section - in the Yocto Project Development Tasks Manual. + ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" + section in the Yocto Project Development Tasks Manual. - Instructions on how to build the BSP using the BSP layer. @@ -912,19 +959,19 @@ Yocto Project: - Information on any known bugs or issues that users should know about when either building or booting the BSP binaries. -- *README.sources File:* If you BSP contains binary images in the +- *README.sources File:* If your BSP contains binary images in the ``binary`` directory, you must include a ``README.sources`` file in - the ``meta-``\ bsp_root_name directory. This file specifies exactly + the ``meta-bsp_root_name`` directory. This file specifies exactly where you can find the sources used to generate the binary images. - *Layer Configuration File:* You must include a ``conf/layer.conf`` - file in the ``meta-``\ bsp_root_name directory. This file identifies - the ``meta-``\ bsp_root_name BSP layer as a layer to the build + file in the ``meta-bsp_root_name`` directory. This file identifies + the ``meta-bsp_root_name`` BSP layer as a layer to the build system. - *Machine Configuration File:* You must include one or more - ``conf/machine/``\ bsp_root_name\ ``.conf`` files in the - ``meta-``\ bsp_root_name directory. These configuration files define + ``conf/machine/bsp_root_name.conf`` files in the + ``meta-bsp_root_name`` directory. These configuration files define machine targets that can be built using the BSP layer. Multiple machine configuration files define variations of machine configurations that the BSP supports. If a BSP supports multiple @@ -936,12 +983,10 @@ Yocto Project: .. note:: It is completely possible for a developer to structure the working - repository as a conglomeration of unrelated BSP files, and to - possibly generate BSPs targeted for release from that directory - using scripts or some other mechanism (e.g. - meta-yocto-bsp - layer). Such considerations are outside the scope of this - document. + repository as a conglomeration of unrelated BSP files, and to possibly + generate BSPs targeted for release from that directory using scripts or + some other mechanism (e.g. ``meta-yocto-bsp`` layer). Such considerations + are outside the scope of this document. Released BSP Recommendations ---------------------------- @@ -962,7 +1007,7 @@ Yocto Project: If you need to distribute a BSP and include bootable images or build kernel and filesystems meant to allow users to boot the BSP for evaluation purposes, you should put the images and artifacts within a - ``binary/`` subdirectory located in the ``meta-``\ bsp_root_name + ``binary/`` subdirectory located in the ``meta-bsp_root_name`` directory. .. note:: @@ -985,10 +1030,10 @@ Customizing a Recipe for a BSP 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 "`Using .bbappend Files in Your - Layer <&YOCTO_DOCS_DEV_URL;#using-bbappend-files>`__" section in the - Yocto Project Development Tasks Manual. +- 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. - Ensure your directory structure in the BSP layer that supports your machine is such that the OpenEmbedded build system can find it. See @@ -1014,33 +1059,30 @@ 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: -1. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the - following: FILESEXTRAPATHS_prepend := "${THISDIR}/files:" The append - file needs to be in the ``meta-xyz/recipes-core/init-ifupdown`` +#. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the + following: :: + + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + + The append file needs to be in the ``meta-xyz/recipes-core/init-ifupdown`` directory. -2. Create and place the new ``interfaces`` configuration file in the - BSP's layer here: - meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces +#. Create and place the new ``interfaces`` configuration file in the + 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 - + meta-xyz/recipes-core/init-ifupdown/files/interfaces - The - :term:`FILESEXTRAPATHS` - variable in the append files extends the search path the build system - uses to find files during the build. Consequently, for this example - you need to have the ``files`` directory in the same location as your - append file. + The :term:`FILESEXTRAPATHS` variable in the append files extends the search + path the build system uses to find files during the build. Consequently, for + this example you need to have the ``files`` directory in the same location as + your append file. BSP Licensing Considerations ============================ @@ -1087,17 +1129,14 @@ A couple different methods exist within the OpenEmbedded build system to satisfy the licensing requirements for an encumbered BSP. The following list describes them in order of preference: -1. *Use - the*\ :term:`LICENSE_FLAGS`\ *Variable - to Define the Recipes that Have Commercial or Other Types of - Specially-Licensed Packages:* For each of those recipes, you can +#. *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`. 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 "`Enabling - Commercially Licensed - Recipes <&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes>`__" + recipe and include the component in the image. See the + ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`" section in the Yocto Project Development Tasks Manual for details on how to use these variables. @@ -1113,7 +1152,7 @@ list describes them in order of preference: ``LICENSE_FLAGS_WHITELIST`` variable, you can build the encumbered image with no change at all to the normal build process. -2. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by +#. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by selecting the "DOWNLOADS" item from the "SOFTWARE" tab on the :yocto_home:`Yocto Project website <>`. You can download BSP tarballs that contain proprietary components after agreeing to the licensing @@ -1148,9 +1187,8 @@ Use these steps to create a BSP layer: - *Create a General Layer:* Use the ``bitbake-layers`` script with the ``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 "`Creating a General Layer Using - the ``bitbake-layers`` - Script <&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script>`__" + ``bitbake-layers`` script, see the + ":ref:`dev-manual/dev-manual-common-tasks: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 @@ -1164,9 +1202,9 @@ Use these steps to create a BSP layer: file. - *Create a Machine Configuration File:* Create a - ``conf/machine/``\ bsp_root_name\ ``.conf`` file. See + ``conf/machine/bsp_root_name.conf`` file. See :yocto_git:`meta-yocto-bsp/conf/machine ` - for sample bsp_root_name\ ``.conf`` files. Other samples such as + for sample ``bsp_root_name.conf`` files. Other samples such as :yocto_git:`meta-ti ` and :yocto_git:`meta-freescale ` @@ -1177,8 +1215,7 @@ Use these steps to create a BSP layer: ``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 layers mentioned in the previous step also contain different kernel - examples. See the "`Modifying an Existing - Recipe <&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe>`__" + examples. See the ":ref:`kernel-dev/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. @@ -1191,19 +1228,27 @@ 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: # We -have a conf and classes directory, add to BBPATH BBPATH .= -":${LAYERDIR}" # We have recipes-\* directories, add to BBFILES BBFILES -+= "${LAYERDIR}/recipes-*/*/*.bb \\ ${LAYERDIR}/recipes-*/*/*.bbappend" -BBFILE_COLLECTIONS += "yoctobsp" BBFILE_PATTERN_yoctobsp = -"^${LAYERDIR}/" BBFILE_PRIORITY_yoctobsp = "5" LAYERVERSION_yoctobsp = -"4" LAYERSERIES_COMPAT_yoctobsp = "DISTRO_NAME_NO_CAP" The variables -used in this file configure the layer. A good way to learn about layer +file. In this example, the ``conf/layer.conf`` is the following: :: + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-\* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "yoctobsp" + BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" + BBFILE_PRIORITY_yoctobsp = "5" + LAYERVERSION_yoctobsp = "4" + LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;" + +The variables used in this file configure the layer. A good way to learn about layer 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 "`step 3 <&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description>`__ +see ":ref:`step 3 `" in the discussion that describes how to create layers in the Yocto Project Development Tasks Manual. @@ -1215,37 +1260,61 @@ 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: -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 +``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`` + ... more ... + +For example, the machine configuration file for the `BeagleBone and BeagleBone Black development boards `__ is located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named -``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" -DEFAULTTUNE ?= "cortexa8hf-neon" include -conf/machine/include/tune-cortexa8.inc IMAGE_FSTYPES += "tar.bz2 jffs2 -wic wic.bmap" 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" SERIAL_CONSOLES ?= "115200;ttyS0 -115200;ttyO0" SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}" -PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" -PREFERRED_VERSION_linux-yocto ?= "5.0%" KERNEL_IMAGETYPE = "zImage" -KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb -am335x-bonegreen.dtb" KERNEL_EXTRA_ARGS += -"LOADADDR=${UBOOT_ENTRYPOINT}" SPL_BINARY = "MLO" UBOOT_SUFFIX = "img" -UBOOT_MACHINE = "am335x_evm_defconfig" UBOOT_ENTRYPOINT = "0x80008000" -UBOOT_LOADADDRESS = "0x80008000" MACHINE_FEATURES = "usbgadget usbhost -vfat alsa" IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage -am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" The variables -used to configure the machine define machine-specific properties; for +``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" + + DEFAULTTUNE ?= "cortexa8hf-neon" + include conf/machine/include/tune-cortexa8.inc + + IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" + 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" + + SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0" + SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}" + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "5.0%" + + KERNEL_IMAGETYPE = "zImage" + KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" + KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" + + SPL_BINARY = "MLO" + UBOOT_SUFFIX = "img" + UBOOT_MACHINE = "am335x_evm_defconfig" + UBOOT_ENTRYPOINT = "0x80008000" + UBOOT_LOADADDRESS = "0x80008000" + + MACHINE_FEATURES = "usbgadget usbhost vfat alsa" + + IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" + +The variables used to configure the machine define machine-specific properties; for example, machine-dependent packages, machine tunings, the type of kernel to build, and U-Boot configurations. @@ -1254,8 +1323,7 @@ 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 "`Yocto Project Variables -Glossary <&YOCTO_DOCS_REF_URL;#ref-variables-glos>`__" in the Yocto +the ":ref:`ref-manual/ref-variables:variables glossary`" in the Yocto Project Reference Manual. - :term:`PREFERRED_PROVIDER_virtual/xserver `: @@ -1274,12 +1342,10 @@ Project Reference Manual. image. Thus, the build does not fail if the packages do not exist. However, the packages are required for a fully-featured image. - .. note:: + .. tip:: - Many - MACHINE\* - variables exist that help you configure a particular piece of - hardware. + Many ``MACHINE\*`` variables exist that help you configure a particular piece + of hardware. - :term:`EXTRA_IMAGEDEPENDS`: Recipes to build that do not provide packages for installing into the @@ -1291,18 +1357,15 @@ Project Reference Manual. - :term:`DEFAULTTUNE`: Machines use tunings to optimize machine, CPU, and application performance. These features, which are collectively known as "tuning features", - exist in the `OpenEmbedded-Core - (OE-Core) <&YOCTO_DOCS_REF_URL;#oe-core>`__ layer (e.g. + 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". .. note:: - The - include - statement that pulls in the - conf/machine/include/tune-cortexa8.inc - file provides many tuning possibilities. + The include statement that pulls in the + conf/machine/include/tune-cortexa8.inc file provides many tuning + possibilities. - :term:`IMAGE_FSTYPES`: The formats the OpenEmbedded build system uses during the build when @@ -1315,7 +1378,7 @@ Project Reference Manual. `JFFS2 `__ image. - :term:`WKS_FILE`: The location of - the `Wic kickstart <&YOCTO_DOCS_REF_URL;#ref-kickstart>`__ file used + the :ref:`Wic kickstart ` file used by the OpenEmbedded build system to create a partitioned image (image.wic). @@ -1354,7 +1417,7 @@ Project Reference Manual. - :term:`KERNEL_EXTRA_ARGS`: Additional ``make`` command-line arguments the OpenEmbedded build system passes on when compiling the kernel. In this example, - "LOADADDR=${UBOOT_ENTRYPOINT}" is passed as a command-line argument. + ``LOADADDR=${UBOOT_ENTRYPOINT}`` is passed as a command-line argument. - :term:`SPL_BINARY`: Defines the Secondary Program Loader (SPL) binary type. In this case, the SPL @@ -1362,12 +1425,11 @@ 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 ``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 u-boot.inc include file. - :term:`UBOOT_* `: Defines @@ -1395,39 +1457,51 @@ Project Reference Manual. - :term:`IMAGE_BOOT_FILES`: Files installed into the device's boot partition when preparing the - image using the Wic tool with the ``bootimg-partition`` or + image using the Wic tool with the ``bootimg-partition`` or ``bootimg-efi`` source plugin. BSP Kernel Recipe Example ------------------------- The kernel recipe used to build the kernel image for the BeagleBone -device was established in the machine configuration: -PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" -PREFERRED_VERSION_linux-yocto ?= "5.0%" The -``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains +device was established in the machine configuration: :: + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "5.0%" + +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" This particular append file works for all the machines that are +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" + +This particular append file works for all the machines that are part of the ``meta-yocto-bsp`` layer. The relevant statements are appended with the "beaglebone-yocto" string. The OpenEmbedded build system uses these statements to override similar statements in the -- cgit v1.2.3-54-g00ecf