summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide/bsp.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2010-12-13 16:21:12 -0800
committerSaul Wold <sgw@linux.intel.com>2010-12-14 13:43:55 -0800
commit27c117141f0189332d9bc66fd371ed178428626e (patch)
tree9eb1032e085c2357a67970a0327d1d82ef39e6bf /documentation/bsp-guide/bsp.xml
parente7f5bc2504f33570b2f42ca95668590b00f040de (diff)
downloadpoky-27c117141f0189332d9bc66fd371ed178428626e.tar.gz
documentation/bsp-guide/bsp.xml: General edits.
1. Edited to incorporate new file system naming structure per Saul Wold. This is the version I am sending him and Tom Z. to review. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Conflicts: documentation/bsp-guide/bsp.xml Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Diffstat (limited to 'documentation/bsp-guide/bsp.xml')
-rw-r--r--documentation/bsp-guide/bsp.xml185
1 files changed, 91 insertions, 94 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index ecf64319fd..3cad0fd010 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -55,27 +55,37 @@
55 <title>Example Filesystem Layout</title> 55 <title>Example Filesystem Layout</title>
56 56
57 <para> 57 <para>
58 The BSP consists of a file structure inside a base directory, meta-bsp in this example, 58 The BSP consists of a file structure inside a base directory, which uses the following
59 where "bsp" is a placeholder for the machine or platform name. 59 naming convention:
60 Examples of some files that it could contain are: 60 <literallayout class='monospaced'>
61 </para> 61 meta-&lt;bsp_name&gt;
62 62 </literallayout>
63 <para> 63 "bsp_name" is a placeholder for the machine or platform name.
64 Here are some example base directory names:
65 <literallayout class='monospaced'>
66 meta-Emenlow
67 meta-intel_n450
68 meta-oaktrail
69 </literallayout>
70 </para>
71
72 <para>
73 The file structure inside the base directory takes on the following form:
64 <programlisting> 74 <programlisting>
65meta-bsp/ 75meta-&lt;bsp_name&gt;/
66meta-bsp/binary/zImage 76meta-&lt;bsp_name&gt;/binary/zImage
67meta-bsp/binary/poky-image-minimal.directdisk 77meta-&lt;bsp_name&gt;/binary/poky-image-minimal.directdisk
68meta-bsp/conf/layer.conf 78meta-&lt;bsp_name&gt;/conf/layer.conf
69meta-bsp/conf/machine/*.conf 79meta-&lt;bsp_name&gt;/conf/machine/*.conf
70meta-bsp/conf/machine/include/tune-*.inc 80meta-&lt;bsp_name&gt;/conf/machine/include/tune-*.inc
71meta-bsp/packages/bootloader/bootloader_0.1.bb 81meta-&lt;bsp_name&gt;/recipes-kernel/bootloader/bootloader_0.1.bb
72meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch 82meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-bsp-2.6.50/*.patch
73meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp 83meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-bsp-2.6.50/defconfig-bsp
74meta-bsp/packages/linux/linux-bsp_2.6.50.bb 84meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-bsp_2.6.50.bb
75meta-bsp/packages/modem/modem-driver_0.1.bb 85meta-&lt;bsp_name&gt;/recipes-&lt;bsp_name&gt;/modem/modem-driver_0.1.bb
76meta-bsp/packages/modem/modem-daemon_0.1.bb 86meta-&lt;bsp_name&gt;/recipes-&lt;bsp_name&gt;/modem/modem-daemon_0.1.bb
77meta-bsp/packages/image-creator/image-creator-native_0.1.bb 87meta-&lt;bsp_name&gt;/recipes-&lt;bsp_name&gt;/image-creator/image-creator-native_0.1.bb
78meta-bsp/prebuilds/ 88meta-&lt;bsp_name&gt;/prebuilds/
79 </programlisting> 89 </programlisting>
80 </para> 90 </para>
81 91
@@ -86,32 +96,29 @@ meta-bsp/prebuilds/
86 </section> 96 </section>
87 97
88 <section id="bsp-filelayout-binary"> 98 <section id="bsp-filelayout-binary">
89 <title>Prebuilt User Binaries (meta-bsp/binary/*)</title> 99 <title>Pre-built User Binaries (meta-&lt;bsp_name&gt;/binary/*)</title>
90 100
91 <para> 101 <para>
92 This optional area contains useful prebuilt kernels and userspace filesystem 102 This optional area contains useful pre-built kernels and userspace filesystem
93 images appropriate to the target system. 103 images appropriate to the target system.
94 Users could use these to get a system 104 You can use these kernels and images to get a system running and quickly get started
95 running and quickly get started on development tasks. 105 on development tasks.
96 The exact types of binaries 106 The exact types of binaries present are highly hardware-dependent.
97 present are highly hardware-dependent. 107 However, a README file should be present that explains how to use the kernels and
98 However, a README file should be present 108 images with the target hardware.
99 that explains how to use them with the target hardware. 109 If pre-built binaries are present, source code to meet licensing requirements must also
100 If prebuilt binaries are 110 be provided in some form.
101 present, source code to meet licensing requirements must also be provided in 111 </para>
102 some form.
103 </para>
104
105 </section> 112 </section>
106 113
107 <section id='bsp-filelayout-layer'> 114 <section id='bsp-filelayout-layer'>
108 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title> 115 <title>Layer Configuration (meta-&lt;bsp_name&gt;/conf/layer.conf)</title>
109 116
110 <para> 117 <para>
111 This file identifies the structure as a Poky layer, identifies the 118 This file identifies the structure as a Poky layer, identifies the
112 contents of the layer and contains information about how Poky should use 119 contents of the layer, and contains information about how Poky should use
113 it. 120 it.
114 Generally, a standard boilerplate file consisting of the following works. 121 Generally, a standard boilerplate file such as the following works:
115 </para> 122 </para>
116 123
117 <para> 124 <para>
@@ -129,26 +136,25 @@ BBFILE_PRIORITY_bsp = "5"
129 </para> 136 </para>
130 137
131 <para> 138 <para>
132 This file simply makes bitbake aware of the recipes and conf directories and is required 139 This file simply makes BitBake aware of the recipes and configuration directories.
133 for recognition of the BSP by Poky. 140 This file must exist so that Poky can recognize the BSP.
134 </para> 141 </para>
135
136 </section> 142 </section>
137 143
138 <section id="bsp-filelayout-machine"> 144 <section id="bsp-filelayout-machine">
139 <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title> 145 <title>Hardware Configuration Options (meta-&lt;bsp_name&gt;/conf/machine/*.conf)</title>
140 146
141 <para> 147 <para>
142 The machine files bind together all the information contained elsewhere 148 The machine files bind together all the information contained elsewhere
143 in the BSP into a format that Poky/OpenEmbedded can understand. 149 in the BSP into a format that Poky can understand.
144 If the BSP supports multiple machines, multiple machine configuration files 150 If the BSP supports multiple machines, multiple machine configuration files
145 can be present. 151 can be present.
146 These filenames correspond to the values to which users have set the MACHINE variable. 152 These filenames correspond to the values to which users have set the MACHINE variable.
147 </para> 153 </para>
148 154
149 <para> 155 <para>
150 These files define things such as what kernel package to use 156 These files define things such as the kernel package to use
151 (PREFERRED_PROVIDER of virtual/kernel), what hardware drivers to 157 (PREFERRED_PROVIDER of virtual/kernel), the hardware drivers to
152 include in different types of images, any special software components 158 include in different types of images, any special software components
153 that are needed, any bootloader information, and also any special image 159 that are needed, any bootloader information, and also any special image
154 format requirements. 160 format requirements.
@@ -158,22 +164,21 @@ BBFILE_PRIORITY_bsp = "5"
158 At least one machine file is required for a Poky BSP layer. 164 At least one machine file is required for a Poky BSP layer.
159 However, you can supply more than one file. 165 However, you can supply more than one file.
160 </para> 166 </para>
161
162 </section> 167 </section>
163 168
164 <section id="bsp-filelayout-tune"> 169 <section id="bsp-filelayout-tune">
165 <title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title> 170 <title>Hardware Optimization Options (meta-&lt;bsp_name&gt;/conf/machine/include/tune-*.inc)</title>
166 171
167 <para> 172 <para>
168 These are shared hardware "tuning" definitions and are commonly used to 173 These files are shared hardware "tuning" definitions and are commonly used to
169 pass specific optimization flags to the compiler. 174 pass specific optimization flags to the compiler.
170 An example is tune-atom.inc: 175 An example is <filename>tune-atom.inc</filename>:
171 </para> 176 </para>
172 <para> 177 <para>
173 <programlisting> 178 <programlisting>
174BASE_PACKAGE_ARCH = "core2" 179BASE_PACKAGE_ARCH = "core2"
175TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" 180TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
176 </programlisting> 181 </programlisting>
177 </para> 182 </para>
178 <para> 183 <para>
179 This example defines a new package architecture called "core2" and uses the 184 This example defines a new package architecture called "core2" and uses the
@@ -191,59 +196,58 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
191 </section> 196 </section>
192 197
193 <section id='bsp-filelayout-kernel'> 198 <section id='bsp-filelayout-kernel'>
194 <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title> 199 <title>Linux Kernel Configuration (meta-&lt;bsp_name&gt;/recipes-kernel/linux/*)</title>
195 200
196 <para> 201 <para>
197 These files make up the definition of a kernel to use with this 202 These files make up the definition of a kernel to use with this hardware.
198 hardware.
199 In this case, it is a complete self-contained kernel with its own 203 In this case, it is a complete self-contained kernel with its own
200 configuration and patches. 204 configuration and patches.
201 However, kernels can be shared between many machines as well. 205 However, kernels can be shared between many machines as well.
202 Following is an example: 206 Following is an example:
203 <programlisting> 207 <programlisting>
204meta-bsp/packages/linux/linux-bsp_2.6.50.bb 208meta-Emenlow/recipes-kernel/linux/linux-bsp_2.6.50.bb
205 </programlisting> 209 </programlisting>
206 This example file is the core kernel recipe that details from where to get the kernel 210 This example file is the core kernel recipe that details from where to get the kernel
207 source. 211 source.
208 All standard source code locations are supported so this could 212 All standard source code locations are supported.
209 be a release tarball, some git repository, or source included in 213 Consequently, the source could be a release tarball, a git repository, or source included in
210 the directory within the BSP itself. 214 the directory within the BSP itself.
211 </para> 215 </para>
212 <para> 216 <para>
213 The file then contains information about what patches to apply and how to configure and build them. 217 The file then contains information about what patches to apply and how to configure and build them.
214 It can reuse the main Poky kernel build class, so the definitions here can remain very simple. 218 Because the file can reuse the main Poky kernel build class, the definitions here can
219 remain very simple.
215 </para> 220 </para>
216 <para> 221 <para>
217 <programlisting> 222 <programlisting>
218linux-bsp-2.6.50/*.patch 223linux-bsp-2.6.50/*.patch
219 </programlisting> 224 </programlisting>
220 </para> 225 </para>
221 <para> 226 <para>
222 The above example file contains patches you can apply against the base kernel, from wherever 227 The above example file contains patches you can apply against the base kernel, from wherever
223 they may have been obtained. 228 they may have been obtained.
224 </para> 229 </para>
225 <para> 230 <para>
226 <programlisting> 231 <programlisting>
227meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp 232meta-Emenlow/recipes-kernel/linux/linux-bsp-2.6.50/defconfig-bsp
228 </programlisting> 233 </programlisting>
229 </para> 234 </para>
230 <para> 235 <para>
231 Finally, this last example file contains kernel configuration information. 236 Finally, this last example file contains kernel configuration information.
232 </para> 237 </para>
233 <para> 238 <para>
234 Examples of kernel recipes are available in Poky itself. 239 Examples of kernel recipes are available in Poky itself, and thus, make these files optional.
235 These files are optional since a kernel from Poky could be selected, although it 240 However, it would be unusual not to have a kernel configuration.
236 would be unusual not to have a kernel configuration.
237 </para> 241 </para>
238 </section> 242 </section>
239 243
240 <section id='bsp-filelayout-packages'> 244 <section id='bsp-filelayout-packages'>
241 <title>Other Software (meta-bsp/packages/*)</title> 245 <title>Other Software (meta-&lt;bsp_name&gt;/recipes-kernel/*)</title>
242 246
243 <para> 247 <para>
244 This section describes other pieces of software that the hardware might need for best 248 This section describes other pieces of software that the hardware might need for best
245 operation. 249 operation.
246 This section shows examples of the kinds of things that you could encounter. 250 Examples show some of the things you could encounter.
247 The examples are standard <filename>.bb</filename> file recipes in the 251 The examples are standard <filename>.bb</filename> file recipes in the
248 usual Poky format. 252 usual Poky format.
249 You can include the source directly by referring to it in the source control system or 253 You can include the source directly by referring to it in the source control system or
@@ -257,7 +261,7 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
257 </para> 261 </para>
258 <para> 262 <para>
259 <programlisting> 263 <programlisting>
260meta-bsp/packages/bootloader/bootloader_0.1.bb 264meta-Emenlow/recipes-kernel/bootloader/bootloader_0.1.bb
261 </programlisting> 265 </programlisting>
262 </para> 266 </para>
263 <para> 267 <para>
@@ -267,8 +271,8 @@ meta-bsp/packages/bootloader/bootloader_0.1.bb
267 </para> 271 </para>
268 <para> 272 <para>
269 <programlisting> 273 <programlisting>
270meta-bsp/packages/modem/modem-driver_0.1.bb 274meta-Emenlow/recipes-Emenlow/modem/modem-driver_0.1.bb
271meta-bsp/packages/modem/modem-daemon_0.1.bb 275meta-Emenlow/recipes-Emenlow/modem/modem-daemon_0.1.bb
272 </programlisting> 276 </programlisting>
273 </para> 277 </para>
274 <para> 278 <para>
@@ -279,7 +283,7 @@ meta-bsp/packages/modem/modem-daemon_0.1.bb
279 </para> 283 </para>
280 <para> 284 <para>
281 <programlisting> 285 <programlisting>
282meta-bsp/packages/image-creator/image-creator-native_0.1.bb 286meta-Emenlow/recipes-Emenlow/image-creator/image-creator-native_0.1.bb
283 </programlisting> 287 </programlisting>
284 </para> 288 </para>
285 </section> 289 </section>
@@ -287,7 +291,7 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
287 <section id='bs-filelayout-bbappend'> 291 <section id='bs-filelayout-bbappend'>
288 <title>Append BSP-Specific Information to Existing Recipes</title> 292 <title>Append BSP-Specific Information to Existing Recipes</title>
289 <para> 293 <para>
290 Suppose you have a recipe such as 'pointercal' that requires machine-specific information. 294 Suppose you have a recipe such as "pointercal" that requires machine-specific information.
291 At the same time, you have your new BSP code nicely partitioned into a layer through which 295 At the same time, you have your new BSP code nicely partitioned into a layer through which
292 you would also like to specify any machine-specific information associated with your new machine. 296 you would also like to specify any machine-specific information associated with your new machine.
293 Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole 297 Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole
@@ -296,9 +300,9 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
296 <para> 300 <para>
297 With the <filename>.bbappend</filename> extension, however, your work becomes much easier. 301 With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
298 This extension allows you to easily merge BSP-specific information with the original recipe. 302 This extension allows you to easily merge BSP-specific information with the original recipe.
299 Whenever bitbake finds any <filename>.bbappend</filename> files they will be 303 Whenever BitBake finds any <filename>.bbappend</filename> files BitBake will include them after
300 included after bitbake loads the associated <filename>.bb</filename> but before any finalize 304 it loads the associated <filename>.bb</filename> file but before any finalize
301 or anonymous methods run. 305 or anonymous methods are run.
302 This allows the BSP layer to do whatever it might want to do to customize the original recipe. 306 This allows the BSP layer to do whatever it might want to do to customize the original recipe.
303 </para> 307 </para>
304 <para> 308 <para>
@@ -311,17 +315,17 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
311 </programlisting> 315 </programlisting>
312 <para> 316 <para>
313 This technique allows the BSP to add machine-specific configuration files to the layer directory, 317 This technique allows the BSP to add machine-specific configuration files to the layer directory,
314 which will be picked up by bitbake. 318 which will be picked up by BitBake.
315 For an example see <filename>meta-emenlow/packages/formfactor</filename>. 319 For an example see <filename>meta-emenlow/packages/formfactor</filename>.
316 </para> 320 </para>
317 </section> 321 </section>
318 322
319 <section id="bsp-filelayout-prebuilds"> 323 <section id="bsp-filelayout-prebuilds">
320 <title>Prebuild Data (meta-bsp/prebuilds/*)</title> 324 <title>Pre-build Data (meta-&lt;bsp_name&gt;/prebuilds/*)</title>
321 <para> 325 <para>
322 This location can contain precompiled representations of the source code 326 This location can contain precompiled representations of the source code
323 contained elsewhere in the BSP layer. 327 contained elsewhere in the BSP layer.
324 Assuming a compatible configuration is used, Poky can process and use these optional precompiled 328 Assuming a compatible configuration is used, Poky can process and use these optional pre-compiled
325 representations to provide much faster build times. 329 representations to provide much faster build times.
326 </para> 330 </para>
327 </section> 331 </section>
@@ -354,24 +358,18 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
354 358
355 <para> 359 <para>
356 For cases where you can substitute something and still maintain functionality, the Poky website will make 360 For cases where you can substitute something and still maintain functionality, the Poky website will make
357 available a 'de-featured' BSP completely free of 361 available a 'de-featured' BSP completely free of the encumbered IP.
358 the encumbered IP. 362 In that case you can use the substitution directly and without any further licensing requirements.
359 In that case you can use the substitution directly and without 363 If present, this fully 'de-featured' BSP will be named meta-&lt;bsp_name&gt; (i.e. the
360 any further licensing requirements.
361 If present, this
362 fully 'de-featured' BSP will be named meta-bsp (i.e. the
363 normal default naming convention). 364 normal default naming convention).
364 If available, this is the simplest the most preferred option. 365 If available, this is the simplest the most preferred option.
365 This, of course, assumes the resulting functionality meets requirements. 366 This, of course, assumes the resulting functionality meets requirements.
366 </para> 367 </para>
367 368
368 <para> 369 <para>
369 If however, a non-encumbered version is unavailable or 370 If however, a non-encumbered version is unavailable or the 'free' version would provide unsuitable
370 the 'free' version would provide unsuitable 371 functionality or quality, an encumbered version can be used.
371 functionality or quality, an encumbered version can be 372 Encumbered versions of a BSP are given names of the form meta-&lt;bsp_name&gt;-nonfree.
372 used.
373 Encumbered versions of a BSP are given names of
374 the form meta-bsp-nonfree.
375 </para> 373 </para>
376 374
377 <para> 375 <para>
@@ -381,11 +379,10 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
381 </para> 379 </para>
382 380
383 <orderedlist> 381 <orderedlist>
384 <listitem> 382 <listitem>
385 383
386 <para> 384 <para>
387 Get a license key (or keys) for the encumbered BSP 385 Get a license key (or keys) for the encumbered BSP by visiting
388 by visiting
389 <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> 386 <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
390 and give the name of the BSP and your e-mail address in the web form. 387 and give the name of the BSP and your e-mail address in the web form.
391 </para> 388 </para>
@@ -427,7 +424,7 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
427 applicable license must be present in <filename>local.conf</filename> or 424 applicable license must be present in <filename>local.conf</filename> or
428 supplied on the command-line. 425 supplied on the command-line.
429 </para> 426 </para>
430 </listitem> 427 </listitem>
431 <listitem> 428 <listitem>
432 <para> 429 <para>
433 Do nothing - build as you normally would. 430 Do nothing - build as you normally would.
@@ -465,7 +462,7 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
465 non-free BSPs. 462 non-free BSPs.
466 Those images are likewise available at 463 Those images are likewise available at
467 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. 464 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
468 </para> 465 </para>
469 </section> 466 </section>
470 467
471</chapter> 468</chapter>