diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2010-11-04 13:01:19 -0700 |
---|---|---|
committer | Richard Purdie <rpurdie@linux.intel.com> | 2010-11-04 20:54:30 +0000 |
commit | 890a794e38f2d11ec0dd6e39e5ab77a929cb51d9 (patch) | |
tree | 75a69ef3e6752085f5bc1a3d84fab378af5b515a /documentation/bsp-guide/bsp.xml | |
parent | 4b7f1eee28dafcb237f54e1739a9936fdd80ebc4 (diff) | |
download | poky-890a794e38f2d11ec0dd6e39e5ab77a929cb51d9.tar.gz |
Created a new folder to hold the BSP Guide
I created a new sub folder to hold the BSP Guide by itself so there are
three folders now for each of the Yocto manuals: BSP Guide, quick start
and poky ref manual. The new folder for the BSP guide is 'bsp-guide'.
It contains the bsp.xml file, its own Makefile, a bsp-guide.xml file,
and its own 'Figures' directory. The 'bsp-guide.xml' file that was
in the poky reference folder was deleted.
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.xml | 459 |
1 files changed, 459 insertions, 0 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml new file mode 100644 index 0000000000..3b4b4818fa --- /dev/null +++ b/documentation/bsp-guide/bsp.xml | |||
@@ -0,0 +1,459 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | ||
3 | |||
4 | <chapter id='bsp'> | ||
5 | |||
6 | <title>Board Support Packages (BSP) - Developers Guide</title> | ||
7 | |||
8 | <para> | ||
9 | A Board Support Package (BSP) is a collection of information that | ||
10 | defines how to support a particular hardware device, set of devices, or | ||
11 | hardware platform. | ||
12 | The BSP includes information about the hardware features | ||
13 | present on the device and kernel configuration information along with any | ||
14 | additional hardware drivers required. | ||
15 | The BSP also lists any additional software | ||
16 | components required in addition to a generic Linux software stack for both | ||
17 | essential and optional platform features. | ||
18 | </para> | ||
19 | |||
20 | <para> | ||
21 | The intent of this document is to define a structure for these components | ||
22 | so that BSPs follow a commonly understood layout. | ||
23 | Providing a common form allows end-users to understand and become familiar | ||
24 | with the layout. | ||
25 | A common form also encourages standardization | ||
26 | of software support of hardware. | ||
27 | </para> | ||
28 | |||
29 | <para> | ||
30 | The proposed format does have elements that are specific to the Poky and | ||
31 | OpenEmbedded build systems. | ||
32 | It is intended that this information can be | ||
33 | used by other systems besides Poky and OpenEmbedded and thatspecified it will be simple | ||
34 | to extract information and convert it to other formats if required. | ||
35 | Poky, through its standard slyers mechanism, can directly accept The format | ||
36 | described as a layer. | ||
37 | The BSP captures all | ||
38 | the hardware specific details in one place in a standard format, which is | ||
39 | useful for any person wishing to use the hardware platform regardless of | ||
40 | the build system being used. | ||
41 | </para> | ||
42 | |||
43 | <para> | ||
44 | The BSP specification does not include a build system or other tools - | ||
45 | it is concerned with the hardware-specific components only. | ||
46 | At the end | ||
47 | distribution point you can shipt the BSP combined with a build system | ||
48 | and other tools. | ||
49 | However, it is important to maintain the distinction that these | ||
50 | are separate components that happen to be combined in certain end products. | ||
51 | </para> | ||
52 | |||
53 | <section id="bsp-filelayout"> | ||
54 | <title>Example Filesystem Layout</title> | ||
55 | |||
56 | <para> | ||
57 | The BSP consists of a file structure inside a base directory, meta-bsp in this example, | ||
58 | where "bsp" is a placeholder for the machine or platform name. | ||
59 | Examples of some files that it could contain are: | ||
60 | </para> | ||
61 | <para> | ||
62 | <literallayout class='monospaced'> | ||
63 | meta-bsp/ | ||
64 | meta-bsp/binary/zImage | ||
65 | meta-bsp/binary/poky-image-minimal.directdisk | ||
66 | meta-bsp/conf/layer.conf | ||
67 | meta-bsp/conf/machine/*.conf | ||
68 | meta-bsp/conf/machine/include/tune-*.inc | ||
69 | meta-bsp/packages/bootloader/bootloader_0.1.bb | ||
70 | meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch | ||
71 | meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp | ||
72 | meta-bsp/packages/linux/linux-bsp_2.6.50.bb | ||
73 | meta-bsp/packages/modem/modem-driver_0.1.bb | ||
74 | meta-bsp/packages/modem/modem-daemon_0.1.bb | ||
75 | meta-bsp/packages/image-creator/image-creator-native_0.1.bb | ||
76 | meta-bsp/prebuilds/ | ||
77 | </literallayout> | ||
78 | </para> | ||
79 | |||
80 | <para> | ||
81 | The following sections detail what these files and directories could contain. | ||
82 | </para> | ||
83 | |||
84 | </section> | ||
85 | |||
86 | <section id="bsp-filelayout-binary"> | ||
87 | <title>Prebuilt User Binaries (meta-bsp/binary/*)</title> | ||
88 | |||
89 | <para> | ||
90 | This optional area contains useful prebuilt kernels and userspace filesystem | ||
91 | images appropriate to the target system. | ||
92 | Users could use these to get a system | ||
93 | running and quickly get started on development tasks. | ||
94 | The exact types of binaries | ||
95 | present will be highly hardware-dependent but a README file should be present | ||
96 | explaining how to use them with the target hardware. | ||
97 | If prebuilt binaries are | ||
98 | present, source code to meet licensing requirements must also be provided in | ||
99 | some form. | ||
100 | </para> | ||
101 | |||
102 | </section> | ||
103 | |||
104 | <section id='bsp-filelayout-layer'> | ||
105 | <title>Layer Configuration (meta-bsp/conf/layer.conf)</title> | ||
106 | |||
107 | <para> | ||
108 | This file identifies the structure as a Poky layer by identifying the | ||
109 | contents of the layer and containing information about how Poky should use | ||
110 | it. | ||
111 | Generally, a standard boilerplate file consisting of the following works. | ||
112 | </para> | ||
113 | |||
114 | <para> | ||
115 | <literallayout class='monospaced'> | ||
116 | # We have a conf directory, add to BBPATH | ||
117 | BBPATH := "${BBPATH}${LAYERDIR}" | ||
118 | |||
119 | # We have a recipes directory containing .bb and .bbappend files, add to BBFILES | ||
120 | BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend" | ||
121 | |||
122 | BBFILE_COLLECTIONS += "bsp" | ||
123 | BBFILE_PATTERN_bsp := "^${LAYERDIR}/" | ||
124 | BBFILE_PRIORITY_bsp = "5" | ||
125 | </literallayout> | ||
126 | </para> | ||
127 | |||
128 | <para> | ||
129 | This file simply makes bitbake aware of the recipes and conf directories and is required | ||
130 | for recognition of the BSP by Poky. | ||
131 | </para> | ||
132 | |||
133 | </section> | ||
134 | |||
135 | <section id="bsp-filelayout-machine"> | ||
136 | <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title> | ||
137 | |||
138 | <para> | ||
139 | The machine files bind together all the information contained elsewhere | ||
140 | in the BSP into a format that Poky/OpenEmbedded can understand. | ||
141 | If the BSP supports multiple machines, multiple machine configuration files | ||
142 | can be present. | ||
143 | These filenames correspond to the values to which users have set the MACHINE variable. | ||
144 | </para> | ||
145 | |||
146 | <para> | ||
147 | These files define things such as what kernel package to use | ||
148 | (PREFERRED_PROVIDER of virtual/kernel), what hardware drivers to | ||
149 | include in different types of images, any special software components | ||
150 | that are needed, any bootloader information, and also any special image | ||
151 | format requirements. | ||
152 | </para> | ||
153 | |||
154 | <para> | ||
155 | At least one machine file is required for a Poky BSP layer. | ||
156 | However, you can supply more than one file. | ||
157 | </para> | ||
158 | |||
159 | </section> | ||
160 | |||
161 | <section id="bsp-filelayout-tune"> | ||
162 | <title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title> | ||
163 | |||
164 | <para> | ||
165 | These are shared hardware "tuning" definitions and are commonly used to | ||
166 | pass specific optimization flags to the compiler. | ||
167 | An example is tune-atom.inc: | ||
168 | </para> | ||
169 | <para> | ||
170 | <literallayout class='monospaced'> | ||
171 | BASE_PACKAGE_ARCH = "core2" | ||
172 | TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" | ||
173 | </literallayout> | ||
174 | </para> | ||
175 | <para> | ||
176 | This example defines a new package architecture called "core2" and uses the | ||
177 | specified optimization flags, which are carefully chosen to give best | ||
178 | performance on atom processors. | ||
179 | </para> | ||
180 | <para> | ||
181 | The tune file would be included by the machine definition and can be | ||
182 | contained in the BSP or referenced from one of the standard core set of | ||
183 | files included with Poky itself. | ||
184 | </para> | ||
185 | <para> | ||
186 | Both the base package architecuture file and the tune file are optional for a Poky BSP layer. | ||
187 | </para> | ||
188 | </section> | ||
189 | |||
190 | <section id='bsp-filelayout-kernel'> | ||
191 | <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title> | ||
192 | |||
193 | <para> | ||
194 | These files make up the definition of a kernel to use with this | ||
195 | hardware. | ||
196 | In this case it is a complete self-contained kernel with its own | ||
197 | configuration and patches but kernels can be shared between many | ||
198 | machines as well. | ||
199 | Following is an example: | ||
200 | <literallayout class='monospaced'> | ||
201 | meta-bsp/packages/linux/linux-bsp_2.6.50.bb | ||
202 | </literallayout> | ||
203 | This example file is the core kernel recipe that details from where to get the kernel | ||
204 | source. | ||
205 | All standard source code locations are supported so this could | ||
206 | be a release tarball, some git repository, or source included in | ||
207 | the directory within the BSP itself. | ||
208 | </para> | ||
209 | <para> | ||
210 | The file then contains information about what patches to apply and how to configure and build them. | ||
211 | It can reuse the main Poky kernel build class, so the definitions here can remain very simple. | ||
212 | </para> | ||
213 | <para> | ||
214 | <literallayout class='monospaced'> | ||
215 | linux-bsp-2.6.50/*.patch | ||
216 | </literallayout> | ||
217 | </para> | ||
218 | <para> | ||
219 | The above example file contains patches you can apply against the base kernel, wherever | ||
220 | they may have been obtained from. | ||
221 | </para> | ||
222 | <para> | ||
223 | <literallayout class='monospaced'> | ||
224 | meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp | ||
225 | </literallayout> | ||
226 | </para> | ||
227 | <para> | ||
228 | Finally, this last example file contains configuration information to use to configure the kernel. | ||
229 | </para> | ||
230 | <para> | ||
231 | Examples of kernel recipes are available in Poky itself. | ||
232 | These files are optional since a kernel from Poky itself could be selected, although it | ||
233 | would be unusual not to have a kernel configuration. | ||
234 | </para> | ||
235 | </section> | ||
236 | |||
237 | <section id='bsp-filelayout-packages'> | ||
238 | <title>Other Software (meta-bsp/packages/*)</title> | ||
239 | |||
240 | <para> | ||
241 | This section describes other pieces of software that the hardware might need for best | ||
242 | operation. | ||
243 | These are examples of the kinds of things that you could encounter. | ||
244 | The examples used in this section are standard <filename>.bb</filename> file recipes in the | ||
245 | usual Poky format. | ||
246 | You can include the source directly by referring to it in the source control system or | ||
247 | the released tarballs of external software projects. | ||
248 | You only need to provide these types of files if the platform requires them. | ||
249 | </para> | ||
250 | <para> | ||
251 | The following file is a bootloader recipe that can be used to generate a new | ||
252 | bootloader binary. | ||
253 | Sometimes these files are included in the final image format and are needed to reflash hardware. | ||
254 | </para> | ||
255 | <para> | ||
256 | <literallayout class='monospaced'> | ||
257 | meta-bsp/packages/bootloader/bootloader_0.1.bb | ||
258 | </literallayout> | ||
259 | </para> | ||
260 | <para> | ||
261 | These next two files are examples of a hardware driver and a hardware daemon that might need | ||
262 | to be included in images to make the hardware useful. | ||
263 | Although the example uses "modem" there may be other components needed, such as firmware. | ||
264 | </para> | ||
265 | <para> | ||
266 | <literallayout class='monospaced'> | ||
267 | meta-bsp/packages/modem/modem-driver_0.1.bb | ||
268 | meta-bsp/packages/modem/modem-daemon_0.1.bb | ||
269 | </literallayout> | ||
270 | </para> | ||
271 | <para> | ||
272 | Sometimes the device needs an image in a very specific format so that the update | ||
273 | mechanism can accept and reflash it. | ||
274 | Recipes to build the tools needed to do this can be included with the BSP. | ||
275 | Following is an example. | ||
276 | </para> | ||
277 | <para> | ||
278 | <literallayout class='monospaced'> | ||
279 | meta-bsp/packages/image-creator/image-creator-native_0.1.bb | ||
280 | </literallayout> | ||
281 | </para> | ||
282 | </section> | ||
283 | |||
284 | <section id='bs-filelayout-bbappend'> | ||
285 | <title>Append BSP-Specific Information to Existing Recipes</title> | ||
286 | <para> | ||
287 | Suppose you have a recipe such as 'pointercal' that requires machine-specific information. | ||
288 | At the same time, you have your new BSP code nicely partitioned into a layer, which is where | ||
289 | you would also like to specify any machine-specific information associated with your new machine. | ||
290 | Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole | ||
291 | pointercal recipe and files into your layer, and then add the single file for your machine. | ||
292 | </para> | ||
293 | <para> | ||
294 | With the <filename>.bbappend</filename> extension, however, your work becomes much easier. | ||
295 | It allows you to easily merge BSP-specific information with the original recipe. | ||
296 | Whenever bitbake finds any <filename>.bbappend</filename> files, they will be | ||
297 | included after bitbake loads the associated <filename>.bb</filename> but before any finalize | ||
298 | or anonymous methods run. | ||
299 | This allows the BSP layer to do whatever it might want to do to customize the original recipe. | ||
300 | </para> | ||
301 | <para> | ||
302 | If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable | ||
303 | to specify their location. | ||
304 | The example below shows extra files contained in a folder called ${PN} (the package name). | ||
305 | </para> | ||
306 | <literallayout class='monospaced'> | ||
307 | FILESEXTRAPATHS := "${THISDIR}/${PN}" | ||
308 | </literallayout> | ||
309 | <para> | ||
310 | This technique allows the BSP to add machine-specific configuration files to the layer directory, | ||
311 | which will be picked up by bitbake. | ||
312 | For an example see <filename>meta-emenlow/packages/formfactor</filename>. | ||
313 | </para> | ||
314 | </section> | ||
315 | |||
316 | <section id="bsp-filelayout-prebuilds"> | ||
317 | <title>Prebuild Data (meta-bsp/prebuilds/*)</title> | ||
318 | <para> | ||
319 | This location can contain precompiled representations of the source code | ||
320 | contained elsewhere in the BSP layer. | ||
321 | Assuming a compatible configuration is used, Poky can process and use these optional precompiled | ||
322 | representations to provide much faster build times. | ||
323 | </para> | ||
324 | </section> | ||
325 | |||
326 | <section id='bsp-click-through-licensing'> | ||
327 | <title>BSP 'Click-Through' Licensing Procedure</title> | ||
328 | |||
329 | <note><para> This section is here as a description of how | ||
330 | click-through licensing is expected to work, and is | ||
331 | not yet not impemented. | ||
332 | </para></note> | ||
333 | |||
334 | <para> | ||
335 | In some cases, a BSP may contain separately licensed IP | ||
336 | (Intellectual Property) for a component, which imposes | ||
337 | upon the user a requirement to accept the terms of a | ||
338 | 'click-through' license. Once the license is accepted | ||
339 | (in whatever form that may be, see details below) the | ||
340 | Poky build system can then build and include the | ||
341 | corresponding component in the final BSP image. Some | ||
342 | affected components may be essential to the normal | ||
343 | functioning of the system and have no 'free' replacement | ||
344 | i.e. the resulting system would be non-functional | ||
345 | without them. Other components may be simply | ||
346 | 'good-to-have' or purely elective, or if essential | ||
347 | nonetheless have a 'free' (possibly less-capable) | ||
348 | version which may substituted for in the BSP recipe. | ||
349 | </para> | ||
350 | |||
351 | <para> | ||
352 | For the latter cases, where it is possible to do so from | ||
353 | a functionality perspective, the Poky website will make | ||
354 | available a 'de-featured' BSP completely free of | ||
355 | encumbered IP, which can be used directly and without | ||
356 | any further licensing requirements. If present, this | ||
357 | fully 'de-featured' BSP will be named meta-bsp (i.e. the | ||
358 | normal default naming convention). This is the simplest | ||
359 | and therefore preferred option if available, assuming | ||
360 | the resulting functionality meets requirements. | ||
361 | </para> | ||
362 | |||
363 | <para> | ||
364 | If however, a non-encumbered version is unavailable or | ||
365 | the 'free' version would provide unsuitable | ||
366 | functionality or quality, an encumbered version can be | ||
367 | used. Encumbered versions of a BSP are given names of | ||
368 | the form meta-bsp-nonfree. There are several ways | ||
369 | within the Poky build system to satisfy the licensing | ||
370 | requirements for an encumbered BSP, in roughly the | ||
371 | following order of preference: | ||
372 | </para> | ||
373 | |||
374 | <itemizedlist> | ||
375 | <listitem> | ||
376 | |||
377 | <para> | ||
378 | Get a license key (or keys) for the encumbered BSP | ||
379 | by visiting | ||
380 | <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> | ||
381 | and give the web form there the name of the BSP and your e-mail address. | ||
382 | </para> | ||
383 | |||
384 | <literallayout class='monospaced'> | ||
385 | [screenshot of dialog box] | ||
386 | </literallayout> | ||
387 | |||
388 | <para> | ||
389 | After agreeing to any applicable license terms, the | ||
390 | BSP key(s) will be immediately sent to the address | ||
391 | given and can be used by specifying BSPKEY_<keydomain> | ||
392 | environment variables when building the image: | ||
393 | </para> | ||
394 | |||
395 | <literallayout class='monospaced'> | ||
396 | $ BSPKEY_<keydomain>=<key> bitbake poky-image-sato | ||
397 | </literallayout> | ||
398 | |||
399 | <para> | ||
400 | This will allow the encumbered image to be built | ||
401 | with no change at all to the normal build process. | ||
402 | </para> | ||
403 | |||
404 | <para> | ||
405 | Equivalently and probably more conveniently, a line | ||
406 | for each key can instead be put into the user's | ||
407 | local.conf file. | ||
408 | </para> | ||
409 | |||
410 | <para> | ||
411 | The <keydomain> component of the | ||
412 | BSPKEY_<keydomain> is required because there | ||
413 | may be multiple licenses in effect for a give BSP; a | ||
414 | given <keydomain> in such cases corresponds to | ||
415 | a particular license. In order for an encumbered | ||
416 | BSP encompassing multiple key domains to be built | ||
417 | successfully, a <keydomain> entry for each | ||
418 | applicable license must be present in local.conf or | ||
419 | supplied on the command-line. | ||
420 | </para> | ||
421 | </listitem> | ||
422 | <listitem> | ||
423 | <para> | ||
424 | Do nothing - build as you normally would, and follow | ||
425 | any license prompts that originate from the | ||
426 | encumbered BSP (the build will cleanly stop at this | ||
427 | point). These usually take the form of instructions | ||
428 | needed to manually fetch the encumbered package(s) | ||
429 | and md5 sums into e.g. the poky/build/downloads | ||
430 | directory. Once the manual package fetch has been | ||
431 | completed, restarting the build will continue where | ||
432 | it left off, this time without the prompt since the | ||
433 | license requirements will have been satisfied. | ||
434 | </para> | ||
435 | </listitem> | ||
436 | <listitem> | ||
437 | <para> | ||
438 | Get a full-featured BSP recipe rather than a key, by | ||
439 | visiting | ||
440 | <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. | ||
441 | Accepting the license agreement(s) presented will | ||
442 | subsequently allow you to download a tarball | ||
443 | containing a full-featured BSP legally cleared for | ||
444 | your use by the just-given license agreement(s). | ||
445 | This method will also allow the encumbered image to | ||
446 | be built with no change at all to the normal build | ||
447 | process. | ||
448 | </para> | ||
449 | </listitem> | ||
450 | </itemizedlist> | ||
451 | <para> | ||
452 | Note that method 3 is also the only option available | ||
453 | when downloading pre-compiled images generated from | ||
454 | non-free BSPs. Those images are likewise available at | ||
455 | <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. | ||
456 | </para> | ||
457 | </section> | ||
458 | |||
459 | </chapter> | ||