summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/bsp-guide/bsp.xml1201
1 files changed, 978 insertions, 223 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 631735ea22..d467ceb8fa 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -1,5 +1,6 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
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 4
4<chapter id='bsp'> 5<chapter id='bsp'>
5 6
@@ -18,77 +19,36 @@
18 </para> 19 </para>
19 20
20 <para> 21 <para>
21 This section (or document if you are reading the BSP Developer's Guide) defines 22 This chapter (or document if you are reading the BSP Developer's Guide)
22 a structure for these components 23 talks about BSP Layers, defines a structure for components
23 so that BSPs follow a commonly understood layout. 24 so that BSPs follow a commonly understood layout, discusses how to customize
24 Providing a common form allows end-users to understand and become familiar 25 a recipe for a BSP, addresses BSP licensing, and provides information that
25 with the layout. 26 shows you how to create and manage a
26 A common form also encourages standardization 27 <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project
27 of software support of hardware. 28 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
28 </para> 29 </para>
29 30
30 <note> 31 <section id='bsp-layers'>
31 The information here does not provide an example of how to create a BSP. 32 <title>BSP Layers</title>
32 For examples on how to create a BSP, see the
33 <ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html#dev-manual-bsp-appendix'>
34 BSP Development Example</ulink> in
35 <ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'>
36 The Yocto Project Development Manual</ulink>.
37 You can also see the
38 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
39 wiki page</ulink>.
40 </note>
41
42 <para>
43 The proposed format does have elements that are specific to the Yocto Project and
44 OpenEmbedded build systems.
45 It is intended that this information can be
46 used by other systems besides Yocto Project and OpenEmbedded and that it will be simple
47 to extract information and convert it to other formats if required.
48 Yocto Project, through its standard layers mechanism, can directly accept the format
49 described as a layer.
50 The BSP captures all
51 the hardware-specific details in one place in a standard format, which is
52 useful for any person wishing to use the hardware platform regardless of
53 the build system they are using.
54 </para>
55
56 <para>
57 The BSP specification does not include a build system or other tools -
58 it is concerned with the hardware-specific components only.
59 At the end
60 distribution point you can ship the BSP combined with a build system
61 and other tools.
62 However, it is important to maintain the distinction that these
63 are separate components that happen to be combined in certain end products.
64 </para>
65
66 <section id="bsp-filelayout">
67 <title>Example Filesystem Layout</title>
68 33
69 <para> 34 <para>
70 The BSP consists of a file structure inside a base directory, which uses the following 35 The BSP consists of a file structure inside a base directory.
71 naming convention: 36 Collectively, you can think of the base directory and the file structure
37 as a BSP Layer.
38 BSP Layers use the following naming convention:
72 <literallayout class='monospaced'> 39 <literallayout class='monospaced'>
73 meta-&lt;bsp_name&gt; 40 meta-&lt;bsp_name&gt;
74 </literallayout> 41 </literallayout>
75 </para>
76
77 <para>
78 "bsp_name" is a placeholder for the machine or platform name. 42 "bsp_name" is a placeholder for the machine or platform name.
79 Here are some example base directory names:
80 <literallayout class='monospaced'>
81 meta-emenlow
82 meta-n450
83 meta-beagleboard
84 </literallayout>
85 </para> 43 </para>
86 44
87 <para> 45 <para>
88 The base directory (<filename>meta-&lt;bsp_name&gt;</filename>) is the root of the BSP layer. 46 The layer's base directory (<filename>meta-&lt;bsp_name&gt;</filename>) is the root
89 This root is what you add to the <filename>BBLAYERS</filename> 47 of the BSP Layer.
90 variable in the <filename>build/conf/bblayers.conf</filename> file found in the 48 This root is what you add to the
91 Yocto Project file's build directory. 49 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
50 variable in the <filename>conf/bblayers.conf</filename> file found in the
51 <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-build-directory'>Yocto Project Build Directory</ulink>.
92 Adding the root allows the Yocto Project build system to recognize the BSP 52 Adding the root allows the Yocto Project build system to recognize the BSP
93 definition and from it build an image. 53 definition and from it build an image.
94 Here is an example: 54 Here is an example:
@@ -99,15 +59,78 @@
99 /usr/local/src/yocto/meta-&lt;bsp_name&gt; \ 59 /usr/local/src/yocto/meta-&lt;bsp_name&gt; \
100 " 60 "
101 </literallayout> 61 </literallayout>
62 </para>
63
64 <para>
65 Some BSPs require additional layers on
66 top of the BSP's root layer in order to be functional.
67 For these cases, you also need to add those layers to the
68 <filename>BBLAYERS</filename> variable in order to build the BSP.
69 You must also specify in the "Dependencies" section of the BSP's
70 <filename>README</filename> file any requirements for additional
71 layers and, preferably, any
72 build instructions that might be contained elsewhere
73 in the <filename>README</filename> file.
74 </para>
75
76 <para>
77 Some layers function as a layer to hold other BSP layers.
78 An example of this type of layer is the <filename>meta-intel</filename> layer.
79 The <filename>meta-intel</filename> layer contains over 10 individual BSP layers.
80 </para>
81
82 <para>
102 For more detailed information on layers, see the 83 For more detailed information on layers, see the
103 "<ulink url='http://www.yoctoproject.org/docs/1.1.1/poky-ref-manual/poky-ref-manual.html#usingpoky-changes-layers'>BitBake Layers</ulink>" section of the Yocto Project Reference Manual. 84 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-changes-layers'>BitBake Layers</ulink>" section of the Yocto Project Reference Manual.
104 You can also see the detailed examples in the appendices of 85 You can also see the detailed examples in the appendices of
105 <ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'> 86 <ulink url='&YOCTO_DOCS_DEV_URL;'>The Yocto Project Development Manual</ulink>.
106 The Yocto Project Development Manual</ulink>. 87 </para>
88 </section>
89
90
91 <section id="bsp-filelayout">
92 <title>Example Filesystem Layout</title>
93
94 <para>
95 Providing a common form allows end-users to understand and become familiar
96 with the layout.
97 A common format also encourages standardization of software support of hardware.
98 </para>
99
100 <para>
101 The proposed form does have elements that are specific to the Yocto Project and
102 OpenEmbedded build systems.
103 It is intended that this information can be
104 used by other systems besides Yocto Project and OpenEmbedded and that it will be simple
105 to extract information and convert it to other formats if required.
106 Yocto Project, through its standard layers mechanism, can directly accept the format
107 described as a layer.
108 The BSP captures all
109 the hardware-specific details in one place in a standard format, which is
110 useful for any person wishing to use the hardware platform regardless of
111 the build system they are using.
112 </para>
113
114 <para>
115 The BSP specification does not include a build system or other tools -
116 it is concerned with the hardware-specific components only.
117 At the end-distribution point, you can ship the BSP combined with a build system
118 and other tools.
119 However, it is important to maintain the distinction that these
120 are separate components that happen to be combined in certain end products.
107 </para> 121 </para>
108 122
109 <para> 123 <para>
110 Below is the common form for the file structure inside a base directory. 124 Before looking at the common form for the file structure inside a BSP Layer,
125 you should be aware that some requirements do exist in order for a BSP to
126 be considered compliant with the Yocto Project.
127 For that list of requirements, see the
128 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
129 section.
130 </para>
131
132 <para>
133 Below is the common form for the file structure inside a BSP Layer.
111 While you can use this basic form for the standard, realize that the actual structures 134 While you can use this basic form for the standard, realize that the actual structures
112 for specific BSPs could differ. 135 for specific BSPs could differ.
113 136
@@ -115,10 +138,12 @@
115 meta-&lt;bsp_name&gt;/ 138 meta-&lt;bsp_name&gt;/
116 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt; 139 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
117 meta-&lt;bsp_name&gt;/README 140 meta-&lt;bsp_name&gt;/README
141 meta-&lt;bsp_name&gt;/README.sources
118 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt; 142 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
119 meta-&lt;bsp_name&gt;/conf/layer.conf 143 meta-&lt;bsp_name&gt;/conf/layer.conf
120 meta-&lt;bsp_name&gt;/conf/machine/*.conf 144 meta-&lt;bsp_name&gt;/conf/machine/*.conf
121 meta-&lt;bsp_name&gt;/recipes-bsp/* 145 meta-&lt;bsp_name&gt;/recipes-bsp/*
146 meta-&lt;bsp_name&gt;/recipes-core/*
122 meta-&lt;bsp_name&gt;/recipes-graphics/* 147 meta-&lt;bsp_name&gt;/recipes-graphics/*
123 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_&lt;kernel_rev&gt;.bbappend 148 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_&lt;kernel_rev&gt;.bbappend
124 </literallayout> 149 </literallayout>
@@ -130,7 +155,8 @@
130 <literallayout class='monospaced'> 155 <literallayout class='monospaced'>
131 meta-crownbay/COPYING.MIT 156 meta-crownbay/COPYING.MIT
132 meta-crownbay/README 157 meta-crownbay/README
133 meta-crownbay/binary 158 meta-crownbay/README.sources
159 meta-crownbay/binary/
134 meta-crownbay/conf/ 160 meta-crownbay/conf/
135 meta-crownbay/conf/layer.conf 161 meta-crownbay/conf/layer.conf
136 meta-crownbay/conf/machine/ 162 meta-crownbay/conf/machine/
@@ -171,7 +197,7 @@
171 <title>License Files</title> 197 <title>License Files</title>
172 198
173 <para> 199 <para>
174 You can find these files in the Yocto Project file's directory structure at: 200 You can find these files in the BSP Layer at:
175 <literallayout class='monospaced'> 201 <literallayout class='monospaced'>
176 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt; 202 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
177 </literallayout> 203 </literallayout>
@@ -193,7 +219,7 @@
193 <section id="bsp-filelayout-readme"> 219 <section id="bsp-filelayout-readme">
194 <title>README File</title> 220 <title>README File</title>
195 <para> 221 <para>
196 You can find these files in the Yocto Project file's directory structure at: 222 You can find this file in the BSP Layer at:
197 <literallayout class='monospaced'> 223 <literallayout class='monospaced'>
198 meta-&lt;bsp_name&gt;/README 224 meta-&lt;bsp_name&gt;/README
199 </literallayout> 225 </literallayout>
@@ -201,21 +227,41 @@
201 227
202 <para> 228 <para>
203 This file provides information on how to boot the live images that are optionally 229 This file provides information on how to boot the live images that are optionally
204 included in the <filename>/binary</filename> directory. 230 included in the <filename>binary/</filename> directory.
205 The <filename>README</filename> file also provides special information needed for 231 The <filename>README</filename> file also provides special information needed for
206 building the image. 232 building the image.
207 </para> 233 </para>
208 234
209 <para> 235 <para>
210 Technically speaking a <filename>README</filename> is optional but it is highly 236 At a minimum, the <filename>README</filename> file must
211 recommended that every BSP has one. 237 contain a list of dependencies, such as the names of
238 any other layers on which the BSP depends and the name of
239 the BSP maintainer with his or her contact information.
240 </para>
241 </section>
242
243 <section id="bsp-filelayout-readme-sources">
244 <title>README.sources File</title>
245 <para>
246 You can find this file in the BSP Layer at:
247 <literallayout class='monospaced'>
248 meta-&lt;bsp_name&gt;/README.sources
249 </literallayout>
250 </para>
251
252 <para>
253 This file provides information on where to locate the BSP source files.
254 For example, information provides where to find the sources that comprise
255 the images shipped with the BSP.
256 Information is also included to help you find the metadata used to generate the images
257 that ship with the BSP.
212 </para> 258 </para>
213 </section> 259 </section>
214 260
215 <section id="bsp-filelayout-binary"> 261 <section id="bsp-filelayout-binary">
216 <title>Pre-built User Binaries</title> 262 <title>Pre-built User Binaries</title>
217 <para> 263 <para>
218 You can find these files in the Yocto Project file's directory structure at: 264 You can find these files in the BSP Layer at:
219 <literallayout class='monospaced'> 265 <literallayout class='monospaced'>
220 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt; 266 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
221 </literallayout> 267 </literallayout>
@@ -225,24 +271,25 @@
225 This optional area contains useful pre-built kernels and user-space filesystem 271 This optional area contains useful pre-built kernels and user-space filesystem
226 images appropriate to the target system. 272 images appropriate to the target system.
227 This directory typically contains graphical (e.g. sato) and minimal live images 273 This directory typically contains graphical (e.g. sato) and minimal live images
228 when the BSP tarball has been created and made available in the Yocto Project website. 274 when the BSP tarball has been created and made available in the
275 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
229 You can use these kernels and images to get a system running and quickly get started 276 You can use these kernels and images to get a system running and quickly get started
230 on development tasks. 277 on development tasks.
231 </para> 278 </para>
232 279
233 <para> 280 <para>
234 The exact types of binaries present are highly hardware-dependent. 281 The exact types of binaries present are highly hardware-dependent.
235 However, a README file should be present in the BSP file structure that explains how to use 282 However, a README file should be present in the BSP Layer that explains how to use
236 the kernels and images with the target hardware. 283 the kernels and images with the target hardware.
237 If pre-built binaries are present, source code to meet licensing requirements must also 284 If pre-built binaries are present, source code to meet licensing requirements must also
238 be provided in some form. 285 exist in some form.
239 </para> 286 </para>
240 </section> 287 </section>
241 288
242 <section id='bsp-filelayout-layer'> 289 <section id='bsp-filelayout-layer'>
243 <title>Layer Configuration File</title> 290 <title>Layer Configuration File</title>
244 <para> 291 <para>
245 You can find this file in the Yocto Project file's directory structure at: 292 You can find this file in the BSP Layer at:
246 <literallayout class='monospaced'> 293 <literallayout class='monospaced'>
247 meta-&lt;bsp_name&gt;/conf/layer.conf 294 meta-&lt;bsp_name&gt;/conf/layer.conf
248 </literallayout> 295 </literallayout>
@@ -253,13 +300,14 @@
253 Project layer, identifies the 300 Project layer, identifies the
254 contents of the layer, and contains information about how Yocto Project should use it. 301 contents of the layer, and contains information about how Yocto Project should use it.
255 Generally, a standard boilerplate file such as the following works. 302 Generally, a standard boilerplate file such as the following works.
256 In the following example you would replace "bsp" and "_bsp" with the actual name 303 In the following example, you would replace "<filename>bsp</filename>" and
257 of the BSP (i.e. &lt;bsp_name&gt; from the example template). 304 "<filename>_bsp</filename>" with the actual name
305 of the BSP (i.e. <filename>&lt;bsp_name&gt;</filename> from the example template).
258 </para> 306 </para>
259 307
260 <para> 308 <para>
261 <literallayout class='monospaced'> 309 <literallayout class='monospaced'>
262 # We have a conf directory, add to BBPATH 310 # We have a conf and classes directory, add to BBPATH
263 BBPATH := "${BBPATH}:${LAYERDIR}" 311 BBPATH := "${BBPATH}:${LAYERDIR}"
264 312
265 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES 313 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
@@ -273,15 +321,25 @@
273 </para> 321 </para>
274 322
275 <para> 323 <para>
324 To illustrate the string substitutions, here are the last three statements from the Crown
325 Bay <filename>conf/layer.conf</filename> file:
326 <literallayout class='monospaced'>
327 BBFILE_COLLECTIONS += "crownbay"
328 BBFILE_PATTERN_crownbay := "^${LAYERDIR}/"
329 BBFILE_PRIORITY_crownbay = "6"
330 </literallayout>
331 </para>
332
333 <para>
276 This file simply makes BitBake aware of the recipes and configuration directories. 334 This file simply makes BitBake aware of the recipes and configuration directories.
277 This file must exist so that the Yocto Project build system can recognize the BSP. 335 The file must exist so that the Yocto Project build system can recognize the BSP.
278 </para> 336 </para>
279 </section> 337 </section>
280 338
281 <section id="bsp-filelayout-machine"> 339 <section id="bsp-filelayout-machine">
282 <title>Hardware Configuration Options</title> 340 <title>Hardware Configuration Options</title>
283 <para> 341 <para>
284 You can find these files in the Yocto Project file's directory structure at: 342 You can find these files in the BSP Layer at:
285 <literallayout class='monospaced'> 343 <literallayout class='monospaced'>
286 meta-&lt;bsp_name&gt;/conf/machine/*.conf 344 meta-&lt;bsp_name&gt;/conf/machine/*.conf
287 </literallayout> 345 </literallayout>
@@ -293,19 +351,20 @@
293 If the BSP supports multiple machines, multiple machine configuration files 351 If the BSP supports multiple machines, multiple machine configuration files
294 can be present. 352 can be present.
295 These filenames correspond to the values to which users have set the 353 These filenames correspond to the values to which users have set the
296 <filename>MACHINE</filename> variable. 354 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
297 </para> 355 </para>
298 356
299 <para> 357 <para>
300 These files define things such as the kernel package to use 358 These files define things such as the kernel package to use
301 (<filename>PREFERRED_PROVIDER</filename> of virtual/kernel), the hardware drivers to 359 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
360 of virtual/kernel), the hardware drivers to
302 include in different types of images, any special software components 361 include in different types of images, any special software components
303 that are needed, any bootloader information, and also any special image 362 that are needed, any bootloader information, and also any special image
304 format requirements. 363 format requirements.
305 </para> 364 </para>
306 365
307 <para> 366 <para>
308 At least one machine file is required for a BSP layer. 367 Each BSP Layer requires at least one machine file.
309 However, you can supply more than one file. 368 However, you can supply more than one file.
310 For example, in the Crown Bay BSP shown earlier in this section, the 369 For example, in the Crown Bay BSP shown earlier in this section, the
311 <filename>conf/machine</filename> directory contains two configuration files: 370 <filename>conf/machine</filename> directory contains two configuration files:
@@ -321,7 +380,7 @@
321 <para> 380 <para>
322 This <filename>crownbay.conf</filename> file could also include 381 This <filename>crownbay.conf</filename> file could also include
323 a hardware "tuning" file that is commonly used to 382 a hardware "tuning" file that is commonly used to
324 define the the package architecture and specify 383 define the package architecture and specify
325 optimization flags, which are carefully chosen to give best 384 optimization flags, which are carefully chosen to give best
326 performance on a given processor. 385 performance on a given processor.
327 </para> 386 </para>
@@ -341,7 +400,7 @@
341 <section id='bsp-filelayout-misc-recipes'> 400 <section id='bsp-filelayout-misc-recipes'>
342 <title>Miscellaneous Recipe Files</title> 401 <title>Miscellaneous Recipe Files</title>
343 <para> 402 <para>
344 You can find these files in the Yocto Project file's directory structure at: 403 You can find these files in the BSP Layer at:
345 <literallayout class='monospaced'> 404 <literallayout class='monospaced'>
346 meta-&lt;bsp_name&gt;/recipes-bsp/* 405 meta-&lt;bsp_name&gt;/recipes-bsp/*
347 </literallayout> 406 </literallayout>
@@ -356,7 +415,10 @@
356 Furthermore, there are machine-specific settings used during the build that are 415 Furthermore, there are machine-specific settings used during the build that are
357 defined by the <filename>machconfig</filename> files. 416 defined by the <filename>machconfig</filename> files.
358 In the Crown Bay example, two <filename>machconfig</filename> files exist: 417 In the Crown Bay example, two <filename>machconfig</filename> files exist:
359 one that supports the Intel EMGD and one that does not: 418 one that supports the
419 <trademark class='registered'>Intel</trademark> Embedded
420 Media and Graphics Driver (<trademark class='registered'>Intel</trademark>
421 EMGD) and one that does not:
360 <literallayout class='monospaced'> 422 <literallayout class='monospaced'>
361 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig 423 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
362 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig 424 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig
@@ -373,14 +435,16 @@
373 <section id='bsp-filelayout-core-recipes'> 435 <section id='bsp-filelayout-core-recipes'>
374 <title>Core Recipe Files</title> 436 <title>Core Recipe Files</title>
375 <para> 437 <para>
376 You can find these files in the Yocto Project file's directory structure at: 438 You can find these files in the BSP Layer at:
377 <literallayout class='monospaced'> 439 <literallayout class='monospaced'>
378 meta-&lt;bsp_name&gt;/recipes-core/* 440 meta-&lt;bsp_name&gt;/recipes-core/*
379 </literallayout> 441 </literallayout>
380 </para> 442 </para>
381 443
382 <para> 444 <para>
383 This directory contains recipe files for the core. 445 This directory contains recipe files that are almost always necessary to build a
446 useful, working Linux image.
447 Thus, the term "core" is used to group these recipes.
384 For example, in the Crown Bay BSP there is the 448 For example, in the Crown Bay BSP there is the
385 <filename>task-core-tools.bbappend</filename> file, which is an append file used 449 <filename>task-core-tools.bbappend</filename> file, which is an append file used
386 to recommend that the SystemTap package be included as a package when the image 450 to recommend that the SystemTap package be included as a package when the image
@@ -391,7 +455,7 @@
391 <section id='bsp-filelayout-recipes-graphics'> 455 <section id='bsp-filelayout-recipes-graphics'>
392 <title>Display Support Files</title> 456 <title>Display Support Files</title>
393 <para> 457 <para>
394 You can find these files in the Yocto Project file's directory structure at: 458 You can find these files in the BSP Layer at:
395 <literallayout class='monospaced'> 459 <literallayout class='monospaced'>
396 meta-&lt;bsp_name&gt;/recipes-graphics/* 460 meta-&lt;bsp_name&gt;/recipes-graphics/*
397 </literallayout> 461 </literallayout>
@@ -401,8 +465,12 @@
401 This optional directory contains recipes for the BSP if it has 465 This optional directory contains recipes for the BSP if it has
402 special requirements for graphics support. 466 special requirements for graphics support.
403 All files that are needed for the BSP to support a display are kept here. 467 All files that are needed for the BSP to support a display are kept here.
404 For example, the Crown Bay BSP contains the following files that support 468 For example, the Crown Bay BSP contains two versions of the
405 building a BSP that supports and does not support the Intel EMGD: 469 <filename>xorg.conf</filename> file.
470 The version in <filename>crownbay</filename> builds a BSP that supports the
471 <trademark class='registered'>Intel</trademark> Embedded Media Graphics Driver (EMGD),
472 while the version in <filename>crownbay-noemgd</filename> builds
473 a BSP that supports Video Electronics Standards Association (VESA) graphics only:
406 <literallayout class='monospaced'> 474 <literallayout class='monospaced'>
407 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend 475 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
408 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf 476 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf
@@ -414,7 +482,7 @@
414 <section id='bsp-filelayout-kernel'> 482 <section id='bsp-filelayout-kernel'>
415 <title>Linux Kernel Configuration</title> 483 <title>Linux Kernel Configuration</title>
416 <para> 484 <para>
417 You can find these files in the Yocto Project file's directory structure at: 485 You can find these files in the BSP Layer at:
418 <literallayout class='monospaced'> 486 <literallayout class='monospaced'>
419 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_*.bbappend 487 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_*.bbappend
420 </literallayout> 488 </literallayout>
@@ -427,12 +495,11 @@
427 For your BSP, you typically want to use an existing Yocto Project kernel found in the 495 For your BSP, you typically want to use an existing Yocto Project kernel found in the
428 Yocto Project repository at <filename>meta/recipes-kernel/linux</filename>. 496 Yocto Project repository at <filename>meta/recipes-kernel/linux</filename>.
429 You can append your specific changes to the kernel recipe by using a 497 You can append your specific changes to the kernel recipe by using a
430 similarly named append file, which is located in the 498 similarly named append file, which is located in the BSP Layer (e.g.
431 <filename>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> 499 the <filename>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> directory).
432 directory.
433 </para> 500 </para>
434 <para> 501 <para>
435 Suppose you use a BSP that uses the <filename>linux-yocto_3.0.bb</filename> kernel, 502 Suppose the BSP uses the <filename>linux-yocto_3.0.bb</filename> kernel,
436 which is the preferred kernel to use for developing a new BSP using the Yocto Project. 503 which is the preferred kernel to use for developing a new BSP using the Yocto Project.
437 In other words, you have selected the kernel in your 504 In other words, you have selected the kernel in your
438 <filename>&lt;bsp_name&gt;.conf</filename> file by adding the following statements: 505 <filename>&lt;bsp_name&gt;.conf</filename> file by adding the following statements:
@@ -449,7 +516,10 @@
449 <literallayout class='monospaced'> 516 <literallayout class='monospaced'>
450 meta-crownbay/recipes-kernel/linux/linux-yocto_3.0.bbappend 517 meta-crownbay/recipes-kernel/linux/linux-yocto_3.0.bbappend
451 </literallayout> 518 </literallayout>
452 The file contains the following: 519 The following listing shows the file.
520 Be aware that the actual commit ID strings in this example listing might be different
521 than the actual strings in the file from the <filename>meta-intel</filename>
522 Git source repository.
453 <literallayout class='monospaced'> 523 <literallayout class='monospaced'>
454 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 524 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
455 525
@@ -467,8 +537,8 @@
467 SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= "2247da9131ea7e46ed4766a69bb1353dba22f873" 537 SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= "2247da9131ea7e46ed4766a69bb1353dba22f873"
468 SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= "d05450e4aef02c1b7137398ab3a9f8f96da74f52" 538 SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= "d05450e4aef02c1b7137398ab3a9f8f96da74f52"
469 </literallayout> 539 </literallayout>
470 This append file contains statements used to support the Crown Bay BSP for both 540 This append file contains statements used to support the Crown Bay BSP for both
471 Intel EMGD and non-EMGD. 541 <trademark class='registered'>Intel</trademark> EMGD and the VESA graphics.
472 The build process, in this case, recognizes and uses only the statements that 542 The build process, in this case, recognizes and uses only the statements that
473 apply to the defined machine name - <filename>crownbay</filename> in this case. 543 apply to the defined machine name - <filename>crownbay</filename> in this case.
474 So, the applicable statements in the <filename>linux-yocto_3.0.bbappend</filename> 544 So, the applicable statements in the <filename>linux-yocto_3.0.bbappend</filename>
@@ -503,14 +573,14 @@
503 </para> 573 </para>
504 <para> 574 <para>
505 For example, suppose you had a set of configuration options in a file called 575 For example, suppose you had a set of configuration options in a file called
506 <filename>defconfig</filename>. 576 <filename>myconfig</filename>.
507 If you put that file inside a directory named 577 If you put that file inside a directory named
508 <filename>/linux-yocto</filename> and then added 578 <filename>/linux-yocto</filename> and then added
509 a <filename>SRC_URI</filename> statement such as the following to the append file, 579 a <filename>SRC_URI</filename> statement such as the following to the append file,
510 those configuration 580 those configuration
511 options will be picked up and applied when the kernel is built. 581 options will be picked up and applied when the kernel is built.
512 <literallayout class='monospaced'> 582 <literallayout class='monospaced'>
513 SRC_URI += "file://defconfig" 583 SRC_URI += "file://myconfig"
514 </literallayout> 584 </literallayout>
515 </para> 585 </para>
516 <para> 586 <para>
@@ -520,20 +590,26 @@
520 into their own files and add those by using a <filename>SRC_URI</filename> statement like the 590 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
521 following in your append file: 591 following in your append file:
522 <literallayout class='monospaced'> 592 <literallayout class='monospaced'>
523 SRC_URI += "file://defconfig \ 593 SRC_URI += "file://myconfig \
524 file://eth.cfg \ 594 file://eth.cfg \
525 file://gfx.cfg" 595 file://gfx.cfg"
526 </literallayout> 596 </literallayout>
527 </para> 597 </para>
528 <para> 598 <para>
529 The <filename>FILESEXTRAPATHS</filename> variable is in boilerplate form here 599 The <filename>FILESEXTRAPATHS</filename> variable is in boilerplate form in the
530 in order to make it easy to do that. 600 previous example in order to make it easy to do that.
531 It basically allows those configuration files to be found by the build process. 601 This variable must be in your layer or BitBake will not find the patches or
602 configurations even if you have them in your <filename>SRC_URI</filename>.
603 The <filename>FILESEXTRAPATHS</filename> variable enables the build process to
604 find those configuration files.
532 </para> 605 </para>
533 <note> 606 <note>
534 <para> 607 <para>
535 Other methods exist to accomplish grouping and defining configuration options. 608 Other methods exist to accomplish grouping and defining configuration options.
536 For example, you could directly add configuration options to the Yocto kernel 609 For example, if you are working with a local clone of the kernel repository,
610 you could checkout the kernel's <filename>meta</filename> branch, make your changes,
611 and then push the changes to the local bare clone of the kernel.
612 The result is that you directly add configuration options to the Yocto kernel
537 <filename>meta</filename> branch for your BSP. 613 <filename>meta</filename> branch for your BSP.
538 The configuration options will likely end up in that location anyway if the BSP gets 614 The configuration options will likely end up in that location anyway if the BSP gets
539 added to the Yocto Project. 615 added to the Yocto Project.
@@ -543,7 +619,7 @@
543 <para> 619 <para>
544 In general, however, the Yocto Project maintainers take care of moving the 620 In general, however, the Yocto Project maintainers take care of moving the
545 <filename>SRC_URI</filename>-specified 621 <filename>SRC_URI</filename>-specified
546 configuration options to the <filename>meta</filename> branch. 622 configuration options to the kernel's <filename>meta</filename> branch.
547 Not only is it easier for BSP developers to not have to worry about putting those 623 Not only is it easier for BSP developers to not have to worry about putting those
548 configurations in the branch, but having the maintainers do it allows them to apply 624 configurations in the branch, but having the maintainers do it allows them to apply
549 'global' knowledge about the kinds of common configuration options multiple BSPs in 625 'global' knowledge about the kinds of common configuration options multiple BSPs in
@@ -553,136 +629,815 @@
553 </section> 629 </section>
554 </section> 630 </section>
555 631
556 <section id='bsp-click-through-licensing'> 632 <section id='requirements-and-recommendations-for-released-bsps'>
557 <title>BSP 'Click-Through' Licensing Procedure</title> 633 <title>Requirements and Recommendations for Released BSPs</title>
558 634
559 <note> This section describes how 635 <para>
560 click-through licensing is expected to work. 636 Certain requirements exist for a released BSP to be considered
561 Currently, this functionality is not yet implemented. 637 compliant with the Yocto Project.
562 </note> 638 Additionally, a single recommendation also exists.
639 This section describes the requirements and recommendation for
640 released BSPs.
641 </para>
642
643 <section id='released-bsp-requirements'>
644 <title>Released BSP Requirements</title>
645
646 <para>
647 Before looking at BSP requirements, you should consider the following:
648 <itemizedlist>
649 <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal"
650 layer that can be added to the Yocto Project.
651 For guidelines on creating a Yocto Project layer that meets these base requirements, see the
652 "<link linkend='bsp-layers'>BSP Layers</link>" and the
653 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding
654 and Creating Layers"</ulink> in the Yocto Project Development Manual.</para></listitem>
655 <listitem><para>The requirements in this section apply regardless of how you
656 ultimately package a BSP.
657 You should consult the packaging and distribution guidelines for your
658 specific release process.
659 For an example of packaging and distribution requirements, see the
660 <ulink url='&YOCTO_WIKI_URL;/wiki/Third_Party_BSP_Release_Process'>Third
661 Party BSP Release Process</ulink> wiki page.</para></listitem>
662 <listitem><para>The requirements for the BSP as it is made available to a developer
663 are completely independent of the released form of the BSP.
664 For example, the BSP metadata can be contained within a Git repository
665 and could have a directory structure completely different from what appears
666 in the officially released BSP layer.</para></listitem>
667 <listitem><para>It is not required that specific packages or package
668 modifications exist in the BSP layer, beyond the requirements for general
669 compliance with the Yocto Project.
670 For example, no requirement exists dictating that a specific kernel or
671 kernel version be used in a given BSP.</para></listitem>
672 </itemizedlist>
673 </para>
674
675 <para>
676 Following are the requirements for a released BSP that conforms to the
677 Yocto Project:
678 <itemizedlist>
679 <listitem><para><emphasis>Layer Name:</emphasis>
680 The BSP must have a layer name that follows the Yocto
681 Project standards.
682 For information on BSP layer names, see the
683 "<link linkend='bsp-layers'>BSP Layers</link>" section.
684 </para></listitem>
685 <listitem><para><emphasis>File System Layout:</emphasis>
686 When possible, use the same directory names in your
687 BSP layer as listed in the <filename>recipes.txt</filename> file.
688 In particular, you should place recipes
689 (<filename>.bb</filename> files) and recipe
690 modifications (<filename>.bbappend</filename> files) into
691 <filename>recipes-*</filename> subdirectories by functional area
692 as outlined in <filename>recipes.txt</filename>.
693 If you cannot find a category in <filename>recipes.txt</filename>
694 to fit a particular recipe, you can make up your own
695 <filename>recipe-*</filename> subdirectory.
696 You can find <filename>recipes.txt</filename> in the
697 <filename>meta</filename> directory of the
698 <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-files'>Yocto
699 Project Files</ulink>, or in the OpenEmbedded Core Layer
700 (<filename>openembedded-core</filename>) found at
701 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
702 </para>
703 <para>Within any particular <filename>recipes-*</filename> category, the layout
704 should match what is found in the OpenEmbedded Core
705 Git repository (<filename>openembedded-core</filename>)
706 or the Yocto Project Files (<filename>poky</filename>).
707 In other words, make sure you place related files in appropriately
708 related <filename>recipes-*</filename> subdirectories specific to the
709 recipe's function, or within a subdirectory containing a set of closely-related
710 recipes.
711 The recipes themselves should follow the general guidelines
712 for recipes used in the Yocto Project found in the
713 <ulink url='https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide'>Yocto
714 Recipe and Patch Style Guide</ulink>.</para></listitem>
715 <listitem><para><emphasis>License File:</emphasis>
716 You must include a license file in the
717 <filename>meta-&lt;bsp_name&gt;</filename> directory.
718 This license covers the BSP metadata as a whole.
719 You must specify which license to use since there is no
720 default license if one is not specified.
721 See the
722 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fishriver/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
723 file for the Fish River BSP in the <filename>meta-fishriver</filename> BSP layer
724 as an example.</para></listitem>
725 <listitem><para><emphasis>README File:</emphasis>
726 You must include a <filename>README</filename> file in the
727 <filename>meta-&lt;bsp_name&gt;</filename> directory.
728 See the
729 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fishriver/README'><filename>README</filename></ulink>
730 file for the Fish River BSP in the <filename>meta-fishriver</filename> BSP layer
731 as an example.</para>
732 <para>At a minimum, the <filename>README</filename> file should
733 contain the following:
734 <itemizedlist>
735 <listitem><para>A brief description about the hardware the BSP
736 targets.</para></listitem>
737 <listitem><para>A list of all the dependencies a
738 on which a BSP layer depends.
739 These dependencies are typically a list of required layers needed
740 to build the BSP.
741 However, the dependencies should also contain information regarding
742 any other dependencies the BSP might have.</para></listitem>
743 <listitem><para>Any required special licensing information.
744 For example, this information includes information on
745 special variables needed to satisfy a EULA,
746 or instructions on information needed to build or distribute
747 binaries built from the BSP metadata.</para></listitem>
748 <listitem><para>The name and contact information for the
749 BSP layer maintainer.
750 This is the person to whom patches and questions should
751 be sent.</para></listitem>
752 <listitem><para>Instructions on how to build the BSP using the BSP
753 layer.</para></listitem>
754 <listitem><para>Instructions on how to boot the BSP build from
755 the BSP layer.</para></listitem>
756 <listitem><para>Instructions on how to boot the binary images
757 contained in the <filename>/binary</filename> directory,
758 if present.</para></listitem>
759 <listitem><para>Information on any known bugs or issues that users
760 should know about when either building or booting the BSP
761 binaries.</para></listitem>
762 </itemizedlist></para></listitem>
763 <listitem><para><emphasis>README.sources File:</emphasis>
764 You must include a <filename>README.sources</filename> in the
765 <filename>meta-&lt;bsp_name&gt;</filename> directory.
766 This file specifies exactly where you can find the sources used to
767 generate the binary images contained in the
768 <filename>/binary</filename> directory, if present.
769 See the
770 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fishriver/README.sources'><filename>README.sources</filename></ulink>
771 file for the Fish River BSP in the <filename>meta-fishriver</filename> BSP layer
772 as an example.</para></listitem>
773 <listitem><para><emphasis>Layer Configuration File:</emphasis>
774 You must include a <filename>conf/layer.conf</filename> in the
775 <filename>meta-&lt;bsp_name&gt;</filename> directory.
776 This file identifies the <filename>meta-&lt;bsp_name&gt;</filename>
777 BSP layer as a layer to the build system.</para></listitem>
778 <listitem><para><emphasis>Machine Configuration File:</emphasis>
779 You must include a <filename>conf/machine/&lt;bsp_name&gt;.conf</filename>
780 in the <filename>meta-&lt;bsp_name&gt;</filename> directory.
781 This configuration file defines a machine target that can be built
782 using the BSP layer.
783 Multiple machine configuration files define variations of machine
784 configurations that are supported by the BSP.
785 If a BSP supports more multiple machine variations, you need to
786 adequately describe each variation in the BSP
787 <filename>README</filename> file.
788 Do not use multiple machine configuration files to describe disparate
789 hardware.
790 Multiple machine configuration files should describe very similar targets.
791 If you do have very different targets, you should create a separate
792 BSP.
793 <note>It is completely possible for a developer to structure the
794 working repository as a conglomeration of unrelated BSP
795 files, and to possibly generate specifically targeted 'release' BSPs
796 from that directory using scripts or some other mechanism.
797 Such considerations are outside the scope of this document.</note>
798 </para></listitem>
799 </itemizedlist>
800 </para>
801 </section>
802
803 <section id='released-bsp-recommendations'>
804 <title>Released BSP Recommendations</title>
805
806 <para>
807 Following are recommendations for a released BSP that conforms to the
808 Yocto Project:
809 <itemizedlist>
810 <listitem><para><emphasis>Bootable Images:</emphasis>
811 BSP releases
812 can contain one or more bootable images.
813 Including bootable images allows users to easily try out the BSP
814 on their own hardware.</para>
815 <para>In some cases, it might not be convenient to include a
816 bootable image.
817 In this case, you might want to make two versions of the
818 BSP available: one that contains binary images, and one
819 that does not.
820 The version that does not contain bootable images avoids
821 unnecessary download times for users not interested in the images.
822 </para>
823 <para>If you need to distribute a BSP and include bootable images or build kernel and
824 filesystems meant to allow users to boot the BSP for evaluation
825 purposes, you should put the images and artifacts within a
826 <filename>binary/</filename> subdirectory located in the
827 <filename>meta-&lt;bsp_name&gt;</filename> directory.
828 <note>If you do include a bootable image as part of the BSP and the image
829 was built by software covered by the GPL or other open source licenses,
830 it is your responsibility to understand
831 and meet all licensing requirements, which could include distribution
832 of source files.</note></para></listitem>
833 <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
834 Kernel recipes in the BSP should be based on a Yocto Linux kernel.
835 Basing your recipes on these kernels reduces the costs for maintaining
836 the BSP and increases its scalability.
837 See the <filename>Yocto Linux Kernel</filename> category in the
838 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'><filename>Yocto Source Repositories</filename></ulink>
839 for these kernels.</para></listitem>
840 </itemizedlist>
841 </para>
842 </section>
843 </section>
844
845 <section id='customizing-a-recipe-for-a-bsp'>
846 <title>Customizing a Recipe for a BSP</title>
563 847
564 <para> 848 <para>
565 In some cases, a BSP contains separately licensed IP 849 If you plan on customizing a recipe for a particular BSP, you need to do the
566 (Intellectual Property) for a component that imposes 850 following:
567 upon the user a requirement to accept the terms of a 851 <itemizedlist>
568 'click-through' license. 852 <listitem><para>Include within the BSP layer a <filename>.bbappend</filename>
569 Once the license is accepted the 853 file for the modified recipe.</para></listitem>
570 Yocto Project build system can then build and include the 854 <listitem><para>Place the BSP-specific file in the BSP's recipe
571 corresponding component in the final BSP image. 855 <filename>.bbappend</filename> file path under a directory named
572 Some affected components might be essential to the normal 856 after the machine.</para></listitem>
573 functioning of the system and have no 'free' replacement 857 </itemizedlist>
574 (i.e. the resulting system would be non-functional 858 </para>
575 without them). 859
576 On the other hand, other components might be simply 860 <para>
577 'good-to-have' or purely elective, or if essential 861 To better understand this, consider an example that customizes a recipe by adding
578 nonetheless have a 'free' (possibly less-capable) 862 a BSP-specific configuration file named <filename>interfaces</filename> to the
579 version that could be used as a in the BSP recipe. 863 <filename>netbase_4.47.bb</filename> recipe for machine "xyz".
864 Do the following:
865 <orderedlist>
866 <listitem><para>Edit the <filename>netbase_4.47.bbappend</filename> file so that it
867 contains the following:
868 <literallayout class='monospaced'>
869 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
870 PRINC := "${@int(PRINC) + 2}"
871 </literallayout></para></listitem>
872 <listitem><para>Create and place the new <filename>interfaces</filename>
873 configuration file in the BSP's layer here:
874 <literallayout class='monospaced'>
875 meta-xyz/recipes-core/netbase/files/xyz/interfaces
876 </literallayout></para></listitem>
877 </orderedlist>
580 </para> 878 </para>
879 </section>
880
881 <section id='bsp-licensing-considerations'>
882 <title>BSP Licensing Considerations</title>
581 883
582 <para> 884 <para>
583 For cases where you can substitute something and still maintain functionality, 885 In some cases, a BSP contains separately licensed Intellectual Property (IP)
584 the Yocto Project website's 886 for a component or components.
585 <ulink url='http://www.yoctoproject.org/download/all?keys=&amp;download_type=1&amp;download_version='>BSP Download Page</ulink> 887 For these cases, you are required to accept the terms of a commercial or other
586 makes available 'de-featured' BSPs that are completely free of any IP encumbrances. 888 type of license that requires some kind of explicit End User License Agreement (EULA).
587 For these cases you can use the substitution directly and without any further licensing 889 Once the license is accepted, the Yocto Project build system can then build and
588 requirements. 890 include the corresponding component in the final BSP image.
589 If present, these fully 'de-featured' BSPs are named appropriately different 891 If the BSP is available as a pre-built image, you can download the image after
590 as compared to the names of the respective encumbered BSPs. 892 agreeing to the license or EULA.
591 If available, these substitutions are the simplest and most preferred options.
592 This, of course, assumes the resulting functionality meets requirements.
593 </para> 893 </para>
594 894
595 <para> 895 <para>
596 If however, a non-encumbered version is unavailable or the 'free' version 896 You could find that some separately licensed components that are essential
597 would provide unsuitable functionality or quality, you can use 897 for normal operation of the system might not have an unencumbered (or free)
598 an encumbered version. 898 substitute.
899 Without these essential components, the system would be non-functional.
900 Then again, you might find that other licensed components that are simply
901 'good-to-have' or purely elective do have an unencumbered, free replacement
902 component that you can use rather than agreeing to the separately licensed component.
903 Even for components essential to the system, you might find an unencumbered component
904 that is not identical but will work as a less-capable version of the
905 licensed version in the BSP recipe.
599 </para> 906 </para>
600 907
601 <para> 908 <para>
602 Several methods exist within the Yocto Project build system to satisfy the licensing 909 For cases where you can substitute a free component and still
603 requirements for an encumbered BSP. 910 maintain the system's functionality, the Yocto Project website's
604 The following list describes them in preferential order: 911 <ulink url='&YOCTO_HOME_URL;/download/all?keys=&amp;download_type=1&amp;download_version='>BSP
912 Download Page</ulink> makes available de-featured BSPs
913 that are completely free of any IP encumbrances.
914 For these cases, you can use the substitution directly and
915 without any further licensing requirements.
916 If present, these fully de-featured BSPs are named appropriately
917 different as compared to the names of the respective
918 encumbered BSPs.
919 If available, these substitutions are your
920 simplest and most preferred options.
921 Use of these substitutions of course assumes the resulting functionality meets
922 system requirements.
923 </para>
924
925 <para>
926 If however, a non-encumbered version is unavailable or
927 it provides unsuitable functionality or quality, you can use an encumbered
928 version.
929 </para>
930
931 <para>
932 A couple different methods exist within the Yocto
933 Project build system to satisfy the licensing
934 requirements for an encumbered BSP.
935 The following list describes them in order of preference:
936 <orderedlist>
937 <listitem><para><emphasis>Use the <filename>LICENSE_FLAGS</filename> variable
938 to define the Yocto Project recipes that have commercial or other types of
939 specially-licensed packages:</emphasis>
940 For each of those recipes, you can
941 specify a matching license string in a
942 <filename>local.conf</filename> variable named
943 <filename>LICENSE_FLAGS_WHITELIST</filename>.
944 Specifying the matching license string signifies that you agree to the license.
945 Thus, the build system can build the corresponding recipe and include
946 the component in the image.
947 See the
948 "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
949 Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
950 Manual for details on how to use these variables.</para>
951 <para>If you build as you normally would, without
952 specifying any recipes in the
953 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
954 provides you with the list of recipes that you have
955 tried to include in the image that need entries in
956 the <filename>LICENSE_FLAGS_WHITELIST</filename>.
957 Once you enter the appropriate license flags into the whitelist,
958 restart the build to continue where it left off.
959 During the build, the prompt will not appear again
960 since you have satisfied the requirement.</para>
961 <para>Once the appropriate license flags are on the white list
962 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
963 can build the encumbered image with no change at all
964 to the normal build process.</para></listitem>
965 <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis>
966 You can get this type of BSP by visiting the Yocto Project website's
967 <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink>
968 page and clicking on "BSP Downloads".
969 You can download BSP tarballs that contain proprietary components
970 after agreeing to the licensing
971 requirements of each of the individually encumbered
972 packages as part of the download process.
973 Obtaining the BSP this way allows you to access an encumbered
974 image immediately after agreeing to the
975 click-through license agreements presented by the
976 website.
977 Note that if you want to build the image
978 yourself using the recipes contained within the BSP
979 tarball, you will still need to create an
980 appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the
981 encumbered recipes in the BSP.</para></listitem>
982 </orderedlist>
983 </para>
984
985 <note>
986 Pre-compiled images are bundled with
987 a time-limited kernel that runs for a
988 predetermined amount of time (10 days) before it forces
989 the system to reboot.
990 This limitation is meant to discourage direct redistribution
991 of the image.
992 You must eventually rebuild the image if you want to remove this restriction.
993 </note>
994 </section>
995
996 <section id='using-the-yocto-projects-bsp-tools'>
997 <title>Using the Yocto Project's BSP Tools</title>
998
999 <para>
1000 The Yocto Project includes a couple of tools that enable
1001 you to create a <link linkend='bsp-layers'>BSP layer</link>
1002 from scratch and do basic configuration and maintenance
1003 of the kernel without ever looking at a Yocto Project metadata file.
1004 These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
1005 respectively.
1006 </para>
1007
1008 <para>
1009 The following sections describe the common location and help features as well
1010 as details for the <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>
1011 tools.
605 </para> 1012 </para>
606 1013
607 <orderedlist> 1014 <section id='common-features'>
608 <listitem> 1015 <title>Common Features</title>
609 1016
610 <para> 1017 <para>
611 Get a license key (or keys) for the encumbered BSP by visiting 1018 Designed to have a command interface somewhat like
612 a website and providing the name of the BSP and your email address 1019 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>, each
613 through a web form. 1020 tool is structured as a set of sub-commands under a
1021 top-level command.
1022 The top-level command (<filename>yocto-bsp</filename>
1023 or <filename>yocto-kernel</filename>) itself does
1024 nothing but invoke or provide help on the sub-commands
1025 it supports.
614 </para> 1026 </para>
615 1027
616 <para> 1028 <para>
617 After agreeing to any applicable license terms, the 1029 Both tools reside in the <filename>scripts/</filename> subdirectory
618 BSP key(s) will be immediately sent to the address 1030 of the <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-files'>Yocto Project
619 you gave and you can use them by specifying BSPKEY_&lt;keydomain&gt; 1031 Files</ulink>.
620 environment variables when building the image: 1032 Consequently, to use the scripts, you must <filename>source</filename> the
621 </para> 1033 environment just as you would when invoking a build:
622 1034 <literallayout class='monospaced'>
623 <literallayout class='monospaced'> 1035 $ source oe-init-build-env [build_dir]
624 $ BSPKEY_&lt;keydomain&gt;=&lt;key&gt; bitbake core-image-sato 1036 </literallayout>
625 </literallayout>
626
627 <para>
628 These steps allow the encumbered image to be built
629 with no change at all to the normal build process.
630 </para>
631
632 <para>
633 Equivalently and probably more conveniently, a line
634 for each key can instead be put into the user's
635 <filename>local.conf</filename> file found in the Yocto Project file's
636 build directory.
637 </para>
638
639 <para>
640 The &lt;keydomain&gt; component of the
641 BSPKEY_&lt;keydomain&gt; is required because there
642 might be multiple licenses in effect for a given BSP.
643 In such cases, a given &lt;keydomain&gt; corresponds to
644 a particular license. In order for an encumbered
645 BSP that encompasses multiple key domains to be built
646 successfully, a &lt;keydomain&gt; entry for each
647 applicable license must be present in <filename>local.conf</filename> or
648 supplied on the command-line.
649 </para>
650 </listitem>
651 <listitem>
652 <para>
653 Do nothing - build as you normally would.
654 When a license is needed the build will stop and prompt you with instructions.
655 Follow the license prompts that originate from the
656 encumbered BSP.
657 These prompts usually take the form of instructions
658 needed to manually fetch the encumbered package(s)
659 and md5 sums into the required directory
660 (e.g. the <filename>yocto/build/downloads</filename>).
661 Once the manual package fetch has been
662 completed, restart the build to continue where
663 it left off.
664 During the build the prompt will not appear again since you have satisfied the
665 requirement.
666 </para>
667 </listitem>
668 <listitem>
669 <para>
670 Get a full-featured BSP recipe rather than a key.
671 You can do this by visiting the applicable BSP download page from the Yocto
672 Project website at
673 <ulink url='http://yoctoproject.org/download/board-support-package-bsp-downloads'></ulink>.
674 BSP tarballs that have proprietary information can be downloaded after agreeing
675 to licensing requirements as part of the download process.
676 Obtaining the code this way allows you to build an encumbered image with
677 no changes at all as compared to the normal build.
678 </para> 1037 </para>
679 </listitem>
680 </orderedlist>
681 <para>
682 Note that the third method is also the only option available
683 when downloading pre-compiled images generated from non-free BSPs.
684 Those images are likewise available at from the Yocto Project website.
685 </para>
686 </section>
687 1038
1039 <para>
1040 The most immediately useful function is to get help on both tools.
1041 The built-in help system makes it easy to drill down at
1042 any time and view the syntax required for any specific command.
1043 Simply enter the name of the command, or the command along with
1044 <filename>help</filename> to display a list of the available sub-commands.
1045 Here is an example:
1046 <literallayout class='monospaced'>
1047 $ yocto-bsp
1048 $ yocto-bsp help
1049
1050 Usage:
1051
1052 Create a customized Yocto BSP layer.
1053
1054 usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
1055
1056 The most commonly used 'yocto-bsp' commands are:
1057 create Create a new Yocto BSP
1058 list List available values for options and BSP properties
1059
1060 See 'yocto-bsp help COMMAND' for more information on a specific command.
1061
1062
1063 Options:
1064 --version show program's version number and exit
1065 -h, --help show this help message and exit
1066 -D, --debug output debug information
1067 </literallayout>
1068 </para>
1069
1070 <para>
1071 Similarly, entering just the name of a sub-command shows the detailed usage
1072 for that sub-command:
1073 <literallayout class='monospaced'>
1074 $ yocto-bsp create
1075
1076 Usage:
1077
1078 Create a new Yocto BSP
1079 usage: yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
1080 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
1081
1082 This command creates a Yocto BSP based on the specified parameters.
1083 The new BSP will be a new Yocto BSP layer contained by default within
1084 the top-level directory specified as 'meta-bsp-name'. The -o option
1085 can be used to place the BSP layer in a directory with a different
1086 name and location.
1087
1088 ...
1089 </literallayout>
1090 </para>
1091
1092 <para>
1093 For any sub-command, you can also use the word 'help' just before the
1094 sub-command to get more extensive documentation:
1095 <literallayout class='monospaced'>
1096 $ yocto-bsp help create
1097
1098 NAME
1099 yocto-bsp create - Create a new Yocto BSP
1100
1101 SYNOPSIS
1102 yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
1103 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
1104
1105 DESCRIPTION
1106 This command creates a Yocto BSP based on the specified
1107 parameters. The new BSP will be a new Yocto BSP layer contained
1108 by default within the top-level directory specified as
1109 'meta-bsp-name'. The -o option can be used to place the BSP layer
1110 in a directory with a different name and location.
1111
1112 The value of the 'karch' parameter determines the set of files
1113 that will be generated for the BSP, along with the specific set of
1114 'properties' that will be used to fill out the BSP-specific
1115 portions of the BSP.
1116
1117 ...
1118
1119 NOTE: Once created, you should add your new layer to your
1120 bblayers.conf file in order for it to be subsequently seen and
1121 modified by the yocto-kernel tool.
1122
1123 NOTE for x86- and x86_64-based BSPs: The generated BSP assumes the
1124 presence of the of the meta-intel layer, so you should also have a
1125 meta-intel layer present and added to your bblayers.conf as well.
1126 </literallayout>
1127 </para>
1128
1129 <para>
1130 Now that you know where these two commands reside and how to access information
1131 on them, you should find it relatively straightforward to discover the commands
1132 necessary to create a BSP and perform basic kernel maintenance on that BSP using
1133 the tools.
1134 The next sections provide a concrete starting point to expand on a few points that
1135 might not be immediately obvious or that could use further explanation.
1136 </para>
1137 </section>
1138
1139
1140 <section id='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
1141 <title>Creating a new BSP Layer Using the yocto-bsp Script</title>
1142
1143 <para>
1144 The <filename>yocto-bsp</filename> script creates a new
1145 <link linkend='bsp-layers'>BSP layer</link> for any architecture supported
1146 by the Yocto Project, as well as QEMU versions of the same.
1147 The default mode of the script's operation is to prompt you for information needed
1148 to generate the BSP layer.
1149 For the current set of BSPs, the script prompts you for various important
1150 parameters such as:
1151 <itemizedlist>
1152 <listitem><para>which kernel to use</para></listitem>
1153 <listitem><para>which branch of that kernel to use (or re-use)</para></listitem>
1154 <listitem><para>whether or not to use X, and if so, which drivers to use</para></listitem>
1155 <listitem><para>whether to turn on SMP</para></listitem>
1156 <listitem><para>whether the BSP has a keyboard</para></listitem>
1157 <listitem><para>whether the BSP has a touchscreen</para></listitem>
1158 <listitem><para>any remaining configurable items associated with the BSP</para></listitem>
1159 </itemizedlist>
1160 </para>
1161
1162 <para>
1163 You use the <filename>yocto-bsp create</filename> sub-command to create
1164 a new BSP layer.
1165 This command requires you to specify a particular architecture on which to
1166 base the BSP.
1167 Assuming you have sourced the environment, you can use the
1168 <filename>yocto-bsp list karch</filename> sub-command to list the
1169 architectures available for BSP creation as follows:
1170 <literallayout class='monospaced'>
1171 $ yocto-bsp list karch
1172 Architectures available:
1173 arm
1174 powerpc
1175 i386
1176 mips
1177 x86_64
1178 qemu
1179 </literallayout>
1180 </para>
1181
1182 <para>
1183 The remainder of this section presents an example that uses
1184 <filename>myarm</filename> as the machine name and <filename>qemu</filename>
1185 as the machine architecture.
1186 Of the available architectures, <filename>qemu</filename> is the only architecture
1187 that causes the script to prompt you further for an actual architecture.
1188 In every other way, this architecture is representative of how creating a BSP for
1189 a 'real' machine would work.
1190 The reason the example uses this architecture is because it is an emulated architecture
1191 and can easily be followed without requiring actual hardware.
1192 </para>
1193
1194 <para>
1195 As the <filename>yocto-bsp create</filename> command runs, default values for
1196 the prompts appear in brackets.
1197 Pressing enter without supplying anything on the command line or pressing enter
1198 and providing an invalid response causes the script to accept the default value.
1199 </para>
1200
1201 <para>
1202 Following is the complete example:
1203 <literallayout class='monospaced'>
1204 $ yocto-bsp create myarm qemu
1205 Which qemu architecture would you like to use? [default: x86]
1206 1) common 32-bit x86
1207 2) common 64-bit x86
1208 3) common 32-bit ARM
1209 4) common 32-bit PowerPC
1210 5) common 32-bit MIPS
1211 3
1212 Would you like to use the default (3.2) kernel? (Y/n)
1213 Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [Y/n]
1214 Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.2...
1215 Please choose a machine branch to base this BSP on => [default: standard/default/common-pc]
1216 1) base
1217 2) standard/base
1218 3) standard/default/arm-versatile-926ejs
1219 4) standard/default/base
1220 5) standard/default/beagleboard
1221 6) standard/default/cedartrailbsp (copy).xml
1222 7) standard/default/common-pc-64/base
1223 8) standard/default/common-pc-64/jasperforest
1224 9) standard/default/common-pc-64/romley
1225 10) standard/default/common-pc-64/sugarbay
1226 11) standard/default/common-pc/atom-pc
1227 12) standard/default/common-pc/base
1228 13) standard/default/crownbay
1229 14) standard/default/emenlow
1230 15) standard/default/fishriver
1231 16) standard/default/fri2
1232 17) standard/default/fsl-mpc8315e-rdb
1233 18) standard/default/mti-malta32-be
1234 19) standard/default/mti-malta32-le
1235 20) standard/default/preempt-rt
1236 21) standard/default/qemu-ppc32
1237 22) standard/default/routerstationpro
1238 23) standard/preempt-rt/base
1239 24) standard/preempt-rt/qemu-ppc32
1240 25) standard/preempt-rt/routerstationpro
1241 26) standard/tiny
1242 3
1243 Do you need SMP support? (Y/n)
1244 Does your BSP have a touchscreen? (y/N)
1245 Does your BSP have a keyboard? (Y/n)
1246 New qemu BSP created in meta-myarm
1247 </literallayout>
1248 Let's take a closer look at the example now:
1249 <orderedlist>
1250 <listitem><para>For the <filename>qemu</filename> architecture,
1251 the script first prompts you for which emulated architecture to use.
1252 In the example, we use the <filename>arm</filename> architecture.
1253 </para></listitem>
1254 <listitem><para>The script then prompts you for the kernel.
1255 The default kernel is 3.2 and is acceptable.
1256 So, the example accepts the default.
1257 If you enter 'n', the script prompts you to further enter the kernel
1258 you do want to use (e.g. 3.0, 3.2_preempt-rt, etc.).</para></listitem>
1259 <listitem><para>Next, the script asks whether you would like to have a new
1260 branch created especially for your BSP in the local
1261 <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink>
1262 Git repository .
1263 If not, then the script re-uses an existing branch.</para>
1264 <para>In this example, the default (or 'yes') is accepted.
1265 Thus, a new branch is created for the BSP rather than using a common, shared
1266 branch.
1267 The new branch is the branch committed to for any patches you might later add.
1268 The reason a new branch is the default is that typically
1269 new BSPs do require BSP-specific patches.
1270 The tool thus assumes that most of time a new branch is required.
1271 <note>In the current implementation, creation or re-use of a branch does
1272 not actually matter.
1273 The reason is because the generated BSPs assume that patches and
1274 configurations live in recipe-space, which is something that can be done
1275 with or without a dedicated branch.
1276 Generated BSPs, however, are different.
1277 This difference becomes significant once the tool's 'publish' functionality
1278 is implemented.</note></para></listitem>
1279 <listitem><para>Regardless of which choice is made in the previous step,
1280 you are now given the opportunity to select a particular machine branch on
1281 which to base your new BSP-specific machine branch on
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
1284 uses <filename>#3</filename> at the prompt, which selects the arm-versatile branch.
1285 </para></listitem>
1286 <listitem><para>The remainder of the prompts are routine.
1287 Defaults are accepted for each.</para></listitem>
1288 <listitem><para>By default, the script creates the new BSP Layer in the
1289 <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-build-directory'>Yocto Project
1290 Build Directory</ulink>.</para></listitem>
1291 </orderedlist>
1292 </para>
1293
1294 <para>
1295 Once the BSP Layer is created, you must add it to your
1296 <filename>bblayers.conf</filename> file.
1297 Here is an example:
1298 <literallayout class='monospaced'>
1299 BBLAYERS = " \
1300 /usr/local/src/yocto/meta \
1301 /usr/local/src/yocto/meta-yocto \
1302 /usr/local/src/yocto/meta-myarm \
1303 "
1304 </literallayout>
1305 Adding the layer to this file allows the build system to build the BSP and
1306 the <filename>yocto-kernel</filename> tool to be able to find the layer and
1307 other metadata it needs on which to operate.
1308 </para>
1309 </section>
1310
1311 <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
1312 <title>Managing Kernel Patches and Config Items with yocto-kernel</title>
1313
1314 <para>
1315 Assuming you have created a Yocto Project
1316 <link linkend='bsp-layers'>BSP Layer</link> using
1317 <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
1318 <filename>yocto-bsp</filename></link> and you added it to your
1319 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
1320 variable in the <filename>bblayers.conf</filename> file, you can now use
1321 the <filename>yocto-kernel</filename> script to add patches and configuration
1322 items to the BSP's kernel.
1323 </para>
1324
1325 <para>
1326 The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
1327 and kernel config settings to a Yocto Project BSP's kernel
1328 <filename>.bbappend</filename> file.
1329 All you need to do is use the appropriate sub-command.
1330 Recall that the easiest way to see exactly what sub-commands are available
1331 is to use the <filename>yocto-kernel</filename> built-in help as follows:
1332 <literallayout class='monospaced'>
1333 $ yocto-kernel
1334 Usage:
1335
1336 Modify and list Yocto BSP kernel config items and patches.
1337
1338 usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
1339
1340 The most commonly used 'yocto-kernel' commands are:
1341 config list List the modifiable set of bare kernel config options for a BSP
1342 config add Add or modify bare kernel config options for a BSP
1343 config rm Remove bare kernel config options from a BSP
1344 patch list List the patches associated with a BSP
1345 patch add Patch the Yocto kernel for a BSP
1346 patch rm Remove patches from a BSP
1347
1348 See 'yocto-kernel help COMMAND' for more information on a specific command.
1349 </literallayout>
1350 </para>
1351
1352 <para>
1353 The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
1354 patch to a BSP.
1355 The following example adds two patches to the <filename>myarm</filename> BSP:
1356 <literallayout class='monospaced'>
1357 $ yocto-kernel patch add myarm ~/test.patch
1358 Added patches:
1359 test.patch
1360
1361 $ yocto-kernel patch add myarm ~/yocto-testmod.patch
1362 Added patches:
1363 yocto-testmod.patch
1364 </literallayout>
1365 <note>Although the previous example adds patches one at a time, it is possible
1366 to add multiple patches at the same time.</note>
1367 </para>
1368
1369 <para>
1370 You can verify patches have been added by using the
1371 <filename>yocto-kernel patch list</filename> sub-command.
1372 Here is an example:
1373 <literallayout class='monospaced'>
1374 $ yocto-kernel patch list myarm
1375 The current set of machine-specific patches for myarm is:
1376 1) test.patch
1377 2) yocto-testmod.patch
1378 </literallayout>
1379 </para>
1380
1381 <para>
1382 You can also use the <filename>yocto-kernel</filename> script to
1383 remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command.
1384 Here is an example:
1385 <literallayout class='monospaced'>
1386 $ yocto-kernel patch rm myarm
1387 Specify the patches to remove:
1388 1) test.patch
1389 2) yocto-testmod.patch
1390 1
1391 Removed patches:
1392 test.patch
1393 </literallayout>
1394 </para>
1395
1396 <para>
1397 Again, using the <filename>yocto-kernel patch list</filename> sub-command,
1398 you can verify that the patch was in fact removed:
1399 <literallayout class='monospaced'>
1400 $ yocto-kernel patch list myarm
1401 The current set of machine-specific patches for myarm is:
1402 1) yocto-testmod.patch
1403 </literallayout>
1404 </para>
1405
1406 <para>
1407 In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
1408 sub-command to add one or more kernel config item settings to a BSP.
1409 The following commands add a couple of config items to the
1410 <filename>myarm</filename> BSP:
1411 <literallayout class='monospaced'>
1412 $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
1413 Added items:
1414 CONFIG_MISC_DEVICES=y
1415
1416 $ yocto-kernel config add myarm KCONFIG_YOCTO_TESTMOD=y
1417 Added items:
1418 CONFIG_YOCTO_TESTMOD=y
1419 </literallayout>
1420 <note>Although the previous example adds config items one at a time, it is possible
1421 to add multiple config items at the same time.</note>
1422 </para>
1423
1424 <para>
1425 You can list the config items now associated with the BSP.
1426 Doing so shows you the config items you added as well as others associated
1427 with the BSP:
1428 <literallayout class='monospaced'>
1429 $ yocto-kernel config list myarm
1430 The current set of machine-specific kernel config items for myarm is:
1431 1) CONFIG_MISC_DEVICES=y
1432 2) CONFIG_YOCTO_TESTMOD=y
1433 </literallayout>
1434 </para>
1435
1436 <para>
1437 Finally, you can remove one or more config items using the
1438 <filename>yocto-kernel config rm</filename> sub-command in a manner
1439 completely analogous to <filename>yocto-kernel patch rm</filename>.
1440 </para>
1441 </section>
1442 </section>
688</chapter> 1443</chapter>