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