handbook: Add alpha verison of a BSP specification

Signed-off-by: Richard Purdie <rpurdie@linux.intel.com>

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
 pdf:
 
         ./poky-doc-tools/poky-docbook-to-pdf poky-handbook.xml
+        ./poky-doc-tools/poky-docbook-to-pdf bsp-guide.xml
 #       -- old way --
 #       dblatex poky-handbook.xml
 
+XSLTOPTS = --stringparam html.stylesheet style.css \
+           --stringparam  chapter.autolabel 1 \
+           --stringparam  appendix.autolabel 1 \
+           --stringparam  section.autolabel 1
+XSLTOPTS2 = --xinclude /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl
+
 html:
 #       See http://www.sagehill.net/docbookxsl/HtmlOutput.html 
-        xsltproc --stringparam html.stylesheet style.css \
-                 --stringparam  chapter.autolabel 1 \
-                 --stringparam  appendix.autolabel 1 \
-                 --stringparam  section.autolabel 1 \
-                 -o poky-handbook.html \
-                 --xinclude /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl                                 \
-                  poky-handbook.xml
+        xsltproc $(XSLTOPTS) -o poky-handbook.html $(XSLTOPTS2) poky-handbook.xml
+        xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSLTOPTS2) bsp-guide.xml
 #       -- old way --
 #       xmlto xhtml-nochunks poky-handbook.xml
 
@@ -24,7 +26,7 @@ tarball: html
 validate:
         xmllint --postvalid --xinclude --noout poky-handbook.xml
 
