summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/bsp-guide/bsp.xml258
-rw-r--r--documentation/poky-ref-manual/bsp.xml152
2 files changed, 215 insertions, 195 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 599c2bf060..4b310dc6ef 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -35,9 +35,9 @@
35 Poky, through its standard layers mechanism, can directly accept The format 35 Poky, through its standard layers mechanism, can directly accept The format
36 described as a layer. 36 described as a layer.
37 The BSP captures all 37 The BSP captures all
38 the hardware specific details in one place in a standard format, which is 38 the hardware-specific details in one place in a standard format, which is
39 useful for any person wishing to use the hardware platform regardless of 39 useful for any person wishing to use the hardware platform regardless of
40 the build system being used. 40 the build system they are using.
41 </para> 41 </para>
42 42
43 <para> 43 <para>
@@ -58,23 +58,24 @@
58 where "bsp" is a placeholder for the machine or platform name. 58 where "bsp" is a placeholder for the machine or platform name.
59 Examples of some files that it could contain are: 59 Examples of some files that it could contain are:
60 </para> 60 </para>
61
61 <para> 62 <para>
62 <literallayout class='monospaced'> 63 <programlisting>
63 meta-bsp/ 64meta-bsp/
64 meta-bsp/binary/zImage 65meta-bsp/binary/zImage
65 meta-bsp/binary/poky-image-minimal.directdisk 66meta-bsp/binary/poky-image-minimal.directdisk
66 meta-bsp/conf/layer.conf 67meta-bsp/conf/layer.conf
67 meta-bsp/conf/machine/*.conf 68meta-bsp/conf/machine/*.conf
68 meta-bsp/conf/machine/include/tune-*.inc 69meta-bsp/conf/machine/include/tune-*.inc
69 meta-bsp/packages/bootloader/bootloader_0.1.bb 70meta-bsp/packages/bootloader/bootloader_0.1.bb
70 meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch 71meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch
71 meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp 72meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
72 meta-bsp/packages/linux/linux-bsp_2.6.50.bb 73meta-bsp/packages/linux/linux-bsp_2.6.50.bb
73 meta-bsp/packages/modem/modem-driver_0.1.bb 74meta-bsp/packages/modem/modem-driver_0.1.bb
74 meta-bsp/packages/modem/modem-daemon_0.1.bb 75meta-bsp/packages/modem/modem-daemon_0.1.bb
75 meta-bsp/packages/image-creator/image-creator-native_0.1.bb 76meta-bsp/packages/image-creator/image-creator-native_0.1.bb
76 meta-bsp/prebuilds/ 77meta-bsp/prebuilds/
77 </literallayout> 78 </programlisting>
78 </para> 79 </para>
79 80
80 <para> 81 <para>
@@ -92,8 +93,9 @@
92 Users could use these to get a system 93 Users could use these to get a system
93 running and quickly get started on development tasks. 94 running and quickly get started on development tasks.
94 The exact types of binaries 95 The exact types of binaries
95 present will be highly hardware-dependent but a README file should be present 96 present are highly hardware-dependent.
96 explaining how to use them with the target hardware. 97 However, a README file should be present
98 that explains how to use them with the target hardware.
97 If prebuilt binaries are 99 If prebuilt binaries are
98 present, source code to meet licensing requirements must also be provided in 100 present, source code to meet licensing requirements must also be provided in
99 some form. 101 some form.
@@ -105,24 +107,24 @@
105 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title> 107 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
106 108
107 <para> 109 <para>
108 This file identifies the structure as a Poky layer by identifying the 110 This file identifies the structure as a Poky layer, identifies the
109 contents of the layer and containing information about how Poky should use 111 contents of the layer and contains information about how Poky should use
110 it. 112 it.
111 Generally, a standard boilerplate file consisting of the following works. 113 Generally, a standard boilerplate file consisting of the following works.
112 </para> 114 </para>
113 115
114 <para> 116 <para>
115 <literallayout class='monospaced'> 117 <programlisting>
116 # We have a conf directory, add to BBPATH 118# We have a conf directory, add to BBPATH
117 BBPATH := "${BBPATH}${LAYERDIR}" 119BBPATH := "${BBPATH}${LAYERDIR}"
118 120
119 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES 121# We have a recipes directory containing .bb and .bbappend files, add to BBFILES
120 BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend" 122BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend"
121 123
122 BBFILE_COLLECTIONS += "bsp" 124BBFILE_COLLECTIONS += "bsp"
123 BBFILE_PATTERN_bsp := "^${LAYERDIR}/" 125BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
124 BBFILE_PRIORITY_bsp = "5" 126BBFILE_PRIORITY_bsp = "5"
125 </literallayout> 127 </programlisting>
126 </para> 128 </para>
127 129
128 <para> 130 <para>
@@ -167,10 +169,10 @@
167 An example is tune-atom.inc: 169 An example is tune-atom.inc:
168 </para> 170 </para>
169 <para> 171 <para>
170 <literallayout class='monospaced'> 172 <programlisting>
171 BASE_PACKAGE_ARCH = "core2" 173BASE_PACKAGE_ARCH = "core2"
172 TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" 174TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
173 </literallayout> 175 </programlisting>
174 </para> 176 </para>
175 <para> 177 <para>
176 This example defines a new package architecture called "core2" and uses the 178 This example defines a new package architecture called "core2" and uses the
@@ -194,12 +196,12 @@
194 These files make up the definition of a kernel to use with this 196 These files make up the definition of a kernel to use with this
195 hardware. 197 hardware.
196 In this case, it is a complete self-contained kernel with its own 198 In this case, it is a complete self-contained kernel with its own
197 configuration and patches but kernels can be shared between many 199 configuration and patches.
198 machines as well. 200 However, kernels can be shared between many machines as well.
199 Following is an example: 201 Following is an example:
200 <literallayout class='monospaced'> 202 <programlisting>
201 meta-bsp/packages/linux/linux-bsp_2.6.50.bb 203meta-bsp/packages/linux/linux-bsp_2.6.50.bb
202 </literallayout> 204 </programlisting>
203 This example file is the core kernel recipe that details from where to get the kernel 205 This example file is the core kernel recipe that details from where to get the kernel
204 source. 206 source.
205 All standard source code locations are supported so this could 207 All standard source code locations are supported so this could
@@ -211,25 +213,25 @@
211 It can reuse the main Poky kernel build class, so the definitions here can remain very simple. 213 It can reuse the main Poky kernel build class, so the definitions here can remain very simple.
212 </para> 214 </para>
213 <para> 215 <para>
214 <literallayout class='monospaced'> 216 <programlisting>
215 linux-bsp-2.6.50/*.patch 217linux-bsp-2.6.50/*.patch
216 </literallayout> 218 </programlisting>
217 </para> 219 </para>
218 <para> 220 <para>
219 The above example file contains patches you can apply against the base kernel, wherever 221 The above example file contains patches you can apply against the base kernel, from wherever
220 they may have been obtained from. 222 they may have been obtained.
221 </para> 223 </para>
222 <para> 224 <para>
223 <literallayout class='monospaced'> 225 <programlisting>
224 meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp 226meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
225 </literallayout> 227 </programlisting>
226 </para> 228 </para>
227 <para> 229 <para>
228 Finally, this last example file contains configuration information to use to configure the kernel. 230 Finally, this last example file contains kernel configuration information.
229 </para> 231 </para>
230 <para> 232 <para>
231 Examples of kernel recipes are available in Poky itself. 233 Examples of kernel recipes are available in Poky itself.
232 These files are optional since a kernel from Poky itself could be selected, although it 234 These files are optional since a kernel from Poky could be selected, although it
233 would be unusual not to have a kernel configuration. 235 would be unusual not to have a kernel configuration.
234 </para> 236 </para>
235 </section> 237 </section>
@@ -240,8 +242,8 @@
240 <para> 242 <para>
241 This section describes other pieces of software that the hardware might need for best 243 This section describes other pieces of software that the hardware might need for best
242 operation. 244 operation.
243 These are examples of the kinds of things that you could encounter. 245 This section shows examples of the kinds of things that you could encounter.
244 The examples used in this section are standard <filename>.bb</filename> file recipes in the 246 The examples are standard <filename>.bb</filename> file recipes in the
245 usual Poky format. 247 usual Poky format.
246 You can include the source directly by referring to it in the source control system or 248 You can include the source directly by referring to it in the source control system or
247 the released tarballs of external software projects. 249 the released tarballs of external software projects.
@@ -250,12 +252,12 @@
250 <para> 252 <para>
251 The following file is a bootloader recipe that can be used to generate a new 253 The following file is a bootloader recipe that can be used to generate a new
252 bootloader binary. 254 bootloader binary.
253 Sometimes these files are included in the final image format and are needed to reflash hardware. 255 Sometimes these files are included in the final image format and are needed to re-flash hardware.
254 </para> 256 </para>
255 <para> 257 <para>
256 <literallayout class='monospaced'> 258 <programlisting>
257 meta-bsp/packages/bootloader/bootloader_0.1.bb 259meta-bsp/packages/bootloader/bootloader_0.1.bb
258 </literallayout> 260 </programlisting>
259 </para> 261 </para>
260 <para> 262 <para>
261 These next two files are examples of a hardware driver and a hardware daemon that might need 263 These next two files are examples of a hardware driver and a hardware daemon that might need
@@ -263,21 +265,21 @@
263 Although the example uses "modem" there may be other components needed, such as firmware. 265 Although the example uses "modem" there may be other components needed, such as firmware.
264 </para> 266 </para>
265 <para> 267 <para>
266 <literallayout class='monospaced'> 268 <programlisting>
267 meta-bsp/packages/modem/modem-driver_0.1.bb 269meta-bsp/packages/modem/modem-driver_0.1.bb
268 meta-bsp/packages/modem/modem-daemon_0.1.bb 270meta-bsp/packages/modem/modem-daemon_0.1.bb
269 </literallayout> 271 </programlisting>
270 </para> 272 </para>
271 <para> 273 <para>
272 Sometimes the device needs an image in a very specific format so that the update 274 Sometimes the device needs an image in a very specific format so that the update
273 mechanism can accept and reflash it. 275 mechanism can accept and re-flash it.
274 Recipes to build the tools needed to do this can be included with the BSP. 276 Recipes to build the tools needed to do this can be included with the BSP.
275 Following is an example. 277 Following is an example.
276 </para> 278 </para>
277 <para> 279 <para>
278 <literallayout class='monospaced'> 280 <programlisting>
279 meta-bsp/packages/image-creator/image-creator-native_0.1.bb 281meta-bsp/packages/image-creator/image-creator-native_0.1.bb
280 </literallayout> 282 </programlisting>
281 </para> 283 </para>
282 </section> 284 </section>
283 285
@@ -285,15 +287,15 @@
285 <title>Append BSP-Specific Information to Existing Recipes</title> 287 <title>Append BSP-Specific Information to Existing Recipes</title>
286 <para> 288 <para>
287 Suppose you have a recipe such as 'pointercal' that requires machine-specific information. 289 Suppose you have a recipe such as 'pointercal' that requires machine-specific information.
288 At the same time, you have your new BSP code nicely partitioned into a layer, which is where 290 At the same time, you have your new BSP code nicely partitioned into a layer through which
289 you would also like to specify any machine-specific information associated with your new machine. 291 you would also like to specify any machine-specific information associated with your new machine.
290 Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole 292 Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole
291 pointercal recipe and files into your layer, and then add the single file for your machine. 293 pointercal recipe and files into your layer and then add the single file for your machine.
292 </para> 294 </para>
293 <para> 295 <para>
294 With the <filename>.bbappend</filename> extension, however, your work becomes much easier. 296 With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
295 It allows you to easily merge BSP-specific information with the original recipe. 297 This extension allows you to easily merge BSP-specific information with the original recipe.
296 Whenever bitbake finds any <filename>.bbappend</filename> files, they will be 298 Whenever bitbake finds any <filename>.bbappend</filename> files they will be
297 included after bitbake loads the associated <filename>.bb</filename> but before any finalize 299 included after bitbake loads the associated <filename>.bb</filename> but before any finalize
298 or anonymous methods run. 300 or anonymous methods run.
299 This allows the BSP layer to do whatever it might want to do to customize the original recipe. 301 This allows the BSP layer to do whatever it might want to do to customize the original recipe.
@@ -303,9 +305,9 @@
303 to specify their location. 305 to specify their location.
304 The example below shows extra files contained in a folder called ${PN} (the package name). 306 The example below shows extra files contained in a folder called ${PN} (the package name).
305 </para> 307 </para>
306 <literallayout class='monospaced'> 308 <programlisting>
307 FILESEXTRAPATHS := "${THISDIR}/${PN}" 309FILESEXTRAPATHS := "${THISDIR}/${PN}"
308 </literallayout> 310 </programlisting>
309 <para> 311 <para>
310 This technique allows the BSP to add machine-specific configuration files to the layer directory, 312 This technique allows the BSP to add machine-specific configuration files to the layer directory,
311 which will be picked up by bitbake. 313 which will be picked up by bitbake.
@@ -327,92 +329,99 @@
327 <title>BSP 'Click-Through' Licensing Procedure</title> 329 <title>BSP 'Click-Through' Licensing Procedure</title>
328 330
329 <note><para> This section describes how 331 <note><para> This section describes how
330 click-through licensing, which is not yet implemented, is expected to work. 332 click-through licensing is expected to work.
333 Currently, this functionality is not yet implemented.
331 </para></note> 334 </para></note>
332 335
333 <para> 336 <para>
334 In some cases, a BSP might contain separately licensed IP 337 In some cases, a BSP contains separately licensed IP
335 (Intellectual Property) for a component that imposes 338 (Intellectual Property) for a component that imposes
336 upon the user a requirement to accept the terms of a 339 upon the user a requirement to accept the terms of a
337 'click-through' license. Once the license is accepted 340 'click-through' license.
338 (in whatever form that may be, see details below) the 341 Once the license is accepted the
339 Poky build system can then build and include the 342 Poky build system can then build and include the
340 corresponding component in the final BSP image. Some 343 corresponding component in the final BSP image.
341 affected components might be essential to the normal 344 Some affected components might be essential to the normal
342 functioning of the system and have no 'free' replacement 345 functioning of the system and have no 'free' replacement
343 (i.e. the resulting system would be non-functional 346 (i.e. the resulting system would be non-functional
344 without them). Other components might be simply 347 without them).
348 On the other hand, other components might be simply
345 'good-to-have' or purely elective, or if essential 349 'good-to-have' or purely elective, or if essential
346 nonetheless have a 'free' (possibly less-capable) 350 nonetheless have a 'free' (possibly less-capable)
347 version that can be substituted for in the BSP recipe. 351 version that could be used as a in the BSP recipe.
348 </para> 352 </para>
349 353
350 <para> 354 <para>
351 For the latter cases, where it is possible to do so from 355 For cases where you can substitute something and still maintain functionality, the Poky website will make
352 a functionality perspective, the Poky website will make
353 available a 'de-featured' BSP completely free of 356 available a 'de-featured' BSP completely free of
354 encumbered IP that can be used directly and without 357 the encumbered IP.
355 any further licensing requirements. If present, this 358 In that case you can use the substitution directly and without
359 any further licensing requirements.
360 If present, this
356 fully 'de-featured' BSP will be named meta-bsp (i.e. the 361 fully 'de-featured' BSP will be named meta-bsp (i.e. the
357 normal default naming convention). This is the simplest 362 normal default naming convention).
358 and therefore preferred option if available, assuming 363 If available, this is the simplest the most preferred option.
359 the resulting functionality meets requirements. 364 This, of course, assumes the resulting functionality meets requirements.
360 </para> 365 </para>
361 366
362 <para> 367 <para>
363 However, if a non-encumbered version is unavailable or 368 If however, a non-encumbered version is unavailable or
364 the 'free' version would provide unsuitable 369 the 'free' version would provide unsuitable
365 functionality or quality, an encumbered version can be 370 functionality or quality, an encumbered version can be
366 used. Encumbered versions of a BSP are given names of 371 used.
367 the form meta-bsp-nonfree. There are several ways 372 Encumbered versions of a BSP are given names of
368 within the Poky build system to satisfy the licensing 373 the form meta-bsp-nonfree.
369 requirements for an encumbered BSP, in roughly the 374 </para>
370 following order of preference: 375
376 <para>
377 Several methods exist within the Poky build system to satisfy the licensing
378 requirements for an encumbered BSP.
379 The following list describes them in preferential order:
371 </para> 380 </para>
372 381
373 <itemizedlist> 382 <orderedlist>
374 <listitem> 383 <listitem>
375 384
376 <para> 385 <para>
377 Get a license key (or keys) for the encumbered BSP 386 Get a license key (or keys) for the encumbered BSP
378 by visiting 387 by visiting
379 <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> 388 <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
380 and give the web form there the name of the BSP and your e-mail address. 389 and give the name of the BSP and your e-mail address in the web form.
381 </para> 390 </para>
382 391
383 <literallayout class='monospaced'> 392 <programlisting>
384 [screenshot of dialog box] 393 [screenshot of dialog box]
385 </literallayout> 394 </programlisting>
386 395
387 <para> 396 <para>
388 After agreeing to any applicable license terms, the 397 After agreeing to any applicable license terms, the
389 BSP key(s) will be immediately sent to the address 398 BSP key(s) will be immediately sent to the address
390 given and can be used by specifying BSPKEY_&lt;keydomain&gt; 399 you gave and you can use them by specifying BSPKEY_&lt;keydomain&gt;
391 environment variables when building the image: 400 environment variables when building the image:
392 </para> 401 </para>
393 402
394 <literallayout class='monospaced'> 403 <programlisting>
395 $ BSPKEY_&lt;keydomain&gt;=&lt;key&gt; bitbake poky-image-sato 404 $ BSPKEY_&lt;keydomain&gt;=&lt;key&gt; bitbake poky-image-sato
396 </literallayout> 405 </programlisting>
397 406
398 <para> 407 <para>
399 This will allow the encumbered image to be built 408 These steps allow the encumbered image to be built
400 with no change at all to the normal build process. 409 with no change at all to the normal build process.
401 </para> 410 </para>
402 411
403 <para> 412 <para>
404 Equivalently and probably more conveniently, a line 413 Equivalently and probably more conveniently, a line
405 for each key can instead be put into the user's 414 for each key can instead be put into the user's
406 local.conf file. 415 <filename>local.conf</filename> file.
407 </para> 416 </para>
408 417
409 <para> 418 <para>
410 The &lt;keydomain&gt; component of the 419 The &lt;keydomain&gt; component of the
411 BSPKEY_&lt;keydomain&gt; is required because there 420 BSPKEY_&lt;keydomain&gt; is required because there
412 may be multiple licenses in effect for a given BSP; a 421 might be multiple licenses in effect for a give BSP.
413 given &lt;keydomain&gt; in such cases corresponds to 422 In such cases, a given &lt;keydomain&gt; corresponds to
414 a particular license. In order for an encumbered 423 a particular license. In order for an encumbered
415 BSP encompassing multiple key domains to be built 424 BSP that encompasses multiple key domains to be built
416 successfully, a &lt;keydomain&gt; entry for each 425 successfully, a &lt;keydomain&gt; entry for each
417 applicable license must be present in <filename>local.conf</filename> or 426 applicable license must be present in <filename>local.conf</filename> or
418 supplied on the command-line. 427 supplied on the command-line.
@@ -420,16 +429,18 @@
420 </listitem> 429 </listitem>
421 <listitem> 430 <listitem>
422 <para> 431 <para>
423 Do nothing - build as you normally would, and follow 432 Do nothing - build as you normally would.
424 any license prompts that originate from the 433 When a license is needed the build will stop and prompt you with instructions.
425 encumbered BSP (the build will cleanly stop at this 434 Follow the license prompts that originate from the
426 point). These usually take the form of instructions 435 encumbered BSP.
436 These prompts usually take the form of instructions
427 needed to manually fetch the encumbered package(s) 437 needed to manually fetch the encumbered package(s)
428 and md5 sums into the directory (e.g. the poky/build/downloads). 438 and md5 sums into the required directory (e.g. the poky/build/downloads)
429 Once the manual package fetch has been 439 Once the manual package fetch has been
430 completed, restarting the build will continue where 440 completed, restart the build to continue where
431 it left off, this time without the prompt since the 441 it left off.
432 license requirements will have been satisfied. 442 During the build the prompt will not appear again since you have satisfied the
443 requirement.
433 </para> 444 </para>
434 </listitem> 445 </listitem>
435 <listitem> 446 <listitem>
@@ -439,7 +450,7 @@
439 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. 450 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
440 Accepting the license agreement(s) presented will 451 Accepting the license agreement(s) presented will
441 subsequently allow you to download a tarball 452 subsequently allow you to download a tarball
442 containing a full-featured BSP legally cleared for 453 containing a full-featured BSP that is legally cleared for
443 your use by the just-given license agreement(s). 454 your use by the just-given license agreement(s).
444 This method will also allow the encumbered image to 455 This method will also allow the encumbered image to
445 be built with no change at all to the normal build 456 be built with no change at all to the normal build
@@ -447,14 +458,13 @@
447 </para> 458 </para>
448 </listitem> 459 </listitem>
449 </itemizedlist> 460 </itemizedlist>
450 <note> 461 <para>
451 <para> 462 Note that the third method is also the only option available
452 Note that method 3 is also the only option available 463 when downloading pre-compiled images generated from
453 when downloading pre-compiled images generated from 464 non-free BSPs.
454 non-free BSPs. Those images are likewise available at 465 Those images are likewise available at
455 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. 466 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
456 </para> 467 </para>
457 </note>
458 </section> 468 </section>
459 469
460</chapter> 470</chapter>
diff --git a/documentation/poky-ref-manual/bsp.xml b/documentation/poky-ref-manual/bsp.xml
index 7cd18b61e3..e8809555c4 100644
--- a/documentation/poky-ref-manual/bsp.xml
+++ b/documentation/poky-ref-manual/bsp.xml
@@ -16,7 +16,8 @@
16 </para> 16 </para>
17 17
18 <para> 18 <para>
19 The intent of this document is to define a structure for these components 19 This section (or document if you are reading the BSP Developer's Guide) defines
20 a structure for these components
20 so that BSPs follow a commonly understood layout. 21 so that BSPs follow a commonly understood layout.
21 Providing a common form allows end-users to understand and become familiar 22 Providing a common form allows end-users to understand and become familiar
22 with the layout. 23 with the layout.
@@ -28,21 +29,21 @@
28 The proposed format does have elements that are specific to the Poky and 29 The proposed format does have elements that are specific to the Poky and
29 OpenEmbedded build systems. 30 OpenEmbedded build systems.
30 It is intended that this information can be 31 It is intended that this information can be
31 used by other systems besides Poky and OpenEmbedded and thatspecified it will be simple 32 used by other systems besides Poky and OpenEmbedded and that it will be simple
32 to extract information and convert it to other formats if required. 33 to extract information and convert it to other formats if required.
33 Poky, through its standard slyers mechanism, can directly accept The format 34 Poky, through its standard layers mechanism, can directly accept The format
34 described as a layer. 35 described as a layer.
35 The BSP captures all 36 The BSP captures all
36 the hardware specific details in one place in a standard format, which is 37 the hardware-specific details in one place in a standard format, which is
37 useful for any person wishing to use the hardware platform regardless of 38 useful for any person wishing to use the hardware platform regardless of
38 the build system being used. 39 the build system they are using.
39 </para> 40 </para>
40 41
41 <para> 42 <para>
42 The BSP specification does not include a build system or other tools - 43 The BSP specification does not include a build system or other tools -
43 it is concerned with the hardware-specific components only. 44 it is concerned with the hardware-specific components only.
44 At the end 45 At the end
45 distribution point you can shipt the BSP combined with a build system 46 distribution point you can ship the BSP combined with a build system
46 and other tools. 47 and other tools.
47 However, it is important to maintain the distinction that these 48 However, it is important to maintain the distinction that these
48 are separate components that happen to be combined in certain end products. 49 are separate components that happen to be combined in certain end products.
@@ -73,7 +74,6 @@ meta-bsp/packages/modem/modem-driver_0.1.bb
73meta-bsp/packages/modem/modem-daemon_0.1.bb 74meta-bsp/packages/modem/modem-daemon_0.1.bb
74meta-bsp/packages/image-creator/image-creator-native_0.1.bb 75meta-bsp/packages/image-creator/image-creator-native_0.1.bb
75meta-bsp/prebuilds/ 76meta-bsp/prebuilds/
76
77 </programlisting> 77 </programlisting>
78 </para> 78 </para>
79 79
@@ -92,8 +92,9 @@ meta-bsp/prebuilds/
92 Users could use these to get a system 92 Users could use these to get a system
93 running and quickly get started on development tasks. 93 running and quickly get started on development tasks.
94 The exact types of binaries 94 The exact types of binaries
95 present will be highly hardware-dependent but a README file should be present 95 present are highly hardware-dependent.
96 explaining how to use them with the target hardware. 96 However, a README file should be present
97 that explains how to use them with the target hardware.
97 If prebuilt binaries are 98 If prebuilt binaries are
98 present, source code to meet licensing requirements must also be provided in 99 present, source code to meet licensing requirements must also be provided in
99 some form. 100 some form.
@@ -105,8 +106,8 @@ meta-bsp/prebuilds/
105 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title> 106 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
106 107
107 <para> 108 <para>
108 This file identifies the structure as a Poky layer by identifying the 109 This file identifies the structure as a Poky layer, identifies the
109 contents of the layer and containing information about how Poky should use 110 contents of the layer and contains information about how Poky should use
110 it. 111 it.
111 Generally, a standard boilerplate file consisting of the following works. 112 Generally, a standard boilerplate file consisting of the following works.
112 </para> 113 </para>
@@ -193,9 +194,9 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
193 <para> 194 <para>
194 These files make up the definition of a kernel to use with this 195 These files make up the definition of a kernel to use with this
195 hardware. 196 hardware.
196 In this case it is a complete self-contained kernel with its own 197 In this case, it is a complete self-contained kernel with its own
197 configuration and patches but kernels can be shared between many 198 configuration and patches.
198 machines as well. 199 However, kernels can be shared between many machines as well.
199 Following is an example: 200 Following is an example:
200 <programlisting> 201 <programlisting>
201meta-bsp/packages/linux/linux-bsp_2.6.50.bb 202meta-bsp/packages/linux/linux-bsp_2.6.50.bb
@@ -216,8 +217,8 @@ linux-bsp-2.6.50/*.patch
216 </programlisting> 217 </programlisting>
217 </para> 218 </para>
218 <para> 219 <para>
219 The above example file contains patches you can apply against the base kernel, wherever 220 The above example file contains patches you can apply against the base kernel, from wherever
220 they may have been obtained from. 221 they may have been obtained.
221 </para> 222 </para>
222 <para> 223 <para>
223 <programlisting> 224 <programlisting>
@@ -225,11 +226,11 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
225 </programlisting> 226 </programlisting>
226 </para> 227 </para>
227 <para> 228 <para>
228 Finally, this last example file contains configuration information to use to configure the kernel. 229 Finally, this last example file contains kernel configuration information.
229 </para> 230 </para>
230 <para> 231 <para>
231 Examples of kernel recipes are available in Poky itself. 232 Examples of kernel recipes are available in Poky itself.
232 These files are optional since a kernel from Poky itself could be selected, although it 233 These files are optional since a kernel from Poky could be selected, although it
233 would be unusual not to have a kernel configuration. 234 would be unusual not to have a kernel configuration.
234 </para> 235 </para>
235 </section> 236 </section>
@@ -240,8 +241,8 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
240 <para> 241 <para>
241 This section describes other pieces of software that the hardware might need for best 242 This section describes other pieces of software that the hardware might need for best
242 operation. 243 operation.
243 These are examples of the kinds of things that you could encounter. 244 This section shows examples of the kinds of things that you could encounter.
244 The examples used in this section are standard <filename>.bb</filename> file recipes in the 245 The examples are standard <filename>.bb</filename> file recipes in the
245 usual Poky format. 246 usual Poky format.
246 You can include the source directly by referring to it in the source control system or 247 You can include the source directly by referring to it in the source control system or
247 the released tarballs of external software projects. 248 the released tarballs of external software projects.
@@ -250,7 +251,7 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
250 <para> 251 <para>
251 The following file is a bootloader recipe that can be used to generate a new 252 The following file is a bootloader recipe that can be used to generate a new
252 bootloader binary. 253 bootloader binary.
253 Sometimes these files are included in the final image format and are needed to reflash hardware. 254 Sometimes these files are included in the final image format and are needed to re-flash hardware.
254 </para> 255 </para>
255 <para> 256 <para>
256 <programlisting> 257 <programlisting>
@@ -270,7 +271,7 @@ meta-bsp/packages/modem/modem-daemon_0.1.bb
270 </para> 271 </para>
271 <para> 272 <para>
272 Sometimes the device needs an image in a very specific format so that the update 273 Sometimes the device needs an image in a very specific format so that the update
273 mechanism can accept and reflash it. 274 mechanism can accept and re-flash it.
274 Recipes to build the tools needed to do this can be included with the BSP. 275 Recipes to build the tools needed to do this can be included with the BSP.
275 Following is an example. 276 Following is an example.
276 </para> 277 </para>
@@ -285,15 +286,15 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
285 <title>Append BSP-Specific Information to Existing Recipes</title> 286 <title>Append BSP-Specific Information to Existing Recipes</title>
286 <para> 287 <para>
287 Suppose you have a recipe such as 'pointercal' that requires machine-specific information. 288 Suppose you have a recipe such as 'pointercal' that requires machine-specific information.
288 At the same time, you have your new BSP code nicely partitioned into a layer, which is where 289 At the same time, you have your new BSP code nicely partitioned into a layer through which
289 you would also like to specify any machine-specific information associated with your new machine. 290 you would also like to specify any machine-specific information associated with your new machine.
290 Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole 291 Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole
291 pointercal recipe and files into your layer, and then add the single file for your machine. 292 pointercal recipe and files into your layer and then add the single file for your machine.
292 </para> 293 </para>
293 <para> 294 <para>
294 With the <filename>.bbappend</filename> extension, however, your work becomes much easier. 295 With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
295 It allows you to easily merge BSP-specific information with the original recipe. 296 This extension allows you to easily merge BSP-specific information with the original recipe.
296 Whenever bitbake finds any <filename>.bbappend</filename> files, they will be 297 Whenever bitbake finds any <filename>.bbappend</filename> files they will be
297 included after bitbake loads the associated <filename>.bb</filename> but before any finalize 298 included after bitbake loads the associated <filename>.bb</filename> but before any finalize
298 or anonymous methods run. 299 or anonymous methods run.
299 This allows the BSP layer to do whatever it might want to do to customize the original recipe. 300 This allows the BSP layer to do whatever it might want to do to customize the original recipe.
@@ -326,59 +327,65 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
326 <section id='bsp-click-through-licensing'> 327 <section id='bsp-click-through-licensing'>
327 <title>BSP 'Click-Through' Licensing Procedure</title> 328 <title>BSP 'Click-Through' Licensing Procedure</title>
328 329
329 <note><para> This section is here as a description of how 330 <note><para> This section describes how
330 click-through licensing is expected to work, and is 331 click-through licensing is expected to work.
331 not yet not impemented. 332 Currently, this functionality is not yet implemented.
332 </para></note> 333 </para></note>
333 334
334 <para> 335 <para>
335 In some cases, a BSP may contain separately licensed IP 336 In some cases, a BSP contains separately licensed IP
336 (Intellectual Property) for a component, which imposes 337 (Intellectual Property) for a component that imposes
337 upon the user a requirement to accept the terms of a 338 upon the user a requirement to accept the terms of a
338 'click-through' license. Once the license is accepted 339 'click-through' license.
339 (in whatever form that may be, see details below) the 340 Once the license is accepted the
340 Poky build system can then build and include the 341 Poky build system can then build and include the
341 corresponding component in the final BSP image. Some 342 corresponding component in the final BSP image.
342 affected components may be essential to the normal 343 Some affected components might be essential to the normal
343 functioning of the system and have no 'free' replacement 344 functioning of the system and have no 'free' replacement
344 i.e. the resulting system would be non-functional 345 (i.e. the resulting system would be non-functional
345 without them. Other components may be simply 346 without them).
347 On the other hand, other components might be simply
346 'good-to-have' or purely elective, or if essential 348 'good-to-have' or purely elective, or if essential
347 nonetheless have a 'free' (possibly less-capable) 349 nonetheless have a 'free' (possibly less-capable)
348 version which may substituted for in the BSP recipe. 350 version that could be used as a in the BSP recipe.
349 </para> 351 </para>
350 352
351 <para> 353 <para>
352 For the latter cases, where it is possible to do so from 354 For cases where you can substitute something and still maintain functionality, the Poky website will make
353 a functionality perspective, the Poky website will make
354 available a 'de-featured' BSP completely free of 355 available a 'de-featured' BSP completely free of
355 encumbered IP, which can be used directly and without 356 the encumbered IP.
356 any further licensing requirements. If present, this 357 In that case you can use the substitution directly and without
358 any further licensing requirements.
359 If present, this
357 fully 'de-featured' BSP will be named meta-bsp (i.e. the 360 fully 'de-featured' BSP will be named meta-bsp (i.e. the
358 normal default naming convention). This is the simplest 361 normal default naming convention).
359 and therefore preferred option if available, assuming 362 If available, this is the simplest the most preferred option.
360 the resulting functionality meets requirements. 363 This, of course, assumes the resulting functionality meets requirements.
361 </para> 364 </para>
362 365
363 <para> 366 <para>
364 If however, a non-encumbered version is unavailable or 367 If however, a non-encumbered version is unavailable or
365 the 'free' version would provide unsuitable 368 the 'free' version would provide unsuitable
366 functionality or quality, an encumbered version can be 369 functionality or quality, an encumbered version can be
367 used. Encumbered versions of a BSP are given names of 370 used.
368 the form meta-bsp-nonfree. There are several ways 371 Encumbered versions of a BSP are given names of
369 within the Poky build system to satisfy the licensing 372 the form meta-bsp-nonfree.
370 requirements for an encumbered BSP, in roughly the 373 </para>
371 following order of preference: 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:
372 </para> 379 </para>
373 380
374 <itemizedlist> 381 <orderedlist>
375 <listitem> 382 <listitem>
376 383
377 <para> 384 <para>
378 Get a license key (or keys) for the encumbered BSP 385 Get a license key (or keys) for the encumbered BSP
379 by visiting 386 by visiting
380 <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> 387 <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
381 and give the web form there the name of the BSP and your e-mail address. 388 and give the name of the BSP and your e-mail address in the web form.
382 </para> 389 </para>
383 390
384 <programlisting> 391 <programlisting>
@@ -388,7 +395,7 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
388 <para> 395 <para>
389 After agreeing to any applicable license terms, the 396 After agreeing to any applicable license terms, the
390 BSP key(s) will be immediately sent to the address 397 BSP key(s) will be immediately sent to the address
391 given and can be used by specifying BSPKEY_&lt;keydomain&gt; 398 you gave and you can use them by specifying BSPKEY_&lt;keydomain&gt;
392 environment variables when building the image: 399 environment variables when building the image:
393 </para> 400 </para>
394 401
@@ -397,40 +404,42 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
397 </programlisting> 404 </programlisting>
398 405
399 <para> 406 <para>
400 This will allow the encumbered image to be built 407 These steps allow the encumbered image to be built
401 with no change at all to the normal build process. 408 with no change at all to the normal build process.
402 </para> 409 </para>
403 410
404 <para> 411 <para>
405 Equivalently and probably more conveniently, a line 412 Equivalently and probably more conveniently, a line
406 for each key can instead be put into the user's 413 for each key can instead be put into the user's
407 local.conf file. 414 <filename>local.conf</filename> file.
408 </para> 415 </para>
409 416
410 <para> 417 <para>
411 The &lt;keydomain&gt; component of the 418 The &lt;keydomain&gt; component of the
412 BSPKEY_&lt;keydomain&gt; is required because there 419 BSPKEY_&lt;keydomain&gt; is required because there
413 may be multiple licenses in effect for a give BSP; a 420 might be multiple licenses in effect for a give BSP.
414 given &lt;keydomain&gt; in such cases corresponds to 421 In such cases, a given &lt;keydomain&gt; corresponds to
415 a particular license. In order for an encumbered 422 a particular license. In order for an encumbered
416 BSP encompassing multiple key domains to be built 423 BSP that encompasses multiple key domains to be built
417 successfully, a &lt;keydomain&gt; entry for each 424 successfully, a &lt;keydomain&gt; entry for each
418 applicable license must be present in local.conf or 425 applicable license must be present in <filename>local.conf</filename> or
419 supplied on the command-line. 426 supplied on the command-line.
420 </para> 427 </para>
421 </listitem> 428 </listitem>
422 <listitem> 429 <listitem>
423 <para> 430 <para>
424 Do nothing - build as you normally would, and follow 431 Do nothing - build as you normally would.
425 any license prompts that originate from the 432 When a license is needed the build will stop and prompt you with instructions.
426 encumbered BSP (the build will cleanly stop at this 433 Follow the license prompts that originate from the
427 point). These usually take the form of instructions 434 encumbered BSP.
435 These prompts usually take the form of instructions
428 needed to manually fetch the encumbered package(s) 436 needed to manually fetch the encumbered package(s)
429 and md5 sums into e.g. the poky/build/downloads 437 and md5 sums into the required directory (e.g. the poky/build/downloads)
430 directory. Once the manual package fetch has been 438 Once the manual package fetch has been
431 completed, restarting the build will continue where 439 completed, restart the build to continue where
432 it left off, this time without the prompt since the 440 it left off.
433 license requirements will have been satisfied. 441 During the build the prompt will not appear again since you have satisfied the
442 requirement.
434 </para> 443 </para>
435 </listitem> 444 </listitem>
436 <listitem> 445 <listitem>
@@ -440,7 +449,7 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
440 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. 449 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
441 Accepting the license agreement(s) presented will 450 Accepting the license agreement(s) presented will
442 subsequently allow you to download a tarball 451 subsequently allow you to download a tarball
443 containing a full-featured BSP legally cleared for 452 containing a full-featured BSP that is legally cleared for
444 your use by the just-given license agreement(s). 453 your use by the just-given license agreement(s).
445 This method will also allow the encumbered image to 454 This method will also allow the encumbered image to
446 be built with no change at all to the normal build 455 be built with no change at all to the normal build
@@ -449,9 +458,10 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
449 </listitem> 458 </listitem>
450 </itemizedlist> 459 </itemizedlist>
451 <para> 460 <para>
452 Note that method 3 is also the only option available 461 Note that the third method is also the only option available
453 when downloading pre-compiled images generated from 462 when downloading pre-compiled images generated from
454 non-free BSPs. Those images are likewise available at 463 non-free BSPs.
464 Those images are likewise available at
455 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. 465 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
456 </para> 466 </para>
457 </section> 467 </section>