handbook: Add alpha verison of a BSP specification
Signed-off-by: Richard Purdie <rpurdie@linux.intel.com>
This commit is contained in:
parent
a49e605a52
commit
d630317b6b
|
@ -3,18 +3,20 @@ all: html pdf tarball
|
||||||
pdf:
|
pdf:
|
||||||
|
|
||||||
./poky-doc-tools/poky-docbook-to-pdf poky-handbook.xml
|
./poky-doc-tools/poky-docbook-to-pdf poky-handbook.xml
|
||||||
|
./poky-doc-tools/poky-docbook-to-pdf bsp-guide.xml
|
||||||
# -- old way --
|
# -- old way --
|
||||||
# dblatex poky-handbook.xml
|
# 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:
|
html:
|
||||||
# See http://www.sagehill.net/docbookxsl/HtmlOutput.html
|
# See http://www.sagehill.net/docbookxsl/HtmlOutput.html
|
||||||
xsltproc --stringparam html.stylesheet style.css \
|
xsltproc $(XSLTOPTS) -o poky-handbook.html $(XSLTOPTS2) poky-handbook.xml
|
||||||
--stringparam chapter.autolabel 1 \
|
xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSLTOPTS2) bsp-guide.xml
|
||||||
--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
|
|
||||||
# -- old way --
|
# -- old way --
|
||||||
# xmlto xhtml-nochunks poky-handbook.xml
|
# xmlto xhtml-nochunks poky-handbook.xml
|
||||||
|
|
||||||
|
@ -24,7 +26,7 @@ tarball: html
|
||||||
validate:
|
validate:
|
||||||
xmllint --postvalid --xinclude --noout poky-handbook.xml
|
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
|
SOURCES = *.png *.xml *.css *.svg
|
||||||
|
|
||||||
publish:
|
publish:
|
||||||
|
|
|
@ -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 & 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
|
||||||
|
-->
|
|
@ -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>
|
|
@ -819,7 +819,7 @@ SRC_URI += "file://NAME-OF-PATCH.patch;patch=1"
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
</chapter>
|
</chapter>
|
||||||
<!--
|
<!--
|
||||||
|
|
|
@ -70,6 +70,8 @@
|
||||||
|
|
||||||
<xi:include href="extendpoky.xml"/>
|
<xi:include href="extendpoky.xml"/>
|
||||||
|
|
||||||
|
<xi:include href="bsp.xml"/>
|
||||||
|
|
||||||
<xi:include href="development.xml"/>
|
<xi:include href="development.xml"/>
|
||||||
|
|
||||||
<xi:include href="ref-structure.xml"/>
|
<xi:include href="ref-structure.xml"/>
|
||||||
|
|
Loading…
Reference in New Issue