Gitiles
Code Review Sign In
gerrit.openbmc.org / mdmillerii / openbmc / 981cc4f9a4dfeabc132adcaf6dab639251705a82 / . / import-layers / yocto-poky / documentation / bsp-guide / bsp.xml
blob: 4d0ace048436c61e9ecf8fe2a7444a6c8067c0ee [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='bsp'>
6
7 <title>Board Support Packages (BSP) - Developer's Guide</title>
8
9 <para>
10 A Board Support Package (BSP) is a collection of information that
11 defines how to support a particular hardware device, set of devices, or
12 hardware platform.
13 The BSP includes information about the hardware features
14 present on the device and kernel configuration information along with any
15 additional hardware drivers required.
16 The BSP also lists any additional software
17 components required in addition to a generic Linux software stack for both
18 essential and optional platform features.
19 </para>
20
21 <para>
22 This guide presents information about BSP Layers, defines a structure for components
23 so that BSPs follow a commonly understood layout, discusses how to customize
24 a recipe for a BSP, addresses BSP licensing, and provides information that
25 shows you how to create and manage a
26 <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project
27 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
28 </para>
29
30 <section id='bsp-layers'>
31 <title>BSP Layers</title>
32
33 <para>
34 A BSP consists of a file structure inside a base directory.
35 Collectively, you can think of the base directory, its file structure,
36 and the contents as a BSP Layer.
37 Although not a strict requirement, layers in the Yocto Project use the
38 following well-established naming convention:
39 <literallayout class='monospaced'>
40 meta-<replaceable>bsp_name</replaceable>
41 </literallayout>
42 The string "meta-" is prepended to the machine or platform name, which is
43 <replaceable>bsp_name</replaceable> in the above form.
44 <note><title>Tip</title>
45 Because the BSP layer naming convention is well-established,
46 it is advisable to follow it when creating layers.
47 Technically speaking, a BSP layer name does not need to
48 start with <filename>meta-</filename>.
49 However, you might run into situations where obscure
50 scripts assume this convention.
51 </note>
52 </para>
53
54 <para>
55 To help understand the BSP layer concept, consider the BSPs that the
56 Yocto Project supports and provides with each release.
57 You can see the layers in the
58 <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
59 through a web interface at
60 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
61 If you go to that interface, you will find near the bottom of the list
62 under "Yocto Metadata Layers" several BSP layers all of which are
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]63 supported by the Yocto Project (e.g. <filename>meta-raspberrypi</filename> and
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]64 <filename>meta-intel</filename>).
65 Each of these layers is a repository unto itself and clicking on a
66 layer reveals information that includes two links from which you can choose
67 to set up a clone of the layer's repository on your local host system.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]68 Here is an example that clones the Raspberry Pi BSP layer:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]69 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]70 $ git clone git://git.yoctoproject.org/meta-raspberrypi
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]71 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]72 </para>
73
74 <para>
75 In addition to BSP layers near the bottom of that referenced
76 Yocto Project Source Repository, the
77 <filename>meta-yocto-bsp</filename> layer is part of the
78 shipped <filename>poky</filename> repository.
79 The <filename>meta-yocto-bsp</filename> layer maintains several
80 BSPs such as the Beaglebone, EdgeRouter, and generic versions of
81 both 32 and 64-bit IA machines.
82 </para>
83
84 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]85 For information on the BSP development workflow, see the
86 "<ulink url='&YOCTO_DOCS_DEV_URL;#developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</ulink>"
87 section in the Yocto Project Development Manual.
88 For more information on how to set up a local copy of source files
89 from a Git repository, see the
90 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
91 section also in the Yocto Project Development Manual.
92 </para>
93
94 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]95 The layer's base directory
96 (<filename>meta-<replaceable>bsp_name</replaceable></filename>)
97 is the root of the BSP Layer.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]98 This root is what you add to the
99 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
100 variable in the <filename>conf/bblayers.conf</filename> file found in the
101 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
102 which is established after you run one of the OpenEmbedded build environment
103 setup scripts (i.e.
104 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
105 and
106 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
107 Adding the root allows the OpenEmbedded build system to recognize the BSP
108 definition and from it build an image.
109 Here is an example:
110 <literallayout class='monospaced'>
111 BBLAYERS ?= " \
112 /usr/local/src/yocto/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]113 /usr/local/src/yocto/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]114 /usr/local/src/yocto/meta-yocto-bsp \
115 /usr/local/src/yocto/meta-mylayer \
116 "
117 </literallayout>
118 </para>
119
120 <para>
121 Some BSPs require additional layers on
122 top of the BSP's root layer in order to be functional.
123 For these cases, you also need to add those layers to the
124 <filename>BBLAYERS</filename> variable in order to build the BSP.
125 You must also specify in the "Dependencies" section of the BSP's
126 <filename>README</filename> file any requirements for additional
127 layers and, preferably, any
128 build instructions that might be contained elsewhere
129 in the <filename>README</filename> file.
130 </para>
131
132 <para>
133 Some layers function as a layer to hold other BSP layers.
134 An example of this type of layer is the <filename>meta-intel</filename> layer,
135 which contains a number of individual BSP sub-layers, as well as a directory
136 named <filename>common/</filename> full of common content across those layers.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]137 Another example is the <filename>meta-yocto-bsp</filename> layer mentioned
138 earlier.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]139 </para>
140
141 <para>
142 For more detailed information on layers, see the
143 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
144 section of the Yocto Project Development Manual.
145 </para>
146 </section>
147
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]148 <section id="bsp-filelayout">
149 <title>Example Filesystem Layout</title>
150
151 <para>
152 Defining a common BSP directory structure allows end-users to understand and
153 become familiar with that structure.
154 A common format also encourages standardization of software support of hardware.
155 </para>
156
157 <para>
158 The proposed form does have elements that are specific to the
159 OpenEmbedded build system.
160 It is intended that this information can be
161 used by other build systems besides the OpenEmbedded build system
162 and that it will be simple
163 to extract information and convert it to other formats if required.
164 The OpenEmbedded build system, through its standard layers mechanism, can directly
165 accept the format described as a layer.
166 The BSP captures all
167 the hardware-specific details in one place in a standard format, which is
168 useful for any person wishing to use the hardware platform regardless of
169 the build system they are using.
170 </para>
171
172 <para>
173 The BSP specification does not include a build system or other tools -
174 it is concerned with the hardware-specific components only.
175 At the end-distribution point, you can ship the BSP combined with a build system
176 and other tools.
177 However, it is important to maintain the distinction that these
178 are separate components that happen to be combined in certain end products.
179 </para>
180
181 <para>
182 Before looking at the common form for the file structure inside a BSP Layer,
183 you should be aware that some requirements do exist in order for a BSP to
184 be considered compliant with the Yocto Project.
185 For that list of requirements, see the
186 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
187 section.
188 </para>
189
190 <para>
191 Below is the common form for the file structure inside a BSP Layer.
192 While you can use this basic form for the standard, realize that the actual structures
193 for specific BSPs could differ.
194
195 <literallayout class='monospaced'>
196 meta-<replaceable>bsp_name</replaceable>/
197 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
198 meta-<replaceable>bsp_name</replaceable>/README
199 meta-<replaceable>bsp_name</replaceable>/README.sources
200 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
201 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
202 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
203 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
204 meta-<replaceable>bsp_name</replaceable>/recipes-core/*
205 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
206 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
207 </literallayout>
208 </para>
209
210 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]211 Below is an example of the Raspberry Pi BSP:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]212
213 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]214 meta-raspberrypi/COPYING.MIT
215 meta-raspberrypi/README
216 meta-raspberrypi/classes
217 meta-raspberrypi/classes/linux-raspberrypi-base.bbclass
218 meta-raspberrypi/classes/sdcard_image-rpi.bbclass
219 meta-raspberrypi/conf/
220 meta-raspberrypi/conf/layer.conf
221 meta-raspberrypi/conf/machine/
222 meta-raspberrypi/conf/machine/raspberrypi.conf
223 meta-raspberrypi/conf/machine/raspberrypi0.conf
224 meta-raspberrypi/conf/machine/raspberrypi2.conf
225 meta-raspberrypi/conf/machine/raspberrypi3.conf
226 meta-raspberrypi/conf/machine/include
227 meta-raspberrypi/conf/machine/include/rpi-base.inc
228 meta-raspberrypi/conf/machine/include/rpi-default-providers.inc
229 meta-raspberrypi/conf/machine/include/rpi-default-settings.inc
230 meta-raspberrypi/conf/machine/include/rpi-default-versions.inc
231 meta-raspberrypi/conf/machine/include/rpi-tune-arm1176jzf-s.inc
232 meta-raspberrypi/files
233 meta-raspberrypi/files/custom-licenses
234 meta-raspberrypi/files/custom-licenses/Broadcom
235 meta-raspberrypi/recipes-bsp
236 meta-raspberrypi/recipes-bsp/bootfiles
237 meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb
238 meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb
239 meta-raspberrypi/recipes-bsp/common
240 meta-raspberrypi/recipes-bsp/common/firmware.inc
241 meta-raspberrypi/recipes-bsp/formfactor_00.bbappend
242 meta-raspberrypi/recipes-bsp/formfactor/raspberrypi/machconfig
243 meta-raspberrypi/recipes-bsp/rpi-mkimage_git.bb
244 meta-raspberrypi/recipes-bsp/rpi-mkimage/License
245 meta-raspberrypi/recipes-bsp/rpi-mkimage/open-files-relative-to-script.patch
246 meta-raspberrypi/recipes-bsp/u-boot/u-boot-rpi_git.bb
247 meta-raspberrypi/recipes-core
248 meta-raspberrypi/recipes-core/images
249 meta-raspberrypi/recipes-core/images/rpi-basic-image.bb
250 meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb
251 meta-raspberrypi/recipes-core/images/rpi-test-image.bb
252 meta-raspberrypi/recipes-core/packagegroups
253 meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb
254 meta-raspberrypi/recipes-core/psplash
255 meta-raspberrypi/recipes-core/psplash/files
256 meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
257 meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h
258 meta-raspberrypi/recipes-devtools
259 meta-raspberrypi/recipes-devtools/bcm2835
260 meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.46.bb
261 meta-raspberrypi/recipes-devtools/pi-blaster
262 meta-raspberrypi/recipes-devtools/pi-blaster/files
263 meta-raspberrypi/recipes-devtools/pi-blaster/*.patch
264 meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster.inc
265 meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb
266 meta-raspberrypi/recipes-devtools/python
267 meta-raspberrypi/recipes-devtools/python/python-rtimu
268 meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch
269 meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb
270 meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.1.0.bb
271 meta-raspberrypi/recipes-devtools/python/rpi-gpio
272 meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch
273 meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.1.bb
274 meta-raspberrypi/recipes-devtools/python/rpio
275 meta-raspberrypi/recipes-devtools/python/rpio/*.patch
276 meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb
277 meta-raspberrypi/recipes-devtools/wiringPi
278 meta-raspberrypi/recipes-devtools/wiringPi/files
279 meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch
280 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi
281 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi/*.patch
282 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb
283 meta-raspberrypi/recipes-graphics
284 meta-raspberrypi/recipes-graphics/eglinfo
285 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend
286 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend
287 meta-raspberrypi/recipes-graphics/userland
288 meta-raspberrypi/recipes-graphics/userland/userland
289 meta-raspberrypi/recipes-graphics/userland/userland/*.patch
290 meta-raspberrypi/recipes-graphics/userland/userland_git.bb
291 meta-raspberrypi/recipes-graphics/vc-graphics
292 meta-raspberrypi/recipes-graphics/vc-graphics/files
293 meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc
294 meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh
295 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb
296 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb
297 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc
298 meta-raspberrypi/recipes-graphics/wayland
299 meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend
300 meta-raspberrypi/recipes-graphics/weston
301 meta-raspberrypi/recipes-graphics/weston/weston_%.bbappend
302 meta-raspberrypi/recipes-graphics/xorg-xserver
303 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config
304 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi
305 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf
306 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d
307 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf
308 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-pitft.conf
309 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
310 meta-raspberrypi/recipes-kernel
311 meta-raspberrypi/recipes-kernel/linux-firmware
312 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware
313 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/LICENSE.broadcom_brcm80211
314 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.bin
315 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.txt
316 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_git.bbappend
317 meta-raspberrypi/recipes-kernel/linux
318 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14
319 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14/*.patch
320 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18
321 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18/*.patch
322 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1
323 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1/*.patch
324 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc
325 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi
326 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi/defconfig
327 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.14.bb
328 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.18.bb
329 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.1.bb
330 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.4.bb
331 meta-raspberrypi/recipes-kernel/linux/linux.inc
332 meta-raspberrypi/recipes-multimedia
333 meta-raspberrypi/recipes-multimedia/gstreamer
334 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx
335 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch
336 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend
337 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend
338 meta-raspberrypi/recipes-multimedia/omxplayer
339 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer
340 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch
341 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb
342 meta-raspberrypi/scripts
343 meta-raspberrypi/scripts/lib
344 meta-raspberrypi/scripts/lib/image
345 meta-raspberrypi/scripts/lib/image/canned-wks
346 meta-raspberrypi/scripts/lib/image/canned-wks/sdimage-raspberrypi.wks
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]347 </literallayout>
348 </para>
349
350 <para>
351 The following sections describe each part of the proposed BSP format.
352 </para>
353
354 <section id="bsp-filelayout-license">
355 <title>License Files</title>
356
357 <para>
358 You can find these files in the BSP Layer at:
359 <literallayout class='monospaced'>
360 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
361 </literallayout>
362 </para>
363
364 <para>
365 These optional files satisfy licensing requirements for the BSP.
366 The type or types of files here can vary depending on the licensing requirements.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]367 For example, in the Raspberry Pi BSP all licensing requirements are handled with the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]368 <filename>COPYING.MIT</filename> file.
369 </para>
370
371 <para>
372 Licensing files can be MIT, BSD, GPLv*, and so forth.
373 These files are recommended for the BSP but are optional and totally up to the BSP developer.
374 </para>
375 </section>
376
377 <section id="bsp-filelayout-readme">
378 <title>README File</title>
379 <para>
380 You can find this file in the BSP Layer at:
381 <literallayout class='monospaced'>
382 meta-<replaceable>bsp_name</replaceable>/README
383 </literallayout>
384 </para>
385
386 <para>
387 This file provides information on how to boot the live images that are optionally
388 included in the <filename>binary/</filename> directory.
389 The <filename>README</filename> file also provides special information needed for
390 building the image.
391 </para>
392
393 <para>
394 At a minimum, the <filename>README</filename> file must
395 contain a list of dependencies, such as the names of
396 any other layers on which the BSP depends and the name of
397 the BSP maintainer with his or her contact information.
398 </para>
399 </section>
400
401 <section id="bsp-filelayout-readme-sources">
402 <title>README.sources File</title>
403 <para>
404 You can find this file in the BSP Layer at:
405 <literallayout class='monospaced'>
406 meta-<replaceable>bsp_name</replaceable>/README.sources
407 </literallayout>
408 </para>
409
410 <para>
411 This file provides information on where to locate the BSP
412 source files used to build the images (if any) that reside in
413 <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
414 Images in the <filename>binary</filename> would be images
415 released with the BSP.
416 The information in the <filename>README.sources</filename>
417 file also helps you find the
418 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
419 used to generate the images that ship with the BSP.
420 <note>
421 If the BSP's <filename>binary</filename> directory is
422 missing or the directory has no images, an existing
423 <filename>README.sources</filename> file is
424 meaningless.
425 </note>
426 </para>
427 </section>
428
429 <section id="bsp-filelayout-binary">
430 <title>Pre-built User Binaries</title>
431 <para>
432 You can find these files in the BSP Layer at:
433 <literallayout class='monospaced'>
434 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
435 </literallayout>
436 </para>
437
438 <para>
439 This optional area contains useful pre-built kernels and
440 user-space filesystem images released with the BSP that are
441 appropriate to the target system.
442 This directory typically contains graphical (e.g. Sato) and
443 minimal live images when the BSP tarball has been created and
444 made available in the
445 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
446 You can use these kernels and images to get a system running
447 and quickly get started on development tasks.
448 </para>
449
450 <para>
451 The exact types of binaries present are highly
452 hardware-dependent.
453 The <filename>README</filename> file should be present in the
454 BSP Layer and it will explain how to use the images with the
455 target hardware.
456 Additionally, the <filename>README.sources</filename> file
457 should be present to locate the sources used to build the
458 images and provide information on the Metadata.
459 </para>
460 </section>
461
462 <section id='bsp-filelayout-layer'>
463 <title>Layer Configuration File</title>
464 <para>
465 You can find this file in the BSP Layer at:
466 <literallayout class='monospaced'>
467 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
468 </literallayout>
469 </para>
470
471 <para>
472 The <filename>conf/layer.conf</filename> file identifies the file structure as a
473 layer, identifies the
474 contents of the layer, and contains information about how the build
475 system should use it.
476 Generally, a standard boilerplate file such as the following works.
477 In the following example, you would replace "<replaceable>bsp</replaceable>" and
478 "<replaceable>_bsp</replaceable>" with the actual name
479 of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template).
480 </para>
481
482 <para>
483 <literallayout class='monospaced'>
484 # We have a conf and classes directory, add to BBPATH
485 BBPATH .= ":${LAYERDIR}"
486
487 # We have a recipes directory, add to BBFILES
488 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]489 ${LAYERDIR}/recipes-*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]490
491 BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>"
492 BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/"
493 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
494
495 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
496 </literallayout>
497 </para>
498
499 <para>
500 To illustrate the string substitutions, here are the corresponding statements
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]501 from the Raspberry Pi <filename>conf/layer.conf</filename> file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]502 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]503 # We have a conf and classes directory, append to BBPATH
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]504 BBPATH .= ":${LAYERDIR}"
505
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]506 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
507 BBFILES += "${LAYERDIR}/recipes*/*/*.bb \
508 ${LAYERDIR}/recipes*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]509
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]510 BBFILE_COLLECTIONS += "raspberrypi"
511 BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/"
512 BBFILE_PRIORITY_raspberrypi = "9"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]513
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]514 # Additional license directories.
515 LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]516 </literallayout>
517 </para>
518
519 <para>
520 This file simply makes
521 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
522 aware of the recipes and configuration directories.
523 The file must exist so that the OpenEmbedded build system can recognize the BSP.
524 </para>
525 </section>
526
527 <section id="bsp-filelayout-machine">
528 <title>Hardware Configuration Options</title>
529 <para>
530 You can find these files in the BSP Layer at:
531 <literallayout class='monospaced'>
532 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
533 </literallayout>
534 </para>
535
536 <para>
537 The machine files bind together all the information contained elsewhere
538 in the BSP into a format that the build system can understand.
539 If the BSP supports multiple machines, multiple machine configuration files
540 can be present.
541 These filenames correspond to the values to which users have set the
542 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
543 </para>
544
545 <para>
546 These files define things such as the kernel package to use
547 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
548 of virtual/kernel), the hardware drivers to
549 include in different types of images, any special software components
550 that are needed, any bootloader information, and also any special image
551 format requirements.
552 </para>
553
554 <para>
555 Each BSP Layer requires at least one machine file.
556 However, you can supply more than one file.
557 </para>
558
559 <para>
560 This configuration file could also include a hardware "tuning"
561 file that is commonly used to define the package architecture
562 and specify optimization flags, which are carefully chosen
563 to give best performance on a given processor.
564 </para>
565
566 <para>
567 Tuning files are found in the <filename>meta/conf/machine/include</filename>
568 directory within the
569 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
570 For example, the <filename>ia32-base.inc</filename> file resides in the
571 <filename>meta/conf/machine/include</filename> directory.
572 </para>
573
574 <para>
575 To use an include file, you simply include them in the
576 machine configuration file.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]577 For example, the Raspberry Pi BSP
578 <filename>raspberrypi3.conf</filename> contains the
579 following statement:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]580 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]581 include conf/machine/raspberrypi2.conf
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]582 </literallayout>
583 </para>
584 </section>
585
586 <section id='bsp-filelayout-misc-recipes'>
587 <title>Miscellaneous BSP-Specific Recipe Files</title>
588 <para>
589 You can find these files in the BSP Layer at:
590 <literallayout class='monospaced'>
591 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
592 </literallayout>
593 </para>
594
595 <para>
596 This optional directory contains miscellaneous recipe files for
597 the BSP.
598 Most notably would be the formfactor files.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]599 For example, in the Raspberry Pi BSP there is the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]600 <filename>formfactor_0.0.bbappend</filename> file, which is an
601 append file used to augment the recipe that starts the build.
602 Furthermore, there are machine-specific settings used during
603 the build that are defined by the
604 <filename>machconfig</filename> file further down in the
605 directory.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]606 Here is the <filename>machconfig</filename>
607 file for the Raspberry Pi BSP:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]608 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]609 HAVE_TOUCHSCREEN=0
610 HAVE_KEYBOARD=1
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]611
612 DISPLAY_CAN_ROTATE=0
613 DISPLAY_ORIENTATION=0
614 DISPLAY_DPI=133
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]615 </literallayout>
616 </para>
617
618 <note><para>
619 If a BSP does not have a formfactor entry, defaults are established according to
620 the formfactor configuration file that is installed by the main
621 formfactor recipe
622 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
623 which is found in the
624 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
625 </para></note>
626 </section>
627
628 <section id='bsp-filelayout-recipes-graphics'>
629 <title>Display Support Files</title>
630 <para>
631 You can find these files in the BSP Layer at:
632 <literallayout class='monospaced'>
633 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
634 </literallayout>
635 </para>
636
637 <para>
638 This optional directory contains recipes for the BSP if it has
639 special requirements for graphics support.
640 All files that are needed for the BSP to support a display are
641 kept here.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]642 </para>
643 </section>
644
645 <section id='bsp-filelayout-kernel'>
646 <title>Linux Kernel Configuration</title>
647 <para>
648 You can find these files in the BSP Layer at:
649 <literallayout class='monospaced'>
650 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
651 </literallayout>
652 </para>
653
654 <para>
655 These files append your specific changes to the main kernel recipe you are using.
656 </para>
657 <para>
658 For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the
659 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
660 at <filename>meta/recipes-kernel/linux</filename>.
661 You can append your specific changes to the kernel recipe by using a
662 similarly named append file, which is located in the BSP Layer (e.g.
663 the <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
664 </para>
665 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]666 Suppose you are using the <filename>linux-yocto_4.4.bb</filename> recipe to build
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]667 the kernel.
668 In other words, you have selected the kernel in your
669 <replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types
670 of statements:
671 <literallayout class='monospaced'>
672 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]673 PREFERRED_VERSION_linux-yocto ?= "4.4%"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]674 </literallayout>
675 <note>
676 When the preferred provider is assumed by default, the
677 <filename>PREFERRED_PROVIDER</filename> statement does not appear in the
678 <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
679 </note>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]680 You would use the <filename>linux-yocto_4.4.bbappend</filename>
681 file to append specific BSP settings to the kernel, thus
682 configuring the kernel for your particular BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]683 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]684
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]685 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]686 As an example, consider the following append file
687 used by the BSPs in <filename>meta-yocto-bsp</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]688 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]689 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]690 </literallayout>
691 The following listing shows the file.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]692 Be aware that the actual commit ID strings in this
693 example listing might be different than the actual strings
694 in the file from the <filename>meta-yocto-bsp</filename>
695 layer upstream.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]696 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]697 KBRANCH_genericx86 = "standard/base"
698 KBRANCH_genericx86-64 = "standard/base"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]699
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]700 KMACHINE_genericx86 ?= "common-pc"
701 KMACHINE_genericx86-64 ?= "common-pc-64"
702 KBRANCH_edgerouter = "standard/edgerouter"
703 KBRANCH_beaglebone = "standard/beaglebone"
704 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]705
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]706 SRCREV_machine_genericx86 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
707 SRCREV_machine_genericx86-64 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
708 SRCREV_machine_edgerouter ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
709 SRCREV_machine_beaglebone ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
710 SRCREV_machine_mpc8315e-rdb ?= "df00877ef9387b38b9601c82db57de2a1b23ce53"
711
712 COMPATIBLE_MACHINE_genericx86 = "genericx86"
713 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
714 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
715 COMPATIBLE_MACHINE_beaglebone = "beaglebone"
716 COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
717
718 LINUX_VERSION_genericx86 = "4.4.3"
719 LINUX_VERSION_genericx86-64 = "4.4.3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]720 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]721 This append file contains statements used to support
722 several BSPs that ship with the Yocto Project.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]723 The file defines machines using the
724 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
725 variable and uses the
726 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
727 variable to ensure the machine name used by the OpenEmbedded
728 build system maps to the machine name used by the Linux Yocto
729 kernel.
730 The file also uses the optional
731 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
732 variable to ensure the build process uses the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]733 appropriate kernel branch.
734 </para>
735
736 <para>
737 Although this particular example does not use it, the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]738 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]739 variable could be used to enable features specific to
740 the kernel.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]741 The append file points to specific commits in the
742 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
743 Git repository and the <filename>meta</filename> Git repository
744 branches to identify the exact kernel needed to build the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]745 BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]746 </para>
747
748 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]749 One thing missing in this particular BSP, which you will
750 typically need when developing a BSP, is the kernel configuration
751 file (<filename>.config</filename>) for your BSP.
752 When developing a BSP, you probably have a kernel configuration
753 file or a set of kernel configuration files that, when taken
754 together, define the kernel configuration for your BSP.
755 You can accomplish this definition by putting the configurations
756 in a file or a set of files inside a directory located at the
757 same level as your kernel's append file and having the same
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]758 name as the kernel's main recipe file.
759 With all these conditions met, simply reference those files in the
760 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
761 statement in the append file.
762 </para>
763
764 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]765 For example, suppose you had some configuration options
766 in a file called <filename>network_configs.cfg</filename>.
767 You can place that file inside a directory named
768 <filename>linux-yocto</filename> and then add
769 a <filename>SRC_URI</filename> statement such as the
770 following to the append file.
771 When the OpenEmbedded build system builds the kernel, the
772 configuration options are picked up and applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]773 <literallayout class='monospaced'>
774 SRC_URI += "file://network_configs.cfg"
775 </literallayout>
776 </para>
777
778 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]779 To group related configurations into multiple files, you
780 perform a similar procedure.
781 Here is an example that groups separate configurations
782 specifically for Ethernet and graphics into their own
783 files and adds the configurations by using a
784 <filename>SRC_URI</filename> statement like the following
785 in your append file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]786 <literallayout class='monospaced'>
787 SRC_URI += "file://myconfig.cfg \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]788 file://eth.cfg \
789 file://gfx.cfg"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]790 </literallayout>
791 </para>
792
793 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]794 Another variable you can use in your kernel recipe append
795 file is the
796 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
797 variable.
798 When you use this statement, you are extending the locations
799 used by the OpenEmbedded system to look for files and
800 patches as the recipe is processed.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]801 </para>
802
803 <note>
804 <para>
805 Other methods exist to accomplish grouping and defining configuration options.
806 For example, if you are working with a local clone of the kernel repository,
807 you could checkout the kernel's <filename>meta</filename> branch, make your changes,
808 and then push the changes to the local bare clone of the kernel.
809 The result is that you directly add configuration options to the
810 <filename>meta</filename> branch for your BSP.
811 The configuration options will likely end up in that location anyway if the BSP gets
812 added to the Yocto Project.
813 </para>
814
815 <para>
816 In general, however, the Yocto Project maintainers take care of moving the
817 <filename>SRC_URI</filename>-specified
818 configuration options to the kernel's <filename>meta</filename> branch.
819 Not only is it easier for BSP developers to not have to worry about putting those
820 configurations in the branch, but having the maintainers do it allows them to apply
821 'global' knowledge about the kinds of common configuration options multiple BSPs in
822 the tree are typically using.
823 This allows for promotion of common configurations into common features.
824 </para>
825 </note>
826 </section>
827 </section>
828
829 <section id='requirements-and-recommendations-for-released-bsps'>
830 <title>Requirements and Recommendations for Released BSPs</title>
831
832 <para>
833 Certain requirements exist for a released BSP to be considered
834 compliant with the Yocto Project.
835 Additionally, recommendations also exist.
836 This section describes the requirements and recommendations for
837 released BSPs.
838 </para>
839
840 <section id='released-bsp-requirements'>
841 <title>Released BSP Requirements</title>
842
843 <para>
844 Before looking at BSP requirements, you should consider the following:
845 <itemizedlist>
846 <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal"
847 layer that can be added to the Yocto Project.
848 For guidelines on creating a layer that meets these base requirements, see the
849 "<link linkend='bsp-layers'>BSP Layers</link>" and the
850 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding
851 and Creating Layers"</ulink> in the Yocto Project Development Manual.</para></listitem>
852 <listitem><para>The requirements in this section apply regardless of how you
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]853 package a BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]854 You should consult the packaging and distribution guidelines for your
855 specific release process.
856 For an example of packaging and distribution requirements, see the
857 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
858 wiki page.</para></listitem>
859 <listitem><para>The requirements for the BSP as it is made available to a developer
860 are completely independent of the released form of the BSP.
861 For example, the BSP Metadata can be contained within a Git repository
862 and could have a directory structure completely different from what appears
863 in the officially released BSP layer.</para></listitem>
864 <listitem><para>It is not required that specific packages or package
865 modifications exist in the BSP layer, beyond the requirements for general
866 compliance with the Yocto Project.
867 For example, no requirement exists dictating that a specific kernel or
868 kernel version be used in a given BSP.</para></listitem>
869 </itemizedlist>
870 </para>
871
872 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]873 Following are the requirements for a released BSP that conform to the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]874 Yocto Project:
875 <itemizedlist>
876 <listitem><para><emphasis>Layer Name:</emphasis>
877 The BSP must have a layer name that follows the Yocto
878 Project standards.
879 For information on BSP layer names, see the
880 "<link linkend='bsp-layers'>BSP Layers</link>" section.
881 </para></listitem>
882 <listitem><para><emphasis>File System Layout:</emphasis>
883 When possible, use the same directory names in your
884 BSP layer as listed in the <filename>recipes.txt</filename> file.
885 In particular, you should place recipes
886 (<filename>.bb</filename> files) and recipe
887 modifications (<filename>.bbappend</filename> files) into
888 <filename>recipes-*</filename> subdirectories by functional area
889 as outlined in <filename>recipes.txt</filename>.
890 If you cannot find a category in <filename>recipes.txt</filename>
891 to fit a particular recipe, you can make up your own
892 <filename>recipes-*</filename> subdirectory.
893 You can find <filename>recipes.txt</filename> in the
894 <filename>meta</filename> directory of the
895 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
896 or in the OpenEmbedded Core Layer
897 (<filename>openembedded-core</filename>) found at
898 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
899 </para>
900 <para>Within any particular <filename>recipes-*</filename> category, the layout
901 should match what is found in the OpenEmbedded Core
902 Git repository (<filename>openembedded-core</filename>)
903 or the Source Directory (<filename>poky</filename>).
904 In other words, make sure you place related files in appropriately
905 related <filename>recipes-*</filename> subdirectories specific to the
906 recipe's function, or within a subdirectory containing a set of closely-related
907 recipes.
908 The recipes themselves should follow the general guidelines
909 for recipes used in the Yocto Project found in the
910 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
911 </para></listitem>
912 <listitem><para><emphasis>License File:</emphasis>
913 You must include a license file in the
914 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
915 This license covers the BSP Metadata as a whole.
916 You must specify which license to use since there is no
917 default license if one is not specified.
918 See the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]919 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
920 file for the Raspberry Pi BSP in the
921 <filename>meta-raspberrypi</filename> BSP layer as an example.
922 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]923 <listitem><para><emphasis>README File:</emphasis>
924 You must include a <filename>README</filename> file in the
925 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
926 See the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]927 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
928 file for the Raspberry Pi BSP in the <filename>meta-raspberrypi</filename> BSP layer
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]929 as an example.</para>
930 <para>At a minimum, the <filename>README</filename> file should
931 contain the following:
932 <itemizedlist>
933 <listitem><para>A brief description about the hardware the BSP
934 targets.</para></listitem>
935 <listitem><para>A list of all the dependencies
936 on which a BSP layer depends.
937 These dependencies are typically a list of required layers needed
938 to build the BSP.
939 However, the dependencies should also contain information regarding
940 any other dependencies the BSP might have.</para></listitem>
941 <listitem><para>Any required special licensing information.
942 For example, this information includes information on
943 special variables needed to satisfy a EULA,
944 or instructions on information needed to build or distribute
945 binaries built from the BSP Metadata.</para></listitem>
946 <listitem><para>The name and contact information for the
947 BSP layer maintainer.
948 This is the person to whom patches and questions should
949 be sent.
950 For information on how to find the right person, see the
951 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
952 section in the Yocto Project Development Manual.
953 </para></listitem>
954 <listitem><para>Instructions on how to build the BSP using the BSP
955 layer.</para></listitem>
956 <listitem><para>Instructions on how to boot the BSP build from
957 the BSP layer.</para></listitem>
958 <listitem><para>Instructions on how to boot the binary images
959 contained in the <filename>binary</filename> directory,
960 if present.</para></listitem>
961 <listitem><para>Information on any known bugs or issues that users
962 should know about when either building or booting the BSP
963 binaries.</para></listitem>
964 </itemizedlist></para></listitem>
965 <listitem><para><emphasis>README.sources File:</emphasis>
966 You must include a <filename>README.sources</filename> in the
967 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
968 This file specifies exactly where you can find the sources used to
969 generate the binary images contained in the
970 <filename>binary</filename> directory, if present.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]971 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]972 <listitem><para><emphasis>Layer Configuration File:</emphasis>
973 You must include a <filename>conf/layer.conf</filename> in the
974 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
975 This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename>
976 BSP layer as a layer to the build system.</para></listitem>
977 <listitem><para><emphasis>Machine Configuration File:</emphasis>
978 You must include one or more
979 <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename>
980 files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
981 These configuration files define machine targets that can be built
982 using the BSP layer.
983 Multiple machine configuration files define variations of machine
984 configurations that are supported by the BSP.
985 If a BSP supports multiple machine variations, you need to
986 adequately describe each variation in the BSP
987 <filename>README</filename> file.
988 Do not use multiple machine configuration files to describe disparate
989 hardware.
990 If you do have very different targets, you should create separate
991 BSP layers for each target.
992 <note>It is completely possible for a developer to structure the
993 working repository as a conglomeration of unrelated BSP
994 files, and to possibly generate BSPs targeted for release
995 from that directory using scripts or some other mechanism
996 (e.g. <filename>meta-yocto-bsp</filename> layer).
997 Such considerations are outside the scope of this document.</note>
998 </para></listitem>
999 </itemizedlist>
1000 </para>
1001 </section>
1002
1003 <section id='released-bsp-recommendations'>
1004 <title>Released BSP Recommendations</title>
1005
1006 <para>
1007 Following are recommendations for a released BSP that conforms to the
1008 Yocto Project:
1009 <itemizedlist>
1010 <listitem><para><emphasis>Bootable Images:</emphasis>
1011 BSP releases
1012 can contain one or more bootable images.
1013 Including bootable images allows users to easily try out the BSP
1014 on their own hardware.</para>
1015 <para>In some cases, it might not be convenient to include a
1016 bootable image.
1017 In this case, you might want to make two versions of the
1018 BSP available: one that contains binary images, and one
1019 that does not.
1020 The version that does not contain bootable images avoids
1021 unnecessary download times for users not interested in the images.
1022 </para>
1023 <para>If you need to distribute a BSP and include bootable images or build kernel and
1024 filesystems meant to allow users to boot the BSP for evaluation
1025 purposes, you should put the images and artifacts within a
1026 <filename>binary/</filename> subdirectory located in the
1027 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
1028 <note>If you do include a bootable image as part of the BSP and the image
1029 was built by software covered by the GPL or other open source licenses,
1030 it is your responsibility to understand
1031 and meet all licensing requirements, which could include distribution
1032 of source files.</note></para></listitem>
1033 <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
1034 Kernel recipes in the BSP should be based on a Yocto Linux kernel.
1035 Basing your recipes on these kernels reduces the costs for maintaining
1036 the BSP and increases its scalability.
1037 See the <filename>Yocto Linux Kernel</filename> category in the
1038 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
1039 for these kernels.</para></listitem>
1040 </itemizedlist>
1041 </para>
1042 </section>
1043 </section>
1044
1045 <section id='customizing-a-recipe-for-a-bsp'>
1046 <title>Customizing a Recipe for a BSP</title>
1047
1048 <para>
1049 If you plan on customizing a recipe for a particular BSP, you need to do the
1050 following:
1051 <itemizedlist>
1052 <listitem><para>Create a <filename>.bbappend</filename>
1053 file for the modified recipe.
1054 For information on using append files, see the
1055 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
1056 section in the Yocto Project Development Manual.
1057 </para></listitem>
1058 <listitem><para>
1059 Ensure your directory structure in the BSP layer
1060 that supports your machine is such that it can be found
1061 by the build system.
1062 See the example later in this section for more information.
1063 </para></listitem>
1064 <listitem><para>
1065 Put the append file in a directory whose name matches
1066 the machine's name and is located in an appropriate
1067 sub-directory inside the BSP layer (i.e.
1068 <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>,
1069 <filename>recipes-core</filename>, and so forth).
1070 </para></listitem>
1071 <listitem><para>Place the BSP-specific files in the proper directory
1072 inside the BSP layer.
1073 How expansive the layer is affects where you must place these files.
1074 For example, if your layer supports several different machine types,
1075 you need to be sure your layer's directory structure includes hierarchy
1076 that separates the files out according to machine.
1077 If your layer does not support multiple machines, the layer would not
1078 have that additional hierarchy and the files would obviously not be
1079 able to reside in a machine-specific directory.
1080 </para></listitem>
1081 </itemizedlist>
1082 </para>
1083
1084 <para>
1085 Following is a specific example to help you better understand the process.
1086 Consider an example that customizes a recipe by adding
1087 a BSP-specific configuration file named <filename>interfaces</filename> to the
1088 <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the
1089 BSP layer also supports several other machines.
1090 Do the following:
1091 <orderedlist>
1092 <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it
1093 contains the following:
1094 <literallayout class='monospaced'>
1095 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1096 </literallayout>
1097 The append file needs to be in the
1098 <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory.
1099 </para></listitem>
1100 <listitem><para>Create and place the new <filename>interfaces</filename>
1101 configuration file in the BSP's layer here:
1102 <literallayout class='monospaced'>
1103 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
1104 </literallayout>
1105 <note>
1106 If the <filename>meta-xyz</filename> layer did not support
1107 multiple machines, you would place the
1108 <filename>interfaces</filename> configuration file in the
1109 layer here:
1110 <literallayout class='monospaced'>
1111 meta-xyz/recipes-core/init-ifupdown/files/interfaces
1112 </literallayout>
1113 </note>
1114 The
1115 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1116 variable in the append files extends the search path
1117 the build system uses to find files during the build.
1118 Consequently, for this example you need to have the
1119 <filename>files</filename> directory in the same location
1120 as your append file.</para></listitem>
1121 </orderedlist>
1122 </para>
1123 </section>
1124
1125 <section id='bsp-licensing-considerations'>
1126 <title>BSP Licensing Considerations</title>
1127
1128 <para>
1129 In some cases, a BSP contains separately licensed Intellectual Property (IP)
1130 for a component or components.
1131 For these cases, you are required to accept the terms of a commercial or other
1132 type of license that requires some kind of explicit End User License Agreement (EULA).
1133 Once the license is accepted, the OpenEmbedded build system can then build and
1134 include the corresponding component in the final BSP image.
1135 If the BSP is available as a pre-built image, you can download the image after
1136 agreeing to the license or EULA.
1137 </para>
1138
1139 <para>
1140 You could find that some separately licensed components that are essential
1141 for normal operation of the system might not have an unencumbered (or free)
1142 substitute.
1143 Without these essential components, the system would be non-functional.
1144 Then again, you might find that other licensed components that are simply
1145 'good-to-have' or purely elective do have an unencumbered, free replacement
1146 component that you can use rather than agreeing to the separately licensed component.
1147 Even for components essential to the system, you might find an unencumbered component
1148 that is not identical but will work as a less-capable version of the
1149 licensed version in the BSP recipe.
1150 </para>
1151
1152 <para>
1153 For cases where you can substitute a free component and still
1154 maintain the system's functionality, the "Downloads" page from the
1155 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink>
1156 makes available de-featured BSPs
1157 that are completely free of any IP encumbrances.
1158 For these cases, you can use the substitution directly and
1159 without any further licensing requirements.
1160 If present, these fully de-featured BSPs are named appropriately
1161 different as compared to the names of the respective
1162 encumbered BSPs.
1163 If available, these substitutions are your
1164 simplest and most preferred options.
1165 Use of these substitutions of course assumes the resulting functionality meets
1166 system requirements.
1167 </para>
1168
1169 <para>
1170 If however, a non-encumbered version is unavailable or
1171 it provides unsuitable functionality or quality, you can use an encumbered
1172 version.
1173 </para>
1174
1175 <para>
1176 A couple different methods exist within the OpenEmbedded build system to
1177 satisfy the licensing requirements for an encumbered BSP.
1178 The following list describes them in order of preference:
1179 <orderedlist>
1180 <listitem><para><emphasis>Use the
1181 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1182 variable to define the recipes that have commercial or other
1183 types of specially-licensed packages:</emphasis>
1184 For each of those recipes, you can
1185 specify a matching license string in a
1186 <filename>local.conf</filename> variable named
1187 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
1188 Specifying the matching license string signifies that you agree to the license.
1189 Thus, the build system can build the corresponding recipe and include
1190 the component in the image.
1191 See the
1192 "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
1193 Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
1194 Manual for details on how to use these variables.</para>
1195 <para>If you build as you normally would, without
1196 specifying any recipes in the
1197 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
1198 provides you with the list of recipes that you have
1199 tried to include in the image that need entries in
1200 the <filename>LICENSE_FLAGS_WHITELIST</filename>.
1201 Once you enter the appropriate license flags into the whitelist,
1202 restart the build to continue where it left off.
1203 During the build, the prompt will not appear again
1204 since you have satisfied the requirement.</para>
1205 <para>Once the appropriate license flags are on the white list
1206 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
1207 can build the encumbered image with no change at all
1208 to the normal build process.</para></listitem>
1209 <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis>
1210 You can get this type of BSP by visiting the
1211 "Downloads" page of the
1212 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1213 You can download BSP tarballs that contain proprietary components
1214 after agreeing to the licensing
1215 requirements of each of the individually encumbered
1216 packages as part of the download process.
1217 Obtaining the BSP this way allows you to access an encumbered
1218 image immediately after agreeing to the
1219 click-through license agreements presented by the
1220 website.
1221 Note that if you want to build the image
1222 yourself using the recipes contained within the BSP
1223 tarball, you will still need to create an
1224 appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the
1225 encumbered recipes in the BSP.</para></listitem>
1226 </orderedlist>
1227 </para>
1228
1229 <note>
1230 Pre-compiled images are bundled with
1231 a time-limited kernel that runs for a
1232 predetermined amount of time (10 days) before it forces
1233 the system to reboot.
1234 This limitation is meant to discourage direct redistribution
1235 of the image.
1236 You must eventually rebuild the image if you want to remove this restriction.
1237 </note>
1238 </section>
1239
1240 <section id='using-the-yocto-projects-bsp-tools'>
1241 <title>Using the Yocto Project's BSP Tools</title>
1242
1243 <para>
1244 The Yocto Project includes a couple of tools that enable
1245 you to create a <link linkend='bsp-layers'>BSP layer</link>
1246 from scratch and do basic configuration and maintenance
1247 of the kernel without ever looking at a Metadata file.
1248 These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
1249 respectively.
1250 </para>
1251
1252 <para>
1253 The following sections describe the common location and help features as well
1254 as provide details for the
1255 <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools.
1256 </para>
1257
1258 <section id='common-features'>
1259 <title>Common Features</title>
1260
1261 <para>
1262 Designed to have a command interface somewhat like
1263 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>, each
1264 tool is structured as a set of sub-commands under a
1265 top-level command.
1266 The top-level command (<filename>yocto-bsp</filename>
1267 or <filename>yocto-kernel</filename>) itself does
1268 nothing but invoke or provide help on the sub-commands
1269 it supports.
1270 </para>
1271
1272 <para>
1273 Both tools reside in the <filename>scripts/</filename> subdirectory
1274 of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1275 Consequently, to use the scripts, you must <filename>source</filename> the
1276 environment just as you would when invoking a build:
1277 <literallayout class='monospaced'>
1278 $ source oe-init-build-env <replaceable>build_dir</replaceable>
1279 </literallayout>
1280 </para>
1281
1282 <para>
1283 The most immediately useful function is to get help on both tools.
1284 The built-in help system makes it easy to drill down at
1285 any time and view the syntax required for any specific command.
1286 Simply enter the name of the command with the <filename>help</filename>
1287 switch:
1288 <literallayout class='monospaced'>
1289 $ yocto-bsp help
1290 Usage:
1291
1292 Create a customized Yocto BSP layer.
1293
1294 usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
1295
1296 Current 'yocto-bsp' commands are:
1297 create Create a new Yocto BSP
1298 list List available values for options and BSP properties
1299
1300 See 'yocto-bsp help COMMAND' for more information on a specific command.
1301
1302
1303 Options:
1304 --version show program's version number and exit
1305 -h, --help show this help message and exit
1306 -D, --debug output debug information
1307 </literallayout>
1308 </para>
1309
1310 <para>
1311 Similarly, entering just the name of a sub-command shows the detailed usage
1312 for that sub-command:
1313 <literallayout class='monospaced'>
1314 $ yocto-bsp create
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1315 ERROR:root:Wrong number of arguments, exiting
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1316
1317 Usage:
1318
1319 Create a new Yocto BSP
1320
1321 usage: yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1322 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1323
1324 This command creates a Yocto BSP based on the specified parameters.
1325 The new BSP will be a new Yocto BSP layer contained by default within
1326 the top-level directory specified as 'meta-bsp-name'. The -o option
1327 can be used to place the BSP layer in a directory with a different
1328 name and location.
1329
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1330 The value of the 'karch' parameter determines the set of files that
1331 will be generated for the BSP, along with the specific set of
1332 'properties' that will be used to fill out the BSP-specific portions
1333 of the BSP. The possible values for the 'karch' parameter can be
1334 listed via 'yocto-bsp list karch'.
1335
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1336 ...
1337 </literallayout>
1338 </para>
1339
1340 <para>
1341 For any sub-command, you can use the word "help" option just before the
1342 sub-command to get more extensive documentation:
1343 <literallayout class='monospaced'>
1344 $ yocto-bsp help create
1345
1346 NAME
1347 yocto-bsp create - Create a new Yocto BSP
1348
1349 SYNOPSIS
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1350 yocto-bsp create &lt;bsp-name> &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1351 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
1352
1353 DESCRIPTION
1354 This command creates a Yocto BSP based on the specified
1355 parameters. The new BSP will be a new Yocto BSP layer contained
1356 by default within the top-level directory specified as
1357 'meta-bsp-name'. The -o option can be used to place the BSP layer
1358 in a directory with a different name and location.
1359
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1360 ...
1361 </literallayout>
1362 </para>
1363
1364 <para>
1365 Now that you know where these two commands reside and how to access information
1366 on them, you should find it relatively straightforward to discover the commands
1367 necessary to create a BSP and perform basic kernel maintenance on that BSP using
1368 the tools.
1369 <note>
1370 You can also use the <filename>yocto-layer</filename> tool to create
1371 a "generic" layer.
1372 For information on this tool, see the
1373 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
1374 section in the Yocto Project Development Guide.
1375 </note>
1376 </para>
1377
1378 <para>
1379 The next sections provide a concrete starting point to expand on a few points that
1380 might not be immediately obvious or that could use further explanation.
1381 </para>
1382 </section>
1383
1384
1385 <section id='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
1386 <title>Creating a new BSP Layer Using the yocto-bsp Script</title>
1387
1388 <para>
1389 The <filename>yocto-bsp</filename> script creates a new
1390 <link linkend='bsp-layers'>BSP layer</link> for any architecture supported
1391 by the Yocto Project, as well as QEMU versions of the same.
1392 The default mode of the script's operation is to prompt you for information needed
1393 to generate the BSP layer.
1394 </para>
1395
1396 <para>
1397 For the current set of BSPs, the script prompts you for various important
1398 parameters such as:
1399 <itemizedlist>
1400 <listitem><para>The kernel to use</para></listitem>
1401 <listitem><para>The branch of that kernel to use (or re-use)</para></listitem>
1402 <listitem><para>Whether or not to use X, and if so, which drivers to use</para></listitem>
1403 <listitem><para>Whether to turn on SMP</para></listitem>
1404 <listitem><para>Whether the BSP has a keyboard</para></listitem>
1405 <listitem><para>Whether the BSP has a touchscreen</para></listitem>
1406 <listitem><para>Remaining configurable items associated with the BSP</para></listitem>
1407 </itemizedlist>
1408 </para>
1409
1410 <para>
1411 You use the <filename>yocto-bsp create</filename> sub-command to create
1412 a new BSP layer.
1413 This command requires you to specify a particular kernel architecture
1414 (<filename>karch</filename>) on which to base the BSP.
1415 Assuming you have sourced the environment, you can use the
1416 <filename>yocto-bsp list karch</filename> sub-command to list the
1417 architectures available for BSP creation as follows:
1418 <literallayout class='monospaced'>
1419 $ yocto-bsp list karch
1420 Architectures available:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1421 powerpc
1422 x86_64
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1423 i386
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1424 arm
1425 qemu
1426 mips
1427 mips64
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1428 </literallayout>
1429 </para>
1430
1431 <para>
1432 The remainder of this section presents an example that uses
1433 <filename>myarm</filename> as the machine name and <filename>qemu</filename>
1434 as the machine architecture.
1435 Of the available architectures, <filename>qemu</filename> is the only architecture
1436 that causes the script to prompt you further for an actual architecture.
1437 In every other way, this architecture is representative of how creating a BSP for
1438 an actual machine would work.
1439 The reason the example uses this architecture is because it is an emulated architecture
1440 and can easily be followed without requiring actual hardware.
1441 </para>
1442
1443 <para>
1444 As the <filename>yocto-bsp create</filename> command runs, default values for
1445 the prompts appear in brackets.
1446 Pressing enter without supplying anything on the command line or pressing enter
1447 with an invalid response causes the script to accept the default value.
1448 Once the script completes, the new <filename>meta-myarm</filename> BSP layer
1449 is created in the current working directory.
1450 This example assumes you have sourced the
1451 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1452 setup script.
1453 </para>
1454
1455 <para>
1456 Following is the complete example:
1457 <literallayout class='monospaced'>
1458 $ yocto-bsp create myarm qemu
1459 Checking basic git connectivity...
1460 Done.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1461
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1462 Which qemu architecture would you like to use? [default: i386]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1463 1) i386 (32-bit)
1464 2) x86_64 (64-bit)
1465 3) ARM (32-bit)
1466 4) PowerPC (32-bit)
1467 5) MIPS (32-bit)
1468 6) MIPS64 (64-bit)
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1469 3
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600[diff] [blame]1470 Would you like to use the default (4.8) kernel? (y/n) [default: y]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1471 Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600[diff] [blame]1472 Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-4.8.git...
1473 Please choose a machine branch to base this BSP on: [default: standard/base]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1474 1) standard/arm-versatile-926ejs
1475 2) standard/base
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600[diff] [blame]1476 3) standard/beaglebone
1477 4) standard/edgerouter
1478 5) standard/fsl-mpc8315e-rdb
1479 6) standard/mti-malta32
1480 7) standard/mti-malta64
1481 8) standard/qemuarm64
1482 9) standard/qemuppc
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1483 1
1484 Would you like SMP support? (y/n) [default: y]
1485 Does your BSP have a touchscreen? (y/n) [default: n]
1486 Does your BSP have a keyboard? (y/n) [default: y]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1487
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1488 New qemu BSP created in meta-myarm
1489 </literallayout>
1490 Take a closer look at the example now:
1491 <orderedlist>
1492 <listitem><para>For the QEMU architecture,
1493 the script first prompts you for which emulated architecture to use.
1494 In the example, we use the ARM architecture.
1495 </para></listitem>
1496 <listitem><para>The script then prompts you for the kernel.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600[diff] [blame]1497 The default 4.8 kernel is acceptable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1498 So, the example accepts the default.
1499 If you enter 'n', the script prompts you to further enter the kernel
1500 you do want to use.</para></listitem>
1501 <listitem><para>Next, the script asks whether you would like to have a new
1502 branch created especially for your BSP in the local
1503 <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink>
1504 Git repository .
1505 If not, then the script re-uses an existing branch.</para>
1506 <para>In this example, the default (or "yes") is accepted.
1507 Thus, a new branch is created for the BSP rather than using a common, shared
1508 branch.
1509 The new branch is the branch committed to for any patches you might later add.
1510 The reason a new branch is the default is that typically
1511 new BSPs do require BSP-specific patches.
1512 The tool thus assumes that most of time a new branch is required.
1513 </para></listitem>
1514 <listitem><para>Regardless of which choice you make in the previous step,
1515 you are now given the opportunity to select a particular machine branch on
1516 which to base your new BSP-specific machine branch
1517 (or to re-use if you had elected to not create a new branch).
1518 Because this example is generating an ARM-based BSP, the example
1519 uses <filename>#1</filename> at the prompt, which selects the ARM-versatile branch.
1520 </para></listitem>
1521 <listitem><para>The remainder of the prompts are routine.
1522 Defaults are accepted for each.</para></listitem>
1523 <listitem><para>By default, the script creates the new BSP Layer in the
1524 current working directory of the
1525 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1526 (i.e. <filename>poky/build</filename>).
1527 </para></listitem>
1528 </orderedlist>
1529 </para>
1530
1531 <para>
1532 Once the BSP Layer is created, you must add it to your
1533 <filename>bblayers.conf</filename> file.
1534 Here is an example:
1535 <literallayout class='monospaced'>
1536 BBLAYERS = ? " \
1537 /usr/local/src/yocto/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1538 /usr/local/src/yocto/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1539 /usr/local/src/yocto/meta-yocto-bsp \
1540 /usr/local/src/yocto/meta-myarm \
1541 "
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1542 </literallayout>
1543 Adding the layer to this file allows the build system to build the BSP and
1544 the <filename>yocto-kernel</filename> tool to be able to find the layer and
1545 other Metadata it needs on which to operate.
1546 </para>
1547 </section>
1548
1549 <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
1550 <title>Managing Kernel Patches and Config Items with yocto-kernel</title>
1551
1552 <para>
1553 Assuming you have created a <link linkend='bsp-layers'>BSP Layer</link> using
1554 <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
1555 <filename>yocto-bsp</filename></link> and you added it to your
1556 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
1557 variable in the <filename>bblayers.conf</filename> file, you can now use
1558 the <filename>yocto-kernel</filename> script to add patches and configuration
1559 items to the BSP's kernel.
1560 </para>
1561
1562 <para>
1563 The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
1564 and kernel config settings to a BSP's kernel
1565 <filename>.bbappend</filename> file.
1566 All you need to do is use the appropriate sub-command.
1567 Recall that the easiest way to see exactly what sub-commands are available
1568 is to use the <filename>yocto-kernel</filename> built-in help as follows:
1569 <literallayout class='monospaced'>
1570 $ yocto-kernel --help
1571 Usage:
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1572
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1573 Modify and list Yocto BSP kernel config items and patches.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1574
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1575 usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1576
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1577 Current 'yocto-kernel' commands are:
1578 config list List the modifiable set of bare kernel config options for a BSP
1579 config add Add or modify bare kernel config options for a BSP
1580 config rm Remove bare kernel config options from a BSP
1581 patch list List the patches associated with a BSP
1582 patch add Patch the Yocto kernel for a BSP
1583 patch rm Remove patches from a BSP
1584 feature list List the features used by a BSP
1585 feature add Have a BSP use a feature
1586 feature rm Have a BSP stop using a feature
1587 features list List the features available to BSPs
1588 feature describe Describe a particular feature
1589 feature create Create a new BSP-local feature
1590 feature destroy Remove a BSP-local feature
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1591
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1592 See 'yocto-kernel help COMMAND' for more information on a specific command.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500[diff] [blame]1593
1594
1595
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500[diff] [blame]1596 Options:
1597 --version show program's version number and exit
1598 -h, --help show this help message and exit
1599 -D, --debug output debug information
1600 </literallayout>
1601 </para>
1602
1603 <para>
1604 The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
1605 patch to a BSP.
1606 The following example adds two patches to the <filename>myarm</filename> BSP:
1607 <literallayout class='monospaced'>
1608 $ yocto-kernel patch add myarm ~/test.patch
1609 Added patches:
1610 test.patch
1611
1612 $ yocto-kernel patch add myarm ~/yocto-testmod.patch
1613 Added patches:
1614 yocto-testmod.patch
1615 </literallayout>
1616 <note>Although the previous example adds patches one at a time, it is possible
1617 to add multiple patches at the same time.</note>
1618 </para>
1619
1620 <para>
1621 You can verify patches have been added by using the
1622 <filename>yocto-kernel patch list</filename> sub-command.
1623 Here is an example:
1624 <literallayout class='monospaced'>
1625 $ yocto-kernel patch list myarm
1626 The current set of machine-specific patches for myarm is:
1627 1) test.patch
1628 2) yocto-testmod.patch
1629 </literallayout>
1630 </para>
1631
1632 <para>
1633 You can also use the <filename>yocto-kernel</filename> script to
1634 remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command.
1635 Here is an example:
1636 <literallayout class='monospaced'>
1637 $ yocto-kernel patch rm myarm
1638 Specify the patches to remove:
1639 1) test.patch
1640 2) yocto-testmod.patch
1641 1
1642 Removed patches:
1643 test.patch
1644 </literallayout>
1645 </para>
1646
1647 <para>
1648 Again, using the <filename>yocto-kernel patch list</filename> sub-command,
1649 you can verify that the patch was in fact removed:
1650 <literallayout class='monospaced'>
1651 $ yocto-kernel patch list myarm
1652 The current set of machine-specific patches for myarm is:
1653 1) yocto-testmod.patch
1654 </literallayout>
1655 </para>
1656
1657 <para>
1658 In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
1659 sub-command to add one or more kernel config item settings to a BSP.
1660 The following commands add a couple of config items to the
1661 <filename>myarm</filename> BSP:
1662 <literallayout class='monospaced'>
1663 $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
1664 Added item:
1665 CONFIG_MISC_DEVICES=y
1666
1667 $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y
1668 Added item:
1669 CONFIG_YOCTO_TESTMOD=y
1670 </literallayout>
1671 <note>
1672 Although the previous example adds config items one at a time, it is possible
1673 to add multiple config items at the same time.
1674 </note>
1675 </para>
1676
1677 <para>
1678 You can list the config items now associated with the BSP.
1679 Doing so shows you the config items you added as well as others associated
1680 with the BSP:
1681 <literallayout class='monospaced'>
1682 $ yocto-kernel config list myarm
1683 The current set of machine-specific kernel config items for myarm is:
1684 1) CONFIG_MISC_DEVICES=y
1685 2) CONFIG_YOCTO_TESTMOD=y
1686 </literallayout>
1687 </para>
1688
1689 <para>
1690 Finally, you can remove one or more config items using the
1691 <filename>yocto-kernel config rm</filename> sub-command in a manner
1692 completely analogous to <filename>yocto-kernel patch rm</filename>.
1693 </para>
1694 </section>
1695 </section>
1696</chapter>