1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3************************************************ 4Board Support Packages (BSP) - Developer's Guide 5************************************************ 6 7A Board Support Package (BSP) is a collection of information that 8defines how to support a particular hardware device, set of devices, or 9hardware platform. The BSP includes information about the hardware 10features present on the device and kernel configuration information 11along with any additional hardware drivers required. The BSP also lists 12any additional software components required in addition to a generic 13Linux software stack for both essential and optional platform features. 14 15This guide presents information about BSP layers, defines a structure 16for components so that BSPs follow a commonly understood layout, 17discusses how to customize a recipe for a BSP, addresses BSP licensing, 18and provides information that shows you how to create a BSP 19Layer using the :ref:`bitbake-layers <bsp-guide/bsp:Creating a new BSP Layer Using the \`\`bitbake-layers\`\` Script>` 20tool. 21 22BSP Layers 23========== 24 25A BSP consists of a file structure inside a base directory. 26Collectively, you can think of the base directory, its file structure, 27and the contents as a BSP layer. Although not a strict requirement, BSP 28layers in the Yocto Project use the following well-established naming 29convention:: 30 31 meta-bsp_root_name 32 33The string "meta-" is prepended to the 34machine or platform name, which is "bsp_root_name" in the above form. 35 36.. note:: 37 38 Because the BSP layer naming convention is well-established, it is 39 advisable to follow it when creating layers. Technically speaking, a 40 BSP layer name does not need to start with ``meta-``. 41 However, various scripts and tools in the Yocto Project development 42 environment assume this convention. 43 44To help understand the BSP layer concept, consider the BSPs that the 45Yocto Project supports and provides with each release. You can see the 46layers in the 47:ref:`overview-manual/development-environment:yocto project source repositories` 48through 49a web interface at :yocto_git:`/`. If you go to that interface, 50you will find a list of repositories under "Yocto Metadata Layers". 51 52.. note:: 53 54 Layers that are no longer actively supported as part of the Yocto 55 Project appear under the heading "Yocto Metadata Layer Archive." 56 57Each repository is a BSP layer supported by the Yocto Project (e.g. 58``meta-raspberrypi`` and ``meta-intel``). Each of these layers is a 59repository unto itself and clicking on the layer name displays two URLs 60from which you can clone the layer's repository to your local system. 61Here is an example that clones the Raspberry Pi BSP layer:: 62 63 $ git clone git://git.yoctoproject.org/meta-raspberrypi 64 65In addition to BSP layers, the ``meta-yocto-bsp`` layer is part of the 66shipped ``poky`` repository. The ``meta-yocto-bsp`` layer maintains 67several "reference" BSPs including the ARM-based Beaglebone, MIPS-based 68EdgeRouter, and generic versions of both 32-bit and 64-bit IA machines. 69 70For information on typical BSP development workflow, see the 71:ref:`bsp-guide/bsp:developing a board support package (bsp)` 72section. For more 73information on how to set up a local copy of source files from a Git 74repository, see the 75:ref:`dev-manual/start:locating yocto project source files` 76section in the Yocto Project Development Tasks Manual. 77 78The BSP layer's base directory (``meta-bsp_root_name``) is the root 79directory of that Layer. This directory is what you add to the 80:term:`BBLAYERS` variable in the 81``conf/bblayers.conf`` file found in your 82:term:`Build Directory`, which is 83established after you run the OpenEmbedded build environment setup 84script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). 85Adding the root directory allows the :term:`OpenEmbedded Build System` 86to recognize the BSP 87layer and from it build an image. Here is an example:: 88 89 BBLAYERS ?= " \ 90 /usr/local/src/yocto/meta \ 91 /usr/local/src/yocto/meta-poky \ 92 /usr/local/src/yocto/meta-yocto-bsp \ 93 /usr/local/src/yocto/meta-mylayer \ 94 " 95 96.. note:: 97 98 Ordering and :term:`BBFILE_PRIORITY` for the layers listed in :term:`BBLAYERS` 99 matter. For example, if multiple layers define a machine configuration, the 100 OpenEmbedded build system uses the last layer searched given similar layer 101 priorities. The build system works from the top-down through the layers 102 listed in :term:`BBLAYERS`. 103 104Some BSPs require or depend on additional layers beyond the BSP's root 105layer in order to be functional. In this case, you need to specify these 106layers in the ``README`` "Dependencies" section of the BSP's root layer. 107Additionally, if any build instructions exist for the BSP, you must add 108them to the "Dependencies" section. 109 110Some layers function as a layer to hold other BSP layers. These layers 111are known as ":term:`container layers <Container Layer>`". An example of 112this type of layer is OpenEmbedded's 113`meta-openembedded <https://github.com/openembedded/meta-openembedded>`__ 114layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers. 115In cases like this, you need to include the names of the actual layers 116you want to work with, such as:: 117 118 BBLAYERS ?= " \ 119 /usr/local/src/yocto/meta \ 120 /usr/local/src/yocto/meta-poky \ 121 /usr/local/src/yocto/meta-yocto-bsp \ 122 /usr/local/src/yocto/meta-mylayer \ 123 .../meta-openembedded/meta-oe \ 124 .../meta-openembedded/meta-perl \ 125 .../meta-openembedded/meta-networking \ 126 " 127 128and so on. 129 130For more information on layers, see the 131":ref:`dev-manual/common-tasks:understanding and creating layers`" 132section of the Yocto Project Development Tasks Manual. 133 134Preparing Your Build Host to Work With BSP Layers 135================================================= 136 137This section describes how to get your build host ready to work with BSP 138layers. Once you have the host set up, you can create the layer as 139described in the 140":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" 141section. 142 143.. note:: 144 145 For structural information on BSPs, see the 146 :ref:`bsp-guide/bsp:example filesystem layout` section. 147 148#. *Set Up the Build Environment:* Be sure you are set up to use BitBake 149 in a shell. See the ":ref:`dev-manual/start:preparing the build host`" 150 section in the Yocto Project Development Tasks Manual for information on how 151 to get a build host ready that is either a native Linux machine or a machine 152 that uses CROPS. 153 154#. *Clone the poky Repository:* You need to have a local copy of the 155 Yocto Project :term:`Source Directory` (i.e. a local 156 ``poky`` repository). See the 157 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and 158 possibly the 159 ":ref:`dev-manual/start:checking out by branch in poky`" or 160 ":ref:`dev-manual/start:checking out by tag in poky`" 161 sections 162 all in the Yocto Project Development Tasks Manual for information on 163 how to clone the ``poky`` repository and check out the appropriate 164 branch for your work. 165 166#. *Determine the BSP Layer You Want:* The Yocto Project supports many 167 BSPs, which are maintained in their own layers or in layers designed 168 to contain several BSPs. To get an idea of machine support through 169 BSP layers, you can look at the 170 :yocto_dl:`index of machines </releases/yocto/yocto-&DISTRO;/machines>` 171 for the release. 172 173#. *Optionally Clone the meta-intel BSP Layer:* If your hardware is 174 based on current Intel CPUs and devices, you can leverage this BSP 175 layer. For details on the ``meta-intel`` BSP layer, see the layer's 176 :yocto_git:`README </meta-intel/tree/README>` file. 177 178 #. *Navigate to Your Source Directory:* Typically, you set up the 179 ``meta-intel`` Git repository inside the :term:`Source Directory` (e.g. 180 ``poky``). :: 181 182 $ cd /home/you/poky 183 184 #. *Clone the Layer:* :: 185 186 $ git clone git://git.yoctoproject.org/meta-intel.git 187 Cloning into 'meta-intel'... 188 remote: Counting objects: 15585, done. 189 remote: Compressing objects: 100% (5056/5056), done. 190 remote: Total 15585 (delta 9123), reused 15329 (delta 8867) 191 Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done. 192 Resolving deltas: 100% (9123/9123), done. 193 Checking connectivity... done. 194 195 #. *Check Out the Proper Branch:* The branch you check out for 196 ``meta-intel`` must match the same branch you are using for the 197 Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``):: 198 199 $ cd meta-intel 200 $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; 201 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch 202 &DISTRO_NAME_NO_CAP; from origin. 203 Switched to a new branch '&DISTRO_NAME_NO_CAP;' 204 205 .. note:: 206 207 To see the available branch names in a cloned repository, use the ``git 208 branch -al`` command. See the 209 ":ref:`dev-manual/start:checking out by branch in poky`" 210 section in the Yocto Project Development Tasks Manual for more 211 information. 212 213#. *Optionally Set Up an Alternative BSP Layer:* If your hardware can be 214 more closely leveraged to an existing BSP not within the 215 ``meta-intel`` BSP layer, you can clone that BSP layer. 216 217 The process is identical to the process used for the ``meta-intel`` 218 layer except for the layer's name. For example, if you determine that 219 your hardware most closely matches the ``meta-raspberrypi``, clone 220 that layer:: 221 222 $ git clone git://git.yoctoproject.org/meta-raspberrypi 223 Cloning into 'meta-raspberrypi'... 224 remote: Counting objects: 4743, done. 225 remote: Compressing objects: 100% (2185/2185), done. 226 remote: Total 4743 (delta 2447), reused 4496 (delta 2258) 227 Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done. 228 Resolving deltas: 100% (2447/2447), done. 229 Checking connectivity... done. 230 231#. *Initialize the Build Environment:* While in the root directory of 232 the Source Directory (i.e. ``poky``), run the 233 :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment 234 setup script to define the OpenEmbedded build environment on your 235 build host. :: 236 237 $ source oe-init-build-env 238 239 Among other things, the script creates the :term:`Build Directory`, which is 240 ``build`` in this case and is located in the :term:`Source Directory`. After 241 the script runs, your current working directory is set to the ``build`` 242 directory. 243 244Example Filesystem Layout 245========================= 246 247Defining a common BSP directory structure allows end-users to understand 248and become familiar with that standard. A common format also encourages 249standardization of software support for hardware. 250 251The proposed form described in this section does have elements that are 252specific to the OpenEmbedded build system. It is intended that 253developers can use this structure with other build systems besides the 254OpenEmbedded build system. It is also intended that it will be simple 255to extract information and convert it to other formats if required. The 256OpenEmbedded build system, through its standard :ref:`layers mechanism 257<overview-manual/yp-intro:the yocto project layer model>`, can 258directly accept the format described as a layer. The BSP layer captures 259all the hardware-specific details in one place using a standard format, 260which is useful for any person wishing to use the hardware platform 261regardless of the build system they are using. 262 263The BSP specification does not include a build system or other tools - 264the specification is concerned with the hardware-specific components 265only. At the end-distribution point, you can ship the BSP layer combined 266with a build system and other tools. Realize that it is important to 267maintain the distinction that the BSP layer, a build system, and tools 268are separate components that could be combined in certain end products. 269 270Before looking at the recommended form for the directory structure 271inside a BSP layer, you should be aware that there are some requirements 272in order for a BSP layer to be considered compliant with the Yocto 273Project. For that list of requirements, see the 274":ref:`bsp-guide/bsp:released bsp requirements`" section. 275 276Below is the typical directory structure for a BSP layer. While this 277basic form represents the standard, realize that the actual layout for 278individual BSPs could differ. :: 279 280 meta-bsp_root_name/ 281 meta-bsp_root_name/bsp_license_file 282 meta-bsp_root_name/README 283 meta-bsp_root_name/README.sources 284 meta-bsp_root_name/binary/bootable_images 285 meta-bsp_root_name/conf/layer.conf 286 meta-bsp_root_name/conf/machine/*.conf 287 meta-bsp_root_name/recipes-bsp/* 288 meta-bsp_root_name/recipes-core/* 289 meta-bsp_root_name/recipes-graphics/* 290 meta-bsp_root_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend 291 292Below is an example of the Raspberry Pi BSP layer that is available from 293the :yocto_git:`Source Repositories <>`: 294 295.. code-block:: none 296 297 meta-raspberrypi/COPYING.MIT 298 meta-raspberrypi/README.md 299 meta-raspberrypi/classes 300 meta-raspberrypi/classes/sdcard_image-rpi.bbclass 301 meta-raspberrypi/conf/ 302 meta-raspberrypi/conf/layer.conf 303 meta-raspberrypi/conf/machine/ 304 meta-raspberrypi/conf/machine/raspberrypi-cm.conf 305 meta-raspberrypi/conf/machine/raspberrypi-cm3.conf 306 meta-raspberrypi/conf/machine/raspberrypi.conf 307 meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf 308 meta-raspberrypi/conf/machine/raspberrypi0.conf 309 meta-raspberrypi/conf/machine/raspberrypi2.conf 310 meta-raspberrypi/conf/machine/raspberrypi3-64.conf 311 meta-raspberrypi/conf/machine/raspberrypi3.conf 312 meta-raspberrypi/conf/machine/include 313 meta-raspberrypi/conf/machine/include/rpi-base.inc 314 meta-raspberrypi/conf/machine/include/rpi-default-providers.inc 315 meta-raspberrypi/conf/machine/include/rpi-default-settings.inc 316 meta-raspberrypi/conf/machine/include/rpi-default-versions.inc 317 meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc 318 meta-raspberrypi/docs 319 meta-raspberrypi/docs/Makefile 320 meta-raspberrypi/docs/conf.py 321 meta-raspberrypi/docs/contributing.md 322 meta-raspberrypi/docs/extra-apps.md 323 meta-raspberrypi/docs/extra-build-config.md 324 meta-raspberrypi/docs/index.rst 325 meta-raspberrypi/docs/layer-contents.md 326 meta-raspberrypi/docs/readme.md 327 meta-raspberrypi/files 328 meta-raspberrypi/files/custom-licenses 329 meta-raspberrypi/files/custom-licenses/Broadcom 330 meta-raspberrypi/recipes-bsp 331 meta-raspberrypi/recipes-bsp/bootfiles 332 meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb 333 meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb 334 meta-raspberrypi/recipes-bsp/common 335 meta-raspberrypi/recipes-bsp/common/firmware.inc 336 meta-raspberrypi/recipes-bsp/formfactor 337 meta-raspberrypi/recipes-bsp/formfactor/formfactor 338 meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi 339 meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig 340 meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend 341 meta-raspberrypi/recipes-bsp/rpi-u-boot-src 342 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files 343 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in 344 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb 345 meta-raspberrypi/recipes-bsp/u-boot 346 meta-raspberrypi/recipes-bsp/u-boot/u-boot 347 meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch 348 meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend 349 meta-raspberrypi/recipes-connectivity 350 meta-raspberrypi/recipes-connectivity/bluez5 351 meta-raspberrypi/recipes-connectivity/bluez5/bluez5 352 meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch 353 meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd 354 meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service 355 meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend 356 meta-raspberrypi/recipes-core 357 meta-raspberrypi/recipes-core/images 358 meta-raspberrypi/recipes-core/images/rpi-basic-image.bb 359 meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb 360 meta-raspberrypi/recipes-core/images/rpi-test-image.bb 361 meta-raspberrypi/recipes-core/packagegroups 362 meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb 363 meta-raspberrypi/recipes-core/psplash 364 meta-raspberrypi/recipes-core/psplash/files 365 meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h 366 meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend 367 meta-raspberrypi/recipes-core/udev 368 meta-raspberrypi/recipes-core/udev/udev-rules-rpi 369 meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules 370 meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb 371 meta-raspberrypi/recipes-devtools 372 meta-raspberrypi/recipes-devtools/bcm2835 373 meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb 374 meta-raspberrypi/recipes-devtools/pi-blaster 375 meta-raspberrypi/recipes-devtools/pi-blaster/files 376 meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch 377 meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb 378 meta-raspberrypi/recipes-devtools/python 379 meta-raspberrypi/recipes-devtools/python/python-rtimu 380 meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch 381 meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb 382 meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb 383 meta-raspberrypi/recipes-devtools/python/rpi-gpio 384 meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch 385 meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb 386 meta-raspberrypi/recipes-devtools/python/rpio 387 meta-raspberrypi/recipes-devtools/python/rpio/*.patch 388 meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb 389 meta-raspberrypi/recipes-devtools/wiringPi 390 meta-raspberrypi/recipes-devtools/wiringPi/files 391 meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch 392 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb 393 meta-raspberrypi/recipes-graphics 394 meta-raspberrypi/recipes-graphics/eglinfo 395 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend 396 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend 397 meta-raspberrypi/recipes-graphics/mesa 398 meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend 399 meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend 400 meta-raspberrypi/recipes-graphics/userland 401 meta-raspberrypi/recipes-graphics/userland/userland 402 meta-raspberrypi/recipes-graphics/userland/userland/*.patch 403 meta-raspberrypi/recipes-graphics/userland/userland_git.bb 404 meta-raspberrypi/recipes-graphics/vc-graphics 405 meta-raspberrypi/recipes-graphics/vc-graphics/files 406 meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc 407 meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh 408 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb 409 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb 410 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc 411 meta-raspberrypi/recipes-graphics/wayland 412 meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend 413 meta-raspberrypi/recipes-graphics/xorg-xserver 414 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config 415 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi 416 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf 417 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d 418 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf 419 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf 420 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf 421 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend 422 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend 423 meta-raspberrypi/recipes-kernel 424 meta-raspberrypi/recipes-kernel/linux-firmware 425 meta-raspberrypi/recipes-kernel/linux-firmware/files 426 meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin 427 meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt 428 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend 429 meta-raspberrypi/recipes-kernel/linux 430 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb 431 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc 432 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb 433 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb 434 meta-raspberrypi/recipes-multimedia 435 meta-raspberrypi/recipes-multimedia/gstreamer 436 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx 437 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch 438 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend 439 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend 440 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12 441 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch 442 meta-raspberrypi/recipes-multimedia/omxplayer 443 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer 444 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch 445 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb 446 meta-raspberrypi/recipes-multimedia/x264 447 meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend 448 meta-raspberrypi/wic meta-raspberrypi/wic/sdimage-raspberrypi.wks 449 450The following sections describe each part of the proposed BSP format. 451 452License Files 453------------- 454 455You can find these files in the BSP Layer at:: 456 457 meta-bsp_root_name/bsp_license_file 458 459These optional files satisfy licensing requirements for the BSP. The 460type or types of files here can vary depending on the licensing 461requirements. For example, in the Raspberry Pi BSP, all licensing 462requirements are handled with the ``COPYING.MIT`` file. 463 464Licensing files can be MIT, BSD, GPLv*, and so forth. These files are 465recommended for the BSP but are optional and totally up to the BSP 466developer. For information on how to maintain license compliance, see 467the ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" 468section in the Yocto Project Development Tasks Manual. 469 470README File 471----------- 472 473You can find this file in the BSP Layer at:: 474 475 meta-bsp_root_name/README 476 477This file provides information on how to boot the live images that are 478optionally included in the ``binary/`` directory. The ``README`` file 479also provides information needed for building the image. 480 481At a minimum, the ``README`` file must contain a list of dependencies, 482such as the names of any other layers on which the BSP depends and the 483name of the BSP maintainer with his or her contact information. 484 485README.sources File 486------------------- 487 488You can find this file in the BSP Layer at:: 489 490 meta-bsp_root_name/README.sources 491 492This file provides information on where to locate the BSP source files 493used to build the images (if any) that reside in 494``meta-bsp_root_name/binary``. Images in the ``binary`` would be images 495released with the BSP. The information in the ``README.sources`` file 496also helps you find the :term:`Metadata` 497used to generate the images that ship with the BSP. 498 499.. note:: 500 501 If the BSP's ``binary`` directory is missing or the directory has no images, an 502 existing ``README.sources`` file is meaningless and usually does not exist. 503 504Pre-built User Binaries 505----------------------- 506 507You can find these files in the BSP Layer at:: 508 509 meta-bsp_root_name/binary/bootable_images 510 511This optional area contains useful pre-built kernels and user-space 512filesystem images released with the BSP that are appropriate to the 513target system. This directory typically contains graphical (e.g. Sato) 514and minimal live images when the BSP tarball has been created and made 515available in the :yocto_home:`Yocto Project <>` website. You can 516use these kernels and images to get a system running and quickly get 517started on development tasks. 518 519The exact types of binaries present are highly hardware-dependent. The 520:ref:`README <bsp-guide/bsp:readme file>` file should be present in the 521BSP Layer and it explains how to use the images with the target 522hardware. Additionally, the 523:ref:`README.sources <bsp-guide/bsp:readme.sources file>` file should be 524present to locate the sources used to build the images and provide 525information on the Metadata. 526 527Layer Configuration File 528------------------------ 529 530You can find this file in the BSP Layer at:: 531 532 meta-bsp_root_name/conf/layer.conf 533 534The ``conf/layer.conf`` file identifies the file structure as a layer, 535identifies the contents of the layer, and contains information about how 536the build system should use it. Generally, a standard boilerplate file 537such as the following works. In the following example, you would replace 538"bsp" with the actual name of the BSP (i.e. "bsp_root_name" from the example 539template). :: 540 541 # We have a conf and classes directory, add to BBPATH 542 BBPATH .= ":${LAYERDIR}" 543 544 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES 545 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ 546 ${LAYERDIR}/recipes-*/*/*.bbappend" 547 548 BBFILE_COLLECTIONS += "bsp" 549 BBFILE_PATTERN_bsp = "^${LAYERDIR}/" 550 BBFILE_PRIORITY_bsp = "6" 551 LAYERDEPENDS_bsp = "intel" 552 553To illustrate the string substitutions, here are the corresponding 554statements from the Raspberry Pi ``conf/layer.conf`` file:: 555 556 # We have a conf and classes directory, append to BBPATH 557 BBPATH .= ":${LAYERDIR}" 558 559 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES 560 BBFILES += "${LAYERDIR}/recipes*/*/*.bb \ 561 ${LAYERDIR}/recipes*/*/*.bbappend" 562 563 BBFILE_COLLECTIONS += "raspberrypi" 564 BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/" 565 BBFILE_PRIORITY_raspberrypi = "9" 566 567 # Additional license directories. 568 LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" 569 . 570 . 571 . 572 573This file simply makes :term:`BitBake` aware of the recipes and configuration 574directories. The file must exist so that the OpenEmbedded build system can 575recognize the BSP. 576 577Hardware Configuration Options 578------------------------------ 579 580You can find these files in the BSP Layer at:: 581 582 meta-bsp_root_name/conf/machine/*.conf 583 584The machine files bind together all the information contained elsewhere 585in the BSP into a format that the build system can understand. Each BSP 586Layer requires at least one machine file. If the BSP supports multiple 587machines, multiple machine configuration files can exist. These 588filenames correspond to the values to which users have set the 589:term:`MACHINE` variable. 590 591These files define things such as the kernel package to use 592(:term:`PREFERRED_PROVIDER` of 593:ref:`virtual/kernel <dev-manual/common-tasks:using virtual providers>`), 594the hardware drivers to include in different types of images, any 595special software components that are needed, any bootloader information, 596and also any special image format requirements. 597 598This configuration file could also include a hardware "tuning" file that 599is commonly used to define the package architecture and specify 600optimization flags, which are carefully chosen to give best performance 601on a given processor. 602 603Tuning files are found in the ``meta/conf/machine/include`` directory 604within the :term:`Source Directory`. 605For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``, 606``tune-1586-nlp.inc``, and so forth) reside in the 607``poky/meta/conf/machine/include`` directory. 608 609To use an include file, you simply include them in the machine 610configuration file. For example, the Raspberry Pi BSP 611``raspberrypi3.conf`` contains the following statement:: 612 613 include conf/machine/include/rpi-base.inc 614 615Miscellaneous BSP-Specific Recipe Files 616--------------------------------------- 617 618You can find these files in the BSP Layer at:: 619 620 meta-bsp_root_name/recipes-bsp/* 621 622This optional directory contains miscellaneous recipe files for the BSP. 623Most notably would be the formfactor files. For example, in the 624Raspberry Pi BSP, there is the ``formfactor_0.0.bbappend`` file, which 625is an append file used to augment the recipe that starts the build. 626Furthermore, there are machine-specific settings used during the build 627that are defined by the ``machconfig`` file further down in the 628directory. Here is the ``machconfig`` file for the Raspberry Pi BSP:: 629 630 HAVE_TOUCHSCREEN=0 631 HAVE_KEYBOARD=1 632 633 DISPLAY_CAN_ROTATE=0 634 DISPLAY_ORIENTATION=0 635 DISPLAY_DPI=133 636 637.. note:: 638 639 If a BSP does not have a formfactor entry, defaults are established 640 according to the formfactor configuration file that is installed by 641 the main formfactor recipe 642 ``meta/recipes-bsp/formfactor/formfactor_0.0.bb``, which is found in 643 the :term:`Source Directory`. 644 645Display Support Files 646--------------------- 647 648You can find these files in the BSP Layer at:: 649 650 meta-bsp_root_name/recipes-graphics/* 651 652This optional directory contains recipes for the BSP if it has special 653requirements for graphics support. All files that are needed for the BSP 654to support a display are kept here. 655 656Linux Kernel Configuration 657-------------------------- 658 659You can find these files in the BSP Layer at:: 660 661 meta-bsp_root_name/recipes-kernel/linux/linux*.bbappend 662 meta-bsp_root_name/recipes-kernel/linux/*.bb 663 664Append files (``*.bbappend``) modify the main kernel recipe being used 665to build the image. The ``*.bb`` files would be a developer-supplied 666kernel recipe. This area of the BSP hierarchy can contain both these 667types of files although, in practice, it is likely that you would have 668one or the other. 669 670For your BSP, you typically want to use an existing Yocto Project kernel 671recipe found in the :term:`Source Directory` 672at 673``meta/recipes-kernel/linux``. You can append machine-specific changes 674to the kernel recipe by using a similarly named append file, which is 675located in the BSP Layer for your target device (e.g. the 676``meta-bsp_root_name/recipes-kernel/linux`` directory). 677 678Suppose you are using the ``linux-yocto_4.4.bb`` recipe to build the 679kernel. In other words, you have selected the kernel in your 680``"bsp_root_name".conf`` file by adding 681:term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` 682statements as follows:: 683 684 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 685 PREFERRED_VERSION_linux-yocto ?= "4.4%" 686 687.. note:: 688 689 When the preferred provider is assumed by default, the :term:`PREFERRED_PROVIDER` 690 statement does not appear in the ``"bsp_root_name".conf`` file. 691 692You would use the ``linux-yocto_4.4.bbappend`` file to append specific 693BSP settings to the kernel, thus configuring the kernel for your 694particular BSP. 695 696You can find more information on what your append file should contain in 697the ":ref:`kernel-dev/common:creating the append file`" section 698in the Yocto Project Linux Kernel Development Manual. 699 700An alternate scenario is when you create your own kernel recipe for the 701BSP. A good example of this is the Raspberry Pi BSP. If you examine the 702``recipes-kernel/linux`` directory you see the following:: 703 704 linux-raspberrypi-dev.bb 705 linux-raspberrypi.inc 706 linux-raspberrypi_4.14.bb 707 linux-raspberrypi_4.9.bb 708 709The directory contains three kernel recipes and a common include file. 710 711Developing a Board Support Package (BSP) 712======================================== 713 714This section describes the high-level procedure you can follow to create 715a BSP. Although not required for BSP creation, the ``meta-intel`` 716repository, which contains many BSPs supported by the Yocto Project, is 717part of the example. 718 719For an example that shows how to create a new layer using the tools, see 720the ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" 721section. 722 723The following illustration and list summarize the BSP creation general 724workflow. 725 726.. image:: figures/bsp-dev-flow.png 727 :align: center 728 729#. *Set up Your Host Development System to Support Development Using the 730 Yocto Project*: See the ":ref:`dev-manual/start:preparing the build host`" 731 section in the Yocto Project Development Tasks Manual for options on how to 732 get a system ready to use the Yocto Project. 733 734#. *Establish the meta-intel Repository on Your System:* Having 735 local copies of these supported BSP layers on your system gives you 736 access to layers you might be able to leverage when creating your 737 BSP. For information on how to get these files, see the 738 ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`" 739 section. 740 741#. *Create Your Own BSP Layer Using the bitbake-layers Script:* 742 Layers are ideal for isolating and storing work for a given piece of 743 hardware. A layer is really just a location or area in which you 744 place the recipes and configurations for your BSP. In fact, a BSP is, 745 in itself, a special type of layer. The simplest way to create a new 746 BSP layer that is compliant with the Yocto Project is to use the 747 ``bitbake-layers`` script. For information about that script, see the 748 ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" 749 section. 750 751 Another example that illustrates a layer is an application. Suppose 752 you are creating an application that has library or other 753 dependencies in order for it to compile and run. The layer, in this 754 case, would be where all the recipes that define those dependencies 755 are kept. The key point for a layer is that it is an isolated area 756 that contains all the relevant information for the project that the 757 OpenEmbedded build system knows about. For more information on 758 layers, see the ":ref:`overview-manual/yp-intro:the yocto project layer model`" 759 section in the Yocto Project Overview and Concepts Manual. You can also 760 reference the ":ref:`dev-manual/common-tasks:understanding and creating layers`" 761 section in the Yocto Project Development Tasks Manual. For more 762 information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" 763 section. 764 765 .. note:: 766 767 - There are four hardware reference BSPs in the Yocto 768 Project release, located in the ``poky/meta-yocto-bsp`` 769 BSP layer: 770 771 - Texas Instruments Beaglebone (``beaglebone-yocto``) 772 773 - Ubiquiti Networks EdgeRouter Lite (``edgerouter``) 774 775 - Two general IA platforms (``genericx86`` and ``genericx86-64``) 776 777 - There are three core Intel BSPs in the Yocto Project 778 release, in the ``meta-intel`` layer: 779 780 - ``intel-core2-32``, which is a BSP optimized for the Core2 781 family of CPUs as well as all CPUs prior to the Silvermont 782 core. 783 784 - ``intel-corei7-64``, which is a BSP optimized for Nehalem 785 and later Core and Xeon CPUs as well as Silvermont and later 786 Atom CPUs, such as the Baytrail SoCs. 787 788 - ``intel-quark``, which is a BSP optimized for the Intel 789 Galileo gen1 & gen2 development boards. 790 791 When you set up a layer for a new BSP, you should follow a standard 792 layout. This layout is described in the ":ref:`bsp-guide/bsp:example filesystem layout`" 793 section. In the standard layout, notice 794 the suggested structure for recipes and configuration information. 795 You can see the standard layout for a BSP by examining any supported 796 BSP found in the ``meta-intel`` layer inside the Source Directory. 797 798#. *Make Configuration Changes to Your New BSP Layer:* The standard BSP 799 layer structure organizes the files you need to edit in ``conf`` and 800 several ``recipes-*`` directories within the BSP layer. Configuration 801 changes identify where your new layer is on the local system and 802 identifies the kernel you are going to use. When you run the 803 ``bitbake-layers`` script, you are able to interactively configure 804 many things for the BSP (e.g. keyboard, touchscreen, and so forth). 805 806#. *Make Recipe Changes to Your New BSP Layer:* Recipe changes include 807 altering recipes (``*.bb`` files), removing recipes you do not use, 808 and adding new recipes or append files (``.bbappend``) that support 809 your hardware. 810 811#. *Prepare for the Build:* Once you have made all the changes to your 812 BSP layer, there remains a few things you need to do for the 813 OpenEmbedded build system in order for it to create your image. You 814 need to get the build environment ready by sourcing an environment 815 setup script (i.e. ``oe-init-build-env``) and you need to be sure two 816 key configuration files are configured appropriately: the 817 ``conf/local.conf`` and the ``conf/bblayers.conf`` file. You must 818 make the OpenEmbedded build system aware of your new layer. See the 819 ":ref:`dev-manual/common-tasks:enabling your layer`" 820 section in the Yocto Project Development Tasks Manual for information 821 on how to let the build system know about your new layer. 822 823#. *Build the Image:* The OpenEmbedded build system uses the BitBake 824 tool to build images based on the type of image you want to create. 825 You can find more information about BitBake in the 826 :doc:`BitBake User Manual <bitbake:index>`. 827 828 The build process supports several types of images to satisfy 829 different needs. See the 830 ":ref:`ref-manual/images:Images`" chapter in the Yocto 831 Project Reference Manual for information on supported images. 832 833Requirements and Recommendations for Released BSPs 834================================================== 835 836This section describes requirements and recommendations for a released 837BSP to be considered compliant with the Yocto Project. 838 839Released BSP Requirements 840------------------------- 841 842Before looking at BSP requirements, you should consider the following: 843 844- The requirements here assume the BSP layer is a well-formed, "legal" 845 layer that can be added to the Yocto Project. For guidelines on 846 creating a layer that meets these base requirements, see the 847 ":ref:`bsp-guide/bsp:bsp layers`" section in this manual and the 848 ":ref:`dev-manual/common-tasks:understanding and creating layers`" 849 section in the Yocto Project Development Tasks Manual. 850 851- The requirements in this section apply regardless of how you package 852 a BSP. You should consult the packaging and distribution guidelines 853 for your specific release process. For an example of packaging and 854 distribution requirements, see the ":yocto_wiki:`Third Party BSP Release 855 Process </Third_Party_BSP_Release_Process>`" 856 wiki page. 857 858- The requirements for the BSP as it is made available to a developer 859 are completely independent of the released form of the BSP. For 860 example, the BSP Metadata can be contained within a Git repository 861 and could have a directory structure completely different from what 862 appears in the officially released BSP layer. 863 864- It is not required that specific packages or package modifications 865 exist in the BSP layer, beyond the requirements for general 866 compliance with the Yocto Project. For example, there is no requirement 867 dictating that a specific kernel or kernel version be used in a given 868 BSP. 869 870Following are the requirements for a released BSP that conform to the 871Yocto Project: 872 873- *Layer Name:* The BSP must have a layer name that follows the Yocto 874 Project standards. For information on BSP layer names, see the 875 ":ref:`bsp-guide/bsp:bsp layers`" section. 876 877- *File System Layout:* When possible, use the same directory names in 878 your BSP layer as listed in the ``recipes.txt`` file, which is found 879 in ``poky/meta`` directory of the :term:`Source Directory` 880 or in the OpenEmbedded-Core Layer (``openembedded-core``) at 881 :oe_git:`/openembedded-core/tree/meta`. 882 883 You should place recipes (``*.bb`` files) and recipe modifications 884 (``*.bbappend`` files) into ``recipes-*`` subdirectories by 885 functional area as outlined in ``recipes.txt``. If you cannot find a 886 category in ``recipes.txt`` to fit a particular recipe, you can make 887 up your own ``recipes-*`` subdirectory. 888 889 Within any particular ``recipes-*`` category, the layout should match 890 what is found in the OpenEmbedded-Core Git repository 891 (``openembedded-core``) or the Source Directory (``poky``). In other 892 words, make sure you place related files in appropriately-related 893 ``recipes-*`` subdirectories specific to the recipe's function, or 894 within a subdirectory containing a set of closely-related recipes. 895 The recipes themselves should follow the general guidelines for 896 recipes used in the Yocto Project found in the ":oe_wiki:`OpenEmbedded 897 Style Guide </Styleguide>`". 898 899- *License File:* You must include a license file in the 900 ``meta-bsp_root_name`` directory. This license covers the BSP 901 Metadata as a whole. You must specify which license to use since no 902 default license exists. See the 903 :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>` 904 file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer 905 as an example. 906 907- *README File:* You must include a ``README`` file in the 908 ``meta-bsp_root_name`` directory. See the 909 :yocto_git:`README.md </meta-raspberrypi/tree/README.md>` 910 file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer 911 as an example. 912 913 At a minimum, the ``README`` file should contain the following: 914 915 - A brief description of the target hardware. 916 917 - A list of all the dependencies of the BSP. These dependencies are 918 typically a list of required layers needed to build the BSP. 919 However, the dependencies should also contain information 920 regarding any other dependencies the BSP might have. 921 922 - Any required special licensing information. For example, this 923 information includes information on special variables needed to 924 satisfy a EULA, or instructions on information needed to build or 925 distribute binaries built from the BSP Metadata. 926 927 - The name and contact information for the BSP layer maintainer. 928 This is the person to whom patches and questions should be sent. 929 For information on how to find the right person, see the 930 ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" 931 section in the Yocto Project Development Tasks Manual. 932 933 - Instructions on how to build the BSP using the BSP layer. 934 935 - Instructions on how to boot the BSP build from the BSP layer. 936 937 - Instructions on how to boot the binary images contained in the 938 ``binary`` directory, if present. 939 940 - Information on any known bugs or issues that users should know 941 about when either building or booting the BSP binaries. 942 943- *README.sources File:* If your BSP contains binary images in the 944 ``binary`` directory, you must include a ``README.sources`` file in 945 the ``meta-bsp_root_name`` directory. This file specifies exactly 946 where you can find the sources used to generate the binary images. 947 948- *Layer Configuration File:* You must include a ``conf/layer.conf`` 949 file in the ``meta-bsp_root_name`` directory. This file identifies 950 the ``meta-bsp_root_name`` BSP layer as a layer to the build 951 system. 952 953- *Machine Configuration File:* You must include one or more 954 ``conf/machine/bsp_root_name.conf`` files in the 955 ``meta-bsp_root_name`` directory. These configuration files define 956 machine targets that can be built using the BSP layer. Multiple 957 machine configuration files define variations of machine 958 configurations that the BSP supports. If a BSP supports multiple 959 machine variations, you need to adequately describe each variation in 960 the BSP ``README`` file. Do not use multiple machine configuration 961 files to describe disparate hardware. If you do have very different 962 targets, you should create separate BSP layers for each target. 963 964 .. note:: 965 966 It is completely possible for a developer to structure the working 967 repository as a conglomeration of unrelated BSP files, and to possibly 968 generate BSPs targeted for release from that directory using scripts or 969 some other mechanism (e.g. ``meta-yocto-bsp`` layer). Such considerations 970 are outside the scope of this document. 971 972Released BSP Recommendations 973---------------------------- 974 975Following are recommendations for released BSPs that conform to the 976Yocto Project: 977 978- *Bootable Images:* Released BSPs can contain one or more bootable 979 images. Including bootable images allows users to easily try out the 980 BSP using their own hardware. 981 982 In some cases, it might not be convenient to include a bootable 983 image. If so, you might want to make two versions of the BSP 984 available: one that contains binary images, and one that does not. 985 The version that does not contain bootable images avoids unnecessary 986 download times for users not interested in the images. 987 988 If you need to distribute a BSP and include bootable images or build 989 kernel and filesystems meant to allow users to boot the BSP for 990 evaluation purposes, you should put the images and artifacts within a 991 ``binary/`` subdirectory located in the ``meta-bsp_root_name`` 992 directory. 993 994 .. note:: 995 996 If you do include a bootable image as part of the BSP and the 997 image was built by software covered by the GPL or other open 998 source licenses, it is your responsibility to understand and meet 999 all licensing requirements, which could include distribution of 1000 source files. 1001 1002- *Use a Yocto Linux Kernel:* Kernel recipes in the BSP should be based 1003 on a Yocto Linux kernel. Basing your recipes on these kernels reduces 1004 the costs for maintaining the BSP and increases its scalability. See 1005 the ``Yocto Linux Kernel`` category in the 1006 :yocto_git:`Source Repositories <>` for these kernels. 1007 1008Customizing a Recipe for a BSP 1009============================== 1010 1011If you plan on customizing a recipe for a particular BSP, you need to do 1012the following: 1013 1014- Create a ``*.bbappend`` file for the modified recipe. For information on using 1015 append files, see the 1016 ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`" 1017 section in the Yocto Project Development Tasks Manual. 1018 1019- Ensure your directory structure in the BSP layer that supports your 1020 machine is such that the OpenEmbedded build system can find it. See 1021 the example later in this section for more information. 1022 1023- Put the append file in a directory whose name matches the machine's 1024 name and is located in an appropriate sub-directory inside the BSP 1025 layer (i.e. ``recipes-bsp``, ``recipes-graphics``, ``recipes-core``, 1026 and so forth). 1027 1028- Place the BSP-specific files in the proper directory inside the BSP 1029 layer. How expansive the layer is affects where you must place these 1030 files. For example, if your layer supports several different machine 1031 types, you need to be sure your layer's directory structure includes 1032 hierarchy that separates the files according to machine. If your 1033 layer does not support multiple machines, the layer would not have 1034 that additional hierarchy and the files would obviously not be able 1035 to reside in a machine-specific directory. 1036 1037Following is a specific example to help you better understand the 1038process. This example customizes a recipe by adding a 1039BSP-specific configuration file named ``interfaces`` to the 1040``init-ifupdown_1.0.bb`` recipe for machine "xyz" where the BSP layer 1041also supports several other machines: 1042 1043#. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the 1044 following:: 1045 1046 FILESEXTRAPATHS:prepend := "${THISDIR}/files:" 1047 1048 The append file needs to be in the ``meta-xyz/recipes-core/init-ifupdown`` 1049 directory. 1050 1051#. Create and place the new ``interfaces`` configuration file in the 1052 BSP's layer here:: 1053 1054 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces 1055 1056 .. note:: 1057 1058 If the ``meta-xyz`` layer did not support multiple machines, you would place 1059 the interfaces configuration file in the layer here:: 1060 1061 meta-xyz/recipes-core/init-ifupdown/files/interfaces 1062 1063 The :term:`FILESEXTRAPATHS` variable in the append files extends the search 1064 path the build system uses to find files during the build. Consequently, for 1065 this example you need to have the ``files`` directory in the same location as 1066 your append file. 1067 1068BSP Licensing Considerations 1069============================ 1070 1071In some cases, a BSP contains separately-licensed Intellectual Property 1072(IP) for a component or components. For these cases, you are required to 1073accept the terms of a commercial or other type of license that requires 1074some kind of explicit End User License Agreement (EULA). Once you accept 1075the license, the OpenEmbedded build system can then build and include 1076the corresponding component in the final BSP image. If the BSP is 1077available as a pre-built image, you can download the image after 1078agreeing to the license or EULA. 1079 1080You could find that some separately-licensed components that are 1081essential for normal operation of the system might not have an 1082unencumbered (or free) substitute. Without these essential components, 1083the system would be non-functional. Then again, you might find that 1084other licensed components that are simply 'good-to-have' or purely 1085elective do have an unencumbered, free replacement component that you 1086can use rather than agreeing to the separately-licensed component. Even 1087for components essential to the system, you might find an unencumbered 1088component that is not identical but will work as a less-capable version 1089of the licensed version in the BSP recipe. 1090 1091For cases where you can substitute a free component and still maintain 1092the system's functionality, the "DOWNLOADS" selection from the 1093"SOFTWARE" tab on the :yocto_home:`Yocto Project Website <>` makes 1094available de-featured BSPs that are completely free of any IP 1095encumbrances. For these cases, you can use the substitution directly and 1096without any further licensing requirements. If present, these fully 1097de-featured BSPs are named appropriately different as compared to the 1098names of their respective encumbered BSPs. If available, these 1099substitutions are your simplest and most preferred options. Obviously, 1100use of these substitutions assumes the resulting functionality meets 1101system requirements. 1102 1103.. note:: 1104 1105 If however, a non-encumbered version is unavailable or it provides 1106 unsuitable functionality or quality, you can use an encumbered 1107 version. 1108 1109There are two different methods within the OpenEmbedded build system to 1110satisfy the licensing requirements for an encumbered BSP. The following 1111list describes them in order of preference: 1112 1113#. *Use the LICENSE_FLAGS Variable to Define the Recipes that Have Commercial or 1114 Other Types of Specially-Licensed Packages:* For each of those recipes, you can 1115 specify a matching license string in a ``local.conf`` variable named 1116 :term:`LICENSE_FLAGS_ACCEPTED`. 1117 Specifying the matching license string signifies that you agree to 1118 the license. Thus, the build system can build the corresponding 1119 recipe and include the component in the image. See the 1120 ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`" 1121 section in the Yocto Project Development Tasks Manual for details on 1122 how to use these variables. 1123 1124 If you build as you normally would, without specifying any recipes in 1125 the :term:`LICENSE_FLAGS_ACCEPTED` variable, the build stops and provides 1126 you with the list of recipes that you have tried to include in the image 1127 that need entries in the :term:`LICENSE_FLAGS_ACCEPTED` variable. Once you 1128 enter the appropriate license flags into it, restart the build to continue 1129 where it left off. During the build, the prompt will not appear again since 1130 you have satisfied the requirement. 1131 1132 Once the appropriate license flags are on the white list in the 1133 :term:`LICENSE_FLAGS_ACCEPTED` variable, you can build the encumbered 1134 image with no change at all to the normal build process. 1135 1136#. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by 1137 selecting the "DOWNLOADS" item from the "SOFTWARE" tab on the 1138 :yocto_home:`Yocto Project website <>`. You can download BSP tarballs 1139 that contain proprietary components after agreeing to the licensing 1140 requirements of each of the individually encumbered packages as part 1141 of the download process. Obtaining the BSP this way allows you to 1142 access an encumbered image immediately after agreeing to the 1143 click-through license agreements presented by the website. If you 1144 want to build the image yourself using the recipes contained within 1145 the BSP tarball, you will still need to create an appropriate 1146 :term:`LICENSE_FLAGS_ACCEPTED` to match the encumbered recipes in the 1147 BSP. 1148 1149.. note:: 1150 1151 Pre-compiled images are bundled with a time-limited kernel that runs 1152 for a predetermined amount of time (10 days) before it forces the 1153 system to reboot. This limitation is meant to discourage direct 1154 redistribution of the image. You must eventually rebuild the image if 1155 you want to remove this restriction. 1156 1157Creating a new BSP Layer Using the ``bitbake-layers`` Script 1158============================================================ 1159 1160The ``bitbake-layers create-layer`` script automates creating a BSP 1161layer. What makes a layer a "BSP layer" is the presence of at least one 1162machine configuration file. Additionally, a BSP layer usually has a 1163kernel recipe or an append file that leverages off an existing kernel 1164recipe. The primary requirement, however, is the machine configuration. 1165 1166Use these steps to create a BSP layer: 1167 1168- *Create a General Layer:* Use the ``bitbake-layers`` script with the 1169 ``create-layer`` subcommand to create a new general layer. For 1170 instructions on how to create a general layer using the 1171 ``bitbake-layers`` script, see the 1172 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" 1173 section in the Yocto Project Development Tasks Manual. 1174 1175- *Create a Layer Configuration File:* Every layer needs a layer 1176 configuration file. This configuration file establishes locations for 1177 the layer's recipes, priorities for the layer, and so forth. You can 1178 find examples of ``layer.conf`` files in the Yocto Project 1179 :yocto_git:`Source Repositories <>`. To get examples of what you need 1180 in your configuration file, locate a layer (e.g. "meta-ti") and 1181 examine the 1182 :yocto_git:`local.conf </meta-ti/tree/meta-ti-bsp/conf/layer.conf>` 1183 file. 1184 1185- *Create a Machine Configuration File:* Create a 1186 ``conf/machine/bsp_root_name.conf`` file. See 1187 :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>` 1188 for sample ``bsp_root_name.conf`` files. There are other samples such as 1189 :yocto_git:`meta-ti </meta-ti/tree/meta-ti-bsp/conf/machine>` 1190 and 1191 :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>` 1192 from other vendors that have more specific machine and tuning 1193 examples. 1194 1195- *Create a Kernel Recipe:* Create a kernel recipe in 1196 ``recipes-kernel/linux`` by either using a kernel append file or a 1197 new custom kernel recipe file (e.g. ``yocto-linux_4.12.bb``). The BSP 1198 layers mentioned in the previous step also contain different kernel 1199 examples. See the ":ref:`kernel-dev/common:modifying an existing recipe`" 1200 section in the Yocto Project Linux Kernel Development Manual for 1201 information on how to create a custom kernel. 1202 1203The remainder of this section provides a description of the Yocto 1204Project reference BSP for Beaglebone, which resides in the 1205:yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>` 1206layer. 1207 1208BSP Layer Configuration Example 1209------------------------------- 1210 1211The layer's ``conf`` directory contains the ``layer.conf`` configuration 1212file. In this example, the ``conf/layer.conf`` file is the following:: 1213 1214 # We have a conf and classes directory, add to BBPATH 1215 BBPATH .= ":${LAYERDIR}" 1216 1217 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES 1218 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ 1219 ${LAYERDIR}/recipes-*/*/*.bbappend" 1220 1221 BBFILE_COLLECTIONS += "yoctobsp" 1222 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" 1223 BBFILE_PRIORITY_yoctobsp = "5" 1224 LAYERVERSION_yoctobsp = "4" 1225 LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;" 1226 1227The variables used in this file configure the layer. A good way to learn about layer 1228configuration files is to examine various files for BSP from the 1229:yocto_git:`Source Repositories <>`. 1230 1231For a detailed description of this particular layer configuration file, 1232see ":ref:`step 3 <dev-manual/common-tasks:creating your own layer>`" 1233in the discussion that describes how to create layers in the Yocto 1234Project Development Tasks Manual. 1235 1236BSP Machine Configuration Example 1237--------------------------------- 1238 1239As mentioned earlier in this section, the existence of a machine 1240configuration file is what makes a layer a BSP layer as compared to a 1241general or kernel layer. 1242 1243There are one or more machine configuration files in the 1244``bsp_layer/conf/machine/`` directory of the layer:: 1245 1246 bsp_layer/conf/machine/machine1\.conf 1247 bsp_layer/conf/machine/machine2\.conf 1248 bsp_layer/conf/machine/machine3\.conf 1249 ... more ... 1250 1251For example, the machine configuration file for the `BeagleBone and 1252BeagleBone Black development boards <https://beagleboard.org/bone>`__ is 1253located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named 1254``beaglebone-yocto.conf``:: 1255 1256 #@TYPE: Machine 1257 #@NAME: Beaglebone-yocto machine 1258 #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards 1259 1260 PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg" 1261 XSERVER ?= "xserver-xorg \ 1262 xf86-video-modesetting \ 1263 " 1264 1265 MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree" 1266 1267 EXTRA_IMAGEDEPENDS += "u-boot" 1268 1269 DEFAULTTUNE ?= "cortexa8hf-neon" 1270 include conf/machine/include/arm/armv7a/tune-cortexa8.inc 1271 1272 IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" 1273 EXTRA_IMAGECMD:jffs2 = "-lnp " 1274 WKS_FILE ?= "beaglebone-yocto.wks" 1275 IMAGE_INSTALL:append = " kernel-devicetree kernel-image-zimage" 1276 do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot" 1277 1278 SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0" 1279 SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}" 1280 1281 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 1282 PREFERRED_VERSION_linux-yocto ?= "5.0%" 1283 1284 KERNEL_IMAGETYPE = "zImage" 1285 KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" 1286 KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" 1287 1288 SPL_BINARY = "MLO" 1289 UBOOT_SUFFIX = "img" 1290 UBOOT_MACHINE = "am335x_evm_defconfig" 1291 UBOOT_ENTRYPOINT = "0x80008000" 1292 UBOOT_LOADADDRESS = "0x80008000" 1293 1294 MACHINE_FEATURES = "usbgadget usbhost vfat alsa" 1295 1296 IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" 1297 1298The variables used to configure the machine define machine-specific properties; for 1299example, machine-dependent packages, machine tunings, the type of kernel 1300to build, and U-Boot configurations. 1301 1302The following list provides some explanation for the statements found in 1303the example reference machine configuration file for the BeagleBone 1304development boards. Realize that much more can be defined as part of a 1305machine's configuration file. In general, you can learn about related 1306variables that this example does not have by locating the variables in 1307the ":ref:`ref-manual/variables:variables glossary`" in the Yocto 1308Project Reference Manual. 1309 1310- :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`: 1311 The recipe that provides "virtual/xserver" when more than one 1312 provider is found. In this case, the recipe that provides 1313 "virtual/xserver" is "xserver-xorg", available in 1314 ``poky/meta/recipes-graphics/xorg-xserver``. 1315 1316- :term:`XSERVER`: The packages that 1317 should be installed to provide an X server and drivers for the 1318 machine. In this example, the "xserver-xorg" and 1319 "xf86-video-modesetting" are installed. 1320 1321- :term:`MACHINE_EXTRA_RRECOMMENDS`: 1322 A list of machine-dependent packages not essential for booting the 1323 image. Thus, the build does not fail if the packages do not exist. 1324 However, the packages are required for a fully-featured image. 1325 1326 .. tip:: 1327 1328 There are many ``MACHINE*`` variables that help you configure a particular piece 1329 of hardware. 1330 1331- :term:`EXTRA_IMAGEDEPENDS`: 1332 Recipes to build that do not provide packages for installing into the 1333 root filesystem but building the image depends on the recipes. 1334 Sometimes a recipe is required to build the final image but is not 1335 needed in the root filesystem. In this case, the U-Boot recipe must 1336 be built for the image. 1337 1338- :term:`DEFAULTTUNE`: Machines 1339 use tunings to optimize machine, CPU, and application performance. 1340 These features, which are collectively known as "tuning features", 1341 are set in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g. 1342 ``poky/meta/conf/machine/include``). In this example, the default 1343 tuning file is ``cortexa8hf-neon``. 1344 1345 .. note:: 1346 1347 The include statement that pulls in the 1348 ``conf/machine/include/arm/tune-cortexa8.inc`` file provides many tuning 1349 possibilities. 1350 1351- :term:`IMAGE_FSTYPES`: The 1352 formats the OpenEmbedded build system uses during the build when 1353 creating the root filesystem. In this example, four types of images 1354 are supported. 1355 1356- :term:`EXTRA_IMAGECMD`: 1357 Specifies additional options for image creation commands. In this 1358 example, the "-lnp " option is used when creating the 1359 `JFFS2 <https://en.wikipedia.org/wiki/JFFS2>`__ image. 1360 1361- :term:`WKS_FILE`: The location of 1362 the :ref:`Wic kickstart <ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used 1363 by the OpenEmbedded build system to create a partitioned image 1364 (image.wic). 1365 1366- :term:`IMAGE_INSTALL`: 1367 Specifies packages to install into an image through the 1368 :ref:`image <ref-classes-image>` class. Recipes 1369 use the :term:`IMAGE_INSTALL` variable. 1370 1371- ``do_image_wic[depends]``: A task that is constructed during the 1372 build. In this example, the task depends on specific tools in order 1373 to create the sysroot when building a Wic image. 1374 1375- :term:`SERIAL_CONSOLES`: 1376 Defines a serial console (TTY) to enable using getty. In this case, 1377 the baud rate is "115200" and the device name is "ttyO0". 1378 1379- :term:`PREFERRED_PROVIDER_virtual/kernel <PREFERRED_PROVIDER>`: 1380 Specifies the recipe that provides "virtual/kernel" when more than 1381 one provider is found. In this case, the recipe that provides 1382 "virtual/kernel" is "linux-yocto", which exists in the layer's 1383 ``recipes-kernel/linux`` directory. 1384 1385- :term:`PREFERRED_VERSION_linux-yocto <PREFERRED_VERSION>`: 1386 Defines the version of the recipe used to build the kernel, which is 1387 "5.0" in this case. 1388 1389- :term:`KERNEL_IMAGETYPE`: 1390 The type of kernel to build for the device. In this case, the 1391 OpenEmbedded build system creates a "zImage" image type. 1392 1393- :term:`KERNEL_DEVICETREE`: 1394 The names of the generated Linux kernel device trees (i.e. the 1395 ``*.dtb``) files. All the device trees for the various BeagleBone 1396 devices are included. 1397 1398- :term:`KERNEL_EXTRA_ARGS`: 1399 Additional ``make`` command-line arguments the OpenEmbedded build 1400 system passes on when compiling the kernel. In this example, 1401 ``LOADADDR=${UBOOT_ENTRYPOINT}`` is passed as a command-line argument. 1402 1403- :term:`SPL_BINARY`: Defines the 1404 Secondary Program Loader (SPL) binary type. In this case, the SPL 1405 binary is set to "MLO", which stands for Multimedia card LOader. 1406 1407 The BeagleBone development board requires an SPL to boot and that SPL 1408 file type must be MLO. Consequently, the machine configuration needs 1409 to define :term:`SPL_BINARY` as ``MLO``. 1410 1411 .. note:: 1412 1413 For more information on how the SPL variables are used, see the 1414 :yocto_git:`u-boot.inc </poky/tree/meta/recipes-bsp/u-boot/u-boot.inc>` 1415 include file. 1416 1417- :term:`UBOOT_* <UBOOT_ENTRYPOINT>`: Defines 1418 various U-Boot configurations needed to build a U-Boot image. In this 1419 example, a U-Boot image is required to boot the BeagleBone device. 1420 See the following variables for more information: 1421 1422 - :term:`UBOOT_SUFFIX`: 1423 Points to the generated U-Boot extension. 1424 1425 - :term:`UBOOT_MACHINE`: 1426 Specifies the value passed on the make command line when building 1427 a U-Boot image. 1428 1429 - :term:`UBOOT_ENTRYPOINT`: 1430 Specifies the entry point for the U-Boot image. 1431 1432 - :term:`UBOOT_LOADADDRESS`: 1433 Specifies the load address for the U-Boot image. 1434 1435- :term:`MACHINE_FEATURES`: 1436 Specifies the list of hardware features the BeagleBone device is 1437 capable of supporting. In this case, the device supports "usbgadget 1438 usbhost vfat alsa". 1439 1440- :term:`IMAGE_BOOT_FILES`: 1441 Files installed into the device's boot partition when preparing the 1442 image using the Wic tool with the ``bootimg-partition`` or 1443 ``bootimg-efi`` source plugin. 1444 1445BSP Kernel Recipe Example 1446------------------------- 1447 1448The kernel recipe used to build the kernel image for the BeagleBone 1449device was established in the machine configuration:: 1450 1451 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 1452 PREFERRED_VERSION_linux-yocto ?= "5.0%" 1453 1454The ``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains 1455metadata used to build the kernel. In this case, a kernel append file 1456(i.e. ``linux-yocto_5.0.bbappend``) is used to override an established 1457kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in 1458:yocto_git:`/poky/tree/meta/recipes-kernel/linux`. 1459 1460Following is the contents of the append file:: 1461 1462 KBRANCH:genericx86 = "v5.0/standard/base" 1463 KBRANCH:genericx86-64 = "v5.0/standard/base" 1464 KBRANCH:edgerouter = "v5.0/standard/edgerouter" 1465 KBRANCH:beaglebone-yocto = "v5.0/standard/beaglebone" 1466 1467 KMACHINE:genericx86 ?= "common-pc" 1468 KMACHINE:genericx86-64 ?= "common-pc-64" 1469 KMACHINE:beaglebone-yocto ?= "beaglebone" 1470 1471 SRCREV_machine:genericx86 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" 1472 SRCREV_machine:genericx86-64 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" 1473 SRCREV_machine:edgerouter ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" 1474 SRCREV_machine:beaglebone-yocto ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" 1475 1476 COMPATIBLE_MACHINE:genericx86 = "genericx86" 1477 COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64" 1478 COMPATIBLE_MACHINE:edgerouter = "edgerouter" 1479 COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto" 1480 1481 LINUX_VERSION:genericx86 = "5.0.3" 1482 LINUX_VERSION:genericx86-64 = "5.0.3" 1483 LINUX_VERSION:edgerouter = "5.0.3" 1484 LINUX_VERSION:beaglebone-yocto = "5.0.3" 1485 1486This particular append file works for all the machines that are 1487part of the ``meta-yocto-bsp`` layer. The relevant statements are 1488appended with the "beaglebone-yocto" string. The OpenEmbedded build 1489system uses these statements to override similar statements in the 1490kernel recipe: 1491 1492- :term:`KBRANCH`: Identifies the 1493 kernel branch that is validated, patched, and configured during the 1494 build. 1495 1496- :term:`KMACHINE`: Identifies the 1497 machine name as known by the kernel, which is sometimes a different 1498 name than what is known by the OpenEmbedded build system. 1499 1500- :term:`SRCREV`: Identifies the 1501 revision of the source code used to build the image. 1502 1503- :term:`COMPATIBLE_MACHINE`: 1504 A regular expression that resolves to one or more target machines 1505 with which the recipe is compatible. 1506 1507- :term:`LINUX_VERSION`: The 1508 Linux version from kernel.org used by the OpenEmbedded build system 1509 to build the kernel image. 1510
