blob: d7b6f15b26d6ba6ee6c060998ff7233cc740db5f [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!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
Brad Bishopd7bf8c12018-02-25 22:55:05 -050058 <ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050059 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 -050063 supported by the Yocto Project (e.g. <filename>meta-raspberrypi</filename> and
Patrick Williamsc124f4f2015-09-15 14:41:29 -050064 <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 -050068 Here is an example that clones the Raspberry Pi BSP layer:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050069 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050070 $ git clone git://git.yoctoproject.org/meta-raspberrypi
Patrick Williamsc124f4f2015-09-15 14:41:29 -050071 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050072 </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 -050085 For information on the BSP development workflow, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050086 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
87 section.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050088 For more information on how to set up a local copy of source files
89 from a Git repository, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050090 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
91 section also in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050092 </para>
93
94 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050095 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 -050098 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
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500101 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
102 which is established after you run the OpenEmbedded build environment
103 setup script (i.e.
104 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500105 Adding the root allows the OpenEmbedded build system to recognize the BSP
106 definition and from it build an image.
107 Here is an example:
108 <literallayout class='monospaced'>
109 BBLAYERS ?= " \
110 /usr/local/src/yocto/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500111 /usr/local/src/yocto/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500112 /usr/local/src/yocto/meta-yocto-bsp \
113 /usr/local/src/yocto/meta-mylayer \
114 "
115 </literallayout>
116 </para>
117
118 <para>
119 Some BSPs require additional layers on
120 top of the BSP's root layer in order to be functional.
121 For these cases, you also need to add those layers to the
122 <filename>BBLAYERS</filename> variable in order to build the BSP.
123 You must also specify in the "Dependencies" section of the BSP's
124 <filename>README</filename> file any requirements for additional
125 layers and, preferably, any
126 build instructions that might be contained elsewhere
127 in the <filename>README</filename> file.
128 </para>
129
130 <para>
131 Some layers function as a layer to hold other BSP layers.
132 An example of this type of layer is the <filename>meta-intel</filename> layer,
133 which contains a number of individual BSP sub-layers, as well as a directory
134 named <filename>common/</filename> full of common content across those layers.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500135 Another example is the <filename>meta-yocto-bsp</filename> layer mentioned
136 earlier.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500137 </para>
138
139 <para>
140 For more detailed information on layers, see the
141 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500142 section of the Yocto Project Development Tasks Manual.
143 </para>
144 </section>
145
146 <section id='preparing-your-build-host-to-work-with-bsp-layers'>
147 <title>Preparing Your Build Host to Work With BSP Layers</title>
148
149 <para>
150 This section describes how to get your build host ready
151 to work with BSP layers.
152 Once you have the host set up, you can create the layer
153 as described in the
154 "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</link>"
155 section.
156 <note>
157 For structural information on BSPs, see the
158 <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
159 section.
160 </note>
161 <orderedlist>
162 <listitem><para>
163 <emphasis>Set Up the Build Environment:</emphasis>
164 Be sure you are set up to use BitBake in a shell.
165 See the
166 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
167 section in the Yocto Project Development Tasks Manual for information
168 on how to get a build host ready that is either a native
169 Linux machine or a machine that uses CROPS.
170 </para></listitem>
171 <listitem><para>
172 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
173 You need to have a local copy of the Yocto Project
174 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
175 (i.e. a local <filename>poky</filename> repository).
176 See the
177 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
178 and possibly the
179 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
180 and
181 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
182 sections all in the Yocto Project Development Tasks Manual for
183 information on how to clone the <filename>poky</filename>
184 repository and check out the appropriate branch for your work.
185 </para></listitem>
186 <listitem><para>
187 <emphasis>Determine the BSP Layer You Want:</emphasis>
188 The Yocto Project supports many BSPs, which are maintained in
189 their own layers or in layers designed to contain several
190 BSPs.
191 To get an idea of machine support through BSP layers, you can
192 look at the
193 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
194 for the release.
195 </para></listitem>
196 <listitem><para>
197 <emphasis>Optionally Clone the
198 <filename>meta-intel</filename> BSP Layer:</emphasis>
199 If your hardware is based on current Intel CPUs and devices,
200 you can leverage this BSP layer.
201 For details on the <filename>meta-intel</filename> BSP layer,
202 see the layer's
203 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
204 file.
205 <orderedlist>
206 <listitem><para>
207 <emphasis>Navigate to Your Source Directory:</emphasis>
208 Typically, you set up the
209 <filename>meta-intel</filename> Git repository
210 inside the
211 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
212 (e.g. <filename>poky</filename>).
213 </para></listitem>
214 <listitem><para>
215 <emphasis>Clone the Layer:</emphasis>
216 <literallayout class='monospaced'>
217 $ git clone git://git.yoctoproject.org/meta-intel.git
218 Cloning into 'meta-intel'...
219 remote: Counting objects: 14224, done.
220 remote: Compressing objects: 100% (4591/4591), done.
221 remote: Total 14224 (delta 8245), reused 13985 (delta 8006)
222 Receiving objects: 100% (14224/14224), 4.29 MiB | 2.90 MiB/s, done.
223 Resolving deltas: 100% (8245/8245), done.
224 Checking connectivity... done.
225 </literallayout>
226 </para></listitem>
227 <listitem><para>
228 <emphasis>Check Out the Proper Branch:</emphasis>
229 The branch you check out for
230 <filename>meta-intel</filename> must match the same
231 branch you are using for the Yocto Project release
232 (e.g. &DISTRO_NAME_NO_CAP;):
233 <literallayout class='monospaced'>
234 $ git checkout <replaceable>branch_name</replaceable>
235 </literallayout>
236 For an example on how to discover branch names and
237 checkout on a branch, see the
238 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
239 section in the Yocto Project Development Tasks Manual.
240 </para></listitem>
241 </orderedlist>
242 </para></listitem>
243 <listitem><para>
244 <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
245 If your hardware can be more closely leveraged to an
246 existing BSP not within the <filename>meta-intel</filename>
247 BSP layer, you can clone that BSP layer.</para>
248
249 <para>The process is identical to the process used for the
250 <filename>meta-intel</filename> layer except for the layer's
251 name.
252 For example, if you determine that your hardware most
253 closely matches the <filename>meta-minnow</filename>,
254 clone that layer:
255 <literallayout class='monospaced'>
256 $ git clone git://git.yoctoproject.org/meta-minnow
257 Cloning into 'meta-minnow'...
258 remote: Counting objects: 456, done.
259 remote: Compressing objects: 100% (283/283), done.
260 remote: Total 456 (delta 163), reused 384 (delta 91)
261 Receiving objects: 100% (456/456), 96.74 KiB | 0 bytes/s, done.
262 Resolving deltas: 100% (163/163), done.
263 Checking connectivity... done.
264 </literallayout>
265 </para></listitem>
266 <listitem><para>
267 <emphasis>Initialize the Build Environment:</emphasis>
268 While in the root directory of the Source Directory (i.e.
269 <filename>poky</filename>), run the
270 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
271 environment setup script to define the OpenEmbedded
272 build environment on your build host.
273 <literallayout class='monospaced'>
274 $ source &OE_INIT_FILE;
275 </literallayout>
276 Among other things, the script creates the
277 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
278 which is <filename>build</filename> in this case
279 and is located in the
280 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
281 After the script runs, your current working directory
282 is set to the <filename>build</filename> directory.
283 </para></listitem>
284 </orderedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500285 </para>
286 </section>
287
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500288 <section id="bsp-filelayout">
289 <title>Example Filesystem Layout</title>
290
291 <para>
292 Defining a common BSP directory structure allows end-users to understand and
293 become familiar with that structure.
294 A common format also encourages standardization of software support of hardware.
295 </para>
296
297 <para>
298 The proposed form does have elements that are specific to the
299 OpenEmbedded build system.
300 It is intended that this information can be
301 used by other build systems besides the OpenEmbedded build system
302 and that it will be simple
303 to extract information and convert it to other formats if required.
304 The OpenEmbedded build system, through its standard layers mechanism, can directly
305 accept the format described as a layer.
306 The BSP captures all
307 the hardware-specific details in one place in a standard format, which is
308 useful for any person wishing to use the hardware platform regardless of
309 the build system they are using.
310 </para>
311
312 <para>
313 The BSP specification does not include a build system or other tools -
314 it is concerned with the hardware-specific components only.
315 At the end-distribution point, you can ship the BSP combined with a build system
316 and other tools.
317 However, it is important to maintain the distinction that these
318 are separate components that happen to be combined in certain end products.
319 </para>
320
321 <para>
322 Before looking at the common form for the file structure inside a BSP Layer,
323 you should be aware that some requirements do exist in order for a BSP to
324 be considered compliant with the Yocto Project.
325 For that list of requirements, see the
326 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
327 section.
328 </para>
329
330 <para>
331 Below is the common form for the file structure inside a BSP Layer.
332 While you can use this basic form for the standard, realize that the actual structures
333 for specific BSPs could differ.
334
335 <literallayout class='monospaced'>
336 meta-<replaceable>bsp_name</replaceable>/
337 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
338 meta-<replaceable>bsp_name</replaceable>/README
339 meta-<replaceable>bsp_name</replaceable>/README.sources
340 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
341 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
342 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
343 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
344 meta-<replaceable>bsp_name</replaceable>/recipes-core/*
345 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
346 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
347 </literallayout>
348 </para>
349
350 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500351 Below is an example of the Raspberry Pi BSP:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500352
353 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500354 meta-raspberrypi/COPYING.MIT
355 meta-raspberrypi/README
356 meta-raspberrypi/classes
357 meta-raspberrypi/classes/linux-raspberrypi-base.bbclass
358 meta-raspberrypi/classes/sdcard_image-rpi.bbclass
359 meta-raspberrypi/conf/
360 meta-raspberrypi/conf/layer.conf
361 meta-raspberrypi/conf/machine/
362 meta-raspberrypi/conf/machine/raspberrypi.conf
363 meta-raspberrypi/conf/machine/raspberrypi0.conf
364 meta-raspberrypi/conf/machine/raspberrypi2.conf
365 meta-raspberrypi/conf/machine/raspberrypi3.conf
366 meta-raspberrypi/conf/machine/include
367 meta-raspberrypi/conf/machine/include/rpi-base.inc
368 meta-raspberrypi/conf/machine/include/rpi-default-providers.inc
369 meta-raspberrypi/conf/machine/include/rpi-default-settings.inc
370 meta-raspberrypi/conf/machine/include/rpi-default-versions.inc
371 meta-raspberrypi/conf/machine/include/rpi-tune-arm1176jzf-s.inc
372 meta-raspberrypi/files
373 meta-raspberrypi/files/custom-licenses
374 meta-raspberrypi/files/custom-licenses/Broadcom
375 meta-raspberrypi/recipes-bsp
376 meta-raspberrypi/recipes-bsp/bootfiles
377 meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb
378 meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb
379 meta-raspberrypi/recipes-bsp/common
380 meta-raspberrypi/recipes-bsp/common/firmware.inc
381 meta-raspberrypi/recipes-bsp/formfactor_00.bbappend
382 meta-raspberrypi/recipes-bsp/formfactor/raspberrypi/machconfig
383 meta-raspberrypi/recipes-bsp/rpi-mkimage_git.bb
384 meta-raspberrypi/recipes-bsp/rpi-mkimage/License
385 meta-raspberrypi/recipes-bsp/rpi-mkimage/open-files-relative-to-script.patch
386 meta-raspberrypi/recipes-bsp/u-boot/u-boot-rpi_git.bb
387 meta-raspberrypi/recipes-core
388 meta-raspberrypi/recipes-core/images
389 meta-raspberrypi/recipes-core/images/rpi-basic-image.bb
390 meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb
391 meta-raspberrypi/recipes-core/images/rpi-test-image.bb
392 meta-raspberrypi/recipes-core/packagegroups
393 meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb
394 meta-raspberrypi/recipes-core/psplash
395 meta-raspberrypi/recipes-core/psplash/files
396 meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
397 meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h
398 meta-raspberrypi/recipes-devtools
399 meta-raspberrypi/recipes-devtools/bcm2835
400 meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.46.bb
401 meta-raspberrypi/recipes-devtools/pi-blaster
402 meta-raspberrypi/recipes-devtools/pi-blaster/files
403 meta-raspberrypi/recipes-devtools/pi-blaster/*.patch
404 meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster.inc
405 meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb
406 meta-raspberrypi/recipes-devtools/python
407 meta-raspberrypi/recipes-devtools/python/python-rtimu
408 meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch
409 meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb
410 meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.1.0.bb
411 meta-raspberrypi/recipes-devtools/python/rpi-gpio
412 meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch
413 meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.1.bb
414 meta-raspberrypi/recipes-devtools/python/rpio
415 meta-raspberrypi/recipes-devtools/python/rpio/*.patch
416 meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb
417 meta-raspberrypi/recipes-devtools/wiringPi
418 meta-raspberrypi/recipes-devtools/wiringPi/files
419 meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch
420 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi
421 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi/*.patch
422 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb
423 meta-raspberrypi/recipes-graphics
424 meta-raspberrypi/recipes-graphics/eglinfo
425 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend
426 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend
427 meta-raspberrypi/recipes-graphics/userland
428 meta-raspberrypi/recipes-graphics/userland/userland
429 meta-raspberrypi/recipes-graphics/userland/userland/*.patch
430 meta-raspberrypi/recipes-graphics/userland/userland_git.bb
431 meta-raspberrypi/recipes-graphics/vc-graphics
432 meta-raspberrypi/recipes-graphics/vc-graphics/files
433 meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc
434 meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh
435 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb
436 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb
437 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc
438 meta-raspberrypi/recipes-graphics/wayland
439 meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend
440 meta-raspberrypi/recipes-graphics/weston
441 meta-raspberrypi/recipes-graphics/weston/weston_%.bbappend
442 meta-raspberrypi/recipes-graphics/xorg-xserver
443 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config
444 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi
445 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf
446 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d
447 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf
448 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-pitft.conf
449 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
450 meta-raspberrypi/recipes-kernel
451 meta-raspberrypi/recipes-kernel/linux-firmware
452 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware
453 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/LICENSE.broadcom_brcm80211
454 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.bin
455 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.txt
456 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_git.bbappend
457 meta-raspberrypi/recipes-kernel/linux
458 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14
459 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14/*.patch
460 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18
461 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18/*.patch
462 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1
463 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1/*.patch
464 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc
465 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi
466 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi/defconfig
467 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.14.bb
468 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.18.bb
469 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.1.bb
470 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.4.bb
471 meta-raspberrypi/recipes-kernel/linux/linux.inc
472 meta-raspberrypi/recipes-multimedia
473 meta-raspberrypi/recipes-multimedia/gstreamer
474 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx
475 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch
476 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend
477 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend
478 meta-raspberrypi/recipes-multimedia/omxplayer
479 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer
480 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch
481 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb
482 meta-raspberrypi/scripts
483 meta-raspberrypi/scripts/lib
484 meta-raspberrypi/scripts/lib/image
485 meta-raspberrypi/scripts/lib/image/canned-wks
486 meta-raspberrypi/scripts/lib/image/canned-wks/sdimage-raspberrypi.wks
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500487 </literallayout>
488 </para>
489
490 <para>
491 The following sections describe each part of the proposed BSP format.
492 </para>
493
494 <section id="bsp-filelayout-license">
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500495 <title>License Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500496
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500497 <para>
498 You can find these files in the BSP Layer at:
499 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500500 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500501 </literallayout>
502 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500503
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500504 <para>
505 These optional files satisfy licensing requirements for the BSP.
506 The type or types of files here can vary depending on the licensing requirements.
507 For example, in the Raspberry Pi BSP all licensing requirements are handled with the
508 <filename>COPYING.MIT</filename> file.
509 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500510
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500511 <para>
512 Licensing files can be MIT, BSD, GPLv*, and so forth.
513 These files are recommended for the BSP but are optional and totally up to the BSP developer.
514 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500515 </section>
516
517 <section id="bsp-filelayout-readme">
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500518 <title>README File</title>
519
520 <para>
521 You can find this file in the BSP Layer at:
522 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500523 meta-<replaceable>bsp_name</replaceable>/README
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500524 </literallayout>
525 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500526
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500527 <para>
528 This file provides information on how to boot the live images that are optionally
529 included in the <filename>binary/</filename> directory.
530 The <filename>README</filename> file also provides special information needed for
531 building the image.
532 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500533
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500534 <para>
535 At a minimum, the <filename>README</filename> file must
536 contain a list of dependencies, such as the names of
537 any other layers on which the BSP depends and the name of
538 the BSP maintainer with his or her contact information.
539 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500540 </section>
541
542 <section id="bsp-filelayout-readme-sources">
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500543 <title>README.sources File</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500544
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500545 <para>
546 You can find this file in the BSP Layer at:
547 <literallayout class='monospaced'>
548 meta-<replaceable>bsp_name</replaceable>/README.sources
549 </literallayout>
550 </para>
551
552 <para>
553 This file provides information on where to locate the BSP
554 source files used to build the images (if any) that reside in
555 <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
556 Images in the <filename>binary</filename> would be images
557 released with the BSP.
558 The information in the <filename>README.sources</filename>
559 file also helps you find the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500560 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500561 used to generate the images that ship with the BSP.
562 <note>
563 If the BSP's <filename>binary</filename> directory is
564 missing or the directory has no images, an existing
565 <filename>README.sources</filename> file is
566 meaningless.
567 </note>
568 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500569 </section>
570
571 <section id="bsp-filelayout-binary">
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500572 <title>Pre-built User Binaries</title>
573
574 <para>
575 You can find these files in the BSP Layer at:
576 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500577 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500578 </literallayout>
579 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500580
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500581 <para>
582 This optional area contains useful pre-built kernels and
583 user-space filesystem images released with the BSP that are
584 appropriate to the target system.
585 This directory typically contains graphical (e.g. Sato) and
586 minimal live images when the BSP tarball has been created and
587 made available in the
588 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
589 You can use these kernels and images to get a system running
590 and quickly get started on development tasks.
591 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500592
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500593 <para>
594 The exact types of binaries present are highly
595 hardware-dependent.
596 The <filename>README</filename> file should be present in the
597 BSP Layer and it will explain how to use the images with the
598 target hardware.
599 Additionally, the <filename>README.sources</filename> file
600 should be present to locate the sources used to build the
601 images and provide information on the Metadata.
602 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500603 </section>
604
605 <section id='bsp-filelayout-layer'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500606 <title>Layer Configuration File</title>
607
608 <para>
609 You can find this file in the BSP Layer at:
610 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500611 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500612 </literallayout>
613 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500614
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500615 <para>
616 The <filename>conf/layer.conf</filename> file identifies the file structure as a
617 layer, identifies the
618 contents of the layer, and contains information about how the build
619 system should use it.
620 Generally, a standard boilerplate file such as the following works.
621 In the following example, you would replace "<replaceable>bsp</replaceable>" and
622 "<replaceable>_bsp</replaceable>" with the actual name
623 of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template).
624 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500625
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500626 <para>
627 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500628 # We have a conf and classes directory, add to BBPATH
629 BBPATH .= ":${LAYERDIR}"
630
631 # We have a recipes directory, add to BBFILES
632 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500633 ${LAYERDIR}/recipes-*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500634
635 BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>"
636 BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/"
637 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
638
639 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500640 </literallayout>
641 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500642
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500643 <para>
644 To illustrate the string substitutions, here are the corresponding statements
645 from the Raspberry Pi <filename>conf/layer.conf</filename> file:
646 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500647 # We have a conf and classes directory, append to BBPATH
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500648 BBPATH .= ":${LAYERDIR}"
649
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500650 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
651 BBFILES += "${LAYERDIR}/recipes*/*/*.bb \
652 ${LAYERDIR}/recipes*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500653
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500654 BBFILE_COLLECTIONS += "raspberrypi"
655 BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/"
656 BBFILE_PRIORITY_raspberrypi = "9"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500657
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500658 # Additional license directories.
659 LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500660 </literallayout>
661 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500662
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500663 <para>
664 This file simply makes
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500665 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500666 aware of the recipes and configuration directories.
667 The file must exist so that the OpenEmbedded build system can recognize the BSP.
668 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500669 </section>
670
671 <section id="bsp-filelayout-machine">
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500672 <title>Hardware Configuration Options</title>
673
674 <para>
675 You can find these files in the BSP Layer at:
676 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500677 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500678 </literallayout>
679 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500680
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500681 <para>
682 The machine files bind together all the information contained elsewhere
683 in the BSP into a format that the build system can understand.
684 If the BSP supports multiple machines, multiple machine configuration files
685 can be present.
686 These filenames correspond to the values to which users have set the
687 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
688 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500689
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500690 <para>
691 These files define things such as the kernel package to use
692 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
693 of virtual/kernel), the hardware drivers to
694 include in different types of images, any special software components
695 that are needed, any bootloader information, and also any special image
696 format requirements.
697 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500698
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500699 <para>
700 Each BSP Layer requires at least one machine file.
701 However, you can supply more than one file.
702 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500703
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500704 <para>
705 This configuration file could also include a hardware "tuning"
706 file that is commonly used to define the package architecture
707 and specify optimization flags, which are carefully chosen
708 to give best performance on a given processor.
709 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500710
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500711 <para>
712 Tuning files are found in the <filename>meta/conf/machine/include</filename>
713 directory within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500714 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500715 For example, the <filename>ia32-base.inc</filename> file resides in the
716 <filename>meta/conf/machine/include</filename> directory.
717 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500718
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500719 <para>
720 To use an include file, you simply include them in the
721 machine configuration file.
722 For example, the Raspberry Pi BSP
723 <filename>raspberrypi3.conf</filename> contains the
724 following statement:
725 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500726 include conf/machine/raspberrypi2.conf
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500727 </literallayout>
728 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500729 </section>
730
731 <section id='bsp-filelayout-misc-recipes'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500732 <title>Miscellaneous BSP-Specific Recipe Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500733
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500734 <para>
735 You can find these files in the BSP Layer at:
736 <literallayout class='monospaced'>
737 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
738 </literallayout>
739 </para>
740
741 <para>
742 This optional directory contains miscellaneous recipe files for
743 the BSP.
744 Most notably would be the formfactor files.
745 For example, in the Raspberry Pi BSP there is the
746 <filename>formfactor_0.0.bbappend</filename> file, which is an
747 append file used to augment the recipe that starts the build.
748 Furthermore, there are machine-specific settings used during
749 the build that are defined by the
750 <filename>machconfig</filename> file further down in the
751 directory.
752 Here is the <filename>machconfig</filename>
753 file for the Raspberry Pi BSP:
754 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500755 HAVE_TOUCHSCREEN=0
756 HAVE_KEYBOARD=1
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500757
758 DISPLAY_CAN_ROTATE=0
759 DISPLAY_ORIENTATION=0
760 DISPLAY_DPI=133
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500761 </literallayout>
762 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500763
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500764 <note><para>
765 If a BSP does not have a formfactor entry, defaults are established according to
766 the formfactor configuration file that is installed by the main
767 formfactor recipe
768 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
769 which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500770 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500771 </para></note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500772 </section>
773
774 <section id='bsp-filelayout-recipes-graphics'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500775 <title>Display Support Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500776
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500777 <para>
778 You can find these files in the BSP Layer at:
779 <literallayout class='monospaced'>
780 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
781 </literallayout>
782 </para>
783
784 <para>
785 This optional directory contains recipes for the BSP if it has
786 special requirements for graphics support.
787 All files that are needed for the BSP to support a display are
788 kept here.
789 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500790 </section>
791
792 <section id='bsp-filelayout-kernel'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500793 <title>Linux Kernel Configuration</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500794
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500795 <para>
796 You can find these files in the BSP Layer at:
797 <literallayout class='monospaced'>
798 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
799 </literallayout>
800 </para>
801
802 <para>
803 These files append machine-specific changes to the main
804 kernel recipe you are using.
805 </para>
806
807 <para>
808 For your BSP, you typically want to use an existing Yocto
809 Project kernel recipe found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500810 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500811 at <filename>meta/recipes-kernel/linux</filename>.
812 You can append machine-specific changes to the kernel recipe
813 by using a similarly named append file, which is located in
814 the BSP Layer for your target device (e.g. the
815 <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
816 </para>
817
818 <para>
819 Suppose you are using the <filename>linux-yocto_4.4.bb</filename>
820 recipe to build the kernel.
821 In other words, you have selected the kernel in your
822 <replaceable>bsp_name</replaceable><filename>.conf</filename>
823 file by adding
824 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
825 and
826 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
827 statements as follows:
828 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500829 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500830 PREFERRED_VERSION_linux-yocto ?= "4.4%"
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500831 </literallayout>
832 <note>
833 When the preferred provider is assumed by default, the
834 <filename>PREFERRED_PROVIDER</filename>
835 statement does not appear in the
836 <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
837 </note>
838 You would use the <filename>linux-yocto_4.4.bbappend</filename>
839 file to append specific BSP settings to the kernel, thus
840 configuring the kernel for your particular BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500841 </para>
842
843 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500844 You can find more information on what your append file
845 should contain in the
846 "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
847 section in the Yocto Project Linux Kernel Development
848 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500849 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500850 </section>
851 </section>
852
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500853 <section id='developing-a-board-support-package-bsp'>
854 <title>Developing a Board Support Package (BSP)</title>
855
856 <para>
857 This section contains the high-level procedure you can follow
858 to create a BSP using the Yocto Project's
859 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
860 Although not required for BSP creation, the
861 <filename>meta-intel</filename> repository, which contains
862 many BSPs supported by the Yocto Project, is part of the
863 example.
864 </para>
865
866 <para>
867 For an example that shows how to create a new layer using
868 the tools, see the
869 "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
870 section.
871 </para>
872
873 <para>
874 The following illustration and list summarize the BSP
875 creation general workflow.
876 </para>
877
878 <para>
879 <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
880 </para>
881
882 <para>
883 <orderedlist>
884 <listitem><para>
885 <emphasis>Set up Your Host Development System to Support
886 Development Using the Yocto Project</emphasis>:
887 See the
888 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
889 section in the Yocto Project Quick Start for options on how
890 to get a build host ready to use the Yocto Project.
891 </para></listitem>
892 <listitem><para>
893 <emphasis>Establish the <filename>meta-intel</filename>
894 Repository on Your System:</emphasis>
895 Having local copies of these supported BSP layers on
896 your system gives you access to layers you might be able
897 to build on or modify to create your BSP.
898 For information on how to get these files, see the
899 "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
900 section.
901 </para></listitem>
902 <listitem><para>
903 <emphasis>Create Your Own BSP Layer Using the
904 <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></link>
905 script:</emphasis>
906 Layers are ideal for isolating and storing work for a
907 given piece of hardware.
908 A layer is really just a location or area in which you
909 place the recipes and configurations for your BSP.
910 In fact, a BSP is, in itself, a special type of layer.
911 The simplest way to create a new BSP layer that is
912 compliant with the Yocto Project is to use the
913 <filename>yocto-bsp</filename> script.
914 For information about that script, see the
915 "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
916 section.</para>
917
918 <para>Another example that illustrates a layer
919 is an application.
920 Suppose you are creating an application that has
921 library or other dependencies in order for it to
922 compile and run.
923 The layer, in this case, would be where all the
924 recipes that define those dependencies are kept.
925 The key point for a layer is that it is an isolated
926 area that contains all the relevant information for
927 the project that the OpenEmbedded build system knows
928 about.
929 For more information on layers, see the
930 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
931 section in the Yocto Project Development Tasks Manual.
932 For more information on BSP layers, see the
933 "<link linkend='bsp-layers'>BSP Layers</link>"
934 section.
935 <note><title>Notes</title>
936 <para>Five BSPs exist that are part of the Yocto
937 Project release:
938 <filename>beaglebone</filename> (ARM),
939 <filename>mpc8315e</filename> (PowerPC),
940 and <filename>edgerouter</filename> (MIPS).
941 The recipes and configurations for these five BSPs
942 are located and dispersed within the
943 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
944 </para>
945
946 <para>Three core Intel BSPs exist as part of the Yocto
947 Project release in the
948 <filename>meta-intel</filename> layer:
949 <itemizedlist>
950 <listitem><para>
951 <filename>intel-core2-32</filename>,
952 which is a BSP optimized for the Core2 family of CPUs
953 as well as all CPUs prior to the Silvermont core.
954 </para></listitem>
955 <listitem><para>
956 <filename>intel-corei7-64</filename>,
957 which is a BSP optimized for Nehalem and later
958 Core and Xeon CPUs as well as Silvermont and later
959 Atom CPUs, such as the Baytrail SoCs.
960 </para></listitem>
961 <listitem><para>
962 <filename>intel-quark</filename>,
963 which is a BSP optimized for the Intel Galileo
964 gen1 &amp; gen2 development boards.
965 </para></listitem>
966 </itemizedlist></para>
967 </note></para>
968
969 <para>When you set up a layer for a new BSP, you should
970 follow a standard layout.
971 This layout is described in the
972 "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
973 section.
974 In the standard layout, you will notice a suggested
975 structure for recipes and configuration information.
976 You can see the standard layout for a BSP by examining
977 any supported BSP found in the
978 <filename>meta-intel</filename> layer inside the Source
979 Directory.
980 </para></listitem>
981 <listitem><para>
982 <emphasis>Make Configuration Changes to Your New BSP
983 Layer:</emphasis>
984 The standard BSP layer structure organizes the files
985 you need to edit in <filename>conf</filename> and
986 several <filename>recipes-*</filename>
987 directories within the BSP layer.
988 Configuration changes identify where your new layer
989 is on the local system and identify which kernel you
990 are going to use.
991 When you run the <filename>yocto-bsp</filename> script,
992 you are able to interactively configure many things for
993 the BSP (e.g. keyboard, touchscreen, and so forth).
994 </para></listitem>
995 <listitem><para>
996 <emphasis>Make Recipe Changes to Your New BSP
997 Layer:</emphasis>
998 Recipe changes include altering recipes
999 (<filename>.bb</filename> files), removing recipes you
1000 do not use, and adding new recipes or append files
1001 (<filename>.bbappend</filename>) that you need to
1002 support your hardware.
1003 </para></listitem>
1004 <listitem><para>
1005 <emphasis>Prepare for the Build:</emphasis>
1006 Once you have made all the changes to your BSP layer,
1007 there remains a few things you need to do for the
1008 OpenEmbedded build system in order for it to create
1009 your image.
1010 You need to get the build environment ready by
1011 sourcing an environment setup script
1012 (i.e. <filename>oe-init-build-env</filename>)
1013 and you need to be sure two key configuration
1014 files are configured appropriately: the
1015 <filename>conf/local.conf</filename> and the
1016 <filename>conf/bblayers.conf</filename> file.
1017 You must make the OpenEmbedded build system aware
1018 of your new layer.
1019 See the
1020 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1021 section in the Yocto Project Development Tasks Manual
1022 for information on how to let the build system
1023 know about your new layer.</para>
1024
1025 <para>The entire process for building an image is
1026 overviewed in the section
1027 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section
1028 of the Yocto Project Quick Start.
1029 You might want to reference this information.
1030 </para></listitem>
1031 <listitem><para>
1032 <emphasis>Build the Image:</emphasis>
1033 The OpenEmbedded build system uses the BitBake tool
1034 to build images based on the type of image you want to
1035 create.
1036 You can find more information about BitBake in the
1037 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
1038 </para>
1039
1040 <para>The build process supports several types of
1041 images to satisfy different needs.
1042 See the
1043 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1044 chapter in the Yocto Project Reference Manual for
1045 information on supported images.
1046 </para></listitem>
1047 </orderedlist>
1048 </para>
1049 </section>
1050
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001051 <section id='requirements-and-recommendations-for-released-bsps'>
1052 <title>Requirements and Recommendations for Released BSPs</title>
1053
1054 <para>
1055 Certain requirements exist for a released BSP to be considered
1056 compliant with the Yocto Project.
1057 Additionally, recommendations also exist.
1058 This section describes the requirements and recommendations for
1059 released BSPs.
1060 </para>
1061
1062 <section id='released-bsp-requirements'>
1063 <title>Released BSP Requirements</title>
1064
1065 <para>
1066 Before looking at BSP requirements, you should consider the following:
1067 <itemizedlist>
1068 <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal"
1069 layer that can be added to the Yocto Project.
1070 For guidelines on creating a layer that meets these base requirements, see the
1071 "<link linkend='bsp-layers'>BSP Layers</link>" and the
1072 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001073 and Creating Layers"</ulink> in the Yocto Project Development Tasks Manual.
1074 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001075 <listitem><para>The requirements in this section apply regardless of how you
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001076 package a BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001077 You should consult the packaging and distribution guidelines for your
1078 specific release process.
1079 For an example of packaging and distribution requirements, see the
1080 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001081 wiki page.
1082 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001083 <listitem><para>The requirements for the BSP as it is made available to a developer
1084 are completely independent of the released form of the BSP.
1085 For example, the BSP Metadata can be contained within a Git repository
1086 and could have a directory structure completely different from what appears
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001087 in the officially released BSP layer.
1088 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001089 <listitem><para>It is not required that specific packages or package
1090 modifications exist in the BSP layer, beyond the requirements for general
1091 compliance with the Yocto Project.
1092 For example, no requirement exists dictating that a specific kernel or
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001093 kernel version be used in a given BSP.
1094 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001095 </itemizedlist>
1096 </para>
1097
1098 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001099 Following are the requirements for a released BSP that conform to the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001100 Yocto Project:
1101 <itemizedlist>
1102 <listitem><para><emphasis>Layer Name:</emphasis>
1103 The BSP must have a layer name that follows the Yocto
1104 Project standards.
1105 For information on BSP layer names, see the
1106 "<link linkend='bsp-layers'>BSP Layers</link>" section.
1107 </para></listitem>
1108 <listitem><para><emphasis>File System Layout:</emphasis>
1109 When possible, use the same directory names in your
1110 BSP layer as listed in the <filename>recipes.txt</filename> file.
1111 In particular, you should place recipes
1112 (<filename>.bb</filename> files) and recipe
1113 modifications (<filename>.bbappend</filename> files) into
1114 <filename>recipes-*</filename> subdirectories by functional area
1115 as outlined in <filename>recipes.txt</filename>.
1116 If you cannot find a category in <filename>recipes.txt</filename>
1117 to fit a particular recipe, you can make up your own
1118 <filename>recipes-*</filename> subdirectory.
1119 You can find <filename>recipes.txt</filename> in the
1120 <filename>meta</filename> directory of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001121 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001122 or in the OpenEmbedded Core Layer
1123 (<filename>openembedded-core</filename>) found at
1124 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
1125 </para>
1126 <para>Within any particular <filename>recipes-*</filename> category, the layout
1127 should match what is found in the OpenEmbedded Core
1128 Git repository (<filename>openembedded-core</filename>)
1129 or the Source Directory (<filename>poky</filename>).
1130 In other words, make sure you place related files in appropriately
1131 related <filename>recipes-*</filename> subdirectories specific to the
1132 recipe's function, or within a subdirectory containing a set of closely-related
1133 recipes.
1134 The recipes themselves should follow the general guidelines
1135 for recipes used in the Yocto Project found in the
1136 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
1137 </para></listitem>
1138 <listitem><para><emphasis>License File:</emphasis>
1139 You must include a license file in the
1140 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
1141 This license covers the BSP Metadata as a whole.
1142 You must specify which license to use since there is no
1143 default license if one is not specified.
1144 See the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001145 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
1146 file for the Raspberry Pi BSP in the
1147 <filename>meta-raspberrypi</filename> BSP layer as an example.
1148 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001149 <listitem><para><emphasis>README File:</emphasis>
1150 You must include a <filename>README</filename> file in the
1151 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
1152 See the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001153 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
1154 file for the Raspberry Pi BSP in the <filename>meta-raspberrypi</filename> BSP layer
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001155 as an example.</para>
1156 <para>At a minimum, the <filename>README</filename> file should
1157 contain the following:
1158 <itemizedlist>
1159 <listitem><para>A brief description about the hardware the BSP
1160 targets.</para></listitem>
1161 <listitem><para>A list of all the dependencies
1162 on which a BSP layer depends.
1163 These dependencies are typically a list of required layers needed
1164 to build the BSP.
1165 However, the dependencies should also contain information regarding
1166 any other dependencies the BSP might have.</para></listitem>
1167 <listitem><para>Any required special licensing information.
1168 For example, this information includes information on
1169 special variables needed to satisfy a EULA,
1170 or instructions on information needed to build or distribute
1171 binaries built from the BSP Metadata.</para></listitem>
1172 <listitem><para>The name and contact information for the
1173 BSP layer maintainer.
1174 This is the person to whom patches and questions should
1175 be sent.
1176 For information on how to find the right person, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001177 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
1178 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001179 </para></listitem>
1180 <listitem><para>Instructions on how to build the BSP using the BSP
1181 layer.</para></listitem>
1182 <listitem><para>Instructions on how to boot the BSP build from
1183 the BSP layer.</para></listitem>
1184 <listitem><para>Instructions on how to boot the binary images
1185 contained in the <filename>binary</filename> directory,
1186 if present.</para></listitem>
1187 <listitem><para>Information on any known bugs or issues that users
1188 should know about when either building or booting the BSP
1189 binaries.</para></listitem>
1190 </itemizedlist></para></listitem>
1191 <listitem><para><emphasis>README.sources File:</emphasis>
1192 You must include a <filename>README.sources</filename> in the
1193 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
1194 This file specifies exactly where you can find the sources used to
1195 generate the binary images contained in the
1196 <filename>binary</filename> directory, if present.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001197 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001198 <listitem><para><emphasis>Layer Configuration File:</emphasis>
1199 You must include a <filename>conf/layer.conf</filename> in the
1200 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
1201 This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename>
1202 BSP layer as a layer to the build system.</para></listitem>
1203 <listitem><para><emphasis>Machine Configuration File:</emphasis>
1204 You must include one or more
1205 <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename>
1206 files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
1207 These configuration files define machine targets that can be built
1208 using the BSP layer.
1209 Multiple machine configuration files define variations of machine
1210 configurations that are supported by the BSP.
1211 If a BSP supports multiple machine variations, you need to
1212 adequately describe each variation in the BSP
1213 <filename>README</filename> file.
1214 Do not use multiple machine configuration files to describe disparate
1215 hardware.
1216 If you do have very different targets, you should create separate
1217 BSP layers for each target.
1218 <note>It is completely possible for a developer to structure the
1219 working repository as a conglomeration of unrelated BSP
1220 files, and to possibly generate BSPs targeted for release
1221 from that directory using scripts or some other mechanism
1222 (e.g. <filename>meta-yocto-bsp</filename> layer).
1223 Such considerations are outside the scope of this document.</note>
1224 </para></listitem>
1225 </itemizedlist>
1226 </para>
1227 </section>
1228
1229 <section id='released-bsp-recommendations'>
1230 <title>Released BSP Recommendations</title>
1231
1232 <para>
1233 Following are recommendations for a released BSP that conforms to the
1234 Yocto Project:
1235 <itemizedlist>
1236 <listitem><para><emphasis>Bootable Images:</emphasis>
1237 BSP releases
1238 can contain one or more bootable images.
1239 Including bootable images allows users to easily try out the BSP
1240 on their own hardware.</para>
1241 <para>In some cases, it might not be convenient to include a
1242 bootable image.
1243 In this case, you might want to make two versions of the
1244 BSP available: one that contains binary images, and one
1245 that does not.
1246 The version that does not contain bootable images avoids
1247 unnecessary download times for users not interested in the images.
1248 </para>
1249 <para>If you need to distribute a BSP and include bootable images or build kernel and
1250 filesystems meant to allow users to boot the BSP for evaluation
1251 purposes, you should put the images and artifacts within a
1252 <filename>binary/</filename> subdirectory located in the
1253 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
1254 <note>If you do include a bootable image as part of the BSP and the image
1255 was built by software covered by the GPL or other open source licenses,
1256 it is your responsibility to understand
1257 and meet all licensing requirements, which could include distribution
1258 of source files.</note></para></listitem>
1259 <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
1260 Kernel recipes in the BSP should be based on a Yocto Linux kernel.
1261 Basing your recipes on these kernels reduces the costs for maintaining
1262 the BSP and increases its scalability.
1263 See the <filename>Yocto Linux Kernel</filename> category in the
1264 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
1265 for these kernels.</para></listitem>
1266 </itemizedlist>
1267 </para>
1268 </section>
1269 </section>
1270
1271 <section id='customizing-a-recipe-for-a-bsp'>
1272 <title>Customizing a Recipe for a BSP</title>
1273
1274 <para>
1275 If you plan on customizing a recipe for a particular BSP, you need to do the
1276 following:
1277 <itemizedlist>
1278 <listitem><para>Create a <filename>.bbappend</filename>
1279 file for the modified recipe.
1280 For information on using append files, see the
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001281 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001282 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001283 </para></listitem>
1284 <listitem><para>
1285 Ensure your directory structure in the BSP layer
1286 that supports your machine is such that it can be found
1287 by the build system.
1288 See the example later in this section for more information.
1289 </para></listitem>
1290 <listitem><para>
1291 Put the append file in a directory whose name matches
1292 the machine's name and is located in an appropriate
1293 sub-directory inside the BSP layer (i.e.
1294 <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>,
1295 <filename>recipes-core</filename>, and so forth).
1296 </para></listitem>
1297 <listitem><para>Place the BSP-specific files in the proper directory
1298 inside the BSP layer.
1299 How expansive the layer is affects where you must place these files.
1300 For example, if your layer supports several different machine types,
1301 you need to be sure your layer's directory structure includes hierarchy
1302 that separates the files out according to machine.
1303 If your layer does not support multiple machines, the layer would not
1304 have that additional hierarchy and the files would obviously not be
1305 able to reside in a machine-specific directory.
1306 </para></listitem>
1307 </itemizedlist>
1308 </para>
1309
1310 <para>
1311 Following is a specific example to help you better understand the process.
1312 Consider an example that customizes a recipe by adding
1313 a BSP-specific configuration file named <filename>interfaces</filename> to the
1314 <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the
1315 BSP layer also supports several other machines.
1316 Do the following:
1317 <orderedlist>
1318 <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it
1319 contains the following:
1320 <literallayout class='monospaced'>
1321 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1322 </literallayout>
1323 The append file needs to be in the
1324 <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory.
1325 </para></listitem>
1326 <listitem><para>Create and place the new <filename>interfaces</filename>
1327 configuration file in the BSP's layer here:
1328 <literallayout class='monospaced'>
1329 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
1330 </literallayout>
1331 <note>
1332 If the <filename>meta-xyz</filename> layer did not support
1333 multiple machines, you would place the
1334 <filename>interfaces</filename> configuration file in the
1335 layer here:
1336 <literallayout class='monospaced'>
1337 meta-xyz/recipes-core/init-ifupdown/files/interfaces
1338 </literallayout>
1339 </note>
1340 The
1341 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1342 variable in the append files extends the search path
1343 the build system uses to find files during the build.
1344 Consequently, for this example you need to have the
1345 <filename>files</filename> directory in the same location
1346 as your append file.</para></listitem>
1347 </orderedlist>
1348 </para>
1349 </section>
1350
1351 <section id='bsp-licensing-considerations'>
1352 <title>BSP Licensing Considerations</title>
1353
1354 <para>
1355 In some cases, a BSP contains separately licensed Intellectual Property (IP)
1356 for a component or components.
1357 For these cases, you are required to accept the terms of a commercial or other
1358 type of license that requires some kind of explicit End User License Agreement (EULA).
1359 Once the license is accepted, the OpenEmbedded build system can then build and
1360 include the corresponding component in the final BSP image.
1361 If the BSP is available as a pre-built image, you can download the image after
1362 agreeing to the license or EULA.
1363 </para>
1364
1365 <para>
1366 You could find that some separately licensed components that are essential
1367 for normal operation of the system might not have an unencumbered (or free)
1368 substitute.
1369 Without these essential components, the system would be non-functional.
1370 Then again, you might find that other licensed components that are simply
1371 'good-to-have' or purely elective do have an unencumbered, free replacement
1372 component that you can use rather than agreeing to the separately licensed component.
1373 Even for components essential to the system, you might find an unencumbered component
1374 that is not identical but will work as a less-capable version of the
1375 licensed version in the BSP recipe.
1376 </para>
1377
1378 <para>
1379 For cases where you can substitute a free component and still
1380 maintain the system's functionality, the "Downloads" page from the
1381 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink>
1382 makes available de-featured BSPs
1383 that are completely free of any IP encumbrances.
1384 For these cases, you can use the substitution directly and
1385 without any further licensing requirements.
1386 If present, these fully de-featured BSPs are named appropriately
1387 different as compared to the names of the respective
1388 encumbered BSPs.
1389 If available, these substitutions are your
1390 simplest and most preferred options.
1391 Use of these substitutions of course assumes the resulting functionality meets
1392 system requirements.
1393 </para>
1394
1395 <para>
1396 If however, a non-encumbered version is unavailable or
1397 it provides unsuitable functionality or quality, you can use an encumbered
1398 version.
1399 </para>
1400
1401 <para>
1402 A couple different methods exist within the OpenEmbedded build system to
1403 satisfy the licensing requirements for an encumbered BSP.
1404 The following list describes them in order of preference:
1405 <orderedlist>
1406 <listitem><para><emphasis>Use the
1407 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1408 variable to define the recipes that have commercial or other
1409 types of specially-licensed packages:</emphasis>
1410 For each of those recipes, you can
1411 specify a matching license string in a
1412 <filename>local.conf</filename> variable named
1413 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
1414 Specifying the matching license string signifies that you agree to the license.
1415 Thus, the build system can build the corresponding recipe and include
1416 the component in the image.
1417 See the
1418 "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
1419 Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
1420 Manual for details on how to use these variables.</para>
1421 <para>If you build as you normally would, without
1422 specifying any recipes in the
1423 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
1424 provides you with the list of recipes that you have
1425 tried to include in the image that need entries in
1426 the <filename>LICENSE_FLAGS_WHITELIST</filename>.
1427 Once you enter the appropriate license flags into the whitelist,
1428 restart the build to continue where it left off.
1429 During the build, the prompt will not appear again
1430 since you have satisfied the requirement.</para>
1431 <para>Once the appropriate license flags are on the white list
1432 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
1433 can build the encumbered image with no change at all
1434 to the normal build process.</para></listitem>
1435 <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis>
1436 You can get this type of BSP by visiting the
1437 "Downloads" page of the
1438 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1439 You can download BSP tarballs that contain proprietary components
1440 after agreeing to the licensing
1441 requirements of each of the individually encumbered
1442 packages as part of the download process.
1443 Obtaining the BSP this way allows you to access an encumbered
1444 image immediately after agreeing to the
1445 click-through license agreements presented by the
1446 website.
1447 Note that if you want to build the image
1448 yourself using the recipes contained within the BSP
1449 tarball, you will still need to create an
1450 appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the
1451 encumbered recipes in the BSP.</para></listitem>
1452 </orderedlist>
1453 </para>
1454
1455 <note>
1456 Pre-compiled images are bundled with
1457 a time-limited kernel that runs for a
1458 predetermined amount of time (10 days) before it forces
1459 the system to reboot.
1460 This limitation is meant to discourage direct redistribution
1461 of the image.
1462 You must eventually rebuild the image if you want to remove this restriction.
1463 </note>
1464 </section>
1465
1466 <section id='using-the-yocto-projects-bsp-tools'>
1467 <title>Using the Yocto Project's BSP Tools</title>
1468
1469 <para>
1470 The Yocto Project includes a couple of tools that enable
1471 you to create a <link linkend='bsp-layers'>BSP layer</link>
1472 from scratch and do basic configuration and maintenance
1473 of the kernel without ever looking at a Metadata file.
1474 These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
1475 respectively.
1476 </para>
1477
1478 <para>
1479 The following sections describe the common location and help features as well
1480 as provide details for the
1481 <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools.
1482 </para>
1483
1484 <section id='common-features'>
1485 <title>Common Features</title>
1486
1487 <para>
1488 Designed to have a command interface somewhat like
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001489 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>, each
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001490 tool is structured as a set of sub-commands under a
1491 top-level command.
1492 The top-level command (<filename>yocto-bsp</filename>
1493 or <filename>yocto-kernel</filename>) itself does
1494 nothing but invoke or provide help on the sub-commands
1495 it supports.
1496 </para>
1497
1498 <para>
1499 Both tools reside in the <filename>scripts/</filename> subdirectory
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001500 of the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001501 Consequently, to use the scripts, you must <filename>source</filename> the
1502 environment just as you would when invoking a build:
1503 <literallayout class='monospaced'>
1504 $ source oe-init-build-env <replaceable>build_dir</replaceable>
1505 </literallayout>
1506 </para>
1507
1508 <para>
1509 The most immediately useful function is to get help on both tools.
1510 The built-in help system makes it easy to drill down at
1511 any time and view the syntax required for any specific command.
1512 Simply enter the name of the command with the <filename>help</filename>
1513 switch:
1514 <literallayout class='monospaced'>
1515 $ yocto-bsp help
1516 Usage:
1517
1518 Create a customized Yocto BSP layer.
1519
1520 usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
1521
1522 Current 'yocto-bsp' commands are:
1523 create Create a new Yocto BSP
1524 list List available values for options and BSP properties
1525
1526 See 'yocto-bsp help COMMAND' for more information on a specific command.
1527
1528
1529 Options:
1530 --version show program's version number and exit
1531 -h, --help show this help message and exit
1532 -D, --debug output debug information
1533 </literallayout>
1534 </para>
1535
1536 <para>
1537 Similarly, entering just the name of a sub-command shows the detailed usage
1538 for that sub-command:
1539 <literallayout class='monospaced'>
1540 $ yocto-bsp create
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001541 ERROR:root:Wrong number of arguments, exiting
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001542
1543 Usage:
1544
1545 Create a new Yocto BSP
1546
1547 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 -05001548 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001549
1550 This command creates a Yocto BSP based on the specified parameters.
1551 The new BSP will be a new Yocto BSP layer contained by default within
1552 the top-level directory specified as 'meta-bsp-name'. The -o option
1553 can be used to place the BSP layer in a directory with a different
1554 name and location.
1555
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001556 The value of the 'karch' parameter determines the set of files that
1557 will be generated for the BSP, along with the specific set of
1558 'properties' that will be used to fill out the BSP-specific portions
1559 of the BSP. The possible values for the 'karch' parameter can be
1560 listed via 'yocto-bsp list karch'.
1561
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001562 ...
1563 </literallayout>
1564 </para>
1565
1566 <para>
1567 For any sub-command, you can use the word "help" option just before the
1568 sub-command to get more extensive documentation:
1569 <literallayout class='monospaced'>
1570 $ yocto-bsp help create
1571
1572 NAME
1573 yocto-bsp create - Create a new Yocto BSP
1574
1575 SYNOPSIS
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001576 yocto-bsp create &lt;bsp-name> &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001577 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
1578
1579 DESCRIPTION
1580 This command creates a Yocto BSP based on the specified
1581 parameters. The new BSP will be a new Yocto BSP layer contained
1582 by default within the top-level directory specified as
1583 'meta-bsp-name'. The -o option can be used to place the BSP layer
1584 in a directory with a different name and location.
1585
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001586 ...
1587 </literallayout>
1588 </para>
1589
1590 <para>
1591 Now that you know where these two commands reside and how to access information
1592 on them, you should find it relatively straightforward to discover the commands
1593 necessary to create a BSP and perform basic kernel maintenance on that BSP using
1594 the tools.
1595 <note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001596 You can also use the <filename>bitbake-layers</filename> script to create
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001597 a "generic" layer.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001598 For information on using this script to create a layer, see the
1599 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
1600 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001601 </note>
1602 </para>
1603
1604 <para>
1605 The next sections provide a concrete starting point to expand on a few points that
1606 might not be immediately obvious or that could use further explanation.
1607 </para>
1608 </section>
1609
1610
1611 <section id='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
1612 <title>Creating a new BSP Layer Using the yocto-bsp Script</title>
1613
1614 <para>
1615 The <filename>yocto-bsp</filename> script creates a new
1616 <link linkend='bsp-layers'>BSP layer</link> for any architecture supported
1617 by the Yocto Project, as well as QEMU versions of the same.
1618 The default mode of the script's operation is to prompt you for information needed
1619 to generate the BSP layer.
1620 </para>
1621
1622 <para>
1623 For the current set of BSPs, the script prompts you for various important
1624 parameters such as:
1625 <itemizedlist>
1626 <listitem><para>The kernel to use</para></listitem>
1627 <listitem><para>The branch of that kernel to use (or re-use)</para></listitem>
1628 <listitem><para>Whether or not to use X, and if so, which drivers to use</para></listitem>
1629 <listitem><para>Whether to turn on SMP</para></listitem>
1630 <listitem><para>Whether the BSP has a keyboard</para></listitem>
1631 <listitem><para>Whether the BSP has a touchscreen</para></listitem>
1632 <listitem><para>Remaining configurable items associated with the BSP</para></listitem>
1633 </itemizedlist>
1634 </para>
1635
1636 <para>
1637 You use the <filename>yocto-bsp create</filename> sub-command to create
1638 a new BSP layer.
1639 This command requires you to specify a particular kernel architecture
1640 (<filename>karch</filename>) on which to base the BSP.
1641 Assuming you have sourced the environment, you can use the
1642 <filename>yocto-bsp list karch</filename> sub-command to list the
1643 architectures available for BSP creation as follows:
1644 <literallayout class='monospaced'>
1645 $ yocto-bsp list karch
1646 Architectures available:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001647 powerpc
1648 x86_64
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001649 i386
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001650 arm
1651 qemu
1652 mips
1653 mips64
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001654 </literallayout>
1655 </para>
1656
1657 <para>
1658 The remainder of this section presents an example that uses
1659 <filename>myarm</filename> as the machine name and <filename>qemu</filename>
1660 as the machine architecture.
1661 Of the available architectures, <filename>qemu</filename> is the only architecture
1662 that causes the script to prompt you further for an actual architecture.
1663 In every other way, this architecture is representative of how creating a BSP for
1664 an actual machine would work.
1665 The reason the example uses this architecture is because it is an emulated architecture
1666 and can easily be followed without requiring actual hardware.
1667 </para>
1668
1669 <para>
1670 As the <filename>yocto-bsp create</filename> command runs, default values for
1671 the prompts appear in brackets.
1672 Pressing enter without supplying anything on the command line or pressing enter
1673 with an invalid response causes the script to accept the default value.
1674 Once the script completes, the new <filename>meta-myarm</filename> BSP layer
1675 is created in the current working directory.
1676 This example assumes you have sourced the
1677 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1678 setup script.
1679 </para>
1680
1681 <para>
1682 Following is the complete example:
1683 <literallayout class='monospaced'>
1684 $ yocto-bsp create myarm qemu
1685 Checking basic git connectivity...
1686 Done.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001687
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001688 Which qemu architecture would you like to use? [default: i386]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001689 1) i386 (32-bit)
1690 2) x86_64 (64-bit)
1691 3) ARM (32-bit)
1692 4) PowerPC (32-bit)
1693 5) MIPS (32-bit)
1694 6) MIPS64 (64-bit)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001695 3
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001696 Would you like to use the default (4.8) kernel? (y/n) [default: y]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001697 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 -06001698 Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-4.8.git...
1699 Please choose a machine branch to base this BSP on: [default: standard/base]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001700 1) standard/arm-versatile-926ejs
1701 2) standard/base
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001702 3) standard/beaglebone
1703 4) standard/edgerouter
1704 5) standard/fsl-mpc8315e-rdb
1705 6) standard/mti-malta32
1706 7) standard/mti-malta64
1707 8) standard/qemuarm64
1708 9) standard/qemuppc
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001709 1
1710 Would you like SMP support? (y/n) [default: y]
1711 Does your BSP have a touchscreen? (y/n) [default: n]
1712 Does your BSP have a keyboard? (y/n) [default: y]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001713
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001714 New qemu BSP created in meta-myarm
1715 </literallayout>
1716 Take a closer look at the example now:
1717 <orderedlist>
1718 <listitem><para>For the QEMU architecture,
1719 the script first prompts you for which emulated architecture to use.
1720 In the example, we use the ARM architecture.
1721 </para></listitem>
1722 <listitem><para>The script then prompts you for the kernel.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001723 The default 4.8 kernel is acceptable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001724 So, the example accepts the default.
1725 If you enter 'n', the script prompts you to further enter the kernel
1726 you do want to use.</para></listitem>
1727 <listitem><para>Next, the script asks whether you would like to have a new
1728 branch created especially for your BSP in the local
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001729 Linux Yocto Kernel Git repository .
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001730 If not, then the script re-uses an existing branch.</para>
1731 <para>In this example, the default (or "yes") is accepted.
1732 Thus, a new branch is created for the BSP rather than using a common, shared
1733 branch.
1734 The new branch is the branch committed to for any patches you might later add.
1735 The reason a new branch is the default is that typically
1736 new BSPs do require BSP-specific patches.
1737 The tool thus assumes that most of time a new branch is required.
1738 </para></listitem>
1739 <listitem><para>Regardless of which choice you make in the previous step,
1740 you are now given the opportunity to select a particular machine branch on
1741 which to base your new BSP-specific machine branch
1742 (or to re-use if you had elected to not create a new branch).
1743 Because this example is generating an ARM-based BSP, the example
1744 uses <filename>#1</filename> at the prompt, which selects the ARM-versatile branch.
1745 </para></listitem>
1746 <listitem><para>The remainder of the prompts are routine.
1747 Defaults are accepted for each.</para></listitem>
1748 <listitem><para>By default, the script creates the new BSP Layer in the
1749 current working directory of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001750 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001751 (i.e. <filename>poky/build</filename>).
1752 </para></listitem>
1753 </orderedlist>
1754 </para>
1755
1756 <para>
1757 Once the BSP Layer is created, you must add it to your
1758 <filename>bblayers.conf</filename> file.
1759 Here is an example:
1760 <literallayout class='monospaced'>
1761 BBLAYERS = ? " \
1762 /usr/local/src/yocto/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001763 /usr/local/src/yocto/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001764 /usr/local/src/yocto/meta-yocto-bsp \
1765 /usr/local/src/yocto/meta-myarm \
1766 "
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001767 </literallayout>
1768 Adding the layer to this file allows the build system to build the BSP and
1769 the <filename>yocto-kernel</filename> tool to be able to find the layer and
1770 other Metadata it needs on which to operate.
1771 </para>
1772 </section>
1773
1774 <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
1775 <title>Managing Kernel Patches and Config Items with yocto-kernel</title>
1776
1777 <para>
1778 Assuming you have created a <link linkend='bsp-layers'>BSP Layer</link> using
1779 <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
1780 <filename>yocto-bsp</filename></link> and you added it to your
1781 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
1782 variable in the <filename>bblayers.conf</filename> file, you can now use
1783 the <filename>yocto-kernel</filename> script to add patches and configuration
1784 items to the BSP's kernel.
1785 </para>
1786
1787 <para>
1788 The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
1789 and kernel config settings to a BSP's kernel
1790 <filename>.bbappend</filename> file.
1791 All you need to do is use the appropriate sub-command.
1792 Recall that the easiest way to see exactly what sub-commands are available
1793 is to use the <filename>yocto-kernel</filename> built-in help as follows:
1794 <literallayout class='monospaced'>
1795 $ yocto-kernel --help
1796 Usage:
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001797
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001798 Modify and list Yocto BSP kernel config items and patches.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001799
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001800 usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001801
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001802 Current 'yocto-kernel' commands are:
1803 config list List the modifiable set of bare kernel config options for a BSP
1804 config add Add or modify bare kernel config options for a BSP
1805 config rm Remove bare kernel config options from a BSP
1806 patch list List the patches associated with a BSP
1807 patch add Patch the Yocto kernel for a BSP
1808 patch rm Remove patches from a BSP
1809 feature list List the features used by a BSP
1810 feature add Have a BSP use a feature
1811 feature rm Have a BSP stop using a feature
1812 features list List the features available to BSPs
1813 feature describe Describe a particular feature
1814 feature create Create a new BSP-local feature
1815 feature destroy Remove a BSP-local feature
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001816
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001817 See 'yocto-kernel help COMMAND' for more information on a specific command.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001818
1819
1820
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001821 Options:
1822 --version show program's version number and exit
1823 -h, --help show this help message and exit
1824 -D, --debug output debug information
1825 </literallayout>
1826 </para>
1827
1828 <para>
1829 The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
1830 patch to a BSP.
1831 The following example adds two patches to the <filename>myarm</filename> BSP:
1832 <literallayout class='monospaced'>
1833 $ yocto-kernel patch add myarm ~/test.patch
1834 Added patches:
1835 test.patch
1836
1837 $ yocto-kernel patch add myarm ~/yocto-testmod.patch
1838 Added patches:
1839 yocto-testmod.patch
1840 </literallayout>
1841 <note>Although the previous example adds patches one at a time, it is possible
1842 to add multiple patches at the same time.</note>
1843 </para>
1844
1845 <para>
1846 You can verify patches have been added by using the
1847 <filename>yocto-kernel patch list</filename> sub-command.
1848 Here is an example:
1849 <literallayout class='monospaced'>
1850 $ yocto-kernel patch list myarm
1851 The current set of machine-specific patches for myarm is:
1852 1) test.patch
1853 2) yocto-testmod.patch
1854 </literallayout>
1855 </para>
1856
1857 <para>
1858 You can also use the <filename>yocto-kernel</filename> script to
1859 remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command.
1860 Here is an example:
1861 <literallayout class='monospaced'>
1862 $ yocto-kernel patch rm myarm
1863 Specify the patches to remove:
1864 1) test.patch
1865 2) yocto-testmod.patch
1866 1
1867 Removed patches:
1868 test.patch
1869 </literallayout>
1870 </para>
1871
1872 <para>
1873 Again, using the <filename>yocto-kernel patch list</filename> sub-command,
1874 you can verify that the patch was in fact removed:
1875 <literallayout class='monospaced'>
1876 $ yocto-kernel patch list myarm
1877 The current set of machine-specific patches for myarm is:
1878 1) yocto-testmod.patch
1879 </literallayout>
1880 </para>
1881
1882 <para>
1883 In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
1884 sub-command to add one or more kernel config item settings to a BSP.
1885 The following commands add a couple of config items to the
1886 <filename>myarm</filename> BSP:
1887 <literallayout class='monospaced'>
1888 $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
1889 Added item:
1890 CONFIG_MISC_DEVICES=y
1891
1892 $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y
1893 Added item:
1894 CONFIG_YOCTO_TESTMOD=y
1895 </literallayout>
1896 <note>
1897 Although the previous example adds config items one at a time, it is possible
1898 to add multiple config items at the same time.
1899 </note>
1900 </para>
1901
1902 <para>
1903 You can list the config items now associated with the BSP.
1904 Doing so shows you the config items you added as well as others associated
1905 with the BSP:
1906 <literallayout class='monospaced'>
1907 $ yocto-kernel config list myarm
1908 The current set of machine-specific kernel config items for myarm is:
1909 1) CONFIG_MISC_DEVICES=y
1910 2) CONFIG_YOCTO_TESTMOD=y
1911 </literallayout>
1912 </para>
1913
1914 <para>
1915 Finally, you can remove one or more config items using the
1916 <filename>yocto-kernel config rm</filename> sub-command in a manner
1917 completely analogous to <filename>yocto-kernel patch rm</filename>.
1918 </para>
1919 </section>
1920 </section>
1921</chapter>