summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-07 23:21:20 (GMT)
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-12-11 16:15:24 (GMT)
commiteb8c9e1494692583f77d83267f78d5d88a79973d (patch)
tree14c2fc28df0901ba57430d1b36112281e53de455 /documentation/bsp-guide
parent3bcdba62b186c554033357bb50de0b20d115a54d (diff)
downloadpoky-eb8c9e1494692583f77d83267f78d5d88a79973d.tar.gz
Documentation: bsp-guide - Removed all trailing whitespace.
(From yocto-docs rev: 00d9bb4dcce101a77761418c1279ebfb9441b0d2) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/bsp-guide')
-rw-r--r--documentation/bsp-guide/bsp-guide.xml18
-rw-r--r--documentation/bsp-guide/bsp.xml546
2 files changed, 282 insertions, 282 deletions
diff --git a/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml
index 5f7551e..4bbc0c5 100644
--- a/documentation/bsp-guide/bsp-guide.xml
+++ b/documentation/bsp-guide/bsp-guide.xml
@@ -2,7 +2,7 @@
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > 3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<book id='bsp-guide' lang='en' 5<book id='bsp-guide' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude" 6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook" 7 xmlns="http://docbook.org/ns/docbook"
8 > 8 >
@@ -10,13 +10,13 @@
10 10
11 <mediaobject> 11 <mediaobject>
12 <imageobject> 12 <imageobject>
13 <imagedata fileref='figures/bsp-title.png' 13 <imagedata fileref='figures/bsp-title.png'
14 format='SVG' 14 format='SVG'
15 align='center' scalefit='1' width='100%'/> 15 align='center' scalefit='1' width='100%'/>
16 </imageobject> 16 </imageobject>
17 </mediaobject> 17 </mediaobject>
18 18
19 <title></title> 19 <title></title>
20 20
21 <authorgroup> 21 <authorgroup>
22 <author> 22 <author>
@@ -80,12 +80,12 @@
80 80
81 <legalnotice> 81 <legalnotice>
82 <para> 82 <para>
83 Permission is granted to copy, distribute and/or modify this document under 83 Permission is granted to copy, distribute and/or modify this document under
84 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons. 84 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
85 </para> 85 </para>
86 <note> 86 <note>
87 Due to production processes, there could be differences between the Yocto Project 87 Due to production processes, there could be differences between the Yocto Project
88 documentation bundled in the release tarball and the 88 documentation bundled in the release tarball and the
89 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink> on 89 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink> on
90 the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. 90 the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
91 For the latest version of this manual, see the manual on the website. 91 For the latest version of this manual, see the manual on the website.
@@ -102,6 +102,6 @@
102--> 102-->
103 103
104</book> 104</book>
105<!-- 105<!--
106vim: expandtab tw=80 ts=4 106vim: expandtab tw=80 ts=4
107--> 107-->
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 020e350..94415a6 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -8,13 +8,13 @@
8 8
9 <para> 9 <para>
10 A Board Support Package (BSP) is a collection of information that 10 A Board Support Package (BSP) is a collection of information that
11 defines how to support a particular hardware device, set of devices, or 11 defines how to support a particular hardware device, set of devices, or
12 hardware platform. 12 hardware platform.
13 The BSP includes information about the hardware features 13 The BSP includes information about the hardware features
14 present on the device and kernel configuration information along with any 14 present on the device and kernel configuration information along with any
15 additional hardware drivers required. 15 additional hardware drivers required.
16 The BSP also lists any additional software 16 The BSP also lists any additional software
17 components required in addition to a generic Linux software stack for both 17 components required in addition to a generic Linux software stack for both
18 essential and optional platform features. 18 essential and optional platform features.
19 </para> 19 </para>
20 20
@@ -22,8 +22,8 @@
22 This guide presents information about BSP Layers, defines a structure for components 22 This guide presents information about BSP Layers, defines a structure for components
23 so that BSPs follow a commonly understood layout, discusses how to customize 23 so that BSPs follow a commonly understood layout, discusses how to customize
24 a recipe for a BSP, addresses BSP licensing, and provides information that 24 a recipe for a BSP, addresses BSP licensing, and provides information that
25 shows you how to create and manage a 25 shows you how to create and manage a
26 <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project 26 <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project
27 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>. 27 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
28 </para> 28 </para>
29 29
@@ -32,7 +32,7 @@
32 32
33 <para> 33 <para>
34 The BSP consists of a file structure inside a base directory. 34 The BSP consists of a file structure inside a base directory.
35 Collectively, you can think of the base directory and the file structure 35 Collectively, you can think of the base directory and the file structure
36 as a BSP Layer. 36 as a BSP Layer.
37 BSP Layers use the following naming convention: 37 BSP Layers use the following naming convention:
38 <literallayout class='monospaced'> 38 <literallayout class='monospaced'>
@@ -42,13 +42,13 @@
42 </para> 42 </para>
43 43
44 <para> 44 <para>
45 The layer's base directory (<filename>meta-&lt;bsp_name&gt;</filename>) is the root 45 The layer's base directory (<filename>meta-&lt;bsp_name&gt;</filename>) is the root
46 of the BSP Layer. 46 of the BSP Layer.
47 This root is what you add to the 47 This root is what you add to the
48 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> 48 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
49 variable in the <filename>conf/bblayers.conf</filename> file found in the 49 variable in the <filename>conf/bblayers.conf</filename> file found in the
50 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 50 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
51 Adding the root allows the OpenEmbedded build system to recognize the BSP 51 Adding the root allows the OpenEmbedded build system to recognize the BSP
52 definition and from it build an image. 52 definition and from it build an image.
53 Here is an example: 53 Here is an example:
54 <literallayout class='monospaced'> 54 <literallayout class='monospaced'>
@@ -70,9 +70,9 @@
70 Some BSPs require additional layers on 70 Some BSPs require additional layers on
71 top of the BSP's root layer in order to be functional. 71 top of the BSP's root layer in order to be functional.
72 For these cases, you also need to add those layers to the 72 For these cases, you also need to add those layers to the
73 <filename>BBLAYERS</filename> variable in order to build the BSP. 73 <filename>BBLAYERS</filename> variable in order to build the BSP.
74 You must also specify in the "Dependencies" section of the BSP's 74 You must also specify in the "Dependencies" section of the BSP's
75 <filename>README</filename> file any requirements for additional 75 <filename>README</filename> file any requirements for additional
76 layers and, preferably, any 76 layers and, preferably, any
77 build instructions that might be contained elsewhere 77 build instructions that might be contained elsewhere
78 in the <filename>README</filename> file. 78 in the <filename>README</filename> file.
@@ -80,13 +80,13 @@
80 80
81 <para> 81 <para>
82 Some layers function as a layer to hold other BSP layers. 82 Some layers function as a layer to hold other BSP layers.
83 An example of this type of layer is the <filename>meta-intel</filename> layer. 83 An example of this type of layer is the <filename>meta-intel</filename> layer.
84 The <filename>meta-intel</filename> layer contains over 10 individual BSP layers. 84 The <filename>meta-intel</filename> layer contains over 10 individual BSP layers.
85 </para> 85 </para>
86 86
87 <para> 87 <para>
88 For more detailed information on layers, see the 88 For more detailed information on layers, see the
89 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" 89 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
90 section of the Yocto Project Development Manual. 90 section of the Yocto Project Development Manual.
91 </para> 91 </para>
92 </section> 92 </section>
@@ -96,38 +96,38 @@
96 <title>Example Filesystem Layout</title> 96 <title>Example Filesystem Layout</title>
97 97
98 <para> 98 <para>
99 Providing a common form allows end-users to understand and become familiar 99 Providing a common form allows end-users to understand and become familiar
100 with the layout. 100 with the layout.
101 A common format also encourages standardization of software support of hardware. 101 A common format also encourages standardization of software support of hardware.
102 </para> 102 </para>
103 103
104 <para> 104 <para>
105 The proposed form does have elements that are specific to the 105 The proposed form does have elements that are specific to the
106 OpenEmbedded build system. 106 OpenEmbedded build system.
107 It is intended that this information can be 107 It is intended that this information can be
108 used by other build systems besides the OpenEmbedded build system 108 used by other build systems besides the OpenEmbedded build system
109 and that it will be simple 109 and that it will be simple
110 to extract information and convert it to other formats if required. 110 to extract information and convert it to other formats if required.
111 The OpenEmbedded build system, through its standard layers mechanism, can directly 111 The OpenEmbedded build system, through its standard layers mechanism, can directly
112 accept the format described as a layer. 112 accept the format described as a layer.
113 The BSP captures all 113 The BSP captures all
114 the hardware-specific details in one place in a standard format, which is 114 the hardware-specific details in one place in a standard format, which is
115 useful for any person wishing to use the hardware platform regardless of 115 useful for any person wishing to use the hardware platform regardless of
116 the build system they are using. 116 the build system they are using.
117 </para> 117 </para>
118 118
119 <para> 119 <para>
120 The BSP specification does not include a build system or other tools - 120 The BSP specification does not include a build system or other tools -
121 it is concerned with the hardware-specific components only. 121 it is concerned with the hardware-specific components only.
122 At the end-distribution point, you can ship the BSP combined with a build system 122 At the end-distribution point, you can ship the BSP combined with a build system
123 and other tools. 123 and other tools.
124 However, it is important to maintain the distinction that these 124 However, it is important to maintain the distinction that these
125 are separate components that happen to be combined in certain end products. 125 are separate components that happen to be combined in certain end products.
126 </para> 126 </para>
127 127
128 <para> 128 <para>
129 Before looking at the common form for the file structure inside a BSP Layer, 129 Before looking at the common form for the file structure inside a BSP Layer,
130 you should be aware that some requirements do exist in order for a BSP to 130 you should be aware that some requirements do exist in order for a BSP to
131 be considered compliant with the Yocto Project. 131 be considered compliant with the Yocto Project.
132 For that list of requirements, see the 132 For that list of requirements, see the
133 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>" 133 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
@@ -137,19 +137,19 @@
137 <para> 137 <para>
138 Below is the common form for the file structure inside a BSP Layer. 138 Below is the common form for the file structure inside a BSP Layer.
139 While you can use this basic form for the standard, realize that the actual structures 139 While you can use this basic form for the standard, realize that the actual structures
140 for specific BSPs could differ. 140 for specific BSPs could differ.
141 141
142 <literallayout class='monospaced'> 142 <literallayout class='monospaced'>
143 meta-&lt;bsp_name&gt;/ 143 meta-&lt;bsp_name&gt;/
144 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt; 144 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
145 meta-&lt;bsp_name&gt;/README 145 meta-&lt;bsp_name&gt;/README
146 meta-&lt;bsp_name&gt;/README.sources 146 meta-&lt;bsp_name&gt;/README.sources
147 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt; 147 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
148 meta-&lt;bsp_name&gt;/conf/layer.conf 148 meta-&lt;bsp_name&gt;/conf/layer.conf
149 meta-&lt;bsp_name&gt;/conf/machine/*.conf 149 meta-&lt;bsp_name&gt;/conf/machine/*.conf
150 meta-&lt;bsp_name&gt;/recipes-bsp/* 150 meta-&lt;bsp_name&gt;/recipes-bsp/*
151 meta-&lt;bsp_name&gt;/recipes-core/* 151 meta-&lt;bsp_name&gt;/recipes-core/*
152 meta-&lt;bsp_name&gt;/recipes-graphics/* 152 meta-&lt;bsp_name&gt;/recipes-graphics/*
153 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_&lt;kernel_rev&gt;.bbappend 153 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_&lt;kernel_rev&gt;.bbappend
154 </literallayout> 154 </literallayout>
155 </para> 155 </para>
@@ -209,8 +209,8 @@
209 <para> 209 <para>
210 These optional files satisfy licensing requirements for the BSP. 210 These optional files satisfy licensing requirements for the BSP.
211 The type or types of files here can vary depending on the licensing requirements. 211 The type or types of files here can vary depending on the licensing requirements.
212 For example, in the Crown Bay BSP all licensing requirements are handled with the 212 For example, in the Crown Bay BSP all licensing requirements are handled with the
213 <filename>COPYING.MIT</filename> file. 213 <filename>COPYING.MIT</filename> file.
214 </para> 214 </para>
215 215
216 <para> 216 <para>
@@ -229,9 +229,9 @@
229 </para> 229 </para>
230 230
231 <para> 231 <para>
232 This file provides information on how to boot the live images that are optionally 232 This file provides information on how to boot the live images that are optionally
233 included in the <filename>binary/</filename> directory. 233 included in the <filename>binary/</filename> directory.
234 The <filename>README</filename> file also provides special information needed for 234 The <filename>README</filename> file also provides special information needed for
235 building the image. 235 building the image.
236 </para> 236 </para>
237 237
@@ -271,20 +271,20 @@
271 </para> 271 </para>
272 272
273 <para> 273 <para>
274 This optional area contains useful pre-built kernels and user-space filesystem 274 This optional area contains useful pre-built kernels and user-space filesystem
275 images appropriate to the target system. 275 images appropriate to the target system.
276 This directory typically contains graphical (e.g. sato) and minimal live images 276 This directory typically contains graphical (e.g. sato) and minimal live images
277 when the BSP tarball has been created and made available in the 277 when the BSP tarball has been created and made available in the
278 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. 278 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
279 You can use these kernels and images to get a system running and quickly get started 279 You can use these kernels and images to get a system running and quickly get started
280 on development tasks. 280 on development tasks.
281 </para> 281 </para>
282 282
283 <para> 283 <para>
284 The exact types of binaries present are highly hardware-dependent. 284 The exact types of binaries present are highly hardware-dependent.
285 However, a README file should be present in the BSP Layer that explains how to use 285 However, a README file should be present in the BSP Layer that explains how to use
286 the kernels and images with the target hardware. 286 the kernels and images with the target hardware.
287 If pre-built binaries are present, source code to meet licensing requirements must also 287 If pre-built binaries are present, source code to meet licensing requirements must also
288 exist in some form. 288 exist in some form.
289 </para> 289 </para>
290 </section> 290 </section>
@@ -299,12 +299,12 @@
299 </para> 299 </para>
300 300
301 <para> 301 <para>
302 The <filename>conf/layer.conf</filename> file identifies the file structure as a 302 The <filename>conf/layer.conf</filename> file identifies the file structure as a
303 layer, identifies the 303 layer, identifies the
304 contents of the layer, and contains information about how the build 304 contents of the layer, and contains information about how the build
305 system should use it. 305 system should use it.
306 Generally, a standard boilerplate file such as the following works. 306 Generally, a standard boilerplate file such as the following works.
307 In the following example, you would replace "<filename>bsp</filename>" and 307 In the following example, you would replace "<filename>bsp</filename>" and
308 "<filename>_bsp</filename>" with the actual name 308 "<filename>_bsp</filename>" with the actual name
309 of the BSP (i.e. <filename>&lt;bsp_name&gt;</filename> from the example template). 309 of the BSP (i.e. <filename>&lt;bsp_name&gt;</filename> from the example template).
310 </para> 310 </para>
@@ -325,7 +325,7 @@
325 </para> 325 </para>
326 326
327 <para> 327 <para>
328 To illustrate the string substitutions, here are the last three statements from the Crown 328 To illustrate the string substitutions, here are the last three statements from the Crown
329 Bay <filename>conf/layer.conf</filename> file: 329 Bay <filename>conf/layer.conf</filename> file:
330 <literallayout class='monospaced'> 330 <literallayout class='monospaced'>
331 BBFILE_COLLECTIONS += "crownbay" 331 BBFILE_COLLECTIONS += "crownbay"
@@ -351,10 +351,10 @@
351 351
352 <para> 352 <para>
353 The machine files bind together all the information contained elsewhere 353 The machine files bind together all the information contained elsewhere
354 in the BSP into a format that the build system can understand. 354 in the BSP into a format that the build system can understand.
355 If the BSP supports multiple machines, multiple machine configuration files 355 If the BSP supports multiple machines, multiple machine configuration files
356 can be present. 356 can be present.
357 These filenames correspond to the values to which users have set the 357 These filenames correspond to the values to which users have set the
358 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. 358 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
359 </para> 359 </para>
360 360
@@ -370,13 +370,13 @@
370 <para> 370 <para>
371 Each BSP Layer requires at least one machine file. 371 Each BSP Layer requires at least one machine file.
372 However, you can supply more than one file. 372 However, you can supply more than one file.
373 For example, in the Crown Bay BSP shown earlier in this section, the 373 For example, in the Crown Bay BSP shown earlier in this section, the
374 <filename>conf/machine</filename> directory contains two configuration files: 374 <filename>conf/machine</filename> directory contains two configuration files:
375 <filename>crownbay.conf</filename> and <filename>crownbay-noemgd.conf</filename>. 375 <filename>crownbay.conf</filename> and <filename>crownbay-noemgd.conf</filename>.
376 The <filename>crownbay.conf</filename> file is used for the Crown Bay BSP 376 The <filename>crownbay.conf</filename> file is used for the Crown Bay BSP
377 that supports the <trademark class='registered'>Intel</trademark> Embedded 377 that supports the <trademark class='registered'>Intel</trademark> Embedded
378 Media and Graphics Driver (<trademark class='registered'>Intel</trademark> 378 Media and Graphics Driver (<trademark class='registered'>Intel</trademark>
379 EMGD), while the <filename>crownbay-noemgd.conf</filename> file is used for the 379 EMGD), while the <filename>crownbay-noemgd.conf</filename> file is used for the
380 Crown Bay BSP that does not support the <trademark class='registered'>Intel</trademark> 380 Crown Bay BSP that does not support the <trademark class='registered'>Intel</trademark>
381 EMGD. 381 EMGD.
382 </para> 382 </para>
@@ -384,23 +384,23 @@
384 <para> 384 <para>
385 This <filename>crownbay.conf</filename> file could also include 385 This <filename>crownbay.conf</filename> file could also include
386 a hardware "tuning" file that is commonly used to 386 a hardware "tuning" file that is commonly used to
387 define the package architecture and specify 387 define the package architecture and specify
388 optimization flags, which are carefully chosen to give best 388 optimization flags, which are carefully chosen to give best
389 performance on a given processor. 389 performance on a given processor.
390 </para> 390 </para>
391 391
392 <para> 392 <para>
393 Tuning files are found in the <filename>meta/conf/machine/include</filename> 393 Tuning files are found in the <filename>meta/conf/machine/include</filename>
394 directory within the 394 directory within the
395 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 395 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
396 Tuning files can also reside in the BSP Layer itself. 396 Tuning files can also reside in the BSP Layer itself.
397 For example, the <filename>ia32-base.inc</filename> file resides in the 397 For example, the <filename>ia32-base.inc</filename> file resides in the
398 <filename>meta-intel</filename> BSP Layer in <filename>conf/machine/include</filename>. 398 <filename>meta-intel</filename> BSP Layer in <filename>conf/machine/include</filename>.
399 </para> 399 </para>
400 400
401 <para> 401 <para>
402 To use an include file, you simply include them in the machine configuration file. 402 To use an include file, you simply include them in the machine configuration file.
403 For example, the Crown Bay BSP <filename>crownbay.conf</filename> has the 403 For example, the Crown Bay BSP <filename>crownbay.conf</filename> has the
404 following statements: 404 following statements:
405 <literallayout class='monospaced'> 405 <literallayout class='monospaced'>
406 require conf/machine/include/tune-atom.inc 406 require conf/machine/include/tune-atom.inc
@@ -415,19 +415,19 @@
415 You can find these files in the BSP Layer at: 415 You can find these files in the BSP Layer at:
416 <literallayout class='monospaced'> 416 <literallayout class='monospaced'>
417 meta-&lt;bsp_name&gt;/recipes-bsp/* 417 meta-&lt;bsp_name&gt;/recipes-bsp/*
418 </literallayout> 418 </literallayout>
419 </para> 419 </para>
420 420
421 <para> 421 <para>
422 This optional directory contains miscellaneous recipe files for the BSP. 422 This optional directory contains miscellaneous recipe files for the BSP.
423 Most notably would be the formfactor files. 423 Most notably would be the formfactor files.
424 For example, in the Crown Bay BSP there is the 424 For example, in the Crown Bay BSP there is the
425 <filename>formfactor_0.0.bbappend</filename> file, which is an append file used 425 <filename>formfactor_0.0.bbappend</filename> file, which is an append file used
426 to augment the recipe that starts the build. 426 to augment the recipe that starts the build.
427 Furthermore, there are machine-specific settings used during the build that are 427 Furthermore, there are machine-specific settings used during the build that are
428 defined by the <filename>machconfig</filename> files. 428 defined by the <filename>machconfig</filename> files.
429 In the Crown Bay example, two <filename>machconfig</filename> files exist: 429 In the Crown Bay example, two <filename>machconfig</filename> files exist:
430 one that supports the 430 one that supports the
431 <trademark class='registered'>Intel</trademark> Embedded 431 <trademark class='registered'>Intel</trademark> Embedded
432 Media and Graphics Driver (<trademark class='registered'>Intel</trademark> 432 Media and Graphics Driver (<trademark class='registered'>Intel</trademark>
433 EMGD) and one that does not: 433 EMGD) and one that does not:
@@ -440,10 +440,10 @@
440 440
441 <note><para> 441 <note><para>
442 If a BSP does not have a formfactor entry, defaults are established according to 442 If a BSP does not have a formfactor entry, defaults are established according to
443 the formfactor configuration file that is installed by the main 443 the formfactor configuration file that is installed by the main
444 formfactor recipe 444 formfactor recipe
445 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, 445 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
446 which is found in the 446 which is found in the
447 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 447 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
448 </para></note> 448 </para></note>
449 </section> 449 </section>
@@ -453,19 +453,19 @@
453 <para> 453 <para>
454 You can find these files in the BSP Layer at: 454 You can find these files in the BSP Layer at:
455 <literallayout class='monospaced'> 455 <literallayout class='monospaced'>
456 meta-&lt;bsp_name&gt;/recipes-graphics/* 456 meta-&lt;bsp_name&gt;/recipes-graphics/*
457 </literallayout> 457 </literallayout>
458 </para> 458 </para>
459 459
460 <para> 460 <para>
461 This optional directory contains recipes for the BSP if it has 461 This optional directory contains recipes for the BSP if it has
462 special requirements for graphics support. 462 special requirements for graphics support.
463 All files that are needed for the BSP to support a display are kept here. 463 All files that are needed for the BSP to support a display are kept here.
464 For example, the Crown Bay BSP contains two versions of the 464 For example, the Crown Bay BSP contains two versions of the
465 <filename>xorg.conf</filename> file. 465 <filename>xorg.conf</filename> file.
466 The version in <filename>crownbay</filename> builds a BSP that supports the 466 The version in <filename>crownbay</filename> builds a BSP that supports the
467 <trademark class='registered'>Intel</trademark> Embedded Media Graphics Driver (EMGD), 467 <trademark class='registered'>Intel</trademark> Embedded Media Graphics Driver (EMGD),
468 while the version in <filename>crownbay-noemgd</filename> builds 468 while the version in <filename>crownbay-noemgd</filename> builds
469 a BSP that supports Video Electronics Standards Association (VESA) graphics only: 469 a BSP that supports Video Electronics Standards Association (VESA) graphics only:
470 <literallayout class='monospaced'> 470 <literallayout class='monospaced'>
471 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend 471 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
@@ -488,29 +488,29 @@
488 These files append your specific changes to the main kernel recipe you are using. 488 These files append your specific changes to the main kernel recipe you are using.
489 </para> 489 </para>
490 <para> 490 <para>
491 For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the 491 For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the
492 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 492 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
493 at <filename>meta/recipes-kernel/linux</filename>. 493 at <filename>meta/recipes-kernel/linux</filename>.
494 You can append your specific changes to the kernel recipe by using a 494 You can append your specific changes to the kernel recipe by using a
495 similarly named append file, which is located in the BSP Layer (e.g. 495 similarly named append file, which is located in the BSP Layer (e.g.
496 the <filename>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> directory). 496 the <filename>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> directory).
497 </para> 497 </para>
498 <para> 498 <para>
499 Suppose you are using the <filename>linux-yocto_3.4.bb</filename> recipe to build 499 Suppose you are using the <filename>linux-yocto_3.4.bb</filename> recipe to build
500 the kernel. 500 the kernel.
501 In other words, you have selected the kernel in your 501 In other words, you have selected the kernel in your
502 <filename>&lt;bsp_name&gt;.conf</filename> file by adding these types 502 <filename>&lt;bsp_name&gt;.conf</filename> file by adding these types
503 of statements: 503 of statements:
504 <literallayout class='monospaced'> 504 <literallayout class='monospaced'>
505 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 505 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
506 PREFERRED_VERSION_linux-yocto = "3.4%" 506 PREFERRED_VERSION_linux-yocto = "3.4%"
507 </literallayout> 507 </literallayout>
508 <note> 508 <note>
509 When the preferred provider is assumed by default, the 509 When the preferred provider is assumed by default, the
510 <filename>PREFERRED_PROVIDER</filename> statement does not appear in the 510 <filename>PREFERRED_PROVIDER</filename> statement does not appear in the
511 <filename>&lt;bsp_name&gt;.conf</filename> file. 511 <filename>&lt;bsp_name&gt;.conf</filename> file.
512 </note> 512 </note>
513 You would use the <filename>linux-yocto_3.4.bbappend</filename> file to append 513 You would use the <filename>linux-yocto_3.4.bbappend</filename> file to append
514 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. 514 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.
515 </para> 515 </para>
516 <para> 516 <para>
@@ -545,11 +545,11 @@
545 SRC_URI_crownbay = "git://git.yoctoproject.org/linux-yocto-3.4.git;protocol=git;nocheckout=1;branch=${KBRANCH},meta,emgd-1.14;name=machine,meta,emgd" 545 SRC_URI_crownbay = "git://git.yoctoproject.org/linux-yocto-3.4.git;protocol=git;nocheckout=1;branch=${KBRANCH},meta,emgd-1.14;name=machine,meta,emgd"
546 SRC_URI_crownbay-noemgd = "git://git.yoctoproject.org/linux-yocto-3.4.git;protocol=git;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta" 546 SRC_URI_crownbay-noemgd = "git://git.yoctoproject.org/linux-yocto-3.4.git;protocol=git;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
547 </literallayout> 547 </literallayout>
548 This append file contains statements used to support the Crown Bay BSP for both 548 This append file contains statements used to support the Crown Bay BSP for both
549 <trademark class='registered'>Intel</trademark> EMGD and the VESA graphics. 549 <trademark class='registered'>Intel</trademark> EMGD and the VESA graphics.
550 The build process, in this case, recognizes and uses only the statements that 550 The build process, in this case, recognizes and uses only the statements that
551 apply to the defined machine name - <filename>crownbay</filename> in this case. 551 apply to the defined machine name - <filename>crownbay</filename> in this case.
552 So, the applicable statements in the <filename>linux-yocto_3.4.bbappend</filename> 552 So, the applicable statements in the <filename>linux-yocto_3.4.bbappend</filename>
553 file are follows: 553 file are follows:
554 <literallayout class='monospaced'> 554 <literallayout class='monospaced'>
555 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 555 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@@ -562,46 +562,46 @@
562 SRCREV_meta_pn-linux-yocto_crownbay ?= "9e3bdb7344054264b750e53fbbb6394cc1c942ac" 562 SRCREV_meta_pn-linux-yocto_crownbay ?= "9e3bdb7344054264b750e53fbbb6394cc1c942ac"
563 SRCREV_emgd_pn-linux-yocto_crownbay ?= "86643bdd8cbad616a161ab91f51108cf0da827bc" 563 SRCREV_emgd_pn-linux-yocto_crownbay ?= "86643bdd8cbad616a161ab91f51108cf0da827bc"
564 </literallayout> 564 </literallayout>
565 The append file defines <filename>crownbay</filename> as the 565 The append file defines <filename>crownbay</filename> as the
566 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> 566 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
567 and uses the 567 and uses the
568 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> variable to 568 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> variable to
569 ensure the machine name used by the OpenEmbedded build system maps to the 569 ensure the machine name used by the OpenEmbedded build system maps to the
570 machine name used by the Linux Yocto kernel. 570 machine name used by the Linux Yocto kernel.
571 The file also uses the optional 571 The file also uses the optional
572 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> variable 572 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> variable
573 to ensure the build process uses the <filename>standard/default/crownbay</filename> 573 to ensure the build process uses the <filename>standard/default/crownbay</filename>
574 kernel branch. 574 kernel branch.
575 Finally, the append file points to specific commits in the 575 Finally, the append file points to specific commits in the
576 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> Git 576 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> Git
577 repository and the <filename>meta</filename> Git repository branches to identify the 577 repository and the <filename>meta</filename> Git repository branches to identify the
578 exact kernel needed to build the Crown Bay BSP. 578 exact kernel needed to build the Crown Bay BSP.
579 <note> 579 <note>
580 For <filename>crownbay</filename>, a specific commit is also needed to point 580 For <filename>crownbay</filename>, a specific commit is also needed to point
581 to the branch that supports EMGD graphics. 581 to the branch that supports EMGD graphics.
582 At a minimum, every BSP points to the 582 At a minimum, every BSP points to the
583 <filename>machine</filename> and <filename>meta</filename> commits. 583 <filename>machine</filename> and <filename>meta</filename> commits.
584 </note> 584 </note>
585 </para> 585 </para>
586 586
587 <para> 587 <para>
588 One thing missing in this particular BSP, which you will typically need when 588 One thing missing in this particular BSP, which you will typically need when
589 developing a BSP, is the kernel configuration file (<filename>.config</filename>) for your BSP. 589 developing a BSP, is the kernel configuration file (<filename>.config</filename>) for your BSP.
590 When developing a BSP, you probably have a kernel configuration file or a set of kernel 590 When developing a BSP, you probably have a kernel configuration file or a set of kernel
591 configuration files that, when taken together, define the kernel configuration for your BSP. 591 configuration files that, when taken together, define the kernel configuration for your BSP.
592 You can accomplish this definition by putting the configurations in a file or a set of files 592 You can accomplish this definition by putting the configurations in a file or a set of files
593 inside a directory located at the same level as your kernel's append file and having the same 593 inside a directory located at the same level as your kernel's append file and having the same
594 name as the kernel's main recipe file. 594 name as the kernel's main recipe file.
595 With all these conditions met, simply reference those files in a 595 With all these conditions met, simply reference those files in a
596 <filename>SRC_URI</filename> statement in the append file. 596 <filename>SRC_URI</filename> statement in the append file.
597 </para> 597 </para>
598 598
599 <para> 599 <para>
600 For example, suppose you had a some configuration options in a file called 600 For example, suppose you had a some configuration options in a file called
601 <filename>network_configs.cfg</filename>. 601 <filename>network_configs.cfg</filename>.
602 You can place that file inside a directory named <filename>/linux-yocto</filename> and then add 602 You can place that file inside a directory named <filename>/linux-yocto</filename> and then add
603 a <filename>SRC_URI</filename> statement such as the following to the append file. 603 a <filename>SRC_URI</filename> statement such as the following to the append file.
604 When the OpenEmbedded build system builds the kernel, the configuration options are 604 When the OpenEmbedded build system builds the kernel, the configuration options are
605 picked up and applied. 605 picked up and applied.
606 <literallayout class='monospaced'> 606 <literallayout class='monospaced'>
607 SRC_URI += "file://network_configs.cfg" 607 SRC_URI += "file://network_configs.cfg"
@@ -609,7 +609,7 @@
609 </para> 609 </para>
610 610
611 <para> 611 <para>
612 To group related configurations into multiple files, you perform a similar procedure. 612 To group related configurations into multiple files, you perform a similar procedure.
613 Here is an example that groups separate configurations specifically for Ethernet and graphics 613 Here is an example that groups separate configurations specifically for Ethernet and graphics
614 into their own files and adds the configurations 614 into their own files and adds the configurations
615 by using a <filename>SRC_URI</filename> statement like the following in your append file: 615 by using a <filename>SRC_URI</filename> statement like the following in your append file:
@@ -621,9 +621,9 @@
621 </para> 621 </para>
622 622
623 <para> 623 <para>
624 The <filename>FILESEXTRAPATHS</filename> variable is in boilerplate form in the 624 The <filename>FILESEXTRAPATHS</filename> variable is in boilerplate form in the
625 previous example in order to make it easy to do that. 625 previous example in order to make it easy to do that.
626 This variable must be in your layer or BitBake will not find the patches or 626 This variable must be in your layer or BitBake will not find the patches or
627 configurations even if you have them in your <filename>SRC_URI</filename>. 627 configurations even if you have them in your <filename>SRC_URI</filename>.
628 The <filename>FILESEXTRAPATHS</filename> variable enables the build process to 628 The <filename>FILESEXTRAPATHS</filename> variable enables the build process to
629 find those configuration files. 629 find those configuration files.
@@ -632,23 +632,23 @@
632 <note> 632 <note>
633 <para> 633 <para>
634 Other methods exist to accomplish grouping and defining configuration options. 634 Other methods exist to accomplish grouping and defining configuration options.
635 For example, if you are working with a local clone of the kernel repository, 635 For example, if you are working with a local clone of the kernel repository,
636 you could checkout the kernel's <filename>meta</filename> branch, make your changes, 636 you could checkout the kernel's <filename>meta</filename> branch, make your changes,
637 and then push the changes to the local bare clone of the kernel. 637 and then push the changes to the local bare clone of the kernel.
638 The result is that you directly add configuration options to the 638 The result is that you directly add configuration options to the
639 <filename>meta</filename> branch for your BSP. 639 <filename>meta</filename> branch for your BSP.
640 The configuration options will likely end up in that location anyway if the BSP gets 640 The configuration options will likely end up in that location anyway if the BSP gets
641 added to the Yocto Project. 641 added to the Yocto Project.
642 </para> 642 </para>
643 643
644 <para> 644 <para>
645 In general, however, the Yocto Project maintainers take care of moving the 645 In general, however, the Yocto Project maintainers take care of moving the
646 <filename>SRC_URI</filename>-specified 646 <filename>SRC_URI</filename>-specified
647 configuration options to the kernel's <filename>meta</filename> branch. 647 configuration options to the kernel's <filename>meta</filename> branch.
648 Not only is it easier for BSP developers to not have to worry about putting those 648 Not only is it easier for BSP developers to not have to worry about putting those
649 configurations in the branch, but having the maintainers do it allows them to apply 649 configurations in the branch, but having the maintainers do it allows them to apply
650 'global' knowledge about the kinds of common configuration options multiple BSPs in 650 'global' knowledge about the kinds of common configuration options multiple BSPs in
651 the tree are typically using. 651 the tree are typically using.
652 This allows for promotion of common configurations into common features. 652 This allows for promotion of common configurations into common features.
653 </para> 653 </para>
654 </note> 654 </note>
@@ -661,7 +661,7 @@
661 <para> 661 <para>
662 Certain requirements exist for a released BSP to be considered 662 Certain requirements exist for a released BSP to be considered
663 compliant with the Yocto Project. 663 compliant with the Yocto Project.
664 Additionally, a single recommendation also exists. 664 Additionally, a single recommendation also exists.
665 This section describes the requirements and recommendation for 665 This section describes the requirements and recommendation for
666 released BSPs. 666 released BSPs.
667 </para> 667 </para>
@@ -675,55 +675,55 @@
675 <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal" 675 <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal"
676 layer that can be added to the Yocto Project. 676 layer that can be added to the Yocto Project.
677 For guidelines on creating a layer that meets these base requirements, see the 677 For guidelines on creating a layer that meets these base requirements, see the
678 "<link linkend='bsp-layers'>BSP Layers</link>" and the 678 "<link linkend='bsp-layers'>BSP Layers</link>" and the
679 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding 679 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding
680 and Creating Layers"</ulink> in the Yocto Project Development Manual.</para></listitem> 680 and Creating Layers"</ulink> in the Yocto Project Development Manual.</para></listitem>
681 <listitem><para>The requirements in this section apply regardless of how you 681 <listitem><para>The requirements in this section apply regardless of how you
682 ultimately package a BSP. 682 ultimately package a BSP.
683 You should consult the packaging and distribution guidelines for your 683 You should consult the packaging and distribution guidelines for your
684 specific release process. 684 specific release process.
685 For an example of packaging and distribution requirements, see the 685 For an example of packaging and distribution requirements, see the
686 <ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third 686 <ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third
687 Party BSP Release Process</ulink> wiki page.</para></listitem> 687 Party BSP Release Process</ulink> wiki page.</para></listitem>
688 <listitem><para>The requirements for the BSP as it is made available to a developer 688 <listitem><para>The requirements for the BSP as it is made available to a developer
689 are completely independent of the released form of the BSP. 689 are completely independent of the released form of the BSP.
690 For example, the BSP metadata can be contained within a Git repository 690 For example, the BSP metadata can be contained within a Git repository
691 and could have a directory structure completely different from what appears 691 and could have a directory structure completely different from what appears
692 in the officially released BSP layer.</para></listitem> 692 in the officially released BSP layer.</para></listitem>
693 <listitem><para>It is not required that specific packages or package 693 <listitem><para>It is not required that specific packages or package
694 modifications exist in the BSP layer, beyond the requirements for general 694 modifications exist in the BSP layer, beyond the requirements for general
695 compliance with the Yocto Project. 695 compliance with the Yocto Project.
696 For example, no requirement exists dictating that a specific kernel or 696 For example, no requirement exists dictating that a specific kernel or
697 kernel version be used in a given BSP.</para></listitem> 697 kernel version be used in a given BSP.</para></listitem>
698 </itemizedlist> 698 </itemizedlist>
699 </para> 699 </para>
700 700
701 <para> 701 <para>
702 Following are the requirements for a released BSP that conforms to the 702 Following are the requirements for a released BSP that conforms to the
703 Yocto Project: 703 Yocto Project:
704 <itemizedlist> 704 <itemizedlist>
705 <listitem><para><emphasis>Layer Name:</emphasis> 705 <listitem><para><emphasis>Layer Name:</emphasis>
706 The BSP must have a layer name that follows the Yocto 706 The BSP must have a layer name that follows the Yocto
707 Project standards. 707 Project standards.
708 For information on BSP layer names, see the 708 For information on BSP layer names, see the
709 "<link linkend='bsp-layers'>BSP Layers</link>" section. 709 "<link linkend='bsp-layers'>BSP Layers</link>" section.
710 </para></listitem> 710 </para></listitem>
711 <listitem><para><emphasis>File System Layout:</emphasis> 711 <listitem><para><emphasis>File System Layout:</emphasis>
712 When possible, use the same directory names in your 712 When possible, use the same directory names in your
713 BSP layer as listed in the <filename>recipes.txt</filename> file. 713 BSP layer as listed in the <filename>recipes.txt</filename> file.
714 In particular, you should place recipes 714 In particular, you should place recipes
715 (<filename>.bb</filename> files) and recipe 715 (<filename>.bb</filename> files) and recipe
716 modifications (<filename>.bbappend</filename> files) into 716 modifications (<filename>.bbappend</filename> files) into
717 <filename>recipes-*</filename> subdirectories by functional area 717 <filename>recipes-*</filename> subdirectories by functional area
718 as outlined in <filename>recipes.txt</filename>. 718 as outlined in <filename>recipes.txt</filename>.
719 If you cannot find a category in <filename>recipes.txt</filename> 719 If you cannot find a category in <filename>recipes.txt</filename>
720 to fit a particular recipe, you can make up your own 720 to fit a particular recipe, you can make up your own
721 <filename>recipe-*</filename> subdirectory. 721 <filename>recipe-*</filename> subdirectory.
722 You can find <filename>recipes.txt</filename> in the 722 You can find <filename>recipes.txt</filename> in the
723 <filename>meta</filename> directory of the 723 <filename>meta</filename> directory of the
724 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, 724 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
725 or in the OpenEmbedded Core Layer 725 or in the OpenEmbedded Core Layer
726 (<filename>openembedded-core</filename>) found at 726 (<filename>openembedded-core</filename>) found at
727 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>. 727 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
728 </para> 728 </para>
729 <para>Within any particular <filename>recipes-*</filename> category, the layout 729 <para>Within any particular <filename>recipes-*</filename> category, the layout
@@ -733,68 +733,68 @@
733 In other words, make sure you place related files in appropriately 733 In other words, make sure you place related files in appropriately
734 related <filename>recipes-*</filename> subdirectories specific to the 734 related <filename>recipes-*</filename> subdirectories specific to the
735 recipe's function, or within a subdirectory containing a set of closely-related 735 recipe's function, or within a subdirectory containing a set of closely-related
736 recipes. 736 recipes.
737 The recipes themselves should follow the general guidelines 737 The recipes themselves should follow the general guidelines
738 for recipes used in the Yocto Project found in the 738 for recipes used in the Yocto Project found in the
739 <ulink url='https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide'>Yocto 739 <ulink url='https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide'>Yocto
740 Recipe and Patch Style Guide</ulink>.</para></listitem> 740 Recipe and Patch Style Guide</ulink>.</para></listitem>
741 <listitem><para><emphasis>License File:</emphasis> 741 <listitem><para><emphasis>License File:</emphasis>
742 You must include a license file in the 742 You must include a license file in the
743 <filename>meta-&lt;bsp_name&gt;</filename> directory. 743 <filename>meta-&lt;bsp_name&gt;</filename> directory.
744 This license covers the BSP metadata as a whole. 744 This license covers the BSP metadata as a whole.
745 You must specify which license to use since there is no 745 You must specify which license to use since there is no
746 default license if one is not specified. 746 default license if one is not specified.
747 See the 747 See the
748 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/COPYING.MIT'><filename>COPYING.MIT</filename></ulink> 748 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
749 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer 749 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
750 as an example.</para></listitem> 750 as an example.</para></listitem>
751 <listitem><para><emphasis>README File:</emphasis> 751 <listitem><para><emphasis>README File:</emphasis>
752 You must include a <filename>README</filename> file in the 752 You must include a <filename>README</filename> file in the
753 <filename>meta-&lt;bsp_name&gt;</filename> directory. 753 <filename>meta-&lt;bsp_name&gt;</filename> directory.
754 See the 754 See the
755 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README'><filename>README</filename></ulink> 755 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README'><filename>README</filename></ulink>
756 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer 756 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
757 as an example.</para> 757 as an example.</para>
758 <para>At a minimum, the <filename>README</filename> file should 758 <para>At a minimum, the <filename>README</filename> file should
759 contain the following: 759 contain the following:
760 <itemizedlist> 760 <itemizedlist>
761 <listitem><para>A brief description about the hardware the BSP 761 <listitem><para>A brief description about the hardware the BSP
762 targets.</para></listitem> 762 targets.</para></listitem>
763 <listitem><para>A list of all the dependencies 763 <listitem><para>A list of all the dependencies
764 on which a BSP layer depends. 764 on which a BSP layer depends.
765 These dependencies are typically a list of required layers needed 765 These dependencies are typically a list of required layers needed
766 to build the BSP. 766 to build the BSP.
767 However, the dependencies should also contain information regarding 767 However, the dependencies should also contain information regarding
768 any other dependencies the BSP might have.</para></listitem> 768 any other dependencies the BSP might have.</para></listitem>
769 <listitem><para>Any required special licensing information. 769 <listitem><para>Any required special licensing information.
770 For example, this information includes information on 770 For example, this information includes information on
771 special variables needed to satisfy a EULA, 771 special variables needed to satisfy a EULA,
772 or instructions on information needed to build or distribute 772 or instructions on information needed to build or distribute
773 binaries built from the BSP metadata.</para></listitem> 773 binaries built from the BSP metadata.</para></listitem>
774 <listitem><para>The name and contact information for the 774 <listitem><para>The name and contact information for the
775 BSP layer maintainer. 775 BSP layer maintainer.
776 This is the person to whom patches and questions should 776 This is the person to whom patches and questions should
777 be sent.</para></listitem> 777 be sent.</para></listitem>
778 <listitem><para>Instructions on how to build the BSP using the BSP 778 <listitem><para>Instructions on how to build the BSP using the BSP
779 layer.</para></listitem> 779 layer.</para></listitem>
780 <listitem><para>Instructions on how to boot the BSP build from 780 <listitem><para>Instructions on how to boot the BSP build from
781 the BSP layer.</para></listitem> 781 the BSP layer.</para></listitem>
782 <listitem><para>Instructions on how to boot the binary images 782 <listitem><para>Instructions on how to boot the binary images
783 contained in the <filename>/binary</filename> directory, 783 contained in the <filename>/binary</filename> directory,
784 if present.</para></listitem> 784 if present.</para></listitem>
785 <listitem><para>Information on any known bugs or issues that users 785 <listitem><para>Information on any known bugs or issues that users
786 should know about when either building or booting the BSP 786 should know about when either building or booting the BSP
787 binaries.</para></listitem> 787 binaries.</para></listitem>
788 </itemizedlist></para></listitem> 788 </itemizedlist></para></listitem>
789 <listitem><para><emphasis>README.sources File:</emphasis> 789 <listitem><para><emphasis>README.sources File:</emphasis>
790 You must include a <filename>README.sources</filename> in the 790 You must include a <filename>README.sources</filename> in the
791 <filename>meta-&lt;bsp_name&gt;</filename> directory. 791 <filename>meta-&lt;bsp_name&gt;</filename> directory.
792 This file specifies exactly where you can find the sources used to 792 This file specifies exactly where you can find the sources used to
793 generate the binary images contained in the 793 generate the binary images contained in the
794 <filename>/binary</filename> directory, if present. 794 <filename>/binary</filename> directory, if present.
795 See the 795 See the
796 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README.sources'><filename>README.sources</filename></ulink> 796 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README.sources'><filename>README.sources</filename></ulink>
797 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer 797 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
798 as an example.</para></listitem> 798 as an example.</para></listitem>
799 <listitem><para><emphasis>Layer Configuration File:</emphasis> 799 <listitem><para><emphasis>Layer Configuration File:</emphasis>
800 You must include a <filename>conf/layer.conf</filename> in the 800 You must include a <filename>conf/layer.conf</filename> in the
@@ -806,19 +806,19 @@
806 in the <filename>meta-&lt;bsp_name&gt;</filename> directory. 806 in the <filename>meta-&lt;bsp_name&gt;</filename> directory.
807 This configuration file defines a machine target that can be built 807 This configuration file defines a machine target that can be built
808 using the BSP layer. 808 using the BSP layer.
809 Multiple machine configuration files define variations of machine 809 Multiple machine configuration files define variations of machine
810 configurations that are supported by the BSP. 810 configurations that are supported by the BSP.
811 If a BSP supports multiple machine variations, you need to 811 If a BSP supports multiple machine variations, you need to
812 adequately describe each variation in the BSP 812 adequately describe each variation in the BSP
813 <filename>README</filename> file. 813 <filename>README</filename> file.
814 Do not use multiple machine configuration files to describe disparate 814 Do not use multiple machine configuration files to describe disparate
815 hardware. 815 hardware.
816 If you do have very different targets, you should create separate 816 If you do have very different targets, you should create separate
817 BSP layers for each target. 817 BSP layers for each target.
818 <note>It is completely possible for a developer to structure the 818 <note>It is completely possible for a developer to structure the
819 working repository as a conglomeration of unrelated BSP 819 working repository as a conglomeration of unrelated BSP
820 files, and to possibly generate specifically targeted 'release' BSPs 820 files, and to possibly generate specifically targeted 'release' BSPs
821 from that directory using scripts or some other mechanism. 821 from that directory using scripts or some other mechanism.
822 Such considerations are outside the scope of this document.</note> 822 Such considerations are outside the scope of this document.</note>
823 </para></listitem> 823 </para></listitem>
824 </itemizedlist> 824 </itemizedlist>
@@ -829,26 +829,26 @@
829 <title>Released BSP Recommendations</title> 829 <title>Released BSP Recommendations</title>
830 830
831 <para> 831 <para>
832 Following are recommendations for a released BSP that conforms to the 832 Following are recommendations for a released BSP that conforms to the
833 Yocto Project: 833 Yocto Project:
834 <itemizedlist> 834 <itemizedlist>
835 <listitem><para><emphasis>Bootable Images:</emphasis> 835 <listitem><para><emphasis>Bootable Images:</emphasis>
836 BSP releases 836 BSP releases
837 can contain one or more bootable images. 837 can contain one or more bootable images.
838 Including bootable images allows users to easily try out the BSP 838 Including bootable images allows users to easily try out the BSP
839 on their own hardware.</para> 839 on their own hardware.</para>
840 <para>In some cases, it might not be convenient to include a 840 <para>In some cases, it might not be convenient to include a
841 bootable image. 841 bootable image.
842 In this case, you might want to make two versions of the 842 In this case, you might want to make two versions of the
843 BSP available: one that contains binary images, and one 843 BSP available: one that contains binary images, and one
844 that does not. 844 that does not.
845 The version that does not contain bootable images avoids 845 The version that does not contain bootable images avoids
846 unnecessary download times for users not interested in the images. 846 unnecessary download times for users not interested in the images.
847 </para> 847 </para>
848 <para>If you need to distribute a BSP and include bootable images or build kernel and 848 <para>If you need to distribute a BSP and include bootable images or build kernel and
849 filesystems meant to allow users to boot the BSP for evaluation 849 filesystems meant to allow users to boot the BSP for evaluation
850 purposes, you should put the images and artifacts within a 850 purposes, you should put the images and artifacts within a
851 <filename>binary/</filename> subdirectory located in the 851 <filename>binary/</filename> subdirectory located in the
852 <filename>meta-&lt;bsp_name&gt;</filename> directory. 852 <filename>meta-&lt;bsp_name&gt;</filename> directory.
853 <note>If you do include a bootable image as part of the BSP and the image 853 <note>If you do include a bootable image as part of the BSP and the image
854 was built by software covered by the GPL or other open source licenses, 854 was built by software covered by the GPL or other open source licenses,
@@ -856,10 +856,10 @@
856 and meet all licensing requirements, which could include distribution 856 and meet all licensing requirements, which could include distribution
857 of source files.</note></para></listitem> 857 of source files.</note></para></listitem>
858 <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis> 858 <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
859 Kernel recipes in the BSP should be based on a Yocto Linux kernel. 859 Kernel recipes in the BSP should be based on a Yocto Linux kernel.
860 Basing your recipes on these kernels reduces the costs for maintaining 860 Basing your recipes on these kernels reduces the costs for maintaining
861 the BSP and increases its scalability. 861 the BSP and increases its scalability.
862 See the <filename>Yocto Linux Kernel</filename> category in the 862 See the <filename>Yocto Linux Kernel</filename> category in the
863 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink> 863 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
864 for these kernels.</para></listitem> 864 for these kernels.</para></listitem>
865 </itemizedlist> 865 </itemizedlist>
@@ -883,18 +883,18 @@
883 </para> 883 </para>
884 884
885 <para> 885 <para>
886 To better understand this, consider an example that customizes a recipe by adding 886 To better understand this, consider an example that customizes a recipe by adding
887 a BSP-specific configuration file named <filename>interfaces</filename> to the 887 a BSP-specific configuration file named <filename>interfaces</filename> to the
888 <filename>netbase_5.0.bb</filename> recipe for machine "xyz". 888 <filename>netbase_5.0.bb</filename> recipe for machine "xyz".
889 Do the following: 889 Do the following:
890 <orderedlist> 890 <orderedlist>
891 <listitem><para>Edit the <filename>netbase_4.47.bbappend</filename> file so that it 891 <listitem><para>Edit the <filename>netbase_4.47.bbappend</filename> file so that it
892 contains the following: 892 contains the following:
893 <literallayout class='monospaced'> 893 <literallayout class='monospaced'>
894 FILESEXTRAPATHS_prepend := "${THISDIR}/files:" 894 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
895 PRINC := "${@int(PRINC) + 2}" 895 PRINC := "${@int(PRINC) + 2}"
896 </literallayout></para></listitem> 896 </literallayout></para></listitem>
897 <listitem><para>Create and place the new <filename>interfaces</filename> 897 <listitem><para>Create and place the new <filename>interfaces</filename>
898 configuration file in the BSP's layer here: 898 configuration file in the BSP's layer here:
899 <literallayout class='monospaced'> 899 <literallayout class='monospaced'>
900 meta-xyz/recipes-core/netbase/files/xyz/interfaces 900 meta-xyz/recipes-core/netbase/files/xyz/interfaces
@@ -909,24 +909,24 @@
909 <para> 909 <para>
910 In some cases, a BSP contains separately licensed Intellectual Property (IP) 910 In some cases, a BSP contains separately licensed Intellectual Property (IP)
911 for a component or components. 911 for a component or components.
912 For these cases, you are required to accept the terms of a commercial or other 912 For these cases, you are required to accept the terms of a commercial or other
913 type of license that requires some kind of explicit End User License Agreement (EULA). 913 type of license that requires some kind of explicit End User License Agreement (EULA).
914 Once the license is accepted, the OpenEmbedded build system can then build and 914 Once the license is accepted, the OpenEmbedded build system can then build and
915 include the corresponding component in the final BSP image. 915 include the corresponding component in the final BSP image.
916 If the BSP is available as a pre-built image, you can download the image after 916 If the BSP is available as a pre-built image, you can download the image after
917 agreeing to the license or EULA. 917 agreeing to the license or EULA.
918 </para> 918 </para>
919 919
920 <para> 920 <para>
921 You could find that some separately licensed components that are essential 921 You could find that some separately licensed components that are essential
922 for normal operation of the system might not have an unencumbered (or free) 922 for normal operation of the system might not have an unencumbered (or free)
923 substitute. 923 substitute.
924 Without these essential components, the system would be non-functional. 924 Without these essential components, the system would be non-functional.
925 Then again, you might find that other licensed components that are simply 925 Then again, you might find that other licensed components that are simply
926 'good-to-have' or purely elective do have an unencumbered, free replacement 926 'good-to-have' or purely elective do have an unencumbered, free replacement
927 component that you can use rather than agreeing to the separately licensed component. 927 component that you can use rather than agreeing to the separately licensed component.
928 Even for components essential to the system, you might find an unencumbered component 928 Even for components essential to the system, you might find an unencumbered component
929 that is not identical but will work as a less-capable version of the 929 that is not identical but will work as a less-capable version of the
930 licensed version in the BSP recipe. 930 licensed version in the BSP recipe.
931 </para> 931 </para>
932 932
@@ -935,14 +935,14 @@
935 maintain the system's functionality, the Yocto Project website's 935 maintain the system's functionality, the Yocto Project website's
936 <ulink url='&YOCTO_HOME_URL;/download/all?keys=&amp;download_type=1&amp;download_version='>BSP 936 <ulink url='&YOCTO_HOME_URL;/download/all?keys=&amp;download_type=1&amp;download_version='>BSP
937 Download Page</ulink> makes available de-featured BSPs 937 Download Page</ulink> makes available de-featured BSPs
938 that are completely free of any IP encumbrances. 938 that are completely free of any IP encumbrances.
939 For these cases, you can use the substitution directly and 939 For these cases, you can use the substitution directly and
940 without any further licensing requirements. 940 without any further licensing requirements.
941 If present, these fully de-featured BSPs are named appropriately 941 If present, these fully de-featured BSPs are named appropriately
942 different as compared to the names of the respective 942 different as compared to the names of the respective
943 encumbered BSPs. 943 encumbered BSPs.
944 If available, these substitutions are your 944 If available, these substitutions are your
945 simplest and most preferred options. 945 simplest and most preferred options.
946 Use of these substitutions of course assumes the resulting functionality meets 946 Use of these substitutions of course assumes the resulting functionality meets
947 system requirements. 947 system requirements.
948 </para> 948 </para>
@@ -953,23 +953,23 @@
953 version. 953 version.
954 </para> 954 </para>
955 955
956 <para> 956 <para>
957 A couple different methods exist within the OpenEmbedded build system to 957 A couple different methods exist within the OpenEmbedded build system to
958 satisfy the licensing requirements for an encumbered BSP. 958 satisfy the licensing requirements for an encumbered BSP.
959 The following list describes them in order of preference: 959 The following list describes them in order of preference:
960 <orderedlist> 960 <orderedlist>
961 <listitem><para><emphasis>Use the <filename>LICENSE_FLAGS</filename> variable 961 <listitem><para><emphasis>Use the <filename>LICENSE_FLAGS</filename> variable
962 to define the recipes that have commercial or other types of 962 to define the recipes that have commercial or other types of
963 specially-licensed packages:</emphasis> 963 specially-licensed packages:</emphasis>
964 For each of those recipes, you can 964 For each of those recipes, you can
965 specify a matching license string in a 965 specify a matching license string in a
966 <filename>local.conf</filename> variable named 966 <filename>local.conf</filename> variable named
967 <filename>LICENSE_FLAGS_WHITELIST</filename>. 967 <filename>LICENSE_FLAGS_WHITELIST</filename>.
968 Specifying the matching license string signifies that you agree to the license. 968 Specifying the matching license string signifies that you agree to the license.
969 Thus, the build system can build the corresponding recipe and include 969 Thus, the build system can build the corresponding recipe and include
970 the component in the image. 970 the component in the image.
971 See the 971 See the
972 "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling 972 "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
973 Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference 973 Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
974 Manual for details on how to use these variables.</para> 974 Manual for details on how to use these variables.</para>
975 <para>If you build as you normally would, without 975 <para>If you build as you normally would, without
@@ -977,15 +977,15 @@
977 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and 977 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
978 provides you with the list of recipes that you have 978 provides you with the list of recipes that you have
979 tried to include in the image that need entries in 979 tried to include in the image that need entries in
980 the <filename>LICENSE_FLAGS_WHITELIST</filename>. 980 the <filename>LICENSE_FLAGS_WHITELIST</filename>.
981 Once you enter the appropriate license flags into the whitelist, 981 Once you enter the appropriate license flags into the whitelist,
982 restart the build to continue where it left off. 982 restart the build to continue where it left off.
983 During the build, the prompt will not appear again 983 During the build, the prompt will not appear again
984 since you have satisfied the requirement.</para> 984 since you have satisfied the requirement.</para>
985 <para>Once the appropriate license flags are on the white list 985 <para>Once the appropriate license flags are on the white list
986 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you 986 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
987 can build the encumbered image with no change at all 987 can build the encumbered image with no change at all
988 to the normal build process.</para></listitem> 988 to the normal build process.</para></listitem>
989 <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis> 989 <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis>
990 You can get this type of BSP by visiting the Yocto Project website's 990 You can get this type of BSP by visiting the Yocto Project website's
991 <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink> 991 <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink>
@@ -993,11 +993,11 @@
993 You can download BSP tarballs that contain proprietary components 993 You can download BSP tarballs that contain proprietary components
994 after agreeing to the licensing 994 after agreeing to the licensing
995 requirements of each of the individually encumbered 995 requirements of each of the individually encumbered
996 packages as part of the download process. 996 packages as part of the download process.
997 Obtaining the BSP this way allows you to access an encumbered 997 Obtaining the BSP this way allows you to access an encumbered
998 image immediately after agreeing to the 998 image immediately after agreeing to the
999 click-through license agreements presented by the 999 click-through license agreements presented by the
1000 website. 1000 website.
1001 Note that if you want to build the image 1001 Note that if you want to build the image
1002 yourself using the recipes contained within the BSP 1002 yourself using the recipes contained within the BSP
1003 tarball, you will still need to create an 1003 tarball, you will still need to create an
@@ -1010,11 +1010,11 @@
1010 Pre-compiled images are bundled with 1010 Pre-compiled images are bundled with
1011 a time-limited kernel that runs for a 1011 a time-limited kernel that runs for a
1012 predetermined amount of time (10 days) before it forces 1012 predetermined amount of time (10 days) before it forces
1013 the system to reboot. 1013 the system to reboot.
1014 This limitation is meant to discourage direct redistribution 1014 This limitation is meant to discourage direct redistribution
1015 of the image. 1015 of the image.
1016 You must eventually rebuild the image if you want to remove this restriction. 1016 You must eventually rebuild the image if you want to remove this restriction.
1017 </note> 1017 </note>
1018 </section> 1018 </section>
1019 1019
1020 <section id='using-the-yocto-projects-bsp-tools'> 1020 <section id='using-the-yocto-projects-bsp-tools'>
@@ -1022,16 +1022,16 @@
1022 1022
1023 <para> 1023 <para>
1024 The Yocto Project includes a couple of tools that enable 1024 The Yocto Project includes a couple of tools that enable
1025 you to create a <link linkend='bsp-layers'>BSP layer</link> 1025 you to create a <link linkend='bsp-layers'>BSP layer</link>
1026 from scratch and do basic configuration and maintenance 1026 from scratch and do basic configuration and maintenance
1027 of the kernel without ever looking at a metadata file. 1027 of the kernel without ever looking at a metadata file.
1028 These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>, 1028 These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
1029 respectively. 1029 respectively.
1030 </para> 1030 </para>
1031 1031
1032 <para> 1032 <para>
1033 The following sections describe the common location and help features as well 1033 The following sections describe the common location and help features as well
1034 as provide details for the 1034 as provide details for the
1035 <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools. 1035 <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools.
1036 </para> 1036 </para>
1037 1037
@@ -1039,7 +1039,7 @@
1039 <title>Common Features</title> 1039 <title>Common Features</title>
1040 1040
1041 <para> 1041 <para>
1042 Designed to have a command interface somewhat like 1042 Designed to have a command interface somewhat like
1043 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>, each 1043 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>, each
1044 tool is structured as a set of sub-commands under a 1044 tool is structured as a set of sub-commands under a
1045 top-level command. 1045 top-level command.
@@ -1050,9 +1050,9 @@
1050 </para> 1050 </para>
1051 1051
1052 <para> 1052 <para>
1053 Both tools reside in the <filename>scripts/</filename> subdirectory 1053 Both tools reside in the <filename>scripts/</filename> subdirectory
1054 of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 1054 of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1055 Consequently, to use the scripts, you must <filename>source</filename> the 1055 Consequently, to use the scripts, you must <filename>source</filename> the
1056 environment just as you would when invoking a build: 1056 environment just as you would when invoking a build:
1057 <literallayout class='monospaced'> 1057 <literallayout class='monospaced'>
1058 $ source oe-init-build-env [build_dir] 1058 $ source oe-init-build-env [build_dir]
@@ -1067,7 +1067,7 @@
1067 switch: 1067 switch:
1068 <literallayout class='monospaced'> 1068 <literallayout class='monospaced'>
1069 $ yocto-bsp help 1069 $ yocto-bsp help
1070 Usage: 1070 Usage:
1071 1071
1072 Create a customized Yocto BSP layer. 1072 Create a customized Yocto BSP layer.
1073 1073
@@ -1088,12 +1088,12 @@
1088 </para> 1088 </para>
1089 1089
1090 <para> 1090 <para>
1091 Similarly, entering just the name of a sub-command shows the detailed usage 1091 Similarly, entering just the name of a sub-command shows the detailed usage
1092 for that sub-command: 1092 for that sub-command:
1093 <literallayout class='monospaced'> 1093 <literallayout class='monospaced'>
1094 $ yocto-bsp create 1094 $ yocto-bsp create
1095 1095
1096 Usage: 1096 Usage:
1097 1097
1098 Create a new Yocto BSP 1098 Create a new Yocto BSP
1099 1099
@@ -1111,7 +1111,7 @@
1111 </para> 1111 </para>
1112 1112
1113 <para> 1113 <para>
1114 For any sub-command, you can also use the word 'help' just before the 1114 For any sub-command, you can also use the word 'help' just before the
1115 sub-command to get more extensive documentation: 1115 sub-command to get more extensive documentation:
1116 <literallayout class='monospaced'> 1116 <literallayout class='monospaced'>
1117 $ yocto-bsp help create 1117 $ yocto-bsp help create
@@ -1141,11 +1141,11 @@
1141 </para> 1141 </para>
1142 1142
1143 <para> 1143 <para>
1144 Now that you know where these two commands reside and how to access information 1144 Now that you know where these two commands reside and how to access information
1145 on them, you should find it relatively straightforward to discover the commands 1145 on them, you should find it relatively straightforward to discover the commands
1146 necessary to create a BSP and perform basic kernel maintenance on that BSP using 1146 necessary to create a BSP and perform basic kernel maintenance on that BSP using
1147 the tools. 1147 the tools.
1148 The next sections provide a concrete starting point to expand on a few points that 1148 The next sections provide a concrete starting point to expand on a few points that
1149 might not be immediately obvious or that could use further explanation. 1149 might not be immediately obvious or that could use further explanation.
1150 </para> 1150 </para>
1151 </section> 1151 </section>
@@ -1155,10 +1155,10 @@
1155 <title>Creating a new BSP Layer Using the yocto-bsp Script</title> 1155 <title>Creating a new BSP Layer Using the yocto-bsp Script</title>
1156 1156
1157 <para> 1157 <para>
1158 The <filename>yocto-bsp</filename> script creates a new 1158 The <filename>yocto-bsp</filename> script creates a new
1159 <link linkend='bsp-layers'>BSP layer</link> for any architecture supported 1159 <link linkend='bsp-layers'>BSP layer</link> for any architecture supported
1160 by the Yocto Project, as well as QEMU versions of the same. 1160 by the Yocto Project, as well as QEMU versions of the same.
1161 The default mode of the script's operation is to prompt you for information needed 1161 The default mode of the script's operation is to prompt you for information needed
1162 to generate the BSP layer. 1162 to generate the BSP layer.
1163 For the current set of BSPs, the script prompts you for various important 1163 For the current set of BSPs, the script prompts you for various important
1164 parameters such as: 1164 parameters such as:
@@ -1174,11 +1174,11 @@
1174 </para> 1174 </para>
1175 1175
1176 <para> 1176 <para>
1177 You use the <filename>yocto-bsp create</filename> sub-command to create 1177 You use the <filename>yocto-bsp create</filename> sub-command to create
1178 a new BSP layer. 1178 a new BSP layer.
1179 This command requires you to specify a particular kernel architecture 1179 This command requires you to specify a particular kernel architecture
1180 (<filename>karch</filename>) on which to base the BSP. 1180 (<filename>karch</filename>) on which to base the BSP.
1181 Assuming you have sourced the environment, you can use the 1181 Assuming you have sourced the environment, you can use the
1182 <filename>yocto-bsp list karch</filename> sub-command to list the 1182 <filename>yocto-bsp list karch</filename> sub-command to list the
1183 architectures available for BSP creation as follows: 1183 architectures available for BSP creation as follows:
1184 <literallayout class='monospaced'> 1184 <literallayout class='monospaced'>
@@ -1194,7 +1194,7 @@
1194 </para> 1194 </para>
1195 1195
1196 <para> 1196 <para>
1197 The remainder of this section presents an example that uses 1197 The remainder of this section presents an example that uses
1198 <filename>myarm</filename> as the machine name and <filename>qemu</filename> 1198 <filename>myarm</filename> as the machine name and <filename>qemu</filename>
1199 as the machine architecture. 1199 as the machine architecture.
1200 Of the available architectures, <filename>qemu</filename> is the only architecture 1200 Of the available architectures, <filename>qemu</filename> is the only architecture
@@ -1206,14 +1206,14 @@
1206 </para> 1206 </para>
1207 1207
1208 <para> 1208 <para>
1209 As the <filename>yocto-bsp create</filename> command runs, default values for 1209 As the <filename>yocto-bsp create</filename> command runs, default values for
1210 the prompts appear in brackets. 1210 the prompts appear in brackets.
1211 Pressing enter without supplying anything on the command line or pressing enter 1211 Pressing enter without supplying anything on the command line or pressing enter
1212 and providing an invalid response causes the script to accept the default value. 1212 and providing an invalid response causes the script to accept the default value.
1213 Once the script completes, the new <filename>meta-myarm</filename> BSP layer 1213 Once the script completes, the new <filename>meta-myarm</filename> BSP layer
1214 is created in the current working directory. 1214 is created in the current working directory.
1215 This example assumes you have source the &OE_INIT_FILE; and are currently 1215 This example assumes you have source the &OE_INIT_FILE; and are currently
1216 in the top-level folder of the 1216 in the top-level folder of the
1217 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 1217 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1218 </para> 1218 </para>
1219 1219
@@ -1254,47 +1254,47 @@
1254 </literallayout> 1254 </literallayout>
1255 Let's take a closer look at the example now: 1255 Let's take a closer look at the example now:
1256 <orderedlist> 1256 <orderedlist>
1257 <listitem><para>For the <filename>qemu</filename> architecture, 1257 <listitem><para>For the <filename>qemu</filename> architecture,
1258 the script first prompts you for which emulated architecture to use. 1258 the script first prompts you for which emulated architecture to use.
1259 In the example, we use the <filename>arm</filename> architecture. 1259 In the example, we use the <filename>arm</filename> architecture.
1260 </para></listitem> 1260 </para></listitem>
1261 <listitem><para>The script then prompts you for the kernel. 1261 <listitem><para>The script then prompts you for the kernel.
1262 The default 3.4 kernel is acceptable. 1262 The default 3.4 kernel is acceptable.
1263 So, the example accepts the default. 1263 So, the example accepts the default.
1264 If you enter 'n', the script prompts you to further enter the kernel 1264 If you enter 'n', the script prompts you to further enter the kernel
1265 you do want to use (e.g. 3.0, 3.2_preempt-rt, and so forth.).</para></listitem> 1265 you do want to use (e.g. 3.0, 3.2_preempt-rt, and so forth.).</para></listitem>
1266 <listitem><para>Next, the script asks whether you would like to have a new 1266 <listitem><para>Next, the script asks whether you would like to have a new
1267 branch created especially for your BSP in the local 1267 branch created especially for your BSP in the local
1268 <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink> 1268 <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink>
1269 Git repository . 1269 Git repository .
1270 If not, then the script re-uses an existing branch.</para> 1270 If not, then the script re-uses an existing branch.</para>
1271 <para>In this example, the default (or 'yes') is accepted. 1271 <para>In this example, the default (or 'yes') is accepted.
1272 Thus, a new branch is created for the BSP rather than using a common, shared 1272 Thus, a new branch is created for the BSP rather than using a common, shared
1273 branch. 1273 branch.
1274 The new branch is the branch committed to for any patches you might later add. 1274 The new branch is the branch committed to for any patches you might later add.
1275 The reason a new branch is the default is that typically 1275 The reason a new branch is the default is that typically
1276 new BSPs do require BSP-specific patches. 1276 new BSPs do require BSP-specific patches.
1277 The tool thus assumes that most of time a new branch is required. 1277 The tool thus assumes that most of time a new branch is required.
1278 </para></listitem> 1278 </para></listitem>
1279 <listitem><para>Regardless of which choice you make in the previous step, 1279 <listitem><para>Regardless of which choice you make in the previous step,
1280 you are now given the opportunity to select a particular machine branch on 1280 you are now given the opportunity to select a particular machine branch on
1281 which to base your new BSP-specific machine branch 1281 which to base your new BSP-specific machine branch
1282 (or to re-use if you had elected to not create a new branch). 1282 (or to re-use if you had elected to not create a new branch).
1283 Because this example is generating an <filename>arm</filename> BSP, the example 1283 Because this example is generating an <filename>arm</filename> BSP, the example
1284 uses <filename>#1</filename> at the prompt, which selects the arm-versatile branch. 1284 uses <filename>#1</filename> at the prompt, which selects the arm-versatile branch.
1285 </para></listitem> 1285 </para></listitem>
1286 <listitem><para>The remainder of the prompts are routine. 1286 <listitem><para>The remainder of the prompts are routine.
1287 Defaults are accepted for each.</para></listitem> 1287 Defaults are accepted for each.</para></listitem>
1288 <listitem><para>By default, the script creates the new BSP Layer in the 1288 <listitem><para>By default, the script creates the new BSP Layer in the
1289 current working directory of the 1289 current working directory of the
1290 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, 1290 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1291 which is <filename>poky</filename> in this case. 1291 which is <filename>poky</filename> in this case.
1292 </para></listitem> 1292 </para></listitem>
1293 </orderedlist> 1293 </orderedlist>
1294 </para> 1294 </para>
1295 1295
1296 <para> 1296 <para>
1297 Once the BSP Layer is created, you must add it to your 1297 Once the BSP Layer is created, you must add it to your
1298 <filename>bblayers.conf</filename> file. 1298 <filename>bblayers.conf</filename> file.
1299 Here is an example: 1299 Here is an example:
1300 <literallayout class='monospaced'> 1300 <literallayout class='monospaced'>
@@ -1309,11 +1309,11 @@
1309 /usr/local/src/yocto/meta \ 1309 /usr/local/src/yocto/meta \
1310 /usr/local/src/yocto/meta-yocto \ 1310 /usr/local/src/yocto/meta-yocto \
1311 " 1311 "
1312 </literallayout> 1312 </literallayout>
1313 Adding the layer to this file allows the build system to build the BSP and 1313 Adding the layer to this file allows the build system to build the BSP and
1314 the <filename>yocto-kernel</filename> tool to be able to find the layer and 1314 the <filename>yocto-kernel</filename> tool to be able to find the layer and
1315 other metadata it needs on which to operate. 1315 other metadata it needs on which to operate.
1316 </para> 1316 </para>
1317 </section> 1317 </section>
1318 1318
1319 <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'> 1319 <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
@@ -1331,14 +1331,14 @@
1331 1331
1332 <para> 1332 <para>
1333 The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches 1333 The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
1334 and kernel config settings to a BSP's kernel 1334 and kernel config settings to a BSP's kernel
1335 <filename>.bbappend</filename> file. 1335 <filename>.bbappend</filename> file.
1336 All you need to do is use the appropriate sub-command. 1336 All you need to do is use the appropriate sub-command.
1337 Recall that the easiest way to see exactly what sub-commands are available 1337 Recall that the easiest way to see exactly what sub-commands are available
1338 is to use the <filename>yocto-kernel</filename> built-in help as follows: 1338 is to use the <filename>yocto-kernel</filename> built-in help as follows:
1339 <literallayout class='monospaced'> 1339 <literallayout class='monospaced'>
1340 $ yocto-kernel 1340 $ yocto-kernel
1341 Usage: 1341 Usage:
1342 1342
1343 Modify and list Yocto BSP kernel config items and patches. 1343 Modify and list Yocto BSP kernel config items and patches.
1344 1344
@@ -1364,8 +1364,8 @@
1364 </para> 1364 </para>
1365 1365
1366 <para> 1366 <para>
1367 The <filename>yocto-kernel patch add</filename> sub-command allows you to add a 1367 The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
1368 patch to a BSP. 1368 patch to a BSP.
1369 The following example adds two patches to the <filename>myarm</filename> BSP: 1369 The following example adds two patches to the <filename>myarm</filename> BSP:
1370 <literallayout class='monospaced'> 1370 <literallayout class='monospaced'>
1371 $ yocto-kernel patch add myarm ~/test.patch 1371 $ yocto-kernel patch add myarm ~/test.patch
@@ -1381,7 +1381,7 @@
1381 </para> 1381 </para>
1382 1382
1383 <para> 1383 <para>
1384 You can verify patches have been added by using the 1384 You can verify patches have been added by using the
1385 <filename>yocto-kernel patch list</filename> sub-command. 1385 <filename>yocto-kernel patch list</filename> sub-command.
1386 Here is an example: 1386 Here is an example:
1387 <literallayout class='monospaced'> 1387 <literallayout class='monospaced'>
@@ -1420,7 +1420,7 @@
1420 <para> 1420 <para>
1421 In a completely similar way, you can use the <filename>yocto-kernel config add</filename> 1421 In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
1422 sub-command to add one or more kernel config item settings to a BSP. 1422 sub-command to add one or more kernel config item settings to a BSP.
1423 The following commands add a couple of config items to the 1423 The following commands add a couple of config items to the
1424 <filename>myarm</filename> BSP: 1424 <filename>myarm</filename> BSP:
1425 <literallayout class='monospaced'> 1425 <literallayout class='monospaced'>
1426 $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y 1426 $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
@@ -1448,7 +1448,7 @@
1448 </para> 1448 </para>
1449 1449
1450 <para> 1450 <para>
1451 Finally, you can remove one or more config items using the 1451 Finally, you can remove one or more config items using the
1452 <filename>yocto-kernel config rm</filename> sub-command in a manner 1452 <filename>yocto-kernel config rm</filename> sub-command in a manner
1453 completely analogous to <filename>yocto-kernel patch rm</filename>. 1453 completely analogous to <filename>yocto-kernel patch rm</filename>.
1454 </para> 1454 </para>