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