diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 1edbc049de..a93ac50f6f 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -4,230 +4,231 @@
- Board Support Packages (BSP) - Developer's Guide
+Board Support Packages (BSP) - Developer's Guide
-
- 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.
-
+
+ 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.
+
-
- This guide presents information about BSP Layers, defines a structure for components
- so that BSPs follow a commonly understood layout, discusses how to customize
- a recipe for a BSP, addresses BSP licensing, and provides information that
- shows you how to create and manage a
- BSP Layer using two Yocto Project
- BSP Tools.
-
+
+ This guide presents information about BSP Layers, defines a structure for components
+ so that BSPs follow a commonly understood layout, discusses how to customize
+ a recipe for a BSP, addresses BSP licensing, and provides information that
+ shows you how to create a
+ BSP Layer using the
+ bitbake-layers
+ tool.
+
-
- BSP Layers
+
+ BSP Layers
-
- A BSP consists of a file structure inside a base directory.
- Collectively, you can think of the base directory, its file structure,
- and the contents as a BSP Layer.
- Although not a strict requirement, BSP layers in the Yocto Project
- use the following well-established naming convention:
-
+
+ A BSP consists of a file structure inside a base directory.
+ Collectively, you can think of the base directory, its file structure,
+ and the contents as a BSP Layer.
+ Although not a strict requirement, BSP layers in the Yocto Project
+ use the following well-established naming convention:
+
meta-bsp_name
-
- The string "meta-" is prepended to the machine or platform name, which is
- bsp_name in the above form.
- Tip
- Because the BSP layer naming convention is well-established,
- it is advisable to follow it when creating layers.
- Technically speaking, a BSP layer name does not need to
- start with meta-.
- However, various scripts and tools in the Yocto Project
- development environment assume this convention.
-
-
+
+ The string "meta-" is prepended to the machine or platform name, which is
+ bsp_name in the above form.
+ Tip
+ Because the BSP layer naming convention is well-established,
+ it is advisable to follow it when creating layers.
+ Technically speaking, a BSP layer name does not need to
+ start with meta-.
+ However, various scripts and tools in the Yocto Project
+ development environment assume this convention.
+
+
-
- To help understand the BSP layer concept, consider the BSPs that the
- Yocto Project supports and provides with each release.
- You can see the layers in the
- Yocto Project Source Repositories
- through a web interface at
- .
- If you go to that interface, you will find a list of repositories
- under "Yocto Metadata Layers".
-
- Layers that are no longer actively supported as part of the
- Yocto Project appear under the heading "Yocto Metadata Layer
- Archive."
-
- Each repository is a BSP layer supported by the Yocto Project
- (e.g. meta-raspberrypi and
- meta-intel).
- Each of these layers is a repository unto itself and clicking on a
- layer reveals information that includes two links from which you can choose
- to set up a clone of the layer's repository on your local host system.
- Here is an example that clones the Raspberry Pi BSP layer:
-
+
+ To help understand the BSP layer concept, consider the BSPs that the
+ Yocto Project supports and provides with each release.
+ You can see the layers in the
+ Yocto Project Source Repositories
+ through a web interface at
+ .
+ If you go to that interface, you will find a list of repositories
+ under "Yocto Metadata Layers".
+
+ Layers that are no longer actively supported as part of the
+ Yocto Project appear under the heading "Yocto Metadata Layer
+ Archive."
+
+ Each repository is a BSP layer supported by the Yocto Project
+ (e.g. meta-raspberrypi and
+ meta-intel).
+ Each of these layers is a repository unto itself and clicking on a
+ layer reveals information that includes two links from which you can choose
+ to set up a clone of the layer's repository on your local host system.
+ Here is an example that clones the Raspberry Pi BSP layer:
+
$ git clone git://git.yoctoproject.org/meta-raspberrypi
-
-
+
+
-
- In addition to BSP layers, the
- meta-yocto-bsp layer is part of the
- shipped poky repository.
- The meta-yocto-bsp layer maintains several
- BSPs such as the Beaglebone, EdgeRouter, and generic versions of
- both 32-bit and 64-bit IA machines.
-
+
+ In addition to BSP layers, the
+ meta-yocto-bsp layer is part of the
+ shipped poky repository.
+ The meta-yocto-bsp layer maintains several
+ BSPs such as the Beaglebone, EdgeRouter, and generic versions of
+ both 32-bit and 64-bit IA machines.
+
-
- For information on the BSP development workflow, see the
- "Developing a Board Support Package (BSP)"
- section.
- For more information on how to set up a local copy of source files
- from a Git repository, see the
- "Working With Yocto Project Source Files"
- section also in the Yocto Project Development Tasks Manual.
-
+
+ For information on the BSP development workflow, see the
+ "Developing a Board Support Package (BSP)"
+ section.
+ For more information on how to set up a local copy of source files
+ from a Git repository, see the
+ "Working With Yocto Project Source Files"
+ section also in the Yocto Project Development Tasks Manual.
+
-
- The layer's base directory
- (meta-bsp_name)
- is the root of the BSP Layer.
- This root is what you add to the
- BBLAYERS
- variable in the conf/bblayers.conf file found in the
- Build Directory,
- which is established after you run the OpenEmbedded build environment
- setup script (i.e.
- &OE_INIT_FILE;).
- Adding the root allows the
- OpenEmbedded build system
- to recognize the BSP layer and from it build an image.
- Here is an example:
-
+
+ The layer's base directory
+ (meta-bsp_name)
+ is the root of the BSP Layer.
+ This root is what you add to the
+ BBLAYERS
+ variable in the conf/bblayers.conf file found in the
+ Build Directory,
+ which is established after you run the OpenEmbedded build environment
+ setup script (i.e.
+ &OE_INIT_FILE;).
+ Adding the root allows the
+ OpenEmbedded build system
+ to recognize the BSP layer and from it build an image.
+ Here is an example:
+
BBLAYERS ?= " \
/usr/local/src/yocto/meta \
/usr/local/src/yocto/meta-poky \
/usr/local/src/yocto/meta-yocto-bsp \
/usr/local/src/yocto/meta-mylayer \
"
-
-
+
+
-
- Some BSPs require additional layers on
- top of the BSP's root layer in order to be functional.
- For these cases, you also need to add those layers to the
- BBLAYERS variable in order to build the BSP.
- You must also specify in the "Dependencies" section of the BSP's
- README file any requirements for additional
- layers and, preferably, any
- build instructions that might be contained elsewhere
- in the README file.
-
+
+ Some BSPs require additional layers on
+ top of the BSP's root layer in order to be functional.
+ For these cases, you also need to add those layers to the
+ BBLAYERS variable in order to build the BSP.
+ You must also specify in the "Dependencies" section of the BSP's
+ README file any requirements for additional
+ layers and, preferably, any
+ build instructions that might be contained elsewhere
+ in the README file.
+
-
- Some layers function as a layer to hold other BSP layers.
- An example of this type of layer is the
- meta-intel layer.
- This layer contains BSP layers for the Intel-core2-32
- Intel Common Core
- (Intel-core2-32) and the Intel-corei7-64
- Intel Common Core
- (Intel-corei7-64).
- the meta-intel layer also contains
- the common/ directory, which contains
- common content across those layers.
-
+
+ Some layers function as a layer to hold other BSP layers.
+ An example of this type of layer is the
+ meta-intel layer.
+ This layer contains BSP layers for the Intel-core2-32
+ Intel Common Core
+ (Intel-core2-32) and the Intel-corei7-64
+ Intel Common Core
+ (Intel-corei7-64).
+ the meta-intel layer also contains
+ the common/ directory, which contains
+ common content across those layers.
+
-
- For more information on layers, see the
- "Understanding and Creating Layers"
- section of the Yocto Project Development Tasks Manual.
-
-
+
+ For more information on layers, see the
+ "Understanding and Creating Layers"
+ section of the Yocto Project Development Tasks Manual.
+
+
-
- Preparing Your Build Host to Work With BSP Layers
+
+ Preparing Your Build Host to Work With BSP Layers
-
- This section describes how to get your build host ready
- to work with BSP layers.
- Once you have the host set up, you can create the layer
- as described in the
- "Creating a new BSP Layer Using the bitbake-layers Script"
- section.
-
- For structural information on BSPs, see the
- Example Filesystem Layout
- section.
-
+
+ This section describes how to get your build host ready
+ to work with BSP layers.
+ Once you have the host set up, you can create the layer
+ as described in the
+ "Creating a new BSP Layer Using the bitbake-layers Script"
+ section.
+
+ For structural information on BSPs, see the
+ Example Filesystem Layout
+ section.
+
+
+
+ Set Up the Build Environment:
+ Be sure you are set up to use BitBake in a shell.
+ See the
+ "Setting Up the Development Host to Use the Yocto Project"
+ section in the Yocto Project Development Tasks Manual for information
+ on how to get a build host ready that is either a native
+ Linux machine or a machine that uses CROPS.
+
+
+ Clone the poky Repository:
+ You need to have a local copy of the Yocto Project
+ Source Directory
+ (i.e. a local poky repository).
+ See the
+ "Cloning the poky Repository"
+ and possibly the
+ "Checking Out by Branch in Poky"
+ or
+ "Checking Out by Tag in Poky"
+ sections all in the Yocto Project Development Tasks Manual for
+ information on how to clone the poky
+ repository and check out the appropriate branch for your work.
+
+
+ Determine the BSP Layer You Want:
+ The Yocto Project supports many BSPs, which are maintained in
+ their own layers or in layers designed to contain several
+ BSPs.
+ To get an idea of machine support through BSP layers, you can
+ look at the
+ index of machines
+ for the release.
+
+
+ Optionally Clone the
+ meta-intel BSP Layer:
+ If your hardware is based on current Intel CPUs and devices,
+ you can leverage this BSP layer.
+ For details on the meta-intel BSP layer,
+ see the layer's
+ README
+ file.
- Set Up the Build Environment:
- Be sure you are set up to use BitBake in a shell.
- See the
- "Setting Up the Development Host to Use the Yocto Project"
- section in the Yocto Project Development Tasks Manual for information
- on how to get a build host ready that is either a native
- Linux machine or a machine that uses CROPS.
-
-
- Clone the poky Repository:
- You need to have a local copy of the Yocto Project
+ Navigate to Your Source Directory:
+ Typically, you set up the
+ meta-intel Git repository
+ inside the
Source Directory
- (i.e. a local poky repository).
- See the
- "Cloning the poky Repository"
- and possibly the
- "Checking Out by Branch in Poky"
- or
- "Checking Out by Tag in Poky"
- sections all in the Yocto Project Development Tasks Manual for
- information on how to clone the poky
- repository and check out the appropriate branch for your work.
-
-
- Determine the BSP Layer You Want:
- The Yocto Project supports many BSPs, which are maintained in
- their own layers or in layers designed to contain several
- BSPs.
- To get an idea of machine support through BSP layers, you can
- look at the
- index of machines
- for the release.
-
-
- Optionally Clone the
- meta-intel BSP Layer:
- If your hardware is based on current Intel CPUs and devices,
- you can leverage this BSP layer.
- For details on the meta-intel BSP layer,
- see the layer's
- README
- file.
-
-
- Navigate to Your Source Directory:
- Typically, you set up the
- meta-intel Git repository
- inside the
- Source Directory
- (e.g. poky).
-
+ (e.g. poky).
+
$ cd /home/you/poky
-
-
-
- Clone the Layer:
-
+
+
+
+ Clone the Layer:
+
$ git clone git://git.yoctoproject.org/meta-intel.git
Cloning into 'meta-intel'...
remote: Counting objects: 15585, done.
@@ -236,44 +237,44 @@
Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done.
Resolving deltas: 100% (9123/9123), done.
Checking connectivity... done.
-
-
-
- Check Out the Proper Branch:
- The branch you check out for
- meta-intel must match the same
- branch you are using for the Yocto Project release
- (e.g. &DISTRO_NAME_NO_CAP;):
-
+
+
+
+ Check Out the Proper Branch:
+ The branch you check out for
+ meta-intel must match the same
+ branch you are using for the Yocto Project release
+ (e.g. &DISTRO_NAME_NO_CAP;):
+
$ cd meta-intel
$ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP;
Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
Switched to a new branch '&DISTRO_NAME_NO_CAP;'
-
-
- To see the available branch names in a cloned repository,
- use the git branch -al command.
- See the
- "Checking Out By Branch in Poky"
- section in the Yocto Project Development Tasks
- Manual for more information.
-
-
-
+
+
+ To see the available branch names in a cloned repository,
+ use the git branch -al command.
+ See the
+ "Checking Out By Branch in Poky"
+ section in the Yocto Project Development Tasks
+ Manual for more information.
+
-
- Optionally Set Up an Alternative BSP Layer:
- If your hardware can be more closely leveraged to an
- existing BSP not within the meta-intel
- BSP layer, you can clone that BSP layer.
+
+
+
+ Optionally Set Up an Alternative BSP Layer:
+ If your hardware can be more closely leveraged to an
+ existing BSP not within the meta-intel
+ BSP layer, you can clone that BSP layer.
- The process is identical to the process used for the
- meta-intel layer except for the layer's
- name.
- For example, if you determine that your hardware most
- closely matches the meta-raspberrypi,
- clone that layer:
-
+ The process is identical to the process used for the
+ meta-intel layer except for the layer's
+ name.
+ For example, if you determine that your hardware most
+ closely matches the meta-raspberrypi,
+ clone that layer:
+
$ git clone git://git.yoctoproject.org/meta-raspberrypi
Cloning into 'meta-raspberrypi'...
remote: Counting objects: 4743, done.
@@ -282,88 +283,88 @@
Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done.
Resolving deltas: 100% (2447/2447), done.
Checking connectivity... done.
-
-
-
- Initialize the Build Environment:
- While in the root directory of the Source Directory (i.e.
- poky), run the
- &OE_INIT_FILE;
- environment setup script to define the OpenEmbedded
- build environment on your build host.
-
- $ source &OE_INIT_FILE;
-
- Among other things, the script creates the
- Build Directory,
- which is build in this case
- and is located in the
- Source Directory.
- After the script runs, your current working directory
- is set to the build directory.
-
-
-
-
-
-
- Example Filesystem Layout
-
-
- Defining a common BSP directory structure allows
- end-users to understand and become familiar with
- that standard.
- A common format also encourages standardization
- of software support for hardware.
-
-
-
- The proposed form described in this section does
- have elements that are specific to the OpenEmbedded
- build system.
- It is intended that developers can use this structure
- with other build systems besides the OpenEmbedded build
- system.
- It is also intended that it will be be simple to extract
- information and convert it to other formats if required.
- The OpenEmbedded build system, through its standard
- layers mechanism,
- can directly accept the format described as a layer.
- The BSP layer captures all the hardware-specific details
- in one place using a standard format, which is useful
- for any person wishing to use the hardware platform
- regardless of the build system they are using.
-
-
-
- The BSP specification does not include a build system
- or other tools - the specification is concerned with
- the hardware-specific components only.
- At the end-distribution point, you can ship the BSP
- layer combined with a build system and other tools.
- Realize that it is important to maintain the distinction
- that the BSP layer, a build system, and tools are
- separate components that could to be combined in
- certain end products.
-
-
-
- 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 layer to
- be considered compliant with the Yocto Project.
- For that list of requirements, see the
- "Released BSP Requirements"
- section.
-
-
-
- Below is the common form for the file structure
- inside a BSP Layer.
- While this basic form represents the standard,
- realize that the actual file structures for specific
- BSPs could differ.
+
+
+
+ Initialize the Build Environment:
+ While in the root directory of the Source Directory (i.e.
+ poky), run the
+ &OE_INIT_FILE;
+ environment setup script to define the OpenEmbedded
+ build environment on your build host.
+ $ source &OE_INIT_FILE;
+
+ Among other things, the script creates the
+ Build Directory,
+ which is build in this case
+ and is located in the
+ Source Directory.
+ After the script runs, your current working directory
+ is set to the build directory.
+
+
+
+
+
+
+ Example Filesystem Layout
+
+
+ Defining a common BSP directory structure allows
+ end-users to understand and become familiar with
+ that standard.
+ A common format also encourages standardization
+ of software support for hardware.
+
+
+
+ The proposed form described in this section does
+ have elements that are specific to the OpenEmbedded
+ build system.
+ It is intended that developers can use this structure
+ with other build systems besides the OpenEmbedded build
+ system.
+ It is also intended that it will be be simple to extract
+ information and convert it to other formats if required.
+ The OpenEmbedded build system, through its standard
+ layers mechanism,
+ can directly accept the format described as a layer.
+ The BSP layer captures all the hardware-specific details
+ in one place using a standard format, which is useful
+ for any person wishing to use the hardware platform
+ regardless of the build system they are using.
+
+
+
+ The BSP specification does not include a build system
+ or other tools - the specification is concerned with
+ the hardware-specific components only.
+ At the end-distribution point, you can ship the BSP
+ layer combined with a build system and other tools.
+ Realize that it is important to maintain the distinction
+ that the BSP layer, a build system, and tools are
+ separate components that could to be combined in
+ certain end products.
+
+
+
+ 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 layer to
+ be considered compliant with the Yocto Project.
+ For that list of requirements, see the
+ "Released BSP Requirements"
+ section.
+
+
+
+ Below is the common form for the file structure
+ inside a BSP Layer.
+ While this basic form represents the standard,
+ realize that the actual file structures for specific
+ BSPs could differ.
+
meta-bsp_name/
meta-bsp_name/bsp_license_file
meta-bsp_name/README
@@ -375,13 +376,13 @@
meta-bsp_name/recipes-core/*
meta-bsp_name/recipes-graphics/*
meta-bsp_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend
-
-
+
+
-
- Below is an example of the Raspberry Pi BSP
- layer that ships with the Yocto Project:
-
+
+ Below is an example of the Raspberry Pi BSP
+ layer that ships with the Yocto Project:
+
meta-raspberrypi/COPYING.MIT
meta-raspberrypi/README.md
meta-raspberrypi/classes
@@ -535,167 +536,167 @@
meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend
meta-raspberrypi/wic
meta-raspberrypi/wic/sdimage-raspberrypi.wks
-
-
+
+
-
- The following sections describe each part of the proposed
- BSP format.
-
+
+ The following sections describe each part of the proposed
+ BSP format.
+
-
- License Files
+
+ License Files
-
- You can find these files in the BSP Layer at:
-
+
+ You can find these files in the BSP Layer at:
+
meta-bsp_name/bsp_license_file
-
-
+
+
-
- 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 Raspberry Pi BSP all licensing
- requirements are handled with the
- COPYING.MIT file.
-
+
+ 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 Raspberry Pi BSP all licensing
+ requirements are handled with the
+ COPYING.MIT file.
+
-
- 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.
- For information on how to maintain license
- compliance, see the
- "Maintaining Open Source License Compliance During Your Product's Lifecycle"
- section in the Yocto Project Development Tasks
- Manual.
-
-
+
+ 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.
+ For information on how to maintain license
+ compliance, see the
+ "Maintaining Open Source License Compliance During Your Product's Lifecycle"
+ section in the Yocto Project Development Tasks
+ Manual.
+
+
-
- README File
+
+ README File
-
- You can find this file in the BSP Layer at:
-
+
+ You can find this file in the BSP Layer at:
+
meta-bsp_name/README
-
-
+
+
-
- This file provides information on how to boot the live
- images that are optionally included in the
- binary/ directory.
- The README file also provides
- information needed for building the image.
-
+
+ This file provides information on how to boot the live
+ images that are optionally included in the
+ binary/ directory.
+ The README file also provides
+ information needed for building the image.
+
-
- At a minimum, the README file must
- contain a list of dependencies, such as the names of
- any other layers on which the BSP depends and the name of
- the BSP maintainer with his or her contact information.
-
-
+
+ At a minimum, the README file must
+ contain a list of dependencies, such as the names of
+ any other layers on which the BSP depends and the name of
+ the BSP maintainer with his or her contact information.
+
+
-
- README.sources File
+
+ README.sources File
-
- You can find this file in the BSP Layer at:
-
+
+ You can find this file in the BSP Layer at:
+
meta-bsp_name/README.sources
-
-
+
+
-
- This file provides information on where to locate the BSP
- source files used to build the images (if any) that
- reside in
- meta-bsp_name/binary.
- Images in the binary would be images
- released with the BSP.
- The information in the README.sources
- file also helps you find the
- Metadata
- used to generate the images that ship with the BSP.
-
- If the BSP's binary directory is
- missing or the directory has no images, an existing
- README.sources file is
- meaningless and usually does not exist.
-
-
-
+
+ This file provides information on where to locate the BSP
+ source files used to build the images (if any) that
+ reside in
+ meta-bsp_name/binary.
+ Images in the binary would be images
+ released with the BSP.
+ The information in the README.sources
+ file also helps you find the
+ Metadata
+ used to generate the images that ship with the BSP.
+
+ If the BSP's binary directory is
+ missing or the directory has no images, an existing
+ README.sources file is
+ meaningless and usually does not exist.
+
+
+
-
- Pre-built User Binaries
+
+ Pre-built User Binaries
-
- You can find these files in the BSP Layer at:
-
+
+ You can find these files in the BSP Layer at:
+
meta-bsp_name/binary/bootable_images
-
-
+
+
-
- This optional area contains useful pre-built kernels
- and user-space filesystem images released with the
- BSP that are 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.
-
+
+ This optional area contains useful pre-built kernels
+ and user-space filesystem images released with the
+ BSP that are 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.
+
-
- The exact types of binaries present are highly
- hardware-dependent.
- The
- README
- file should be present in the BSP Layer and it
- explains how to use the images with the target hardware.
- Additionally, the
- README.sources
- file should be present to locate the sources used to
- build the images and provide information on the
- Metadata.
-
-
+
+ The exact types of binaries present are highly
+ hardware-dependent.
+ The
+ README
+ file should be present in the BSP Layer and it
+ explains how to use the images with the target hardware.
+ Additionally, the
+ README.sources
+ file should be present to locate the sources used to
+ build the images and provide information on the
+ Metadata.
+
+
-
- Layer Configuration File
+
+ Layer Configuration File
-
- You can find this file in the BSP Layer at:
-
+
+ You can find this file in the BSP Layer at:
+
meta-bsp_name/conf/layer.conf
-
-
+
+
-
- The conf/layer.conf file
- identifies the file structure as a layer,
- identifies the contents of the layer, and
- contains information about how the build system should
- use it.
- Generally, a standard boilerplate file such as the
- following works.
- In the following example, you would replace
- bsp with the actual
- name of the BSP (i.e.
- bsp_name from the example
- template).
-
+
+ The conf/layer.conf file
+ identifies the file structure as a layer,
+ identifies the contents of the layer, and
+ contains information about how the build system should
+ use it.
+ Generally, a standard boilerplate file such as the
+ following works.
+ In the following example, you would replace
+ bsp with the actual
+ name of the BSP (i.e.
+ bsp_name from the example
+ template).
+
-
-
+
+
# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"
@@ -708,14 +709,14 @@
BBFILE_PRIORITY_bsp = "6"
LAYERDEPENDS_bsp = "intel"
-
-
+
+
-
- To illustrate the string substitutions, here are
- the corresponding statements from the Raspberry
- Pi conf/layer.conf file:
-
+
+ To illustrate the string substitutions, here are
+ the corresponding statements from the Raspberry
+ Pi conf/layer.conf file:
+
# We have a conf and classes directory, append to BBPATH
BBPATH .= ":${LAYERDIR}"
@@ -732,1429 +733,1098 @@
.
.
.
-
-
+
+
-
- This file simply makes
- BitBake
- aware of the recipes and configuration directories.
- The file must exist so that the OpenEmbedded build system
- can recognize the BSP.
-
-
+
+ This file simply makes
+ BitBake
+ aware of the recipes and configuration directories.
+ The file must exist so that the OpenEmbedded build system
+ can recognize the BSP.
+
+
-
- Hardware Configuration Options
+
+ Hardware Configuration Options
-
- You can find these files in the BSP Layer at:
-
+
+ You can find these files in the BSP Layer at:
+
meta-bsp_name/conf/machine/*.conf
-
-
+
+
-
- The machine files bind together all the information
- contained elsewhere in the BSP into a format that
- the build system can understand.
- Each BSP Layer requires at least one machine file.
- If the BSP supports multiple machines, multiple
- machine configuration files can exist.
- These filenames correspond to the values to which
- users have set the
- MACHINE variable.
-
+
+ The machine files bind together all the information
+ contained elsewhere in the BSP into a format that
+ the build system can understand.
+ Each BSP Layer requires at least one machine file.
+ If the BSP supports multiple machines, multiple
+ machine configuration files can exist.
+ These filenames correspond to the values to which
+ users have set the
+ MACHINE variable.
+
-
- These files define things such as the kernel package
- to use
- (PREFERRED_PROVIDER
- 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.
-
+
+ These files define things such as the kernel package
+ to use
+ (PREFERRED_PROVIDER
+ 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.
+
-
- This configuration file could also include a hardware
- "tuning" file that is commonly used to define the
- package architecture and specify optimization flags,
- which are carefully chosen to give best performance
- on a given processor.
-
+
+ This configuration file could also include a hardware
+ "tuning" file that is commonly used to define the
+ package architecture and specify optimization flags,
+ which are carefully chosen to give best performance
+ on a given processor.
+
-
- Tuning files are found in the
- meta/conf/machine/include
- directory within the
- Source Directory.
- For example, many tune-* files
- (e.g. tune-arm1136jf-s.inc,
- tun-1586-nlp.inc, and so forth)
- reside in the
- poky/meta/conf/machine/include
- directory.
-
+
+ Tuning files are found in the
+ meta/conf/machine/include
+ directory within the
+ Source Directory.
+ For example, many tune-* files
+ (e.g. tune-arm1136jf-s.inc,
+ tun-1586-nlp.inc, and so forth)
+ reside in the
+ poky/meta/conf/machine/include
+ directory.
+
-
- To use an include file, you simply include them in the
- machine configuration file.
- For example, the Raspberry Pi BSP
- raspberrypi3.conf contains the
- following statement:
-
+
+ To use an include file, you simply include them in the
+ machine configuration file.
+ For example, the Raspberry Pi BSP
+ raspberrypi3.conf contains the
+ following statement:
+
include conf/machine/include/rpi-base.inc
-
-
-
+
+
+
-
- Miscellaneous BSP-Specific Recipe Files
+
+ Miscellaneous BSP-Specific Recipe Files
-
- You can find these files in the BSP Layer at:
-
+
+ You can find these files in the BSP Layer at:
+
meta-bsp_name/recipes-bsp/*
-
-
+
+
-
- This optional directory contains miscellaneous recipe
- files for the BSP.
- Most notably would be the formfactor files.
- For example, in the Raspberry Pi BSP there is the
- formfactor_0.0.bbappend 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
- machconfig file further down in
- the directory.
- Here is the machconfig file for
- the Raspberry Pi BSP:
-
+
+ This optional directory contains miscellaneous recipe
+ files for the BSP.
+ Most notably would be the formfactor files.
+ For example, in the Raspberry Pi BSP there is the
+ formfactor_0.0.bbappend 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
+ machconfig file further down in
+ the directory.
+ Here is the machconfig file for
+ the Raspberry Pi BSP:
+
HAVE_TOUCHSCREEN=0
HAVE_KEYBOARD=1
DISPLAY_CAN_ROTATE=0
DISPLAY_ORIENTATION=0
DISPLAY_DPI=133
-
-
+
+
-
- If a BSP does not have a formfactor entry, defaults
- are established according to the formfactor
- configuration file that is installed by the main
- formfactor recipe
- meta/recipes-bsp/formfactor/formfactor_0.0.bb,
- which is found in the
- Source Directory.
-
-
+
+ If a BSP does not have a formfactor entry, defaults
+ are established according to the formfactor
+ configuration file that is installed by the main
+ formfactor recipe
+ meta/recipes-bsp/formfactor/formfactor_0.0.bb,
+ which is found in the
+ Source Directory.
+
+
-
- Display Support Files
+
+ Display Support Files
-
- You can find these files in the BSP Layer at:
-
+
+ You can find these files in the BSP Layer at:
+
meta-bsp_name/recipes-graphics/*
-
-
+
+
-
- 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.
-
-
+
+ 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.
+
+
-
- Linux Kernel Configuration
+
+ Linux Kernel Configuration
-
- You can find these files in the BSP Layer at:
-
+
+ You can find these files in the BSP Layer at:
+
meta-bsp_name/recipes-kernel/linux/linux-yocto*.bbappend
-
-
+ meta-bsp_name/recipes-kernel/linux/*.bb
+
+
-
- These files append machine-specific changes to the main
- kernel recipe you are using.
-
+
+ Append files (*.bbappend modify
+ the main kernel recipe being used to build the image.
+ The *.bb files would be a
+ developer-supplied recipe.
+ This area of the BSP hierarchy can contain both these
+ types of files.
+
-
- For your BSP, you typically want to use an existing Yocto
- Project kernel recipe found in the
- Source Directory
- at meta/recipes-kernel/linux.
- You can append machine-specific changes to the
- kernel recipe by using a similarly named append
- file, which is located in the BSP Layer for your
- target device (e.g. the
- meta-bsp_name/recipes-kernel/linux directory).
-
+
+ For your BSP, you typically want to use an existing Yocto
+ Project kernel recipe found in the
+ Source Directory
+ at meta/recipes-kernel/linux.
+ You can append machine-specific changes to the
+ kernel recipe by using a similarly named append
+ file, which is located in the BSP Layer for your
+ target device (e.g. the
+ meta-bsp_name/recipes-kernel/linux directory).
+
-
- Suppose you are using the
- linux-yocto_4.4.bb recipe to
- build the kernel.
- In other words, you have selected the kernel in your
- bsp_name.conf
- file by adding
- PREFERRED_PROVIDER
- and
- PREFERRED_VERSION
- statements as follows:
-
+
+ Suppose you are using the
+ linux-yocto_4.4.bb recipe to
+ build the kernel.
+ In other words, you have selected the kernel in your
+ bsp_name.conf
+ file by adding
+ PREFERRED_PROVIDER
+ and
+ PREFERRED_VERSION
+ statements as follows:
+
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
PREFERRED_VERSION_linux-yocto ?= "4.4%"
-
-
- When the preferred provider is assumed by
- default, the
- PREFERRED_PROVIDER
- statement does not appear in the
- bsp_name.conf file.
-
- You would use the
- linux-yocto_4.4.bbappend
- file to append specific BSP settings to the kernel,
- thus configuring the kernel for your particular BSP.
-
+
+
+ When the preferred provider is assumed by
+ default, the
+ PREFERRED_PROVIDER
+ statement does not appear in the
+ bsp_name.conf file.
+
+ You would use the
+ linux-yocto_4.4.bbappend
+ file to append specific BSP settings to the kernel,
+ thus configuring the kernel for your particular BSP.
+
-
- You can find more information on what your append file
- should contain in the
- "Creating the Append File"
- section in the Yocto Project Linux Kernel Development
- Manual.
-
-
-
+
+ You can find more information on what your append file
+ should contain in the
+ "Creating the Append File"
+ section in the Yocto Project Linux Kernel Development
+ Manual.
+
-
- Developing a Board Support Package (BSP)
+
+ An alternate scenario is when you create your own
+ kernel recipe for the BSP.
+ A good example of this is the Raspberry Pi BSP.
+ If you examine the
+ recipes-kernel/linux directory
+ you see the following:
+
+ linux-raspberrypi-dev.bb
+ linux-raspberrypi.inc
+ linux-raspberrypi_4.14.bb
+ linux-raspberrypi_4.9.bb
+
+ The directory contains three kernel recipes and an
+ include file.
+
+
+
-
- This section contains the high-level procedure you can
- follow to create a BSP using the Yocto Project's
- BSP Tools.
- Although not required for BSP creation, the
- meta-intel repository, which
- contains many BSPs supported by the Yocto Project,
- is part of the example.
-
+
+ Developing a Board Support Package (BSP)
-
- For an example that shows how to create a new
- layer using the tools, see the
+
+ This section contains the high-level procedure you can
+ follow to create a BSP.
+ Although not required for BSP creation, the
+ meta-intel repository, which
+ contains many BSPs supported by the Yocto Project,
+ is part of the example.
+
+
+
+ For an example that shows how to create a new
+ layer using the tools, see the
+ "Creating a New BSP Layer Using the bitbake-layers Script"
+ section.
+
+
+
+ The following illustration and list summarize the BSP
+ creation general workflow.
+
+
+
+
+
+
+
+
+
+ Set up Your Host Development System
+ to Support Development Using the Yocto
+ Project:
+ See the
+ "Setting Up the Development Host to Use the Yocto Project"
+ section in the Yocto Project Development Tasks
+ Manual for options on how to get a system ready
+ to use the Yocto Project.
+
+
+ Establish the
+ meta-intel
+ Repository on Your System:
+ Having local copies of these supported BSP layers
+ on your system gives you access to layers you
+ might be able to leverage when creating your BSP.
+ For information on how to get these files, see the
+ "Preparing Your Build Host to Work with BSP Layers"
+ section.
+
+
+ Create Your Own BSP Layer Using the
+ bitbake-layers
+ Script:
+ Layers are ideal for isolating and storing work
+ for a given piece of hardware.
+ A layer is really just a location or area in which you
+ place the recipes and configurations for your BSP.
+ In fact, a BSP is, in itself, a special type of layer.
+ The simplest way to create a new BSP layer that is
+ compliant with the Yocto Project is to use the
+ bitbake-layers script.
+ For information about that script, see the
"Creating a New BSP Layer Using the bitbake-layers Script"
- section.
-
+ section.
-
- The following illustration and list summarize the BSP
- creation general workflow.
-
-
-
-
-
-
-
-
-
- Set up Your Host Development System
- to Support Development Using the Yocto
- Project:
- See the
- "Setting Up the Development Host to Use the Yocto Project"
- section in the Yocto Project Development Tasks
- Manual for options on how to get a system ready
- to use the Yocto Project.
-
-
- Establish the
- meta-intel
- Repository on Your System:
- Having local copies of these supported BSP layers
- on your system gives you access to layers you
- might be able to leverage when creating your BSP.
- For information on how to get these files, see the
- "Preparing Your Build Host to Work with BSP Layers"
- section.
-
-
- Create Your Own BSP Layer Using the
- bitbake-layers
- Script:
- Layers are ideal for isolating and storing work
- for a given piece of hardware.
- A layer is really just a location or area in which you
- place the recipes and configurations for your BSP.
- In fact, a BSP is, in itself, a special type of layer.
- The simplest way to create a new BSP layer that is
- compliant with the Yocto Project is to use the
- bitbake-layers script.
- For information about that script, see the
- "Creating a New BSP Layer Using the bitbake-layers Script"
- section.
-
- Another example that illustrates a layer
- is an application.
- Suppose you are creating an application that has
- library or other dependencies in order for it to
- compile and run.
- The layer, in this case, would be where all the
- recipes that define those dependencies are kept.
- The key point for a layer is that it is an
- isolated area that contains all the relevant
- information for the project that the
- OpenEmbedded build system knows about.
- For more information on layers, see the
- "The Yocto Project Layer Model"
- section in the Getting Started With Yocto Project
- Manual.
- You can also reference the
- "Understanding and Creating Layers"
- section in the Yocto Project Development Tasks
- Manual.
- For more information on BSP layers, see the
- "BSP Layers"
- section.
- Notes
-
-
- Five hardware reference BSPs exist
- that are part of the Yocto Project release
- and are located in the
- poky/meta-yocto-bsp BSP
- layer:
-
-
- Texas Instruments Beaglebone
- (beaglebone-yocto
-
-
- Freescale MPC8315E-RDB
- (mpc8315e-rdb)
-
-
- Ubiquiti Networks EdgeRouter Lite
- (edgerouter)
-
-
- Two general IA platforms
- (genericx86 and
- genericx86-64)
-
-
-
-
- Three core Intel BSPs exist as part of
- the Yocto Project release in the
- meta-intel layer:
-
-
- intel-core2-32,
- which is a BSP optimized for the Core2
- family of CPUs as well as all CPUs
- prior to the Silvermont core.
-
-
- intel-corei7-64,
- which is a BSP optimized for Nehalem
- and later Core and Xeon CPUs as well
- as Silvermont and later Atom CPUs,
- such as the Baytrail SoCs.
-
-
- intel-quark,
- which is a BSP optimized for the
- Intel Galileo gen1 & gen2
- development boards.
-
-
-
-
-
-
- When you set up a layer for a new BSP,
- you should follow a standard layout.
- This layout is described in the
- "Example Filesystem Layout"
- section.
- In the standard layout, notice the suggested
- structure for recipes and configuration
- information.
- You can see the standard layout for a BSP
- by examining any supported BSP found in the
- meta-intel layer inside
- the Source Directory.
-
-
- Make Configuration Changes to Your New
- BSP Layer:
- The standard BSP layer structure organizes the
- files you need to edit in
- conf and several
- recipes-* directories
- within the BSP layer.
- Configuration changes identify where your new
- layer is on the local system and identifies the
- kernel you are going to use.
- When you run the
- bitbake-layers script,
- you are able to interactively configure many
- things for the BSP (e.g. keyboard, touchscreen,
- and so forth).
-
-
- Make Recipe Changes to Your New BSP
- Layer:
- Recipe changes include altering recipes
- (*.bb files), removing
- recipes you do not use, and adding new recipes
- or append files (.bbappend)
- that support your hardware.
-
-
- Prepare for the Build:
- Once you have made all the changes to your BSP
- layer, there remains a few things you need to
- do for the OpenEmbedded build system in order
- for it to create your image.
- You need to get the build environment ready by
- sourcing an environment setup script
- (i.e. oe-init-build-env)
- and you need to be sure two key configuration
- files are configured appropriately: the
- conf/local.conf and the
- conf/bblayers.conf file.
- You must make the OpenEmbedded build system aware
- of your new layer.
- See the
- "Enabling Your Layer"
- section in the Yocto Project Development Tasks Manual
- for information on how to let the build system
- know about your new layer.
-
-
- Build the Image:
- The OpenEmbedded build system uses the BitBake tool
- to build images based on the type of image you want to
- create.
- You can find more information about BitBake in the
- BitBake User Manual.
-
-
- The build process supports several types of
- images to satisfy different needs.
- See the
- "Images"
- chapter in the Yocto Project Reference Manual for
- information on supported images.
-
-
-
-
-
-
- Requirements and Recommendations for Released BSPs
-
-
- Certain requirements exist for a released BSP to be
- considered compliant with the Yocto Project.
- Additionally, recommendations also exist.
- This section describes the requirements and
- recommendations for released BSPs.
-
-
-
- Released BSP Requirements
-
-
- Before looking at BSP requirements, you should consider
- the following:
+ Another example that illustrates a layer
+ is an application.
+ Suppose you are creating an application that has
+ library or other dependencies in order for it to
+ compile and run.
+ The layer, in this case, would be where all the
+ recipes that define those dependencies are kept.
+ The key point for a layer is that it is an
+ isolated area that contains all the relevant
+ information for the project that the
+ OpenEmbedded build system knows about.
+ For more information on layers, see the
+ "The Yocto Project Layer Model"
+ section in the Getting Started With Yocto Project
+ Manual.
+ You can also reference the
+ "Understanding and Creating Layers"
+ section in the Yocto Project Development Tasks
+ Manual.
+ For more information on BSP layers, see the
+ "BSP Layers"
+ section.
+ Notes
- 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"
- section in this manual and the
- "Understanding and Creating Layers""
- section in the Yocto Project Development Tasks
- Manual.
-
-
- The requirements in this section apply
- regardless of how you 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 conform 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, which
- is found in poky/meta
- directory of the
- Source Directory
- or in the OpenEmbedded Core Layer
- (openembedded-core) at
- .
-
-
- 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.
-
-
- 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
- "OpenEmbedded 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 no
- default license exists when one not specified.
- See the
- COPYING.MIT
- file for the Raspberry Pi BSP in the
- meta-raspberrypi 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 Raspberry Pi BSP in the
- meta-raspberrypi BSP layer
- as an example.
-
- At a minimum, the README
- file should contain the following:
+ Five hardware reference BSPs exist
+ that are part of the Yocto Project release
+ and are located in the
+ poky/meta-yocto-bsp BSP
+ layer:
- A brief description about the hardware the BSP
- targets.
+ Texas Instruments Beaglebone
+ (beaglebone-yocto
- 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.
+ Freescale MPC8315E-RDB
+ (mpc8315e-rdb)
- 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.
-
+ Ubiquiti Networks EdgeRouter Lite
+ (edgerouter)
+
- 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
- "Submitting a Change to the Yocto Project"
- section in the Yocto Project Development
- Tasks 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.
+ Two general IA platforms
+ (genericx86 and
+ genericx86-64)
- README.sources File:
- If you BSP contains binary images in the
- binary directory, you must
- include a README.sources
- file in the
- meta-bsp_name
- directory.
- This file specifies exactly where you can find
- the sources used to generate the binary images.
-
-
- Layer Configuration File:
- You must include a
- conf/layer.conf file 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 the
- BSP supports.
- 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.
-
- It is completely possible for a developer to
- structure the working repository as a
- conglomeration of unrelated BSP files, and to
- possibly generate BSPs targeted for release
- from that directory using scripts or some
- other mechanism
- (e.g. meta-yocto-bsp layer).
- Such considerations are outside the scope of
- this document.
-
+ Three core Intel BSPs exist as part of
+ the Yocto Project release in the
+ meta-intel layer:
+
+
+ intel-core2-32,
+ which is a BSP optimized for the Core2
+ family of CPUs as well as all CPUs
+ prior to the Silvermont core.
+
+
+ intel-corei7-64,
+ which is a BSP optimized for Nehalem
+ and later Core and Xeon CPUs as well
+ as Silvermont and later Atom CPUs,
+ such as the Baytrail SoCs.
+
+
+ intel-quark,
+ which is a BSP optimized for the
+ Intel Galileo gen1 & gen2
+ development boards.
+
+
+
+
+ When you set up a layer for a new BSP,
+ you should follow a standard layout.
+ This layout is described in the
+ "Example Filesystem Layout"
+ section.
+ In the standard layout, notice the suggested
+ structure for recipes and configuration
+ information.
+ You can see the standard layout for a BSP
+ by examining any supported BSP found in the
+ meta-intel layer inside
+ the Source Directory.
+
+
+ Make Configuration Changes to Your New
+ BSP Layer:
+ The standard BSP layer structure organizes the
+ files you need to edit in
+ conf and several
+ recipes-* directories
+ within the BSP layer.
+ Configuration changes identify where your new
+ layer is on the local system and identifies the
+ kernel you are going to use.
+ When you run the
+ bitbake-layers script,
+ you are able to interactively configure many
+ things for the BSP (e.g. keyboard, touchscreen,
+ and so forth).
+
+
+ Make Recipe Changes to Your New BSP
+ Layer:
+ Recipe changes include altering recipes
+ (*.bb files), removing
+ recipes you do not use, and adding new recipes
+ or append files (.bbappend)
+ that support your hardware.
+
+
+ Prepare for the Build:
+ Once you have made all the changes to your BSP
+ layer, there remains a few things you need to
+ do for the OpenEmbedded build system in order
+ for it to create your image.
+ You need to get the build environment ready by
+ sourcing an environment setup script
+ (i.e. oe-init-build-env)
+ and you need to be sure two key configuration
+ files are configured appropriately: the
+ conf/local.conf and the
+ conf/bblayers.conf file.
+ You must make the OpenEmbedded build system aware
+ of your new layer.
+ See the
+ "Enabling Your Layer"
+ section in the Yocto Project Development Tasks Manual
+ for information on how to let the build system
+ know about your new layer.
+
+
+ Build the Image:
+ The OpenEmbedded build system uses the BitBake tool
+ to build images based on the type of image you want to
+ create.
+ You can find more information about BitBake in the
+ BitBake User Manual.
-
-
- Released BSP Recommendations
+ The build process supports several types of
+ images to satisfy different needs.
+ See the
+ "Images"
+ chapter in the Yocto Project Reference Manual for
+ information on supported images.
+
+
+
+
-
- Following are recommendations for released BSPs that
- conform to the Yocto Project:
+
+ Requirements and Recommendations for Released BSPs
+
+
+ Certain requirements exist for a released BSP to be
+ considered compliant with the Yocto Project.
+ Additionally, recommendations also exist.
+ This section describes the requirements and
+ recommendations for released BSPs.
+
+
+
+ Released BSP Requirements
+
+
+ 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"
+ section in this manual and the
+ "Understanding and Creating Layers""
+ section in the Yocto Project Development Tasks
+ Manual.
+
+
+ The requirements in this section apply
+ regardless of how you 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 conform 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, which
+ is found in poky/meta
+ directory of the
+ Source Directory
+ or in the OpenEmbedded Core Layer
+ (openembedded-core) at
+ .
+
+
+ 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.
+
+
+ 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
+ "OpenEmbedded 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 no
+ default license exists when one not specified.
+ See the
+ COPYING.MIT
+ file for the Raspberry Pi BSP in the
+ meta-raspberrypi 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 Raspberry Pi BSP in the
+ meta-raspberrypi BSP layer
+ as an example.
+
+ At a minimum, the README
+ file should contain the following:
- Bootable Images:
- Released BSPs can contain one or more bootable
- images.
- Including bootable images allows users to easily
- try out the BSP using their own hardware.
-
- In some cases, it might not be convenient
- to include a bootable image.
- If so, 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.
-
- 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
- binary/ subdirectory located
- in the
- meta-bsp_name
- directory.
-
- If you do include a bootable image as part
- of the BSP and the image was built by software
- covered by the GPL or other open source licenses,
- it is your responsibility to understand
- and meet all licensing requirements, which could
- include distribution of source files.
-
+ A brief description about the hardware the BSP
+ targets.
- Use a Yocto Linux Kernel:
- Kernel recipes in the BSP should be based on a
- Yocto Linux kernel.
- Basing your recipes on these kernels reduces
- the costs for maintaining the BSP and increases
- its scalability.
- See the Yocto Linux Kernel
- category in the
- Source Repositories
- for these kernels.
+ 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
+ "Submitting a Change to the Yocto Project"
+ section in the Yocto Project Development
+ Tasks 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.
-
-
-
-
-
- Customizing a Recipe for a BSP
-
-
- If you plan on customizing a recipe for a particular BSP,
- you need to do the following:
-
-
- Create a *.bbappend file for
- the modified recipe.
- For information on using append files, see the
- "Using .bbappend Files in Your Layer"
- section in the Yocto Project Development Tasks
- Manual.
-
-
- Ensure your directory structure in the BSP layer
- that supports your machine is such that the
- OpenEmbedded build system can find it.
- See the example later in this section for more
- information.
-
-
- Put the append file in a directory whose name matches
- the machine's name and is located in an appropriate
- sub-directory inside the BSP layer (i.e.
- recipes-bsp,
- recipes-graphics,
- recipes-core, and so forth).
-
-
- Place the BSP-specific files in the proper
- directory inside the BSP layer.
- How expansive the layer is affects where you must
- place these files.
- For example, if your layer supports several
- different machine types, you need to be sure your
- layer's directory structure includes hierarchy
- that separates the files according to machine.
- If your layer does not support multiple machines,
- the layer would not have that additional hierarchy
- and the files would obviously not be able to reside
- in a machine-specific directory.
-
-
-
-
-
- Following is a specific example to help you better understand
- the process.
- This example customizes customizes a recipe by adding a
- BSP-specific configuration file named
- interfaces to the
- init-ifupdown_1.0.bb recipe for machine
- "xyz" where the BSP layer also supports several other
- machines:
-
-
- Edit the
- init-ifupdown_1.0.bbappend file
- so that it contains the following:
-
- FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
-
- The append file needs to be in the
- meta-xyz/recipes-core/init-ifupdown
- directory.
-
-
- Create and place the new
- interfaces configuration file in
- the BSP's layer here:
-
- meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
-
-
- If the meta-xyz layer did
- not support multiple machines, you would place
- the interfaces configuration
- file in the layer here:
-
- meta-xyz/recipes-core/init-ifupdown/files/interfaces
-
-
- The
- FILESEXTRAPATHS
- variable in the append files extends the search path
- the build system uses to find files during the build.
- Consequently, for this example you need to have the
- files directory in the same
- location as your append file.
-
-
-
-
-
-
- BSP Licensing Considerations
-
-
- In some cases, a BSP contains separately licensed
- Intellectual Property (IP) for a component or components.
- For these cases, you are required to accept the terms
- of a commercial or other type of license that requires
- some kind of explicit End User License Agreement (EULA).
- Once you accept the license, the OpenEmbedded build system
- can then build and include the corresponding component
- in the final BSP image.
- If the BSP is available as a pre-built image, you can
- download the image after agreeing to the license or EULA.
-
-
-
- You could find that some separately licensed components
- that are essential for normal operation of the system might
- not have an unencumbered (or free) substitute.
- Without these essential components, the system would be
- non-functional.
- Then again, you might find that other licensed components
- that are simply 'good-to-have' or purely elective do have
- an unencumbered, free replacement component that you can
- use rather than agreeing to the separately licensed
- component.
- Even for components essential to the system, you might
- find an unencumbered component that is not identical but
- will work as a less-capable version of the licensed version
- in the BSP recipe.
-
-
-
- For cases where you can substitute a free component and
- still maintain the system's functionality, the "DOWNLOADS"
- selection from the "SOFTWARE" tab on the
- Yocto Project website
- 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 their
- respective encumbered BSPs.
- If available, these substitutions are your simplest and
- most preferred options.
- Obviously, use of these substitutions assumes the resulting
- functionality meets system requirements.
-
- If however, a non-encumbered version is unavailable or
- it provides unsuitable functionality or quality, you can
- use an encumbered version.
-
-
-
-
- A couple different methods exist within the OpenEmbedded
- build system to satisfy the licensing requirements for an
- encumbered BSP.
- The following list describes them in order of preference:
-
-
- Use the
- LICENSE_FLAGS
- Variable to Define the Recipes that Have Commercial
- or Other Types of Specially-Licensed Packages:
- For each of those recipes, you can specify a
- matching license string in a
- local.conf variable named
- LICENSE_FLAGS_WHITELIST.
- Specifying the matching license string signifies
- that you agree to the license.
- Thus, the build system can build the corresponding
- recipe and include the component in the image.
- See the
- "Enabling Commercially Licensed Recipes"
- section in the Yocto Project Concepts Manual for
- details on how to use these variables.
-
- If you build as you normally would, without
- specifying any recipes in the
- LICENSE_FLAGS_WHITELIST, the
- build stops and provides you with the list of recipes
- that you have tried to include in the image that
- need entries in the
- LICENSE_FLAGS_WHITELIST.
- Once you enter the appropriate license flags into
- the whitelist, restart the build to continue where
- it left off.
- During the build, the prompt will not appear again
- since you have satisfied the requirement.
-
- Once the appropriate license flags are on the
- white list in the
- LICENSE_FLAGS_WHITELIST variable,
- you can build the encumbered image with no change
- at all to the normal build process.
-
-
- Get a Pre-Built Version of the BSP:
- You can get this type of BSP by selecting the
- "DOWNLOADS" item from the "SOFTWARE" tab on the
- Yocto Project website.
- You can download BSP tarballs that contain
- proprietary components after agreeing to the
- licensing requirements of each of the individually
- encumbered packages as part of the download process.
- Obtaining the BSP this way allows you to access an
- encumbered image immediately after agreeing to the
- click-through license agreements presented by the
- website.
- If you want to build the image yourself using
- the recipes contained within the BSP tarball,
- you will still need to create an appropriate
- LICENSE_FLAGS_WHITELIST
- to match the encumbered recipes in the BSP.
-
-
-
- Pre-compiled images are bundled with a time-limited
- kernel that runs for a predetermined amount of time
- (10 days) before it forces the system to reboot.
- This limitation is meant to discourage direct
- redistribution of the image.
- You must eventually rebuild the image if you want
- to remove this restriction.
-
-
-
-
-
- Using the Yocto Project's BSP Tools
-
-
- The Yocto Project includes a couple of tools that enable
- you to create a BSP layer
- from scratch and do basic configuration and maintenance
- of the kernel without ever looking at a Metadata file.
- These tools are yocto-bsp and yocto-kernel,
- respectively.
-
-
-
- The following sections describe the common location and help features as well
- as provide details for the
- yocto-bsp and yocto-kernel tools.
-
-
-
- Common Features
-
-
- Designed to have a command interface somewhat like
- Git, each
- tool is structured as a set of sub-commands under a
- top-level command.
- The top-level command (yocto-bsp
- or yocto-kernel) itself does
- nothing but invoke or provide help on the sub-commands
- it supports.
-
-
-
- Both tools reside in the scripts/ subdirectory
- of the Source Directory.
- Consequently, to use the scripts, you must source the
- environment just as you would when invoking a build:
-
- $ source oe-init-build-env build_dir
-
-
-
-
- The most immediately useful function is to get help on both tools.
- The built-in help system makes it easy to drill down at
- any time and view the syntax required for any specific command.
- Simply enter the name of the command with the help
- switch:
-
- $ yocto-bsp help
- Usage:
-
- Create a customized Yocto BSP layer.
-
- usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
-
- Current 'yocto-bsp' commands are:
- create Create a new Yocto BSP
- list List available values for options and BSP properties
-
- See 'yocto-bsp help COMMAND' for more information on a specific command.
-
-
- Options:
- --version show program's version number and exit
- -h, --help show this help message and exit
- -D, --debug output debug information
-
-
-
-
- Similarly, entering just the name of a sub-command shows the detailed usage
- for that sub-command:
-
- $ yocto-bsp create
- ERROR:root:Wrong number of arguments, exiting
-
- Usage:
-
- Create a new Yocto BSP
-
- usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
- [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
-
- This command creates a Yocto BSP based on the specified parameters.
- The new BSP will be a new Yocto BSP layer contained by default within
- the top-level directory specified as 'meta-bsp-name'. The -o option
- can be used to place the BSP layer in a directory with a different
- name and location.
-
- The value of the 'karch' parameter determines the set of files that
- will be generated for the BSP, along with the specific set of
- 'properties' that will be used to fill out the BSP-specific portions
- of the BSP. The possible values for the 'karch' parameter can be
- listed via 'yocto-bsp list karch'.
-
- ...
-
-
-
-
- For any sub-command, you can use the word "help" option just before the
- sub-command to get more extensive documentation:
-
- $ yocto-bsp help create
-
- NAME
- yocto-bsp create - Create a new Yocto BSP
-
- SYNOPSIS
- yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
- [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
-
- DESCRIPTION
- This command creates a Yocto BSP based on the specified
- parameters. The new BSP will be a new Yocto BSP layer contained
- by default within the top-level directory specified as
- 'meta-bsp-name'. The -o option can be used to place the BSP layer
- in a directory with a different name and location.
-
- ...
-
-
-
-
- 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 maintenance on that BSP using
- the tools.
+
+
+ README.sources File:
+ If you BSP contains binary images in the
+ binary directory, you must
+ include a README.sources
+ file in the
+ meta-bsp_name
+ directory.
+ This file specifies exactly where you can find
+ the sources used to generate the binary images.
+
+
+ Layer Configuration File:
+ You must include a
+ conf/layer.conf file 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 the
+ BSP supports.
+ 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.
- You can also use the bitbake-layers script to create
- a "generic" layer.
- For information on using this script to create a layer, see the
- "Creating a General Layer Using the bitbake-layers Script"
- section in the Yocto Project Development Tasks Manual.
+ It is completely possible for a developer to
+ structure the working repository as a
+ conglomeration of unrelated BSP files, and to
+ possibly generate BSPs targeted for release
+ from that directory using scripts or some
+ other mechanism
+ (e.g. meta-yocto-bsp layer).
+ Such considerations are outside the scope of
+ this document.
-
+
+
+
+
-
- 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.
-
-
+
+ Released BSP Recommendations
+
+ Following are recommendations for released BSPs that
+ conform to the Yocto Project:
+
+
+ Bootable Images:
+ Released BSPs can contain one or more bootable
+ images.
+ Including bootable images allows users to easily
+ try out the BSP using their own hardware.
-
- Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script
+ In some cases, it might not be convenient
+ to include a bootable image.
+ If so, 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.
-
- I have put in information that will be the basis of this section,
- but it is missing a lot at this point.
- This whole section needs reviewed and filled in with proper
- information.
-
+ 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
+ binary/ subdirectory located
+ in the
+ meta-bsp_name
+ directory.
+
+ If you do include a bootable image as part
+ of the BSP and the image was built by software
+ covered by the GPL or other open source licenses,
+ it is your responsibility to understand
+ and meet all licensing requirements, which could
+ include distribution of source files.
+
+
+
+ Use a Yocto Linux Kernel:
+ Kernel recipes in the BSP should be based on a
+ Yocto Linux kernel.
+ Basing your recipes on these kernels reduces
+ the costs for maintaining the BSP and increases
+ its scalability.
+ See the Yocto Linux Kernel
+ category in the
+ Source Repositories
+ for these kernels.
+
+
+
+
+
-
- [INTRODUCE THE PROCEDURE AND LINK BACK TO BSP layer.
- IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET
- UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.]
-
- [PARAMETER 1]
- [PARAMETER 2]
- [PARAMETER 3]
- [PARAMETER 4]
- [PARAMETER 5]
- [PARAMETER 6]
- [PARAMETER 7]
-
-
+
+ Customizing a Recipe for a BSP
-
- The following procedure creates a BSP layer:
-
-
- Create General Layer:
- Use the bitbake-layers script with the
- create-layer subcommand to create a
- new general layer.
- For instructions on how to create a general layer using the
- bitbake-layers script, see the
- "Creating a General Layer Using the bitbake-layers Script"
- section in the Yocto Project Development Tasks Manual.
-
-
- Create a Machine Configuration File:
- Create a conf/machine/>machine<.conf
- file.
- See meta-yocto-bsp/conf/machine for sample
- >machine.conf< files.
- Other samples exist from other vendors such as
- meta-intel, meta-ti,
- and meta-freescale that have more specific machine
- and tuning examples.
-
-
- Create a Kernel Recipe:
- Create a kernel recipe in recipes-kernel/linux
- either using a linux-yocto kernel with a .bbappend
- file or a new custom kernel recipe file (i.e. .bb
- file).
- The BSP layers mentioned in the previous step also contain different
- kernel examples.
- You can start with the linux-yocto or use a custom kernel.
- See the
- "Modifying an Existing Recipe"
- section in the Yocto Project Linux Kernel Development Manual
- for information on how to create a custom kernel.
-
-
-
+
+ If you plan on customizing a recipe for a particular BSP,
+ you need to do the following:
+
+
+ Create a *.bbappend file for
+ the modified recipe.
+ For information on using append files, see the
+ "Using .bbappend Files in Your Layer"
+ section in the Yocto Project Development Tasks
+ Manual.
+
+
+ Ensure your directory structure in the BSP layer
+ that supports your machine is such that the
+ OpenEmbedded build system can find it.
+ See the example later in this section for more
+ information.
+
+
+ Put the append file in a directory whose name matches
+ the machine's name and is located in an appropriate
+ sub-directory inside the BSP layer (i.e.
+ recipes-bsp,
+ recipes-graphics,
+ recipes-core, and so forth).
+
+
+ Place the BSP-specific files in the proper
+ directory inside the BSP layer.
+ How expansive the layer is affects where you must
+ place these files.
+ For example, if your layer supports several
+ different machine types, you need to be sure your
+ layer's directory structure includes hierarchy
+ that separates the files according to machine.
+ If your layer does not support multiple machines,
+ the layer would not have that additional hierarchy
+ and the files would obviously not be able to reside
+ in a machine-specific directory.
+
+
+
-
- [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO
- BE PROVIDED BY ENGINEERS.]
-
-
-
- The remainder of this section presents an example that uses
- myarm as the machine name and qemu
- as the machine architecture.
- Of the available architectures, qemu is the only architecture
- that causes the script to prompt you further for an actual architecture.
- In every other way, this architecture is representative of how creating a BSP for
- an actual machine would work.
- The reason the example uses this architecture is because it is an emulated architecture
- and can easily be followed without requiring actual hardware.
-
-
-
-
-
- Following is a complete example:
+
+ Following is a specific example to help you better understand
+ the process.
+ This example customizes customizes a recipe by adding a
+ BSP-specific configuration file named
+ interfaces to the
+ init-ifupdown_1.0.bb recipe for machine
+ "xyz" where the BSP layer also supports several other
+ machines:
+
+
+ Edit the
+ init-ifupdown_1.0.bbappend file
+ so that it contains the following:
+
+ FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
+
+ The append file needs to be in the
+ meta-xyz/recipes-core/init-ifupdown
+ directory.
+
+
+ Create and place the new
+ interfaces configuration file in
+ the BSP's layer here:
+
+ meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
+
+
+ If the meta-xyz layer did
+ not support multiple machines, you would place
+ the interfaces configuration
+ file in the layer here:
- [INSERT EXAMPLE - NEED EXAMPLE]
+ meta-xyz/recipes-core/init-ifupdown/files/interfaces
-
-
+
+ The
+ FILESEXTRAPATHS
+ variable in the append files extends the search path
+ the build system uses to find files during the build.
+ Consequently, for this example you need to have the
+ files directory in the same
+ location as your append file.
+
+
+
+
-
- Once the BSP Layer is created, you must add it to your
- bblayers.conf file.
- Here is an example:
-
+
+ BSP Licensing Considerations
+
+
+ In some cases, a BSP contains separately licensed
+ Intellectual Property (IP) for a component or components.
+ For these cases, you are required to accept the terms
+ of a commercial or other type of license that requires
+ some kind of explicit End User License Agreement (EULA).
+ Once you accept the license, the OpenEmbedded build system
+ can then build and include the corresponding component
+ in the final BSP image.
+ If the BSP is available as a pre-built image, you can
+ download the image after agreeing to the license or EULA.
+
+
+
+ You could find that some separately licensed components
+ that are essential for normal operation of the system might
+ not have an unencumbered (or free) substitute.
+ Without these essential components, the system would be
+ non-functional.
+ Then again, you might find that other licensed components
+ that are simply 'good-to-have' or purely elective do have
+ an unencumbered, free replacement component that you can
+ use rather than agreeing to the separately licensed
+ component.
+ Even for components essential to the system, you might
+ find an unencumbered component that is not identical but
+ will work as a less-capable version of the licensed version
+ in the BSP recipe.
+
+
+
+ For cases where you can substitute a free component and
+ still maintain the system's functionality, the "DOWNLOADS"
+ selection from the "SOFTWARE" tab on the
+ Yocto Project website
+ 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 their
+ respective encumbered BSPs.
+ If available, these substitutions are your simplest and
+ most preferred options.
+ Obviously, use of these substitutions assumes the resulting
+ functionality meets system requirements.
+
+ If however, a non-encumbered version is unavailable or
+ it provides unsuitable functionality or quality, you can
+ use an encumbered version.
+
+
+
+
+ A couple different methods exist within the OpenEmbedded
+ build system to satisfy the licensing requirements for an
+ encumbered BSP.
+ The following list describes them in order of preference:
+
+
+ Use the
+ LICENSE_FLAGS
+ Variable to Define the Recipes that Have Commercial
+ or Other Types of Specially-Licensed Packages:
+ For each of those recipes, you can specify a
+ matching license string in a
+ local.conf variable named
+ LICENSE_FLAGS_WHITELIST.
+ Specifying the matching license string signifies
+ that you agree to the license.
+ Thus, the build system can build the corresponding
+ recipe and include the component in the image.
+ See the
+ "Enabling Commercially Licensed Recipes"
+ section in the Yocto Project Concepts Manual for
+ details on how to use these variables.
+
+ If you build as you normally would, without
+ specifying any recipes in the
+ LICENSE_FLAGS_WHITELIST, the
+ build stops and provides you with the list of recipes
+ that you have tried to include in the image that
+ need entries in the
+ LICENSE_FLAGS_WHITELIST.
+ Once you enter the appropriate license flags into
+ the whitelist, restart the build to continue where
+ it left off.
+ During the build, the prompt will not appear again
+ since you have satisfied the requirement.
+
+ Once the appropriate license flags are on the
+ white list in the
+ LICENSE_FLAGS_WHITELIST variable,
+ you can build the encumbered image with no change
+ at all to the normal build process.
+
+
+ Get a Pre-Built Version of the BSP:
+ You can get this type of BSP by selecting the
+ "DOWNLOADS" item from the "SOFTWARE" tab on the
+ Yocto Project website.
+ You can download BSP tarballs that contain
+ proprietary components after agreeing to the
+ licensing requirements of each of the individually
+ encumbered packages as part of the download process.
+ Obtaining the BSP this way allows you to access an
+ encumbered image immediately after agreeing to the
+ click-through license agreements presented by the
+ website.
+ If you want to build the image yourself using
+ the recipes contained within the BSP tarball,
+ you will still need to create an appropriate
+ LICENSE_FLAGS_WHITELIST
+ to match the encumbered recipes in the BSP.
+
+
+
+ Pre-compiled images are bundled with a time-limited
+ kernel that runs for a predetermined amount of time
+ (10 days) before it forces the system to reboot.
+ This limitation is meant to discourage direct
+ redistribution of the image.
+ You must eventually rebuild the image if you want
+ to remove this restriction.
+
+
+
+
+
+ Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script
+
+
+ [INTRODUCE THE PROCEDURE AND LINK BACK TO BSP layer.
+ IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET
+ UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.]
+
+ [PARAMETER 1]
+ [PARAMETER 2]
+ [PARAMETER 3]
+ [PARAMETER 4]
+ [PARAMETER 5]
+ [PARAMETER 6]
+ [PARAMETER 7]
+
+
+
+
+ The following procedure creates a BSP layer:
+
+
+ Create General Layer:
+ Use the bitbake-layers script with the
+ create-layer subcommand to create a
+ new general layer.
+ For instructions on how to create a general layer using the
+ bitbake-layers script, see the
+ "Creating a General Layer Using the bitbake-layers Script"
+ section in the Yocto Project Development Tasks Manual.
+
+
+ Create a Machine Configuration File:
+ Create a conf/machine/>machine<.conf
+ file.
+ See meta-yocto-bsp/conf/machine for sample
+ >machine.conf< files.
+ Other samples exist from other vendors such as
+ meta-intel, meta-ti,
+ and meta-freescale that have more specific machine
+ and tuning examples.
+
+
+ Create a Kernel Recipe:
+ Create a kernel recipe in recipes-kernel/linux
+ either using a linux-yocto kernel with a .bbappend
+ file or a new custom kernel recipe file (i.e. .bb
+ file).
+ The BSP layers mentioned in the previous step also contain different
+ kernel examples.
+ You can start with the linux-yocto or use a custom kernel.
+ See the
+ "Modifying an Existing Recipe"
+ section in the Yocto Project Linux Kernel Development Manual
+ for information on how to create a custom kernel.
+
+
+
+
+
+ [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO
+ BE PROVIDED BY ENGINEERS.]
+
+
+
+ The remainder of this section presents an example that uses
+ myarm as the machine name and qemu
+ as the machine architecture.
+ Of the available architectures, qemu is the only architecture
+ that causes the script to prompt you further for an actual architecture.
+ In every other way, this architecture is representative of how creating a BSP for
+ an actual machine would work.
+ The reason the example uses this architecture is because it is an emulated architecture
+ and can easily be followed without requiring actual hardware.
+
+
+
+ Following is a complete example:
+
+ [INSERT EXAMPLE - NEED EXAMPLE]
+
+
+
+
+ Once the BSP Layer is created, you must add it to your
+ bblayers.conf file.
+ Here is an example:
+
BBLAYERS = ? " \
/usr/local/src/yocto/meta \
/usr/local/src/yocto/meta-poky \
/usr/local/src/yocto/meta-yocto-bsp \
/usr/local/src/yocto/meta-myarm \
"
-
- Adding the layer to this file allows the build system to build the BSP and
- find the layer along with other Metadata it needs.
-
-
-
-
- Managing Kernel Patches and Config Items with yocto-kernel
-
-
- Assuming you have created a BSP Layer using
-
- yocto-bsp and you added it to your
- BBLAYERS
- variable in the bblayers.conf file, you can now use
- the yocto-kernel script to add patches and configuration
- items to the BSP's kernel.
-
-
-
- The yocto-kernel script allows you to add, remove, and list patches
- and kernel config settings to a BSP's kernel
- .bbappend file.
- All you need to do is use the appropriate sub-command.
- Recall that the easiest way to see exactly what sub-commands are available
- is to use the yocto-kernel built-in help as follows:
-
- $ yocto-kernel --help
- Usage:
-
- Modify and list Yocto BSP kernel config items and patches.
-
- usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
-
- Current 'yocto-kernel' commands are:
- config list List the modifiable set of bare kernel config options for a BSP
- config add Add or modify bare kernel config options for a BSP
- config rm Remove bare kernel config options from a BSP
- patch list List the patches associated with a BSP
- patch add Patch the Yocto kernel for a BSP
- patch rm Remove patches from a BSP
- feature list List the features used by a BSP
- feature add Have a BSP use a feature
- feature rm Have a BSP stop using a feature
- features list List the features available to BSPs
- feature describe Describe a particular feature
- feature create Create a new BSP-local feature
- feature destroy Remove a BSP-local feature
-
- See 'yocto-kernel help COMMAND' for more information on a specific command.
-
-
-
- Options:
- --version show program's version number and exit
- -h, --help show this help message and exit
- -D, --debug output debug information
-
-
-
-
- The yocto-kernel patch add sub-command allows you to add a
- patch to a BSP.
- The following example adds two patches to the myarm BSP:
-
- $ yocto-kernel patch add myarm ~/test.patch
- Added patches:
- test.patch
-
- $ yocto-kernel patch add myarm ~/yocto-testmod.patch
- Added patches:
- yocto-testmod.patch
-
- Although the previous example adds patches one at a time, it is possible
- to add multiple patches at the same time.
-
-
-
- You can verify patches have been added by using the
- yocto-kernel patch list sub-command.
- Here is an example:
-
- $ yocto-kernel patch list myarm
- The current set of machine-specific patches for myarm is:
- 1) test.patch
- 2) yocto-testmod.patch
-
-
-
-
- You can also use the yocto-kernel script to
- remove a patch using the yocto-kernel patch rm sub-command.
- Here is an example:
-
- $ yocto-kernel patch rm myarm
- Specify the patches to remove:
- 1) test.patch
- 2) yocto-testmod.patch
- 1
- Removed patches:
- test.patch
-
-
-
-
- Again, using the yocto-kernel patch list sub-command,
- you can verify that the patch was in fact removed:
-
- $ yocto-kernel patch list myarm
- The current set of machine-specific patches for myarm is:
- 1) yocto-testmod.patch
-
-
-
-
- In a completely similar way, you can use the yocto-kernel config add
- sub-command to add one or more kernel config item settings to a BSP.
- The following commands add a couple of config items to the
- myarm BSP:
-
- $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
- Added item:
- CONFIG_MISC_DEVICES=y
-
- $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y
- Added item:
- CONFIG_YOCTO_TESTMOD=y
-
-
- Although the previous example adds config items one at a time, it is possible
- to add multiple config items at the same time.
-
-
-
-
- You can list the config items now associated with the BSP.
- Doing so shows you the config items you added as well as others associated
- with the BSP:
-
- $ yocto-kernel config list myarm
- The current set of machine-specific kernel config items for myarm is:
- 1) CONFIG_MISC_DEVICES=y
- 2) CONFIG_YOCTO_TESTMOD=y
-
-
-
-
- Finally, you can remove one or more config items using the
- yocto-kernel config rm sub-command in a manner
- completely analogous to yocto-kernel patch rm.
-
-
-
+
+ Adding the layer to this file allows the build system to build the BSP and
+ find the layer along with other Metadata it needs.
+
+
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index d4bed076aa..1ea5ca53d2 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -1224,18 +1224,6 @@
the
"Getting Ready for Traditional Kernel Development"
Section.
-
-
-
- Although this example uses Git and shell commands to generate the
- patch, you could use the yocto-kernel script
- found in the Source Directory
- under scripts to add and manage kernel
- patches and configuration.
- See the "Managing kernel Patches and Config Items with yocto-kernel"
- section in the Yocto Project Board Support Packages (BSP)
- Developer's Guide for more information on the
- yocto-kernel script.
Edit the Source Files
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index dba45495f2..7a5a34deb1 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -127,18 +127,6 @@
-
-
- Finally, while this document focuses on the manual creation of
- recipes, patches, and configuration files, the Yocto Project
- Board Support Package (BSP) tools are available to automate
- this process with existing content and work well to create the
- initial framework and boilerplate code.
- For details on these tools, see the
- "Using the Yocto Project's BSP Tools"
- section in the Yocto Project Board Support Package (BSP) Developer's
- Guide.
-
@@ -243,11 +231,7 @@
Additionally, if you are working in a BSP layer
and need to modify the BSP's kernel's configuration,
- you can use the
- yocto-kernel
- script as well as menuconfig.
- The yocto-kernel script lets
- you interactively set up kernel configurations.
+ you can use menuconfig.
Rebuild the Kernel Image With Your Changes:
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
index e984391fdf..45c71bc1b1 100644
--- a/documentation/toaster-manual/toaster-manual-reference.xml
+++ b/documentation/toaster-manual/toaster-manual-reference.xml
@@ -92,11 +92,11 @@
For general information on layers, see the
- "BSP Layers"
- and
- "Using the Yocto Project's BSP Tools"
- sections in the Yocto Project Board Support Package (BSP)
- Developer's Guide.
+ "The Yocto Project Layer Model"
+ section in the Getting Started With Yocto Project Manual.
+ For information on how to create layers, see the
+ "Understanding and Creating Layers"
+ section in the Yocto Project Development Tasks Manual.