summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide/bsp.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-08-18 16:00:16 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-23 18:47:04 -0700
commit31d594802f4b3fb18ee64bc23427c9af8468b724 (patch)
treec72644a009246f2eb36efbe6f4b065bd03b16a34 /documentation/bsp-guide/bsp.xml
parent8fd890a8ec389fe21d4dc51335a0c4261d59579a (diff)
downloadpoky-31d594802f4b3fb18ee64bc23427c9af8468b724.tar.gz
documentation/bsp-guide/bsp.xml: General updates
I added a parallel textual construct at the beginning of each section that details a directory in the Yocto Project file's structure. I did not like starting these sections with a literallayout string. (From yocto-docs rev: 5dde476f0c02d655217f3fa863522e8b7df57cda) 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/bsp.xml')
-rw-r--r--documentation/bsp-guide/bsp.xml388
1 files changed, 159 insertions, 229 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index c7f9f87d4b..492a7956d2 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -3,7 +3,7 @@
3 3
4<chapter id='bsp'> 4<chapter id='bsp'>
5 5
6 <title>Board Support Packages (BSP) - Developers Guide</title> 6 <title>Board Support Packages (BSP) - Developer's Guide</title>
7 7
8 <para> 8 <para>
9 A Board Support Package (BSP) is a collection of information that 9 A Board Support Package (BSP) is a collection of information that
@@ -27,12 +27,12 @@
27 of software support of hardware. 27 of software support of hardware.
28 </para> 28 </para>
29 29
30 <note><para> 30 <note>
31 The information here does not provide an example of how to create a BSP. 31 The information here does not provide an example of how to create a BSP.
32 For information on how to create a BSP, see the Yocto Project Development Manual or the 32 For information on how to create a BSP, see the Yocto Project Development Manual or the
33 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'></ulink> 33 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'></ulink>
34 wiki page. 34 wiki page.
35 </para></note> 35 </note>
36 36
37 <para> 37 <para>
38 The proposed format does have elements that are specific to the Yocto Project and 38 The proposed format does have elements that are specific to the Yocto Project and
@@ -81,8 +81,11 @@
81 81
82 <para> 82 <para>
83 The base directory (<filename>meta-&lt;bsp_name&gt;</filename>) is the root of the BSP layer. 83 The base directory (<filename>meta-&lt;bsp_name&gt;</filename>) is the root of the BSP layer.
84 This root is what you add to the BBLAYERS variable in <filename>build/conf/bblayers.conf</filename> 84 This root is what you add to the <filename>BBLAYERS</filename>
85 so that the build system recognizes the BSP definition and from it can build an image. 85 variable in the <filename>build/conf/bblayers.conf</filename> file found in the
86 Yocto Project file's build directory.
87 Adding the root allows the Yocto Project build system to recognize the BSP
88 definition and from it build an image.
86 Here is an example: 89 Here is an example:
87 <literallayout class='monospaced'> 90 <literallayout class='monospaced'>
88 BBLAYERS = " \ 91 BBLAYERS = " \
@@ -94,6 +97,9 @@
94 For more detailed information on layers, see the 97 For more detailed information on layers, see the
95 <ulink url='http://www.yoctoproject.org/docs/poky-ref-manual/poky-ref-manual.html#usingpoky-changes-layers'> 98 <ulink url='http://www.yoctoproject.org/docs/poky-ref-manual/poky-ref-manual.html#usingpoky-changes-layers'>
96 BitBake Layers</ulink> section of the Yocto Project Reference Manual. 99 BitBake Layers</ulink> section of the Yocto Project Reference Manual.
100 You can also see the detailed examples in the appendices of
101 <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>
102 The Yocto Project Development Manual</ulink>.
97 </para> 103 </para>
98 104
99 <para> 105 <para>
@@ -101,41 +107,41 @@
101 While you can use this basic form for the standard, realize that the actual structures 107 While you can use this basic form for the standard, realize that the actual structures
102 for specific BSPs could differ. 108 for specific BSPs could differ.
103 109
104 <programlisting> 110 <literallayout class='monospaced'>
105meta-&lt;bsp_name&gt;/ 111 meta-&lt;bsp_name&gt;/
106meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt; 112 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
107meta-&lt;bsp_name&gt;/README 113 meta-&lt;bsp_name&gt;/README
108meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt; 114 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
109meta-&lt;bsp_name&gt;/conf/layer.conf 115 meta-&lt;bsp_name&gt;/conf/layer.conf
110meta-&lt;bsp_name&gt;/conf/machine/*.conf 116 meta-&lt;bsp_name&gt;/conf/machine/*.conf
111meta-&lt;bsp_name&gt;/recipes-bsp/* 117 meta-&lt;bsp_name&gt;/recipes-bsp/*
112meta-&lt;bsp_name&gt;/recipes-graphics/* 118 meta-&lt;bsp_name&gt;/recipes-graphics/*
113meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_git.bbappend 119 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_git.bbappend
114 </programlisting> 120 </literallayout>
115 </para> 121 </para>
116 122
117 <para> 123 <para>
118 Below is an example of the crownbay BSP: 124 Below is an example of the Crownbay BSP:
119 125
120 <programlisting> 126 <literallayout class='monospaced'>
121meta-crownbay/COPYING.MIT 127 meta-crownbay/COPYING.MIT
122meta-crownbay/README 128 meta-crownbay/README
123meta-crownbay/binary/.gitignore 129 meta-crownbay/binary/.gitignore
124meta-crownbay/conf/layer.conf 130 meta-crownbay/conf/layer.conf
125meta-crownbay/conf/machine/crownbay.conf 131 meta-crownbay/conf/machine/crownbay.conf
126meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig 132 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
127meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend 133 meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
128meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf 134 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf
129meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend 135 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
130meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore 136 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore
131meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb 137 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb
132meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch 138 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch
133meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch 139 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch
134meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch 140 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch
135meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch 141 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch
136meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb 142 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb
137meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend 143 meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend
138 </programlisting> 144 </literallayout>
139 </para> 145 </para>
140 146
141 <para> 147 <para>
@@ -144,14 +150,18 @@ meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend
144 150
145 <section id="bsp-filelayout-license"> 151 <section id="bsp-filelayout-license">
146 <title>License Files</title> 152 <title>License Files</title>
147 <programlisting> 153
148meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt; 154 <para>
149 </programlisting> 155 You can find these files in the Yocto Project file's directory structure at:
156 <literallayout class='monospaced'>
157 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
158 </literallayout>
159 </para>
150 160
151 <para> 161 <para>
152 These optional files satisfy licensing requirements for the BSP. 162 These optional files satisfy licensing requirements for the BSP.
153 The type or types of files here can vary depending on the licensing requirements. 163 The type or types of files here can vary depending on the licensing requirements.
154 For example, in the crownbay BSP all licensing requirements are handled with the 164 For example, in the Crownbay BSP all licensing requirements are handled with the
155 <filename>COPYING.MIT</filename> file. 165 <filename>COPYING.MIT</filename> file.
156 </para> 166 </para>
157 167
@@ -163,9 +173,12 @@ meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
163 173
164 <section id="bsp-filelayout-readme"> 174 <section id="bsp-filelayout-readme">
165 <title>README File</title> 175 <title>README File</title>
166 <programlisting> 176 <para>
167meta-&lt;bsp_name&gt;/README 177 You can find these files in the Yocto Project file's directory structure at:
168 </programlisting> 178 <literallayout class='monospaced'>
179 meta-&lt;bsp_name&gt;/README
180 </literallayout>
181 </para>
169 182
170 <para> 183 <para>
171 This file provides information on how to boot the live images that are optionally 184 This file provides information on how to boot the live images that are optionally
@@ -182,9 +195,12 @@ meta-&lt;bsp_name&gt;/README
182 195
183 <section id="bsp-filelayout-binary"> 196 <section id="bsp-filelayout-binary">
184 <title>Pre-built User Binaries</title> 197 <title>Pre-built User Binaries</title>
185 <programlisting> 198 <para>
186meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt; 199 You can find these files in the Yocto Project file's directory structure at:
187 </programlisting> 200 <literallayout class='monospaced'>
201 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
202 </literallayout>
203 </para>
188 204
189 <para> 205 <para>
190 This optional area contains useful pre-built kernels and user-space filesystem 206 This optional area contains useful pre-built kernels and user-space filesystem
@@ -206,9 +222,12 @@ meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
206 222
207 <section id='bsp-filelayout-layer'> 223 <section id='bsp-filelayout-layer'>
208 <title>Layer Configuration File</title> 224 <title>Layer Configuration File</title>
209 <programlisting> 225 <para>
210meta-&lt;bsp_name&gt;/conf/layer.conf 226 You can find these files in the Yocto Project file's directory structure at:
211 </programlisting> 227 <literallayout class='monospaced'>
228 meta-&lt;bsp_name&gt;/conf/layer.conf
229 </literallayout>
230 </para>
212 231
213 <para> 232 <para>
214 This file identifies the structure as a Yocto Project layer, identifies the 233 This file identifies the structure as a Yocto Project layer, identifies the
@@ -219,18 +238,18 @@ meta-&lt;bsp_name&gt;/conf/layer.conf
219 </para> 238 </para>
220 239
221 <para> 240 <para>
222 <programlisting> 241 <literallayout class='monospaced'>
223# We have a conf directory, add to BBPATH 242 # We have a conf directory, add to BBPATH
224BBPATH := "${BBPATH}:${LAYERDIR}" 243 BBPATH := "${BBPATH}:${LAYERDIR}"
225 244
226# We have a recipes directory containing .bb and .bbappend files, add to BBFILES 245 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
227BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ 246 BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \
228 ${LAYERDIR}/recipes/*/*.bbappend" 247 ${LAYERDIR}/recipes/*/*.bbappend"
229 248
230BBFILE_COLLECTIONS += "bsp" 249 BBFILE_COLLECTIONS += "bsp"
231BBFILE_PATTERN_bsp := "^${LAYERDIR}/" 250 BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
232BBFILE_PRIORITY_bsp = "5" 251 BBFILE_PRIORITY_bsp = "5"
233 </programlisting> 252 </literallayout>
234 </para> 253 </para>
235 254
236 <para> 255 <para>
@@ -241,9 +260,12 @@ BBFILE_PRIORITY_bsp = "5"
241 260
242 <section id="bsp-filelayout-machine"> 261 <section id="bsp-filelayout-machine">
243 <title>Hardware Configuration Options</title> 262 <title>Hardware Configuration Options</title>
244 <programlisting> 263 <para>
245meta-&lt;bsp_name&gt;/conf/machine/*.conf 264 You can find these files in the Yocto Project file's directory structure at:
246 </programlisting> 265 <literallayout class='monospaced'>
266 meta-&lt;bsp_name&gt;/conf/machine/*.conf
267 </literallayout>
268 </para>
247 269
248 <para> 270 <para>
249 The machine files bind together all the information contained elsewhere 271 The machine files bind together all the information contained elsewhere
@@ -272,10 +294,10 @@ meta-&lt;bsp_name&gt;/conf/machine/*.conf
272 An example is <filename>tune-atom.inc</filename>: 294 An example is <filename>tune-atom.inc</filename>:
273 </para> 295 </para>
274 <para> 296 <para>
275 <programlisting> 297 <literallayout class='monospaced'>
276BASE_PACKAGE_ARCH = "core2" 298 BASE_PACKAGE_ARCH = "core2"
277TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" 299 TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
278 </programlisting> 300 </literallayout>
279 </para> 301 </para>
280 <para> 302 <para>
281 This example defines a new package architecture called "core2" and uses the 303 This example defines a new package architecture called "core2" and uses the
@@ -294,19 +316,22 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
294 316
295 <section id='bsp-filelayout-misc-recipes'> 317 <section id='bsp-filelayout-misc-recipes'>
296 <title>Miscellaneous Recipe Files</title> 318 <title>Miscellaneous Recipe Files</title>
297 <programlisting> 319 <para>
298meta-&lt;bsp_name&gt;/recipes-bsp/* 320 You can find these files in the Yocto Project file's directory structure at:
299 </programlisting> 321 <literallayout class='monospaced'>
322 meta-&lt;bsp_name&gt;/recipes-bsp/*
323 </literallayout>
324 </para>
300 325
301 <para> 326 <para>
302 This optional directory contains miscellaneous recipe files for the BSP. 327 This optional directory contains miscellaneous recipe files for the BSP.
303 Most notably would be the formfactor files. 328 Most notably would be the formfactor files.
304 For example, in the crownbay BSP there is a <filename>machconfig</filename> file and a 329 For example, in the Crownbay BSP there is a <filename>machconfig</filename> file and a
305 <filename>formfactor_0.0.bbappend</filename> file: 330 <filename>formfactor_0.0.bbappend</filename> file:
306 <programlisting> 331 <literallayout class='monospaced'>
307meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig 332 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
308meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend 333 meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
309 </programlisting> 334 </literallayout>
310 </para> 335 </para>
311 336
312 <note><para> 337 <note><para>
@@ -317,34 +342,40 @@ meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
317 342
318 <section id='bsp-filelayout-recipes-graphics'> 343 <section id='bsp-filelayout-recipes-graphics'>
319 <title>Display Support Files</title> 344 <title>Display Support Files</title>
320 <programlisting> 345 <para>
321meta-&lt;bsp_name&gt;/recipes-graphics/* 346 You can find these files in the Yocto Project file's directory structure at:
322 </programlisting> 347 <literallayout class='monospaced'>
348 meta-&lt;bsp_name&gt;/recipes-graphics/*
349 </literallayout>
350 </para>
323 351
324 <para> 352 <para>
325 This optional directory contains recipes for the BSP if it has 353 This optional directory contains recipes for the BSP if it has
326 special requirements for graphics support. 354 special requirements for graphics support.
327 All files that are needed for the BSP to support a display are kept here. 355 All files that are needed for the BSP to support a display are kept here.
328 For example, in the crownbay BSP several display support files exist: 356 For example, in the Crownbay BSP several display support files exist:
329 <programlisting> 357 <literallayout class='monospaced'>
330meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf 358 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf
331meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend 359 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
332meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore 360 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore
333meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb 361 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb
334meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch 362 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch
335meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch 363 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch
336meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch 364 eta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch
337meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch 365 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch
338meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb 366 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb
339 </programlisting> 367 </literallayout>
340 </para> 368 </para>
341 </section> 369 </section>
342 370
343 <section id='bsp-filelayout-kernel'> 371 <section id='bsp-filelayout-kernel'>
344 <title>Linux Kernel Configuration</title> 372 <title>Linux Kernel Configuration</title>
345 <programlisting> 373 <para>
346meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_git.bbappend 374 You can find these files in the Yocto Project file's directory structure at:
347 </programlisting> 375 <literallayout class='monospaced'>
376 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_git.bbappend
377 </literallayout>
378 </para>
348 379
349 <para> 380 <para>
350 This file appends your specific changes to the kernel you are using. 381 This file appends your specific changes to the kernel you are using.
@@ -362,25 +393,25 @@ meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_git.bbappend
362 which is the preferred kernel to use for developing a new BSP using the Yocto Project. 393 which is the preferred kernel to use for developing a new BSP using the Yocto Project.
363 In other words, you have selected the kernel in your 394 In other words, you have selected the kernel in your
364 <filename>&lt;bsp_name&gt;.conf</filename> file by adding the following statement: 395 <filename>&lt;bsp_name&gt;.conf</filename> file by adding the following statement:
365 <programlisting> 396 <literallayout class='monospaced'>
366PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 397 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
367 </programlisting> 398 </literallayout>
368 You would use the <filename>linux-yocto_git.bbappend</filename> file to append 399 You would use the <filename>linux-yocto_git.bbappend</filename> file to append
369 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. 400 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.
370 </para> 401 </para>
371 <para> 402 <para>
372 Now take a look at the existing "crownbay" BSP. 403 Now take a look at the existing Crownbay BSP.
373 The append file used is: 404 The append file used is:
374 <programlisting> 405 <literallayout class='monospaced'>
375meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend 406 meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend
376 </programlisting> 407 </literallayout>
377 The file contains the following: 408 The file contains the following:
378 <programlisting> 409 <literallayout class='monospaced'>
379FILESEXTRAPATHS := "${THISDIR}/${PN}" 410 FILESEXTRAPATHS := "${THISDIR}/${PN}"
380COMPATIBLE_MACHINE_crownbay = "crownbay" 411 COMPATIBLE_MACHINE_crownbay = "crownbay"
381KMACHINE_crownbay = "yocto/standard/crownbay" 412 KMACHINE_crownbay = "yocto/standard/crownbay"
382 </programlisting> 413 </literallayout>
383 This append file adds "crownbay" as a compatible machine, 414 This append file adds Crownbay as a compatible machine,
384 and additionally sets a Yocto Kernel-specific variable that identifies the name of the 415 and additionally sets a Yocto Kernel-specific variable that identifies the name of the
385 BSP branch to use in the Git repository to find configuration information. 416 BSP branch to use in the Git repository to find configuration information.
386 </para> 417 </para>
@@ -402,9 +433,9 @@ KMACHINE_crownbay = "yocto/standard/crownbay"
402 <filename class='directory'>/linux-yocto</filename> and then added 433 <filename class='directory'>/linux-yocto</filename> and then added
403 a SRC_URI statement such as the following to the append file, those configuration 434 a SRC_URI statement such as the following to the append file, those configuration
404 options will be picked up and applied when the kernel is built. 435 options will be picked up and applied when the kernel is built.
405 <programlisting> 436 <literallayout class='monospaced'>
406SRC_URI += "file://defconfig" 437 SRC_URI += "file://defconfig"
407 </programlisting> 438 </literallayout>
408 </para> 439 </para>
409 <para> 440 <para>
410 As mentioned earlier, you can group related configurations into multiple files and 441 As mentioned earlier, you can group related configurations into multiple files and
@@ -412,18 +443,19 @@ SRC_URI += "file://defconfig"
412 For example, you could group separate configurations specifically for Ethernet and graphics 443 For example, you could group separate configurations specifically for Ethernet and graphics
413 into their own files and add those by using a SRC_URI statement like the 444 into their own files and add those by using a SRC_URI statement like the
414 following in your append file: 445 following in your append file:
415 <programlisting> 446 <literallayout class='monospaced'>
416SRC_URI += "file://defconfig \ 447 SRC_URI += "file://defconfig \
417 file://eth.cfg \ 448 file://eth.cfg \
418 file://gfx.cfg" 449 file://gfx.cfg"
419 </programlisting> 450 </literallayout>
420 </para> 451 </para>
421 <para> 452 <para>
422 The FILESEXTRAPATHS variable is in boilerplate form here in order to make it easy 453 The FILESEXTRAPATHS variable is in boilerplate form here in order to make it easy
423 to do that. 454 to do that.
424 It basically allows those configuration files to be found by the build process. 455 It basically allows those configuration files to be found by the build process.
425 </para> 456 </para>
426 <note><para> 457 <note>
458 <para>
427 Other methods exist to accomplish grouping and defining configuration options. 459 Other methods exist to accomplish grouping and defining configuration options.
428 For example, you could directly add configuration options to the Yocto kernel 460 For example, you could directly add configuration options to the Yocto kernel
429 <filename class='directory'>meta</filename> branch for your BSP. 461 <filename class='directory'>meta</filename> branch for your BSP.
@@ -432,116 +464,26 @@ SRC_URI += "file://defconfig \
432 For information on how to add these configurations directly, see the 464 For information on how to add these configurations directly, see the
433 "Yocto Project Kernel Architecture and Use Manual" on the 465 "Yocto Project Kernel Architecture and Use Manual" on the
434 <ulink url="http://yoctoproject.org/community/documentation">Yocto Project website 466 <ulink url="http://yoctoproject.org/community/documentation">Yocto Project website
435 Documentation Page</ulink> 467 Documentation Page</ulink></para>
436 </para> 468 <para>
437 <para>
438 In general, however, the Yocto Project maintainers take care of moving the SRC_URI-specified 469 In general, however, the Yocto Project maintainers take care of moving the SRC_URI-specified
439 configuration options to the <filename class='directory'>meta</filename> branch. 470 configuration options to the <filename class='directory'>meta</filename> branch.
440 Not only is it easier for BSP developers to not have to worry about putting those 471 Not only is it easier for BSP developers to not have to worry about putting those
441 configurations in the branch, but having the maintainers do it allows them to apply 472 configurations in the branch, but having the maintainers do it allows them to apply
442 'global' knowledge about the kinds of common configuration options multiple BSPs in 473 'global' knowledge about the kinds of common configuration options multiple BSPs in
443 the tree are typically using. 474 the tree are typically using.
444 This allows for promotion of common configurations into common features. 475 This allows for promotion of common configurations into common features.</para>
445 </para></note> 476 </note>
446 </section>
447
448<!-- <section id='bsp-filelayout-packages'>
449 <title>Other Software (meta-&lt;bsp_name&gt;/recipes-kernel/*)</title>
450
451 <para>
452 This section describes other pieces of software that the hardware might need for best
453 operation.
454 Examples show some of the things you could encounter.
455 The examples are standard <filename>.bb</filename> file recipes in the
456 usual Poky format.
457 You can include the source directly by referring to it in the source control system or
458 the released tarballs of external software projects.
459 You only need to provide these types of files if the platform requires them.
460 </para>
461 <para>
462 The following file is a bootloader recipe that can be used to generate a new
463 bootloader binary.
464 Sometimes these files are included in the final image format and are needed to re-flash hardware.
465 </para>
466 <para>
467 <programlisting>
468meta-Emenlow/recipes-kernel/bootloader/bootloader_0.1.bb
469 </programlisting>
470 </para>
471 <para>
472 These next two files are examples of a hardware driver and a hardware daemon that might need
473 to be included in images to make the hardware useful.
474 Although the example uses "modem" there may be other components needed, such as firmware.
475 </para>
476 <para>
477 <programlisting>
478meta-Emenlow/recipes-Emenlow/modem/modem-driver_0.1.bb
479meta-Emenlow/recipes-Emenlow/modem/modem-daemon_0.1.bb
480 </programlisting>
481 </para>
482 <para>
483 Sometimes the device needs an image in a very specific format so that the update
484 mechanism can accept and re-flash it.
485 Recipes to build the tools needed to do this can be included with the BSP.
486 Following is an example.
487 </para>
488 <para>
489 <programlisting>
490meta-Emenlow/recipes-Emenlow/image-creator/image-creator-native_0.1.bb
491 </programlisting>
492 </para>
493 </section>
494
495 <section id='bs-filelayout-bbappend'>
496 <title>Append BSP-Specific Information to Existing Recipes</title>
497 <para>
498 Suppose you have a recipe such as "pointercal" that requires machine-specific information.
499 At the same time, you have your new BSP code nicely partitioned into a layer through which
500 you would also like to specify any machine-specific information associated with your new machine.
501 Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole
502 pointercal recipe and files into your layer and then add the single file for your machine.
503 </para>
504 <para>
505 With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
506 This extension allows you to easily merge BSP-specific information with the original recipe.
507 Whenever BitBake finds any <filename>.bbappend</filename> files BitBake will include them after
508 it loads the associated <filename>.bb</filename> file but before any finalize
509 or anonymous methods are run.
510 This allows the BSP layer to do whatever it might want to do to customize the original recipe.
511 </para>
512 <para>
513 If your recipe needs to reference extra files it can use the FILESEXTRAPATHS variable
514 to specify their location.
515 The example below shows extra files contained in a folder called ${PN} (the package name).
516 </para>
517 <programlisting>
518FILESEXTRAPATHS := "${THISDIR}/${PN}"
519 </programlisting>
520 <para>
521 This technique allows the BSP to add machine-specific configuration files to the layer directory,
522 which will be picked up by BitBake.
523 For an example see <filename>meta-emenlow/packages/formfactor</filename>.
524 </para>
525 </section> 477 </section>
526
527 <section id="bsp-filelayout-prebuilds">
528 <title>Pre-build Data (meta-&lt;bsp_name&gt;/prebuilds/*)</title>
529 <para>
530 This location can contain precompiled representations of the source code
531 contained elsewhere in the BSP layer.
532 Assuming a compatible configuration is used, Poky can process and use these optional pre-compiled
533 representations to provide much faster build times.
534 </para>
535 </section> -->
536 </section> 478 </section>
537 479
538 <section id='bsp-click-through-licensing'> 480 <section id='bsp-click-through-licensing'>
539 <title>BSP 'Click-Through' Licensing Procedure</title> 481 <title>BSP 'Click-Through' Licensing Procedure</title>
540 482
541 <note><para> This section describes how 483 <note> This section describes how
542 click-through licensing is expected to work. 484 click-through licensing is expected to work.
543 Currently, this functionality is not yet implemented. 485 Currently, this functionality is not yet implemented.
544 </para></note> 486 </note>
545 487
546 <para> 488 <para>
547 In some cases, a BSP contains separately licensed IP 489 In some cases, a BSP contains separately licensed IP
@@ -595,19 +537,6 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
595 through a web form. 537 through a web form.
596 </para> 538 </para>
597 539
598<!--
599 <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
600 and give the name of the BSP and your e-mail address in the web form.
601 </para>
602
603 COMMENT: This link is not implemented at this point.
604
605 <programlisting>
606 [screenshot of dialog box]
607 </programlisting>
608
609-->
610
611 <para> 540 <para>
612 After agreeing to any applicable license terms, the 541 After agreeing to any applicable license terms, the
613 BSP key(s) will be immediately sent to the address 542 BSP key(s) will be immediately sent to the address
@@ -615,9 +544,9 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
615 environment variables when building the image: 544 environment variables when building the image:
616 </para> 545 </para>
617 546
618 <programlisting> 547 <literallayout class='monospaced'>
619 $ BSPKEY_&lt;keydomain&gt;=&lt;key&gt; bitbake core-image-sato 548 $ BSPKEY_&lt;keydomain&gt;=&lt;key&gt; bitbake core-image-sato
620 </programlisting> 549 </literallayout>
621 550
622 <para> 551 <para>
623 These steps allow the encumbered image to be built 552 These steps allow the encumbered image to be built
@@ -627,7 +556,8 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
627 <para> 556 <para>
628 Equivalently and probably more conveniently, a line 557 Equivalently and probably more conveniently, a line
629 for each key can instead be put into the user's 558 for each key can instead be put into the user's
630 <filename>local.conf</filename> file. 559 <filename>local.conf</filename> file found in the Yocto Project file's
560 build directory.
631 </para> 561 </para>
632 562
633 <para> 563 <para>