1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<chapter id='bsp'>
<title>Board Support Packages (BSP) - Developers Guide</title>
<para>
A Board Support Package (BSP) is a collection of information that
defines how to support a particular hardware device, set of devices, or
hardware platform.
The BSP includes information about the hardware features
present on the device and kernel configuration information along with any
additional hardware drivers required.
The BSP also lists any additional software
components required in addition to a generic Linux software stack for both
essential and optional platform features.
</para>
<para>
The intent of this document is to define a structure for these components
so that BSPs follow a commonly understood layout.
Providing a common form allows end-users to understand and become familiar
with the layout.
A common form also encourages standardization
of software support of hardware.
</para>
<para>
The proposed format does have elements that are specific to the Poky and
OpenEmbedded build systems.
It is intended that this information can be
used by other systems besides Poky and OpenEmbedded and that it will be simple
to extract information and convert it to other formats if required.
Poky, through its standard layers mechanism, can directly accept The format
described as a layer.
The BSP captures all
the hardware-specific details in one place in a standard format, which is
useful for any person wishing to use the hardware platform regardless of
the build system they are using.
</para>
<para>
The BSP specification does not include a build system or other tools -
it is concerned with the hardware-specific components only.
At the end
distribution point you can ship the BSP combined with a build system
and other tools.
However, it is important to maintain the distinction that these
are separate components that happen to be combined in certain end products.
</para>
<section id="bsp-filelayout">
<title>Example Filesystem Layout</title>
<para>
The BSP consists of a file structure inside a base directory, meta-bsp in this example,
where "bsp" is a placeholder for the machine or platform name.
Examples of some files that it could contain are:
</para>
<para>
<programlisting>
meta-bsp/
meta-bsp/binary/zImage
meta-bsp/binary/poky-image-minimal.directdisk
meta-bsp/conf/layer.conf
meta-bsp/conf/machine/*.conf
meta-bsp/conf/machine/include/tune-*.inc
meta-bsp/packages/bootloader/bootloader_0.1.bb
meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch
meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
meta-bsp/packages/linux/linux-bsp_2.6.50.bb
meta-bsp/packages/modem/modem-driver_0.1.bb
meta-bsp/packages/modem/modem-daemon_0.1.bb
meta-bsp/packages/image-creator/image-creator-native_0.1.bb
meta-bsp/prebuilds/
</programlisting>
</para>
<para>
The following sections detail what these files and directories could contain.
</para>
</section>
<section id="bsp-filelayout-binary">
<title>Prebuilt User Binaries (meta-bsp/binary/*)</title>
<para>
This optional area contains useful prebuilt kernels and userspace filesystem
images appropriate to the target system.
Users could use these to get a system
running and quickly get started on development tasks.
The exact types of binaries
present are highly hardware-dependent.
However, a README file should be present
that explains how to use them with the target hardware.
If prebuilt binaries are
present, source code to meet licensing requirements must also be provided in
some form.
</para>
</section>
<section id='bsp-filelayout-layer'>
<title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
<para>
This file identifies the structure as a Poky layer, identifies the
contents of the layer and contains information about how Poky should use
it.
Generally, a standard boilerplate file consisting of the following works.
</para>
<para>
<programlisting>
# We have a conf directory, add to BBPATH
BBPATH := "${BBPATH}${LAYERDIR}"
# We have a recipes directory containing .bb and .bbappend files, add to BBFILES
BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend"
BBFILE_COLLECTIONS += "bsp"
BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
BBFILE_PRIORITY_bsp = "5"
</programlisting>
</para>
<para>
This file simply makes bitbake aware of the recipes and conf directories and is required
for recognition of the BSP by Poky.
</para>
</section>
<section id="bsp-filelayout-machine">
<title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title>
<para>
The machine files bind together all the information contained elsewhere
in the BSP into a format that Poky/OpenEmbedded can understand.
If the BSP supports multiple machines, multiple machine configuration files
can be present.
These filenames correspond to the values to which users have set the MACHINE variable.
</para>
<para>
These files define things such as what kernel package to use
(PREFERRED_PROVIDER of virtual/kernel), what hardware drivers to
include in different types of images, any special software components
that are needed, any bootloader information, and also any special image
format requirements.
</para>
<para>
At least one machine file is required for a Poky BSP layer.
However, you can supply more than one file.
</para>
</section>
<section id="bsp-filelayout-tune">
<title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
<para>
These are shared hardware "tuning" definitions and are commonly used to
pass specific optimization flags to the compiler.
An example is tune-atom.inc:
</para>
<para>
<programlisting>
BASE_PACKAGE_ARCH = "core2"
TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
</programlisting>
</para>
<para>
This example defines a new package architecture called "core2" and uses the
specified optimization flags, which are carefully chosen to give best
performance on atom processors.
</para>
<para>
The tune file would be included by the machine definition and can be
contained in the BSP or referenced from one of the standard core set of
files included with Poky itself.
</para>
<para>
Both the base package architecuture file and the tune file are optional for a Poky BSP layer.
</para>
</section>
<section id='bsp-filelayout-kernel'>
<title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title>
<para>
These files make up the definition of a kernel to use with this
hardware.
In this case, it is a complete self-contained kernel with its own
configuration and patches.
However, kernels can be shared between many machines as well.
Following is an example:
<programlisting>
meta-bsp/packages/linux/linux-bsp_2.6.50.bb
</programlisting>
This example file is the core kernel recipe that details from where to get the kernel
source.
All standard source code locations are supported so this could
be a release tarball, some git repository, or source included in
the directory within the BSP itself.
</para>
<para>
The file then contains information about what patches to apply and how to configure and build them.
It can reuse the main Poky kernel build class, so the definitions here can remain very simple.
</para>
<para>
<programlisting>
linux-bsp-2.6.50/*.patch
</programlisting>
</para>
<para>
The above example file contains patches you can apply against the base kernel, from wherever
they may have been obtained.
</para>
<para>
<programlisting>
meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
</programlisting>
</para>
<para>
Finally, this last example file contains kernel configuration information.
</para>
<para>
Examples of kernel recipes are available in Poky itself.
These files are optional since a kernel from Poky could be selected, although it
would be unusual not to have a kernel configuration.
</para>
</section>
<section id='bsp-filelayout-packages'>
<title>Other Software (meta-bsp/packages/*)</title>
<para>
This section describes other pieces of software that the hardware might need for best
operation.
This section shows examples of the kinds of things that you could encounter.
The examples are standard <filename>.bb</filename> file recipes in the
usual Poky format.
You can include the source directly by referring to it in the source control system or
the released tarballs of external software projects.
You only need to provide these types of files if the platform requires them.
</para>
<para>
The following file is a bootloader recipe that can be used to generate a new
bootloader binary.
Sometimes these files are included in the final image format and are needed to re-flash hardware.
</para>
<para>
<programlisting>
meta-bsp/packages/bootloader/bootloader_0.1.bb
</programlisting>
</para>
<para>
These next two files are examples of a hardware driver and a hardware daemon that might need
to be included in images to make the hardware useful.
Although the example uses "modem" there may be other components needed, such as firmware.
</para>
<para>
<programlisting>
meta-bsp/packages/modem/modem-driver_0.1.bb
meta-bsp/packages/modem/modem-daemon_0.1.bb
</programlisting>
</para>
<para>
Sometimes the device needs an image in a very specific format so that the update
mechanism can accept and re-flash it.
Recipes to build the tools needed to do this can be included with the BSP.
Following is an example.
</para>
<para>
<programlisting>
meta-bsp/packages/image-creator/image-creator-native_0.1.bb
</programlisting>
</para>
</section>
<section id='bs-filelayout-bbappend'>
<title>Append BSP-Specific Information to Existing Recipes</title>
<para>
Suppose you have a recipe such as 'pointercal' that requires machine-specific information.
At the same time, you have your new BSP code nicely partitioned into a layer through which
you would also like to specify any machine-specific information associated with your new machine.
Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole
pointercal recipe and files into your layer and then add the single file for your machine.
</para>
<para>
With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
This extension allows you to easily merge BSP-specific information with the original recipe.
Whenever bitbake finds any <filename>.bbappend</filename> files they will be
included after bitbake loads the associated <filename>.bb</filename> but before any finalize
or anonymous methods run.
This allows the BSP layer to do whatever it might want to do to customize the original recipe.
</para>
<para>
If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable
to specify their location.
The example below shows extra files contained in a folder called ${PN} (the package name).
</para>
<programlisting>
FILESEXTRAPATHS := "${THISDIR}/${PN}"
</programlisting>
<para>
This technique allows the BSP to add machine-specific configuration files to the layer directory,
which will be picked up by bitbake.
For an example see <filename>meta-emenlow/packages/formfactor</filename>.
</para>
</section>
<section id="bsp-filelayout-prebuilds">
<title>Prebuild Data (meta-bsp/prebuilds/*)</title>
<para>
This location can contain precompiled representations of the source code
contained elsewhere in the BSP layer.
Assuming a compatible configuration is used, Poky can process and use these optional precompiled
representations to provide much faster build times.
</para>
</section>
<section id='bsp-click-through-licensing'>
<title>BSP 'Click-Through' Licensing Procedure</title>
<note><para> This section describes how
click-through licensing is expected to work.
Currently, this functionality is not yet implemented.
</para></note>
<para>
In some cases, a BSP contains separately licensed IP
(Intellectual Property) for a component that imposes
upon the user a requirement to accept the terms of a
'click-through' license.
Once the license is accepted the
Poky build system can then build and include the
corresponding component in the final BSP image.
Some affected components might be essential to the normal
functioning of the system and have no 'free' replacement
(i.e. the resulting system would be non-functional
without them).
On the other hand, other components might be simply
'good-to-have' or purely elective, or if essential
nonetheless have a 'free' (possibly less-capable)
version that could be used as a in the BSP recipe.
</para>
<para>
For cases where you can substitute something and still maintain functionality, the Poky website will make
available a 'de-featured' BSP completely free of
the encumbered IP.
In that case you can use the substitution directly and without
any further licensing requirements.
If present, this
fully 'de-featured' BSP will be named meta-bsp (i.e. the
normal default naming convention).
If available, this is the simplest the most preferred option.
This, of course, assumes the resulting functionality meets requirements.
</para>
<para>
If however, a non-encumbered version is unavailable or
the 'free' version would provide unsuitable
functionality or quality, an encumbered version can be
used.
Encumbered versions of a BSP are given names of
the form meta-bsp-nonfree.
</para>
<para>
Several methods exist within the Poky build system to satisfy the licensing
requirements for an encumbered BSP.
The following list describes them in preferential order:
</para>
<orderedlist>
<listitem>
<para>
Get a license key (or keys) for the encumbered BSP
by visiting
<ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
and give the name of the BSP and your e-mail address in the web form.
</para>
<programlisting>
[screenshot of dialog box]
</programlisting>
<para>
After agreeing to any applicable license terms, the
BSP key(s) will be immediately sent to the address
you gave and you can use them by specifying BSPKEY_<keydomain>
environment variables when building the image:
</para>
<programlisting>
$ BSPKEY_<keydomain>=<key> bitbake poky-image-sato
</programlisting>
<para>
These steps allow the encumbered image to be built
with no change at all to the normal build process.
</para>
<para>
Equivalently and probably more conveniently, a line
for each key can instead be put into the user's
<filename>local.conf</filename> file.
</para>
<para>
The <keydomain> component of the
BSPKEY_<keydomain> is required because there
might be multiple licenses in effect for a give BSP.
In such cases, a given <keydomain> corresponds to
a particular license. In order for an encumbered
BSP that encompasses multiple key domains to be built
successfully, a <keydomain> entry for each
applicable license must be present in <filename>local.conf</filename> or
supplied on the command-line.
</para>
</listitem>
<listitem>
<para>
Do nothing - build as you normally would.
When a license is needed the build will stop and prompt you with instructions.
Follow the license prompts that originate from the
encumbered BSP.
These prompts usually take the form of instructions
needed to manually fetch the encumbered package(s)
and md5 sums into the required directory (e.g. the poky/build/downloads)
Once the manual package fetch has been
completed, restart the build to continue where
it left off.
During the build the prompt will not appear again since you have satisfied the
requirement.
</para>
</listitem>
<listitem>
<para>
Get a full-featured BSP recipe rather than a key, by
visiting
<ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
Accepting the license agreement(s) presented will
subsequently allow you to download a tarball
containing a full-featured BSP that is legally cleared for
your use by the just-given license agreement(s).
This method will also allow the encumbered image to
be built with no change at all to the normal build
process.
</para>
</listitem>
</itemizedlist>
<para>
Note that the third method is also the only option available
when downloading pre-compiled images generated from
non-free BSPs.
Those images are likewise available at
<ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
</para>
</section>
</chapter>
|