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