summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual/bsp.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2010-11-11 10:23:10 -0800
committerRichard Purdie <rpurdie@linux.intel.com>2010-11-15 22:25:25 +0000
commit2d6441d17e291e3779c117aaf048e74a26834bc0 (patch)
tree3bd695e40bd5489a3ecdc20d9be283072421c2a3 /documentation/poky-ref-manual/bsp.xml
parent89e64dbe9e1142216e5dcc75dd7aea63b3c61366 (diff)
downloadpoky-2d6441d17e291e3779c117aaf048e74a26834bc0.tar.gz
BSP Guide and BSP Chapter: Sync'ed these two files
After moving BSP Guide into its own folder for documentation I discovered a consequence of that. There are two separate bsp.xml files now: one in the poky-ref-manual folder and one in the bsp folder. I had done some good cleanup work in the version in the poky-ref-manual folder. This commit reflects a 'meld' operation where I re-sync'ed the bsp.xml file in the bsp-guide folder to be the same (almost) as the one in the poky-ref-manual folder. There is still one slight difference between the two files due to one's context as a stand-alone manual and the other as a section in a larger book. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Diffstat (limited to 'documentation/poky-ref-manual/bsp.xml')
-rw-r--r--documentation/poky-ref-manual/bsp.xml152
1 files changed, 81 insertions, 71 deletions
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>