Poky Reference Manual: Removed the bsp.xml file.
Because I am single-sourcing the bsp.xml file that is used both as chapter 4 in the Poky Reference Manual and as the singe file in the BSP Guide I removed the bsp.xml file that was local to the poky-ref-manual folder. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
This commit is contained in:
parent
b1f69283b3
commit
c2f7ed472c
|
@ -1,469 +0,0 @@
|
||||||
<!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 that
|
|
||||||
defines how to support a particular hardware device, set of devices, or
|
|
||||||
hardware platform.
|
|
||||||
The BSP includes information about the hardware features
|
|
||||||
present on the device and kernel configuration information along with any
|
|
||||||
additional hardware drivers required.
|
|
||||||
The BSP also lists any additional software
|
|
||||||
components required in addition to a generic Linux software stack for both
|
|
||||||
essential and optional platform features.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This section (or document if you are reading the BSP Developer's Guide) defines
|
|
||||||
a structure for these components
|
|
||||||
so that BSPs follow a commonly understood layout.
|
|
||||||
Providing a common form allows end-users to understand and become familiar
|
|
||||||
with the layout.
|
|
||||||
A common form also encourages standardization
|
|
||||||
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 and OpenEmbedded and that it will be simple
|
|
||||||
to extract information and convert it to other formats if required.
|
|
||||||
Poky, through its standard layers mechanism, can directly accept The format
|
|
||||||
described as a layer.
|
|
||||||
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 they are using.
|
|
||||||
</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 you can ship the BSP combined with a build system
|
|
||||||
and other tools.
|
|
||||||
However, it is important to maintain the distinction that these
|
|
||||||
are separate components that happen to 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 are highly hardware-dependent.
|
|
||||||
However, a README file should be present
|
|
||||||
that explains 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, identifies the
|
|
||||||
contents of the layer and contains information about how Poky should use
|
|
||||||
it.
|
|
||||||
Generally, a standard boilerplate file consisting of the following works.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
# We have a conf directory, add to BBPATH
|
|
||||||
BBPATH := "${BBPATH}${LAYERDIR}"
|
|
||||||
|
|
||||||
# We have a recipes directory containing .bb and .bbappend files, add to BBFILES
|
|
||||||
BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend"
|
|
||||||
|
|
||||||
BBFILE_COLLECTIONS += "bsp"
|
|
||||||
BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
|
|
||||||
BBFILE_PRIORITY_bsp = "5"
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This file simply makes bitbake aware of the recipes and conf directories and 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 to which users have set the MACHINE variable.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
These files define things such as what kernel package to use
|
|
||||||
(PREFERRED_PROVIDER of virtual/kernel), what 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.
|
|
||||||
However, you can supply more than one file.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section id="bsp-filelayout-tune">
|
|
||||||
<title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
These are shared hardware "tuning" definitions and are commonly used to
|
|
||||||
pass specific optimization 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>
|
|
||||||
This example defines a new package architecture called "core2" and uses the
|
|
||||||
specified optimization flags, which are carefully chosen to give best
|
|
||||||
performance on atom processors.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The tune file would be included by the machine definition and can be
|
|
||||||
contained in the BSP or referenced from one of the standard core set of
|
|
||||||
files included with Poky itself.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Both the base package architecuture file and the tune file 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.
|
|
||||||
However, kernels can be shared between many machines as well.
|
|
||||||
Following is an example:
|
|
||||||
<programlisting>
|
|
||||||
meta-bsp/packages/linux/linux-bsp_2.6.50.bb
|
|
||||||
</programlisting>
|
|
||||||
This example file is the core kernel recipe that details from where to get the kernel
|
|
||||||
source.
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The file then contains information about what patches to apply and how to configure and build them.
|
|
||||||
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>
|
|
||||||
The above example file contains patches you can apply against the base kernel, from wherever
|
|
||||||
they may have been obtained.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Finally, this last example file contains kernel configuration information.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Examples of kernel recipes are available in Poky itself.
|
|
||||||
These files are optional since a kernel from Poky 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 section describes other pieces of software that the hardware might need for best
|
|
||||||
operation.
|
|
||||||
This section shows examples of the kinds of things that you could encounter.
|
|
||||||
The examples are standard <filename>.bb</filename> file recipes in the
|
|
||||||
usual Poky format.
|
|
||||||
You can include the source directly by referring to it in the source control system or
|
|
||||||
the released tarballs of external software projects.
|
|
||||||
You only need to provide these types of files if the platform requires them.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The following file is a bootloader recipe that can be used to generate a new
|
|
||||||
bootloader binary.
|
|
||||||
Sometimes these files are included in the final image format and are needed to re-flash hardware.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
meta-bsp/packages/bootloader/bootloader_0.1.bb
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
These next two files are examples of a hardware driver and a hardware daemon that might need
|
|
||||||
to be included in images to make the hardware useful.
|
|
||||||
Although the example uses "modem" there may be other components needed, such as firmware.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
meta-bsp/packages/modem/modem-driver_0.1.bb
|
|
||||||
meta-bsp/packages/modem/modem-daemon_0.1.bb
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Sometimes the device needs an image in a very specific format so that the update
|
|
||||||
mechanism can accept and re-flash it.
|
|
||||||
Recipes to build the tools needed to do this can be included with the BSP.
|
|
||||||
Following is an example.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
meta-bsp/packages/image-creator/image-creator-native_0.1.bb
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section id='bs-filelayout-bbappend'>
|
|
||||||
<title>Append BSP-Specific Information to Existing Recipes</title>
|
|
||||||
<para>
|
|
||||||
Suppose you have a recipe such as 'pointercal' that requires machine-specific information.
|
|
||||||
At the same time, you have your new BSP code nicely partitioned into a layer through which
|
|
||||||
you would also like to specify any machine-specific information associated with your new machine.
|
|
||||||
Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole
|
|
||||||
pointercal recipe and files into your layer and then add the single file for your machine.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
|
|
||||||
This extension allows you to easily merge BSP-specific information with the original recipe.
|
|
||||||
Whenever bitbake finds any <filename>.bbappend</filename> files they will be
|
|
||||||
included after bitbake loads the associated <filename>.bb</filename> but before any finalize
|
|
||||||
or anonymous methods run.
|
|
||||||
This allows the BSP layer to do whatever it might want to do to customize the original recipe.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable
|
|
||||||
to specify their location.
|
|
||||||
The example below shows extra files contained in a folder called ${PN} (the package name).
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
FILESEXTRAPATHS := "${THISDIR}/${PN}"
|
|
||||||
</programlisting>
|
|
||||||
<para>
|
|
||||||
This technique allows the BSP to add machine-specific configuration files to the layer directory,
|
|
||||||
which will be picked up by bitbake.
|
|
||||||
For an example see <filename>meta-emenlow/packages/formfactor</filename>.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section id="bsp-filelayout-prebuilds">
|
|
||||||
<title>Prebuild Data (meta-bsp/prebuilds/*)</title>
|
|
||||||
<para>
|
|
||||||
This location can contain precompiled representations of the source code
|
|
||||||
contained elsewhere in the BSP layer.
|
|
||||||
Assuming a compatible configuration is used, Poky can process and use these optional precompiled
|
|
||||||
representations to provide much faster build times.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section id='bsp-click-through-licensing'>
|
|
||||||
<title>BSP 'Click-Through' Licensing Procedure</title>
|
|
||||||
|
|
||||||
<note><para> This section describes how
|
|
||||||
click-through licensing is expected to work.
|
|
||||||
Currently, this functionality is not yet implemented.
|
|
||||||
</para></note>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
In some cases, a BSP contains separately licensed IP
|
|
||||||
(Intellectual Property) for a component that imposes
|
|
||||||
upon the user a requirement to accept the terms of a
|
|
||||||
'click-through' license.
|
|
||||||
Once the license is accepted the
|
|
||||||
Poky build system can then build and include the
|
|
||||||
corresponding component in the final BSP image.
|
|
||||||
Some affected components might 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).
|
|
||||||
On the other hand, other components might be simply
|
|
||||||
'good-to-have' or purely elective, or if essential
|
|
||||||
nonetheless have a 'free' (possibly less-capable)
|
|
||||||
version that could be used as a in the BSP recipe.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
For cases where you can substitute something and still maintain functionality, the Poky website will make
|
|
||||||
available a 'de-featured' BSP completely free of
|
|
||||||
the encumbered IP.
|
|
||||||
In that case you can use the substitution 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).
|
|
||||||
If available, this is the simplest the most preferred option.
|
|
||||||
This, of course, assumes 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.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Several methods exist within the Poky build system to satisfy the licensing
|
|
||||||
requirements for an encumbered BSP.
|
|
||||||
The following list describes them in preferential order:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<orderedlist>
|
|
||||||
<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 name of the BSP and your e-mail address in the web form.
|
|
||||||
</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
|
|
||||||
you gave and you can use them by specifying BSPKEY_<keydomain>
|
|
||||||
environment variables when building the image:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
$ BSPKEY_<keydomain>=<key> bitbake poky-image-sato
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
These steps 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
|
|
||||||
<filename>local.conf</filename> file.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <keydomain> component of the
|
|
||||||
BSPKEY_<keydomain> is required because there
|
|
||||||
might be multiple licenses in effect for a give BSP.
|
|
||||||
In such cases, a given <keydomain> corresponds to
|
|
||||||
a particular license. In order for an encumbered
|
|
||||||
BSP that encompasses multiple key domains to be built
|
|
||||||
successfully, a <keydomain> entry for each
|
|
||||||
applicable license must be present in <filename>local.conf</filename> or
|
|
||||||
supplied on the command-line.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Do nothing - build as you normally would.
|
|
||||||
When a license is needed the build will stop and prompt you with instructions.
|
|
||||||
Follow the license prompts that originate from the
|
|
||||||
encumbered BSP.
|
|
||||||
These prompts usually take the form of instructions
|
|
||||||
needed to manually fetch the encumbered package(s)
|
|
||||||
and md5 sums into the required directory (e.g. the poky/build/downloads)
|
|
||||||
Once the manual package fetch has been
|
|
||||||
completed, restart the build to continue where
|
|
||||||
it left off.
|
|
||||||
During the build the prompt will not appear again since you have satisfied the
|
|
||||||
requirement.
|
|
||||||
</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 that is 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>
|
|
||||||
</orderedlist>
|
|
||||||
<para>
|
|
||||||
Note that the third method 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>
|
|
Loading…
Reference in New Issue