summaryrefslogtreecommitdiffstats
path: root/handbook
diff options
context:
space:
mode:
authorZhai Edwin <edwin.zhai@intel.com>2010-09-09 08:23:01 (GMT)
committerRichard Purdie <rpurdie@linux.intel.com>2010-09-10 11:20:44 (GMT)
commit8c7e1aced86cbef5f7856bb59c2190bb408dd024 (patch)
tree27720d67eccdc586709168bdd03a27bd57ba3184 /handbook
parent2beaecb35133aa9006a8b3ce79b4dee202fc35b2 (diff)
downloadpoky-8c7e1aced86cbef5f7856bb59c2190bb408dd024.tar.gz
handbook: review and modify CH4 (BSP) and Appendix B
Besides basic corrections, also add .bbappend to bsp introduction and update bitbake help to match latest output Signed-off-by: Zhai Edwin <edwin.zhai@intel.com> Signed-off-by: Dexuan Cui <dexuan.cui@intel.com> Signed-off-by: Kevin Tian <kevin.tian@intel.com>
Diffstat (limited to 'handbook')
-rw-r--r--handbook/bsp.xml60
-rw-r--r--handbook/ref-bitbake.xml35
2 files changed, 66 insertions, 29 deletions
diff --git a/handbook/bsp.xml b/handbook/bsp.xml
index 37dd166..b897f06 100644
--- a/handbook/bsp.xml
+++ b/handbook/bsp.xml
@@ -28,18 +28,18 @@
28 OpenEmbedded build systems. It is intended that this information can be 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 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 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 31 described 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 32 layers mechanism, but it is important to recognise that the BSP captures all
33 the hardware specific details in one place in a standard format which is 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 34 useful for any person wishing to use the hardware platform regardless of
35 the build system in use. 35 the build system in use.
36 </para> 36 </para>
37 37
38 <para> 38 <para>
39 The BSP specification does not include a build system or other tooling, 39 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 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 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 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. 43 are separate components which may just be combined in certain end products.
44 </para> 44 </para>
45 45
@@ -47,7 +47,7 @@
47 <title>Example Filesystem Layout</title> 47 <title>Example Filesystem Layout</title>
48 48
49 <para> 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: 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> 51 </para>
52 52
53 <para> 53 <para>
@@ -108,9 +108,9 @@ BBPATH := "${BBPATH}${LAYERDIR}"
108# We have a packages directory, add to BBFILES 108# We have a packages directory, add to BBFILES
109BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb" 109BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb"
110 110
111BBFILE_COLLECTIONS += "meta-bsp" 111BBFILE_COLLECTIONS += "bsp"
112BBFILE_PATTERN_meta-bsp := "^${LAYERDIR}/" 112BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
113BBFILE_PRIORITY_meta-bsp = "5" 113BBFILE_PRIORITY_bsp = "5"
114 </programlisting> 114 </programlisting>
115 </para> 115 </para>
116 116
@@ -129,7 +129,7 @@ BBFILE_PRIORITY_meta-bsp = "5"
129 129
130 <para> 130 <para>
131 The machine files bind together all the information contained elsewhere 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 132 in the BSP into a format that Poky/OpenEmbedded can understand. If
133 the BSP supports multiple machines, multiple machine configuration files 133 the BSP supports multiple machines, multiple machine configuration files
134 can be present. These filenames correspond to the values users set the 134 can be present. These filenames correspond to the values users set the
135 MACHINE variable to. 135 MACHINE variable to.
@@ -139,7 +139,7 @@ BBFILE_PRIORITY_meta-bsp = "5"
139 These files would define things like which kernel package to use 139 These files would define things like which kernel package to use
140 (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to 140 (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to
141 include in different types of images, any special software components 141 include in different types of images, any special software components
142 that are needed, any bootloader information and also any special image 142 that are needed, any bootloader information, and also any special image
143 format requirements. 143 format requirements.
144 </para> 144 </para>
145 145
@@ -165,7 +165,7 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
165 </para> 165 </para>
166 <para> 166 <para>
167 which defines a new package architecture called "core2" and uses the 167 which defines a new package architecture called "core2" and uses the
168 optimisation flags specified which are carefully chosen to give best 168 optimization flags specified, which are carefully chosen to give best
169 performance on atom cpus. 169 performance on atom cpus.
170 </para> 170 </para>
171 <para> 171 <para>
@@ -182,7 +182,7 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
182 182
183 <para> 183 <para>
184 These files make up the definition of a kernel to use with this 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 185 hardware. In this case it is a complete self contained kernel with its own
186 configuration and patches but kernels can be shared between many 186 configuration and patches but kernels can be shared between many
187 machines as well. Taking some specific example files: 187 machines as well. Taking some specific example files:
188 </para> 188 </para>
@@ -197,7 +197,7 @@ meta-bsp/packages/linux/linux-bsp_2.6.50.bb
197 be a release tarball, some git repository or source included in 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 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 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. 200 Poky kernel build class, so the definitions here can remain very simple.
201 </para> 201 </para>
202 <para> 202 <para>
203 <programlisting> 203 <programlisting>
@@ -229,7 +229,7 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
229 <para> 229 <para>
230 This area includes other pieces of software which the hardware may need for best 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 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 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, 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. 234 referred to in source control systems or release tarballs of external software projects.
235 </para> 235 </para>
@@ -269,6 +269,36 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
269 </para> 269 </para>
270 </section> 270 </section>
271 271
272 <section id='bs-filelayout-bbappend'>
273 <title>Append BSP specific information to existing recipes</title>
274
275 <para>
276 Say you have a recipe like pointercal which has machine specific information in it,
277 and then you have your new bsp code in a layer. Before .bbappend extension is
278 introduced, you have to copy the whole pointercal recipe and files into your layer,
279 and then add the single file for your machine which is ugly.
280
281 .bbappend makes above work much easier, to allow bsp specific information merged
282 with original recipe easily. When bitbake finds any X.bbappend files, they will be
283 included after bitbake loads X.bb but before finalise and any anonymous methods run.
284 This allows bsp layer to poke around and do whatever it might want to customise
285 the original recipe.
286
287 .bbappend is expected to include below two lines in the head (which may be changed
288 in the future):
289 </para>
290
291 <programlisting>
292THISDIR := "${@os.path.dirname(bb.data.getVar('FILE', d, True))}"
293FILESPATH =. "${@base_set_filespath(["${THISDIR}/${PN}"], d)}:"
294 </programlisting>
295
296 <para>
297 Then bsp could add machine specific config files in layer directory, which will be
298 added by bitbake. You could look at meta-emenlow/packages/formfactor as example
299 </para>
300 </section>
301
272 <section id='bsp-filelayout-prebuilds'> 302 <section id='bsp-filelayout-prebuilds'>
273 <title>Prebuild Data (meta-bsp/prebuilds/*)</title> 303 <title>Prebuild Data (meta-bsp/prebuilds/*)</title>
274 304
diff --git a/handbook/ref-bitbake.xml b/handbook/ref-bitbake.xml
index ddf3c76..eaf9467 100644
--- a/handbook/ref-bitbake.xml
+++ b/handbook/ref-bitbake.xml
@@ -6,7 +6,7 @@
6 <title>Reference: Bitbake</title> 6 <title>Reference: Bitbake</title>
7 7
8 <para> 8 <para>
9 Bitbake a program written in Python which interprets the metadata 9 Bitbake is a program written in Python that interprets the metadata
10 that makes up Poky. At some point, people wonder what actually happens 10 that makes up Poky. At some point, people wonder what actually happens
11 when you type <command>bitbake poky-image-sato</command>. This section 11 when you type <command>bitbake poky-image-sato</command>. This section
12 aims to give an overview of what happens behind the scenes from a 12 aims to give an overview of what happens behind the scenes from a
@@ -16,7 +16,7 @@
16 <para> 16 <para>
17 It is worth noting that bitbake aims to be a generic "task" executor 17 It is worth noting that bitbake aims to be a generic "task" executor
18 capable of handling complex dependency relationships. As such it has no 18 capable of handling complex dependency relationships. As such it has no
19 real knowledge of what the tasks its executing actually do. It just 19 real knowledge of what the tasks it is executing actually do. It just
20 considers a list of tasks with dependencies and handles metadata 20 considers a list of tasks with dependencies and handles metadata
21 consisting of variables in a certain format which get passed to the 21 consisting of variables in a certain format which get passed to the
22 tasks. 22 tasks.
@@ -26,7 +26,7 @@
26 <title>Parsing</title> 26 <title>Parsing</title>
27 27
28 <para> 28 <para>
29 The first thing BitBake does is work out its configuration by 29 The first thing BitBake does is that work out its configuration by
30 looking for a file called <filename>bitbake.conf</filename>. 30 looking for a file called <filename>bitbake.conf</filename>.
31 Bitbake searches through the <varname>BBPATH</varname> environment 31 Bitbake searches through the <varname>BBPATH</varname> environment
32 variable looking for a <filename class="directory">conf/</filename> 32 variable looking for a <filename class="directory">conf/</filename>
@@ -117,7 +117,7 @@
117 specified on the commandline) and looks for providers of that target. 117 specified on the commandline) and looks for providers of that target.
118 Once a provider is selected, BitBake resolves all the dependencies for 118 Once a provider is selected, BitBake resolves all the dependencies for
119 the target. In the case of "poky-image-sato", it would lead to 119 the target. In the case of "poky-image-sato", it would lead to
120 <filename>task-oh.bb</filename> and <filename>task-base.bb</filename> 120 <filename>task-base.bb</filename>
121 which in turn would lead to packages like <application>Contacts</application>, 121 which in turn would lead to packages like <application>Contacts</application>,
122 <application>Dates</application>, <application>BusyBox</application> 122 <application>Dates</application>, <application>BusyBox</application>
123 and these in turn depend on glibc and the toolchain. 123 and these in turn depend on glibc and the toolchain.
@@ -154,7 +154,8 @@
154 "1" makes it likely the package will be used. 154 "1" makes it likely the package will be used.
155 <glossterm><link 155 <glossterm><link
156 linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides 156 linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides
157 any default preference. <glossterm><link 157 any <glossterm><link
158 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>. <glossterm><link
158 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> 159 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>
159 is often used to mark more 160 is often used to mark more
160 experimental new versions of packages until they've undergone sufficient 161 experimental new versions of packages until they've undergone sufficient
@@ -176,7 +177,7 @@
176 multi-core systems, BitBake considers each task as an independent 177 multi-core systems, BitBake considers each task as an independent
177 entity with a set of dependencies. There are many variables that 178 entity with a set of dependencies. There are many variables that
178 are used to signify these dependencies and more information can be found 179 are used to signify these dependencies and more information can be found
179 found about these in the <ulink url='http://bitbake.berlios.de/manual/'> 180 about these in the <ulink url='http://bitbake.berlios.de/manual/'>
180 BitBake manual</ulink>. At a basic level it is sufficient to know 181 BitBake manual</ulink>. At a basic level it is sufficient to know
181 that BitBake uses the <glossterm><link 182 that BitBake uses the <glossterm><link
182 linkend='var-DEPENDS'>DEPENDS</link></glossterm> and 183 linkend='var-DEPENDS'>DEPENDS</link></glossterm> and
@@ -196,7 +197,7 @@
196 order. The build now starts with BitBake forking off threads up to 197 order. The build now starts with BitBake forking off threads up to
197 the limit set in the <glossterm><link 198 the limit set in the <glossterm><link
198 linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable 199 linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable
199 as long there are tasks ready to run, i.e. tasks with all their 200 as long as there are tasks ready to run, i.e. tasks with all their
200 dependencies met. 201 dependencies met.
201 </para> 202 </para>
202 203
@@ -271,9 +272,9 @@ Options:
271 target that failed, and those that depend on it, 272 target that failed, and those that depend on it,
272 cannot be remade, the other dependencies of these 273 cannot be remade, the other dependencies of these
273 targets can be processed all the same. 274 targets can be processed all the same.
275 -a, --tryaltconfigs continue with builds by trying to use alternative
276 providers where possible.
274 -f, --force force run of specified cmd, regardless of stamp status 277 -f, --force force run of specified cmd, regardless of stamp status
275 -i, --interactive drop into the interactive mode also called the BitBake
276 shell.
277 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes 278 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
278 the specified task for the providee and the packages 279 the specified task for the providee and the packages
279 it depends on, i.e. 'compile' does not implicitly call 280 it depends on, i.e. 'compile' does not implicitly call
@@ -286,6 +287,9 @@ Options:
286 -D, --debug Increase the debug level. You can specify this more 287 -D, --debug Increase the debug level. You can specify this more
287 than once. 288 than once.
288 -n, --dry-run don't execute, just go through the motions 289 -n, --dry-run don't execute, just go through the motions
290 -S, --dump-signatures
291 don't execute, just dump out the signature
292 construction information
289 -p, --parse-only quit after parsing the BB files (developers only) 293 -p, --parse-only quit after parsing the BB files (developers only)
290 -d, --disable-psyco disable using the psyco just-in-time compiler (not 294 -d, --disable-psyco disable using the psyco just-in-time compiler (not
291 recommended) 295 recommended)
@@ -294,13 +298,16 @@ Options:
294 what used to be bbread) 298 what used to be bbread)
295 -g, --graphviz emit the dependency trees of the specified packages in 299 -g, --graphviz emit the dependency trees of the specified packages in
296 the dot syntax 300 the dot syntax
297 -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS 301 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
298 Stop processing at the given list of dependencies when 302 Assume these dependencies don't exist and are already
299 generating dependency graphs. This can help to make 303 provided (equivalent to ASSUME_PROVIDED). Useful to
300 the graph more appealing 304 make dependency graphs more appealing
301 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS 305 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
302 Show debug logging for the specified logging domains 306 Show debug logging for the specified logging domains
303 -P, --profile profile the command and print a report</screen> 307 -P, --profile profile the command and print a report
308 -u UI, --ui=UI userinterface to use
309 --revisions-changed Set the exit code depending on whether upstream
310 floating revisions have changed or not</screen>
304 311
305 </section> 312 </section>
306 313