-OUTPUTS = poky-handbook.tgz poky-handbook.html poky-handbook.pdf
+OUTPUTS = poky-handbook.tgz poky-handbook.html poky-handbook.pdf bsp-guide.pdf
 SOURCES = *.png *.xml *.css *.svg
 
 publish:
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 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<book id='poky-handbook' lang='en' 
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+    <bookinfo>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref='common/poky-handbook.png' 
+                    format='SVG' 
+                    align='center' scalefit='1' width='100%'/>
+            </imageobject>    
+        </mediaobject>
+
+        <title>Board Support Package (BSP) Developers Guide</title>
+
+        <authorgroup>
+            <author>
+                <firstname>Richard</firstname> <surname>Purdie</surname>
+                <affiliation>
+                    <orgname>Intel Corporation</orgname>
+                </affiliation>
+                <email>richard@linux.intel.com</email>
+            </author>
+        </authorgroup>
+
+        <revhistory>
+            <revision>
+                <revnumber>0.4</revnumber>
+                <date>26 May 2010</date>
+                <revremark>Alpha Draft</revremark>
+            </revision>
+        </revhistory>
+
+    <copyright>
+      <year>2010</year>
+      <holder>Intel Corporation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this document under 
+        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.
+      </para>
+    </legalnotice>
+
+    </bookinfo>
+
+    <xi:include href="bsp.xml"/>
+
+    <index id='index'>
+      <title>Index</title>
+    </index>
+
+</book>
+<!-- 
+vim: expandtab tw=80 ts=4 
+-->
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 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id='bsp'>
+
+        <title>Board Support Packages (BSP) - Developers Guide</title>
+
+        <para>
+            A Board Support Package (BSP) is a collection of information which together
+            defines how to support a particular hardware device, set of devices or 
+            hardware platform. It will include information about the hardware features 
+            present on the device, kernel configuration information along with any 
+            additional hardware drivers required and also any additional software 
+            components required in addition to a generic Linux software stack for both 
+            essential and optional platform features.
+        </para>
+
+        <para>
+            The intend of this document is to define a structure for these components
+            so that BSPs follow a commonly understood layout allowing them to be 
+            provided in a common way that everyone understands. It also allows end 
+            users to become familiar with one common format and encourages standardisation 
+            of software support of hardware.
+        </para>
+
+        <para>
+            The proposed format does have elements that are specific to the Poky and 
+            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 
+            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, 
+            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
+            are separate components which may just be combined in certain end products.
+        </para>
+
+        <section id='bsp-filelayout'>
+            <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:
+            </para>
+
+            <para>
+                <programlisting>
+meta-bsp/                                
+meta-bsp/binary/zImage
+meta-bsp/binary/poky-image-minimal.directdisk
+meta-bsp/conf/layer.conf 
+meta-bsp/conf/machine/*.conf             
+meta-bsp/conf/machine/include/tune-*.inc
+meta-bsp/packages/bootloader/bootloader_0.1.bb
+meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch
+meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
+meta-bsp/packages/linux/linux-bsp_2.6.50.bb
+meta-bsp/packages/modem/modem-driver_0.1.bb
+meta-bsp/packages/modem/modem-daemon_0.1.bb
+meta-bsp/packages/image-creator/image-creator-native_0.1.bb
+meta-bsp/prebuilds/
+
+                </programlisting>
+            </para>
+
+            <para>
+                The following sections detail what these files and directories could contain.
+            </para>
+
+        </section>
+
+        <section id='bsp-filelayout-binary'>
+            <title>Prebuilt User Binaries (meta-bsp/binary/*)</title>
+
+            <para>
+                This optional area cotains useful prebuilt kernels and userspace filesystem 
+                images appropriate to the target system. Users could use these to get a system 
+                running and quickly get started on development tasks. The exact types of binaries
+                present will be highly hardware dependent but a README file should be present 
+                explaining how to use them with the target hardware. If prebuilt binaries are 
+                present, source code to meet licensing requirements must also be provided in 
+                some form.
+            </para>
+       
+        </section>
+
+        <section id='bsp-filelayout-layer'>
+            <title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
+
+            <para>
+                This file identifies the structure as a Poky layer. This file identifies the 
+                contents of the layer and how contains information about how Poky should use 
+                it. In general it will most likely be a standard boilerplate file consisting of:
+            </para>
+
+            <para>
+               <programlisting>
+# We have a conf directory, add to BBPATH
+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"
+                </programlisting>
+            </para>
+
+            <para>
+                which simply makes bitbake aware of the packages and conf directories.
+            </para>
+
+            <para>
+                This file is required for recognition of the BSP by Poky.
+            </para>
+
+        </section>
+
+        <section id='bsp-filelayout-machine'>
+            <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title>
+
+            <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
+                the BSP supports multiple machines, multiple machine configuration files
+                can be present. These filenames correspond to the values users set the
+                MACHINE variable to.
+            </para>
+
+            <para>
+                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
+                format requirements.
+            </para>
+
+            <para>
+                At least one machine file is required for a Poky BSP layer but more than one may be present.
+            </para>
+
+        </section>
+
+        <section id='bsp-filelayout-tune'>
+            <title>Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
+
+            <para>
+                These are shared hardware "tuning" definitions and are commonly used to
+                pass specific optimisation flags to the compiler. An example is
+                tune-atom.inc:
+            </para>
+            <para>
+               <programlisting>
+BASE_PACKAGE_ARCH = "core2"
+TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
+               </programlisting>
+            </para>
+            <para>
+                which defines a new package architecture called "core2" and uses the
+                optimisation flags specified which are carefully chosen to give best
+                performance on atom cpus.
+            </para>
+            <para>
+                The tune file would be included by the machine definition and can be
+                contained in the BSP or reference one from the standard core set of
+                files included with Poky itself.
+            </para>
+            <para>
+                These files are optional for a Poky BSP layer.
+            </para>
+        </section>
+        <section id='bsp-filelayout-kernel'>
+            <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title>
+
+            <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
+                configuration and patches but kernels can be shared between many
+                machines as well. Taking some specific example files:
+            </para>
+            <para>
+               <programlisting>
+meta-bsp/packages/linux/linux-bsp_2.6.50.bb
+               </programlisting>
+            </para>
+            <para>
+                which is the core kernel recipe which firstly details where to get the kernel
+                source from. All standard source code locations are supported so this could 
+                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.
+            </para>
+            <para>
+               <programlisting>
+linux-bsp-2.6.50/*.patch
+               </programlisting>
+            </para>
+            <para>
+                which are patches which may be applied against the base kernel, wherever
+                that may have been obtained from.
+            </para>
+            <para>
+               <programlisting>
+meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
+               </programlisting>
+            </para>
+            <para>
+                which is the configuration information to use to configure the kernel.
+            </para>
+            <para>
+                Examples of kernel recipes are available in Poky itself. These files are
+                optional since a kernel from Poky itself could be selected although it
+                would be unusual not to have a kernel configuration.
+            </para>
+        </section>
+
+        <section id='bsp-filelayout-packages'>
+            <title>Other Software (meta-bsp/packages/*)</title>
+
+            <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
+                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>
+            <para>
+               <programlisting>
+meta-bsp/packages/bootloader/bootloader_0.1.bb
+               </programlisting>
+            </para>
+            <para>
+                Some kind of bootloader recipe which may be used to generate a new
+                bootloader binary. Sometimes these are included in the final image
+                format and needed to reflash hardware.
+            </para>
+            <para>
+               <programlisting>
+meta-bsp/packages/modem/modem-driver_0.1.bb
+meta-bsp/packages/modem/modem-daemon_0.1.bb
+               </programlisting>
+            </para>
+            <para>
+                These are examples of a hardware driver and also a hardware daemon which
+                may need to be included in images to make the hardware useful. "modem"
+                is one example but there may be other components needed like firmware.
+            </para>
+            <para>
+               <programlisting>
+meta-bsp/packages/image-creator/image-creator-native_0.1.bb
+               </programlisting>
+            </para>
+            <para>
+                Sometimes the device will need an image in a very specific format for
+                its update mechanism to accept and reflash with it. Recipes to build the
+                tools needed to do this can be included with the BSP.
+            </para>
+            <para>
+                These files only need be provided if the platform requires them.
+            </para>
+        </section>
+
+        <section id='bsp-filelayout-prebuilds'>
+            <title>Prebuild Data (meta-bsp/prebuilds/*)</title>
+
+            <para>
+                The location can contains a precompiled representation of the source code 
+                contained elsewhere in the BSP layer. It can be processed and used by
+                Poky to provide much faster build times assuming a compatible configuration is used.
+            </para>
+
+            <para>
+                These files are optional.
+            </para>
+
+        </section>
+
+</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"
 
         </section>
 
-</section>
+    </section>
 
 </chapter>
 <!-- 
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 @@
 
     <xi:include href="extendpoky.xml"/>
 
+    <xi:include href="bsp.xml"/>
+
     <xi:include href="development.xml"/>
 
     <xi:include href="ref-structure.xml"/>