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>

2 files changed, 66 insertions, 29 deletions

diff --git a/handbook/bsp.xml b/handbook/bsp.xml
index 37dd166749..b897f0691d 100644
--- a/handbook/bsp.xml
+++ b/handbook/bsp.xml
@@ -28,18 +28,18 @@
             OpenEmbedded build systems. It is intended that this information can be 
             used by other systems besides Poky/OpenEmbedded and that it will be simple
             to extract information and convert to other formats if required. The format 
-            descriped can be directly accepted as a layer by Poky using its standard 
-            layers mechanism but its important to recognise that the BSP captures all 
-            the hardware specific details in one place in a standard format which is 
+            described can be directly accepted as a layer by Poky using its standard 
+            layers mechanism, but it is important to recognise that the BSP captures all 
+            the hardware specific details in one place in a standard format, which is 
             useful for any person wishing to use the hardware platform regardless of 
             the build system in use.
         </para>
 
         <para>
-            The BSP specification does not include a build system or other tooling, 
+            The BSP specification does not include a build system or other tools, 
             it is concerned with the hardware specific components only. At the end 
             distribution point the BSP may be shipped combined with a build system
-            and other tools but it is important to maintain the distinction that these
+            and other tools, but it is important to maintain the distinction that these
             are separate components which may just be combined in certain end products.
         </para>
 
@@ -47,7 +47,7 @@
             <title>Example Filesystem Layout</title>
 
             <para>
-                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:
+                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:
             </para>
 
             <para>
@@ -108,9 +108,9 @@ BBPATH := "${BBPATH}${LAYERDIR}"
 # We have a packages directory, add to BBFILES
 BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb"
 
-BBFILE_COLLECTIONS += "meta-bsp"
-BBFILE_PATTERN_meta-bsp := "^${LAYERDIR}/"
-BBFILE_PRIORITY_meta-bsp = "5"
+BBFILE_COLLECTIONS += "bsp"
+BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
+BBFILE_PRIORITY_bsp = "5"
                 </programlisting>
             </para>
 
@@ -129,7 +129,7 @@ BBFILE_PRIORITY_meta-bsp = "5"
 
             <para>
                 The machine files bind together all the information contained elsewhere
-                in the BSP into a format that Poky/OpenEmbedded can understand it in. If
+                in the BSP into a format that Poky/OpenEmbedded can understand. If
                 the BSP supports multiple machines, multiple machine configuration files
                 can be present. These filenames correspond to the values users set the
                 MACHINE variable to.
