+++ /dev/null
-<!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>
