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