summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--handbook/Makefile18
-rw-r--r--handbook/bsp-guide.xml61
-rw-r--r--handbook/bsp.xml287
-rw-r--r--handbook/extendpoky.xml2
-rw-r--r--handbook/poky-handbook.xml2
5 files changed, 361 insertions, 9 deletions
diff --git a/handbook/Makefile b/handbook/Makefile
index 4a4dd7e83f..01353b11af 100644
--- a/handbook/Makefile
+++ b/handbook/Makefile
@@ -3,18 +3,20 @@ all: html pdf tarball
3pdf: 3pdf:
4 4
5 ./poky-doc-tools/poky-docbook-to-pdf poky-handbook.xml 5 ./poky-doc-tools/poky-docbook-to-pdf poky-handbook.xml
6 ./poky-doc-tools/poky-docbook-to-pdf bsp-guide.xml
6# -- old way -- 7# -- old way --
7# dblatex poky-handbook.xml 8# dblatex poky-handbook.xml
8 9
10XSLTOPTS = --stringparam html.stylesheet style.css \
11 --stringparam chapter.autolabel 1 \
12 --stringparam appendix.autolabel 1 \
13 --stringparam section.autolabel 1
14XSLTOPTS2 = --xinclude /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl
15
9html: 16html:
10# See http://www.sagehill.net/docbookxsl/HtmlOutput.html 17# See http://www.sagehill.net/docbookxsl/HtmlOutput.html
11 xsltproc --stringparam html.stylesheet style.css \ 18 xsltproc $(XSLTOPTS) -o poky-handbook.html $(XSLTOPTS2) poky-handbook.xml
12 --stringparam chapter.autolabel 1 \ 19 xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSLTOPTS2) bsp-guide.xml
13 --stringparam appendix.autolabel 1 \
14 --stringparam section.autolabel 1 \
15 -o poky-handbook.html \
16 --xinclude /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl \
17 poky-handbook.xml
18# -- old way -- 20# -- old way --
19# xmlto xhtml-nochunks poky-handbook.xml 21# xmlto xhtml-nochunks poky-handbook.xml
20 22
@@ -24,7 +26,7 @@ tarball: html
24validate: 26validate:
25 xmllint --postvalid --xinclude --noout poky-handbook.xml 27 xmllint --postvalid --xinclude --noout poky-handbook.xml
26 28
27OUTPUTS = poky-handbook.tgz poky-handbook.html poky-handbook.pdf 29OUTPUTS = poky-handbook.tgz poky-handbook.html poky-handbook.pdf bsp-guide.pdf
28SOURCES = *.png *.xml *.css *.svg 30SOURCES = *.png *.xml *.css *.svg
29 31
30publish: 32publish:
diff --git a/handbook/bsp-guide.xml b/handbook/bsp-guide.xml
new file mode 100644
index 0000000000..e5933d7e9c
--- /dev/null
+++ b/handbook/bsp-guide.xml
@@ -0,0 +1,61 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<book id='poky-handbook' lang='en'
5 xmlns:xi="http://www.w3.org/2003/XInclude"
6 xmlns="http://docbook.org/ns/docbook"
7 >
8 <bookinfo>
9
10 <mediaobject>
11 <imageobject>
12 <imagedata fileref='common/poky-handbook.png'
13 format='SVG'
14 align='center' scalefit='1' width='100%'/>
15 </imageobject>
16 </mediaobject>
17
18 <title>Board Support Package (BSP) Developers Guide</title>
19
20 <authorgroup>
21 <author>
22 <firstname>Richard</firstname> <surname>Purdie</surname>
23 <affiliation>
24 <orgname>Intel Corporation</orgname>
25 </affiliation>
26 <email>richard@linux.intel.com</email>
27 </author>
28 </authorgroup>
29
30 <revhistory>
31 <revision>
32 <revnumber>0.4</revnumber>
33 <date>26 May 2010</date>
34 <revremark>Alpha Draft</revremark>
35 </revision>
36 </revhistory>
37
38 <copyright>
39 <year>2010</year>
40 <holder>Intel Corporation</holder>
41 </copyright>
42
43 <legalnotice>
44 <para>
45 Permission is granted to copy, distribute and/or modify this document under
46 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
47 </para>
48 </legalnotice>
49
50 </bookinfo>
51
52 <xi:include href="bsp.xml"/>
53
54 <index id='index'>
55 <title>Index</title>
56 </index>
57
58</book>
59<!--
60vim: expandtab tw=80 ts=4
61-->
diff --git a/handbook/bsp.xml b/handbook/bsp.xml
new file mode 100644
index 0000000000..37dd166749
--- /dev/null
+++ b/handbook/bsp.xml
@@ -0,0 +1,287 @@
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 which together
10 defines how to support a particular hardware device, set of devices or
11 hardware platform. It will include information about the hardware features
12 present on the device, kernel configuration information along with any
13 additional hardware drivers required and also any additional software
14 components required in addition to a generic Linux software stack for both
15 essential and optional platform features.
16 </para>
17
18 <para>
19 The intend of this document is to define a structure for these components
20 so that BSPs follow a commonly understood layout allowing them to be
21 provided in a common way that everyone understands. It also allows end
22 users to become familiar with one common format and encourages standardisation
23 of software support of hardware.
24 </para>
25
26 <para>
27 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 used by other systems besides Poky/OpenEmbedded and that it will be simple
30 to extract information and convert to other formats if required. The format
31 descriped can be directly accepted as a layer by Poky using its standard
32 layers mechanism but its important to recognise that the BSP captures all
33 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
35 the build system in use.
36 </para>
37
38 <para>
39 The BSP specification does not include a build system or other tooling,
40 it is concerned with the hardware specific components only. At the end
41 distribution point the BSP may be shipped combined with a build system
42 and other tools but it is important to maintain the distinction that these
43 are separate components which may just be combined in certain end products.
44 </para>
45
46 <section id='bsp-filelayout'>
47 <title>Example Filesystem Layout</title>
48
49 <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:
51 </para>
52
53 <para>
54 <programlisting>
55meta-bsp/
56meta-bsp/binary/zImage
57meta-bsp/binary/poky-image-minimal.directdisk
58meta-bsp/conf/layer.conf
59meta-bsp/conf/machine/*.conf
60meta-bsp/conf/machine/include/tune-*.inc
61meta-bsp/packages/bootloader/bootloader_0.1.bb
62meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch
63meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
64meta-bsp/packages/linux/linux-bsp_2.6.50.bb
65meta-bsp/packages/modem/modem-driver_0.1.bb
66meta-bsp/packages/modem/modem-daemon_0.1.bb
67meta-bsp/packages/image-creator/image-creator-native_0.1.bb
68meta-bsp/prebuilds/
69
70 </programlisting>
71 </para>
72
73 <para>
74 The following sections detail what these files and directories could contain.
75 </para>
76
77 </section>
78
79 <section id='bsp-filelayout-binary'>
80 <title>Prebuilt User Binaries (meta-bsp/binary/*)</title>
81
82 <para>
83 This optional area cotains useful prebuilt kernels and userspace filesystem
84 images appropriate to the target system. Users could use these to get a system
85 running and quickly get started on development tasks. The exact types of binaries
86 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
88 present, source code to meet licensing requirements must also be provided in
89 some form.
90 </para>
91
92 </section>
93
94 <section id='bsp-filelayout-layer'>
95 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
96
97 <para>
98 This file identifies the structure as a Poky layer. This file identifies the
99 contents of the layer and how contains information about how Poky should use
100 it. In general it will most likely be a standard boilerplate file consisting of:
101 </para>
102
103 <para>
104 <programlisting>
105# We have a conf directory, add to BBPATH
106BBPATH := "${BBPATH}${LAYERDIR}"
107
108# We have a packages directory, add to BBFILES
109BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb"
110
111BBFILE_COLLECTIONS += "meta-bsp"
112BBFILE_PATTERN_meta-bsp := "^${LAYERDIR}/"
113BBFILE_PRIORITY_meta-bsp = "5"
114 </programlisting>
115 </para>
116
117 <para>
118 which simply makes bitbake aware of the packages and conf directories.
119 </para>
120
121 <para>
122 This file is required for recognition of the BSP by Poky.
123 </para>
124
125 </section>
126
127 <section id='bsp-filelayout-machine'>
128 <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title>
129
130 <para>
131 The machine files bind together all the information contained elsewhere
132 in the BSP into a format that Poky/OpenEmbedded can understand it in. If
133 the BSP supports multiple machines, multiple machine configuration files
134 can be present. These filenames correspond to the values users set the
135 MACHINE variable to.
136 </para>
137
138 <para>
139 These files would define things like which kernel package to use
140 (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to
141 include in different types of images, any special software components
142 that are needed, any bootloader information and also any special image
143 format requirements.
144 </para>
145
146 <para>
147 At least one machine file is required for a Poky BSP layer but more than one may be present.
148 </para>
149
150 </section>
151
152 <section id='bsp-filelayout-tune'>
153 <title>Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
154
155 <para>
156 These are shared hardware "tuning" definitions and are commonly used to
157 pass specific optimisation flags to the compiler. An example is
158 tune-atom.inc:
159 </para>
160 <para>
161 <programlisting>
162BASE_PACKAGE_ARCH = "core2"
163TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
164 </programlisting>
165 </para>
166 <para>
167 which defines a new package architecture called "core2" and uses the
168 optimisation flags specified which are carefully chosen to give best
169 performance on atom cpus.
170 </para>
171 <para>
172 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
174 files included with Poky itself.
175 </para>
176 <para>
177 These files are optional for a Poky BSP layer.
178 </para>
179 </section>
180 <section id='bsp-filelayout-kernel'>
181 <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title>
182
183 <para>
184 These files make up the definition of a kernel to use with this
185 hardware. In this case its a complete self contained kernel with its own
186 configuration and patches but kernels can be shared between many
187 machines as well. Taking some specific example files:
188 </para>
189 <para>
190 <programlisting>
191meta-bsp/packages/linux/linux-bsp_2.6.50.bb
192 </programlisting>
193 </para>
194 <para>
195 which is the core kernel recipe which firstly details where to get the kernel
196 source from. All standard source code locations are supported so this could
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 meaning the definitions here can remain very simple.
201 </para>
202 <para>
203 <programlisting>
204linux-bsp-2.6.50/*.patch
205 </programlisting>
206 </para>
207 <para>
208 which are patches which may be applied against the base kernel, wherever
209 that may have been obtained from.
210 </para>
211 <para>
212 <programlisting>
213meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
214 </programlisting>
215 </para>
216 <para>
217 which is the configuration information to use to configure the kernel.
218 </para>
219 <para>
220 Examples of kernel recipes are available in Poky itself. These files are
221 optional since a kernel from Poky itself could be selected although it
222 would be unusual not to have a kernel configuration.
223 </para>
224 </section>
225
226 <section id='bsp-filelayout-packages'>
227 <title>Other Software (meta-bsp/packages/*)</title>
228
229 <para>
230 This area includes other pieces of software which the hardware may need for best
231 operation. These are just examples of the kind of things that may be
232 encountered. The are standard .bb file recipes in the usual Poky format
233 so for examples, see standard Poky recipes. The source can be included directly,
234 referred to in source control systems or release tarballs of external software projects.
235 </para>
236 <para>
237 <programlisting>
238meta-bsp/packages/bootloader/bootloader_0.1.bb
239 </programlisting>
240 </para>
241 <para>
242 Some kind of bootloader recipe which may be used to generate a new
243 bootloader binary. Sometimes these are included in the final image
244 format and needed to reflash hardware.
245 </para>
246 <para>
247 <programlisting>
248meta-bsp/packages/modem/modem-driver_0.1.bb
249meta-bsp/packages/modem/modem-daemon_0.1.bb
250 </programlisting>
251 </para>
252 <para>
253 These are examples of a hardware driver and also a hardware daemon which
254 may need to be included in images to make the hardware useful. "modem"
255 is one example but there may be other components needed like firmware.
256 </para>
257 <para>
258 <programlisting>
259meta-bsp/packages/image-creator/image-creator-native_0.1.bb
260 </programlisting>
261 </para>
262 <para>
263 Sometimes the device will need an image in a very specific format for
264 its update mechanism to accept and reflash with it. Recipes to build the
265 tools needed to do this can be included with the BSP.
266 </para>
267 <para>
268 These files only need be provided if the platform requires them.
269 </para>
270 </section>
271
272 <section id='bsp-filelayout-prebuilds'>
273 <title>Prebuild Data (meta-bsp/prebuilds/*)</title>
274
275 <para>
276 The location can contains a precompiled representation of the source code
277 contained elsewhere in the BSP layer. It can be processed and used by
278 Poky to provide much faster build times assuming a compatible configuration is used.
279 </para>
280
281 <para>
282 These files are optional.
283 </para>
284
285 </section>
286
287</chapter>
diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index df6441fad5..b6a8c786af 100644
--- a/handbook/extendpoky.xml
+++ b/handbook/extendpoky.xml
@@ -819,7 +819,7 @@ SRC_URI += "file://NAME-OF-PATCH.patch;patch=1"
819 819
820 </section> 820 </section>
821 821
822</section> 822 </section>
823 823
824</chapter> 824</chapter>
825<!-- 825<!--
diff --git a/handbook/poky-handbook.xml b/handbook/poky-handbook.xml
index 2e336bcd6b..1064a545a4 100644
--- a/handbook/poky-handbook.xml
+++ b/handbook/poky-handbook.xml
@@ -70,6 +70,8 @@
70 70
71 <xi:include href="extendpoky.xml"/> 71 <xi:include href="extendpoky.xml"/>
72 72
73 <xi:include href="bsp.xml"/>
74
73 <xi:include href="development.xml"/> 75 <xi:include href="development.xml"/>
74 76
75 <xi:include href="ref-structure.xml"/> 77 <xi:include href="ref-structure.xml"/>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-15 12:40:37 +0000