1 files changed, 1450 insertions, 0 deletions

diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
new file mode 100644
index 0000000000..09e25a061c
--- /dev/null
+++ b/documentation/bsp-guide/bsp.rst
@@ -0,0 +1,1450 @@
+************************************************
+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
+hardware platform. The BSP includes information about the hardware
+features present on the device and kernel configuration information
+along with any additional hardware drivers required. The BSP also lists
+any additional software components required in addition to a generic
+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>`__
+tool.
+
+BSP Layers
+==========
+
+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
+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
+   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
+a web interface at ` <&YOCTO_GIT_URL;>`__. If you go to that interface,
+you will find a list of repositories under "Yocto Metadata Layers".
+
+.. note::
+
+   Layers that are no longer actively supported as part of the Yocto
+   Project appear under the heading "Yocto Metadata Layer Archive."
+
+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
+
+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.
+
+For information on typical BSP development workflow, see the
+"`Developing a Board Support Package
+(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>`__"
+section in the Yocto Project Development Tasks Manual.
+
+The BSP layer's base directory (``meta-bsp_root_name``) is the root
+directory of that Layer. This directory is what you add to the
+```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable in the
+``conf/bblayers.conf`` file found in your `Build
+Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__, which is
+established after you run the OpenEmbedded build environment setup
+script (i.e. ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__).
+Adding the root directory allows the `OpenEmbedded build
+system <&YOCTO_DOCS_REF_URL;#build-system-term>`__ 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
+\\ "
+
+.. 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
+   .
+
+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
+layers in the ``README`` "Dependencies" section of the BSP's root layer.
+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
+this type of layer is OpenEmbedded's
+```meta-openembedded`` <https://github.com/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>`__"
+section of the Yocto Project Development Tasks Manual.
+
+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>`__"
+section.
+
+.. note::
+
+   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.
+
+2. *Clone the ``poky`` Repository:* You need to have a local copy of the
+   Yocto Project `Source
+   Directory <&YOCTO_DOCS_REF_URL;#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
+   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
+   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
+   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.
+
+   1. *Navigate to Your Source Directory:* Typically, you set up the
+      ``meta-intel`` Git repository inside the `Source
+      Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ (e.g.
+      ``poky``). $ cd /home/you/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.
+
+   3. *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'
+
+      .. 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.
+
+5. *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
+   the Source Directory (i.e. ``poky``), run the
+   ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ environment
+   setup script to define the OpenEmbedded build environment on your
+   build host. $ source OE_INIT_FILE Among other things, the script
+   creates the `Build
+   Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__, which is
+   ``build`` in this case and is located in the `Source
+   Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__. After the
+   script runs, your current working directory is set to the ``build``
+   directory.
+
+.. _bsp-filelayout:
+
+Example Filesystem Layout
+=========================
+
+Defining a common BSP directory structure allows end-users to understand
+and become familiar with that standard. A common format also encourages
+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
+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
+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
+regardless of the build system they are using.
+
+The BSP specification does not include a build system or other tools -
+the specification is concerned with the hardware-specific components
+only. At the end-distribution point, you can ship the BSP layer combined
+with a build system and other tools. Realize that it is important to
+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
+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.
+
+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
+
+Below is an example of the Raspberry Pi BSP layer that is available from
+the `Source Respositories <&YOCTO_GIT_URL;>`__:
+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.
+
+.. _bsp-filelayout-license:
+
+License Files
+-------------
+
+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
+requirements. For example, in the Raspberry Pi BSP, all licensing
+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>`__"
+section in the Yocto Project Development Tasks Manual.
+
+.. _bsp-filelayout-readme:
+
+README File
+-----------
+
+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
+also provides information needed for building the image.
+
+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:
+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
+``meta-bsp_root_name/binary``. Images in the ``binary`` would be images
+released with the BSP. The information in the ``README.sources`` file
+also helps you find the `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__
+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.
+
+.. _bsp-filelayout-binary:
+
+Pre-built User Binaries
+-----------------------
+
+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
+target system. This directory typically contains graphical (e.g. Sato)
+and minimal live images when the BSP tarball has been created and made
+available in the `Yocto Project <&YOCTO_HOME_URL;>`__ website. You can
+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
+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
+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:
+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).
+
+# 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"
+
+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 `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__
+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
+
+The machine files bind together all the information contained elsewhere
+in the BSP into a format that the build system can understand. Each BSP
+Layer requires at least one machine file. If the BSP supports multiple
+machines, multiple machine configuration files can exist. These
+filenames correspond to the values to which users have set the
+```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable.
+
+These files define things such as the kernel package to use
+(```PREFERRED_PROVIDER`` <&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER>`__
+of
+`virtual/kernel <&YOCTO_DOCS_DEV_URL;#metadata-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.
+
+This configuration file could also include a hardware "tuning" file that
+is commonly used to define the package architecture and specify
+optimization flags, which are carefully chosen to give best performance
+on a given processor.
+
+Tuning files are found in the ``meta/conf/machine/include`` directory
+within the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__.
+For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``,
+``tune-1586-nlp.inc``, and so forth) reside in the
+``poky/meta/conf/machine/include`` directory.
+
+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
+
+.. _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/\*
+
+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
+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
+
+.. note::
+
+   If a BSP does not have a formfactor entry, defaults are established
+   according to the formfactor configuration file that is installed by
+   the main formfactor recipe
+   ``meta/recipes-bsp/formfactor/formfactor_0.0.bb``, which is found in
+   the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__.
+
+.. _bsp-filelayout-recipes-graphics:
+
+Display Support Files
+---------------------
+
+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
+to support a display are kept here.
+
+.. _bsp-filelayout-kernel:
+
+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
+
+Append files (``*.bbappend``) modify the main kernel recipe being used
+to build the image. The ``*.bb`` files would be a developer-supplied
+kernel recipe. This area of the BSP hierarchy can contain both these
+types of files although, in practice, it is likely that you would have
+one or the other.
+
+For your BSP, you typically want to use an existing Yocto Project kernel
+recipe found in the `Source
+Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ at
+``meta/recipes-kernel/linux``. You can append machine-specific changes
+to the kernel recipe by using a similarly named append file, which is
+located in the BSP Layer for your target device (e.g. the
+``meta-bsp_root_name/recipes-kernel/linux`` directory).
+
+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
+```PREFERRED_PROVIDER`` <&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER>`__
+and
+```PREFERRED_VERSION`` <&YOCTO_DOCS_REF_URL;#var-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.
+
+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
+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.
+
+Developing a Board Support Package (BSP)
+========================================
+
+This section describes the high-level procedure you can follow to create
+a BSP. Although not required for BSP creation, the ``meta-intel``
+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>`__"
+section.
+
+The following illustration and list summarize the BSP creation general
+workflow.
+
+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
+   get a system ready to use the Yocto Project.
+
+2. *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>`__"
+   section.
+
+3. *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>`__"
+   section.
+
+   Another example that illustrates a layer is an application. Suppose
+   you are creating an application that has library or other
+   dependencies in order for it to compile and run. The layer, in this
+   case, would be where all the recipes that define those dependencies
+   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>`__"
+   section in the Yocto Project Development Tasks Manual. For more
+   information on BSP layers, see the "`BSP Layers <#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``
+         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.
+
+   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
+   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
+   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
+   identifies the kernel you are going to use. When you run the
+   ``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
+   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
+   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
+   setup script (i.e. ``oe-init-build-env``) and you need to be sure two
+   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>`__"
+   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
+   tool to build images based on the type of image you want to create.
+   You can find more information about BitBake in the `BitBake User
+   Manual <&YOCTO_DOCS_BB_URL;>`__.
+
+   The build process supports several types of images to satisfy
+   different needs. See the
+   "`Images <&YOCTO_DOCS_REF_URL;#ref-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.
+
+Released BSP Requirements
+-------------------------
+
+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>`__"
+   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>`__"
+   wiki page.
+
+-  The requirements for the BSP as it is made available to a developer
+   are completely independent of the released form of the BSP. For
+   example, the BSP Metadata can be contained within a Git repository
+   and could have a directory structure completely different from what
+   appears in the officially released BSP layer.
+
+-  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
+   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:
+
+-  *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.
+
+-  *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 `Source
+   Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ 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
+   (``*.bbappend`` files) into ``recipes-*`` subdirectories by
+   functional area as outlined in ``recipes.txt``. If you cannot find a
+   category in ``recipes.txt`` to fit a particular recipe, you can make
+   up your own ``recipes-*`` subdirectory.
+
+   Within any particular ``recipes-*`` category, the layout should match
+   what is found in the OpenEmbedded-Core Git repository
+   (``openembedded-core``) or the Source Directory (``poky``). In other
+   words, make sure you place related files in appropriately-related
+   ``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>`__".
+
+-  *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
+   ```COPYING.MIT`` <&YOCTO_GIT_URL;/cgit.cgi/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
+   ```README.md`` <&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md>`__
+   file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer
+   as an example.
+
+   At a minimum, the ``README`` file should contain the following:
+
+   -  A brief description of the target hardware.
+
+   -  A list of all the dependencies of the BSP. These dependencies are
+      typically a list of required layers needed to build the BSP.
+      However, the dependencies should also contain information
+      regarding any other dependencies the BSP might have.
+
+   -  Any required special licensing information. For example, this
+      information includes information on special variables needed to
+      satisfy a EULA, or instructions on information needed to build or
+      distribute binaries built from the BSP Metadata.
+
+   -  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.
+
+   -  Instructions on how to build the BSP using the BSP layer.
+
+   -  Instructions on how to boot the BSP build from the BSP layer.
+
+   -  Instructions on how to boot the binary images contained in the
+      ``binary`` directory, if present.
+
+   -  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
+   ``binary`` directory, you must include a ``README.sources`` file in
+   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
+   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
+   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
+   machine variations, you need to adequately describe each variation in
+   the BSP ``README`` file. Do not use multiple machine configuration
+   files to describe disparate hardware. If you do have very different
+   targets, you should create separate BSP layers for each target.
+
+   .. 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.
+
+Released BSP Recommendations
+----------------------------
+
+Following are recommendations for released BSPs that conform to the
+Yocto Project:
+
+-  *Bootable Images:* Released BSPs can contain one or more bootable
+   images. Including bootable images allows users to easily try out the
+   BSP using their own hardware.
+
+   In some cases, it might not be convenient to include a bootable
+   image. If so, you might want to make two versions of the BSP
+   available: one that contains binary images, and one that does not.
+   The version that does not contain bootable images avoids unnecessary
+   download times for users not interested in the images.
+
+   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
+   directory.
+
+   .. note::
+
+      If you do include a bootable image as part of the BSP and the
+      image was built by software covered by the GPL or other open
+      source licenses, it is your responsibility to understand and meet
+      all licensing requirements, which could include distribution of
+      source files.
+
+-  *Use a Yocto Linux Kernel:* Kernel recipes in the BSP should be based
+   on a Yocto Linux kernel. Basing your recipes on these kernels reduces
+   the costs for maintaining the BSP and increases its scalability. See
+   the ``Yocto Linux Kernel`` category in the `Source
+   Repositories <&YOCTO_GIT_URL;>`__ for these kernels.
+
+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.
+
+-  Ensure your directory structure in the BSP layer that supports your
+   machine is such that the OpenEmbedded build system can find it. See
+   the example later in this section for more information.
+
+-  Put the append file in a directory whose name matches the machine's
+   name and is located in an appropriate sub-directory inside the BSP
+   layer (i.e. ``recipes-bsp``, ``recipes-graphics``, ``recipes-core``,
+   and so forth).
+
+-  Place the BSP-specific files in the proper directory inside the BSP
+   layer. How expansive the layer is affects where you must place these
+   files. For example, if your layer supports several different machine
+   types, you need to be sure your layer's directory structure includes
+   hierarchy that separates the files according to machine. If your
+   layer does not support multiple machines, the layer would not have
+   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
+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``
+   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
+
+   .. note::
+
+      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
+                             
+
+   The
+   ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-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
+============================
+
+In some cases, a BSP contains separately-licensed Intellectual Property
+(IP) for a component or components. For these cases, you are required to
+accept the terms of a commercial or other type of license that requires
+some kind of explicit End User License Agreement (EULA). Once you accept
+the license, the OpenEmbedded build system can then build and include
+the corresponding component in the final BSP image. If the BSP is
+available as a pre-built image, you can download the image after
+agreeing to the license or EULA.
+
+You could find that some separately-licensed components that are
+essential for normal operation of the system might not have an
+unencumbered (or free) substitute. Without these essential components,
+the system would be non-functional. Then again, you might find that
+other licensed components that are simply 'good-to-have' or purely
+elective do have an unencumbered, free replacement component that you
+can use rather than agreeing to the separately-licensed component. Even
+for components essential to the system, you might find an unencumbered
+component that is not identical but will work as a less-capable version
+of the licensed version in the BSP recipe.
+
+For cases where you can substitute a free component and still maintain
+the system's functionality, the "DOWNLOADS" selection from the
+"SOFTWARE" tab on the `Yocto Project website <&YOCTO_HOME_URL;>`__ makes
+available de-featured BSPs that are completely free of any IP
+encumbrances. For these cases, you can use the substitution directly and
+without any further licensing requirements. If present, these fully
+de-featured BSPs are named appropriately different as compared to the
+names of their respective encumbered BSPs. If available, these
+substitutions are your simplest and most preferred options. Obviously,
+use of these substitutions assumes the resulting functionality meets
+system requirements.
+
+.. note::
+
+   If however, a non-encumbered version is unavailable or it provides
+   unsuitable functionality or quality, you can use an encumbered
+   version.
+
+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*\ ```LICENSE_FLAGS`` <&YOCTO_DOCS_REF_URL;#var-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
+   ```LICENSE_FLAGS_WHITELIST`` <&YOCTO_DOCS_REF_URL;#var-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>`__"
+   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.
+
+   Once the appropriate license flags are on the white list in the
+   ``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
+   selecting the "DOWNLOADS" item from the "SOFTWARE" tab on the `Yocto
+   Project website <&YOCTO_HOME_URL;>`__. You can download BSP tarballs
+   that contain proprietary components after agreeing to the licensing
+   requirements of each of the individually encumbered packages as part
+   of the download process. Obtaining the BSP this way allows you to
+   access an encumbered image immediately after agreeing to the
+   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
+   BSP.
+
+.. note::
+
+   Pre-compiled images are bundled with a time-limited kernel that runs
+   for a predetermined amount of time (10 days) before it forces the
+   system to reboot. This limitation is meant to discourage direct
+   redistribution of the image. You must eventually rebuild the image if
+   you want to remove this restriction.
+
+Creating a new BSP Layer Using the ``bitbake-layers`` Script
+============================================================
+
+The ``bitbake-layers create-layer`` script automates creating a BSP
+layer. What makes a layer a "BSP layer" is the presence of at least one
+machine configuration file. Additionally, a BSP layer usually has a
+kernel recipe or an append file that leverages off an existing kernel
+recipe. The primary requirement, however, is the machine configuration.
+
+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>`__"
+   section in the Yocto Project Development Tasks Manual.
+
+-  *Create a Layer Configuration File:* Every layer needs a layer
+   configuration file. This configuration file establishes locations for
+   the layer's recipes, priorities for the layer, and so forth. You can
+   find examples of ``layer.conf`` files in the Yocto Project `Source
+   Repositories <&YOCTO_GIT_URL;>`__. To get examples of what you need
+   in your configuration file, locate a layer (e.g. "meta-ti") and
+   examine the
+   ` <&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf>`__
+   file.
+
+-  *Create a Machine Configuration File:* Create a
+   ``conf/machine/``\ bsp_root_name\ ``.conf`` file. See
+   ```meta-yocto-bsp/conf/machine`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine>`__
+   for sample bsp_root_name\ ``.conf`` files. Other samples such as
+   ```meta-ti`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine>`__
+   and
+   ```meta-freescale`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine>`__
+   exist 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
+   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>`__"
+   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
+```meta-yocto-bsp`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/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: # 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 `Source
+Repositories <&YOCTO_GIT_URL;>`__.
+
+For a detailed description of this particular layer configuration file,
+see "`step 3 <&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description>`__
+in the discussion that describes how to create layers in the Yocto
+Project Development Tasks Manual.
+
+BSP Machine Configuration Example
+---------------------------------
+
+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:
+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``: #@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.
+
+The following list provides some explanation for the statements found in
+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
+Project Reference Manual.
+
+-  ```PREFERRED_PROVIDER_virtual/xserver`` <&YOCTO_DOCS_REF_URL;#var-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
+   ``poky/meta/recipes-graphics/xorg-xserver``.
+
+-  ```XSERVER`` <&YOCTO_DOCS_REF_URL;#var-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.
+
+-  ```MACHINE_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-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.
+   However, the packages are required for a fully-featured image.
+
+   .. note::
+
+      Many
+      MACHINE\*
+      variables exist that help you configure a particular piece of
+      hardware.
+
+-  ```EXTRA_IMAGEDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS>`__:
+   Recipes to build that do not provide packages for installing into the
+   root filesystem but building the image depends on the recipes.
+   Sometimes a recipe is required to build the final image but is not
+   needed in the root filesystem. In this case, the U-Boot recipe must
+   be built for the image.
+
+-  ```DEFAULTTUNE`` <&YOCTO_DOCS_REF_URL;#var-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.
+   ``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.
+
+-  ```IMAGE_FSTYPES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES>`__: The
+   formats the OpenEmbedded build system uses during the build when
+   creating the root filesystem. In this example, four types of images
+   are supported.
+
+-  ```EXTRA_IMAGECMD`` <&YOCTO_DOCS_REF_URL;#var-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.
+
+-  ```WKS_FILE`` <&YOCTO_DOCS_REF_URL;#var-WKS_FILE>`__: The location of
+   the `Wic kickstart <&YOCTO_DOCS_REF_URL;#ref-kickstart>`__ file used
+   by the OpenEmbedded build system to create a partitioned image
+   (image.wic).
+
+-  ```IMAGE_INSTALL`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL>`__:
+   Specifies packages to install into an image through the
+   ```image`` <&YOCTO_DOCS_REF_URL;#ref-classes-image>`__ class. Recipes
+   use the ``IMAGE_INSTALL`` variable.
+
+-  ``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.
+
+-  ```SERIAL_CONSOLES`` <&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES>`__:
+   Defines a serial console (TTY) to enable using getty. In this case,
+   the baud rate is "115200" and the device name is "ttyO0".
+
+-  ```PREFERRED_PROVIDER_virtual/kernel`` <&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER>`__:
+   Specifies the recipe that provides "virtual/kernel" when more than
+   one provider is found. In this case, the recipe that provides
+   "virtual/kernel" is "linux-yocto", which exists in the layer's
+   ``recipes-kernel/linux`` directory.
+
+-  ```PREFERRED_VERSION_linux-yocto`` <&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION>`__:
+   Defines the version of the recipe used to build the kernel, which is
+   "5.0" in this case.
+
+-  ```KERNEL_IMAGETYPE`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE>`__:
+   The type of kernel to build for the device. In this case, the
+   OpenEmbedded build system creates a "zImage" image type.
+
+-  ```KERNEL_DEVICETREE`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE>`__:
+   The names of the generated Linux kernel device trees (i.e. the
+   ``*.dtb``) files. All the device trees for the various BeagleBone
+   devices are included.
+
+-  ```KERNEL_EXTRA_ARGS`` <&YOCTO_DOCS_REF_URL;#var-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.
+
+-  ```SPL_BINARY`` <&YOCTO_DOCS_REF_URL;#var-SPL_BINARY>`__: Defines the
+   Secondary Program Loader (SPL) binary type. In this case, the SPL
+   binary is set to "MLO", which stands for Multimedia card LOader.
+
+   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".
+
+   .. note::
+
+      For more information on how the SPL variables are used, see the
+      u-boot.inc
+      include file.
+
+-  ```UBOOT_*`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT>`__: Defines
+   various U-Boot configurations needed to build a U-Boot image. In this
+   example, a U-Boot image is required to boot the BeagleBone device.
+   See the following variables for more information:
+
+   -  ```UBOOT_SUFFIX`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX>`__:
+      Points to the generated U-Boot extension.
+
+   -  ```UBOOT_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE>`__:
+      Specifies the value passed on the make command line when building
+      a U-Boot image.
+
+   -  ```UBOOT_ENTRYPOINT`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT>`__:
+      Specifies the entry point for the U-Boot image.
+
+   -  ```UBOOT_LOADADDRESS`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS>`__:
+      Specifies the load address for the U-Boot image.
+
+-  ```MACHINE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES>`__:
+   Specifies the list of hardware features the BeagleBone device is
+   capable of supporting. In this case, the device supports "usbgadget
+   usbhost vfat alsa".
+
+-  ```IMAGE_BOOT_FILES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES>`__:
+   Files installed into the device's boot partition when preparing the
+   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
+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
+` <&YOCTO_GIT_URL;/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
+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
+kernel recipe:
+
+-  ```KBRANCH`` <&YOCTO_DOCS_REF_URL;#var-KBRANCH>`__: Identifies the
+   kernel branch that is validated, patched, and configured during the
+   build.
+
+-  ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__: Identifies the
+   machine name as known by the kernel, which is sometimes a different
+   name than what is known by the OpenEmbedded build system.
+
+-  ```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__: Identifies the
+   revision of the source code used to build the image.
+
+-  ```COMPATIBLE_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE>`__:
+   A regular expression that resolves to one or more target machines
+   with which the recipe is compatible.
+
+-  ```LINUX_VERSION`` <&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION>`__: The
+   Linux version from kernel.org used by the OpenEmbedded build system
+   to build the kernel image.