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