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