documentation/bsp-guide/bsp.xml: BSP recommendations section added
Added the "Requirements and Recommendations for Released BSPs" section. This section was requested by Dave Stewart based on community input for direction on how to create a BSP that was compliant with the Yocto Project. The input for the section came from Tom Zanussi. A spell-check was performed also prior to this commit that addressed a few spelling issues across the file. (From yocto-docs rev: 7ed0dd1093b33491231dec06f7b5f8e76004130d) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
c29a721a68
commit
4969df1279
|
|
@ -75,7 +75,7 @@
|
|||
|
||||
<para>
|
||||
Some layers function as a layer to hold other BSP layers.
|
||||
An example of this type of layers is the <filename>meta-intel</filename> layer.
|
||||
An example of this type of layer is the <filename>meta-intel</filename> layer.
|
||||
The <filename>meta-intel</filename> layer contains over 10 individual BSP layers.
|
||||
</para>
|
||||
|
||||
|
|
@ -121,6 +121,15 @@
|
|||
are separate components that happen to be combined in certain end products.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Before looking at the common form for the file structure inside a BSP Layer,
|
||||
you should be aware that some requirements do exist in order for a BSP to
|
||||
be considered compliant with the Yocto Project.
|
||||
For that list of requirements, see the
|
||||
"<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
|
||||
section.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Below is the common form for the file structure inside a BSP Layer.
|
||||
While you can use this basic form for the standard, realize that the actual structures
|
||||
|
|
@ -644,6 +653,193 @@
|
|||
</section>
|
||||
</section>
|
||||
|
||||
<section id='requirements-and-recommendations-for-released-bsps'>
|
||||
<title>Requirements and Recommendations for Released BSPs</title>
|
||||
|
||||
<para>
|
||||
Certain requirements exist for a released BSP to be considered
|
||||
compliant with the Yocto Project.
|
||||
Additionally, a single recommendation also exists.
|
||||
This section describes the requirements and recommendation for
|
||||
released BSPs.
|
||||
</para>
|
||||
|
||||
<section id='released-bsp-requirements'>
|
||||
<title>Released BSP Requirements</title>
|
||||
|
||||
<para>
|
||||
Before looking at BSP requirements, you should consider the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>The requirements here assume the base Yocto Project requirements
|
||||
for the BSP layer are already met.
|
||||
For example, requirements for working with the
|
||||
<filename>oe-core</filename> and standard toolchain layers.</para></listitem>
|
||||
<listitem><para>The requirements in this section apply regardless of how you
|
||||
ultimately package a BSP.
|
||||
You should consult the packaging and distribution guidelines for your
|
||||
specific release process.
|
||||
For an example of packaging and distribution requirements, see the
|
||||
<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third
|
||||
Party BSP Release Process</ulink> wiki page.</para></listitem>
|
||||
<listitem><para>The requirements for the BSP as it is made available to a developer
|
||||
are completely independent of the released form of the BSP.
|
||||
For example, the BSP metadata can be contained within a Git repository
|
||||
and could have a directory structure completely different from what appears
|
||||
in the officially released BSP layer.</para></listitem>
|
||||
<listitem><para>No requirement stipulates that specific packages or package
|
||||
modifications exist in the BSP layer, beyond the requirements for general
|
||||
compliance with the Yocto Project.
|
||||
For example, no requirement exists dictating that a specific kernel or
|
||||
kernel version be used in a given BSP.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Following are the requirements for a released BSP that conforms to the
|
||||
Yocto Project:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Layer Name:</emphasis>
|
||||
The BSP must have a layer name that follows the Yocto
|
||||
Project standards.
|
||||
For information on BSP layer names, see the
|
||||
"<link linkend='bsp-layers'>BSP Layers</link>" section.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>File System Layout:</emphasis>
|
||||
In general, the filesystem layout for the BSP layer
|
||||
should use the same directory names
|
||||
as listed in <filename>recipes.txt</filename>.
|
||||
You can find <filename>recipes.txt</filename> in the
|
||||
<filename>meta</filename> directory of the
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-files'>Yocto
|
||||
Project Files</ulink>, or in the OpenEmbedded Core Layer
|
||||
(<filename>openembedded-core</filename>) found at
|
||||
<ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
|
||||
</para>
|
||||
<para>In particular, you should place recipes
|
||||
(<filename>.bb</filename> files) and recipe
|
||||
modifications (<filename>.bbappend</filename> files) into
|
||||
<filename>recipes-*</filename> subdirectories by functional area
|
||||
as outlined in <filename>recipes.txt</filename>.
|
||||
If none of the categories fits a particular recipe, you can
|
||||
make up your own <filename>recipe-*</filename> subdirectory.</para>
|
||||
<para>Within any particular <filename>recipes-*</filename> category, the layout
|
||||
should match what is found in the OpenEmbedded Core
|
||||
Git repository (<filename>openembedded-core</filename>)
|
||||
or the Yocto Project Files (<filename>poky</filename>).
|
||||
In other words, make sure you place related files in appropriately
|
||||
related <filename>recipes-*</filename> subdirectories specific to the
|
||||
recipe's function, or within a subdirectory containing a set of closely-related
|
||||
recipes.
|
||||
The recipes themselves should follow the general guidelines
|
||||
for recipes used in the Yocto Project found in the
|
||||
<ulink url='https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide'>Yocto
|
||||
Recipe and Patch Style Guide</ulink>.</para></listitem>
|
||||
<listitem><para><emphasis>License File:</emphasis>
|
||||
You must include a license file in the
|
||||
<filename>meta-<bsp_name></filename> directory.
|
||||
This license covers the BSP metadata as a whole.
|
||||
You must specify which license to use since there is no
|
||||
default license if one is not specified.</para></listitem>
|
||||
<listitem><para><emphasis>README File:</emphasis>
|
||||
You must include a <filename>README</filename> file in the
|
||||
<filename>meta-<bsp_name></filename> directory.
|
||||
At a minimum, the <filename>README</filename> file should
|
||||
contain the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>A brief description about the hardware the BSP
|
||||
targets.</para></listitem>
|
||||
<listitem><para>A list of all the dependencies a
|
||||
on which a BSP layer depends.
|
||||
These dependencies are typically a list of required layers needed
|
||||
to build the BSP.
|
||||
However, the dependencies should also contain information regarding
|
||||
any other dependencies the BSP might have.</para></listitem>
|
||||
<listitem><para>Any required special licensing information.
|
||||
For example, this information includes information on
|
||||
special variables needed to satisfy a EULA,
|
||||
or instructions on information needed to build or distribute
|
||||
binaries built from the BSP metadata.</para></listitem>
|
||||
<listitem><para>The name and contact information for the
|
||||
BSP layer maintainer.
|
||||
This is the person to whom patches and questions should
|
||||
be sent.</para></listitem>
|
||||
<listitem><para>Instructions on how to build the BSP using the BSP
|
||||
layer.</para></listitem>
|
||||
<listitem><para>Instructions on how to boot the BSP build from
|
||||
the BSP layer.</para></listitem>
|
||||
<listitem><para>Instructions on how to boot the binary images
|
||||
contained in the <filename>/binary</filename> directory,
|
||||
if present.</para></listitem>
|
||||
<listitem><para>Information on any known bugs or issues that users
|
||||
should know about when either building or booting the BSP
|
||||
binaries.</para></listitem>
|
||||
</itemizedlist></para></listitem>
|
||||
<listitem><para><emphasis>README.sources File:</emphasis>
|
||||
You must include a <filename>README.sources</filename> in the
|
||||
<filename>meta-<bsp_name></filename> directory.
|
||||
This file specifies exactly where you can find the sources used to
|
||||
generate the binary images contained in the
|
||||
<filename>/binary</filename> directory, if present.</para></listitem>
|
||||
<listitem><para><emphasis>Layer Configuration File:</emphasis>
|
||||
You must include a <filename>conf/layer.conf</filename> in the
|
||||
<filename>meta-<bsp_name></filename> directory.
|
||||
This file identifies the <filename>meta-<bsp_name></filename>
|
||||
BSP layer as a layer to the build system.</para></listitem>
|
||||
<listitem><para><emphasis>Machine Configuration File:</emphasis>
|
||||
You must include a <filename>conf/machine/<bsp_name>.conf</filename>
|
||||
in the <filename>meta-<bsp_name></filename> directory.
|
||||
This configuration file defines a machine target that can be built
|
||||
using the BSP layer.
|
||||
Multiple machine configuration files define variations of machine
|
||||
configurations that are supported by the BSP.
|
||||
If a BSP supports more multiple machine variations, you need to
|
||||
adequately describe each variation in the BSP
|
||||
<filename>README</filename> file.
|
||||
Do not use multiple machine configuration files to describe disparate
|
||||
hardware.
|
||||
Multiple machine configuration files should describe very similar targets.
|
||||
If you do have very different targets, you should create a separate
|
||||
BSP.
|
||||
<note>It is completely possible for a developer to structure the
|
||||
working repository as a conglomeration of unrelated BSP
|
||||
files, and to possibly generate specifically targeted 'release' BSPs
|
||||
from that directory using scripts or some other mechanism.
|
||||
Such considerations are outside the scope of this document.</note>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='released-bsp-recommendations'>
|
||||
<title>Released BSP Recommendations</title>
|
||||
|
||||
<para>
|
||||
One recommendation for BSP releases is that they contain
|
||||
one or more bootable images.
|
||||
Including bootable images allows users to easily try out the BSP
|
||||
on their own hardware.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In some cases, it might not be convenient to include a
|
||||
bootable image.
|
||||
In this case, you might want to make two versions of the
|
||||
BSP available: one that contains binary images, and one
|
||||
that does not.
|
||||
The version that does not contain bootable images avoids
|
||||
unnecessary download times for users not interested in the images.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you need to distribute a BSP and include bootable images or build kernel and
|
||||
filesystems meant to allow users to boot the BSP for evaluation
|
||||
purposes, you should put the images and artifacts within a
|
||||
<filename>binary/</filename> subdirectory located in the
|
||||
<filename>meta-<bsp_name></filename> directory.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id='customizing-a-recipe-for-a-bsp'>
|
||||
<title>Customizing a Recipe for a BSP</title>
|
||||
|
||||
|
|
@ -760,7 +956,7 @@
|
|||
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>
|
||||
<para>Once the appropriate license flags are whitelisted
|
||||
<para>Once the appropriate license flags are on the white list
|
||||
in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
|
||||
can build the encumbered image with no change at all
|
||||
to the normal build process.</para></listitem>
|
||||
|
|
@ -931,7 +1127,7 @@
|
|||
<para>
|
||||
Now that you know where these two commands reside and how to access information
|
||||
on them, you should find it relatively straightforward to discover the commands
|
||||
necessary to create a BSP and perform basic kernel maintainence on that BSP using
|
||||
necessary to create a BSP and perform basic kernel maintenance on that BSP using
|
||||
the tools.
|
||||
The next sections provide a concrete starting point to expand on a few points that
|
||||
might not be immediately obvious or that could use further explanation.
|
||||
|
|
@ -990,7 +1186,7 @@
|
|||
In every other way, this architecture is representative of how creating a BSP for
|
||||
a 'real' machine would work.
|
||||
The reason the example uses this architecture is because it is an emulated architecture
|
||||
and can easily be followed without requireing actual hardware.
|
||||
and can easily be followed without requiring actual hardware.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
|
@ -1059,7 +1255,7 @@
|
|||
If you enter 'n', the script prompts you to further enter the kernel
|
||||
you do want to use (e.g. 3.0, 3.2_preempt-rt, etc.).</para></listitem>
|
||||
<listitem><para>Next, the script asks whether you would like to have a new
|
||||
branch created especially for your BSPin the local
|
||||
branch created especially for your BSP in the local
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink>
|
||||
Git repository .
|
||||
If not, then the script re-uses an existing branch.</para>
|
||||
|
|
|
|||
Loading…
Reference in New Issue