blob: 72a077e80682f1586e4e58d6de6f5465c59b3476 [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; ] >
Andrew Geisslerd25ed322020-06-27 00:28:28 -05004<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005
6<chapter id='bsp'>
7
Brad Bishop316dfdd2018-06-25 12:45:53 -04008<title>Board Support Packages (BSP) - Developer's Guide</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009
Brad Bishop316dfdd2018-06-25 12:45:53 -040010<para>
11 A Board Support Package (BSP) is a collection of information that
12 defines how to support a particular hardware device, set of devices, or
13 hardware platform.
14 The BSP includes information about the hardware features
15 present on the device and kernel configuration information along with any
16 additional hardware drivers required.
17 The BSP also lists any additional software
18 components required in addition to a generic Linux software stack for both
19 essential and optional platform features.
20</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050021
Brad Bishop316dfdd2018-06-25 12:45:53 -040022<para>
Andrew Geissler82c905d2020-04-13 13:39:40 -050023 This guide presents information about BSP layers, defines a structure for components
Brad Bishop316dfdd2018-06-25 12:45:53 -040024 so that BSPs follow a commonly understood layout, discusses how to customize
25 a recipe for a BSP, addresses BSP licensing, and provides information that
26 shows you how to create a
27 <link linkend='bsp-layers'>BSP Layer</link> using the
28 <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></link>
29 tool.
30</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050031
Brad Bishop316dfdd2018-06-25 12:45:53 -040032<section id='bsp-layers'>
33 <title>BSP Layers</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050034
Brad Bishop316dfdd2018-06-25 12:45:53 -040035 <para>
36 A BSP consists of a file structure inside a base directory.
37 Collectively, you can think of the base directory, its file structure,
Andrew Geissler82c905d2020-04-13 13:39:40 -050038 and the contents as a <firstterm>BSP layer</firstterm>.
Brad Bishop316dfdd2018-06-25 12:45:53 -040039 Although not a strict requirement, BSP layers in the Yocto Project
40 use the following well-established naming convention:
41 <literallayout class='monospaced'>
42 meta-<replaceable>bsp_root_name</replaceable>
43 </literallayout>
44 The string "meta-" is prepended to the machine or platform name, which is
45 <replaceable>bsp_root_name</replaceable> in the above form.
46 <note><title>Tip</title>
47 Because the BSP layer naming convention is well-established,
48 it is advisable to follow it when creating layers.
49 Technically speaking, a BSP layer name does not need to
50 start with <filename>meta-</filename>.
51 However, various scripts and tools in the Yocto Project
52 development environment assume this convention.
53 </note>
54 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050055
Brad Bishop316dfdd2018-06-25 12:45:53 -040056 <para>
57 To help understand the BSP layer concept, consider the BSPs that the
58 Yocto Project supports and provides with each release.
59 You can see the layers in the
60 <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
61 through a web interface at
62 <ulink url='&YOCTO_GIT_URL;'></ulink>.
63 If you go to that interface, you will find a list of repositories
64 under "Yocto Metadata Layers".
65 <note>
66 Layers that are no longer actively supported as part of the
67 Yocto Project appear under the heading "Yocto Metadata Layer
68 Archive."
69 </note>
70 Each repository is a BSP layer supported by the Yocto Project
71 (e.g. <filename>meta-raspberrypi</filename> and
72 <filename>meta-intel</filename>).
Andrew Geissler82c905d2020-04-13 13:39:40 -050073 Each of these layers is a repository unto itself and clicking on
74 the layer name displays two URLs from which you can
75 clone the layer's repository to your local system.
Brad Bishop316dfdd2018-06-25 12:45:53 -040076 Here is an example that clones the Raspberry Pi BSP layer:
77 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050078 $ git clone git://git.yoctoproject.org/meta-raspberrypi
Brad Bishop316dfdd2018-06-25 12:45:53 -040079 </literallayout>
80 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050081
Brad Bishop316dfdd2018-06-25 12:45:53 -040082 <para>
83 In addition to BSP layers, the
84 <filename>meta-yocto-bsp</filename> layer is part of the
85 shipped <filename>poky</filename> repository.
86 The <filename>meta-yocto-bsp</filename> layer maintains several
Andrew Geissler82c905d2020-04-13 13:39:40 -050087 "reference" BSPs including the ARM-based Beaglebone, MIPS-based
88 EdgeRouter, and generic versions of
Brad Bishop316dfdd2018-06-25 12:45:53 -040089 both 32-bit and 64-bit IA machines.
90 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050091
Brad Bishop316dfdd2018-06-25 12:45:53 -040092 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -050093 For information on typical BSP development workflow, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040094 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
95 section.
96 For more information on how to set up a local copy of source files
97 from a Git repository, see the
98 "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
99 section in the Yocto Project Development Tasks Manual.
100 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500101
Brad Bishop316dfdd2018-06-25 12:45:53 -0400102 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500103 The BSP layer's base directory
Brad Bishop316dfdd2018-06-25 12:45:53 -0400104 (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>)
Andrew Geissler82c905d2020-04-13 13:39:40 -0500105 is the root directory of that Layer.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400106 This directory is what you add to the
107 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500108 variable in the <filename>conf/bblayers.conf</filename> file found in your
Brad Bishop316dfdd2018-06-25 12:45:53 -0400109 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
110 which is established after you run the OpenEmbedded build environment
111 setup script (i.e.
112 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
113 Adding the root directory allows the
114 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
115 to recognize the BSP layer and from it build an image.
116 Here is an example:
117 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500118 BBLAYERS ?= " \
119 /usr/local/src/yocto/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500120 /usr/local/src/yocto/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500121 /usr/local/src/yocto/meta-yocto-bsp \
122 /usr/local/src/yocto/meta-mylayer \
123 "
Brad Bishop316dfdd2018-06-25 12:45:53 -0400124 </literallayout>
125 <note><title>Tip</title>
126 Ordering and
127 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
128 for the layers listed in <filename>BBLAYERS</filename>
129 matter.
130 For example, if multiple layers define a machine
131 configuration, the OpenEmbedded build system uses
132 the last layer searched given similar layer
133 priorities.
134 The build system works from the top-down through
135 the layers listed in <filename>BBLAYERS</filename>.
136 </note>
137 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500138
Brad Bishop316dfdd2018-06-25 12:45:53 -0400139 <para>
140 Some BSPs require or depend on additional layers
141 beyond the BSP's root layer in order to be functional.
142 In this case, you need to specify these layers in the
143 <filename>README</filename> "Dependencies" section of the
144 BSP's root layer.
145 Additionally, if any build instructions exist for the
146 BSP, you must add them to the "Dependencies" section.
147 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500148
Brad Bishop316dfdd2018-06-25 12:45:53 -0400149 <para>
150 Some layers function as a layer to hold other BSP layers.
151 These layers are knows as
152 "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>".
Brad Bishopc342db32019-05-15 21:57:59 -0400153 An example of this type of layer is OpenEmbedded's
154 <ulink url='https://github.com/openembedded/meta-openembedded'><filename>meta-openembedded</filename></ulink>
155 layer.
156 The <filename>meta-openembedded</filename> layer contains
157 many <filename>meta-*</filename> layers.
Andrew Geissler82c905d2020-04-13 13:39:40 -0500158 In cases like this, you need to include the names of the actual
159 layers you want to work with, such as:
160 <literallayout class='monospaced'>
161 BBLAYERS ?= " \
162 /usr/local/src/yocto/meta \
163 /usr/local/src/yocto/meta-poky \
164 /usr/local/src/yocto/meta-yocto-bsp \
165 /usr/local/src/yocto/meta-mylayer \
166 .../meta-openembedded/meta-oe \
167 .../meta-openembedded/meta-perl \
168 .../meta-openembedded/meta-networking \
169 "
170 </literallayout>
171 and so on.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400172 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500173
Brad Bishop316dfdd2018-06-25 12:45:53 -0400174 <para>
175 For more information on layers, see the
176 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
177 section of the Yocto Project Development Tasks Manual.
178 </para>
179</section>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500180
Brad Bishop316dfdd2018-06-25 12:45:53 -0400181<section id='preparing-your-build-host-to-work-with-bsp-layers'>
182 <title>Preparing Your Build Host to Work With BSP Layers</title>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500183
Brad Bishop316dfdd2018-06-25 12:45:53 -0400184 <para>
185 This section describes how to get your build host ready
186 to work with BSP layers.
187 Once you have the host set up, you can create the layer
188 as described in the
189 "<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>"
190 section.
191 <note>
192 For structural information on BSPs, see the
193 <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
194 section.
195 </note>
196 <orderedlist>
197 <listitem><para>
198 <emphasis>Set Up the Build Environment:</emphasis>
199 Be sure you are set up to use BitBake in a shell.
200 See the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800201 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400202 section in the Yocto Project Development Tasks Manual for information
203 on how to get a build host ready that is either a native
204 Linux machine or a machine that uses CROPS.
205 </para></listitem>
206 <listitem><para>
207 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
208 You need to have a local copy of the Yocto Project
209 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
210 (i.e. a local <filename>poky</filename> repository).
211 See the
212 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
213 and possibly the
214 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
215 or
216 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
217 sections all in the Yocto Project Development Tasks Manual for
218 information on how to clone the <filename>poky</filename>
219 repository and check out the appropriate branch for your work.
220 </para></listitem>
221 <listitem><para>
222 <emphasis>Determine the BSP Layer You Want:</emphasis>
223 The Yocto Project supports many BSPs, which are maintained in
224 their own layers or in layers designed to contain several
225 BSPs.
226 To get an idea of machine support through BSP layers, you can
227 look at the
228 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
229 for the release.
230 </para></listitem>
231 <listitem><para>
232 <emphasis>Optionally Clone the
233 <filename>meta-intel</filename> BSP Layer:</emphasis>
234 If your hardware is based on current Intel CPUs and devices,
235 you can leverage this BSP layer.
236 For details on the <filename>meta-intel</filename> BSP layer,
237 see the layer's
238 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
239 file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500240 <orderedlist>
241 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400242 <emphasis>Navigate to Your Source Directory:</emphasis>
243 Typically, you set up the
244 <filename>meta-intel</filename> Git repository
245 inside the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500246 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400247 (e.g. <filename>poky</filename>).
248 <literallayout class='monospaced'>
249 $ cd /home/<replaceable>you</replaceable>/poky
250 </literallayout>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500251 </para></listitem>
252 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400253 <emphasis>Clone the Layer:</emphasis>
254 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500255 $ git clone git://git.yoctoproject.org/meta-intel.git
256 Cloning into 'meta-intel'...
Brad Bishop316dfdd2018-06-25 12:45:53 -0400257 remote: Counting objects: 15585, done.
258 remote: Compressing objects: 100% (5056/5056), done.
259 remote: Total 15585 (delta 9123), reused 15329 (delta 8867)
260 Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done.
261 Resolving deltas: 100% (9123/9123), done.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500262 Checking connectivity... done.
263 </literallayout>
264 </para></listitem>
265 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400266 <emphasis>Check Out the Proper Branch:</emphasis>
267 The branch you check out for
268 <filename>meta-intel</filename> must match the same
269 branch you are using for the Yocto Project release
270 (e.g. &DISTRO_NAME_NO_CAP;):
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500271 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400272 $ cd meta-intel
273 $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP;
274 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
275 Switched to a new branch '&DISTRO_NAME_NO_CAP;'
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500276 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400277 <note>
278 To see the available branch names in a cloned repository,
279 use the <filename>git branch -al</filename> command.
280 See the
281 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
282 section in the Yocto Project Development Tasks
283 Manual for more information.
284 </note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500285 </para></listitem>
286 </orderedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400287 </para></listitem>
288 <listitem><para>
289 <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
290 If your hardware can be more closely leveraged to an
291 existing BSP not within the <filename>meta-intel</filename>
292 BSP layer, you can clone that BSP layer.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500293
Brad Bishop316dfdd2018-06-25 12:45:53 -0400294 <para>The process is identical to the process used for the
295 <filename>meta-intel</filename> layer except for the layer's
296 name.
297 For example, if you determine that your hardware most
298 closely matches the <filename>meta-raspberrypi</filename>,
299 clone that layer:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500300 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400301 $ git clone git://git.yoctoproject.org/meta-raspberrypi
302 Cloning into 'meta-raspberrypi'...
303 remote: Counting objects: 4743, done.
304 remote: Compressing objects: 100% (2185/2185), done.
305 remote: Total 4743 (delta 2447), reused 4496 (delta 2258)
306 Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done.
307 Resolving deltas: 100% (2447/2447), done.
308 Checking connectivity... done.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500309 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400310 </para></listitem>
311 <listitem><para>
312 <emphasis>Initialize the Build Environment:</emphasis>
313 While in the root directory of the Source Directory (i.e.
314 <filename>poky</filename>), run the
315 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
316 environment setup script to define the OpenEmbedded
317 build environment on your build host.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500318 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400319 $ source &OE_INIT_FILE;
320 </literallayout>
321 Among other things, the script creates the
322 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
323 which is <filename>build</filename> in this case
324 and is located in the
325 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
326 After the script runs, your current working directory
327 is set to the <filename>build</filename> directory.
328 </para></listitem>
329 </orderedlist>
330 </para>
331</section>
332
333<section id="bsp-filelayout">
334 <title>Example Filesystem Layout</title>
335
336 <para>
337 Defining a common BSP directory structure allows
338 end-users to understand and become familiar with
339 that standard.
340 A common format also encourages standardization
341 of software support for hardware.
342 </para>
343
344 <para>
345 The proposed form described in this section does
346 have elements that are specific to the OpenEmbedded
347 build system.
348 It is intended that developers can use this structure
349 with other build systems besides the OpenEmbedded build
350 system.
351 It is also intended that it will be be simple to extract
352 information and convert it to other formats if required.
353 The OpenEmbedded build system, through its standard
354 <ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
355 can directly accept the format described as a layer.
356 The BSP layer captures all the hardware-specific details
357 in one place using a standard format, which is useful
358 for any person wishing to use the hardware platform
359 regardless of the build system they are using.
360 </para>
361
362 <para>
363 The BSP specification does not include a build system
364 or other tools - the specification is concerned with
365 the hardware-specific components only.
366 At the end-distribution point, you can ship the BSP
367 layer combined with a build system and other tools.
368 Realize that it is important to maintain the distinction
369 that the BSP layer, a build system, and tools are
Andrew Geissler82c905d2020-04-13 13:39:40 -0500370 separate components that could be combined in
Brad Bishop316dfdd2018-06-25 12:45:53 -0400371 certain end products.
372 </para>
373
374 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500375 Before looking at the recommended form for the directory structure
376 inside a BSP layer, you should be aware that some
Brad Bishop316dfdd2018-06-25 12:45:53 -0400377 requirements do exist in order for a BSP layer to
Andrew Geissler82c905d2020-04-13 13:39:40 -0500378 be considered <firstterm>compliant</firstterm> with the Yocto Project.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400379 For that list of requirements, see the
380 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
381 section.
382 </para>
383
384 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500385 Below is the typical directory structure for a BSP layer.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400386 While this basic form represents the standard,
Andrew Geissler82c905d2020-04-13 13:39:40 -0500387 realize that the actual layout for individual
Brad Bishop316dfdd2018-06-25 12:45:53 -0400388 BSPs could differ.
389 <literallayout class='monospaced'>
390 meta-<replaceable>bsp_root_name</replaceable>/
391 meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
392 meta-<replaceable>bsp_root_name</replaceable>/README
393 meta-<replaceable>bsp_root_name</replaceable>/README.sources
394 meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
395 meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
396 meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
397 meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
398 meta-<replaceable>bsp_root_name</replaceable>/recipes-core/*
399 meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
400 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
401 </literallayout>
402 </para>
403
404 <para>
405 Below is an example of the Raspberry Pi BSP
406 layer that is available from the
407 <ulink url='&YOCTO_GIT_URL;'>Source Respositories</ulink>:
408 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500409 meta-raspberrypi/COPYING.MIT
Brad Bishop316dfdd2018-06-25 12:45:53 -0400410 meta-raspberrypi/README.md
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500411 meta-raspberrypi/classes
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500412 meta-raspberrypi/classes/sdcard_image-rpi.bbclass
413 meta-raspberrypi/conf/
414 meta-raspberrypi/conf/layer.conf
415 meta-raspberrypi/conf/machine/
Brad Bishop316dfdd2018-06-25 12:45:53 -0400416 meta-raspberrypi/conf/machine/raspberrypi-cm.conf
417 meta-raspberrypi/conf/machine/raspberrypi-cm3.conf
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500418 meta-raspberrypi/conf/machine/raspberrypi.conf
Brad Bishop316dfdd2018-06-25 12:45:53 -0400419 meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500420 meta-raspberrypi/conf/machine/raspberrypi0.conf
421 meta-raspberrypi/conf/machine/raspberrypi2.conf
Brad Bishop316dfdd2018-06-25 12:45:53 -0400422 meta-raspberrypi/conf/machine/raspberrypi3-64.conf
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500423 meta-raspberrypi/conf/machine/raspberrypi3.conf
424 meta-raspberrypi/conf/machine/include
425 meta-raspberrypi/conf/machine/include/rpi-base.inc
426 meta-raspberrypi/conf/machine/include/rpi-default-providers.inc
427 meta-raspberrypi/conf/machine/include/rpi-default-settings.inc
428 meta-raspberrypi/conf/machine/include/rpi-default-versions.inc
Brad Bishop316dfdd2018-06-25 12:45:53 -0400429 meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc
430 meta-raspberrypi/docs
431 meta-raspberrypi/docs/Makefile
432 meta-raspberrypi/docs/conf.py
433 meta-raspberrypi/docs/contributing.md
434 meta-raspberrypi/docs/extra-apps.md
435 meta-raspberrypi/docs/extra-build-config.md
436 meta-raspberrypi/docs/index.rst
437 meta-raspberrypi/docs/layer-contents.md
438 meta-raspberrypi/docs/readme.md
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500439 meta-raspberrypi/files
440 meta-raspberrypi/files/custom-licenses
441 meta-raspberrypi/files/custom-licenses/Broadcom
442 meta-raspberrypi/recipes-bsp
443 meta-raspberrypi/recipes-bsp/bootfiles
444 meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb
445 meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb
446 meta-raspberrypi/recipes-bsp/common
447 meta-raspberrypi/recipes-bsp/common/firmware.inc
Brad Bishop316dfdd2018-06-25 12:45:53 -0400448 meta-raspberrypi/recipes-bsp/formfactor
449 meta-raspberrypi/recipes-bsp/formfactor/formfactor
450 meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi
451 meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig
452 meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend
453 meta-raspberrypi/recipes-bsp/rpi-u-boot-src
454 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files
455 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in
456 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb
457 meta-raspberrypi/recipes-bsp/u-boot
458 meta-raspberrypi/recipes-bsp/u-boot/u-boot
459 meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch
460 meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend
461 meta-raspberrypi/recipes-connectivity
462 meta-raspberrypi/recipes-connectivity/bluez5
463 meta-raspberrypi/recipes-connectivity/bluez5/bluez5
464 meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch
465 meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd
466 meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service
467 meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500468 meta-raspberrypi/recipes-core
469 meta-raspberrypi/recipes-core/images
470 meta-raspberrypi/recipes-core/images/rpi-basic-image.bb
471 meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb
472 meta-raspberrypi/recipes-core/images/rpi-test-image.bb
473 meta-raspberrypi/recipes-core/packagegroups
474 meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb
475 meta-raspberrypi/recipes-core/psplash
476 meta-raspberrypi/recipes-core/psplash/files
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500477 meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h
Brad Bishop316dfdd2018-06-25 12:45:53 -0400478 meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
479 meta-raspberrypi/recipes-core/udev
480 meta-raspberrypi/recipes-core/udev/udev-rules-rpi
481 meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules
482 meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500483 meta-raspberrypi/recipes-devtools
484 meta-raspberrypi/recipes-devtools/bcm2835
Brad Bishop316dfdd2018-06-25 12:45:53 -0400485 meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500486 meta-raspberrypi/recipes-devtools/pi-blaster
487 meta-raspberrypi/recipes-devtools/pi-blaster/files
Brad Bishop316dfdd2018-06-25 12:45:53 -0400488 meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500489 meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb
490 meta-raspberrypi/recipes-devtools/python
491 meta-raspberrypi/recipes-devtools/python/python-rtimu
492 meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch
493 meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb
Brad Bishop316dfdd2018-06-25 12:45:53 -0400494 meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500495 meta-raspberrypi/recipes-devtools/python/rpi-gpio
496 meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch
Brad Bishop316dfdd2018-06-25 12:45:53 -0400497 meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500498 meta-raspberrypi/recipes-devtools/python/rpio
499 meta-raspberrypi/recipes-devtools/python/rpio/*.patch
500 meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb
501 meta-raspberrypi/recipes-devtools/wiringPi
502 meta-raspberrypi/recipes-devtools/wiringPi/files
503 meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500504 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb
505 meta-raspberrypi/recipes-graphics
506 meta-raspberrypi/recipes-graphics/eglinfo
507 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend
508 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend
Brad Bishop316dfdd2018-06-25 12:45:53 -0400509 meta-raspberrypi/recipes-graphics/mesa
510 meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend
511 meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500512 meta-raspberrypi/recipes-graphics/userland
513 meta-raspberrypi/recipes-graphics/userland/userland
514 meta-raspberrypi/recipes-graphics/userland/userland/*.patch
515 meta-raspberrypi/recipes-graphics/userland/userland_git.bb
516 meta-raspberrypi/recipes-graphics/vc-graphics
517 meta-raspberrypi/recipes-graphics/vc-graphics/files
518 meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc
519 meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh
520 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb
521 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb
522 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc
523 meta-raspberrypi/recipes-graphics/wayland
524 meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500525 meta-raspberrypi/recipes-graphics/xorg-xserver
526 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config
527 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi
528 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf
529 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d
530 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf
Brad Bishop316dfdd2018-06-25 12:45:53 -0400531 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf
532 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500533 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
Brad Bishop316dfdd2018-06-25 12:45:53 -0400534 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500535 meta-raspberrypi/recipes-kernel
536 meta-raspberrypi/recipes-kernel/linux-firmware
Brad Bishop316dfdd2018-06-25 12:45:53 -0400537 meta-raspberrypi/recipes-kernel/linux-firmware/files
538 meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin
539 meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt
540 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500541 meta-raspberrypi/recipes-kernel/linux
Brad Bishop316dfdd2018-06-25 12:45:53 -0400542 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500543 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc
Brad Bishop316dfdd2018-06-25 12:45:53 -0400544 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb
545 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500546 meta-raspberrypi/recipes-multimedia
547 meta-raspberrypi/recipes-multimedia/gstreamer
548 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx
549 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch
550 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend
551 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend
Brad Bishop316dfdd2018-06-25 12:45:53 -0400552 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12
553 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500554 meta-raspberrypi/recipes-multimedia/omxplayer
555 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer
556 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch
557 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb
Brad Bishop316dfdd2018-06-25 12:45:53 -0400558 meta-raspberrypi/recipes-multimedia/x264
559 meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend
560 meta-raspberrypi/wic
561 meta-raspberrypi/wic/sdimage-raspberrypi.wks
562 </literallayout>
563 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500564
Brad Bishop316dfdd2018-06-25 12:45:53 -0400565 <para>
566 The following sections describe each part of the proposed
567 BSP format.
568 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500569
Brad Bishop316dfdd2018-06-25 12:45:53 -0400570 <section id="bsp-filelayout-license">
571 <title>License Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500572
Brad Bishop316dfdd2018-06-25 12:45:53 -0400573 <para>
574 You can find these files in the BSP Layer at:
575 <literallayout class='monospaced'>
576 meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
577 </literallayout>
578 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500579
Brad Bishop316dfdd2018-06-25 12:45:53 -0400580 <para>
581 These optional files satisfy licensing requirements
582 for the BSP.
583 The type or types of files here can vary depending
584 on the licensing requirements.
Andrew Geissler82c905d2020-04-13 13:39:40 -0500585 For example, in the Raspberry Pi BSP, all licensing
Brad Bishop316dfdd2018-06-25 12:45:53 -0400586 requirements are handled with the
587 <filename>COPYING.MIT</filename> file.
588 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500589
Brad Bishop316dfdd2018-06-25 12:45:53 -0400590 <para>
591 Licensing files can be MIT, BSD, GPLv*, and so forth.
592 These files are recommended for the BSP but are
593 optional and totally up to the BSP developer.
594 For information on how to maintain license
595 compliance, see the
596 "<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>"
597 section in the Yocto Project Development Tasks
598 Manual.
599 </para>
600 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500601
Brad Bishop316dfdd2018-06-25 12:45:53 -0400602 <section id="bsp-filelayout-readme">
603 <title>README File</title>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500604
Brad Bishop316dfdd2018-06-25 12:45:53 -0400605 <para>
606 You can find this file in the BSP Layer at:
607 <literallayout class='monospaced'>
608 meta-<replaceable>bsp_root_name</replaceable>/README
609 </literallayout>
610 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500611
Brad Bishop316dfdd2018-06-25 12:45:53 -0400612 <para>
613 This file provides information on how to boot the live
614 images that are optionally included in the
615 <filename>binary/</filename> directory.
616 The <filename>README</filename> file also provides
617 information needed for building the image.
618 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500619
Brad Bishop316dfdd2018-06-25 12:45:53 -0400620 <para>
621 At a minimum, the <filename>README</filename> file must
622 contain a list of dependencies, such as the names of
623 any other layers on which the BSP depends and the name of
624 the BSP maintainer with his or her contact information.
625 </para>
626 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500627
Brad Bishop316dfdd2018-06-25 12:45:53 -0400628 <section id="bsp-filelayout-readme-sources">
629 <title>README.sources File</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500630
Brad Bishop316dfdd2018-06-25 12:45:53 -0400631 <para>
632 You can find this file in the BSP Layer at:
633 <literallayout class='monospaced'>
634 meta-<replaceable>bsp_root_name</replaceable>/README.sources
635 </literallayout>
636 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500637
Brad Bishop316dfdd2018-06-25 12:45:53 -0400638 <para>
639 This file provides information on where to locate the BSP
640 source files used to build the images (if any) that
641 reside in
642 <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>.
643 Images in the <filename>binary</filename> would be images
644 released with the BSP.
645 The information in the <filename>README.sources</filename>
646 file also helps you find the
647 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
648 used to generate the images that ship with the BSP.
649 <note>
650 If the BSP's <filename>binary</filename> directory is
651 missing or the directory has no images, an existing
652 <filename>README.sources</filename> file is
653 meaningless and usually does not exist.
654 </note>
655 </para>
656 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500657
Brad Bishop316dfdd2018-06-25 12:45:53 -0400658 <section id="bsp-filelayout-binary">
659 <title>Pre-built User Binaries</title>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500660
Brad Bishop316dfdd2018-06-25 12:45:53 -0400661 <para>
662 You can find these files in the BSP Layer at:
663 <literallayout class='monospaced'>
664 meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
665 </literallayout>
666 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500667
Brad Bishop316dfdd2018-06-25 12:45:53 -0400668 <para>
669 This optional area contains useful pre-built kernels
670 and user-space filesystem images released with the
671 BSP that are appropriate to the target system.
672 This directory typically contains graphical (e.g. Sato)
673 and minimal live images when the BSP tarball has been
674 created and made available in the
675 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
676 website.
677 You can use these kernels and images to get a system
678 running and quickly get started on development tasks.
679 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500680
Brad Bishop316dfdd2018-06-25 12:45:53 -0400681 <para>
682 The exact types of binaries present are highly
683 hardware-dependent.
684 The
685 <link linkend='bsp-filelayout-readme'><filename>README</filename></link>
686 file should be present in the BSP Layer and it
687 explains how to use the images with the target hardware.
688 Additionally, the
689 <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link>
690 file should be present to locate the sources used to
691 build the images and provide information on the
692 Metadata.
693 </para>
694 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500695
Brad Bishop316dfdd2018-06-25 12:45:53 -0400696 <section id='bsp-filelayout-layer'>
697 <title>Layer Configuration File</title>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500698
Brad Bishop316dfdd2018-06-25 12:45:53 -0400699 <para>
700 You can find this file in the BSP Layer at:
701 <literallayout class='monospaced'>
702 meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
703 </literallayout>
704 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500705
Brad Bishop316dfdd2018-06-25 12:45:53 -0400706 <para>
707 The <filename>conf/layer.conf</filename> file
708 identifies the file structure as a layer,
709 identifies the contents of the layer, and
710 contains information about how the build system should
711 use it.
712 Generally, a standard boilerplate file such as the
713 following works.
714 In the following example, you would replace
715 <replaceable>bsp</replaceable> with the actual
716 name of the BSP (i.e.
717 <replaceable>bsp_root_name</replaceable> from the example
718 template).
719 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500720
Brad Bishop316dfdd2018-06-25 12:45:53 -0400721 <para>
722 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500723 # We have a conf and classes directory, add to BBPATH
724 BBPATH .= ":${LAYERDIR}"
725
726 # We have a recipes directory, add to BBFILES
727 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500728 ${LAYERDIR}/recipes-*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500729
730 BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>"
731 BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/"
732 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
733
734 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400735 </literallayout>
736 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500737
Brad Bishop316dfdd2018-06-25 12:45:53 -0400738 <para>
739 To illustrate the string substitutions, here are
740 the corresponding statements from the Raspberry
741 Pi <filename>conf/layer.conf</filename> file:
742 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500743 # We have a conf and classes directory, append to BBPATH
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500744 BBPATH .= ":${LAYERDIR}"
745
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500746 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
747 BBFILES += "${LAYERDIR}/recipes*/*/*.bb \
748 ${LAYERDIR}/recipes*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500749
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500750 BBFILE_COLLECTIONS += "raspberrypi"
751 BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/"
752 BBFILE_PRIORITY_raspberrypi = "9"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500753
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500754 # Additional license directories.
755 LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400756 .
757 .
758 .
759 </literallayout>
760 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500761
Brad Bishop316dfdd2018-06-25 12:45:53 -0400762 <para>
763 This file simply makes
764 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
765 aware of the recipes and configuration directories.
766 The file must exist so that the OpenEmbedded build system
767 can recognize the BSP.
768 </para>
769 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500770
Brad Bishop316dfdd2018-06-25 12:45:53 -0400771 <section id="bsp-filelayout-machine">
772 <title>Hardware Configuration Options</title>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500773
Brad Bishop316dfdd2018-06-25 12:45:53 -0400774 <para>
775 You can find these files in the BSP Layer at:
776 <literallayout class='monospaced'>
777 meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
778 </literallayout>
779 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500780
Brad Bishop316dfdd2018-06-25 12:45:53 -0400781 <para>
782 The machine files bind together all the information
783 contained elsewhere in the BSP into a format that
784 the build system can understand.
785 Each BSP Layer requires at least one machine file.
786 If the BSP supports multiple machines, multiple
787 machine configuration files can exist.
788 These filenames correspond to the values to which
789 users have set the
790 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
791 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500792
Brad Bishop316dfdd2018-06-25 12:45:53 -0400793 <para>
794 These files define things such as the kernel package
795 to use
796 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
797 of
798 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>),
799 the hardware drivers to include in different types
800 of images, any special software components that are
801 needed, any bootloader information, and also any
802 special image format requirements.
803 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500804
Brad Bishop316dfdd2018-06-25 12:45:53 -0400805 <para>
806 This configuration file could also include a hardware
807 "tuning" file that is commonly used to define the
808 package architecture and specify optimization flags,
809 which are carefully chosen to give best performance
810 on a given processor.
811 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500812
Brad Bishop316dfdd2018-06-25 12:45:53 -0400813 <para>
814 Tuning files are found in the
815 <filename>meta/conf/machine/include</filename>
816 directory within the
817 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
818 For example, many <filename>tune-*</filename> files
819 (e.g. <filename>tune-arm1136jf-s.inc</filename>,
Andrew Geissler82c905d2020-04-13 13:39:40 -0500820 <filename>tune-1586-nlp.inc</filename>, and so forth)
Brad Bishop316dfdd2018-06-25 12:45:53 -0400821 reside in the
822 <filename>poky/meta/conf/machine/include</filename>
823 directory.
824 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500825
Brad Bishop316dfdd2018-06-25 12:45:53 -0400826 <para>
827 To use an include file, you simply include them in the
828 machine configuration file.
829 For example, the Raspberry Pi BSP
830 <filename>raspberrypi3.conf</filename> contains the
831 following statement:
832 <literallayout class='monospaced'>
833 include conf/machine/include/rpi-base.inc
834 </literallayout>
835 </para>
836 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500837
Brad Bishop316dfdd2018-06-25 12:45:53 -0400838 <section id='bsp-filelayout-misc-recipes'>
839 <title>Miscellaneous BSP-Specific Recipe Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500840
Brad Bishop316dfdd2018-06-25 12:45:53 -0400841 <para>
842 You can find these files in the BSP Layer at:
843 <literallayout class='monospaced'>
844 meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
845 </literallayout>
846 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500847
Brad Bishop316dfdd2018-06-25 12:45:53 -0400848 <para>
849 This optional directory contains miscellaneous recipe
850 files for the BSP.
851 Most notably would be the formfactor files.
Andrew Geissler82c905d2020-04-13 13:39:40 -0500852 For example, in the Raspberry Pi BSP, there is the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400853 <filename>formfactor_0.0.bbappend</filename> file,
854 which is an append file used to augment the recipe
855 that starts the build.
856 Furthermore, there are machine-specific settings used
857 during the build that are defined by the
858 <filename>machconfig</filename> file further down in
859 the directory.
860 Here is the <filename>machconfig</filename> file for
861 the Raspberry Pi BSP:
862 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500863 HAVE_TOUCHSCREEN=0
864 HAVE_KEYBOARD=1
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500865
866 DISPLAY_CAN_ROTATE=0
867 DISPLAY_ORIENTATION=0
868 DISPLAY_DPI=133
Brad Bishop316dfdd2018-06-25 12:45:53 -0400869 </literallayout>
870 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500871
Brad Bishop316dfdd2018-06-25 12:45:53 -0400872 <note><para>
873 If a BSP does not have a formfactor entry, defaults
874 are established according to the formfactor
875 configuration file that is installed by the main
876 formfactor recipe
877 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
878 which is found in the
879 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
880 </para></note>
881 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500882
Brad Bishop316dfdd2018-06-25 12:45:53 -0400883 <section id='bsp-filelayout-recipes-graphics'>
884 <title>Display Support Files</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500885
Brad Bishop316dfdd2018-06-25 12:45:53 -0400886 <para>
887 You can find these files in the BSP Layer at:
888 <literallayout class='monospaced'>
889 meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
890 </literallayout>
891 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500892
Brad Bishop316dfdd2018-06-25 12:45:53 -0400893 <para>
894 This optional directory contains recipes for the
895 BSP if it has special requirements for graphics
896 support.
897 All files that are needed for the BSP to support
898 a display are kept here.
899 </para>
900 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500901
Brad Bishop316dfdd2018-06-25 12:45:53 -0400902 <section id='bsp-filelayout-kernel'>
903 <title>Linux Kernel Configuration</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500904
Brad Bishop316dfdd2018-06-25 12:45:53 -0400905 <para>
906 You can find these files in the BSP Layer at:
907 <literallayout class='monospaced'>
908 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend
909 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb
910 </literallayout>
911 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500912
Brad Bishop316dfdd2018-06-25 12:45:53 -0400913 <para>
914 Append files (<filename>*.bbappend</filename>) modify
915 the main kernel recipe being used to build the image.
916 The <filename>*.bb</filename> files would be a
917 developer-supplied kernel recipe.
918 This area of the BSP hierarchy can contain both these
Andrew Geissler82c905d2020-04-13 13:39:40 -0500919 types of files although, in practice, it is likely that
Brad Bishop316dfdd2018-06-25 12:45:53 -0400920 you would have one or the other.
921 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500922
Brad Bishop316dfdd2018-06-25 12:45:53 -0400923 <para>
924 For your BSP, you typically want to use an existing Yocto
925 Project kernel recipe found in the
926 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
927 at <filename>meta/recipes-kernel/linux</filename>.
928 You can append machine-specific changes to the
929 kernel recipe by using a similarly named append
930 file, which is located in the BSP Layer for your
931 target device (e.g. the
932 <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory).
933 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500934
Brad Bishop316dfdd2018-06-25 12:45:53 -0400935 <para>
936 Suppose you are using the
937 <filename>linux-yocto_4.4.bb</filename> recipe to
938 build the kernel.
939 In other words, you have selected the kernel in your
940 <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
941 file by adding
942 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
943 and
944 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
945 statements as follows:
946 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500947 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500948 PREFERRED_VERSION_linux-yocto ?= "4.4%"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400949 </literallayout>
950 <note>
951 When the preferred provider is assumed by
952 default, the
953 <filename>PREFERRED_PROVIDER</filename>
954 statement does not appear in the
955 <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file.
956 </note>
957 You would use the
958 <filename>linux-yocto_4.4.bbappend</filename>
959 file to append specific BSP settings to the kernel,
960 thus configuring the kernel for your particular BSP.
961 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500962
Brad Bishop316dfdd2018-06-25 12:45:53 -0400963 <para>
964 You can find more information on what your append file
965 should contain in the
966 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file'>Creating the Append File</ulink>"
967 section in the Yocto Project Linux Kernel Development
968 Manual.
969 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500970
Brad Bishop316dfdd2018-06-25 12:45:53 -0400971 <para>
972 An alternate scenario is when you create your own
973 kernel recipe for the BSP.
974 A good example of this is the Raspberry Pi BSP.
975 If you examine the
976 <filename>recipes-kernel/linux</filename> directory
977 you see the following:
978 <literallayout class='monospaced'>
979 linux-raspberrypi-dev.bb
980 linux-raspberrypi.inc
981 linux-raspberrypi_4.14.bb
982 linux-raspberrypi_4.9.bb
983 </literallayout>
984 The directory contains three kernel recipes and a
985 common include file.
986 </para>
987 </section>
988</section>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500989
Brad Bishop316dfdd2018-06-25 12:45:53 -0400990<section id='developing-a-board-support-package-bsp'>
991 <title>Developing a Board Support Package (BSP)</title>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500992
Brad Bishop316dfdd2018-06-25 12:45:53 -0400993 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500994 This section describes the high-level procedure you can
Brad Bishop316dfdd2018-06-25 12:45:53 -0400995 follow to create a BSP.
996 Although not required for BSP creation, the
997 <filename>meta-intel</filename> repository, which
998 contains many BSPs supported by the Yocto Project,
999 is part of the example.
1000 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001001
Brad Bishop316dfdd2018-06-25 12:45:53 -04001002 <para>
1003 For an example that shows how to create a new
1004 layer using the tools, see the
1005 "<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>"
1006 section.
1007 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001008
Brad Bishop316dfdd2018-06-25 12:45:53 -04001009 <para>
1010 The following illustration and list summarize the BSP
1011 creation general workflow.
1012 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001013
Brad Bishop316dfdd2018-06-25 12:45:53 -04001014 <para>
1015 <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
1016 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001017
Brad Bishop316dfdd2018-06-25 12:45:53 -04001018 <para>
1019 <orderedlist>
1020 <listitem><para>
1021 <emphasis>Set up Your Host Development System
1022 to Support Development Using the Yocto
1023 Project</emphasis>:
1024 See the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001025 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04001026 section in the Yocto Project Development Tasks
1027 Manual for options on how to get a system ready
1028 to use the Yocto Project.
1029 </para></listitem>
1030 <listitem><para>
1031 <emphasis>Establish the
1032 <filename>meta-intel</filename>
1033 Repository on Your System:</emphasis>
1034 Having local copies of these supported BSP layers
1035 on your system gives you access to layers you
1036 might be able to leverage when creating your BSP.
1037 For information on how to get these files, see the
1038 "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
1039 section.
1040 </para></listitem>
1041 <listitem><para>
1042 <emphasis>Create Your Own BSP Layer Using the
1043 <filename>bitbake-layers</filename>
1044 Script:</emphasis>
1045 Layers are ideal for isolating and storing work
1046 for a given piece of hardware.
1047 A layer is really just a location or area in which you
1048 place the recipes and configurations for your BSP.
1049 In fact, a BSP is, in itself, a special type of layer.
1050 The simplest way to create a new BSP layer that is
1051 compliant with the Yocto Project is to use the
1052 <filename>bitbake-layers</filename> script.
1053 For information about that script, see the
1054 "<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>"
1055 section.</para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001056
Brad Bishop316dfdd2018-06-25 12:45:53 -04001057 <para>Another example that illustrates a layer
1058 is an application.
1059 Suppose you are creating an application that has
1060 library or other dependencies in order for it to
1061 compile and run.
1062 The layer, in this case, would be where all the
1063 recipes that define those dependencies are kept.
1064 The key point for a layer is that it is an
1065 isolated area that contains all the relevant
1066 information for the project that the
1067 OpenEmbedded build system knows about.
1068 For more information on layers, see the
1069 "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
1070 section in the Yocto Project Overview and Concepts
1071 Manual.
1072 You can also reference the
1073 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1074 section in the Yocto Project Development Tasks
1075 Manual.
1076 For more information on BSP layers, see the
1077 "<link linkend='bsp-layers'>BSP Layers</link>"
1078 section.
1079 <note><title>Notes</title>
1080 <itemizedlist>
1081 <listitem><para>
1082 Five hardware reference BSPs exist
1083 that are part of the Yocto Project release
1084 and are located in the
1085 <filename>poky/meta-yocto-bsp</filename> BSP
1086 layer:
1087 <itemizedlist>
1088 <listitem><para>
1089 Texas Instruments Beaglebone
1090 (<filename>beaglebone-yocto</filename>)
1091 </para></listitem>
1092 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001093 Ubiquiti Networks EdgeRouter Lite
1094 (<filename>edgerouter</filename>)
1095 </para></listitem>
1096 <listitem><para>
1097 Two general IA platforms
1098 (<filename>genericx86</filename> and
1099 <filename>genericx86-64</filename>)
1100 </para></listitem>
1101 </itemizedlist>
1102 </para></listitem>
1103 <listitem><para>
1104 Three core Intel BSPs exist as part of
1105 the Yocto Project release in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001106 <filename>meta-intel</filename> layer:
1107 <itemizedlist>
1108 <listitem><para>
1109 <filename>intel-core2-32</filename>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04001110 which is a BSP optimized for the Core2
1111 family of CPUs as well as all CPUs
1112 prior to the Silvermont core.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001113 </para></listitem>
1114 <listitem><para>
1115 <filename>intel-corei7-64</filename>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04001116 which is a BSP optimized for Nehalem
1117 and later Core and Xeon CPUs as well
1118 as Silvermont and later Atom CPUs,
1119 such as the Baytrail SoCs.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001120 </para></listitem>
1121 <listitem><para>
1122 <filename>intel-quark</filename>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04001123 which is a BSP optimized for the
1124 Intel Galileo gen1 &amp; gen2
1125 development boards.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001126 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001127 </itemizedlist>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001128 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001129 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001130 </note></para>
1131
1132 <para>When you set up a layer for a new BSP,
1133 you should follow a standard layout.
1134 This layout is described in the
1135 "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
1136 section.
1137 In the standard layout, notice the suggested
1138 structure for recipes and configuration
1139 information.
1140 You can see the standard layout for a BSP
1141 by examining any supported BSP found in the
1142 <filename>meta-intel</filename> layer inside
1143 the Source Directory.
1144 </para></listitem>
1145 <listitem><para>
1146 <emphasis>Make Configuration Changes to Your New
1147 BSP Layer:</emphasis>
1148 The standard BSP layer structure organizes the
1149 files you need to edit in
1150 <filename>conf</filename> and several
1151 <filename>recipes-*</filename> directories
1152 within the BSP layer.
1153 Configuration changes identify where your new
1154 layer is on the local system and identifies the
1155 kernel you are going to use.
1156 When you run the
1157 <filename>bitbake-layers</filename> script,
1158 you are able to interactively configure many
1159 things for the BSP (e.g. keyboard, touchscreen,
1160 and so forth).
1161 </para></listitem>
1162 <listitem><para>
1163 <emphasis>Make Recipe Changes to Your New BSP
1164 Layer:</emphasis>
1165 Recipe changes include altering recipes
1166 (<filename>*.bb</filename> files), removing
1167 recipes you do not use, and adding new recipes
1168 or append files (<filename>.bbappend</filename>)
1169 that support your hardware.
1170 </para></listitem>
1171 <listitem><para>
1172 <emphasis>Prepare for the Build:</emphasis>
1173 Once you have made all the changes to your BSP
1174 layer, there remains a few things you need to
1175 do for the OpenEmbedded build system in order
1176 for it to create your image.
1177 You need to get the build environment ready by
1178 sourcing an environment setup script
1179 (i.e. <filename>oe-init-build-env</filename>)
1180 and you need to be sure two key configuration
1181 files are configured appropriately: the
1182 <filename>conf/local.conf</filename> and the
1183 <filename>conf/bblayers.conf</filename> file.
1184 You must make the OpenEmbedded build system aware
1185 of your new layer.
1186 See the
1187 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1188 section in the Yocto Project Development Tasks Manual
1189 for information on how to let the build system
1190 know about your new layer.
1191 </para></listitem>
1192 <listitem><para>
1193 <emphasis>Build the Image:</emphasis>
1194 The OpenEmbedded build system uses the BitBake tool
1195 to build images based on the type of image you want to
1196 create.
1197 You can find more information about BitBake in the
1198 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001199 </para>
1200
Brad Bishop316dfdd2018-06-25 12:45:53 -04001201 <para>The build process supports several types of
1202 images to satisfy different needs.
1203 See the
1204 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1205 chapter in the Yocto Project Reference Manual for
1206 information on supported images.
1207 </para></listitem>
1208 </orderedlist>
1209 </para>
1210</section>
1211
1212<section id='requirements-and-recommendations-for-released-bsps'>
1213 <title>Requirements and Recommendations for Released BSPs</title>
1214
1215 <para>
1216 Certain requirements exist for a released BSP to be
1217 considered compliant with the Yocto Project.
1218 Additionally, recommendations also exist.
1219 This section describes the requirements and
1220 recommendations for released BSPs.
1221 </para>
1222
1223 <section id='released-bsp-requirements'>
1224 <title>Released BSP Requirements</title>
1225
1226 <para>
1227 Before looking at BSP requirements, you should consider
1228 the following:
1229 <itemizedlist>
1230 <listitem><para>
1231 The requirements here assume the BSP layer
1232 is a well-formed, "legal" layer that can be
1233 added to the Yocto Project.
1234 For guidelines on creating a layer that meets
1235 these base requirements, see the
1236 "<link linkend='bsp-layers'>BSP Layers</link>"
1237 section in this manual and the
1238 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>"
1239 section in the Yocto Project Development Tasks
1240 Manual.
1241 </para></listitem>
1242 <listitem><para>
1243 The requirements in this section apply
1244 regardless of how you package a BSP.
1245 You should consult the packaging and distribution
1246 guidelines for your specific release process.
1247 For an example of packaging and distribution
1248 requirements, see the
1249 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
1250 wiki page.
1251 </para></listitem>
1252 <listitem><para>
1253 The requirements for the BSP as it is made
1254 available to a developer are completely
1255 independent of the released form of the BSP.
1256 For example, the BSP Metadata can be contained
1257 within a Git repository and could have a directory
1258 structure completely different from what appears
1259 in the officially released BSP layer.
1260 </para></listitem>
1261 <listitem><para>
1262 It is not required that specific packages or
1263 package modifications exist in the BSP layer,
1264 beyond the requirements for general
1265 compliance with the Yocto Project.
1266 For example, no requirement exists dictating
1267 that a specific kernel or kernel version be
1268 used in a given BSP.
1269 </para></listitem>
1270 </itemizedlist>
1271 </para>
1272
1273 <para>
1274 Following are the requirements for a released BSP
1275 that conform to the Yocto Project:
1276 <itemizedlist>
1277 <listitem><para>
1278 <emphasis>Layer Name:</emphasis>
1279 The BSP must have a layer name that follows
1280 the Yocto Project standards.
1281 For information on BSP layer names, see the
1282 "<link linkend='bsp-layers'>BSP Layers</link>" section.
1283 </para></listitem>
1284 <listitem><para>
1285 <emphasis>File System Layout:</emphasis>
1286 When possible, use the same directory names
1287 in your BSP layer as listed in the
1288 <filename>recipes.txt</filename> file, which
1289 is found in <filename>poky/meta</filename>
1290 directory of the
1291 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1292 or in the OpenEmbedded-Core Layer
1293 (<filename>openembedded-core</filename>) at
1294 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
1295 </para>
1296
1297 <para>You should place recipes
1298 (<filename>*.bb</filename> files) and recipe
1299 modifications (<filename>*.bbappend</filename>
1300 files) into <filename>recipes-*</filename>
1301 subdirectories by functional area as outlined
1302 in <filename>recipes.txt</filename>.
1303 If you cannot find a category in
1304 <filename>recipes.txt</filename> to fit a
1305 particular recipe, you can make up your own
1306 <filename>recipes-*</filename> subdirectory.
1307 </para>
1308
1309 <para>Within any particular
1310 <filename>recipes-*</filename> category, the
1311 layout should match what is found in the
1312 OpenEmbedded-Core Git repository
1313 (<filename>openembedded-core</filename>)
1314 or the Source Directory (<filename>poky</filename>).
1315 In other words, make sure you place related
Andrew Geissler82c905d2020-04-13 13:39:40 -05001316 files in appropriately-related
Brad Bishop316dfdd2018-06-25 12:45:53 -04001317 <filename>recipes-*</filename> subdirectories
1318 specific to the recipe's function, or within
1319 a subdirectory containing a set of closely-related
1320 recipes.
1321 The recipes themselves should follow the general
1322 guidelines for recipes used in the Yocto Project
1323 found in the
1324 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
1325 </para></listitem>
1326 <listitem><para>
1327 <emphasis>License File:</emphasis>
1328 You must include a license file in the
1329 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1330 directory.
1331 This license covers the BSP Metadata as a whole.
1332 You must specify which license to use since no
Andrew Geissler82c905d2020-04-13 13:39:40 -05001333 default license exists when one is not specified.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001334 See the
1335 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
1336 file for the Raspberry Pi BSP in the
1337 <filename>meta-raspberrypi</filename> BSP layer
1338 as an example.
1339 </para></listitem>
1340 <listitem><para>
1341 <emphasis>README File:</emphasis>
1342 You must include a <filename>README</filename>
1343 file in the
1344 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1345 directory.
1346 See the
1347 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md'><filename>README.md</filename></ulink>
1348 file for the Raspberry Pi BSP in the
1349 <filename>meta-raspberrypi</filename> BSP layer
1350 as an example.</para>
1351
1352 <para>At a minimum, the <filename>README</filename>
1353 file should contain the following:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001354 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001355 <listitem><para>
Andrew Geissler82c905d2020-04-13 13:39:40 -05001356 A brief description of the target hardware.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001357 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001358 <listitem><para>
Andrew Geissler82c905d2020-04-13 13:39:40 -05001359 A list of all the dependencies of the BSP.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001360 These dependencies are typically a list
1361 of required layers needed to build the
1362 BSP.
1363 However, the dependencies should also
1364 contain information regarding any other
1365 dependencies the BSP might have.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001366 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001367 <listitem><para>
1368 Any required special licensing information.
1369 For example, this information includes
1370 information on special variables needed
1371 to satisfy a EULA, or instructions on
1372 information needed to build or distribute
1373 binaries built from the BSP Metadata.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001374 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001375 <listitem><para>
1376 The name and contact information for the
1377 BSP layer maintainer.
1378 This is the person to whom patches and
1379 questions should be sent.
1380 For information on how to find the right
1381 person, see the
1382 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
1383 section in the Yocto Project Development
1384 Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001385 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001386 <listitem><para>
1387 Instructions on how to build the BSP using
1388 the BSP layer.
1389 </para></listitem>
1390 <listitem><para>
1391 Instructions on how to boot the BSP build
1392 from the BSP layer.
1393 </para></listitem>
1394 <listitem><para>
1395 Instructions on how to boot the binary
1396 images contained in the
1397 <filename>binary</filename> directory,
1398 if present.
1399 </para></listitem>
1400 <listitem><para>
1401 Information on any known bugs or issues
1402 that users should know about when either
1403 building or booting the BSP binaries.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001404 </para></listitem>
1405 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001406 </para></listitem>
1407 <listitem><para>
1408 <emphasis>README.sources File:</emphasis>
1409 If you BSP contains binary images in the
1410 <filename>binary</filename> directory, you must
1411 include a <filename>README.sources</filename>
1412 file in the
1413 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1414 directory.
1415 This file specifies exactly where you can find
1416 the sources used to generate the binary images.
1417 </para></listitem>
1418 <listitem><para>
1419 <emphasis>Layer Configuration File:</emphasis>
1420 You must include a
1421 <filename>conf/layer.conf</filename> file in
1422 the
1423 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1424 directory.
1425 This file identifies the
1426 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1427 BSP layer as a layer to the build system.
1428 </para></listitem>
1429 <listitem><para>
1430 <emphasis>Machine Configuration File:</emphasis>
1431 You must include one or more
1432 <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1433 files in the
1434 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1435 directory.
1436 These configuration files define machine targets
1437 that can be built using the BSP layer.
1438 Multiple machine configuration files define
1439 variations of machine configurations that the
1440 BSP supports.
1441 If a BSP supports multiple machine variations,
1442 you need to adequately describe each variation
1443 in the BSP <filename>README</filename> file.
1444 Do not use multiple machine configuration files
1445 to describe disparate hardware.
1446 If you do have very different targets, you should
1447 create separate BSP layers for each target.
1448 <note>
1449 It is completely possible for a developer to
1450 structure the working repository as a
1451 conglomeration of unrelated BSP files, and to
1452 possibly generate BSPs targeted for release
1453 from that directory using scripts or some
1454 other mechanism
1455 (e.g. <filename>meta-yocto-bsp</filename> layer).
1456 Such considerations are outside the scope of
1457 this document.
1458 </note>
1459 </para></listitem>
1460 </itemizedlist>
1461 </para>
1462 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001463
Brad Bishop316dfdd2018-06-25 12:45:53 -04001464 <section id='released-bsp-recommendations'>
1465 <title>Released BSP Recommendations</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001466
Brad Bishop316dfdd2018-06-25 12:45:53 -04001467 <para>
1468 Following are recommendations for released BSPs that
1469 conform to the Yocto Project:
1470 <itemizedlist>
1471 <listitem><para>
1472 <emphasis>Bootable Images:</emphasis>
1473 Released BSPs can contain one or more bootable
1474 images.
1475 Including bootable images allows users to easily
1476 try out the BSP using their own hardware.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001477
Brad Bishop316dfdd2018-06-25 12:45:53 -04001478 <para>In some cases, it might not be convenient
1479 to include a bootable image.
1480 If so, you might want to make two versions of the
1481 BSP available: one that contains binary images, and
1482 one that does not.
1483 The version that does not contain bootable images
1484 avoids unnecessary download times for users not
1485 interested in the images.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001486
Brad Bishop316dfdd2018-06-25 12:45:53 -04001487 <para>If you need to distribute a BSP and include
1488 bootable images or build kernel and filesystems
1489 meant to allow users to boot the BSP for evaluation
1490 purposes, you should put the images and artifacts
1491 within a
1492 <filename>binary/</filename> subdirectory located
1493 in the
1494 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1495 directory.
1496 <note>
1497 If you do include a bootable image as part
1498 of the BSP and the image was built by software
1499 covered by the GPL or other open source licenses,
1500 it is your responsibility to understand
1501 and meet all licensing requirements, which could
1502 include distribution of source files.
1503 </note>
1504 </para></listitem>
1505 <listitem><para>
1506 <emphasis>Use a Yocto Linux Kernel:</emphasis>
1507 Kernel recipes in the BSP should be based on a
1508 Yocto Linux kernel.
1509 Basing your recipes on these kernels reduces
1510 the costs for maintaining the BSP and increases
1511 its scalability.
1512 See the <filename>Yocto Linux Kernel</filename>
1513 category in the
1514 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1515 for these kernels.
1516 </para></listitem>
1517 </itemizedlist>
1518 </para>
1519 </section>
1520</section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001521
Brad Bishop316dfdd2018-06-25 12:45:53 -04001522<section id='customizing-a-recipe-for-a-bsp'>
1523 <title>Customizing a Recipe for a BSP</title>
1524
1525 <para>
1526 If you plan on customizing a recipe for a particular BSP,
1527 you need to do the following:
1528 <itemizedlist>
1529 <listitem><para>
1530 Create a <filename>*.bbappend</filename> file for
1531 the modified recipe.
1532 For information on using append files, see the
1533 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
1534 section in the Yocto Project Development Tasks
1535 Manual.
1536 </para></listitem>
1537 <listitem><para>
1538 Ensure your directory structure in the BSP layer
1539 that supports your machine is such that the
1540 OpenEmbedded build system can find it.
1541 See the example later in this section for more
1542 information.
1543 </para></listitem>
1544 <listitem><para>
1545 Put the append file in a directory whose name matches
1546 the machine's name and is located in an appropriate
1547 sub-directory inside the BSP layer (i.e.
1548 <filename>recipes-bsp</filename>,
1549 <filename>recipes-graphics</filename>,
1550 <filename>recipes-core</filename>, and so forth).
1551 </para></listitem>
1552 <listitem><para>
1553 Place the BSP-specific files in the proper
1554 directory inside the BSP layer.
1555 How expansive the layer is affects where you must
1556 place these files.
1557 For example, if your layer supports several
1558 different machine types, you need to be sure your
1559 layer's directory structure includes hierarchy
1560 that separates the files according to machine.
1561 If your layer does not support multiple machines,
1562 the layer would not have that additional hierarchy
1563 and the files would obviously not be able to reside
1564 in a machine-specific directory.
1565 </para></listitem>
1566 </itemizedlist>
1567 </para>
1568
1569 <para>
1570 Following is a specific example to help you better understand
1571 the process.
1572 This example customizes customizes a recipe by adding a
1573 BSP-specific configuration file named
1574 <filename>interfaces</filename> to the
1575 <filename>init-ifupdown_1.0.bb</filename> recipe for machine
1576 "xyz" where the BSP layer also supports several other
1577 machines:
1578 <orderedlist>
1579 <listitem><para>
1580 Edit the
1581 <filename>init-ifupdown_1.0.bbappend</filename> file
1582 so that it contains the following:
1583 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001584 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
Brad Bishop316dfdd2018-06-25 12:45:53 -04001585 </literallayout>
1586 The append file needs to be in the
1587 <filename>meta-xyz/recipes-core/init-ifupdown</filename>
1588 directory.
1589 </para></listitem>
1590 <listitem><para>
1591 Create and place the new
1592 <filename>interfaces</filename> configuration file in
1593 the BSP's layer here:
1594 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001595 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
Brad Bishop316dfdd2018-06-25 12:45:53 -04001596 </literallayout>
1597 <note>
1598 If the <filename>meta-xyz</filename> layer did
1599 not support multiple machines, you would place
1600 the <filename>interfaces</filename> configuration
1601 file in the layer here:
1602 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001603 meta-xyz/recipes-core/init-ifupdown/files/interfaces
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001604 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001605 </note>
1606 The
1607 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1608 variable in the append files extends the search path
1609 the build system uses to find files during the build.
1610 Consequently, for this example you need to have the
1611 <filename>files</filename> directory in the same
1612 location as your append file.
1613 </para></listitem>
1614 </orderedlist>
1615 </para>
1616</section>
1617
1618<section id='bsp-licensing-considerations'>
1619 <title>BSP Licensing Considerations</title>
1620
1621 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -05001622 In some cases, a BSP contains separately-licensed
Brad Bishop316dfdd2018-06-25 12:45:53 -04001623 Intellectual Property (IP) for a component or components.
1624 For these cases, you are required to accept the terms
1625 of a commercial or other type of license that requires
1626 some kind of explicit End User License Agreement (EULA).
1627 Once you accept the license, the OpenEmbedded build system
1628 can then build and include the corresponding component
1629 in the final BSP image.
1630 If the BSP is available as a pre-built image, you can
1631 download the image after agreeing to the license or EULA.
1632 </para>
1633
1634 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -05001635 You could find that some separately-licensed components
Brad Bishop316dfdd2018-06-25 12:45:53 -04001636 that are essential for normal operation of the system might
1637 not have an unencumbered (or free) substitute.
1638 Without these essential components, the system would be
1639 non-functional.
1640 Then again, you might find that other licensed components
1641 that are simply 'good-to-have' or purely elective do have
1642 an unencumbered, free replacement component that you can
Andrew Geissler82c905d2020-04-13 13:39:40 -05001643 use rather than agreeing to the separately-licensed
Brad Bishop316dfdd2018-06-25 12:45:53 -04001644 component.
1645 Even for components essential to the system, you might
1646 find an unencumbered component that is not identical but
1647 will work as a less-capable version of the licensed version
1648 in the BSP recipe.
1649 </para>
1650
1651 <para>
1652 For cases where you can substitute a free component and
1653 still maintain the system's functionality, the "DOWNLOADS"
1654 selection from the "SOFTWARE" tab on the
1655 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>
1656 makes available de-featured BSPs that are completely free
1657 of any IP encumbrances.
1658 For these cases, you can use the substitution directly and
1659 without any further licensing requirements.
1660 If present, these fully de-featured BSPs are named
1661 appropriately different as compared to the names of their
1662 respective encumbered BSPs.
1663 If available, these substitutions are your simplest and
1664 most preferred options.
1665 Obviously, use of these substitutions assumes the resulting
1666 functionality meets system requirements.
1667 <note>
1668 If however, a non-encumbered version is unavailable or
1669 it provides unsuitable functionality or quality, you can
1670 use an encumbered version.
1671 </note>
1672 </para>
1673
1674 <para>
1675 A couple different methods exist within the OpenEmbedded
1676 build system to satisfy the licensing requirements for an
1677 encumbered BSP.
1678 The following list describes them in order of preference:
1679 <orderedlist>
1680 <listitem><para>
1681 <emphasis>Use the
1682 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1683 Variable to Define the Recipes that Have Commercial
1684 or Other Types of Specially-Licensed Packages:</emphasis>
1685 For each of those recipes, you can specify a
1686 matching license string in a
1687 <filename>local.conf</filename> variable named
1688 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
1689 Specifying the matching license string signifies
1690 that you agree to the license.
1691 Thus, the build system can build the corresponding
1692 recipe and include the component in the image.
1693 See the
1694 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
1695 section in the Yocto Project Development Tasks
1696 Manual for details on how to use these variables.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001697 </para>
1698
Brad Bishop316dfdd2018-06-25 12:45:53 -04001699 <para>If you build as you normally would, without
1700 specifying any recipes in the
1701 <filename>LICENSE_FLAGS_WHITELIST</filename>, the
1702 build stops and provides you with the list of recipes
1703 that you have tried to include in the image that
1704 need entries in the
1705 <filename>LICENSE_FLAGS_WHITELIST</filename>.
1706 Once you enter the appropriate license flags into
1707 the whitelist, restart the build to continue where
1708 it left off.
1709 During the build, the prompt will not appear again
1710 since you have satisfied the requirement.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001711
Brad Bishop316dfdd2018-06-25 12:45:53 -04001712 <para>Once the appropriate license flags are on the
1713 white list in the
1714 <filename>LICENSE_FLAGS_WHITELIST</filename> variable,
1715 you can build the encumbered image with no change
1716 at all to the normal build process.
1717 </para></listitem>
1718 <listitem><para>
1719 <emphasis>Get a Pre-Built Version of the BSP:</emphasis>
1720 You can get this type of BSP by selecting the
1721 "DOWNLOADS" item from the "SOFTWARE" tab on the
1722 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1723 You can download BSP tarballs that contain
1724 proprietary components after agreeing to the
1725 licensing requirements of each of the individually
1726 encumbered packages as part of the download process.
1727 Obtaining the BSP this way allows you to access an
1728 encumbered image immediately after agreeing to the
1729 click-through license agreements presented by the
1730 website.
1731 If you want to build the image yourself using
1732 the recipes contained within the BSP tarball,
1733 you will still need to create an appropriate
1734 <filename>LICENSE_FLAGS_WHITELIST</filename>
1735 to match the encumbered recipes in the BSP.
1736 </para></listitem>
1737 </orderedlist>
1738 <note>
1739 Pre-compiled images are bundled with a time-limited
1740 kernel that runs for a predetermined amount of time
1741 (10 days) before it forces the system to reboot.
1742 This limitation is meant to discourage direct
1743 redistribution of the image.
1744 You must eventually rebuild the image if you want
1745 to remove this restriction.
1746 </note>
1747 </para>
1748</section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001749
Brad Bishop316dfdd2018-06-25 12:45:53 -04001750<section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>
1751 <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001752
Brad Bishop316dfdd2018-06-25 12:45:53 -04001753 <para>
1754 The <filename>bitbake-layers create-layer</filename> script
1755 automates creating a BSP layer.
Andrew Geissler82c905d2020-04-13 13:39:40 -05001756 What makes a layer a "BSP layer" is the presence of at least one machine
Brad Bishop316dfdd2018-06-25 12:45:53 -04001757 configuration file.
1758 Additionally, a BSP layer usually has a kernel recipe
1759 or an append file that leverages off an existing kernel recipe.
1760 The primary requirement, however, is the machine configuration.
1761 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001762
Brad Bishop316dfdd2018-06-25 12:45:53 -04001763 <para>
1764 Use these steps to create a BSP layer:
1765 <itemizedlist>
1766 <listitem><para>
1767 <emphasis>Create a General Layer:</emphasis>
1768 Use the <filename>bitbake-layers</filename> script with the
1769 <filename>create-layer</filename> subcommand to create a
1770 new general layer.
1771 For instructions on how to create a general layer using the
1772 <filename>bitbake-layers</filename> script, see the
1773 "<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>"
1774 section in the Yocto Project Development Tasks Manual.
1775 </para></listitem>
1776 <listitem><para>
1777 <emphasis>Create a Layer Configuration File:</emphasis>
1778 Every layer needs a layer configuration file.
1779 This configuration file establishes locations for the
1780 layer's recipes, priorities for the layer, and so forth.
1781 You can find examples of <filename>layer.conf</filename>
1782 files in the Yocto Project
1783 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
1784 To get examples of what you need in your configuration
1785 file, locate a layer (e.g. "meta-ti") and examine the
1786 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink>
1787 file.
1788 </para></listitem>
1789 <listitem><para>
1790 <emphasis>Create a Machine Configuration File:</emphasis>
1791 Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1792 file.
1793 See
1794 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink>
1795 for sample
1796 <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1797 files.
1798 Other samples such as
1799 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink>
1800 and
1801 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink>
1802 exist from other vendors that have more specific machine
1803 and tuning examples.
1804 </para></listitem>
1805 <listitem><para>
1806 <emphasis>Create a Kernel Recipe:</emphasis>
1807 Create a kernel recipe in <filename>recipes-kernel/linux</filename>
1808 by either using a kernel append file or a new custom kernel
1809 recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>).
1810 The BSP layers mentioned in the previous step also contain different
1811 kernel examples.
1812 See the
1813 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
1814 section in the Yocto Project Linux Kernel Development Manual
1815 for information on how to create a custom kernel.
1816 </para></listitem>
1817 </itemizedlist>
1818 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001819
Brad Bishop316dfdd2018-06-25 12:45:53 -04001820 <para>
1821 The remainder of this section provides a description of
1822 the Yocto Project reference BSP for Beaglebone, which
1823 resides in the
Brad Bishopc342db32019-05-15 21:57:59 -04001824 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink>
1825 layer.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001826 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001827
Brad Bishop316dfdd2018-06-25 12:45:53 -04001828 <section id='bsp-layer-configuration-example'>
1829 <title>BSP Layer Configuration Example</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001830
Brad Bishop316dfdd2018-06-25 12:45:53 -04001831 <para>
1832 The layer's <filename>conf</filename> directory
1833 contains the <filename>layer.conf</filename>
1834 configuration file.
1835 In this example, the
1836 <filename>conf/layer.conf</filename> is the
1837 following:
1838 <literallayout class='monospaced'>
1839 # We have a conf and classes directory, add to BBPATH
1840 BBPATH .= ":${LAYERDIR}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001841
Brad Bishop316dfdd2018-06-25 12:45:53 -04001842 # We have recipes-* directories, add to BBFILES
1843 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1844 ${LAYERDIR}/recipes-*/*/*.bbappend"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001845
Brad Bishop316dfdd2018-06-25 12:45:53 -04001846 BBFILE_COLLECTIONS += "yoctobsp"
1847 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
1848 BBFILE_PRIORITY_yoctobsp = "5"
1849 LAYERVERSION_yoctobsp = "4"
1850 LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
1851 </literallayout>
1852 The variables used in this file configure the
1853 layer.
1854 A good way to learn about layer configuration
1855 files is to examine various files for BSP from
1856 the
1857 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
1858 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001859
Brad Bishop316dfdd2018-06-25 12:45:53 -04001860 <para>
1861 For a detailed description of this particular
1862 layer configuration file, see
1863 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink>
1864 in the discussion that describes how to create
1865 layers in the Yocto Project Development Tasks Manual.
1866 </para>
1867 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001868
Brad Bishop316dfdd2018-06-25 12:45:53 -04001869 <section id='bsp-machine-configuration-example'>
1870 <title>BSP Machine Configuration Example</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001871
Brad Bishop316dfdd2018-06-25 12:45:53 -04001872 <para>
1873 As mentioned earlier in this section, the existence
1874 of a machine configuration file is what makes a
1875 layer a BSP layer as compared to a general or
1876 kernel layer.
1877 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001878
Brad Bishop316dfdd2018-06-25 12:45:53 -04001879 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -05001880 One or more machine configuration files exist in the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001881 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
1882 directory of the layer:
1883 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -05001884 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine1</replaceable><filename>.conf</filename>
1885 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine2</replaceable><filename>.conf</filename>
1886 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine3</replaceable><filename>.conf</filename>
1887 ... more ...
Brad Bishop316dfdd2018-06-25 12:45:53 -04001888 </literallayout>
1889 For example, the machine configuration file for the
1890 <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
Brad Bishopc342db32019-05-15 21:57:59 -04001891 is located in the layer
Brad Bishop316dfdd2018-06-25 12:45:53 -04001892 <filename>poky/meta-yocto-bsp/conf/machine</filename>
1893 and is named <filename>beaglebone-yocto.conf</filename>:
1894 <literallayout class='monospaced'>
1895 #@TYPE: Machine
1896 #@NAME: Beaglebone-yocto machine
1897 #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001898
Brad Bishop316dfdd2018-06-25 12:45:53 -04001899 PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
1900 XSERVER ?= "xserver-xorg \
1901 xf86-video-modesetting \
1902 "
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001903
Brad Bishop316dfdd2018-06-25 12:45:53 -04001904 MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001905
Brad Bishop316dfdd2018-06-25 12:45:53 -04001906 EXTRA_IMAGEDEPENDS += "u-boot"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001907
Brad Bishop316dfdd2018-06-25 12:45:53 -04001908 DEFAULTTUNE ?= "cortexa8hf-neon"
1909 include conf/machine/include/tune-cortexa8.inc
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001910
Brad Bishop316dfdd2018-06-25 12:45:53 -04001911 IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap"
1912 EXTRA_IMAGECMD_jffs2 = "-lnp "
1913 WKS_FILE ?= "beaglebone-yocto.wks"
1914 IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage"
1915 do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001916
Brad Bishopc342db32019-05-15 21:57:59 -04001917 SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0"
1918 SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}"
Brad Bishop316dfdd2018-06-25 12:45:53 -04001919
1920 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Brad Bishopc342db32019-05-15 21:57:59 -04001921 PREFERRED_VERSION_linux-yocto ?= "5.0%"
Brad Bishop316dfdd2018-06-25 12:45:53 -04001922
1923 KERNEL_IMAGETYPE = "zImage"
1924 KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
1925 KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
1926
1927 SPL_BINARY = "MLO"
1928 UBOOT_SUFFIX = "img"
Brad Bishopc342db32019-05-15 21:57:59 -04001929 UBOOT_MACHINE = "am335x_evm_defconfig"
Brad Bishop316dfdd2018-06-25 12:45:53 -04001930 UBOOT_ENTRYPOINT = "0x80008000"
1931 UBOOT_LOADADDRESS = "0x80008000"
1932
1933 MACHINE_FEATURES = "usbgadget usbhost vfat alsa"
1934
Brad Bishopc342db32019-05-15 21:57:59 -04001935 IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
Brad Bishop316dfdd2018-06-25 12:45:53 -04001936 </literallayout>
1937 The variables used to configure the machine define
Andrew Geissler82c905d2020-04-13 13:39:40 -05001938 machine-specific properties;
1939 for example, machine-dependent packages, machine
Brad Bishop316dfdd2018-06-25 12:45:53 -04001940 tunings, the type of kernel to build, and
1941 U-Boot configurations.
1942 </para>
1943
1944 <para>
1945 The following list provides some explanation
1946 for the statements found in the example reference
1947 machine configuration file for the BeagleBone
1948 development boards.
1949 Realize that much more can be defined as part of
Andrew Geissler82c905d2020-04-13 13:39:40 -05001950 a machine's configuration file.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001951 In general, you can learn about related variables
1952 that this example does not have by locating the
1953 variables in the
1954 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>"
1955 in the Yocto Project Reference Manual.
1956 <itemizedlist>
1957 <listitem><para>
1958 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>:
1959 The recipe that provides "virtual/xserver" when
1960 more than one provider is found.
1961 In this case, the recipe that provides
1962 "virtual/xserver" is "xserver-xorg", which
1963 exists in
Brad Bishopc342db32019-05-15 21:57:59 -04001964 <filename>poky/meta/recipes-graphics/xorg-xserver</filename>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001965 </para></listitem>
1966 <listitem><para>
1967 <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>:
1968 The packages that should be installed to provide
1969 an X server and drivers for the machine.
1970 In this example, the "xserver-xorg" and
1971 "xf86-video-modesetting" are installed.
1972 </para></listitem>
1973 <listitem><para>
1974 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>:
1975 A list of machine-dependent packages
1976 not essential for booting the image.
1977 Thus, the build does not fail if the packages
1978 do not exist.
1979 However, the packages are required for a
1980 fully-featured image.
1981 <note><title>Tip</title>
1982 Many <filename>MACHINE*</filename> variables
1983 exist that help you configure a particular
1984 piece of hardware.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001985 </note>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001986 </para></listitem>
1987 <listitem><para>
1988 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>:
1989 Recipes to build that do not provide packages
1990 for installing into the root filesystem
1991 but building the image depends on the
1992 recipes.
1993 Sometimes a recipe is required to build
1994 the final image but is not needed in the
1995 root filesystem.
1996 In this case, the U-Boot recipe must be
1997 built for the image.
1998 </para></listitem>
1999 <listitem><para>
2000 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>:
2001 Machines use tunings to optimize machine,
2002 CPU, and application performance.
2003 These features, which are collectively known
2004 as "tuning features", exist in the
2005 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
2006 layer (e.g.
2007 <filename>poky/meta/conf/machine/include</filename>).
2008 In this example, the default tunning file is
2009 "cortexa8hf-neon".
2010 <note>
2011 The <filename>include</filename> statement
2012 that pulls in the
2013 <filename>conf/machine/include/tune-cortexa8.inc</filename>
2014 file provides many tuning possibilities.
2015 </note>
2016 </para></listitem>
2017 <listitem><para>
2018 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>:
2019 The formats the OpenEmbedded build system
2020 uses during the build when creating the
2021 root filesystem.
2022 In this example, four types of images are
2023 supported.
2024 </para></listitem>
2025 <listitem><para>
2026 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>:
2027 Specifies additional options for image
2028 creation commands.
2029 In this example, the "-lnp " option is used
2030 when creating the
2031 <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink>
2032 image.
2033 </para></listitem>
2034 <listitem><para>
2035 <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>:
2036 The location of the
2037 <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink>
2038 file used by the OpenEmbedded build system to
2039 create a partitioned image (image.wic).
2040 </para></listitem>
2041 <listitem><para>
2042 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
2043 Specifies packages to install into an image
2044 through the
2045 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
2046 class.
2047 Recipes use the <filename>IMAGE_INSTALL</filename>
2048 variable.
2049 </para></listitem>
2050 <listitem><para>
2051 <filename>do_image_wic[depends]</filename>:
2052 A task that is constructed during the build.
2053 In this example, the task depends on specific tools
2054 in order to create the sysroot when buiding a Wic
2055 image.
2056 </para></listitem>
2057 <listitem><para>
2058 <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>:
2059 Defines a serial console (TTY) to enable using
2060 getty.
2061 In this case, the baud rate is "115200" and the
2062 device name is "ttyO0".
2063 </para></listitem>
2064 <listitem><para>
2065 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>:
2066 Specifies the recipe that provides
2067 "virtual/kernel" when more than one provider
2068 is found.
2069 In this case, the recipe that provides
2070 "virtual/kernel" is "linux-yocto", which
2071 exists in the layer's
2072 <filename>recipes-kernel/linux</filename> directory.
2073 </para></listitem>
2074 <listitem><para>
2075 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>:
2076 Defines the version of the recipe used
Brad Bishopc342db32019-05-15 21:57:59 -04002077 to build the kernel, which is "5.0" in this
Brad Bishop316dfdd2018-06-25 12:45:53 -04002078 case.
2079 </para></listitem>
2080 <listitem><para>
2081 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>:
2082 The type of kernel to build for the device.
2083 In this case, the OpenEmbedded build system
2084 creates a "zImage" image type.
2085 </para></listitem>
2086 <listitem><para>
2087 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>:
Brad Bishopc342db32019-05-15 21:57:59 -04002088 The names of the generated Linux kernel device
2089 trees (i.e. the <filename>*.dtb</filename>) files.
Brad Bishop316dfdd2018-06-25 12:45:53 -04002090 All the device trees for the various BeagleBone
2091 devices are included.
2092<!--
2093 You have to include some *.inc files according to the definition of KERNEL_DEVICETREE.
2094 I don't see where these are being provided.
2095-->
2096 </para></listitem>
2097 <listitem><para>
2098 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>:
2099 Additional <filename>make</filename>
2100 command-line arguments the OpenEmbedded build
2101 system passes on when compiling the kernel.
2102 In this example, "LOADADDR=${UBOOT_ENTRYPOINT}"
2103 is passed as a command-line argument.
2104 </para></listitem>
2105 <listitem><para>
2106 <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>:
2107 Defines the Secondary Program Loader (SPL) binary
2108 type.
2109 In this case, the SPL binary is set to
2110 "MLO", which stands for Multimedia card LOader.
2111 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002112
Brad Bishop316dfdd2018-06-25 12:45:53 -04002113 <para>The BeagleBone development board requires an
2114 SPL to boot and that SPL file type must be MLO.
2115 Consequently, the machine configuration needs to
2116 define <filename>SPL_BINARY</filename> as "MLO".
2117 <note>
2118 For more information on how the SPL variables
2119 are used, see the
2120 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink>
2121 include file.
2122 </note>
2123 </para></listitem>
2124 <listitem><para>
2125 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>:
2126 Defines various U-Boot configurations needed
2127 to build a U-Boot image.
2128 In this example, a U-Boot image is required
2129 to boot the BeagleBone device.
2130 See the following variables for more information:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002131 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002132 <listitem><para>
2133 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>:
2134 Points to the generated U-Boot extension.
2135 </para></listitem>
2136 <listitem><para>
2137 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>:
2138 Specifies the value passed on the make command line when building a U-Boot image.
2139 </para></listitem>
2140 <listitem><para>
2141 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>:
2142 Specifies the entry point for the U-Boot image.
2143 </para></listitem>
2144 <listitem><para>
2145 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>:
2146 Specifies the load address for the U-Boot image.
2147 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002148 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002149 </para></listitem>
2150 <listitem><para>
2151 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>:
2152 Specifies the list of hardware features the
2153 BeagleBone device is capable of supporting.
2154 In this case, the device supports
2155 "usbgadget usbhost vfat alsa".
2156 </para></listitem>
2157 <listitem><para>
2158 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>:
2159 Files installed into the device's boot partition
2160 when preparing the image using the Wic tool
2161 with the <filename>bootimg-partition</filename>
2162 source plugin.
Brad Bishop316dfdd2018-06-25 12:45:53 -04002163 </para></listitem>
2164 </itemizedlist>
2165 </para>
2166 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002167
Brad Bishop316dfdd2018-06-25 12:45:53 -04002168 <section id='bsp-kernel-recipe-example'>
2169 <title>BSP Kernel Recipe Example</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002170
Brad Bishop316dfdd2018-06-25 12:45:53 -04002171 <para>
2172 The kernel recipe used to build the kernel image
2173 for the BeagleBone device was established in the
2174 machine configuration:
2175 <literallayout class='monospaced'>
2176 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Brad Bishopc342db32019-05-15 21:57:59 -04002177 PREFERRED_VERSION_linux-yocto ?= "5.0%"
Brad Bishop316dfdd2018-06-25 12:45:53 -04002178 </literallayout>
2179 The <filename>meta-yocto-bsp/recipes-kernel/linux</filename>
2180 directory in the layer contains metadata used
2181 to build the kernel.
Brad Bishopc342db32019-05-15 21:57:59 -04002182 In this case, a kernel append file (i.e.
2183 <filename>linux-yocto_5.0.bbappend</filename>) is used to
2184 override an established kernel recipe (i.e.
2185 <filename>linux-yocto_5.0.bb</filename>), which is
Brad Bishop316dfdd2018-06-25 12:45:53 -04002186 located in
Brad Bishopc342db32019-05-15 21:57:59 -04002187 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04002188 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002189
Brad Bishop316dfdd2018-06-25 12:45:53 -04002190 <para>
2191 Following is the contents of the append file:
2192 <literallayout class='monospaced'>
Brad Bishopc342db32019-05-15 21:57:59 -04002193 KBRANCH_genericx86 = "v5.0/standard/base"
2194 KBRANCH_genericx86-64 = "v5.0/standard/base"
2195 KBRANCH_edgerouter = "v5.0/standard/edgerouter"
2196 KBRANCH_beaglebone-yocto = "v5.0/standard/beaglebone"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002197
Brad Bishop316dfdd2018-06-25 12:45:53 -04002198 KMACHINE_genericx86 ?= "common-pc"
2199 KMACHINE_genericx86-64 ?= "common-pc-64"
Brad Bishopc342db32019-05-15 21:57:59 -04002200 KMACHINE_beaglebone-yocto ?= "beaglebone"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002201
Brad Bishopc342db32019-05-15 21:57:59 -04002202 SRCREV_machine_genericx86 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
2203 SRCREV_machine_genericx86-64 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
2204 SRCREV_machine_edgerouter ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
2205 SRCREV_machine_beaglebone-yocto ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002206
Brad Bishop316dfdd2018-06-25 12:45:53 -04002207 COMPATIBLE_MACHINE_genericx86 = "genericx86"
2208 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
2209 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
2210 COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002211
Brad Bishopc342db32019-05-15 21:57:59 -04002212 LINUX_VERSION_genericx86 = "5.0.3"
2213 LINUX_VERSION_genericx86-64 = "5.0.3"
2214 LINUX_VERSION_edgerouter = "5.0.3"
2215 LINUX_VERSION_beaglebone-yocto = "5.0.3"
Brad Bishop316dfdd2018-06-25 12:45:53 -04002216 </literallayout>
2217 This particular append file works for all the
2218 machines that are part of the
Brad Bishopc342db32019-05-15 21:57:59 -04002219 <filename>meta-yocto-bsp</filename> layer.
Brad Bishop316dfdd2018-06-25 12:45:53 -04002220 The relevant statements are appended with
2221 the "beaglebone-yocto" string.
2222 The OpenEmbedded build system uses these
2223 statements to override similar statements
2224 in the kernel recipe:
2225 <itemizedlist>
2226 <listitem><para>
2227 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>:
2228 Identifies the kernel branch that is validated,
2229 patched, and configured during the build.
2230 </para></listitem>
2231 <listitem><para>
2232 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>:
2233 Identifies the machine name as known by the
2234 kernel, which is sometimes a different name
2235 than what is known by the OpenEmbedded build
2236 system.
2237 </para></listitem>
2238 <listitem><para>
2239 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
2240 Identifies the revision of the source code used
2241 to build the image.
Brad Bishop316dfdd2018-06-25 12:45:53 -04002242 </para></listitem>
2243 <listitem><para>
2244 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
2245 A regular expression that resolves to one or
2246 more target machines with which the recipe
2247 is compatible.
2248 </para></listitem>
2249 <listitem><para>
2250 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
2251 The Linux version from kernel.org used by
2252 the OpenEmbedded build system to build the
2253 kernel image.
2254 </para></listitem>
2255 </itemizedlist>
2256 </para>
2257 </section>
2258</section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002259</chapter>