-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<chapter id='bsp'>
+<!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
+ 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. It will include information about the hardware features
+ 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. It will also list any additional software
+ 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>
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
+ 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/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
+ OpenEmbedded build systems.
+ It is intended that this information can be
+ used by other systems besides Poky and OpenEmbedded and thatspecified it will be simple
+ to extract information and convert it to other formats if required.
+ Poky, through its standard slyers 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 in use.
+ the build system being used.
</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.
+ it is concerned with the hardware-specific components only.
+ At the end
+ distribution point you can shipt 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'>
+ <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:
+ 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>
</section>
- <section id='bsp-filelayout-binary'>
+ <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
+ 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
+ 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>
<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:
+ This file identifies the structure as a Poky layer by identifying the
+ contents of the layer and containing information about how Poky should use
+ it.
+ Generally, a standard boilerplate file consisting of the following works.
</para>
<para>
BBPATH := "${BBPATH}${LAYERDIR}"
# We have a recipes directory containing .bb and .bbappend files, add to BBFILES
-BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb ${LAYERDIR}/recipes/*/*.bbappend"
+BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend"
BBFILE_COLLECTIONS += "bsp"
BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
</para>
<para>
- which simply makes bitbake aware of the recipes and conf directories.
- </para>
-
- <para>
- This file is required for recognition of the BSP by Poky.
+ 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'>
+ <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.
+ 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 would define things like which kernel package to use
- (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to
+ 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 but more than one may be present.
+ 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 Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
+ <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 optimisation flags to the compiler. An example is
- tune-atom.inc:
+ pass specific optimization flags to the compiler.
+ An example is tune-atom.inc:
</para>
<para>
<programlisting>
</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.
+ 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 reference one from the standard core set of
+ contained in the BSP or referenced from one of the standard core set of
files included with Poky itself.
</para>
<para>
- These files are optional for a Poky BSP layer.
+ 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
+ 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>
+ 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>
- 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.
+ 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>
</programlisting>
</para>
<para>
- which are patches which may be applied against the base kernel, wherever
+ The above example file contains patches you can apply against the base kernel, wherever
they may have been obtained from.
</para>
<para>
</programlisting>
</para>
<para>
- which is the configuration information to use to configure the kernel.
+ Finally, this last example file contains 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
+ 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>
<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.
+ This section describes other pieces of software that the hardware might need for best
+ operation.
+ These are examples of the kinds of things that you could encounter.
+ The examples used in this section 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 reflash hardware.
</para>
<para>
<programlisting>
</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.
+ 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>
</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.
+ Sometimes the device needs an image in a very specific format so that the update
+ mechanism can accept and reflash 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>
- 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.
+ 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, which is where
+ 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>
- These files only need be provided if the platform requires them.
+ With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
+ It 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>
- </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.
-
- 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).
+ 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>
- 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.
+ 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'>
+ <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.
+ 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>
+ <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
<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.
+ 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>
