summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/poky-ref-manual/bsp.xml246
1 files changed, 127 insertions, 119 deletions
diff --git a/documentation/poky-ref-manual/bsp.xml b/documentation/poky-ref-manual/bsp.xml
index acb9f38e19..7cd18b61e3 100644
--- a/documentation/poky-ref-manual/bsp.xml
+++ b/documentation/poky-ref-manual/bsp.xml
@@ -1,53 +1,60 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 2<chapter id="bsp">
3
4<chapter id='bsp'>
5 3
6 <title>Board Support Packages (BSP) - Developers Guide</title> 4 <title>Board Support Packages (BSP) - Developers Guide</title>
7 5
8 <para> 6 <para>
9 A Board Support Package (BSP) is a collection of information which together 7 A Board Support Package (BSP) is a collection of information that
10 defines how to support a particular hardware device, set of devices, or 8 defines how to support a particular hardware device, set of devices, or
11 hardware platform. It will include information about the hardware features 9 hardware platform.
10 The BSP includes information about the hardware features
12 present on the device and kernel configuration information along with any 11 present on the device and kernel configuration information along with any
13 additional hardware drivers required. It will also list any additional software 12 additional hardware drivers required.
13 The BSP also lists any additional software
14 components required in addition to a generic Linux software stack for both 14 components required in addition to a generic Linux software stack for both
15 essential and optional platform features. 15 essential and optional platform features.
16 </para> 16 </para>
17 17
18 <para> 18 <para>
19 The intent of this document is to define a structure for these components 19 The intent of this document is to define a structure for these components
20 so that BSPs follow a commonly understood layout, allowing them to be 20 so that BSPs follow a commonly understood layout.
21 provided in a common form that everyone understands. It also allows end-users 21 Providing a common form allows end-users to understand and become familiar
22 to become familiar with one common format and encourages standardisation 22 with the layout.
23 A common form also encourages standardization
23 of software support of hardware. 24 of software support of hardware.
24 </para> 25 </para>
25 26
26 <para> 27 <para>
27 The proposed format does have elements that are specific to the Poky and 28 The proposed format does have elements that are specific to the Poky and
28 OpenEmbedded build systems. It is intended that this information can be 29 OpenEmbedded build systems.
29 used by other systems besides Poky/OpenEmbedded and that it will be simple 30 It is intended that this information can be
30 to extract information and convert to other formats if required. The format 31 used by other systems besides Poky and OpenEmbedded and thatspecified it will be simple
31 described can be directly accepted as a layer by Poky using its standard 32 to extract information and convert it to other formats if required.
32 layers mechanism, but it is important to recognise that the BSP captures all 33 Poky, through its standard slyers mechanism, can directly accept The format
34 described as a layer.
35 The BSP captures all
33 the hardware specific details in one place in a standard format, which is 36 the hardware specific details in one place in a standard format, which is
34 useful for any person wishing to use the hardware platform regardless of 37 useful for any person wishing to use the hardware platform regardless of
35 the build system in use. 38 the build system being used.
36 </para> 39 </para>
37 40
38 <para> 41 <para>
39 The BSP specification does not include a build system or other tools - 42 The BSP specification does not include a build system or other tools -
40 it is concerned with the hardware specific components only. At the end 43 it is concerned with the hardware-specific components only.
41 distribution point the BSP may be shipped combined with a build system 44 At the end
42 and other tools, but it is important to maintain the distinction that these 45 distribution point you can shipt the BSP combined with a build system
43 are separate components which may just be combined in certain end products. 46 and other tools.
47 However, it is important to maintain the distinction that these
48 are separate components that happen to be combined in certain end products.
44 </para> 49 </para>
45 50
46 <section id='bsp-filelayout'> 51 <section id="bsp-filelayout">
47 <title>Example Filesystem Layout</title> 52 <title>Example Filesystem Layout</title>
48 53
49 <para> 54 <para>
50 The BSP consists of a file structure inside a base directory, meta-bsp in this example, where "bsp" is a placeholder for the machine or platform name. Examples of some files that it could contain are: 55 The BSP consists of a file structure inside a base directory, meta-bsp in this example,
56 where "bsp" is a placeholder for the machine or platform name.
57 Examples of some files that it could contain are:
51 </para> 58 </para>
52 59
53 <para> 60 <para>
@@ -76,15 +83,18 @@ meta-bsp/prebuilds/
76 83
77 </section> 84 </section>
78 85
79 <section id='bsp-filelayout-binary'> 86 <section id="bsp-filelayout-binary">
80 <title>Prebuilt User Binaries (meta-bsp/binary/*)</title> 87 <title>Prebuilt User Binaries (meta-bsp/binary/*)</title>
81 88
82 <para> 89 <para>
83 This optional area contains useful prebuilt kernels and userspace filesystem 90 This optional area contains useful prebuilt kernels and userspace filesystem
84 images appropriate to the target system. Users could use these to get a system 91 images appropriate to the target system.
85 running and quickly get started on development tasks. The exact types of binaries 92 Users could use these to get a system
93 running and quickly get started on development tasks.
94 The exact types of binaries
86 present will be highly hardware-dependent but a README file should be present 95 present will be highly hardware-dependent but a README file should be present
87 explaining how to use them with the target hardware. If prebuilt binaries are 96 explaining how to use them with the target hardware.
97 If prebuilt binaries are
88 present, source code to meet licensing requirements must also be provided in 98 present, source code to meet licensing requirements must also be provided in
89 some form. 99 some form.
90 </para> 100 </para>
@@ -95,9 +105,10 @@ meta-bsp/prebuilds/
95 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title> 105 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
96 106
97 <para> 107 <para>
98 This file identifies the structure as a Poky layer. This file identifies the 108 This file identifies the structure as a Poky layer by identifying the
99 contents of the layer and contains information about how Poky should use 109 contents of the layer and containing information about how Poky should use
100 it. In general it will most likely be a standard boilerplate file consisting of: 110 it.
111 Generally, a standard boilerplate file consisting of the following works.
101 </para> 112 </para>
102 113
103 <para> 114 <para>
@@ -106,7 +117,7 @@ meta-bsp/prebuilds/
106BBPATH := "${BBPATH}${LAYERDIR}" 117BBPATH := "${BBPATH}${LAYERDIR}"
107 118
108# We have a recipes directory containing .bb and .bbappend files, add to BBFILES 119# We have a recipes directory containing .bb and .bbappend files, add to BBFILES
109BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb ${LAYERDIR}/recipes/*/*.bbappend" 120BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend"
110 121
111BBFILE_COLLECTIONS += "bsp" 122BBFILE_COLLECTIONS += "bsp"
112BBFILE_PATTERN_bsp := "^${LAYERDIR}/" 123BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
@@ -115,47 +126,45 @@ BBFILE_PRIORITY_bsp = "5"
115 </para> 126 </para>
116 127
117 <para> 128 <para>
118 which simply makes bitbake aware of the recipes and conf directories. 129 This file simply makes bitbake aware of the recipes and conf directories and is required
119 </para> 130 for recognition of the BSP by Poky.
120
121 <para>
122 This file is required for recognition of the BSP by Poky.
123 </para> 131 </para>
124 132
125 </section> 133 </section>
126 134
127 <section id='bsp-filelayout-machine'> 135 <section id="bsp-filelayout-machine">
128 <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title> 136 <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title>
129 137
130 <para> 138 <para>
131 The machine files bind together all the information contained elsewhere 139 The machine files bind together all the information contained elsewhere
132 in the BSP into a format that Poky/OpenEmbedded can understand. If 140 in the BSP into a format that Poky/OpenEmbedded can understand.
133 the BSP supports multiple machines, multiple machine configuration files 141 If the BSP supports multiple machines, multiple machine configuration files
134 can be present. These filenames correspond to the values users set the 142 can be present.
135 MACHINE variable to. 143 These filenames correspond to the values to which users have set the MACHINE variable.
136 </para> 144 </para>
137 145
138 <para> 146 <para>
139 These files would define things like which kernel package to use 147 These files define things such as what kernel package to use
140 (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to 148 (PREFERRED_PROVIDER of virtual/kernel), what hardware drivers to
141 include in different types of images, any special software components 149 include in different types of images, any special software components
142 that are needed, any bootloader information, and also any special image 150 that are needed, any bootloader information, and also any special image
143 format requirements. 151 format requirements.
144 </para> 152 </para>
145 153
146 <para> 154 <para>
147 At least one machine file is required for a Poky BSP layer but more than one may be present. 155 At least one machine file is required for a Poky BSP layer.
156 However, you can supply more than one file.
148 </para> 157 </para>
149 158
150 </section> 159 </section>
151 160
152 <section id='bsp-filelayout-tune'> 161 <section id="bsp-filelayout-tune">
153 <title>Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title> 162 <title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
154 163
155 <para> 164 <para>
156 These are shared hardware "tuning" definitions and are commonly used to 165 These are shared hardware "tuning" definitions and are commonly used to
157 pass specific optimisation flags to the compiler. An example is 166 pass specific optimization flags to the compiler.
158 tune-atom.inc: 167 An example is tune-atom.inc:
159 </para> 168 </para>
160 <para> 169 <para>
161 <programlisting> 170 <programlisting>
@@ -164,40 +173,42 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
164 </programlisting> 173 </programlisting>
165 </para> 174 </para>
166 <para> 175 <para>
167 which defines a new package architecture called "core2" and uses the 176 This example defines a new package architecture called "core2" and uses the
168 optimization flags specified, which are carefully chosen to give best 177 specified optimization flags, which are carefully chosen to give best
169 performance on atom cpus. 178 performance on atom processors.
170 </para> 179 </para>
171 <para> 180 <para>
172 The tune file would be included by the machine definition and can be 181 The tune file would be included by the machine definition and can be
173 contained in the BSP or reference one from the standard core set of 182 contained in the BSP or referenced from one of the standard core set of
174 files included with Poky itself. 183 files included with Poky itself.
175 </para> 184 </para>
176 <para> 185 <para>
177 These files are optional for a Poky BSP layer. 186 Both the base package architecuture file and the tune file are optional for a Poky BSP layer.
178 </para> 187 </para>
179 </section> 188 </section>
189
180 <section id='bsp-filelayout-kernel'> 190 <section id='bsp-filelayout-kernel'>
181 <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title> 191 <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title>
182 192
183 <para> 193 <para>
184 These files make up the definition of a kernel to use with this 194 These files make up the definition of a kernel to use with this
185 hardware. In this case it is a complete self-contained kernel with its own 195 hardware.
196 In this case it is a complete self-contained kernel with its own
186 configuration and patches but kernels can be shared between many 197 configuration and patches but kernels can be shared between many
187 machines as well. Taking some specific example files: 198 machines as well.
188 </para> 199 Following is an example:
189 <para>
190 <programlisting> 200 <programlisting>
191meta-bsp/packages/linux/linux-bsp_2.6.50.bb 201meta-bsp/packages/linux/linux-bsp_2.6.50.bb
192 </programlisting> 202 </programlisting>
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.
193 </para> 208 </para>
194 <para> 209 <para>
195 which is the core kernel recipe which firstly details where to get the kernel 210 The file then contains information about what patches to apply and how to configure and build them.
196 source from. All standard source code locations are supported so this could 211 It can reuse the main Poky kernel build class, so the definitions here can remain very simple.
197 be a release tarball, some git repository, or source included in
198 the directory within the BSP itself. It then contains information about which
199 patches to apply and how to configure and build it. It can reuse the main
200 Poky kernel build class, so the definitions here can remain very simple.
201 </para> 212 </para>
202 <para> 213 <para>
203 <programlisting> 214 <programlisting>
@@ -205,7 +216,7 @@ linux-bsp-2.6.50/*.patch
205 </programlisting> 216 </programlisting>
206 </para> 217 </para>
207 <para> 218 <para>
208 which are patches which may be applied against the base kernel, wherever 219 The above example file contains patches you can apply against the base kernel, wherever
209 they may have been obtained from. 220 they may have been obtained from.
210 </para> 221 </para>
211 <para> 222 <para>
@@ -214,11 +225,11 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
214 </programlisting> 225 </programlisting>
215 </para> 226 </para>
216 <para> 227 <para>
217 which is the configuration information to use to configure the kernel. 228 Finally, this last example file contains configuration information to use to configure the kernel.
218 </para> 229 </para>
219 <para> 230 <para>
220 Examples of kernel recipes are available in Poky itself. These files are 231 Examples of kernel recipes are available in Poky itself.
221 optional since a kernel from Poky itself could be selected, although it 232 These files are optional since a kernel from Poky itself could be selected, although it
222 would be unusual not to have a kernel configuration. 233 would be unusual not to have a kernel configuration.
223 </para> 234 </para>
224 </section> 235 </section>
@@ -227,11 +238,19 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
227 <title>Other Software (meta-bsp/packages/*)</title> 238 <title>Other Software (meta-bsp/packages/*)</title>
228 239
229 <para> 240 <para>
230 This area includes other pieces of software which the hardware may need for best 241 This section describes other pieces of software that the hardware might need for best
231 operation. These are just examples of the kind of things that may be 242 operation.
232 encountered. These are standard .bb file recipes in the usual Poky format, 243 These are examples of the kinds of things that you could encounter.
233 so for examples, see standard Poky recipes. The source can be included directly, 244 The examples used in this section are standard <filename>.bb</filename> file recipes in the
234 referred to in source control systems or release tarballs of external software projects. 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.
235 </para> 254 </para>
236 <para> 255 <para>
237 <programlisting> 256 <programlisting>
@@ -239,9 +258,9 @@ meta-bsp/packages/bootloader/bootloader_0.1.bb
239 </programlisting> 258 </programlisting>
240 </para> 259 </para>
241 <para> 260 <para>
242 Some kind of bootloader recipe which may be used to generate a new 261 These next two files are examples of a hardware driver and a hardware daemon that might need
243 bootloader binary. Sometimes these are included in the final image 262 to be included in images to make the hardware useful.
244 format and needed to reflash hardware. 263 Although the example uses "modem" there may be other components needed, such as firmware.
245 </para> 264 </para>
246 <para> 265 <para>
247 <programlisting> 266 <programlisting>
@@ -250,72 +269,62 @@ meta-bsp/packages/modem/modem-daemon_0.1.bb
250 </programlisting> 269 </programlisting>
251 </para> 270 </para>
252 <para> 271 <para>
253 These are examples of a hardware driver and also a hardware daemon which 272 Sometimes the device needs an image in a very specific format so that the update
254 may need to be included in images to make the hardware useful. "modem" 273 mechanism can accept and reflash it.
255 is one example but there may be other components needed like firmware. 274 Recipes to build the tools needed to do this can be included with the BSP.
275 Following is an example.
256 </para> 276 </para>
257 <para> 277 <para>
258 <programlisting> 278 <programlisting>
259meta-bsp/packages/image-creator/image-creator-native_0.1.bb 279meta-bsp/packages/image-creator/image-creator-native_0.1.bb
260 </programlisting> 280 </programlisting>
261 </para> 281 </para>
282 </section>
283
284 <section id='bs-filelayout-bbappend'>
285 <title>Append BSP-Specific Information to Existing Recipes</title>
262 <para> 286 <para>
263 Sometimes the device will need an image in a very specific format for 287 Suppose you have a recipe such as 'pointercal' that requires machine-specific information.
264 its update mechanism to accept and reflash with it. Recipes to build the 288 At the same time, you have your new BSP code nicely partitioned into a layer, which is where
265 tools needed to do this can be included with the BSP. 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.
266 </para> 292 </para>
267 <para> 293 <para>
268 These files only need be provided if the platform requires them. 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.
269 </para> 300 </para>
270 </section>
271
272 <section id='bs-filelayout-bbappend'>
273 <title>Append BSP specific information to existing recipes</title>
274
275 <para> 301 <para>
276 Say you have a recipe like pointercal which has machine-specific information in it, 302 If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable
277 and then you have your new BSP code in a layer. Before the .bbappend extension was 303 to specify their location.
278 introduced, you'd have to copy the whole pointercal recipe and files into your layer, 304 The example below shows extra files contained in a folder called ${PN} (the package name).
279 and then add the single file for your machine, which is ugly.
280
281 .bbappend makes the above work much easier, to allow BSP-specific information to be merged
282 with the original recipe easily. When bitbake finds any X.bbappend files, they will be
283 included after bitbake loads X.bb but before finalise or anonymous methods run.
284 This allows the BSP layer to poke around and do whatever it might want to customise
285 the original recipe.
286
287 If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable
288 to specify their location. The example below shows extra files contained in a folder
289 called ${PN} (the package name).
290 </para> 305 </para>
291
292 <programlisting> 306 <programlisting>
293FILESEXTRAPATHS := "${THISDIR}/${PN}" 307FILESEXTRAPATHS := "${THISDIR}/${PN}"
294 </programlisting> 308 </programlisting>
295
296 <para> 309 <para>
297 Then the BSP could add machine-specific config files in layer directory, which will be 310 This technique allows the BSP to add machine-specific configuration files to the layer directory,
298 added by bitbake. You can look at meta-emenlow/packages/formfactor as an example. 311 which will be picked up by bitbake.
312 For an example see <filename>meta-emenlow/packages/formfactor</filename>.
299 </para> 313 </para>
300 </section> 314 </section>
301 315
302 <section id='bsp-filelayout-prebuilds'> 316 <section id="bsp-filelayout-prebuilds">
303 <title>Prebuild Data (meta-bsp/prebuilds/*)</title> 317 <title>Prebuild Data (meta-bsp/prebuilds/*)</title>
304
305 <para>
306 The location can contain a precompiled representation of the source code
307 contained elsewhere in the BSP layer. It can be processed and used by
308 Poky to provide much faster build times, assuming a compatible configuration is used.
309 </para>
310
311 <para> 318 <para>
312 These files are optional. 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.
313 </para> 323 </para>
314
315 </section> 324 </section>
316 325
317 <section id='bsp-click-through-licensing'> 326 <section id='bsp-click-through-licensing'>
318 <title>BSP 'Click-through' Licensing Procedure</title> 327 <title>BSP 'Click-Through' Licensing Procedure</title>
319 328
320 <note><para> This section is here as a description of how 329 <note><para> This section is here as a description of how
321 click-through licensing is expected to work, and is 330 click-through licensing is expected to work, and is
@@ -367,10 +376,9 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
367 376
368 <para> 377 <para>
369 Get a license key (or keys) for the encumbered BSP 378 Get a license key (or keys) for the encumbered BSP
370 by 379 by visiting
371 visiting <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> 380 <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
372 and give the web form there the name of the BSP 381 and give the web form there the name of the BSP and your e-mail address.
373 and your e-mail address.
374 </para> 382 </para>
375 383
376 <programlisting> 384 <programlisting>