blob: 5c43f53d0c01d6d86dd0ec5b7a7119cd75fa1d54 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
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
Andrew Geisslerc926e172021-05-07 16:11:35 -050029convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050030
31 meta-bsp_root_name
32
33The string "meta-" is prepended to the
Andrew Geissler4c19ea12020-10-27 13:52:24 -050034machine or platform name, which is "bsp_root_name" in the above form.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050035
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050040 BSP layer name does not need to start with ``meta-``.
41 However, various scripts and tools in the Yocto Project development
Andrew Geisslerc9f78652020-09-18 14:11:35 -050042 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060047:ref:`overview-manual/development-environment:yocto project source repositories`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050048through
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.
Andrew Geisslerc926e172021-05-07 16:11:35 -050061Here is an example that clones the Raspberry Pi BSP layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062
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
Andrew Geissler09209ee2020-12-13 08:44:15 -060075:ref:`dev-manual/start:locating yocto project source files`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050076section 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060084script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050085Adding the root directory allows the :term:`OpenEmbedded Build System`
86to recognize the BSP
Andrew Geisslerc926e172021-05-07 16:11:35 -050087layer and from it build an image. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050088
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
Andrew Geissler09036742021-06-25 14:25:14 -050098 Ordering and :term:`BBFILE_PRIORITY` for the layers listed in :term:`BBLAYERS`
Andrew Geissler4c19ea12020-10-27 13:52:24 -050099 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
Andrew Geissler09036742021-06-25 14:25:14 -0500102 listed in :term:`BBLAYERS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500103
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500111are known as ":term:`container layers <Container Layer>`". An example of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112this 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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500116you want to work with, such as::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600131":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500132section 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500145 For structural information on BSPs, see the
146 :ref:`bsp-guide/bsp:example filesystem layout` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500147
148#. *Set Up the Build Environment:* Be sure you are set up to use BitBake
Andrew Geissler09209ee2020-12-13 08:44:15 -0600149 in a shell. See the ":ref:`dev-manual/start:preparing the build host`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500150 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500154#. *Clone the poky Repository:* You need to have a local copy of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500155 Yocto Project :term:`Source Directory` (i.e. a local
156 ``poky`` repository). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600157 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500158 possibly the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600159 ":ref:`dev-manual/start:checking out by branch in poky`" or
160 ":ref:`dev-manual/start:checking out by tag in poky`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500161 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500172#. *Optionally Clone the meta-intel BSP Layer:* If your hardware is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600175 :yocto_git:`README </meta-intel/tree/README>` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500176
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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500196 Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600208 ":ref:`dev-manual/start:checking out by branch in poky`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500209 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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500219 that layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600232 :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500233 setup script to define the OpenEmbedded build environment on your
234 build host. ::
235
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500236 $ source oe-init-build-env
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500237
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500243Example 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
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500253OpenEmbedded build system. It is also intended that it will be simple
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254to extract information and convert it to other formats if required. The
255OpenEmbedded build system, through its standard :ref:`layers mechanism
Andrew Geissler09209ee2020-12-13 08:44:15 -0600256<overview-manual/yp-intro:the yocto project layer model>`, can
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500257directly 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700270inside a BSP layer, you should be aware that there are some requirements
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500271in 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
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500292the :yocto_git:`Source Repositories <>`:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500293
294.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500295
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500451License Files
452-------------
453
Andrew Geisslerc926e172021-05-07 16:11:35 -0500454You can find these files in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500455
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600466the ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500467section in the Yocto Project Development Tasks Manual.
468
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500469README File
470-----------
471
Andrew Geisslerc926e172021-05-07 16:11:35 -0500472You can find this file in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500484README.sources File
485-------------------
486
Andrew Geisslerc926e172021-05-07 16:11:35 -0500487You can find this file in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500488
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500503Pre-built User Binaries
504-----------------------
505
Andrew Geisslerc926e172021-05-07 16:11:35 -0500506You can find these files in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500507
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500526Layer Configuration File
527------------------------
528
Andrew Geisslerc926e172021-05-07 16:11:35 -0500529You can find this file in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500530
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500537"bsp" with the actual name of the BSP (i.e. "bsp_root_name" from the example
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500538template). ::
539
540 # We have a conf and classes directory, add to BBPATH
541 BBPATH .= ":${LAYERDIR}"
542
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500543 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500544 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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500553statements from the Raspberry Pi ``conf/layer.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500554
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500576Hardware Configuration Options
577------------------------------
578
Andrew Geisslerc926e172021-05-07 16:11:35 -0500579You can find these files in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500580
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600592:ref:`virtual/kernel <dev-manual/common-tasks:using virtual providers>`),
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500593the 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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500610``raspberrypi3.conf`` contains the following statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500611
612 include conf/machine/include/rpi-base.inc
613
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500614Miscellaneous BSP-Specific Recipe Files
615---------------------------------------
616
Andrew Geisslerc926e172021-05-07 16:11:35 -0500617You can find these files in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500618
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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500627directory. Here is the ``machconfig`` file for the Raspberry Pi BSP::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500628
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500644Display Support Files
645---------------------
646
Andrew Geisslerc926e172021-05-07 16:11:35 -0500647You can find these files in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500648
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500655Linux Kernel Configuration
656--------------------------
657
Andrew Geisslerc926e172021-05-07 16:11:35 -0500658You can find these files in the BSP Layer at::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500659
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500679``"bsp_root_name".conf`` file by adding
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500680:term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500681statements as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500682
683 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
684 PREFERRED_VERSION_linux-yocto ?= "4.4%"
685
686.. note::
687
Andrew Geissler09036742021-06-25 14:25:14 -0500688 When the preferred provider is assumed by default, the :term:`PREFERRED_PROVIDER`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500689 statement does not appear in the ``"bsp_root_name".conf`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500690
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600696the ":ref:`kernel-dev/common:creating the append file`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500697in 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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500701``recipes-kernel/linux`` directory you see the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500702
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600729 Yocto Project*: See the ":ref:`dev-manual/start:preparing the build host`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500730 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600757 layers, see the ":ref:`overview-manual/yp-intro:the yocto project layer model`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500758 section in the Yocto Project Overview and Concepts Manual. You can also
Andrew Geissler09209ee2020-12-13 08:44:15 -0600759 reference the ":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500760 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700766 - There are four hardware reference BSPs in the Yocto
767 Project release, located in the ``poky/meta-yocto-bsp``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500768 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700776 - There are three core Intel BSPs in the Yocto Project
777 release, in the ``meta-intel`` layer:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500778
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600818 ":ref:`dev-manual/common-tasks:enabling your layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500819 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600829 ":ref:`ref-manual/images:Images`" chapter in the Yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500830 Project Reference Manual for information on supported images.
831
832Requirements and Recommendations for Released BSPs
833==================================================
834
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700835This section describes requirements and recommendations for a released
836BSP to be considered compliant with the Yocto Project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500837
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600847 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500848 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500853 distribution requirements, see the ":yocto_wiki:`Third Party BSP Release
Andrew Geissler09209ee2020-12-13 08:44:15 -0600854 Process </Third_Party_BSP_Release_Process>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500855 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700865 compliance with the Yocto Project. For example, there is no requirement
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500866 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500880 https://git.openembedded.org/openembedded-core/tree/meta.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500881
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
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600895 recipes used in the Yocto Project found in the ":oe_wiki:`OpenEmbedded
896 Style Guide </Styleguide>`".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500897
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
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700901 default license exists. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600902 :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500903 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600908 :yocto_git:`README.md </meta-raspberrypi/tree/README.md>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500909 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600929 ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500930 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001014 append files, see the ":ref:`dev-manual/common-tasks:using
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001015 .bbappend files in your layer`" section in the Yocto Project Development
1016 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
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001037process. This example customizes a recipe by adding a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001038BSP-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
Andrew Geisslerc926e172021-05-07 16:11:35 -05001043 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001044
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
Andrew Geisslerc926e172021-05-07 16:11:35 -05001051 BSP's layer here::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001052
1053 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
1054
1055 .. note::
1056
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001057 If the ``meta-xyz`` layer did not support multiple machines, you would place
Andrew Geisslerc926e172021-05-07 16:11:35 -05001058 the interfaces configuration file in the layer here::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001059
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
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001108There are two different methods within the OpenEmbedded build system to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001109satisfy 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001119 ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001120 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
Andrew Geissler09036742021-06-25 14:25:14 -05001124 the :term:`LICENSE_FLAGS_WHITELIST`, the build stops and provides you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001125 with the list of recipes that you have tried to include in the image
Andrew Geissler09036742021-06-25 14:25:14 -05001126 that need entries in the :term:`LICENSE_FLAGS_WHITELIST`. Once you enter
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001127 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
Andrew Geissler09036742021-06-25 14:25:14 -05001132 :term:`LICENSE_FLAGS_WHITELIST` variable, you can build the encumbered
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001133 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
Andrew Geissler09036742021-06-25 14:25:14 -05001145 :term:`LICENSE_FLAGS_WHITELIST` to match the encumbered recipes in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001146 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001171 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001172 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001181 :yocto_git:`local.conf </meta-ti/tree/conf/layer.conf>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001182 file.
1183
1184- *Create a Machine Configuration File:* Create a
1185 ``conf/machine/bsp_root_name.conf`` file. See
Andrew Geissler09209ee2020-12-13 08:44:15 -06001186 :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>`
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001187 for sample ``bsp_root_name.conf`` files. There are other samples such as
Andrew Geissler09209ee2020-12-13 08:44:15 -06001188 :yocto_git:`meta-ti </meta-ti/tree/conf/machine>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001189 and
Andrew Geissler09209ee2020-12-13 08:44:15 -06001190 :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>`
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001191 from other vendors that have more specific machine and tuning
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001192 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001198 examples. See the ":ref:`kernel-dev/common:modifying an existing recipe`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001199 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001204:yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001205layer.
1206
1207BSP Layer Configuration Example
1208-------------------------------
1209
1210The layer's ``conf`` directory contains the ``layer.conf`` configuration
Andrew Geisslerc926e172021-05-07 16:11:35 -05001211file. In this example, the ``conf/layer.conf`` is the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001212
1213 # We have a conf and classes directory, add to BBPATH
1214 BBPATH .= ":${LAYERDIR}"
1215
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001216 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001217 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,
Andrew Geissler09209ee2020-12-13 08:44:15 -06001231see ":ref:`step 3 <dev-manual/common-tasks:creating your own layer>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001232in 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001242There are one or more machine configuration files in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001243``bsp_layer/conf/machine/`` directory of the layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001244
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001245 bsp_layer/conf/machine/machine1\.conf
1246 bsp_layer/conf/machine/machine2\.conf
1247 bsp_layer/conf/machine/machine3\.conf
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001248 ... more ...
1249
1250For example, the machine configuration file for the `BeagleBone and
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001251BeagleBone Black development boards <https://beagleboard.org/bone>`__ is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001252located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named
Andrew Geisslerc926e172021-05-07 16:11:35 -05001253``beaglebone-yocto.conf``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001254
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/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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001306the ":ref:`ref-manual/variables:variables glossary`" in the Yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001307Project 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001312 "virtual/xserver" is "xserver-xorg", available in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001313 ``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
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001327 There are many ``MACHINE*`` variables that help you configure a particular piece
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001328 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",
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001340 are set in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001341 ``poky/meta/conf/machine/include``). In this example, the default
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001342 tuning file is ``cortexa8hf-neon``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001343
1344 .. note::
1345
1346 The include statement that pulls in the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001347 ``conf/machine/include/tune-cortexa8.inc`` file provides many tuning
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001348 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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001361 the :ref:`Wic kickstart <ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001362 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 ``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
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001372 to create the sysroot when building a Wic image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001373
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
Andrew Geissler09036742021-06-25 14:25:14 -05001408 to define :term:`SPL_BINARY` as ``MLO``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001409
1410 .. note::
1411
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001412 For more information on how the SPL variables are used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001413 :yocto_git:`u-boot.inc </poky/tree/meta/recipes-bsp/u-boot/u-boot.inc>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001414 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
Andrew Geisslerc926e172021-05-07 16:11:35 -05001448device was established in the machine configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001449
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
Andrew Geissler09209ee2020-12-13 08:44:15 -06001457:yocto_git:`/poky/tree/meta/recipes-kernel/linux`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001458
Andrew Geisslerc926e172021-05-07 16:11:35 -05001459Following is the contents of the append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001460
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.