@@ -139,7 +139,7 @@ BBFILE_PRIORITY_meta-bsp = "5"
                 These files would define things like which kernel package to use
                 (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to
                 include in different types of images, any special software components
-                that are needed, any bootloader information and also any special image
+                that are needed, any bootloader information, and also any special image
                 format requirements.
             </para>
 
@@ -165,7 +165,7 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
             </para>
             <para>
                 which defines a new package architecture called "core2" and uses the
-                optimisation flags specified which are carefully chosen to give best
+                optimization flags specified, which are carefully chosen to give best
                 performance on atom cpus.
             </para>
             <para>
@@ -182,7 +182,7 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
 
             <para>
                 These files make up the definition of a kernel to use with this
-                hardware. In this case its a complete self contained kernel with its own
+                hardware. In this case it is a complete self contained kernel with its own
                 configuration and patches but kernels can be shared between many
                 machines as well. Taking some specific example files:
             </para>
@@ -197,7 +197,7 @@ meta-bsp/packages/linux/linux-bsp_2.6.50.bb
                 be a release tarball, some git repository or source included in
                 the directory within the BSP itself. It then contains information about which 
                 patches to apply and how to configure and build it. It can reuse the main
-                Poky kernel build class meaning the definitions here can remain very simple.
+                Poky kernel build class, so the definitions here can remain very simple.
             </para>
             <para>
                <programlisting>
@@ -229,7 +229,7 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
             <para>
                 This area includes other pieces of software which the hardware may need for best
                 operation. These are just examples of the kind of things that may be
-                encountered. The are standard .bb file recipes in the usual Poky format
+                encountered. The are standard .bb file recipes in the usual Poky format,
                 so for examples, see standard Poky recipes. The source can be included directly, 
                 referred to in source control systems or release tarballs of external software projects.
             </para>
@@ -269,6 +269,36 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
             </para>
         </section>
 
+        <section id='bs-filelayout-bbappend'>
+            <title>Append BSP specific information to existing recipes</title>
+
+            <para>
+            Say you have a recipe like pointercal which has machine specific information in it,
+            and then you have your new bsp code in a layer. Before .bbappend extension is
+            introduced, you have to copy the whole pointercal recipe and files into your layer,
+            and then add the single file for your machine which is ugly.
+
+            .bbappend makes above work much easier, to allow bsp specific information merged
+            with original recipe easily. When bitbake finds any X.bbappend files, they will be
+            included after bitbake loads X.bb but before finalise and any anonymous methods run.
+            This allows bsp layer to poke around and do whatever it might want to customise
+            the original recipe.
+
+            .bbappend is expected to include below two lines in the head (which may be changed
+            in the future):
+            </para>
+
+            <programlisting>
+THISDIR := "${@os.path.dirname(bb.data.getVar('FILE', d, True))}"
+FILESPATH =. "${@base_set_filespath(["${THISDIR}/${PN}"], d)}:"
+            </programlisting>
+
+            <para>
+            Then bsp could add machine specific config files in layer directory, which will be
+            added by bitbake. You could look at meta-emenlow/packages/formfactor as example
+            </para>
+        </section>
+
         <section id='bsp-filelayout-prebuilds'>
             <title>Prebuild Data (meta-bsp/prebuilds/*)</title>
 
diff --git a/handbook/ref-bitbake.xml b/handbook/ref-bitbake.xml
index ddf3c760f2..eaf9467950 100644
--- a/handbook/ref-bitbake.xml
+++ b/handbook/ref-bitbake.xml
@@ -6,7 +6,7 @@
     <title>Reference: Bitbake</title>
 
     <para>
-        Bitbake a program written in Python which interprets the metadata
+        Bitbake is a program written in Python that interprets the metadata
         that makes up Poky. At some point, people wonder what actually happens 
         when you type <command>bitbake poky-image-sato</command>. This section 
         aims to give an overview of what happens behind the scenes from a
@@ -16,7 +16,7 @@
     <para>
         It is worth noting that bitbake aims to be a generic "task" executor 
         capable of handling complex dependency relationships. As such it has no 
-        real knowledge of what the tasks its executing actually do. It just 
+        real knowledge of what the tasks it is executing actually do. It just 
         considers a list of tasks with dependencies and handles metadata 
         consisting of variables in a certain format which get passed to the 
         tasks.
@@ -26,7 +26,7 @@
         <title>Parsing</title>
 
         <para>
-            The first thing BitBake does is work out its configuration by 
+            The first thing BitBake does is that work out its configuration by 
             looking for a file called <filename>bitbake.conf</filename>.
             Bitbake searches through the <varname>BBPATH</varname> environment 
             variable looking for a <filename class="directory">conf/</filename> 
@@ -117,7 +117,7 @@
             specified on the commandline) and looks for providers of that target.
             Once a provider is selected, BitBake resolves all the dependencies for  
             the target. In the case of "poky-image-sato", it would lead to 
-            <filename>task-oh.bb</filename> and <filename>task-base.bb</filename>  
+            <filename>task-base.bb</filename>  
             which in turn would lead to packages like <application>Contacts</application>, 
             <application>Dates</application>, <application>BusyBox</application>
             and these in turn depend on glibc and the toolchain.
@@ -154,7 +154,8 @@
             "1" makes it likely the package will be used. 
             <glossterm><link
                     linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides 
-            any default preference. <glossterm><link
+            any <glossterm><link
+                    linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>. <glossterm><link
                     linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> 
             is often used to mark more 
             experimental new versions of packages until they've undergone sufficient 
@@ -176,7 +177,7 @@
             multi-core systems, BitBake considers each task as an independent 
             entity with a set of dependencies. There are many variables that 
             are used to signify these dependencies and more information can be found 
-            found about these in the <ulink url='http://bitbake.berlios.de/manual/'>
+            about these in the <ulink url='http://bitbake.berlios.de/manual/'>
             BitBake manual</ulink>. At a basic level it is sufficient to know 
         that BitBake uses the <glossterm><link
                 linkend='var-DEPENDS'>DEPENDS</link></glossterm> and 
@@ -196,7 +197,7 @@
             order. The build now starts with BitBake forking off threads up to
             the limit set in the <glossterm><link
                     linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable
-            as long there are tasks ready to run, i.e. tasks with all their
+            as long as there are tasks ready to run, i.e. tasks with all their
             dependencies met.
         </para>
 
@@ -271,9 +272,9 @@ Options:
                         target that failed, and those that depend on it,
                         cannot be remade, the other dependencies of these
                         targets can be processed all the same.
+  -a, --tryaltconfigs   continue with builds by trying to use alternative
+                        providers where possible.
   -f, --force           force run of specified cmd, regardless of stamp status
-  -i, --interactive     drop into the interactive mode also called the BitBake
-                        shell.
   -c CMD, --cmd=CMD     Specify task to execute. Note that this only executes
                         the specified task for the providee and the packages
                         it depends on, i.e. 'compile' does not implicitly call
@@ -286,6 +287,9 @@ Options:
   -D, --debug           Increase the debug level. You can specify this more
                         than once.
   -n, --dry-run         don't execute, just go through the motions
+  -S, --dump-signatures
+                        don't execute, just dump out the signature
+                        construction information
   -p, --parse-only      quit after parsing the BB files (developers only)
   -d, --disable-psyco   disable using the psyco just-in-time compiler (not
                         recommended)
@@ -294,13 +298,16 @@ Options:
                         what used to be bbread)
   -g, --graphviz        emit the dependency trees of the specified packages in
                         the dot syntax
-  -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
-                        Stop processing at the given list of dependencies when
-                        generating dependency graphs. This can help to make
-                        the graph more appealing
+  -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
+                        Assume these dependencies don't exist and are already
+                        provided (equivalent to ASSUME_PROVIDED). Useful to
+                        make dependency graphs more appealing
   -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
                         Show debug logging for the specified logging domains
-  -P, --profile         profile the command and print a report</screen>
+  -P, --profile         profile the command and print a report
+  -u UI, --ui=UI        userinterface to use
+  --revisions-changed   Set the exit code depending on whether upstream
+                        floating revisions have changed or not</screen>
 
     </section>