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