452 lines
19 KiB
XML
452 lines
19 KiB
XML
<!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 and kernel configuration information along with any
|
|
additional hardware drivers required. It will also list any additional software
|
|
components required in addition to a generic Linux software stack for both
|
|
essential and optional platform features.
|
|
</para>
|
|
|
|
<para>
|
|
The intent 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 form 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
|
|
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 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
|
|
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 contains 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 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 += "bsp"
|
|
BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
|
|
BBFILE_PRIORITY_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. 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
|
|
optimization 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 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>
|
|
<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, so 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
|
|
they 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. These 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='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 the .bbappend extension was
|
|
introduced, you'd 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 the above work much easier, to allow BSP-specific information to be merged
|
|
with the original recipe easily. When bitbake finds any X.bbappend files, they will be
|
|
included after bitbake loads X.bb but before finalise or anonymous methods run.
|
|
This allows the BSP layer to poke around and do whatever it might want to customise
|
|
the original recipe.
|
|
|
|
.bbappend is expected to include the 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 the BSP could add machine-specific config files in layer directory, which will be
|
|
added by bitbake. You can look at meta-emenlow/packages/formfactor as an example.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='bsp-filelayout-prebuilds'>
|
|
<title>Prebuild Data (meta-bsp/prebuilds/*)</title>
|
|
|
|
<para>
|
|
The location can contain 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>
|
|
|
|
<section id='bsp-click-through-licensing'>
|
|
<title>BSP 'Click-through' Licensing Procedure</title>
|
|
|
|
<note><para> This section is here as a description of how
|
|
click-through licensing is expected to work, and is
|
|
not yet not impemented.
|
|
</para></note>
|
|
|
|
<para>
|
|
In some cases, a BSP may contain separately licensed IP
|
|
(Intellectual Property) for a component, which imposes
|
|
upon the user a requirement to accept the terms of a
|
|
'click-through' license. Once the license is accepted
|
|
(in whatever form that may be, see details below) the
|
|
Poky build system can then build and include the
|
|
corresponding component in the final BSP image. Some
|
|
affected components may be essential to the normal
|
|
functioning of the system and have no 'free' replacement
|
|
i.e. the resulting system would be non-functional
|
|
without them. Other components may be simply
|
|
'good-to-have' or purely elective, or if essential
|
|
nonetheless have a 'free' (possibly less-capable)
|
|
version which may substituted for in the BSP recipe.
|
|
</para>
|
|
|
|
<para>
|
|
For the latter cases, where it is possible to do so from
|
|
a functionality perspective, the Poky website will make
|
|
available a 'de-featured' BSP completely free of
|
|
encumbered IP, which can be used directly and without
|
|
any further licensing requirements. If present, this
|
|
fully 'de-featured' BSP will be named meta-bsp (i.e. the
|
|
normal default naming convention). This is the simplest
|
|
and therefore preferred option if available, assuming
|
|
the resulting functionality meets requirements.
|
|
</para>
|
|
|
|
<para>
|
|
If however, a non-encumbered version is unavailable or
|
|
the 'free' version would provide unsuitable
|
|
functionality or quality, an encumbered version can be
|
|
used. Encumbered versions of a BSP are given names of
|
|
the form meta-bsp-nonfree. There are several ways
|
|
within the Poky build system to satisfy the licensing
|
|
requirements for an encumbered BSP, in roughly the
|
|
following order of preference:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
|
|
<para>
|
|
Get a license key (or keys) for the encumbered BSP
|
|
by
|
|
visiting <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
|
|
and give the web form there the name of the BSP
|
|
and your e-mail address.
|
|
</para>
|
|
|
|
<programlisting>
|
|
[screenshot of dialog box]
|
|
</programlisting>
|
|
|
|
<para>
|
|
After agreeing to any applicable license terms, the
|
|
BSP key(s) will be immediately sent to the address
|
|
given and can be used by specifying BSPKEY_<keydomain>
|
|
environment variables when building the image:
|
|
</para>
|
|
|
|
<programlisting>
|
|
$ BSPKEY_<keydomain>=<key> bitbake poky-image-sato
|
|
</programlisting>
|
|
|
|
<para>
|
|
This will allow the encumbered image to be built
|
|
with no change at all to the normal build process.
|
|
</para>
|
|
|
|
<para>
|
|
Equivalently and probably more conveniently, a line
|
|
for each key can instead be put into the user's
|
|
local.conf file.
|
|
</para>
|
|
|
|
<para>
|
|
The <keydomain> component of the
|
|
BSPKEY_<keydomain> is required because there
|
|
may be multiple licenses in effect for a give BSP; a
|
|
given <keydomain> in such cases corresponds to
|
|
a particular license. In order for an encumbered
|
|
BSP encompassing multiple key domains to be built
|
|
successfully, a <keydomain> entry for each
|
|
applicable license must be present in local.conf or
|
|
supplied on the command-line.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Do nothing - build as you normally would, and follow
|
|
any license prompts that originate from the
|
|
encumbered BSP (the build will cleanly stop at this
|
|
point). These usually take the form of instructions
|
|
needed to manually fetch the encumbered package(s)
|
|
and md5 sums into e.g. the poky/build/downloads
|
|
directory. Once the manual package fetch has been
|
|
completed, restarting the build will continue where
|
|
it left off, this time without the prompt since the
|
|
license requirements will have been satisfied.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Get a full-featured BSP recipe rather than a key, by
|
|
visiting
|
|
<ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
|
|
Accepting the license agreement(s) presented will
|
|
subsequently allow you to download a tarball
|
|
containing a full-featured BSP legally cleared for
|
|
your use by the just-given license agreement(s).
|
|
This method will also allow the encumbered image to
|
|
be built with no change at all to the normal build
|
|
process.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Note that method 3 is also the only option available
|
|
when downloading pre-compiled images generated from
|
|
non-free BSPs. Those images are likewise available at
|
|
<ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
|
|
</para>
|
|
</section>
|
|
|
|
</chapter>
|