blob: 00a28b0327fc1492b4e0c2a97323952e7b7ab0b5 [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
Brad Bishop316dfdd2018-06-25 12:45:53 -04007<title>Board Support Packages (BSP) - Developer's Guide</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008
Brad Bishop316dfdd2018-06-25 12:45:53 -04009<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>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050020
Brad Bishop316dfdd2018-06-25 12:45:53 -040021<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 a
26 <link linkend='bsp-layers'>BSP Layer</link> using the
27 <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></link>
28 tool.
29</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050030
Brad Bishop316dfdd2018-06-25 12:45:53 -040031<section id='bsp-layers'>
32 <title>BSP Layers</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050033
Brad Bishop316dfdd2018-06-25 12:45:53 -040034 <para>
35 A BSP consists of a file structure inside a base directory.
36 Collectively, you can think of the base directory, its file structure,
37 and the contents as a BSP Layer.
38 Although not a strict requirement, BSP layers in the Yocto Project
39 use the following well-established naming convention:
40 <literallayout class='monospaced'>
41 meta-<replaceable>bsp_root_name</replaceable>
42 </literallayout>
43 The string "meta-" is prepended to the machine or platform name, which is
44 <replaceable>bsp_root_name</replaceable> in the above form.
45 <note><title>Tip</title>
46 Because the BSP layer naming convention is well-established,
47 it is advisable to follow it when creating layers.
48 Technically speaking, a BSP layer name does not need to
49 start with <filename>meta-</filename>.
50 However, various scripts and tools in the Yocto Project
51 development environment assume this convention.
52 </note>
53 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050054
Brad Bishop316dfdd2018-06-25 12:45:53 -040055 <para>
56 To help understand the BSP layer concept, consider the BSPs that the
57 Yocto Project supports and provides with each release.
58 You can see the layers in the
59 <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
60 through a web interface at
61 <ulink url='&YOCTO_GIT_URL;'></ulink>.
62 If you go to that interface, you will find a list of repositories
63 under "Yocto Metadata Layers".
64 <note>
65 Layers that are no longer actively supported as part of the
66 Yocto Project appear under the heading "Yocto Metadata Layer
67 Archive."
68 </note>
69 Each repository is a BSP layer supported by the Yocto Project
70 (e.g. <filename>meta-raspberrypi</filename> and
71 <filename>meta-intel</filename>).
72 Each of these layers is a repository unto itself and clicking on a
73 layer reveals information that includes two links from which you can choose
74 to set up a clone of the layer's repository on your local host system.
75 Here is an example that clones the Raspberry Pi BSP layer:
76 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050077 $ git clone git://git.yoctoproject.org/meta-raspberrypi
Brad Bishop316dfdd2018-06-25 12:45:53 -040078 </literallayout>
79 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050080
Brad Bishop316dfdd2018-06-25 12:45:53 -040081 <para>
82 In addition to BSP layers, the
83 <filename>meta-yocto-bsp</filename> layer is part of the
84 shipped <filename>poky</filename> repository.
85 The <filename>meta-yocto-bsp</filename> layer maintains several
86 BSPs such as the Beaglebone, EdgeRouter, and generic versions of
87 both 32-bit and 64-bit IA machines.
88 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050089
Brad Bishop316dfdd2018-06-25 12:45:53 -040090 <para>
91 For information on the BSP development workflow, see the
92 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
93 section.
94 For more information on how to set up a local copy of source files
95 from a Git repository, see the
96 "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
97 section in the Yocto Project Development Tasks Manual.
98 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050099
Brad Bishop316dfdd2018-06-25 12:45:53 -0400100 <para>
101 The layer's base directory
102 (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>)
103 is the root directory of the BSP Layer.
104 This directory is what you add to the
105 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
106 variable in the <filename>conf/bblayers.conf</filename> file found in the
107 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
108 which is established after you run the OpenEmbedded build environment
109 setup script (i.e.
110 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
111 Adding the root directory allows the
112 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
113 to recognize the BSP layer and from it build an image.
114 Here is an example:
115 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500116 BBLAYERS ?= " \
117 /usr/local/src/yocto/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500118 /usr/local/src/yocto/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500119 /usr/local/src/yocto/meta-yocto-bsp \
120 /usr/local/src/yocto/meta-mylayer \
121 "
Brad Bishop316dfdd2018-06-25 12:45:53 -0400122 </literallayout>
123 <note><title>Tip</title>
124 Ordering and
125 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
126 for the layers listed in <filename>BBLAYERS</filename>
127 matter.
128 For example, if multiple layers define a machine
129 configuration, the OpenEmbedded build system uses
130 the last layer searched given similar layer
131 priorities.
132 The build system works from the top-down through
133 the layers listed in <filename>BBLAYERS</filename>.
134 </note>
135 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500136
Brad Bishop316dfdd2018-06-25 12:45:53 -0400137 <para>
138 Some BSPs require or depend on additional layers
139 beyond the BSP's root layer in order to be functional.
140 In this case, you need to specify these layers in the
141 <filename>README</filename> "Dependencies" section of the
142 BSP's root layer.
143 Additionally, if any build instructions exist for the
144 BSP, you must add them to the "Dependencies" section.
145 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500146
Brad Bishop316dfdd2018-06-25 12:45:53 -0400147 <para>
148 Some layers function as a layer to hold other BSP layers.
149 These layers are knows as
150 "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>".
151 An example of this type of layer is the
152 <filename>meta-intel</filename> layer.
153 This layer contains BSP layers for the Intel-core2-32
154 <trademark class='registered'>Intel</trademark> Common Core
155 (Intel-core2-32) and the Intel-corei7-64
156 <trademark class='registered'>Intel</trademark> Common Core
157 (Intel-corei7-64).
158 the <filename>meta-intel</filename> layer also contains
159 the <filename>common/</filename> directory, which contains
160 common content across those layers.
161 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500162
Brad Bishop316dfdd2018-06-25 12:45:53 -0400163 <para>
164 For more information on layers, see the
165 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
166 section of the Yocto Project Development Tasks Manual.
167 </para>
168</section>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500169
Brad Bishop316dfdd2018-06-25 12:45:53 -0400170<section id='preparing-your-build-host-to-work-with-bsp-layers'>
171 <title>Preparing Your Build Host to Work With BSP Layers</title>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500172
Brad Bishop316dfdd2018-06-25 12:45:53 -0400173 <para>
174 This section describes how to get your build host ready
175 to work with BSP layers.
176 Once you have the host set up, you can create the layer
177 as described in the
178 "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
179 section.
180 <note>
181 For structural information on BSPs, see the
182 <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
183 section.
184 </note>
185 <orderedlist>
186 <listitem><para>
187 <emphasis>Set Up the Build Environment:</emphasis>
188 Be sure you are set up to use BitBake in a shell.
189 See the
190 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
191 section in the Yocto Project Development Tasks Manual for information
192 on how to get a build host ready that is either a native
193 Linux machine or a machine that uses CROPS.
194 </para></listitem>
195 <listitem><para>
196 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
197 You need to have a local copy of the Yocto Project
198 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
199 (i.e. a local <filename>poky</filename> repository).
200 See the
201 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
202 and possibly the
203 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
204 or
205 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
206 sections all in the Yocto Project Development Tasks Manual for
207 information on how to clone the <filename>poky</filename>
208 repository and check out the appropriate branch for your work.
209 </para></listitem>
210 <listitem><para>
211 <emphasis>Determine the BSP Layer You Want:</emphasis>
212 The Yocto Project supports many BSPs, which are maintained in
213 their own layers or in layers designed to contain several
214 BSPs.
215 To get an idea of machine support through BSP layers, you can
216 look at the
217 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
218 for the release.
219 </para></listitem>
220 <listitem><para>
221 <emphasis>Optionally Clone the
222 <filename>meta-intel</filename> BSP Layer:</emphasis>
223 If your hardware is based on current Intel CPUs and devices,
224 you can leverage this BSP layer.
225 For details on the <filename>meta-intel</filename> BSP layer,
226 see the layer's
227 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
228 file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500229 <orderedlist>
230 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400231 <emphasis>Navigate to Your Source Directory:</emphasis>
232 Typically, you set up the
233 <filename>meta-intel</filename> Git repository
234 inside the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500235 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400236 (e.g. <filename>poky</filename>).
237 <literallayout class='monospaced'>
238 $ cd /home/<replaceable>you</replaceable>/poky
239 </literallayout>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500240 </para></listitem>
241 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400242 <emphasis>Clone the Layer:</emphasis>
243 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500244 $ git clone git://git.yoctoproject.org/meta-intel.git
245 Cloning into 'meta-intel'...
Brad Bishop316dfdd2018-06-25 12:45:53 -0400246 remote: Counting objects: 15585, done.
247 remote: Compressing objects: 100% (5056/5056), done.
248 remote: Total 15585 (delta 9123), reused 15329 (delta 8867)
249 Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done.
250 Resolving deltas: 100% (9123/9123), done.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500251 Checking connectivity... done.
252 </literallayout>
253 </para></listitem>
254 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400255 <emphasis>Check Out the Proper Branch:</emphasis>
256 The branch you check out for
257 <filename>meta-intel</filename> must match the same
258 branch you are using for the Yocto Project release
259 (e.g. &DISTRO_NAME_NO_CAP;):
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500260 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400261 $ cd meta-intel
262 $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP;
263 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
264 Switched to a new branch '&DISTRO_NAME_NO_CAP;'
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500265 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400266 <note>
267 To see the available branch names in a cloned repository,
268 use the <filename>git branch -al</filename> command.
269 See the
270 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
271 section in the Yocto Project Development Tasks
272 Manual for more information.
273 </note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500274 </para></listitem>
275 </orderedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400276 </para></listitem>
277 <listitem><para>
278 <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
279 If your hardware can be more closely leveraged to an
280 existing BSP not within the <filename>meta-intel</filename>
281 BSP layer, you can clone that BSP layer.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500282
Brad Bishop316dfdd2018-06-25 12:45:53 -0400283 <para>The process is identical to the process used for the
284 <filename>meta-intel</filename> layer except for the layer's
285 name.
286 For example, if you determine that your hardware most
287 closely matches the <filename>meta-raspberrypi</filename>,
288 clone that layer:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500289 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400290 $ git clone git://git.yoctoproject.org/meta-raspberrypi
291 Cloning into 'meta-raspberrypi'...
292 remote: Counting objects: 4743, done.
293 remote: Compressing objects: 100% (2185/2185), done.
294 remote: Total 4743 (delta 2447), reused 4496 (delta 2258)
295 Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done.
296 Resolving deltas: 100% (2447/2447), done.
297 Checking connectivity... done.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500298 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400299 </para></listitem>
300 <listitem><para>
301 <emphasis>Initialize the Build Environment:</emphasis>
302 While in the root directory of the Source Directory (i.e.
303 <filename>poky</filename>), run the
304 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
305 environment setup script to define the OpenEmbedded
306 build environment on your build host.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500307 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400308 $ source &OE_INIT_FILE;
309 </literallayout>
310 Among other things, the script creates the
311 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
312 which is <filename>build</filename> in this case
313 and is located in the
314 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
315 After the script runs, your current working directory
316 is set to the <filename>build</filename> directory.
317 </para></listitem>
318 </orderedlist>
319 </para>
320</section>
321
322<section id="bsp-filelayout">
323 <title>Example Filesystem Layout</title>
324
325 <para>
326 Defining a common BSP directory structure allows
327 end-users to understand and become familiar with
328 that standard.
329 A common format also encourages standardization
330 of software support for hardware.
331 </para>
332
333 <para>
334 The proposed form described in this section does
335 have elements that are specific to the OpenEmbedded
336 build system.
337 It is intended that developers can use this structure
338 with other build systems besides the OpenEmbedded build
339 system.
340 It is also intended that it will be be simple to extract
341 information and convert it to other formats if required.
342 The OpenEmbedded build system, through its standard
343 <ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
344 can directly accept the format described as a layer.
345 The BSP layer captures all the hardware-specific details
346 in one place using a standard format, which is useful
347 for any person wishing to use the hardware platform
348 regardless of the build system they are using.
349 </para>
350
351 <para>
352 The BSP specification does not include a build system
353 or other tools - the specification is concerned with
354 the hardware-specific components only.
355 At the end-distribution point, you can ship the BSP
356 layer combined with a build system and other tools.
357 Realize that it is important to maintain the distinction
358 that the BSP layer, a build system, and tools are
359 separate components that could to be combined in
360 certain end products.
361 </para>
362
363 <para>
364 Before looking at the common form for the file structure
365 inside a BSP Layer, you should be aware that some
366 requirements do exist in order for a BSP layer to
367 be considered compliant with the Yocto Project.
368 For that list of requirements, see the
369 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
370 section.
371 </para>
372
373 <para>
374 Below is the common form for the file structure
375 inside a BSP Layer.
376 While this basic form represents the standard,
377 realize that the actual file structures for specific
378 BSPs could differ.
379 <literallayout class='monospaced'>
380 meta-<replaceable>bsp_root_name</replaceable>/
381 meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
382 meta-<replaceable>bsp_root_name</replaceable>/README
383 meta-<replaceable>bsp_root_name</replaceable>/README.sources
384 meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
385 meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
386 meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
387 meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
388 meta-<replaceable>bsp_root_name</replaceable>/recipes-core/*
389 meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
390 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
391 </literallayout>
392 </para>
393
394 <para>
395 Below is an example of the Raspberry Pi BSP
396 layer that is available from the
397 <ulink url='&YOCTO_GIT_URL;'>Source Respositories</ulink>:
398 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500399 meta-raspberrypi/COPYING.MIT
Brad Bishop316dfdd2018-06-25 12:45:53 -0400400 meta-raspberrypi/README.md
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500401 meta-raspberrypi/classes
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500402 meta-raspberrypi/classes/sdcard_image-rpi.bbclass
403 meta-raspberrypi/conf/
404 meta-raspberrypi/conf/layer.conf
405 meta-raspberrypi/conf/machine/
Brad Bishop316dfdd2018-06-25 12:45:53 -0400406 meta-raspberrypi/conf/machine/raspberrypi-cm.conf
407 meta-raspberrypi/conf/machine/raspberrypi-cm3.conf
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500408 meta-raspberrypi/conf/machine/raspberrypi.conf
Brad Bishop316dfdd2018-06-25 12:45:53 -0400409 meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500410 meta-raspberrypi/conf/machine/raspberrypi0.conf
411 meta-raspberrypi/conf/machine/raspberrypi2.conf
Brad Bishop316dfdd2018-06-25 12:45:53 -0400412 meta-raspberrypi/conf/machine/raspberrypi3-64.conf
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500413 meta-raspberrypi/conf/machine/raspberrypi3.conf
414 meta-raspberrypi/conf/machine/include
415 meta-raspberrypi/conf/machine/include/rpi-base.inc
416 meta-raspberrypi/conf/machine/include/rpi-default-providers.inc
417 meta-raspberrypi/conf/machine/include/rpi-default-settings.inc
418 meta-raspberrypi/conf/machine/include/rpi-default-versions.inc
Brad Bishop316dfdd2018-06-25 12:45:53 -0400419 meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc
420 meta-raspberrypi/docs
421 meta-raspberrypi/docs/Makefile
422 meta-raspberrypi/docs/conf.py
423 meta-raspberrypi/docs/contributing.md
424 meta-raspberrypi/docs/extra-apps.md
425 meta-raspberrypi/docs/extra-build-config.md
426 meta-raspberrypi/docs/index.rst
427 meta-raspberrypi/docs/layer-contents.md
428 meta-raspberrypi/docs/readme.md
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500429 meta-raspberrypi/files
430 meta-raspberrypi/files/custom-licenses
431 meta-raspberrypi/files/custom-licenses/Broadcom
432 meta-raspberrypi/recipes-bsp
433 meta-raspberrypi/recipes-bsp/bootfiles
434 meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb
435 meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb
436 meta-raspberrypi/recipes-bsp/common
437 meta-raspberrypi/recipes-bsp/common/firmware.inc
Brad Bishop316dfdd2018-06-25 12:45:53 -0400438 meta-raspberrypi/recipes-bsp/formfactor
439 meta-raspberrypi/recipes-bsp/formfactor/formfactor
440 meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi
441 meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig
442 meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend
443 meta-raspberrypi/recipes-bsp/rpi-u-boot-src
444 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files
445 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in
446 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb
447 meta-raspberrypi/recipes-bsp/u-boot
448 meta-raspberrypi/recipes-bsp/u-boot/u-boot
449 meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch
450 meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend
451 meta-raspberrypi/recipes-connectivity
452 meta-raspberrypi/recipes-connectivity/bluez5
453 meta-raspberrypi/recipes-connectivity/bluez5/bluez5
454 meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch
455 meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd
456 meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service
457 meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500458 meta-raspberrypi/recipes-core
459 meta-raspberrypi/recipes-core/images
460 meta-raspberrypi/recipes-core/images/rpi-basic-image.bb
461 meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb
462 meta-raspberrypi/recipes-core/images/rpi-test-image.bb
463 meta-raspberrypi/recipes-core/packagegroups
464 meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb
465 meta-raspberrypi/recipes-core/psplash
466 meta-raspberrypi/recipes-core/psplash/files
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500467 meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h
Brad Bishop316dfdd2018-06-25 12:45:53 -0400468 meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
469 meta-raspberrypi/recipes-core/udev
470 meta-raspberrypi/recipes-core/udev/udev-rules-rpi
471 meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules
472 meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500473 meta-raspberrypi/recipes-devtools
474 meta-raspberrypi/recipes-devtools/bcm2835
Brad Bishop316dfdd2018-06-25 12:45:53 -0400475 meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500476 meta-raspberrypi/recipes-devtools/pi-blaster
477 meta-raspberrypi/recipes-devtools/pi-blaster/files
Brad Bishop316dfdd2018-06-25 12:45:53 -0400478 meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500479 meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb
480 meta-raspberrypi/recipes-devtools/python
481 meta-raspberrypi/recipes-devtools/python/python-rtimu
482 meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch
483 meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb
Brad Bishop316dfdd2018-06-25 12:45:53 -0400484 meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500485 meta-raspberrypi/recipes-devtools/python/rpi-gpio
486 meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch
Brad Bishop316dfdd2018-06-25 12:45:53 -0400487 meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500488 meta-raspberrypi/recipes-devtools/python/rpio
489 meta-raspberrypi/recipes-devtools/python/rpio/*.patch
490 meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb
491 meta-raspberrypi/recipes-devtools/wiringPi
492 meta-raspberrypi/recipes-devtools/wiringPi/files
493 meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500494 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb
495 meta-raspberrypi/recipes-graphics
496 meta-raspberrypi/recipes-graphics/eglinfo
497 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend
498 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend
Brad Bishop316dfdd2018-06-25 12:45:53 -0400499 meta-raspberrypi/recipes-graphics/mesa
500 meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend
501 meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500502 meta-raspberrypi/recipes-graphics/userland
503 meta-raspberrypi/recipes-graphics/userland/userland
504 meta-raspberrypi/recipes-graphics/userland/userland/*.patch
505 meta-raspberrypi/recipes-graphics/userland/userland_git.bb
506 meta-raspberrypi/recipes-graphics/vc-graphics
507 meta-raspberrypi/recipes-graphics/vc-graphics/files
508 meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc
509 meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh
510 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb
511 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb
512 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc
513 meta-raspberrypi/recipes-graphics/wayland
514 meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500515 meta-raspberrypi/recipes-graphics/xorg-xserver
516 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config
517 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi
518 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf
519 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d
520 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf
Brad Bishop316dfdd2018-06-25 12:45:53 -0400521 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf
522 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500523 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
Brad Bishop316dfdd2018-06-25 12:45:53 -0400524 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500525 meta-raspberrypi/recipes-kernel
526 meta-raspberrypi/recipes-kernel/linux-firmware
Brad Bishop316dfdd2018-06-25 12:45:53 -0400527 meta-raspberrypi/recipes-kernel/linux-firmware/files
528 meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin
529 meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt
530 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500531 meta-raspberrypi/recipes-kernel/linux
Brad Bishop316dfdd2018-06-25 12:45:53 -0400532 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500533 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc
Brad Bishop316dfdd2018-06-25 12:45:53 -0400534 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb
535 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500536 meta-raspberrypi/recipes-multimedia
537 meta-raspberrypi/recipes-multimedia/gstreamer
538 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx
539 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch
540 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend
541 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend
Brad Bishop316dfdd2018-06-25 12:45:53 -0400542 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12
543 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500544 meta-raspberrypi/recipes-multimedia/omxplayer
545 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer
546 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch
547 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb
Brad Bishop316dfdd2018-06-25 12:45:53 -0400548 meta-raspberrypi/recipes-multimedia/x264
549 meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend
550 meta-raspberrypi/wic
551 meta-raspberrypi/wic/sdimage-raspberrypi.wks
552 </literallayout>
553 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500554
Brad Bishop316dfdd2018-06-25 12:45:53 -0400555 <para>
556 The following sections describe each part of the proposed
557 BSP format.
558 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500559
Brad Bishop316dfdd2018-06-25 12:45:53 -0400560 <section id="bsp-filelayout-license">
561 <title>License Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500562
Brad Bishop316dfdd2018-06-25 12:45:53 -0400563 <para>
564 You can find these files in the BSP Layer at:
565 <literallayout class='monospaced'>
566 meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
567 </literallayout>
568 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500569
Brad Bishop316dfdd2018-06-25 12:45:53 -0400570 <para>
571 These optional files satisfy licensing requirements
572 for the BSP.
573 The type or types of files here can vary depending
574 on the licensing requirements.
575 For example, in the Raspberry Pi BSP all licensing
576 requirements are handled with the
577 <filename>COPYING.MIT</filename> file.
578 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500579
Brad Bishop316dfdd2018-06-25 12:45:53 -0400580 <para>
581 Licensing files can be MIT, BSD, GPLv*, and so forth.
582 These files are recommended for the BSP but are
583 optional and totally up to the BSP developer.
584 For information on how to maintain license
585 compliance, see the
586 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
587 section in the Yocto Project Development Tasks
588 Manual.
589 </para>
590 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500591
Brad Bishop316dfdd2018-06-25 12:45:53 -0400592 <section id="bsp-filelayout-readme">
593 <title>README File</title>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500594
Brad Bishop316dfdd2018-06-25 12:45:53 -0400595 <para>
596 You can find this file in the BSP Layer at:
597 <literallayout class='monospaced'>
598 meta-<replaceable>bsp_root_name</replaceable>/README
599 </literallayout>
600 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500601
Brad Bishop316dfdd2018-06-25 12:45:53 -0400602 <para>
603 This file provides information on how to boot the live
604 images that are optionally included in the
605 <filename>binary/</filename> directory.
606 The <filename>README</filename> file also provides
607 information needed for building the image.
608 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500609
Brad Bishop316dfdd2018-06-25 12:45:53 -0400610 <para>
611 At a minimum, the <filename>README</filename> file must
612 contain a list of dependencies, such as the names of
613 any other layers on which the BSP depends and the name of
614 the BSP maintainer with his or her contact information.
615 </para>
616 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500617
Brad Bishop316dfdd2018-06-25 12:45:53 -0400618 <section id="bsp-filelayout-readme-sources">
619 <title>README.sources File</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500620
Brad Bishop316dfdd2018-06-25 12:45:53 -0400621 <para>
622 You can find this file in the BSP Layer at:
623 <literallayout class='monospaced'>
624 meta-<replaceable>bsp_root_name</replaceable>/README.sources
625 </literallayout>
626 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500627
Brad Bishop316dfdd2018-06-25 12:45:53 -0400628 <para>
629 This file provides information on where to locate the BSP
630 source files used to build the images (if any) that
631 reside in
632 <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>.
633 Images in the <filename>binary</filename> would be images
634 released with the BSP.
635 The information in the <filename>README.sources</filename>
636 file also helps you find the
637 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
638 used to generate the images that ship with the BSP.
639 <note>
640 If the BSP's <filename>binary</filename> directory is
641 missing or the directory has no images, an existing
642 <filename>README.sources</filename> file is
643 meaningless and usually does not exist.
644 </note>
645 </para>
646 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500647
Brad Bishop316dfdd2018-06-25 12:45:53 -0400648 <section id="bsp-filelayout-binary">
649 <title>Pre-built User Binaries</title>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500650
Brad Bishop316dfdd2018-06-25 12:45:53 -0400651 <para>
652 You can find these files in the BSP Layer at:
653 <literallayout class='monospaced'>
654 meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
655 </literallayout>
656 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500657
Brad Bishop316dfdd2018-06-25 12:45:53 -0400658 <para>
659 This optional area contains useful pre-built kernels
660 and user-space filesystem images released with the
661 BSP that are appropriate to the target system.
662 This directory typically contains graphical (e.g. Sato)
663 and minimal live images when the BSP tarball has been
664 created and made available in the
665 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
666 website.
667 You can use these kernels and images to get a system
668 running and quickly get started on development tasks.
669 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500670
Brad Bishop316dfdd2018-06-25 12:45:53 -0400671 <para>
672 The exact types of binaries present are highly
673 hardware-dependent.
674 The
675 <link linkend='bsp-filelayout-readme'><filename>README</filename></link>
676 file should be present in the BSP Layer and it
677 explains how to use the images with the target hardware.
678 Additionally, the
679 <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link>
680 file should be present to locate the sources used to
681 build the images and provide information on the
682 Metadata.
683 </para>
684 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500685
Brad Bishop316dfdd2018-06-25 12:45:53 -0400686 <section id='bsp-filelayout-layer'>
687 <title>Layer Configuration File</title>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500688
Brad Bishop316dfdd2018-06-25 12:45:53 -0400689 <para>
690 You can find this file in the BSP Layer at:
691 <literallayout class='monospaced'>
692 meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
693 </literallayout>
694 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500695
Brad Bishop316dfdd2018-06-25 12:45:53 -0400696 <para>
697 The <filename>conf/layer.conf</filename> file
698 identifies the file structure as a layer,
699 identifies the contents of the layer, and
700 contains information about how the build system should
701 use it.
702 Generally, a standard boilerplate file such as the
703 following works.
704 In the following example, you would replace
705 <replaceable>bsp</replaceable> with the actual
706 name of the BSP (i.e.
707 <replaceable>bsp_root_name</replaceable> from the example
708 template).
709 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500710
Brad Bishop316dfdd2018-06-25 12:45:53 -0400711 <para>
712 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500713 # We have a conf and classes directory, add to BBPATH
714 BBPATH .= ":${LAYERDIR}"
715
716 # We have a recipes directory, add to BBFILES
717 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500718 ${LAYERDIR}/recipes-*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500719
720 BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>"
721 BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/"
722 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
723
724 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400725 </literallayout>
726 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500727
Brad Bishop316dfdd2018-06-25 12:45:53 -0400728 <para>
729 To illustrate the string substitutions, here are
730 the corresponding statements from the Raspberry
731 Pi <filename>conf/layer.conf</filename> file:
732 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500733 # We have a conf and classes directory, append to BBPATH
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500734 BBPATH .= ":${LAYERDIR}"
735
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500736 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
737 BBFILES += "${LAYERDIR}/recipes*/*/*.bb \
738 ${LAYERDIR}/recipes*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500739
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500740 BBFILE_COLLECTIONS += "raspberrypi"
741 BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/"
742 BBFILE_PRIORITY_raspberrypi = "9"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500743
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500744 # Additional license directories.
745 LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400746 .
747 .
748 .
749 </literallayout>
750 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500751
Brad Bishop316dfdd2018-06-25 12:45:53 -0400752 <para>
753 This file simply makes
754 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
755 aware of the recipes and configuration directories.
756 The file must exist so that the OpenEmbedded build system
757 can recognize the BSP.
758 </para>
759 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500760
Brad Bishop316dfdd2018-06-25 12:45:53 -0400761 <section id="bsp-filelayout-machine">
762 <title>Hardware Configuration Options</title>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500763
Brad Bishop316dfdd2018-06-25 12:45:53 -0400764 <para>
765 You can find these files in the BSP Layer at:
766 <literallayout class='monospaced'>
767 meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
768 </literallayout>
769 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500770
Brad Bishop316dfdd2018-06-25 12:45:53 -0400771 <para>
772 The machine files bind together all the information
773 contained elsewhere in the BSP into a format that
774 the build system can understand.
775 Each BSP Layer requires at least one machine file.
776 If the BSP supports multiple machines, multiple
777 machine configuration files can exist.
778 These filenames correspond to the values to which
779 users have set the
780 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
781 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500782
Brad Bishop316dfdd2018-06-25 12:45:53 -0400783 <para>
784 These files define things such as the kernel package
785 to use
786 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
787 of
788 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>),
789 the hardware drivers to include in different types
790 of images, any special software components that are
791 needed, any bootloader information, and also any
792 special image format requirements.
793 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500794
Brad Bishop316dfdd2018-06-25 12:45:53 -0400795 <para>
796 This configuration file could also include a hardware
797 "tuning" file that is commonly used to define the
798 package architecture and specify optimization flags,
799 which are carefully chosen to give best performance
800 on a given processor.
801 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500802
Brad Bishop316dfdd2018-06-25 12:45:53 -0400803 <para>
804 Tuning files are found in the
805 <filename>meta/conf/machine/include</filename>
806 directory within the
807 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
808 For example, many <filename>tune-*</filename> files
809 (e.g. <filename>tune-arm1136jf-s.inc</filename>,
810 <filename>tun-1586-nlp.inc</filename>, and so forth)
811 reside in the
812 <filename>poky/meta/conf/machine/include</filename>
813 directory.
814 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500815
Brad Bishop316dfdd2018-06-25 12:45:53 -0400816 <para>
817 To use an include file, you simply include them in the
818 machine configuration file.
819 For example, the Raspberry Pi BSP
820 <filename>raspberrypi3.conf</filename> contains the
821 following statement:
822 <literallayout class='monospaced'>
823 include conf/machine/include/rpi-base.inc
824 </literallayout>
825 </para>
826 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500827
Brad Bishop316dfdd2018-06-25 12:45:53 -0400828 <section id='bsp-filelayout-misc-recipes'>
829 <title>Miscellaneous BSP-Specific Recipe Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500830
Brad Bishop316dfdd2018-06-25 12:45:53 -0400831 <para>
832 You can find these files in the BSP Layer at:
833 <literallayout class='monospaced'>
834 meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
835 </literallayout>
836 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500837
Brad Bishop316dfdd2018-06-25 12:45:53 -0400838 <para>
839 This optional directory contains miscellaneous recipe
840 files for the BSP.
841 Most notably would be the formfactor files.
842 For example, in the Raspberry Pi BSP there is the
843 <filename>formfactor_0.0.bbappend</filename> file,
844 which is an append file used to augment the recipe
845 that starts the build.
846 Furthermore, there are machine-specific settings used
847 during the build that are defined by the
848 <filename>machconfig</filename> file further down in
849 the directory.
850 Here is the <filename>machconfig</filename> file for
851 the Raspberry Pi BSP:
852 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500853 HAVE_TOUCHSCREEN=0
854 HAVE_KEYBOARD=1
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500855
856 DISPLAY_CAN_ROTATE=0
857 DISPLAY_ORIENTATION=0
858 DISPLAY_DPI=133
Brad Bishop316dfdd2018-06-25 12:45:53 -0400859 </literallayout>
860 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500861
Brad Bishop316dfdd2018-06-25 12:45:53 -0400862 <note><para>
863 If a BSP does not have a formfactor entry, defaults
864 are established according to the formfactor
865 configuration file that is installed by the main
866 formfactor recipe
867 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
868 which is found in the
869 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
870 </para></note>
871 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500872
Brad Bishop316dfdd2018-06-25 12:45:53 -0400873 <section id='bsp-filelayout-recipes-graphics'>
874 <title>Display Support Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500875
Brad Bishop316dfdd2018-06-25 12:45:53 -0400876 <para>
877 You can find these files in the BSP Layer at:
878 <literallayout class='monospaced'>
879 meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
880 </literallayout>
881 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500882
Brad Bishop316dfdd2018-06-25 12:45:53 -0400883 <para>
884 This optional directory contains recipes for the
885 BSP if it has special requirements for graphics
886 support.
887 All files that are needed for the BSP to support
888 a display are kept here.
889 </para>
890 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500891
Brad Bishop316dfdd2018-06-25 12:45:53 -0400892 <section id='bsp-filelayout-kernel'>
893 <title>Linux Kernel Configuration</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500894
Brad Bishop316dfdd2018-06-25 12:45:53 -0400895 <para>
896 You can find these files in the BSP Layer at:
897 <literallayout class='monospaced'>
898 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend
899 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb
900 </literallayout>
901 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500902
Brad Bishop316dfdd2018-06-25 12:45:53 -0400903 <para>
904 Append files (<filename>*.bbappend</filename>) modify
905 the main kernel recipe being used to build the image.
906 The <filename>*.bb</filename> files would be a
907 developer-supplied kernel recipe.
908 This area of the BSP hierarchy can contain both these
909 types of files, although in practice, it is likely that
910 you would have one or the other.
911 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500912
Brad Bishop316dfdd2018-06-25 12:45:53 -0400913 <para>
914 For your BSP, you typically want to use an existing Yocto
915 Project kernel recipe found in the
916 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
917 at <filename>meta/recipes-kernel/linux</filename>.
918 You can append machine-specific changes to the
919 kernel recipe by using a similarly named append
920 file, which is located in the BSP Layer for your
921 target device (e.g. the
922 <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory).
923 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500924
Brad Bishop316dfdd2018-06-25 12:45:53 -0400925 <para>
926 Suppose you are using the
927 <filename>linux-yocto_4.4.bb</filename> recipe to
928 build the kernel.
929 In other words, you have selected the kernel in your
930 <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
931 file by adding
932 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
933 and
934 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
935 statements as follows:
936 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500937 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500938 PREFERRED_VERSION_linux-yocto ?= "4.4%"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400939 </literallayout>
940 <note>
941 When the preferred provider is assumed by
942 default, the
943 <filename>PREFERRED_PROVIDER</filename>
944 statement does not appear in the
945 <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file.
946 </note>
947 You would use the
948 <filename>linux-yocto_4.4.bbappend</filename>
949 file to append specific BSP settings to the kernel,
950 thus configuring the kernel for your particular BSP.
951 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500952
Brad Bishop316dfdd2018-06-25 12:45:53 -0400953 <para>
954 You can find more information on what your append file
955 should contain in the
956 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file'>Creating the Append File</ulink>"
957 section in the Yocto Project Linux Kernel Development
958 Manual.
959 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500960
Brad Bishop316dfdd2018-06-25 12:45:53 -0400961 <para>
962 An alternate scenario is when you create your own
963 kernel recipe for the BSP.
964 A good example of this is the Raspberry Pi BSP.
965 If you examine the
966 <filename>recipes-kernel/linux</filename> directory
967 you see the following:
968 <literallayout class='monospaced'>
969 linux-raspberrypi-dev.bb
970 linux-raspberrypi.inc
971 linux-raspberrypi_4.14.bb
972 linux-raspberrypi_4.9.bb
973 </literallayout>
974 The directory contains three kernel recipes and a
975 common include file.
976 </para>
977 </section>
978</section>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500979
Brad Bishop316dfdd2018-06-25 12:45:53 -0400980<section id='developing-a-board-support-package-bsp'>
981 <title>Developing a Board Support Package (BSP)</title>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500982
Brad Bishop316dfdd2018-06-25 12:45:53 -0400983 <para>
984 This section contains the high-level procedure you can
985 follow to create a BSP.
986 Although not required for BSP creation, the
987 <filename>meta-intel</filename> repository, which
988 contains many BSPs supported by the Yocto Project,
989 is part of the example.
990 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500991
Brad Bishop316dfdd2018-06-25 12:45:53 -0400992 <para>
993 For an example that shows how to create a new
994 layer using the tools, see the
995 "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
996 section.
997 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500998
Brad Bishop316dfdd2018-06-25 12:45:53 -0400999 <para>
1000 The following illustration and list summarize the BSP
1001 creation general workflow.
1002 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001003
Brad Bishop316dfdd2018-06-25 12:45:53 -04001004 <para>
1005 <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
1006 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001007
Brad Bishop316dfdd2018-06-25 12:45:53 -04001008 <para>
1009 <orderedlist>
1010 <listitem><para>
1011 <emphasis>Set up Your Host Development System
1012 to Support Development Using the Yocto
1013 Project</emphasis>:
1014 See the
1015 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
1016 section in the Yocto Project Development Tasks
1017 Manual for options on how to get a system ready
1018 to use the Yocto Project.
1019 </para></listitem>
1020 <listitem><para>
1021 <emphasis>Establish the
1022 <filename>meta-intel</filename>
1023 Repository on Your System:</emphasis>
1024 Having local copies of these supported BSP layers
1025 on your system gives you access to layers you
1026 might be able to leverage when creating your BSP.
1027 For information on how to get these files, see the
1028 "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
1029 section.
1030 </para></listitem>
1031 <listitem><para>
1032 <emphasis>Create Your Own BSP Layer Using the
1033 <filename>bitbake-layers</filename>
1034 Script:</emphasis>
1035 Layers are ideal for isolating and storing work
1036 for a given piece of hardware.
1037 A layer is really just a location or area in which you
1038 place the recipes and configurations for your BSP.
1039 In fact, a BSP is, in itself, a special type of layer.
1040 The simplest way to create a new BSP layer that is
1041 compliant with the Yocto Project is to use the
1042 <filename>bitbake-layers</filename> script.
1043 For information about that script, see the
1044 "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
1045 section.</para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001046
Brad Bishop316dfdd2018-06-25 12:45:53 -04001047 <para>Another example that illustrates a layer
1048 is an application.
1049 Suppose you are creating an application that has
1050 library or other dependencies in order for it to
1051 compile and run.
1052 The layer, in this case, would be where all the
1053 recipes that define those dependencies are kept.
1054 The key point for a layer is that it is an
1055 isolated area that contains all the relevant
1056 information for the project that the
1057 OpenEmbedded build system knows about.
1058 For more information on layers, see the
1059 "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
1060 section in the Yocto Project Overview and Concepts
1061 Manual.
1062 You can also reference the
1063 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1064 section in the Yocto Project Development Tasks
1065 Manual.
1066 For more information on BSP layers, see the
1067 "<link linkend='bsp-layers'>BSP Layers</link>"
1068 section.
1069 <note><title>Notes</title>
1070 <itemizedlist>
1071 <listitem><para>
1072 Five hardware reference BSPs exist
1073 that are part of the Yocto Project release
1074 and are located in the
1075 <filename>poky/meta-yocto-bsp</filename> BSP
1076 layer:
1077 <itemizedlist>
1078 <listitem><para>
1079 Texas Instruments Beaglebone
1080 (<filename>beaglebone-yocto</filename>)
1081 </para></listitem>
1082 <listitem><para>
1083 Freescale MPC8315E-RDB
1084 (<filename>mpc8315e-rdb</filename>)
1085 </para></listitem>
1086 <listitem><para>
1087 Ubiquiti Networks EdgeRouter Lite
1088 (<filename>edgerouter</filename>)
1089 </para></listitem>
1090 <listitem><para>
1091 Two general IA platforms
1092 (<filename>genericx86</filename> and
1093 <filename>genericx86-64</filename>)
1094 </para></listitem>
1095 </itemizedlist>
1096 </para></listitem>
1097 <listitem><para>
1098 Three core Intel BSPs exist as part of
1099 the Yocto Project release in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001100 <filename>meta-intel</filename> layer:
1101 <itemizedlist>
1102 <listitem><para>
1103 <filename>intel-core2-32</filename>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04001104 which is a BSP optimized for the Core2
1105 family of CPUs as well as all CPUs
1106 prior to the Silvermont core.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001107 </para></listitem>
1108 <listitem><para>
1109 <filename>intel-corei7-64</filename>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04001110 which is a BSP optimized for Nehalem
1111 and later Core and Xeon CPUs as well
1112 as Silvermont and later Atom CPUs,
1113 such as the Baytrail SoCs.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001114 </para></listitem>
1115 <listitem><para>
1116 <filename>intel-quark</filename>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04001117 which is a BSP optimized for the
1118 Intel Galileo gen1 &amp; gen2
1119 development boards.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001120 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001121 </itemizedlist>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001122 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001123 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001124 </note></para>
1125
1126 <para>When you set up a layer for a new BSP,
1127 you should follow a standard layout.
1128 This layout is described in the
1129 "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
1130 section.
1131 In the standard layout, notice the suggested
1132 structure for recipes and configuration
1133 information.
1134 You can see the standard layout for a BSP
1135 by examining any supported BSP found in the
1136 <filename>meta-intel</filename> layer inside
1137 the Source Directory.
1138 </para></listitem>
1139 <listitem><para>
1140 <emphasis>Make Configuration Changes to Your New
1141 BSP Layer:</emphasis>
1142 The standard BSP layer structure organizes the
1143 files you need to edit in
1144 <filename>conf</filename> and several
1145 <filename>recipes-*</filename> directories
1146 within the BSP layer.
1147 Configuration changes identify where your new
1148 layer is on the local system and identifies the
1149 kernel you are going to use.
1150 When you run the
1151 <filename>bitbake-layers</filename> script,
1152 you are able to interactively configure many
1153 things for the BSP (e.g. keyboard, touchscreen,
1154 and so forth).
1155 </para></listitem>
1156 <listitem><para>
1157 <emphasis>Make Recipe Changes to Your New BSP
1158 Layer:</emphasis>
1159 Recipe changes include altering recipes
1160 (<filename>*.bb</filename> files), removing
1161 recipes you do not use, and adding new recipes
1162 or append files (<filename>.bbappend</filename>)
1163 that support your hardware.
1164 </para></listitem>
1165 <listitem><para>
1166 <emphasis>Prepare for the Build:</emphasis>
1167 Once you have made all the changes to your BSP
1168 layer, there remains a few things you need to
1169 do for the OpenEmbedded build system in order
1170 for it to create your image.
1171 You need to get the build environment ready by
1172 sourcing an environment setup script
1173 (i.e. <filename>oe-init-build-env</filename>)
1174 and you need to be sure two key configuration
1175 files are configured appropriately: the
1176 <filename>conf/local.conf</filename> and the
1177 <filename>conf/bblayers.conf</filename> file.
1178 You must make the OpenEmbedded build system aware
1179 of your new layer.
1180 See the
1181 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1182 section in the Yocto Project Development Tasks Manual
1183 for information on how to let the build system
1184 know about your new layer.
1185 </para></listitem>
1186 <listitem><para>
1187 <emphasis>Build the Image:</emphasis>
1188 The OpenEmbedded build system uses the BitBake tool
1189 to build images based on the type of image you want to
1190 create.
1191 You can find more information about BitBake in the
1192 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001193 </para>
1194
Brad Bishop316dfdd2018-06-25 12:45:53 -04001195 <para>The build process supports several types of
1196 images to satisfy different needs.
1197 See the
1198 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1199 chapter in the Yocto Project Reference Manual for
1200 information on supported images.
1201 </para></listitem>
1202 </orderedlist>
1203 </para>
1204</section>
1205
1206<section id='requirements-and-recommendations-for-released-bsps'>
1207 <title>Requirements and Recommendations for Released BSPs</title>
1208
1209 <para>
1210 Certain requirements exist for a released BSP to be
1211 considered compliant with the Yocto Project.
1212 Additionally, recommendations also exist.
1213 This section describes the requirements and
1214 recommendations for released BSPs.
1215 </para>
1216
1217 <section id='released-bsp-requirements'>
1218 <title>Released BSP Requirements</title>
1219
1220 <para>
1221 Before looking at BSP requirements, you should consider
1222 the following:
1223 <itemizedlist>
1224 <listitem><para>
1225 The requirements here assume the BSP layer
1226 is a well-formed, "legal" layer that can be
1227 added to the Yocto Project.
1228 For guidelines on creating a layer that meets
1229 these base requirements, see the
1230 "<link linkend='bsp-layers'>BSP Layers</link>"
1231 section in this manual and the
1232 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>"
1233 section in the Yocto Project Development Tasks
1234 Manual.
1235 </para></listitem>
1236 <listitem><para>
1237 The requirements in this section apply
1238 regardless of how you package a BSP.
1239 You should consult the packaging and distribution
1240 guidelines for your specific release process.
1241 For an example of packaging and distribution
1242 requirements, see the
1243 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
1244 wiki page.
1245 </para></listitem>
1246 <listitem><para>
1247 The requirements for the BSP as it is made
1248 available to a developer are completely
1249 independent of the released form of the BSP.
1250 For example, the BSP Metadata can be contained
1251 within a Git repository and could have a directory
1252 structure completely different from what appears
1253 in the officially released BSP layer.
1254 </para></listitem>
1255 <listitem><para>
1256 It is not required that specific packages or
1257 package modifications exist in the BSP layer,
1258 beyond the requirements for general
1259 compliance with the Yocto Project.
1260 For example, no requirement exists dictating
1261 that a specific kernel or kernel version be
1262 used in a given BSP.
1263 </para></listitem>
1264 </itemizedlist>
1265 </para>
1266
1267 <para>
1268 Following are the requirements for a released BSP
1269 that conform to the Yocto Project:
1270 <itemizedlist>
1271 <listitem><para>
1272 <emphasis>Layer Name:</emphasis>
1273 The BSP must have a layer name that follows
1274 the Yocto Project standards.
1275 For information on BSP layer names, see the
1276 "<link linkend='bsp-layers'>BSP Layers</link>" section.
1277 </para></listitem>
1278 <listitem><para>
1279 <emphasis>File System Layout:</emphasis>
1280 When possible, use the same directory names
1281 in your BSP layer as listed in the
1282 <filename>recipes.txt</filename> file, which
1283 is found in <filename>poky/meta</filename>
1284 directory of the
1285 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1286 or in the OpenEmbedded-Core Layer
1287 (<filename>openembedded-core</filename>) at
1288 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
1289 </para>
1290
1291 <para>You should place recipes
1292 (<filename>*.bb</filename> files) and recipe
1293 modifications (<filename>*.bbappend</filename>
1294 files) into <filename>recipes-*</filename>
1295 subdirectories by functional area as outlined
1296 in <filename>recipes.txt</filename>.
1297 If you cannot find a category in
1298 <filename>recipes.txt</filename> to fit a
1299 particular recipe, you can make up your own
1300 <filename>recipes-*</filename> subdirectory.
1301 </para>
1302
1303 <para>Within any particular
1304 <filename>recipes-*</filename> category, the
1305 layout should match what is found in the
1306 OpenEmbedded-Core Git repository
1307 (<filename>openembedded-core</filename>)
1308 or the Source Directory (<filename>poky</filename>).
1309 In other words, make sure you place related
1310 files in appropriately related
1311 <filename>recipes-*</filename> subdirectories
1312 specific to the recipe's function, or within
1313 a subdirectory containing a set of closely-related
1314 recipes.
1315 The recipes themselves should follow the general
1316 guidelines for recipes used in the Yocto Project
1317 found in the
1318 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
1319 </para></listitem>
1320 <listitem><para>
1321 <emphasis>License File:</emphasis>
1322 You must include a license file in the
1323 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1324 directory.
1325 This license covers the BSP Metadata as a whole.
1326 You must specify which license to use since no
1327 default license exists when one not specified.
1328 See the
1329 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
1330 file for the Raspberry Pi BSP in the
1331 <filename>meta-raspberrypi</filename> BSP layer
1332 as an example.
1333 </para></listitem>
1334 <listitem><para>
1335 <emphasis>README File:</emphasis>
1336 You must include a <filename>README</filename>
1337 file in the
1338 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1339 directory.
1340 See the
1341 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md'><filename>README.md</filename></ulink>
1342 file for the Raspberry Pi BSP in the
1343 <filename>meta-raspberrypi</filename> BSP layer
1344 as an example.</para>
1345
1346 <para>At a minimum, the <filename>README</filename>
1347 file should contain the following:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001348 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001349 <listitem><para>
1350 A brief description about the hardware the BSP
1351 targets.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001352 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001353 <listitem><para>
1354 A list of all the dependencies
1355 on which a BSP layer depends.
1356 These dependencies are typically a list
1357 of required layers needed to build the
1358 BSP.
1359 However, the dependencies should also
1360 contain information regarding any other
1361 dependencies the BSP might have.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001362 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001363 <listitem><para>
1364 Any required special licensing information.
1365 For example, this information includes
1366 information on special variables needed
1367 to satisfy a EULA, or instructions on
1368 information needed to build or distribute
1369 binaries built from the BSP Metadata.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001370 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001371 <listitem><para>
1372 The name and contact information for the
1373 BSP layer maintainer.
1374 This is the person to whom patches and
1375 questions should be sent.
1376 For information on how to find the right
1377 person, see the
1378 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
1379 section in the Yocto Project Development
1380 Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001381 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001382 <listitem><para>
1383 Instructions on how to build the BSP using
1384 the BSP layer.
1385 </para></listitem>
1386 <listitem><para>
1387 Instructions on how to boot the BSP build
1388 from the BSP layer.
1389 </para></listitem>
1390 <listitem><para>
1391 Instructions on how to boot the binary
1392 images contained in the
1393 <filename>binary</filename> directory,
1394 if present.
1395 </para></listitem>
1396 <listitem><para>
1397 Information on any known bugs or issues
1398 that users should know about when either
1399 building or booting the BSP binaries.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001400 </para></listitem>
1401 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001402 </para></listitem>
1403 <listitem><para>
1404 <emphasis>README.sources File:</emphasis>
1405 If you BSP contains binary images in the
1406 <filename>binary</filename> directory, you must
1407 include a <filename>README.sources</filename>
1408 file in the
1409 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1410 directory.
1411 This file specifies exactly where you can find
1412 the sources used to generate the binary images.
1413 </para></listitem>
1414 <listitem><para>
1415 <emphasis>Layer Configuration File:</emphasis>
1416 You must include a
1417 <filename>conf/layer.conf</filename> file in
1418 the
1419 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1420 directory.
1421 This file identifies the
1422 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1423 BSP layer as a layer to the build system.
1424 </para></listitem>
1425 <listitem><para>
1426 <emphasis>Machine Configuration File:</emphasis>
1427 You must include one or more
1428 <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1429 files in the
1430 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1431 directory.
1432 These configuration files define machine targets
1433 that can be built using the BSP layer.
1434 Multiple machine configuration files define
1435 variations of machine configurations that the
1436 BSP supports.
1437 If a BSP supports multiple machine variations,
1438 you need to adequately describe each variation
1439 in the BSP <filename>README</filename> file.
1440 Do not use multiple machine configuration files
1441 to describe disparate hardware.
1442 If you do have very different targets, you should
1443 create separate BSP layers for each target.
1444 <note>
1445 It is completely possible for a developer to
1446 structure the working repository as a
1447 conglomeration of unrelated BSP files, and to
1448 possibly generate BSPs targeted for release
1449 from that directory using scripts or some
1450 other mechanism
1451 (e.g. <filename>meta-yocto-bsp</filename> layer).
1452 Such considerations are outside the scope of
1453 this document.
1454 </note>
1455 </para></listitem>
1456 </itemizedlist>
1457 </para>
1458 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001459
Brad Bishop316dfdd2018-06-25 12:45:53 -04001460 <section id='released-bsp-recommendations'>
1461 <title>Released BSP Recommendations</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001462
Brad Bishop316dfdd2018-06-25 12:45:53 -04001463 <para>
1464 Following are recommendations for released BSPs that
1465 conform to the Yocto Project:
1466 <itemizedlist>
1467 <listitem><para>
1468 <emphasis>Bootable Images:</emphasis>
1469 Released BSPs can contain one or more bootable
1470 images.
1471 Including bootable images allows users to easily
1472 try out the BSP using their own hardware.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001473
Brad Bishop316dfdd2018-06-25 12:45:53 -04001474 <para>In some cases, it might not be convenient
1475 to include a bootable image.
1476 If so, you might want to make two versions of the
1477 BSP available: one that contains binary images, and
1478 one that does not.
1479 The version that does not contain bootable images
1480 avoids unnecessary download times for users not
1481 interested in the images.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001482
Brad Bishop316dfdd2018-06-25 12:45:53 -04001483 <para>If you need to distribute a BSP and include
1484 bootable images or build kernel and filesystems
1485 meant to allow users to boot the BSP for evaluation
1486 purposes, you should put the images and artifacts
1487 within a
1488 <filename>binary/</filename> subdirectory located
1489 in the
1490 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1491 directory.
1492 <note>
1493 If you do include a bootable image as part
1494 of the BSP and the image was built by software
1495 covered by the GPL or other open source licenses,
1496 it is your responsibility to understand
1497 and meet all licensing requirements, which could
1498 include distribution of source files.
1499 </note>
1500 </para></listitem>
1501 <listitem><para>
1502 <emphasis>Use a Yocto Linux Kernel:</emphasis>
1503 Kernel recipes in the BSP should be based on a
1504 Yocto Linux kernel.
1505 Basing your recipes on these kernels reduces
1506 the costs for maintaining the BSP and increases
1507 its scalability.
1508 See the <filename>Yocto Linux Kernel</filename>
1509 category in the
1510 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1511 for these kernels.
1512 </para></listitem>
1513 </itemizedlist>
1514 </para>
1515 </section>
1516</section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001517
Brad Bishop316dfdd2018-06-25 12:45:53 -04001518<section id='customizing-a-recipe-for-a-bsp'>
1519 <title>Customizing a Recipe for a BSP</title>
1520
1521 <para>
1522 If you plan on customizing a recipe for a particular BSP,
1523 you need to do the following:
1524 <itemizedlist>
1525 <listitem><para>
1526 Create a <filename>*.bbappend</filename> file for
1527 the modified recipe.
1528 For information on using append files, see the
1529 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
1530 section in the Yocto Project Development Tasks
1531 Manual.
1532 </para></listitem>
1533 <listitem><para>
1534 Ensure your directory structure in the BSP layer
1535 that supports your machine is such that the
1536 OpenEmbedded build system can find it.
1537 See the example later in this section for more
1538 information.
1539 </para></listitem>
1540 <listitem><para>
1541 Put the append file in a directory whose name matches
1542 the machine's name and is located in an appropriate
1543 sub-directory inside the BSP layer (i.e.
1544 <filename>recipes-bsp</filename>,
1545 <filename>recipes-graphics</filename>,
1546 <filename>recipes-core</filename>, and so forth).
1547 </para></listitem>
1548 <listitem><para>
1549 Place the BSP-specific files in the proper
1550 directory inside the BSP layer.
1551 How expansive the layer is affects where you must
1552 place these files.
1553 For example, if your layer supports several
1554 different machine types, you need to be sure your
1555 layer's directory structure includes hierarchy
1556 that separates the files according to machine.
1557 If your layer does not support multiple machines,
1558 the layer would not have that additional hierarchy
1559 and the files would obviously not be able to reside
1560 in a machine-specific directory.
1561 </para></listitem>
1562 </itemizedlist>
1563 </para>
1564
1565 <para>
1566 Following is a specific example to help you better understand
1567 the process.
1568 This example customizes customizes a recipe by adding a
1569 BSP-specific configuration file named
1570 <filename>interfaces</filename> to the
1571 <filename>init-ifupdown_1.0.bb</filename> recipe for machine
1572 "xyz" where the BSP layer also supports several other
1573 machines:
1574 <orderedlist>
1575 <listitem><para>
1576 Edit the
1577 <filename>init-ifupdown_1.0.bbappend</filename> file
1578 so that it contains the following:
1579 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001580 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
Brad Bishop316dfdd2018-06-25 12:45:53 -04001581 </literallayout>
1582 The append file needs to be in the
1583 <filename>meta-xyz/recipes-core/init-ifupdown</filename>
1584 directory.
1585 </para></listitem>
1586 <listitem><para>
1587 Create and place the new
1588 <filename>interfaces</filename> configuration file in
1589 the BSP's layer here:
1590 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001591 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
Brad Bishop316dfdd2018-06-25 12:45:53 -04001592 </literallayout>
1593 <note>
1594 If the <filename>meta-xyz</filename> layer did
1595 not support multiple machines, you would place
1596 the <filename>interfaces</filename> configuration
1597 file in the layer here:
1598 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001599 meta-xyz/recipes-core/init-ifupdown/files/interfaces
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001600 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001601 </note>
1602 The
1603 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1604 variable in the append files extends the search path
1605 the build system uses to find files during the build.
1606 Consequently, for this example you need to have the
1607 <filename>files</filename> directory in the same
1608 location as your append file.
1609 </para></listitem>
1610 </orderedlist>
1611 </para>
1612</section>
1613
1614<section id='bsp-licensing-considerations'>
1615 <title>BSP Licensing Considerations</title>
1616
1617 <para>
1618 In some cases, a BSP contains separately licensed
1619 Intellectual Property (IP) for a component or components.
1620 For these cases, you are required to accept the terms
1621 of a commercial or other type of license that requires
1622 some kind of explicit End User License Agreement (EULA).
1623 Once you accept the license, the OpenEmbedded build system
1624 can then build and include the corresponding component
1625 in the final BSP image.
1626 If the BSP is available as a pre-built image, you can
1627 download the image after agreeing to the license or EULA.
1628 </para>
1629
1630 <para>
1631 You could find that some separately licensed components
1632 that are essential for normal operation of the system might
1633 not have an unencumbered (or free) substitute.
1634 Without these essential components, the system would be
1635 non-functional.
1636 Then again, you might find that other licensed components
1637 that are simply 'good-to-have' or purely elective do have
1638 an unencumbered, free replacement component that you can
1639 use rather than agreeing to the separately licensed
1640 component.
1641 Even for components essential to the system, you might
1642 find an unencumbered component that is not identical but
1643 will work as a less-capable version of the licensed version
1644 in the BSP recipe.
1645 </para>
1646
1647 <para>
1648 For cases where you can substitute a free component and
1649 still maintain the system's functionality, the "DOWNLOADS"
1650 selection from the "SOFTWARE" tab on the
1651 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>
1652 makes available de-featured BSPs that are completely free
1653 of any IP encumbrances.
1654 For these cases, you can use the substitution directly and
1655 without any further licensing requirements.
1656 If present, these fully de-featured BSPs are named
1657 appropriately different as compared to the names of their
1658 respective encumbered BSPs.
1659 If available, these substitutions are your simplest and
1660 most preferred options.
1661 Obviously, use of these substitutions assumes the resulting
1662 functionality meets system requirements.
1663 <note>
1664 If however, a non-encumbered version is unavailable or
1665 it provides unsuitable functionality or quality, you can
1666 use an encumbered version.
1667 </note>
1668 </para>
1669
1670 <para>
1671 A couple different methods exist within the OpenEmbedded
1672 build system to satisfy the licensing requirements for an
1673 encumbered BSP.
1674 The following list describes them in order of preference:
1675 <orderedlist>
1676 <listitem><para>
1677 <emphasis>Use the
1678 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1679 Variable to Define the Recipes that Have Commercial
1680 or Other Types of Specially-Licensed Packages:</emphasis>
1681 For each of those recipes, you can specify a
1682 matching license string in a
1683 <filename>local.conf</filename> variable named
1684 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
1685 Specifying the matching license string signifies
1686 that you agree to the license.
1687 Thus, the build system can build the corresponding
1688 recipe and include the component in the image.
1689 See the
1690 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
1691 section in the Yocto Project Development Tasks
1692 Manual for details on how to use these variables.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001693 </para>
1694
Brad Bishop316dfdd2018-06-25 12:45:53 -04001695 <para>If you build as you normally would, without
1696 specifying any recipes in the
1697 <filename>LICENSE_FLAGS_WHITELIST</filename>, the
1698 build stops and provides you with the list of recipes
1699 that you have tried to include in the image that
1700 need entries in the
1701 <filename>LICENSE_FLAGS_WHITELIST</filename>.
1702 Once you enter the appropriate license flags into
1703 the whitelist, restart the build to continue where
1704 it left off.
1705 During the build, the prompt will not appear again
1706 since you have satisfied the requirement.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001707
Brad Bishop316dfdd2018-06-25 12:45:53 -04001708 <para>Once the appropriate license flags are on the
1709 white list in the
1710 <filename>LICENSE_FLAGS_WHITELIST</filename> variable,
1711 you can build the encumbered image with no change
1712 at all to the normal build process.
1713 </para></listitem>
1714 <listitem><para>
1715 <emphasis>Get a Pre-Built Version of the BSP:</emphasis>
1716 You can get this type of BSP by selecting the
1717 "DOWNLOADS" item from the "SOFTWARE" tab on the
1718 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1719 You can download BSP tarballs that contain
1720 proprietary components after agreeing to the
1721 licensing requirements of each of the individually
1722 encumbered packages as part of the download process.
1723 Obtaining the BSP this way allows you to access an
1724 encumbered image immediately after agreeing to the
1725 click-through license agreements presented by the
1726 website.
1727 If you want to build the image yourself using
1728 the recipes contained within the BSP tarball,
1729 you will still need to create an appropriate
1730 <filename>LICENSE_FLAGS_WHITELIST</filename>
1731 to match the encumbered recipes in the BSP.
1732 </para></listitem>
1733 </orderedlist>
1734 <note>
1735 Pre-compiled images are bundled with a time-limited
1736 kernel that runs for a predetermined amount of time
1737 (10 days) before it forces the system to reboot.
1738 This limitation is meant to discourage direct
1739 redistribution of the image.
1740 You must eventually rebuild the image if you want
1741 to remove this restriction.
1742 </note>
1743 </para>
1744</section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001745
Brad Bishop316dfdd2018-06-25 12:45:53 -04001746<section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>
1747 <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001748
Brad Bishop316dfdd2018-06-25 12:45:53 -04001749 <para>
1750 The <filename>bitbake-layers create-layer</filename> script
1751 automates creating a BSP layer.
1752 What makes a layer a "BSP layer", is the presence of a machine
1753 configuration file.
1754 Additionally, a BSP layer usually has a kernel recipe
1755 or an append file that leverages off an existing kernel recipe.
1756 The primary requirement, however, is the machine configuration.
1757 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001758
Brad Bishop316dfdd2018-06-25 12:45:53 -04001759 <para>
1760 Use these steps to create a BSP layer:
1761 <itemizedlist>
1762 <listitem><para>
1763 <emphasis>Create a General Layer:</emphasis>
1764 Use the <filename>bitbake-layers</filename> script with the
1765 <filename>create-layer</filename> subcommand to create a
1766 new general layer.
1767 For instructions on how to create a general layer using the
1768 <filename>bitbake-layers</filename> script, see the
1769 "<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>"
1770 section in the Yocto Project Development Tasks Manual.
1771 </para></listitem>
1772 <listitem><para>
1773 <emphasis>Create a Layer Configuration File:</emphasis>
1774 Every layer needs a layer configuration file.
1775 This configuration file establishes locations for the
1776 layer's recipes, priorities for the layer, and so forth.
1777 You can find examples of <filename>layer.conf</filename>
1778 files in the Yocto Project
1779 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
1780 To get examples of what you need in your configuration
1781 file, locate a layer (e.g. "meta-ti") and examine the
1782 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink>
1783 file.
1784 </para></listitem>
1785 <listitem><para>
1786 <emphasis>Create a Machine Configuration File:</emphasis>
1787 Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1788 file.
1789 See
1790 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink>
1791 for sample
1792 <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1793 files.
1794 Other samples such as
1795 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink>
1796 and
1797 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink>
1798 exist from other vendors that have more specific machine
1799 and tuning examples.
1800 </para></listitem>
1801 <listitem><para>
1802 <emphasis>Create a Kernel Recipe:</emphasis>
1803 Create a kernel recipe in <filename>recipes-kernel/linux</filename>
1804 by either using a kernel append file or a new custom kernel
1805 recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>).
1806 The BSP layers mentioned in the previous step also contain different
1807 kernel examples.
1808 See the
1809 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
1810 section in the Yocto Project Linux Kernel Development Manual
1811 for information on how to create a custom kernel.
1812 </para></listitem>
1813 </itemizedlist>
1814 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001815
Brad Bishop316dfdd2018-06-25 12:45:53 -04001816 <para>
1817 The remainder of this section provides a description of
1818 the Yocto Project reference BSP for Beaglebone, which
1819 resides in the
1820 <ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>Container Layer</ulink>
1821 (i.e.
1822 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink>).
1823 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001824
Brad Bishop316dfdd2018-06-25 12:45:53 -04001825 <section id='bsp-layer-configuration-example'>
1826 <title>BSP Layer Configuration Example</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001827
Brad Bishop316dfdd2018-06-25 12:45:53 -04001828 <para>
1829 The layer's <filename>conf</filename> directory
1830 contains the <filename>layer.conf</filename>
1831 configuration file.
1832 In this example, the
1833 <filename>conf/layer.conf</filename> is the
1834 following:
1835 <literallayout class='monospaced'>
1836 # We have a conf and classes directory, add to BBPATH
1837 BBPATH .= ":${LAYERDIR}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001838
Brad Bishop316dfdd2018-06-25 12:45:53 -04001839 # We have recipes-* directories, add to BBFILES
1840 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1841 ${LAYERDIR}/recipes-*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001842
Brad Bishop316dfdd2018-06-25 12:45:53 -04001843 BBFILE_COLLECTIONS += "yoctobsp"
1844 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
1845 BBFILE_PRIORITY_yoctobsp = "5"
1846 LAYERVERSION_yoctobsp = "4"
1847 LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
1848 </literallayout>
1849 The variables used in this file configure the
1850 layer.
1851 A good way to learn about layer configuration
1852 files is to examine various files for BSP from
1853 the
1854 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
1855 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001856
Brad Bishop316dfdd2018-06-25 12:45:53 -04001857 <para>
1858 For a detailed description of this particular
1859 layer configuration file, see
1860 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink>
1861 in the discussion that describes how to create
1862 layers in the Yocto Project Development Tasks Manual.
1863 </para>
1864 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001865
Brad Bishop316dfdd2018-06-25 12:45:53 -04001866 <section id='bsp-machine-configuration-example'>
1867 <title>BSP Machine Configuration Example</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001868
Brad Bishop316dfdd2018-06-25 12:45:53 -04001869 <para>
1870 As mentioned earlier in this section, the existence
1871 of a machine configuration file is what makes a
1872 layer a BSP layer as compared to a general or
1873 kernel layer.
1874 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001875
Brad Bishop316dfdd2018-06-25 12:45:53 -04001876 <para>
1877 Machine configuration files exist in the
1878 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
1879 directory of the layer:
1880 <literallayout class='monospaced'>
1881 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine</replaceable><filename>.conf</filename>
1882 </literallayout>
1883 For example, the machine configuration file for the
1884 <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
1885 is located in the container layer
1886 <filename>poky/meta-yocto-bsp/conf/machine</filename>
1887 and is named <filename>beaglebone-yocto.conf</filename>:
1888 <literallayout class='monospaced'>
1889 #@TYPE: Machine
1890 #@NAME: Beaglebone-yocto machine
1891 #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001892
Brad Bishop316dfdd2018-06-25 12:45:53 -04001893 PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
1894 XSERVER ?= "xserver-xorg \
1895 xf86-video-modesetting \
1896 "
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001897
Brad Bishop316dfdd2018-06-25 12:45:53 -04001898 MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001899
Brad Bishop316dfdd2018-06-25 12:45:53 -04001900 EXTRA_IMAGEDEPENDS += "u-boot"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001901
Brad Bishop316dfdd2018-06-25 12:45:53 -04001902 DEFAULTTUNE ?= "cortexa8hf-neon"
1903 include conf/machine/include/tune-cortexa8.inc
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001904
Brad Bishop316dfdd2018-06-25 12:45:53 -04001905 IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap"
1906 EXTRA_IMAGECMD_jffs2 = "-lnp "
1907 WKS_FILE ?= "beaglebone-yocto.wks"
1908 IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage"
1909 do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001910
Brad Bishop316dfdd2018-06-25 12:45:53 -04001911 SERIAL_CONSOLES = "115200;ttyO0"
1912
1913 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1914 PREFERRED_VERSION_linux-yocto ?= "4.12%"
1915
1916 KERNEL_IMAGETYPE = "zImage"
1917 KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
1918 KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
1919
1920 SPL_BINARY = "MLO"
1921 UBOOT_SUFFIX = "img"
1922 UBOOT_MACHINE = "am335x_boneblack_config"
1923 UBOOT_ENTRYPOINT = "0x80008000"
1924 UBOOT_LOADADDRESS = "0x80008000"
1925
1926 MACHINE_FEATURES = "usbgadget usbhost vfat alsa"
1927
1928 IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO"
1929 </literallayout>
1930 The variables used to configure the machine define
1931 machine-specific properties.
1932 For example, machine-dependent packages, machine
1933 tunings, the type of kernel to build, and
1934 U-Boot configurations.
1935 </para>
1936
1937 <para>
1938 The following list provides some explanation
1939 for the statements found in the example reference
1940 machine configuration file for the BeagleBone
1941 development boards.
1942 Realize that much more can be defined as part of
1943 a machines configuration file.
1944 In general, you can learn about related variables
1945 that this example does not have by locating the
1946 variables in the
1947 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>"
1948 in the Yocto Project Reference Manual.
1949 <itemizedlist>
1950 <listitem><para>
1951 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>:
1952 The recipe that provides "virtual/xserver" when
1953 more than one provider is found.
1954 In this case, the recipe that provides
1955 "virtual/xserver" is "xserver-xorg", which
1956 exists in
1957 <filename>poky/meta/recipes-graphics/xserver-xorg</filename>.
1958 </para></listitem>
1959 <listitem><para>
1960 <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>:
1961 The packages that should be installed to provide
1962 an X server and drivers for the machine.
1963 In this example, the "xserver-xorg" and
1964 "xf86-video-modesetting" are installed.
1965 </para></listitem>
1966 <listitem><para>
1967 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>:
1968 A list of machine-dependent packages
1969 not essential for booting the image.
1970 Thus, the build does not fail if the packages
1971 do not exist.
1972 However, the packages are required for a
1973 fully-featured image.
1974 <note><title>Tip</title>
1975 Many <filename>MACHINE*</filename> variables
1976 exist that help you configure a particular
1977 piece of hardware.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001978 </note>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001979 </para></listitem>
1980 <listitem><para>
1981 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>:
1982 Recipes to build that do not provide packages
1983 for installing into the root filesystem
1984 but building the image depends on the
1985 recipes.
1986 Sometimes a recipe is required to build
1987 the final image but is not needed in the
1988 root filesystem.
1989 In this case, the U-Boot recipe must be
1990 built for the image.
1991 </para></listitem>
1992 <listitem><para>
1993 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>:
1994 Machines use tunings to optimize machine,
1995 CPU, and application performance.
1996 These features, which are collectively known
1997 as "tuning features", exist in the
1998 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
1999 layer (e.g.
2000 <filename>poky/meta/conf/machine/include</filename>).
2001 In this example, the default tunning file is
2002 "cortexa8hf-neon".
2003 <note>
2004 The <filename>include</filename> statement
2005 that pulls in the
2006 <filename>conf/machine/include/tune-cortexa8.inc</filename>
2007 file provides many tuning possibilities.
2008 </note>
2009 </para></listitem>
2010 <listitem><para>
2011 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>:
2012 The formats the OpenEmbedded build system
2013 uses during the build when creating the
2014 root filesystem.
2015 In this example, four types of images are
2016 supported.
2017 </para></listitem>
2018 <listitem><para>
2019 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>:
2020 Specifies additional options for image
2021 creation commands.
2022 In this example, the "-lnp " option is used
2023 when creating the
2024 <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink>
2025 image.
2026 </para></listitem>
2027 <listitem><para>
2028 <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>:
2029 The location of the
2030 <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink>
2031 file used by the OpenEmbedded build system to
2032 create a partitioned image (image.wic).
2033 </para></listitem>
2034 <listitem><para>
2035 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
2036 Specifies packages to install into an image
2037 through the
2038 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
2039 class.
2040 Recipes use the <filename>IMAGE_INSTALL</filename>
2041 variable.
2042 </para></listitem>
2043 <listitem><para>
2044 <filename>do_image_wic[depends]</filename>:
2045 A task that is constructed during the build.
2046 In this example, the task depends on specific tools
2047 in order to create the sysroot when buiding a Wic
2048 image.
2049 </para></listitem>
2050 <listitem><para>
2051 <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>:
2052 Defines a serial console (TTY) to enable using
2053 getty.
2054 In this case, the baud rate is "115200" and the
2055 device name is "ttyO0".
2056 </para></listitem>
2057 <listitem><para>
2058 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>:
2059 Specifies the recipe that provides
2060 "virtual/kernel" when more than one provider
2061 is found.
2062 In this case, the recipe that provides
2063 "virtual/kernel" is "linux-yocto", which
2064 exists in the layer's
2065 <filename>recipes-kernel/linux</filename> directory.
2066 </para></listitem>
2067 <listitem><para>
2068 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>:
2069 Defines the version of the recipe used
2070 to build the kernel, which is "4.12" in this
2071 case.
2072 </para></listitem>
2073 <listitem><para>
2074 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>:
2075 The type of kernel to build for the device.
2076 In this case, the OpenEmbedded build system
2077 creates a "zImage" image type.
2078 </para></listitem>
2079 <listitem><para>
2080 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>:
2081 The name of the generated Linux kernel device
2082 tree (i.e. the <filename>.dtb</filename>) file.
2083 All the device trees for the various BeagleBone
2084 devices are included.
2085<!--
2086 You have to include some *.inc files according to the definition of KERNEL_DEVICETREE.
2087 I don't see where these are being provided.
2088-->
2089 </para></listitem>
2090 <listitem><para>
2091 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>:
2092 Additional <filename>make</filename>
2093 command-line arguments the OpenEmbedded build
2094 system passes on when compiling the kernel.
2095 In this example, "LOADADDR=${UBOOT_ENTRYPOINT}"
2096 is passed as a command-line argument.
2097 </para></listitem>
2098 <listitem><para>
2099 <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>:
2100 Defines the Secondary Program Loader (SPL) binary
2101 type.
2102 In this case, the SPL binary is set to
2103 "MLO", which stands for Multimedia card LOader.
2104 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002105
Brad Bishop316dfdd2018-06-25 12:45:53 -04002106 <para>The BeagleBone development board requires an
2107 SPL to boot and that SPL file type must be MLO.
2108 Consequently, the machine configuration needs to
2109 define <filename>SPL_BINARY</filename> as "MLO".
2110 <note>
2111 For more information on how the SPL variables
2112 are used, see the
2113 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink>
2114 include file.
2115 </note>
2116 </para></listitem>
2117 <listitem><para>
2118 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>:
2119 Defines various U-Boot configurations needed
2120 to build a U-Boot image.
2121 In this example, a U-Boot image is required
2122 to boot the BeagleBone device.
2123 See the following variables for more information:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002124 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002125 <listitem><para>
2126 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>:
2127 Points to the generated U-Boot extension.
2128 </para></listitem>
2129 <listitem><para>
2130 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>:
2131 Specifies the value passed on the make command line when building a U-Boot image.
2132 </para></listitem>
2133 <listitem><para>
2134 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>:
2135 Specifies the entry point for the U-Boot image.
2136 </para></listitem>
2137 <listitem><para>
2138 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>:
2139 Specifies the load address for the U-Boot image.
2140 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002141 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002142 </para></listitem>
2143 <listitem><para>
2144 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>:
2145 Specifies the list of hardware features the
2146 BeagleBone device is capable of supporting.
2147 In this case, the device supports
2148 "usbgadget usbhost vfat alsa".
2149 </para></listitem>
2150 <listitem><para>
2151 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>:
2152 Files installed into the device's boot partition
2153 when preparing the image using the Wic tool
2154 with the <filename>bootimg-partition</filename>
2155 source plugin.
2156 In this case, the "u-boot.${UBOOT_SUFFIX}" and
2157 "MLO" files are installed.
2158 </para></listitem>
2159 </itemizedlist>
2160 </para>
2161 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002162
Brad Bishop316dfdd2018-06-25 12:45:53 -04002163 <section id='bsp-kernel-recipe-example'>
2164 <title>BSP Kernel Recipe Example</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002165
Brad Bishop316dfdd2018-06-25 12:45:53 -04002166 <para>
2167 The kernel recipe used to build the kernel image
2168 for the BeagleBone device was established in the
2169 machine configuration:
2170 <literallayout class='monospaced'>
2171 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
2172 PREFERRED_VERSION_linux-yocto ?= "4.12%"
2173 </literallayout>
2174 The <filename>meta-yocto-bsp/recipes-kernel/linux</filename>
2175 directory in the layer contains metadata used
2176 to build the kernel.
2177 In this case, a kernel append file is used to
2178 override an established kernel recipe, which is
2179 located in
2180 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>
2181 and named
2182 <filename>linux-yocto_4.12.bb</filename>.
2183 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002184
Brad Bishop316dfdd2018-06-25 12:45:53 -04002185 <para>
2186 Following is the contents of the append file:
2187 <literallayout class='monospaced'>
2188 KBRANCH_genericx86 = "standard/base"
2189 KBRANCH_genericx86-64 = "standard/base"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002190
Brad Bishop316dfdd2018-06-25 12:45:53 -04002191 KMACHINE_genericx86 ?= "common-pc"
2192 KMACHINE_genericx86-64 ?= "common-pc-64"
2193 KBRANCH_edgerouter = "standard/edgerouter"
2194 KBRANCH_beaglebone-yocto = "standard/beaglebone"
2195 KMACHINE_beaglebone-yocto = "beaglebone"
2196 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002197
Brad Bishop316dfdd2018-06-25 12:45:53 -04002198 SRCREV_machine_genericx86 ?= "1c4ad569af3e23a77994235435040e322908687f"
2199 SRCREV_machine_genericx86-64 ?= "1c4ad569af3e23a77994235435040e322908687f"
2200 SRCREV_machine_edgerouter ?= "257f843ea367744620f1d92910afd2f454e31483"
2201 SRCREV_machine_beaglebone-yocto ?= "257f843ea367744620f1d92910afd2f454e31483"
2202 SRCREV_machine_mpc8315e-rdb ?= "014560874f9eb2a86138c9cc35046ff1720485e1"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002203
2204
Brad Bishop316dfdd2018-06-25 12:45:53 -04002205 COMPATIBLE_MACHINE_genericx86 = "genericx86"
2206 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
2207 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
2208 COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto"
2209 COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002210
Brad Bishop316dfdd2018-06-25 12:45:53 -04002211 LINUX_VERSION_genericx86 = "4.12.20"
2212 LINUX_VERSION_genericx86-64 = "4.12.20"
2213 LINUX_VERSION_edgerouter = "4.12.19"
2214 LINUX_VERSION_beaglebone-yocto = "4.12.19"
2215 LINUX_VERSION_mpc8315e-rdb = "4.12.19"
2216 </literallayout>
2217 This particular append file works for all the
2218 machines that are part of the
2219 <filename>meta-yocto-bsp</filename> container
2220 layer.
2221 The relevant statements are appended with
2222 the "beaglebone-yocto" string.
2223 The OpenEmbedded build system uses these
2224 statements to override similar statements
2225 in the kernel recipe:
2226 <itemizedlist>
2227 <listitem><para>
2228 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>:
2229 Identifies the kernel branch that is validated,
2230 patched, and configured during the build.
2231 </para></listitem>
2232 <listitem><para>
2233 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>:
2234 Identifies the machine name as known by the
2235 kernel, which is sometimes a different name
2236 than what is known by the OpenEmbedded build
2237 system.
2238 </para></listitem>
2239 <listitem><para>
2240 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
2241 Identifies the revision of the source code used
2242 to build the image.
2243<!--
2244 You find out about that point in the kernel source tree by
2245 doing the following command:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002246
Brad Bishop316dfdd2018-06-25 12:45:53 -04002247 git log &dash;&dash;decorate 257f843ea367744620f1d92910afd2f454e31483
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002248
Brad Bishop316dfdd2018-06-25 12:45:53 -04002249 Returns information about the commit, which is usually
2250 that it is a merge point for a stable kernel release.
2251-->
2252 </para></listitem>
2253 <listitem><para>
2254 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
2255 A regular expression that resolves to one or
2256 more target machines with which the recipe
2257 is compatible.
2258 </para></listitem>
2259 <listitem><para>
2260 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
2261 The Linux version from kernel.org used by
2262 the OpenEmbedded build system to build the
2263 kernel image.
2264 </para></listitem>
2265 </itemizedlist>
2266 </para>
2267 </section>
2268</section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002269</chapter>