Before looking at BSP requirements, you should consider the following:
The requirements here assume the BSP layer is a well-formed, "legal" layer that can be added to the Yocto Project. For guidelines on creating a layer that meets these base requirements, see the "BSP Layers" and the "Understanding and Creating Layers" in the Yocto Project Development Manual.
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 "Third Party BSP Release Process" wiki page.
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.
It is not required 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.
Following are the requirements for a released BSP that conforms to the Yocto Project:
Layer Name: The BSP must have a layer name that follows the Yocto Project standards. For information on BSP layer names, see the "BSP Layers" section.
File System Layout:
When possible, use the same directory names in your
BSP layer as listed in the recipes.txt
file.
In particular, you should place recipes
(.bb
files) and recipe
modifications (.bbappend
files) into
recipes-*
subdirectories by functional area
as outlined in recipes.txt
.
If you cannot find a category in recipes.txt
to fit a particular recipe, you can make up your own
recipes-*
subdirectory.
You can find recipes.txt
in the
meta
directory of the
Source Directory,
or in the OpenEmbedded Core Layer
(openembedded-core
) found at
http://git.openembedded.org/openembedded-core/tree/meta.
Within any particular recipes-*
category, the layout
should match what is found in the OpenEmbedded Core
Git repository (openembedded-core
)
or the Source Directory (poky
).
In other words, make sure you place related files in appropriately
related recipes-*
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
"Yocto Recipe and Patch Style Guide".
License File:
You must include a license file in the
meta-<bsp_name>
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.
See the
COPYING.MIT
file for the Fish River Island 2 BSP in the meta-fri2
BSP layer
as an example.
README File:
You must include a README
file in the
meta-<bsp_name>
directory.
See the
README
file for the Fish River Island 2 BSP in the meta-fri2
BSP layer
as an example.
At a minimum, the README
file should
contain the following:
A brief description about the hardware the BSP targets.
A list of all the dependencies 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.
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.
The name and contact information for the BSP layer maintainer. This is the person to whom patches and questions should be sent. For information on how to find the right person, see the "How to Submit a Change" section in the Yocto Project Development Manual.
Instructions on how to build the BSP using the BSP layer.
Instructions on how to boot the BSP build from the BSP layer.
Instructions on how to boot the binary images
contained in the /binary
directory,
if present.
Information on any known bugs or issues that users should know about when either building or booting the BSP binaries.
README.sources File:
You must include a README.sources
in the
meta-<bsp_name>
directory.
This file specifies exactly where you can find the sources used to
generate the binary images contained in the
/binary
directory, if present.
See the
README.sources
file for the Fish River Island 2 BSP in the meta-fri2
BSP layer
as an example.
Layer Configuration File:
You must include a conf/layer.conf
in the
meta-<bsp_name>
directory.
This file identifies the meta-<bsp_name>
BSP layer as a layer to the build system.
Machine Configuration File:
You must include one or more conf/machine/<bsp_name>.conf
files in the meta-<bsp_name>
directory.
These configuration files define machine targets 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 multiple machine variations, you need to
adequately describe each variation in the BSP
README
file.
Do not use multiple machine configuration files to describe disparate
hardware.
If you do have very different targets, you should create separate
BSP layers for each target.
meta-yocto-bsp
layer).
Such considerations are outside the scope of this document.