689 lines
33 KiB
XML
689 lines
33 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) - Developer's 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>
|
|
|
|
<note>
|
|
The information here does not provide an example of how to create a BSP.
|
|
For examples on how to create a BSP, see the
|
|
<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html#dev-manual-bsp-appendix'>
|
|
BSP Development Example</ulink> in
|
|
<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'>
|
|
The Yocto Project Development Manual</ulink>.
|
|
You can also see the
|
|
<ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
|
|
wiki page</ulink>.
|
|
</note>
|
|
|
|
<para>
|
|
The proposed format does have elements that are specific to the Yocto Project and
|
|
OpenEmbedded build systems.
|
|
It is intended that this information can be
|
|
used by other systems besides Yocto Project and OpenEmbedded and that it will be simple
|
|
to extract information and convert it to other formats if required.
|
|
Yocto Project, 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, which uses the following
|
|
naming convention:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
"bsp_name" is a placeholder for the machine or platform name.
|
|
Here are some example base directory names:
|
|
<literallayout class='monospaced'>
|
|
meta-emenlow
|
|
meta-n450
|
|
meta-beagleboard
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
The base directory (<filename>meta-<bsp_name></filename>) is the root of the BSP layer.
|
|
This root is what you add to the <filename>BBLAYERS</filename>
|
|
variable in the <filename>build/conf/bblayers.conf</filename> file found in the
|
|
Yocto Project file's build directory.
|
|
Adding the root allows the Yocto Project build system to recognize the BSP
|
|
definition and from it build an image.
|
|
Here is an example:
|
|
<literallayout class='monospaced'>
|
|
BBLAYERS = " \
|
|
/usr/local/src/yocto/meta \
|
|
/usr/local/src/yocto/meta-yocto \
|
|
/usr/local/src/yocto/meta-<bsp_name> \
|
|
"
|
|
</literallayout>
|
|
For more detailed information on layers, see the
|
|
"<ulink url='http://www.yoctoproject.org/docs/1.1.1/poky-ref-manual/poky-ref-manual.html#usingpoky-changes-layers'>BitBake Layers</ulink>" section of the Yocto Project Reference Manual.
|
|
You can also see the detailed examples in the appendices of
|
|
<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'>
|
|
The Yocto Project Development Manual</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
Below is the common form for the file structure inside a base directory.
|
|
While you can use this basic form for the standard, realize that the actual structures
|
|
for specific BSPs could differ.
|
|
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/
|
|
meta-<bsp_name>/<bsp_license_file>
|
|
meta-<bsp_name>/README
|
|
meta-<bsp_name>/binary/<bootable_images>
|
|
meta-<bsp_name>/conf/layer.conf
|
|
meta-<bsp_name>/conf/machine/*.conf
|
|
meta-<bsp_name>/recipes-bsp/*
|
|
meta-<bsp_name>/recipes-graphics/*
|
|
meta-<bsp_name>/recipes-kernel/linux/linux-yocto_<kernel_rev>.bbappend
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
Below is an example of the Crown Bay BSP:
|
|
|
|
<literallayout class='monospaced'>
|
|
meta-crownbay/COPYING.MIT
|
|
meta-crownbay/README
|
|
meta-crownbay/binary
|
|
meta-crownbay/conf/
|
|
meta-crownbay/conf/layer.conf
|
|
meta-crownbay/conf/machine/
|
|
meta-crownbay/conf/machine/crownbay.conf
|
|
meta-crownbay/conf/machine/crownbay-noemgd.conf
|
|
meta-crownbay/recipes-bsp/
|
|
meta-crownbay/recipes-bsp/formfactor/
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor/
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig
|
|
meta-crownbay/recipes-core
|
|
meta-crownbay/recipes-core/tasks
|
|
meta-crownbay/recipes-core/tasks/task-core-tools.bbappend
|
|
meta-crownbay/recipes-graphics/
|
|
meta-crownbay/recipes-graphics/xorg-xserver/
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/xorg.conf
|
|
meta-crownbay/recipes-kernel/
|
|
meta-crownbay/recipes-kernel/linux/
|
|
meta-crownbay/recipes-kernel/linux/linux-yocto_2.6.34.bbappend
|
|
meta-crownbay/recipes-kernel/linux/linux-yocto_2.6.37.bbappend
|
|
meta-crownbay/recipes-kernel/linux/linux-yocto_3.0.bbappend
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
The following sections describe each part of the proposed BSP format.
|
|
</para>
|
|
|
|
<section id="bsp-filelayout-license">
|
|
<title>License Files</title>
|
|
|
|
<para>
|
|
You can find these files in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/<bsp_license_file>
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
These optional files satisfy licensing requirements for the BSP.
|
|
The type or types of files here can vary depending on the licensing requirements.
|
|
For example, in the Crown Bay BSP all licensing requirements are handled with the
|
|
<filename>COPYING.MIT</filename> file.
|
|
</para>
|
|
|
|
<para>
|
|
Licensing files can be MIT, BSD, GPLv*, and so forth.
|
|
These files are recommended for the BSP but are optional and totally up to the BSP developer.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="bsp-filelayout-readme">
|
|
<title>README File</title>
|
|
<para>
|
|
You can find these files in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/README
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
This file provides information on how to boot the live images that are optionally
|
|
included in the <filename>/binary</filename> directory.
|
|
The <filename>README</filename> file also provides special information needed for
|
|
building the image.
|
|
</para>
|
|
|
|
<para>
|
|
Technically speaking a <filename>README</filename> is optional but it is highly
|
|
recommended that every BSP has one.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="bsp-filelayout-binary">
|
|
<title>Pre-built User Binaries</title>
|
|
<para>
|
|
You can find these files in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/binary/<bootable_images>
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
This optional area contains useful pre-built kernels and user-space filesystem
|
|
images appropriate to the target system.
|
|
This directory typically contains graphical (e.g. sato) and minimal live images
|
|
when the BSP tarball has been created and made available in the Yocto Project website.
|
|
You can use these kernels and images to get a system running and quickly get started
|
|
on development tasks.
|
|
</para>
|
|
|
|
<para>
|
|
The exact types of binaries present are highly hardware-dependent.
|
|
However, a README file should be present in the BSP file structure that explains how to use
|
|
the kernels and images with the target hardware.
|
|
If pre-built 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 File</title>
|
|
<para>
|
|
You can find this file in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/conf/layer.conf
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
The <filename>conf/layer.conf</filename> file identifies the file structure as a Yocto
|
|
Project layer, identifies the
|
|
contents of the layer, and contains information about how Yocto Project should use it.
|
|
Generally, a standard boilerplate file such as the following works.
|
|
In the following example you would replace "bsp" and "_bsp" with the actual name
|
|
of the BSP (i.e. <bsp_name> from the example template).
|
|
</para>
|
|
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
# 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"
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
This file simply makes BitBake aware of the recipes and configuration directories.
|
|
This file must exist so that the Yocto Project build system can recognize the BSP.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="bsp-filelayout-machine">
|
|
<title>Hardware Configuration Options</title>
|
|
<para>
|
|
You can find these files in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/conf/machine/*.conf
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
The machine files bind together all the information contained elsewhere
|
|
in the BSP into a format that the Yocto Project build system 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
|
|
<filename>MACHINE</filename> variable.
|
|
</para>
|
|
|
|
<para>
|
|
These files define things such as the kernel package to use
|
|
(<filename>PREFERRED_PROVIDER</filename> of virtual/kernel), the 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 BSP layer.
|
|
However, you can supply more than one file.
|
|
For example, in the Crown Bay BSP shown earlier in this section, the
|
|
<filename>conf/machine</filename> directory contains two configuration files:
|
|
<filename>crownbay.conf</filename> and <filename>crownbay-noemgd.conf</filename>.
|
|
The <filename>crownbay.conf</filename> file is used for the Crown Bay BSP
|
|
that supports the <trademark class='registered'>Intel</trademark> Embedded
|
|
Media and Graphics Driver (<trademark class='registered'>Intel</trademark>
|
|
EMGD), while the <filename>crownbay-noemgd.conf</filename> file is used for the
|
|
Crown Bay BSP that does not support the <trademark class='registered'>Intel</trademark>
|
|
EMGD.
|
|
</para>
|
|
|
|
<para>
|
|
This <filename>crownbay.conf</filename> file could also include
|
|
a hardware "tuning" file that is commonly used to
|
|
define the the package architecture and specify
|
|
optimization flags, which are carefully chosen to give best
|
|
performance on a given processor.
|
|
</para>
|
|
|
|
<para>
|
|
Tuning files are found in the <filename>meta/conf/machine/include</filename>
|
|
directory.
|
|
To use them, you simply include them in the machine configuration file.
|
|
For example, the Crown Bay BSP <filename>crownbay.conf</filename> has the
|
|
following statement:
|
|
<literallayout class='monospaced'>
|
|
include conf/machine/include/tune-atom.inc
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='bsp-filelayout-misc-recipes'>
|
|
<title>Miscellaneous Recipe Files</title>
|
|
<para>
|
|
You can find these files in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/recipes-bsp/*
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
This optional directory contains miscellaneous recipe files for the BSP.
|
|
Most notably would be the formfactor files.
|
|
For example, in the Crown Bay BSP there is the
|
|
<filename>formfactor_0.0.bbappend</filename> file, which is an append file used
|
|
to augment the recipe that starts the build.
|
|
Furthermore, there are machine-specific settings used during the build that are
|
|
defined by the <filename>machconfig</filename> files.
|
|
In the Crown Bay example, two <filename>machconfig</filename> files exist:
|
|
one that supports the Intel EMGD and one that does not:
|
|
<literallayout class='monospaced'>
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig
|
|
meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
|
|
</literallayout>
|
|
</para>
|
|
|
|
<note><para>
|
|
If a BSP does not have a formfactor entry, defaults are established according to
|
|
the configuration script.
|
|
</para></note>
|
|
</section>
|
|
|
|
<section id='bsp-filelayout-core-recipes'>
|
|
<title>Core Recipe Files</title>
|
|
<para>
|
|
You can find these files in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/recipes-core/*
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
This directory contains recipe files for the core.
|
|
For example, in the Crown Bay BSP there is the
|
|
<filename>task-core-tools.bbappend</filename> file, which is an append file used
|
|
to recommend that the SystemTap package be included as a package when the image
|
|
is built.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='bsp-filelayout-recipes-graphics'>
|
|
<title>Display Support Files</title>
|
|
<para>
|
|
You can find these files in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/recipes-graphics/*
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
This optional directory contains recipes for the BSP if it has
|
|
special requirements for graphics support.
|
|
All files that are needed for the BSP to support a display are kept here.
|
|
For example, the Crown Bay BSP contains the following files that support
|
|
building a BSP that supports and does not support the Intel EMGD:
|
|
<literallayout class='monospaced'>
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf
|
|
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/xorg.conf
|
|
</literallayout>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='bsp-filelayout-kernel'>
|
|
<title>Linux Kernel Configuration</title>
|
|
<para>
|
|
You can find these files in the Yocto Project file's directory structure at:
|
|
<literallayout class='monospaced'>
|
|
meta-<bsp_name>/recipes-kernel/linux/linux-yocto_*.bbappend
|
|
</literallayout>
|
|
</para>
|
|
|
|
<para>
|
|
These files append your specific changes to the kernel you are using.
|
|
</para>
|
|
<para>
|
|
For your BSP, you typically want to use an existing Yocto Project kernel found in the
|
|
Yocto Project repository at <filename>meta/recipes-kernel/linux</filename>.
|
|
You can append your specific changes to the kernel recipe by using a
|
|
similarly named append file, which is located in the
|
|
<filename>meta-<bsp_name>/recipes-kernel/linux</filename>
|
|
directory.
|
|
</para>
|
|
<para>
|
|
Suppose you use a BSP that uses the <filename>linux-yocto_3.0.bb</filename> kernel,
|
|
which is the preferred kernel to use for developing a new BSP using the Yocto Project.
|
|
In other words, you have selected the kernel in your
|
|
<filename><bsp_name>.conf</filename> file by adding the following statements:
|
|
<literallayout class='monospaced'>
|
|
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
|
|
PREFERRED_VERSION_linux-yocto = "3.0%"
|
|
</literallayout>
|
|
You would use the <filename>linux-yocto_3.0.bbappend</filename> file to append
|
|
specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.
|
|
</para>
|
|
<para>
|
|
As an example, look at the existing Crown Bay BSP.
|
|
The append file used is:
|
|
<literallayout class='monospaced'>
|
|
meta-crownbay/recipes-kernel/linux/linux-yocto_3.0.bbappend
|
|
</literallayout>
|
|
The file contains the following:
|
|
<literallayout class='monospaced'>
|
|
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
|
|
|
|
COMPATIBLE_MACHINE_crownbay = "crownbay"
|
|
KMACHINE_crownbay = "yocto/standard/crownbay"
|
|
KERNEL_FEATURES_append_crownbay += " cfg/smp.scc"
|
|
|
|
COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
|
|
KMACHINE_crownbay-noemgd = "yocto/standard/crownbay"
|
|
KERNEL_FEATURES_append_crownbay-noemgd += " cfg/smp.scc"
|
|
|
|
SRCREV_machine_pn-linux-yocto_crownbay ?= "2247da9131ea7e46ed4766a69bb1353dba22f873"
|
|
SRCREV_meta_pn-linux-yocto_crownbay ?= "d05450e4aef02c1b7137398ab3a9f8f96da74f52"
|
|
|
|
SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= "2247da9131ea7e46ed4766a69bb1353dba22f873"
|
|
SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= "d05450e4aef02c1b7137398ab3a9f8f96da74f52"
|
|
</literallayout>
|
|
This append file contains statements used to support the Crown Bay BSP for both
|
|
Intel EMGD and non-EMGD.
|
|
The build process, in this case, recognizes and uses only the statements that
|
|
apply to the defined machine name - <filename>crownbay</filename> in this case.
|
|
So, the applicable statements in the <filename>linux-yocto_3.0.bbappend</filename>
|
|
file are follows:
|
|
<literallayout class='monospaced'>
|
|
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
|
|
|
|
COMPATIBLE_MACHINE_crownbay = "crownbay"
|
|
KMACHINE_crownbay = "yocto/standard/crownbay"
|
|
KERNEL_FEATURES_append_crownbay += " cfg/smp.scc"
|
|
|
|
SRCREV_machine_pn-linux-yocto_crownbay ?= "2247da9131ea7e46ed4766a69bb1353dba22f873"
|
|
SRCREV_meta_pn-linux-yocto_crownbay ?= "d05450e4aef02c1b7137398ab3a9f8f96da74f52"
|
|
</literallayout>
|
|
The append file defines <filename>crownbay</filename> as the compatible machine,
|
|
defines the <filename>KMACHINE</filename>, points to some configuration fragments
|
|
to use by setting the <filename>KERNEL_FEATURES</filename> variable, and then points
|
|
to the specific commits in the Yocto Project files Git repository and the
|
|
<filename>meta</filename> Git repository branches to identify the exact kernel needed
|
|
to build the Crown Bay BSP.
|
|
</para>
|
|
<para>
|
|
One thing missing in this particular BSP, which you will typically need when
|
|
developing a BSP, is the kernel configuration file (<filename>.config</filename>) for your BSP.
|
|
When developing a BSP, you probably have a kernel configuration file or a set of kernel
|
|
configuration files that, when taken together, define the kernel configuration for your BSP.
|
|
You can accomplish this definition by putting the configurations in a file or a set of files
|
|
inside a directory located at the same level as your append file and having the same name
|
|
as the kernel.
|
|
With all these conditions met simply reference those files in a
|
|
<filename>SRC_URI</filename> statement in the append file.
|
|
</para>
|
|
<para>
|
|
For example, suppose you had a set of configuration options in a file called
|
|
<filename>defconfig</filename>.
|
|
If you put that file inside a directory named
|
|
<filename>/linux-yocto</filename> and then added
|
|
a <filename>SRC_URI</filename> statement such as the following to the append file,
|
|
those configuration
|
|
options will be picked up and applied when the kernel is built.
|
|
<literallayout class='monospaced'>
|
|
SRC_URI += "file://defconfig"
|
|
</literallayout>
|
|
</para>
|
|
<para>
|
|
As mentioned earlier, you can group related configurations into multiple files and
|
|
name them all in the <filename>SRC_URI</filename> statement as well.
|
|
For example, you could group separate configurations specifically for Ethernet and graphics
|
|
into their own files and add those by using a <filename>SRC_URI</filename> statement like the
|
|
following in your append file:
|
|
<literallayout class='monospaced'>
|
|
SRC_URI += "file://defconfig \
|
|
file://eth.cfg \
|
|
file://gfx.cfg"
|
|
</literallayout>
|
|
</para>
|
|
<para>
|
|
The <filename>FILESEXTRAPATHS</filename> variable is in boilerplate form here
|
|
in order to make it easy to do that.
|
|
It basically allows those configuration files to be found by the build process.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Other methods exist to accomplish grouping and defining configuration options.
|
|
For example, you could directly add configuration options to the Yocto kernel
|
|
<filename>meta</filename> branch for your BSP.
|
|
The configuration options will likely end up in that location anyway if the BSP gets
|
|
added to the Yocto Project.
|
|
For information on how to add these configurations directly, see
|
|
<ulink url='http://yoctoproject.org/docs/1.1.1/kernel-manual/kernel-manual.html'>
|
|
The Yocto Project Kernel Architecture and Use Manual</ulink>.</para>
|
|
<para>
|
|
In general, however, the Yocto Project maintainers take care of moving the
|
|
<filename>SRC_URI</filename>-specified
|
|
configuration options to the <filename>meta</filename> branch.
|
|
Not only is it easier for BSP developers to not have to worry about putting those
|
|
configurations in the branch, but having the maintainers do it allows them to apply
|
|
'global' knowledge about the kinds of common configuration options multiple BSPs in
|
|
the tree are typically using.
|
|
This allows for promotion of common configurations into common features.</para>
|
|
</note>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='bsp-click-through-licensing'>
|
|
<title>BSP 'Click-Through' Licensing Procedure</title>
|
|
|
|
<note> This section describes how
|
|
click-through licensing is expected to work.
|
|
Currently, this functionality is not yet implemented.
|
|
</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
|
|
Yocto Project 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 Yocto Project website's
|
|
<ulink url='http://www.yoctoproject.org/download/all?keys=&download_type=1&download_version='>BSP Download Page</ulink>
|
|
makes available 'de-featured' BSPs that are completely free of any IP encumbrances.
|
|
For these cases you can use the substitution directly and without any further licensing
|
|
requirements.
|
|
If present, these fully 'de-featured' BSPs are named appropriately different
|
|
as compared to the names of the respective encumbered BSPs.
|
|
If available, these substitutions are the simplest and most preferred options.
|
|
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, you can use
|
|
an encumbered version.
|
|
</para>
|
|
|
|
<para>
|
|
Several methods exist within the Yocto Project 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
|
|
a website and providing the name of the BSP and your email address
|
|
through a web form.
|
|
</para>
|
|
|
|
<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>
|
|
|
|
<literallayout class='monospaced'>
|
|
$ BSPKEY_<keydomain>=<key> bitbake core-image-sato
|
|
</literallayout>
|
|
|
|
<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 found in the Yocto Project file's
|
|
build directory.
|
|
</para>
|
|
|
|
<para>
|
|
The <keydomain> component of the
|
|
BSPKEY_<keydomain> is required because there
|
|
might be multiple licenses in effect for a given 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 <filename>yocto/build/downloads</filename>).
|
|
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.
|
|
You can do this by visiting the applicable BSP download page from the Yocto
|
|
Project website at
|
|
<ulink url='http://yoctoproject.org/download/board-support-package-bsp-downloads'></ulink>.
|
|
BSP tarballs that have proprietary information can be downloaded after agreeing
|
|
to licensing requirements as part of the download process.
|
|
Obtaining the code this way allows you to build an encumbered image with
|
|
no changes at all as compared to the normal build.
|
|
</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 from the Yocto Project website.
|
|
</para>
|
|
</section>
|
|
|
|
</chapter>
|