Yocto 2.5
Move OpenBMC to Yocto 2.5(sumo)
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Change-Id: I5c5ad6904a16e14c1c397f0baf10c9d465594a78
diff --git a/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml b/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml
index d7b6f15..00a28b0 100644
--- a/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml
+++ b/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml
@@ -4,371 +4,428 @@
<chapter id='bsp'>
- <title>Board Support Packages (BSP) - Developer's Guide</title>
+<title>Board Support Packages (BSP) - Developer's Guide</title>
- <para>
- A Board Support Package (BSP) is a collection of information that
- defines how to support a particular hardware device, set of devices, or
- hardware platform.
- The BSP includes information about the hardware features
- present on the device and kernel configuration information along with any
- additional hardware drivers required.
- The BSP also lists any additional software
- components required in addition to a generic Linux software stack for both
- essential and optional platform features.
- </para>
+<para>
+ A Board Support Package (BSP) is a collection of information that
+ defines how to support a particular hardware device, set of devices, or
+ hardware platform.
+ The BSP includes information about the hardware features
+ present on the device and kernel configuration information along with any
+ additional hardware drivers required.
+ The BSP also lists any additional software
+ components required in addition to a generic Linux software stack for both
+ essential and optional platform features.
+</para>
- <para>
- This 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
- <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project
- <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
- </para>
+<para>
+ 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
+ <link linkend='bsp-layers'>BSP Layer</link> using the
+ <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></link>
+ tool.
+</para>
- <section id='bsp-layers'>
- <title>BSP Layers</title>
+<section id='bsp-layers'>
+ <title>BSP Layers</title>
- <para>
- 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, layers in the Yocto Project use the
- following well-established naming convention:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>
- </literallayout>
- The string "meta-" is prepended to the machine or platform name, which is
- <replaceable>bsp_name</replaceable> in the above form.
- <note><title>Tip</title>
- 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 <filename>meta-</filename>.
- However, you might run into situations where obscure
- scripts assume this convention.
- </note>
- </para>
+ <para>
+ 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:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>
+ </literallayout>
+ The string "meta-" is prepended to the machine or platform name, which is
+ <replaceable>bsp_root_name</replaceable> in the above form.
+ <note><title>Tip</title>
+ 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 <filename>meta-</filename>.
+ However, various scripts and tools in the Yocto Project
+ development environment assume this convention.
+ </note>
+ </para>
- <para>
- 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
- <ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
- through a web interface at
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
- If you go to that interface, you will find near the bottom of the list
- under "Yocto Metadata Layers" several BSP layers all of which are
- supported by the Yocto Project (e.g. <filename>meta-raspberrypi</filename> and
- <filename>meta-intel</filename>).
- 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:
- <literallayout class='monospaced'>
+ <para>
+ 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
+ <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
+ through a web interface at
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
+ If you go to that interface, you will find a list of repositories
+ under "Yocto Metadata Layers".
+ <note>
+ Layers that are no longer actively supported as part of the
+ Yocto Project appear under the heading "Yocto Metadata Layer
+ Archive."
+ </note>
+ Each repository is a BSP layer supported by the Yocto Project
+ (e.g. <filename>meta-raspberrypi</filename> and
+ <filename>meta-intel</filename>).
+ 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:
+ <literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/meta-raspberrypi
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- In addition to BSP layers near the bottom of that referenced
- Yocto Project Source Repository, the
- <filename>meta-yocto-bsp</filename> layer is part of the
- shipped <filename>poky</filename> repository.
- The <filename>meta-yocto-bsp</filename> layer maintains several
- BSPs such as the Beaglebone, EdgeRouter, and generic versions of
- both 32 and 64-bit IA machines.
- </para>
+ <para>
+ In addition to BSP layers, the
+ <filename>meta-yocto-bsp</filename> layer is part of the
+ shipped <filename>poky</filename> repository.
+ The <filename>meta-yocto-bsp</filename> layer maintains several
+ BSPs such as the Beaglebone, EdgeRouter, and generic versions of
+ both 32-bit and 64-bit IA machines.
+ </para>
- <para>
- For information on the BSP development workflow, see the
- "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
- section.
- For more information on how to set up a local copy of source files
- from a Git repository, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
- section also in the Yocto Project Development Tasks Manual.
- </para>
+ <para>
+ For information on the BSP development workflow, see the
+ "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
+ section.
+ For more information on how to set up a local copy of source files
+ from a Git repository, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
- <para>
- The layer's base directory
- (<filename>meta-<replaceable>bsp_name</replaceable></filename>)
- is the root of the BSP Layer.
- This root is what you add to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
- variable in the <filename>conf/bblayers.conf</filename> file found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
- which is established after you run the OpenEmbedded build environment
- setup script (i.e.
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
- Adding the root allows the OpenEmbedded build system to recognize the BSP
- definition and from it build an image.
- Here is an example:
- <literallayout class='monospaced'>
+ <para>
+ The layer's base directory
+ (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>)
+ is the root directory of the BSP Layer.
+ This directory is what you add to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
+ variable in the <filename>conf/bblayers.conf</filename> file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ which is established after you run the OpenEmbedded build environment
+ setup script (i.e.
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
+ Adding the root directory allows the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ to recognize the BSP layer and from it build an image.
+ Here is an example:
+ <literallayout class='monospaced'>
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 \
"
- </literallayout>
- </para>
+ </literallayout>
+ <note><title>Tip</title>
+ Ordering and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
+ for the layers listed in <filename>BBLAYERS</filename>
+ matter.
+ For example, if multiple layers define a machine
+ configuration, the OpenEmbedded build system uses
+ the last layer searched given similar layer
+ priorities.
+ The build system works from the top-down through
+ the layers listed in <filename>BBLAYERS</filename>.
+ </note>
+ </para>
- <para>
- 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
- <filename>BBLAYERS</filename> variable in order to build the BSP.
- You must also specify in the "Dependencies" section of the BSP's
- <filename>README</filename> file any requirements for additional
- layers and, preferably, any
- build instructions that might be contained elsewhere
- in the <filename>README</filename> file.
- </para>
+ <para>
+ Some BSPs require or depend on additional layers
+ beyond the BSP's root layer in order to be functional.
+ In this case, you need to specify these layers in the
+ <filename>README</filename> "Dependencies" section of the
+ BSP's root layer.
+ Additionally, if any build instructions exist for the
+ BSP, you must add them to the "Dependencies" section.
+ </para>
- <para>
- Some layers function as a layer to hold other BSP layers.
- An example of this type of layer is the <filename>meta-intel</filename> layer,
- which contains a number of individual BSP sub-layers, as well as a directory
- named <filename>common/</filename> full of common content across those layers.
- Another example is the <filename>meta-yocto-bsp</filename> layer mentioned
- earlier.
- </para>
+ <para>
+ Some layers function as a layer to hold other BSP layers.
+ These layers are knows as
+ "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>".
+ An example of this type of layer is the
+ <filename>meta-intel</filename> layer.
+ This layer contains BSP layers for the Intel-core2-32
+ <trademark class='registered'>Intel</trademark> Common Core
+ (Intel-core2-32) and the Intel-corei7-64
+ <trademark class='registered'>Intel</trademark> Common Core
+ (Intel-corei7-64).
+ the <filename>meta-intel</filename> layer also contains
+ the <filename>common/</filename> directory, which contains
+ common content across those layers.
+ </para>
- <para>
- For more detailed information on layers, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section of the Yocto Project Development Tasks Manual.
- </para>
- </section>
+ <para>
+ For more information on layers, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ </para>
+</section>
- <section id='preparing-your-build-host-to-work-with-bsp-layers'>
- <title>Preparing Your Build Host to Work With BSP Layers</title>
+<section id='preparing-your-build-host-to-work-with-bsp-layers'>
+ <title>Preparing Your Build Host to Work With BSP Layers</title>
- <para>
- 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
- "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</link>"
- section.
- <note>
- For structural information on BSPs, see the
- <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
- section.
- </note>
+ <para>
+ 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
+ "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
+ section.
+ <note>
+ For structural information on BSPs, see the
+ <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
+ section.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set Up the Build Environment:</emphasis>
+ Be sure you are set up to use BitBake in a shell.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
+ 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.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
+ You need to have a local copy of the Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (i.e. a local <filename>poky</filename> repository).
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
+ and possibly the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
+ or
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
+ sections all in the Yocto Project Development Tasks Manual for
+ information on how to clone the <filename>poky</filename>
+ repository and check out the appropriate branch for your work.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Determine the BSP Layer You Want:</emphasis>
+ 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
+ <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
+ for the release.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Clone the
+ <filename>meta-intel</filename> BSP Layer:</emphasis>
+ If your hardware is based on current Intel CPUs and devices,
+ you can leverage this BSP layer.
+ For details on the <filename>meta-intel</filename> BSP layer,
+ see the layer's
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
+ file.
<orderedlist>
<listitem><para>
- <emphasis>Set Up the Build Environment:</emphasis>
- Be sure you are set up to use BitBake in a shell.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
- 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.
- </para></listitem>
- <listitem><para>
- <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
- You need to have a local copy of the Yocto Project
+ <emphasis>Navigate to Your Source Directory:</emphasis>
+ Typically, you set up the
+ <filename>meta-intel</filename> Git repository
+ inside the
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- (i.e. a local <filename>poky</filename> repository).
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
- and possibly the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
- and
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
- sections all in the Yocto Project Development Tasks Manual for
- information on how to clone the <filename>poky</filename>
- repository and check out the appropriate branch for your work.
+ (e.g. <filename>poky</filename>).
+ <literallayout class='monospaced'>
+ $ cd /home/<replaceable>you</replaceable>/poky
+ </literallayout>
</para></listitem>
<listitem><para>
- <emphasis>Determine the BSP Layer You Want:</emphasis>
- 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
- <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
- for the release.
- </para></listitem>
- <listitem><para>
- <emphasis>Optionally Clone the
- <filename>meta-intel</filename> BSP Layer:</emphasis>
- If your hardware is based on current Intel CPUs and devices,
- you can leverage this BSP layer.
- For details on the <filename>meta-intel</filename> BSP layer,
- see the layer's
- <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
- file.
- <orderedlist>
- <listitem><para>
- <emphasis>Navigate to Your Source Directory:</emphasis>
- Typically, you set up the
- <filename>meta-intel</filename> Git repository
- inside the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- (e.g. <filename>poky</filename>).
- </para></listitem>
- <listitem><para>
- <emphasis>Clone the Layer:</emphasis>
- <literallayout class='monospaced'>
+ <emphasis>Clone the Layer:</emphasis>
+ <literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/meta-intel.git
Cloning into 'meta-intel'...
- remote: Counting objects: 14224, done.
- remote: Compressing objects: 100% (4591/4591), done.
- remote: Total 14224 (delta 8245), reused 13985 (delta 8006)
- Receiving objects: 100% (14224/14224), 4.29 MiB | 2.90 MiB/s, done.
- Resolving deltas: 100% (8245/8245), done.
- Checking connectivity... done.
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Check Out the Proper Branch:</emphasis>
- The branch you check out for
- <filename>meta-intel</filename> must match the same
- branch you are using for the Yocto Project release
- (e.g. &DISTRO_NAME_NO_CAP;):
- <literallayout class='monospaced'>
- $ git checkout <replaceable>branch_name</replaceable>
- </literallayout>
- For an example on how to discover branch names and
- checkout on a branch, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- </orderedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
- If your hardware can be more closely leveraged to an
- existing BSP not within the <filename>meta-intel</filename>
- BSP layer, you can clone that BSP layer.</para>
-
- <para>The process is identical to the process used for the
- <filename>meta-intel</filename> layer except for the layer's
- name.
- For example, if you determine that your hardware most
- closely matches the <filename>meta-minnow</filename>,
- clone that layer:
- <literallayout class='monospaced'>
- $ git clone git://git.yoctoproject.org/meta-minnow
- Cloning into 'meta-minnow'...
- remote: Counting objects: 456, done.
- remote: Compressing objects: 100% (283/283), done.
- remote: Total 456 (delta 163), reused 384 (delta 91)
- Receiving objects: 100% (456/456), 96.74 KiB | 0 bytes/s, done.
- Resolving deltas: 100% (163/163), done.
+ remote: Counting objects: 15585, done.
+ remote: Compressing objects: 100% (5056/5056), done.
+ remote: Total 15585 (delta 9123), reused 15329 (delta 8867)
+ Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done.
+ Resolving deltas: 100% (9123/9123), done.
Checking connectivity... done.
</literallayout>
</para></listitem>
<listitem><para>
- <emphasis>Initialize the Build Environment:</emphasis>
- While in the root directory of the Source Directory (i.e.
- <filename>poky</filename>), run the
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
- environment setup script to define the OpenEmbedded
- build environment on your build host.
+ <emphasis>Check Out the Proper Branch:</emphasis>
+ The branch you check out for
+ <filename>meta-intel</filename> must match the same
+ branch you are using for the Yocto Project release
+ (e.g. &DISTRO_NAME_NO_CAP;):
<literallayout class='monospaced'>
- $ source &OE_INIT_FILE;
+ $ 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;'
</literallayout>
- Among other things, the script creates the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
- which is <filename>build</filename> in this case
- and is located in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- After the script runs, your current working directory
- is set to the <filename>build</filename> directory.
+ <note>
+ To see the available branch names in a cloned repository,
+ use the <filename>git branch -al</filename> command.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual for more information.
+ </note>
</para></listitem>
</orderedlist>
- </para>
- </section>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
+ If your hardware can be more closely leveraged to an
+ existing BSP not within the <filename>meta-intel</filename>
+ BSP layer, you can clone that BSP layer.</para>
- <section id="bsp-filelayout">
- <title>Example Filesystem Layout</title>
-
- <para>
- Defining a common BSP directory structure allows end-users to understand and
- become familiar with that structure.
- A common format also encourages standardization of software support of hardware.
- </para>
-
- <para>
- The proposed form does have elements that are specific to the
- OpenEmbedded build system.
- It is intended that this information can be
- used by other build systems besides the OpenEmbedded build system
- and that it will 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 captures all
- the hardware-specific details in one place in a standard format, which is
- useful for any person wishing to use the hardware platform regardless of
- the build system they are using.
- </para>
-
- <para>
- The BSP specification does not include a build system or other tools -
- it is concerned with the hardware-specific components only.
- At the end-distribution point, you can ship the BSP combined with a build system
- and other tools.
- However, it is important to maintain the distinction that these
- are separate components that happen to be combined in certain end products.
- </para>
-
- <para>
- Before looking at the common form for the file structure inside a BSP Layer,
- you should be aware that some requirements do exist in order for a BSP to
- be considered compliant with the Yocto Project.
- For that list of requirements, see the
- "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
- section.
- </para>
-
- <para>
- Below is the common form for the file structure inside a BSP Layer.
- While you can use this basic form for the standard, realize that the actual structures
- for specific BSPs could differ.
-
+ <para>The process is identical to the process used for the
+ <filename>meta-intel</filename> layer except for the layer's
+ name.
+ For example, if you determine that your hardware most
+ closely matches the <filename>meta-raspberrypi</filename>,
+ clone that layer:
<literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/
- meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
- meta-<replaceable>bsp_name</replaceable>/README
- meta-<replaceable>bsp_name</replaceable>/README.sources
- meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
- meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
- meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
- meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
- meta-<replaceable>bsp_name</replaceable>/recipes-core/*
- meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
- meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
+ $ git clone git://git.yoctoproject.org/meta-raspberrypi
+ Cloning into 'meta-raspberrypi'...
+ remote: Counting objects: 4743, done.
+ remote: Compressing objects: 100% (2185/2185), done.
+ remote: Total 4743 (delta 2447), reused 4496 (delta 2258)
+ Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done.
+ Resolving deltas: 100% (2447/2447), done.
+ Checking connectivity... done.
</literallayout>
- </para>
-
- <para>
- Below is an example of the Raspberry Pi BSP:
-
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initialize the Build Environment:</emphasis>
+ While in the root directory of the Source Directory (i.e.
+ <filename>poky</filename>), run the
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+ environment setup script to define the OpenEmbedded
+ build environment on your build host.
<literallayout class='monospaced'>
+ $ source &OE_INIT_FILE;
+ </literallayout>
+ Among other things, the script creates the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ which is <filename>build</filename> in this case
+ and is located in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ After the script runs, your current working directory
+ is set to the <filename>build</filename> directory.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id="bsp-filelayout">
+ <title>Example Filesystem Layout</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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
+ <ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ Before looking at the common form for the file structure
+ inside a BSP Layer, you should be aware that some
+ requirements do exist in order for a BSP layer to
+ be considered compliant with the Yocto Project.
+ For that list of requirements, see the
+ "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
+ section.
+ </para>
+
+ <para>
+ Below is the common form for the file structure
+ inside a BSP Layer.
+ While this basic form represents the standard,
+ realize that the actual file structures for specific
+ BSPs could differ.
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/
+ meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
+ meta-<replaceable>bsp_root_name</replaceable>/README
+ meta-<replaceable>bsp_root_name</replaceable>/README.sources
+ meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
+ meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
+ meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-core/*
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
+ </literallayout>
+ </para>
+
+ <para>
+ Below is an example of the Raspberry Pi BSP
+ layer that is available from the
+ <ulink url='&YOCTO_GIT_URL;'>Source Respositories</ulink>:
+ <literallayout class='monospaced'>
meta-raspberrypi/COPYING.MIT
- meta-raspberrypi/README
+ meta-raspberrypi/README.md
meta-raspberrypi/classes
- meta-raspberrypi/classes/linux-raspberrypi-base.bbclass
meta-raspberrypi/classes/sdcard_image-rpi.bbclass
meta-raspberrypi/conf/
meta-raspberrypi/conf/layer.conf
meta-raspberrypi/conf/machine/
+ meta-raspberrypi/conf/machine/raspberrypi-cm.conf
+ meta-raspberrypi/conf/machine/raspberrypi-cm3.conf
meta-raspberrypi/conf/machine/raspberrypi.conf
+ meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf
meta-raspberrypi/conf/machine/raspberrypi0.conf
meta-raspberrypi/conf/machine/raspberrypi2.conf
+ meta-raspberrypi/conf/machine/raspberrypi3-64.conf
meta-raspberrypi/conf/machine/raspberrypi3.conf
meta-raspberrypi/conf/machine/include
meta-raspberrypi/conf/machine/include/rpi-base.inc
meta-raspberrypi/conf/machine/include/rpi-default-providers.inc
meta-raspberrypi/conf/machine/include/rpi-default-settings.inc
meta-raspberrypi/conf/machine/include/rpi-default-versions.inc
- meta-raspberrypi/conf/machine/include/rpi-tune-arm1176jzf-s.inc
+ meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc
+ meta-raspberrypi/docs
+ meta-raspberrypi/docs/Makefile
+ meta-raspberrypi/docs/conf.py
+ meta-raspberrypi/docs/contributing.md
+ meta-raspberrypi/docs/extra-apps.md
+ meta-raspberrypi/docs/extra-build-config.md
+ meta-raspberrypi/docs/index.rst
+ meta-raspberrypi/docs/layer-contents.md
+ meta-raspberrypi/docs/readme.md
meta-raspberrypi/files
meta-raspberrypi/files/custom-licenses
meta-raspberrypi/files/custom-licenses/Broadcom
@@ -378,12 +435,26 @@
meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb
meta-raspberrypi/recipes-bsp/common
meta-raspberrypi/recipes-bsp/common/firmware.inc
- meta-raspberrypi/recipes-bsp/formfactor_00.bbappend
- meta-raspberrypi/recipes-bsp/formfactor/raspberrypi/machconfig
- meta-raspberrypi/recipes-bsp/rpi-mkimage_git.bb
- meta-raspberrypi/recipes-bsp/rpi-mkimage/License
- meta-raspberrypi/recipes-bsp/rpi-mkimage/open-files-relative-to-script.patch
- meta-raspberrypi/recipes-bsp/u-boot/u-boot-rpi_git.bb
+ meta-raspberrypi/recipes-bsp/formfactor
+ meta-raspberrypi/recipes-bsp/formfactor/formfactor
+ meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi
+ meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig
+ meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend
+ meta-raspberrypi/recipes-bsp/rpi-u-boot-src
+ meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files
+ meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in
+ meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb
+ meta-raspberrypi/recipes-bsp/u-boot
+ meta-raspberrypi/recipes-bsp/u-boot/u-boot
+ meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch
+ meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend
+ meta-raspberrypi/recipes-connectivity
+ meta-raspberrypi/recipes-connectivity/bluez5
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend
meta-raspberrypi/recipes-core
meta-raspberrypi/recipes-core/images
meta-raspberrypi/recipes-core/images/rpi-basic-image.bb
@@ -393,37 +464,41 @@
meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb
meta-raspberrypi/recipes-core/psplash
meta-raspberrypi/recipes-core/psplash/files
- meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h
+ meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
+ meta-raspberrypi/recipes-core/udev
+ meta-raspberrypi/recipes-core/udev/udev-rules-rpi
+ meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules
+ meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb
meta-raspberrypi/recipes-devtools
meta-raspberrypi/recipes-devtools/bcm2835
- meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.46.bb
+ meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb
meta-raspberrypi/recipes-devtools/pi-blaster
meta-raspberrypi/recipes-devtools/pi-blaster/files
- meta-raspberrypi/recipes-devtools/pi-blaster/*.patch
- meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster.inc
+ meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch
meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb
meta-raspberrypi/recipes-devtools/python
meta-raspberrypi/recipes-devtools/python/python-rtimu
meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch
meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb
- meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.1.0.bb
+ meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb
meta-raspberrypi/recipes-devtools/python/rpi-gpio
meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch
- meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.1.bb
+ meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb
meta-raspberrypi/recipes-devtools/python/rpio
meta-raspberrypi/recipes-devtools/python/rpio/*.patch
meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb
meta-raspberrypi/recipes-devtools/wiringPi
meta-raspberrypi/recipes-devtools/wiringPi/files
meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch
- meta-raspberrypi/recipes-devtools/wiringPi/wiringpi
- meta-raspberrypi/recipes-devtools/wiringPi/wiringpi/*.patch
meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb
meta-raspberrypi/recipes-graphics
meta-raspberrypi/recipes-graphics/eglinfo
meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend
meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend
+ meta-raspberrypi/recipes-graphics/mesa
+ meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend
+ meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend
meta-raspberrypi/recipes-graphics/userland
meta-raspberrypi/recipes-graphics/userland/userland
meta-raspberrypi/recipes-graphics/userland/userland/*.patch
@@ -437,194 +512,204 @@
meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc
meta-raspberrypi/recipes-graphics/wayland
meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend
- meta-raspberrypi/recipes-graphics/weston
- meta-raspberrypi/recipes-graphics/weston/weston_%.bbappend
meta-raspberrypi/recipes-graphics/xorg-xserver
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf
- meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-pitft.conf
+ meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf
+ meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
+ meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend
meta-raspberrypi/recipes-kernel
meta-raspberrypi/recipes-kernel/linux-firmware
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/LICENSE.broadcom_brcm80211
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.bin
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.txt
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_git.bbappend
+ meta-raspberrypi/recipes-kernel/linux-firmware/files
+ meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin
+ meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt
+ meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend
meta-raspberrypi/recipes-kernel/linux
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14/*.patch
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18/*.patch
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1/*.patch
+ meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb
meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi/defconfig
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.14.bb
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.18.bb
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.1.bb
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.4.bb
- meta-raspberrypi/recipes-kernel/linux/linux.inc
+ meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb
+ meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb
meta-raspberrypi/recipes-multimedia
meta-raspberrypi/recipes-multimedia/gstreamer
meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx
meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch
meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend
meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend
+ meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12
+ meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch
meta-raspberrypi/recipes-multimedia/omxplayer
meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer
meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch
meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb
- meta-raspberrypi/scripts
- meta-raspberrypi/scripts/lib
- meta-raspberrypi/scripts/lib/image
- meta-raspberrypi/scripts/lib/image/canned-wks
- meta-raspberrypi/scripts/lib/image/canned-wks/sdimage-raspberrypi.wks
- </literallayout>
- </para>
+ meta-raspberrypi/recipes-multimedia/x264
+ meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend
+ meta-raspberrypi/wic
+ meta-raspberrypi/wic/sdimage-raspberrypi.wks
+ </literallayout>
+ </para>
- <para>
- The following sections describe each part of the proposed BSP format.
- </para>
+ <para>
+ The following sections describe each part of the proposed
+ BSP format.
+ </para>
- <section id="bsp-filelayout-license">
- <title>License Files</title>
+ <section id="bsp-filelayout-license">
+ <title>License Files</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
+ </literallayout>
+ </para>
- <para>
- These optional files satisfy licensing requirements for the BSP.
- The type or types of files here can vary depending on the licensing requirements.
- For example, in the Raspberry Pi BSP all licensing requirements are handled with the
- <filename>COPYING.MIT</filename> file.
- </para>
+ <para>
+ These optional files satisfy licensing requirements
+ for the BSP.
+ The type or types of files here can vary depending
+ on the licensing requirements.
+ For example, in the Raspberry Pi BSP all licensing
+ requirements are handled with the
+ <filename>COPYING.MIT</filename> file.
+ </para>
- <para>
- Licensing files can be MIT, BSD, GPLv*, and so forth.
- These files are recommended for the BSP but are optional and totally up to the BSP developer.
- </para>
- </section>
+ <para>
+ Licensing files can be MIT, BSD, GPLv*, and so forth.
+ These files are recommended for the BSP but are
+ optional and totally up to the BSP developer.
+ For information on how to maintain license
+ compliance, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ </para>
+ </section>
- <section id="bsp-filelayout-readme">
- <title>README File</title>
+ <section id="bsp-filelayout-readme">
+ <title>README File</title>
- <para>
- You can find this file in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/README
- </literallayout>
- </para>
+ <para>
+ You can find this file in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/README
+ </literallayout>
+ </para>
- <para>
- This file provides information on how to boot the live images that are optionally
- included in the <filename>binary/</filename> directory.
- The <filename>README</filename> file also provides special information needed for
- building the image.
- </para>
+ <para>
+ This file provides information on how to boot the live
+ images that are optionally included in the
+ <filename>binary/</filename> directory.
+ The <filename>README</filename> file also provides
+ information needed for building the image.
+ </para>
- <para>
- At a minimum, the <filename>README</filename> 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.
- </para>
- </section>
+ <para>
+ At a minimum, the <filename>README</filename> 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.
+ </para>
+ </section>
- <section id="bsp-filelayout-readme-sources">
- <title>README.sources File</title>
+ <section id="bsp-filelayout-readme-sources">
+ <title>README.sources File</title>
- <para>
- You can find this file in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/README.sources
- </literallayout>
- </para>
+ <para>
+ You can find this file in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/README.sources
+ </literallayout>
+ </para>
- <para>
- This file provides information on where to locate the BSP
- source files used to build the images (if any) that reside in
- <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
- Images in the <filename>binary</filename> would be images
- released with the BSP.
- The information in the <filename>README.sources</filename>
- file also helps you find the
- <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
- used to generate the images that ship with the BSP.
- <note>
- If the BSP's <filename>binary</filename> directory is
- missing or the directory has no images, an existing
- <filename>README.sources</filename> file is
- meaningless.
- </note>
- </para>
- </section>
+ <para>
+ This file provides information on where to locate the BSP
+ source files used to build the images (if any) that
+ reside in
+ <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>.
+ Images in the <filename>binary</filename> would be images
+ released with the BSP.
+ The information in the <filename>README.sources</filename>
+ file also helps you find the
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+ used to generate the images that ship with the BSP.
+ <note>
+ If the BSP's <filename>binary</filename> directory is
+ missing or the directory has no images, an existing
+ <filename>README.sources</filename> file is
+ meaningless and usually does not exist.
+ </note>
+ </para>
+ </section>
- <section id="bsp-filelayout-binary">
- <title>Pre-built User Binaries</title>
+ <section id="bsp-filelayout-binary">
+ <title>Pre-built User Binaries</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
+ </literallayout>
+ </para>
- <para>
- 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
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
- You can use these kernels and images to get a system running
- and quickly get started on development tasks.
- </para>
+ <para>
+ 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
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
+ website.
+ You can use these kernels and images to get a system
+ running and quickly get started on development tasks.
+ </para>
- <para>
- The exact types of binaries present are highly
- hardware-dependent.
- The <filename>README</filename> file should be present in the
- BSP Layer and it will explain how to use the images with the
- target hardware.
- Additionally, the <filename>README.sources</filename> file
- should be present to locate the sources used to build the
- images and provide information on the Metadata.
- </para>
- </section>
+ <para>
+ The exact types of binaries present are highly
+ hardware-dependent.
+ The
+ <link linkend='bsp-filelayout-readme'><filename>README</filename></link>
+ file should be present in the BSP Layer and it
+ explains how to use the images with the target hardware.
+ Additionally, the
+ <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link>
+ file should be present to locate the sources used to
+ build the images and provide information on the
+ Metadata.
+ </para>
+ </section>
- <section id='bsp-filelayout-layer'>
- <title>Layer Configuration File</title>
+ <section id='bsp-filelayout-layer'>
+ <title>Layer Configuration File</title>
- <para>
- You can find this file in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
- </literallayout>
- </para>
+ <para>
+ You can find this file in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
+ </literallayout>
+ </para>
- <para>
- The <filename>conf/layer.conf</filename> 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 "<replaceable>bsp</replaceable>" and
- "<replaceable>_bsp</replaceable>" with the actual name
- of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template).
- </para>
+ <para>
+ The <filename>conf/layer.conf</filename> 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
+ <replaceable>bsp</replaceable> with the actual
+ name of the BSP (i.e.
+ <replaceable>bsp_root_name</replaceable> from the example
+ template).
+ </para>
- <para>
- <literallayout class='monospaced'>
+ <para>
+ <literallayout class='monospaced'>
# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"
@@ -637,13 +722,14 @@
BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- To illustrate the string substitutions, here are the corresponding statements
- from the Raspberry Pi <filename>conf/layer.conf</filename> file:
- <literallayout class='monospaced'>
+ <para>
+ To illustrate the string substitutions, here are
+ the corresponding statements from the Raspberry
+ Pi <filename>conf/layer.conf</filename> file:
+ <literallayout class='monospaced'>
# We have a conf and classes directory, append to BBPATH
BBPATH .= ":${LAYERDIR}"
@@ -657,1265 +743,1527 @@
# Additional license directories.
LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
- </literallayout>
- </para>
+ .
+ .
+ .
+ </literallayout>
+ </para>
- <para>
- This file simply makes
- <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
- aware of the recipes and configuration directories.
- The file must exist so that the OpenEmbedded build system can recognize the BSP.
- </para>
- </section>
+ <para>
+ This file simply makes
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ aware of the recipes and configuration directories.
+ The file must exist so that the OpenEmbedded build system
+ can recognize the BSP.
+ </para>
+ </section>
- <section id="bsp-filelayout-machine">
- <title>Hardware Configuration Options</title>
+ <section id="bsp-filelayout-machine">
+ <title>Hardware Configuration Options</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
+ </literallayout>
+ </para>
- <para>
- The machine files bind together all the information contained elsewhere
- in the BSP into a format that the build system can understand.
- If the BSP supports multiple machines, multiple machine configuration files
- can be present.
- These filenames correspond to the values to which users have set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
- </para>
+ <para>
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
+ </para>
- <para>
- These files define things such as the kernel package to use
- (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
- of virtual/kernel), the hardware drivers to
- include in different types of images, any special software components
- that are needed, any bootloader information, and also any special image
- format requirements.
- </para>
+ <para>
+ These files define things such as the kernel package
+ to use
+ (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+ of
+ <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>),
+ the hardware drivers to include in different types
+ of images, any special software components that are
+ needed, any bootloader information, and also any
+ special image format requirements.
+ </para>
- <para>
- Each BSP Layer requires at least one machine file.
- However, you can supply more than one file.
- </para>
+ <para>
+ 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.
+ </para>
- <para>
- 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.
- </para>
+ <para>
+ Tuning files are found in the
+ <filename>meta/conf/machine/include</filename>
+ directory within the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ For example, many <filename>tune-*</filename> files
+ (e.g. <filename>tune-arm1136jf-s.inc</filename>,
+ <filename>tun-1586-nlp.inc</filename>, and so forth)
+ reside in the
+ <filename>poky/meta/conf/machine/include</filename>
+ directory.
+ </para>
- <para>
- Tuning files are found in the <filename>meta/conf/machine/include</filename>
- directory within the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- For example, the <filename>ia32-base.inc</filename> file resides in the
- <filename>meta/conf/machine/include</filename> directory.
- </para>
+ <para>
+ To use an include file, you simply include them in the
+ machine configuration file.
+ For example, the Raspberry Pi BSP
+ <filename>raspberrypi3.conf</filename> contains the
+ following statement:
+ <literallayout class='monospaced'>
+ include conf/machine/include/rpi-base.inc
+ </literallayout>
+ </para>
+ </section>
- <para>
- To use an include file, you simply include them in the
- machine configuration file.
- For example, the Raspberry Pi BSP
- <filename>raspberrypi3.conf</filename> contains the
- following statement:
- <literallayout class='monospaced'>
- include conf/machine/raspberrypi2.conf
- </literallayout>
- </para>
- </section>
+ <section id='bsp-filelayout-misc-recipes'>
+ <title>Miscellaneous BSP-Specific Recipe Files</title>
- <section id='bsp-filelayout-misc-recipes'>
- <title>Miscellaneous BSP-Specific Recipe Files</title>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
+ </literallayout>
+ </para>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
- </literallayout>
- </para>
-
- <para>
- This optional directory contains miscellaneous recipe files for
- the BSP.
- Most notably would be the formfactor files.
- For example, in the Raspberry Pi BSP there is the
- <filename>formfactor_0.0.bbappend</filename> file, which is an
- append file used to augment the recipe that starts the build.
- Furthermore, there are machine-specific settings used during
- the build that are defined by the
- <filename>machconfig</filename> file further down in the
- directory.
- Here is the <filename>machconfig</filename>
- file for the Raspberry Pi BSP:
- <literallayout class='monospaced'>
+ <para>
+ 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
+ <filename>formfactor_0.0.bbappend</filename> file,
+ which is an append file used to augment the recipe
+ that starts the build.
+ Furthermore, there are machine-specific settings used
+ during the build that are defined by the
+ <filename>machconfig</filename> file further down in
+ the directory.
+ Here is the <filename>machconfig</filename> file for
+ the Raspberry Pi BSP:
+ <literallayout class='monospaced'>
HAVE_TOUCHSCREEN=0
HAVE_KEYBOARD=1
DISPLAY_CAN_ROTATE=0
DISPLAY_ORIENTATION=0
DISPLAY_DPI=133
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <note><para>
- 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
- <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
- which is found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- </para></note>
- </section>
+ <note><para>
+ 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
+ <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
+ which is found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ </para></note>
+ </section>
- <section id='bsp-filelayout-recipes-graphics'>
- <title>Display Support Files</title>
+ <section id='bsp-filelayout-recipes-graphics'>
+ <title>Display Support Files</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
+ </literallayout>
+ </para>
- <para>
- This optional directory contains recipes for the BSP if it has
- special requirements for graphics support.
- All files that are needed for the BSP to support a display are
- kept here.
- </para>
- </section>
+ <para>
+ This optional directory contains recipes for the
+ BSP if it has special requirements for graphics
+ support.
+ All files that are needed for the BSP to support
+ a display are kept here.
+ </para>
+ </section>
- <section id='bsp-filelayout-kernel'>
- <title>Linux Kernel Configuration</title>
+ <section id='bsp-filelayout-kernel'>
+ <title>Linux Kernel Configuration</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb
+ </literallayout>
+ </para>
- <para>
- These files append machine-specific changes to the main
- kernel recipe you are using.
- </para>
+ <para>
+ Append files (<filename>*.bbappend</filename>) modify
+ the main kernel recipe being used to build the image.
+ The <filename>*.bb</filename> files would be a
+ developer-supplied kernel recipe.
+ This area of the BSP hierarchy can contain both these
+ types of files, although in practice, it is likely that
+ you would have one or the other.
+ </para>
- <para>
- For your BSP, you typically want to use an existing Yocto
- Project kernel recipe found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- at <filename>meta/recipes-kernel/linux</filename>.
- 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
- <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
- </para>
+ <para>
+ For your BSP, you typically want to use an existing Yocto
+ Project kernel recipe found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ at <filename>meta/recipes-kernel/linux</filename>.
+ 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
+ <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory).
+ </para>
- <para>
- Suppose you are using the <filename>linux-yocto_4.4.bb</filename>
- recipe to build the kernel.
- In other words, you have selected the kernel in your
- <replaceable>bsp_name</replaceable><filename>.conf</filename>
- file by adding
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
- statements as follows:
- <literallayout class='monospaced'>
+ <para>
+ Suppose you are using the
+ <filename>linux-yocto_4.4.bb</filename> recipe to
+ build the kernel.
+ In other words, you have selected the kernel in your
+ <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+ file by adding
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
+ statements as follows:
+ <literallayout class='monospaced'>
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
PREFERRED_VERSION_linux-yocto ?= "4.4%"
- </literallayout>
- <note>
- When the preferred provider is assumed by default, the
- <filename>PREFERRED_PROVIDER</filename>
- statement does not appear in the
- <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
- </note>
- You would use the <filename>linux-yocto_4.4.bbappend</filename>
- file to append specific BSP settings to the kernel, thus
- configuring the kernel for your particular BSP.
- </para>
+ </literallayout>
+ <note>
+ When the preferred provider is assumed by
+ default, the
+ <filename>PREFERRED_PROVIDER</filename>
+ statement does not appear in the
+ <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file.
+ </note>
+ You would use the
+ <filename>linux-yocto_4.4.bbappend</filename>
+ file to append specific BSP settings to the kernel,
+ thus configuring the kernel for your particular BSP.
+ </para>
- <para>
- You can find more information on what your append file
- should contain in the
- "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
- section in the Yocto Project Linux Kernel Development
- Manual.
- </para>
- </section>
- </section>
+ <para>
+ You can find more information on what your append file
+ should contain in the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file'>Creating the Append File</ulink>"
+ section in the Yocto Project Linux Kernel Development
+ Manual.
+ </para>
- <section id='developing-a-board-support-package-bsp'>
- <title>Developing a Board Support Package (BSP)</title>
+ <para>
+ 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
+ <filename>recipes-kernel/linux</filename> directory
+ you see the following:
+ <literallayout class='monospaced'>
+ linux-raspberrypi-dev.bb
+ linux-raspberrypi.inc
+ linux-raspberrypi_4.14.bb
+ linux-raspberrypi_4.9.bb
+ </literallayout>
+ The directory contains three kernel recipes and a
+ common include file.
+ </para>
+ </section>
+</section>
- <para>
- This section contains the high-level procedure you can follow
- to create a BSP using the Yocto Project's
- <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
- Although not required for BSP creation, the
- <filename>meta-intel</filename> repository, which contains
- many BSPs supported by the Yocto Project, is part of the
- example.
- </para>
+<section id='developing-a-board-support-package-bsp'>
+ <title>Developing a Board Support Package (BSP)</title>
- <para>
- For an example that shows how to create a new layer using
- the tools, see the
- "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
- section.
- </para>
+ <para>
+ This section contains the high-level procedure you can
+ follow to create a BSP.
+ Although not required for BSP creation, the
+ <filename>meta-intel</filename> repository, which
+ contains many BSPs supported by the Yocto Project,
+ is part of the example.
+ </para>
- <para>
- The following illustration and list summarize the BSP
- creation general workflow.
- </para>
+ <para>
+ For an example that shows how to create a new
+ layer using the tools, see the
+ "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
+ section.
+ </para>
- <para>
- <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
- </para>
+ <para>
+ The following illustration and list summarize the BSP
+ creation general workflow.
+ </para>
- <para>
- <orderedlist>
- <listitem><para>
- <emphasis>Set up Your Host Development System to Support
- Development Using the Yocto Project</emphasis>:
- See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
- section in the Yocto Project Quick Start for options on how
- to get a build host ready to use the Yocto Project.
- </para></listitem>
- <listitem><para>
- <emphasis>Establish the <filename>meta-intel</filename>
- Repository on Your System:</emphasis>
- Having local copies of these supported BSP layers on
- your system gives you access to layers you might be able
- to build on or modify to create your BSP.
- For information on how to get these files, see the
- "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
- section.
- </para></listitem>
- <listitem><para>
- <emphasis>Create Your Own BSP Layer Using the
- <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></link>
- script:</emphasis>
- 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
- <filename>yocto-bsp</filename> script.
- For information about that script, see the
- "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
- section.</para>
+ <para>
+ <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
+ </para>
- <para>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
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section in the Yocto Project Development Tasks Manual.
- For more information on BSP layers, see the
- "<link linkend='bsp-layers'>BSP Layers</link>"
- section.
- <note><title>Notes</title>
- <para>Five BSPs exist that are part of the Yocto
- Project release:
- <filename>beaglebone</filename> (ARM),
- <filename>mpc8315e</filename> (PowerPC),
- and <filename>edgerouter</filename> (MIPS).
- The recipes and configurations for these five BSPs
- are located and dispersed within the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- </para>
+ <para>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set up Your Host Development System
+ to Support Development Using the Yocto
+ Project</emphasis>:
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual for options on how to get a system ready
+ to use the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Establish the
+ <filename>meta-intel</filename>
+ Repository on Your System:</emphasis>
+ 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
+ "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create Your Own BSP Layer Using the
+ <filename>bitbake-layers</filename>
+ Script:</emphasis>
+ 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
+ <filename>bitbake-layers</filename> script.
+ For information about that script, see the
+ "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
+ section.</para>
- <para>Three core Intel BSPs exist as part of the Yocto
- Project release in the
+ <para>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
+ "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+ section in the Yocto Project Overview and Concepts
+ Manual.
+ You can also reference the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ For more information on BSP layers, see the
+ "<link linkend='bsp-layers'>BSP Layers</link>"
+ section.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Five hardware reference BSPs exist
+ that are part of the Yocto Project release
+ and are located in the
+ <filename>poky/meta-yocto-bsp</filename> BSP
+ layer:
+ <itemizedlist>
+ <listitem><para>
+ Texas Instruments Beaglebone
+ (<filename>beaglebone-yocto</filename>)
+ </para></listitem>
+ <listitem><para>
+ Freescale MPC8315E-RDB
+ (<filename>mpc8315e-rdb</filename>)
+ </para></listitem>
+ <listitem><para>
+ Ubiquiti Networks EdgeRouter Lite
+ (<filename>edgerouter</filename>)
+ </para></listitem>
+ <listitem><para>
+ Two general IA platforms
+ (<filename>genericx86</filename> and
+ <filename>genericx86-64</filename>)
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ Three core Intel BSPs exist as part of
+ the Yocto Project release in the
<filename>meta-intel</filename> layer:
<itemizedlist>
<listitem><para>
<filename>intel-core2-32</filename>,
- which is a BSP optimized for the Core2 family of CPUs
- as well as all CPUs prior to the Silvermont core.
+ which is a BSP optimized for the Core2
+ family of CPUs as well as all CPUs
+ prior to the Silvermont core.
</para></listitem>
<listitem><para>
<filename>intel-corei7-64</filename>,
- 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.
+ 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.
</para></listitem>
<listitem><para>
<filename>intel-quark</filename>,
- which is a BSP optimized for the Intel Galileo
- gen1 & gen2 development boards.
+ which is a BSP optimized for the
+ Intel Galileo gen1 & gen2
+ development boards.
</para></listitem>
- </itemizedlist></para>
- </note></para>
-
- <para>When you set up a layer for a new BSP, you should
- follow a standard layout.
- This layout is described in the
- "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
- section.
- In the standard layout, you will notice a suggested
- structure for recipes and configuration information.
- You can see the standard layout for a BSP by examining
- any supported BSP found in the
- <filename>meta-intel</filename> layer inside the Source
- Directory.
- </para></listitem>
- <listitem><para>
- <emphasis>Make Configuration Changes to Your New BSP
- Layer:</emphasis>
- The standard BSP layer structure organizes the files
- you need to edit in <filename>conf</filename> and
- several <filename>recipes-*</filename>
- directories within the BSP layer.
- Configuration changes identify where your new layer
- is on the local system and identify which kernel you
- are going to use.
- When you run the <filename>yocto-bsp</filename> script,
- you are able to interactively configure many things for
- the BSP (e.g. keyboard, touchscreen, and so forth).
- </para></listitem>
- <listitem><para>
- <emphasis>Make Recipe Changes to Your New BSP
- Layer:</emphasis>
- Recipe changes include altering recipes
- (<filename>.bb</filename> files), removing recipes you
- do not use, and adding new recipes or append files
- (<filename>.bbappend</filename>) that you need to
- support your hardware.
- </para></listitem>
- <listitem><para>
- <emphasis>Prepare for the Build:</emphasis>
- 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. <filename>oe-init-build-env</filename>)
- and you need to be sure two key configuration
- files are configured appropriately: the
- <filename>conf/local.conf</filename> and the
- <filename>conf/bblayers.conf</filename> file.
- You must make the OpenEmbedded build system aware
- of your new layer.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
- section in the Yocto Project Development Tasks Manual
- for information on how to let the build system
- know about your new layer.</para>
-
- <para>The entire process for building an image is
- overviewed in the section
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section
- of the Yocto Project Quick Start.
- You might want to reference this information.
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Image:</emphasis>
- 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
- <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
- </para>
-
- <para>The build process supports several types of
- images to satisfy different needs.
- See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
- chapter in the Yocto Project Reference Manual for
- information on supported images.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='requirements-and-recommendations-for-released-bsps'>
- <title>Requirements and Recommendations for Released BSPs</title>
-
- <para>
- Certain requirements exist for a released BSP to be considered
- compliant with the Yocto Project.
- Additionally, recommendations also exist.
- This section describes the requirements and recommendations for
- released BSPs.
- </para>
-
- <section id='released-bsp-requirements'>
- <title>Released BSP Requirements</title>
-
- <para>
- Before looking at BSP requirements, you should consider the following:
- <itemizedlist>
- <listitem><para>The requirements here assume the 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
- "<link linkend='bsp-layers'>BSP Layers</link>" and the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding
- and Creating Layers"</ulink> in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>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
- "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
- wiki page.
- </para></listitem>
- <listitem><para>The requirements for the BSP as it is made available to a developer
- are completely independent of the released form of the BSP.
- For example, the BSP Metadata can be contained within a Git repository
- and could have a directory structure completely different from what appears
- in the officially released BSP layer.
- </para></listitem>
- <listitem><para>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.
+ </itemizedlist>
</para></listitem>
</itemizedlist>
+ </note></para>
+
+ <para>When you set up a layer for a new BSP,
+ you should follow a standard layout.
+ This layout is described in the
+ "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
+ 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
+ <filename>meta-intel</filename> layer inside
+ the Source Directory.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Configuration Changes to Your New
+ BSP Layer:</emphasis>
+ The standard BSP layer structure organizes the
+ files you need to edit in
+ <filename>conf</filename> and several
+ <filename>recipes-*</filename> 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
+ <filename>bitbake-layers</filename> script,
+ you are able to interactively configure many
+ things for the BSP (e.g. keyboard, touchscreen,
+ and so forth).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Recipe Changes to Your New BSP
+ Layer:</emphasis>
+ Recipe changes include altering recipes
+ (<filename>*.bb</filename> files), removing
+ recipes you do not use, and adding new recipes
+ or append files (<filename>.bbappend</filename>)
+ that support your hardware.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Prepare for the Build:</emphasis>
+ 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. <filename>oe-init-build-env</filename>)
+ and you need to be sure two key configuration
+ files are configured appropriately: the
+ <filename>conf/local.conf</filename> and the
+ <filename>conf/bblayers.conf</filename> file.
+ You must make the OpenEmbedded build system aware
+ of your new layer.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
+ section in the Yocto Project Development Tasks Manual
+ for information on how to let the build system
+ know about your new layer.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Image:</emphasis>
+ 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
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
</para>
- <para>
- Following are the requirements for a released BSP that conform to the
- Yocto Project:
+ <para>The build process supports several types of
+ images to satisfy different needs.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+ chapter in the Yocto Project Reference Manual for
+ information on supported images.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='requirements-and-recommendations-for-released-bsps'>
+ <title>Requirements and Recommendations for Released BSPs</title>
+
+ <para>
+ Certain requirements exist for a released BSP to be
+ considered compliant with the Yocto Project.
+ Additionally, recommendations also exist.
+ This section describes the requirements and
+ recommendations for released BSPs.
+ </para>
+
+ <section id='released-bsp-requirements'>
+ <title>Released BSP Requirements</title>
+
+ <para>
+ Before looking at BSP requirements, you should consider
+ the following:
+ <itemizedlist>
+ <listitem><para>
+ The requirements here assume the 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
+ "<link linkend='bsp-layers'>BSP Layers</link>"
+ section in this manual and the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ </para></listitem>
+ <listitem><para>
+ 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
+ "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
+ wiki page.
+ </para></listitem>
+ <listitem><para>
+ The requirements for the BSP as it is made
+ available to a developer are completely
+ independent of the released form of the BSP.
+ For example, the BSP Metadata can be contained
+ within a Git repository and could have a directory
+ structure completely different from what appears
+ in the officially released BSP layer.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Following are the requirements for a released BSP
+ that conform to the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Layer Name:</emphasis>
+ The BSP must have a layer name that follows
+ the Yocto Project standards.
+ For information on BSP layer names, see the
+ "<link linkend='bsp-layers'>BSP Layers</link>" section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>File System Layout:</emphasis>
+ When possible, use the same directory names
+ in your BSP layer as listed in the
+ <filename>recipes.txt</filename> file, which
+ is found in <filename>poky/meta</filename>
+ directory of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ or in the OpenEmbedded-Core Layer
+ (<filename>openembedded-core</filename>) at
+ <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
+ </para>
+
+ <para>You should place recipes
+ (<filename>*.bb</filename> files) and recipe
+ modifications (<filename>*.bbappend</filename>
+ files) into <filename>recipes-*</filename>
+ subdirectories by functional area as outlined
+ in <filename>recipes.txt</filename>.
+ If you cannot find a category in
+ <filename>recipes.txt</filename> to fit a
+ particular recipe, you can make up your own
+ <filename>recipes-*</filename> subdirectory.
+ </para>
+
+ <para>Within any particular
+ <filename>recipes-*</filename> category, the
+ layout should match what is found in the
+ OpenEmbedded-Core Git repository
+ (<filename>openembedded-core</filename>)
+ or the Source Directory (<filename>poky</filename>).
+ In other words, make sure you place related
+ files in appropriately related
+ <filename>recipes-*</filename> subdirectories
+ specific to the recipe's function, or within
+ a subdirectory containing a set of closely-related
+ recipes.
+ The recipes themselves should follow the general
+ guidelines for recipes used in the Yocto Project
+ found in the
+ "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
+ </para></listitem>
+ <listitem><para>
+ <emphasis>License File:</emphasis>
+ You must include a license file in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ 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
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
+ file for the Raspberry Pi BSP in the
+ <filename>meta-raspberrypi</filename> BSP layer
+ as an example.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>README File:</emphasis>
+ You must include a <filename>README</filename>
+ file in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ See the
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md'><filename>README.md</filename></ulink>
+ file for the Raspberry Pi BSP in the
+ <filename>meta-raspberrypi</filename> BSP layer
+ as an example.</para>
+
+ <para>At a minimum, the <filename>README</filename>
+ file should contain the following:
<itemizedlist>
- <listitem><para><emphasis>Layer Name:</emphasis>
- The BSP must have a layer name that follows the Yocto
- Project standards.
- For information on BSP layer names, see the
- "<link linkend='bsp-layers'>BSP Layers</link>" section.
+ <listitem><para>
+ A brief description about the hardware the BSP
+ targets.
</para></listitem>
- <listitem><para><emphasis>File System Layout:</emphasis>
- When possible, use the same directory names in your
- BSP layer as listed in the <filename>recipes.txt</filename> file.
- In particular, you should place recipes
- (<filename>.bb</filename> files) and recipe
- modifications (<filename>.bbappend</filename> files) into
- <filename>recipes-*</filename> subdirectories by functional area
- as outlined in <filename>recipes.txt</filename>.
- If you cannot find a category in <filename>recipes.txt</filename>
- to fit a particular recipe, you can make up your own
- <filename>recipes-*</filename> subdirectory.
- You can find <filename>recipes.txt</filename> in the
- <filename>meta</filename> directory of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
- or in the OpenEmbedded Core Layer
- (<filename>openembedded-core</filename>) found at
- <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
- </para>
- <para>Within any particular <filename>recipes-*</filename> category, the layout
- should match what is found in the OpenEmbedded Core
- Git repository (<filename>openembedded-core</filename>)
- or the Source Directory (<filename>poky</filename>).
- In other words, make sure you place related files in appropriately
- related <filename>recipes-*</filename> subdirectories specific to the
- recipe's function, or within a subdirectory containing a set of closely-related
- recipes.
- The recipes themselves should follow the general guidelines
- for recipes used in the Yocto Project found in the
- "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
+ <listitem><para>
+ 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.
</para></listitem>
- <listitem><para><emphasis>License File:</emphasis>
- You must include a license file in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- This license covers the BSP Metadata as a whole.
- You must specify which license to use since there is no
- default license if one is not specified.
- See the
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
- file for the Raspberry Pi BSP in the
- <filename>meta-raspberrypi</filename> BSP layer as an example.
+ <listitem><para>
+ Any required special licensing information.
+ For example, this information includes
+ information on special variables needed
+ to satisfy a EULA, or instructions on
+ information needed to build or distribute
+ binaries built from the BSP Metadata.
</para></listitem>
- <listitem><para><emphasis>README File:</emphasis>
- You must include a <filename>README</filename> file in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- See the
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
- file for the Raspberry Pi BSP in the <filename>meta-raspberrypi</filename> BSP layer
- as an example.</para>
- <para>At a minimum, the <filename>README</filename> file should
- contain the following:
- <itemizedlist>
- <listitem><para>A brief description about the hardware the BSP
- targets.</para></listitem>
- <listitem><para>A list of all the dependencies
- on which a BSP layer depends.
- These dependencies are typically a list of required layers needed
- to build the BSP.
- However, the dependencies should also contain information regarding
- any other dependencies the BSP might have.</para></listitem>
- <listitem><para>Any required special licensing information.
- For example, this information includes information on
- special variables needed to satisfy a EULA,
- or instructions on information needed to build or distribute
- binaries built from the BSP Metadata.</para></listitem>
- <listitem><para>The name and contact information for the
- BSP layer maintainer.
- This is the person to whom patches and questions should
- be sent.
- For information on how to find the right person, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>Instructions on how to build the BSP using the BSP
- layer.</para></listitem>
- <listitem><para>Instructions on how to boot the BSP build from
- the BSP layer.</para></listitem>
- <listitem><para>Instructions on how to boot the binary images
- contained in the <filename>binary</filename> directory,
- if present.</para></listitem>
- <listitem><para>Information on any known bugs or issues that users
- should know about when either building or booting the BSP
- binaries.</para></listitem>
- </itemizedlist></para></listitem>
- <listitem><para><emphasis>README.sources File:</emphasis>
- You must include a <filename>README.sources</filename> in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- This file specifies exactly where you can find the sources used to
- generate the binary images contained in the
- <filename>binary</filename> directory, if present.
+ <listitem><para>
+ 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
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
+ section in the Yocto Project Development
+ Tasks Manual.
</para></listitem>
- <listitem><para><emphasis>Layer Configuration File:</emphasis>
- You must include a <filename>conf/layer.conf</filename> in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename>
- BSP layer as a layer to the build system.</para></listitem>
- <listitem><para><emphasis>Machine Configuration File:</emphasis>
- You must include one or more
- <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename>
- files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- These configuration files define machine targets that can be built
- using the BSP layer.
- Multiple machine configuration files define variations of machine
- configurations that are supported by the BSP.
- If a BSP supports multiple machine variations, you need to
- adequately describe each variation in the BSP
- <filename>README</filename> 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.
- <note>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. <filename>meta-yocto-bsp</filename> layer).
- Such considerations are outside the scope of this document.</note>
+ <listitem><para>
+ Instructions on how to build the BSP using
+ the BSP layer.
+ </para></listitem>
+ <listitem><para>
+ Instructions on how to boot the BSP build
+ from the BSP layer.
+ </para></listitem>
+ <listitem><para>
+ Instructions on how to boot the binary
+ images contained in the
+ <filename>binary</filename> directory,
+ if present.
+ </para></listitem>
+ <listitem><para>
+ Information on any known bugs or issues
+ that users should know about when either
+ building or booting the BSP binaries.
</para></listitem>
</itemizedlist>
- </para>
- </section>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>README.sources File:</emphasis>
+ If you BSP contains binary images in the
+ <filename>binary</filename> directory, you must
+ include a <filename>README.sources</filename>
+ file in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ This file specifies exactly where you can find
+ the sources used to generate the binary images.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Layer Configuration File:</emphasis>
+ You must include a
+ <filename>conf/layer.conf</filename> file in
+ the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ This file identifies the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ BSP layer as a layer to the build system.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Machine Configuration File:</emphasis>
+ You must include one or more
+ <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+ files in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ 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 <filename>README</filename> 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.
+ <note>
+ 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. <filename>meta-yocto-bsp</filename> layer).
+ Such considerations are outside the scope of
+ this document.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
- <section id='released-bsp-recommendations'>
- <title>Released BSP Recommendations</title>
+ <section id='released-bsp-recommendations'>
+ <title>Released BSP Recommendations</title>
- <para>
- Following are recommendations for a released BSP that conforms to the
- Yocto Project:
- <itemizedlist>
- <listitem><para><emphasis>Bootable Images:</emphasis>
- BSP releases
- can contain one or more bootable images.
- Including bootable images allows users to easily try out the BSP
- on their own hardware.</para>
- <para>In some cases, it might not be convenient to include a
- bootable image.
- In this case, you might want to make two versions of the
- BSP available: one that contains binary images, and one
- that does not.
- The version that does not contain bootable images avoids
- unnecessary download times for users not interested in the images.
- </para>
- <para>If you need to distribute a BSP and include bootable images or build kernel and
- filesystems meant to allow users to boot the BSP for evaluation
- purposes, you should put the images and artifacts within a
- <filename>binary/</filename> subdirectory located in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- <note>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.</note></para></listitem>
- <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
- 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 <filename>Yocto Linux Kernel</filename> category in the
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
- for these kernels.</para></listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
+ <para>
+ Following are recommendations for released BSPs that
+ conform to the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Bootable Images:</emphasis>
+ Released BSPs can contain one or more bootable
+ images.
+ Including bootable images allows users to easily
+ try out the BSP using their own hardware.</para>
- <section id='customizing-a-recipe-for-a-bsp'>
- <title>Customizing a Recipe for a BSP</title>
+ <para>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.</para>
- <para>
- If you plan on customizing a recipe for a particular BSP, you need to do the
- following:
- <itemizedlist>
- <listitem><para>Create a <filename>.bbappend</filename>
- file for the modified recipe.
- For information on using append files, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>
- Ensure your directory structure in the BSP layer
- that supports your machine is such that it can be found
- by the build system.
- See the example later in this section for more information.
- </para></listitem>
- <listitem><para>
- 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.
- <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>,
- <filename>recipes-core</filename>, and so forth).
- </para></listitem>
- <listitem><para>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 out 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.
- </para></listitem>
- </itemizedlist>
- </para>
+ <para>If you need to distribute a BSP and include
+ bootable images or build kernel and filesystems
+ meant to allow users to boot the BSP for evaluation
+ purposes, you should put the images and artifacts
+ within a
+ <filename>binary/</filename> subdirectory located
+ in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ <note>
+ 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.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Use a Yocto Linux Kernel:</emphasis>
+ 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 <filename>Yocto Linux Kernel</filename>
+ category in the
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
+ for these kernels.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
- <para>
- Following is a specific example to help you better understand the process.
- Consider an example that customizes a recipe by adding
- a BSP-specific configuration file named <filename>interfaces</filename> to the
- <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the
- BSP layer also supports several other machines.
- Do the following:
- <orderedlist>
- <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it
- contains the following:
- <literallayout class='monospaced'>
+<section id='customizing-a-recipe-for-a-bsp'>
+ <title>Customizing a Recipe for a BSP</title>
+
+ <para>
+ If you plan on customizing a recipe for a particular BSP,
+ you need to do the following:
+ <itemizedlist>
+ <listitem><para>
+ Create a <filename>*.bbappend</filename> file for
+ the modified recipe.
+ For information on using append files, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ <filename>recipes-bsp</filename>,
+ <filename>recipes-graphics</filename>,
+ <filename>recipes-core</filename>, and so forth).
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ 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
+ <filename>interfaces</filename> to the
+ <filename>init-ifupdown_1.0.bb</filename> recipe for machine
+ "xyz" where the BSP layer also supports several other
+ machines:
+ <orderedlist>
+ <listitem><para>
+ Edit the
+ <filename>init-ifupdown_1.0.bbappend</filename> file
+ so that it contains the following:
+ <literallayout class='monospaced'>
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
- </literallayout>
- The append file needs to be in the
- <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory.
- </para></listitem>
- <listitem><para>Create and place the new <filename>interfaces</filename>
- configuration file in the BSP's layer here:
- <literallayout class='monospaced'>
+ </literallayout>
+ The append file needs to be in the
+ <filename>meta-xyz/recipes-core/init-ifupdown</filename>
+ directory.
+ </para></listitem>
+ <listitem><para>
+ Create and place the new
+ <filename>interfaces</filename> configuration file in
+ the BSP's layer here:
+ <literallayout class='monospaced'>
meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
- </literallayout>
- <note>
- If the <filename>meta-xyz</filename> layer did not support
- multiple machines, you would place the
- <filename>interfaces</filename> configuration file in the
- layer here:
- <literallayout class='monospaced'>
+ </literallayout>
+ <note>
+ If the <filename>meta-xyz</filename> layer did
+ not support multiple machines, you would place
+ the <filename>interfaces</filename> configuration
+ file in the layer here:
+ <literallayout class='monospaced'>
meta-xyz/recipes-core/init-ifupdown/files/interfaces
- </literallayout>
- </note>
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- 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
- <filename>files</filename> directory in the same location
- as your append file.</para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='bsp-licensing-considerations'>
- <title>BSP Licensing Considerations</title>
-
- <para>
- 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 the license is accepted, 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- For cases where you can substitute a free component and still
- maintain the system's functionality, the "Downloads" page from the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink>
- makes available de-featured BSPs
- that are completely free of any IP encumbrances.
- For these cases, you can use the substitution directly and
- without any further licensing requirements.
- If present, these fully de-featured BSPs are named appropriately
- different as compared to the names of the respective
- encumbered BSPs.
- If available, these substitutions are your
- simplest and most preferred options.
- Use of these substitutions of course assumes the resulting functionality meets
- system requirements.
- </para>
-
- <para>
- If however, a non-encumbered version is unavailable or
- it provides unsuitable functionality or quality, you can use an encumbered
- version.
- </para>
-
- <para>
- 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:
- <orderedlist>
- <listitem><para><emphasis>Use the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
- variable to define the recipes that have commercial or other
- types of specially-licensed packages:</emphasis>
- For each of those recipes, you can
- specify a matching license string in a
- <filename>local.conf</filename> variable named
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
- 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
- "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
- Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
- Manual for details on how to use these variables.</para>
- <para>If you build as you normally would, without
- specifying any recipes in the
- <filename>LICENSE_FLAGS_WHITELIST</filename>, 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 <filename>LICENSE_FLAGS_WHITELIST</filename>.
- 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.</para>
- <para>Once the appropriate license flags are on the white list
- in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
- can build the encumbered image with no change at all
- to the normal build process.</para></listitem>
- <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis>
- You can get this type of BSP by visiting the
- "Downloads" page of the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
- 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.
- Note that if you want to build the image
- yourself using the recipes contained within the BSP
- tarball, you will still need to create an
- appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the
- encumbered recipes in the BSP.</para></listitem>
- </orderedlist>
- </para>
-
- <note>
- 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.
- </note>
- </section>
-
- <section id='using-the-yocto-projects-bsp-tools'>
- <title>Using the Yocto Project's BSP Tools</title>
-
- <para>
- The Yocto Project includes a couple of tools that enable
- you to create a <link linkend='bsp-layers'>BSP layer</link>
- from scratch and do basic configuration and maintenance
- of the kernel without ever looking at a Metadata file.
- These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
- respectively.
- </para>
-
- <para>
- The following sections describe the common location and help features as well
- as provide details for the
- <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools.
- </para>
-
- <section id='common-features'>
- <title>Common Features</title>
-
- <para>
- Designed to have a command interface somewhat like
- <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>, each
- tool is structured as a set of sub-commands under a
- top-level command.
- The top-level command (<filename>yocto-bsp</filename>
- or <filename>yocto-kernel</filename>) itself does
- nothing but invoke or provide help on the sub-commands
- it supports.
- </para>
-
- <para>
- Both tools reside in the <filename>scripts/</filename> subdirectory
- of the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- Consequently, to use the scripts, you must <filename>source</filename> the
- environment just as you would when invoking a build:
- <literallayout class='monospaced'>
- $ source oe-init-build-env <replaceable>build_dir</replaceable>
</literallayout>
+ </note>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+ 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
+ <filename>files</filename> directory in the same
+ location as your append file.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='bsp-licensing-considerations'>
+ <title>BSP Licensing Considerations</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>
+ makes available de-featured BSPs that are completely free
+ of any IP encumbrances.
+ For these cases, you can use the substitution directly and
+ without any further licensing requirements.
+ If present, these fully de-featured BSPs are named
+ appropriately different as compared to the names of 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.
+ <note>
+ If however, a non-encumbered version is unavailable or
+ it provides unsuitable functionality or quality, you can
+ use an encumbered version.
+ </note>
+ </para>
+
+ <para>
+ 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:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
+ Variable to Define the Recipes that Have Commercial
+ or Other Types of Specially-Licensed Packages:</emphasis>
+ For each of those recipes, you can specify a
+ matching license string in a
+ <filename>local.conf</filename> variable named
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
+ 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
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual for details on how to use these variables.
</para>
- <para>
- 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 <filename>help</filename>
- switch:
- <literallayout class='monospaced'>
- $ yocto-bsp help
- Usage:
+ <para>If you build as you normally would, without
+ specifying any recipes in the
+ <filename>LICENSE_FLAGS_WHITELIST</filename>, 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
+ <filename>LICENSE_FLAGS_WHITELIST</filename>.
+ 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.</para>
- Create a customized Yocto BSP layer.
+ <para>Once the appropriate license flags are on the
+ white list in the
+ <filename>LICENSE_FLAGS_WHITELIST</filename> variable,
+ you can build the encumbered image with no change
+ at all to the normal build process.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Get a Pre-Built Version of the BSP:</emphasis>
+ You can get this type of BSP by selecting the
+ "DOWNLOADS" item from the "SOFTWARE" tab on the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
+ 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
+ <filename>LICENSE_FLAGS_WHITELIST</filename>
+ to match the encumbered recipes in the BSP.
+ </para></listitem>
+ </orderedlist>
+ <note>
+ 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.
+ </note>
+ </para>
+</section>
- usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
+<section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>
+ <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
- Current 'yocto-bsp' commands are:
- create Create a new Yocto BSP
- list List available values for options and BSP properties
+ <para>
+ The <filename>bitbake-layers create-layer</filename> script
+ automates creating a BSP layer.
+ What makes a layer a "BSP layer", is the presence of a machine
+ configuration file.
+ Additionally, a BSP layer usually has a kernel recipe
+ or an append file that leverages off an existing kernel recipe.
+ The primary requirement, however, is the machine configuration.
+ </para>
- See 'yocto-bsp help COMMAND' for more information on a specific command.
+ <para>
+ Use these steps to create a BSP layer:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Create a General Layer:</emphasis>
+ Use the <filename>bitbake-layers</filename> script with the
+ <filename>create-layer</filename> subcommand to create a
+ new general layer.
+ For instructions on how to create a general layer using the
+ <filename>bitbake-layers</filename> script, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Layer Configuration File:</emphasis>
+ Every layer needs a layer configuration file.
+ This configuration file establishes locations for the
+ layer's recipes, priorities for the layer, and so forth.
+ You can find examples of <filename>layer.conf</filename>
+ files in the Yocto Project
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
+ To get examples of what you need in your configuration
+ file, locate a layer (e.g. "meta-ti") and examine the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink>
+ file.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Machine Configuration File:</emphasis>
+ Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+ file.
+ See
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink>
+ for sample
+ <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+ files.
+ Other samples such as
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink>
+ and
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink>
+ exist from other vendors that have more specific machine
+ and tuning examples.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Kernel Recipe:</emphasis>
+ Create a kernel recipe in <filename>recipes-kernel/linux</filename>
+ by either using a kernel append file or a new custom kernel
+ recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>).
+ The BSP layers mentioned in the previous step also contain different
+ kernel examples.
+ See the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
+ section in the Yocto Project Linux Kernel Development Manual
+ for information on how to create a custom kernel.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The remainder of this section provides a description of
+ the Yocto Project reference BSP for Beaglebone, which
+ resides in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>Container Layer</ulink>
+ (i.e.
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink>).
+ </para>
- Options:
- --version show program's version number and exit
- -h, --help show this help message and exit
- -D, --debug output debug information
- </literallayout>
- </para>
+ <section id='bsp-layer-configuration-example'>
+ <title>BSP Layer Configuration Example</title>
- <para>
- Similarly, entering just the name of a sub-command shows the detailed usage
- for that sub-command:
- <literallayout class='monospaced'>
- $ yocto-bsp create
- ERROR:root:Wrong number of arguments, exiting
+ <para>
+ The layer's <filename>conf</filename> directory
+ contains the <filename>layer.conf</filename>
+ configuration file.
+ In this example, the
+ <filename>conf/layer.conf</filename> is the
+ following:
+ <literallayout class='monospaced'>
+ # We have a conf and classes directory, add to BBPATH
+ BBPATH .= ":${LAYERDIR}"
- Usage:
+ # We have recipes-* directories, add to BBFILES
+ BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+ ${LAYERDIR}/recipes-*/*/*.bbappend"
- Create a new Yocto BSP
+ BBFILE_COLLECTIONS += "yoctobsp"
+ BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
+ BBFILE_PRIORITY_yoctobsp = "5"
+ LAYERVERSION_yoctobsp = "4"
+ LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
+ </literallayout>
+ The variables used in this file configure the
+ layer.
+ A good way to learn about layer configuration
+ files is to examine various files for BSP from
+ the
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
+ </para>
- usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
- [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
+ <para>
+ For a detailed description of this particular
+ layer configuration file, see
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink>
+ in the discussion that describes how to create
+ layers in the Yocto Project Development Tasks Manual.
+ </para>
+ </section>
- 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.
+ <section id='bsp-machine-configuration-example'>
+ <title>BSP Machine Configuration Example</title>
- 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'.
+ <para>
+ As mentioned earlier in this section, the existence
+ of a machine configuration file is what makes a
+ layer a BSP layer as compared to a general or
+ kernel layer.
+ </para>
- ...
- </literallayout>
- </para>
+ <para>
+ Machine configuration files exist in the
+ <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
+ directory of the layer:
+ <literallayout class='monospaced'>
+ <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine</replaceable><filename>.conf</filename>
+ </literallayout>
+ For example, the machine configuration file for the
+ <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
+ is located in the container layer
+ <filename>poky/meta-yocto-bsp/conf/machine</filename>
+ and is named <filename>beaglebone-yocto.conf</filename>:
+ <literallayout class='monospaced'>
+ #@TYPE: Machine
+ #@NAME: Beaglebone-yocto machine
+ #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards
- <para>
- For any sub-command, you can use the word "help" option just before the
- sub-command to get more extensive documentation:
- <literallayout class='monospaced'>
- $ yocto-bsp help create
+ PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
+ XSERVER ?= "xserver-xorg \
+ xf86-video-modesetting \
+ "
- NAME
- yocto-bsp create - Create a new Yocto BSP
+ MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"
- SYNOPSIS
- yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
- [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
+ EXTRA_IMAGEDEPENDS += "u-boot"
- 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.
+ DEFAULTTUNE ?= "cortexa8hf-neon"
+ include conf/machine/include/tune-cortexa8.inc
- ...
- </literallayout>
- </para>
+ IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap"
+ EXTRA_IMAGECMD_jffs2 = "-lnp "
+ WKS_FILE ?= "beaglebone-yocto.wks"
+ IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage"
+ do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot"
- <para>
- Now that you know where these two commands reside and how to access information
- on them, you should find it relatively straightforward to discover the commands
- necessary to create a BSP and perform basic kernel maintenance on that BSP using
- the tools.
- <note>
- You can also use the <filename>bitbake-layers</filename> script to create
- a "generic" layer.
- For information on using this script to create a layer, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
- section in the Yocto Project Development Tasks Manual.
+ SERIAL_CONSOLES = "115200;ttyO0"
+
+ PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+ PREFERRED_VERSION_linux-yocto ?= "4.12%"
+
+ KERNEL_IMAGETYPE = "zImage"
+ KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
+ KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
+
+ SPL_BINARY = "MLO"
+ UBOOT_SUFFIX = "img"
+ UBOOT_MACHINE = "am335x_boneblack_config"
+ UBOOT_ENTRYPOINT = "0x80008000"
+ UBOOT_LOADADDRESS = "0x80008000"
+
+ MACHINE_FEATURES = "usbgadget usbhost vfat alsa"
+
+ IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO"
+ </literallayout>
+ The variables used to configure the machine define
+ machine-specific properties.
+ For example, machine-dependent packages, machine
+ tunings, the type of kernel to build, and
+ U-Boot configurations.
+ </para>
+
+ <para>
+ The following list provides some explanation
+ for the statements found in the example reference
+ machine configuration file for the BeagleBone
+ development boards.
+ Realize that much more can be defined as part of
+ a machines configuration file.
+ In general, you can learn about related variables
+ that this example does not have by locating the
+ variables in the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>"
+ in the Yocto Project Reference Manual.
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>:
+ The recipe that provides "virtual/xserver" when
+ more than one provider is found.
+ In this case, the recipe that provides
+ "virtual/xserver" is "xserver-xorg", which
+ exists in
+ <filename>poky/meta/recipes-graphics/xserver-xorg</filename>.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>:
+ The packages that should be installed to provide
+ an X server and drivers for the machine.
+ In this example, the "xserver-xorg" and
+ "xf86-video-modesetting" are installed.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>:
+ A list of machine-dependent packages
+ not essential for booting the image.
+ Thus, the build does not fail if the packages
+ do not exist.
+ However, the packages are required for a
+ fully-featured image.
+ <note><title>Tip</title>
+ Many <filename>MACHINE*</filename> variables
+ exist that help you configure a particular
+ piece of hardware.
</note>
- </para>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>:
+ Recipes to build that do not provide packages
+ for installing into the root filesystem
+ but building the image depends on the
+ recipes.
+ Sometimes a recipe is required to build
+ the final image but is not needed in the
+ root filesystem.
+ In this case, the U-Boot recipe must be
+ built for the image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>:
+ Machines use tunings to optimize machine,
+ CPU, and application performance.
+ These features, which are collectively known
+ as "tuning features", exist in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
+ layer (e.g.
+ <filename>poky/meta/conf/machine/include</filename>).
+ In this example, the default tunning file is
+ "cortexa8hf-neon".
+ <note>
+ The <filename>include</filename> statement
+ that pulls in the
+ <filename>conf/machine/include/tune-cortexa8.inc</filename>
+ file provides many tuning possibilities.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>:
+ The formats the OpenEmbedded build system
+ uses during the build when creating the
+ root filesystem.
+ In this example, four types of images are
+ supported.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>:
+ Specifies additional options for image
+ creation commands.
+ In this example, the "-lnp " option is used
+ when creating the
+ <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink>
+ image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>:
+ The location of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink>
+ file used by the OpenEmbedded build system to
+ create a partitioned image (image.wic).
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
+ Specifies packages to install into an image
+ through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
+ class.
+ Recipes use the <filename>IMAGE_INSTALL</filename>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <filename>do_image_wic[depends]</filename>:
+ A task that is constructed during the build.
+ In this example, the task depends on specific tools
+ in order to create the sysroot when buiding a Wic
+ image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>:
+ Defines a serial console (TTY) to enable using
+ getty.
+ In this case, the baud rate is "115200" and the
+ device name is "ttyO0".
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>:
+ Specifies the recipe that provides
+ "virtual/kernel" when more than one provider
+ is found.
+ In this case, the recipe that provides
+ "virtual/kernel" is "linux-yocto", which
+ exists in the layer's
+ <filename>recipes-kernel/linux</filename> directory.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>:
+ Defines the version of the recipe used
+ to build the kernel, which is "4.12" in this
+ case.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>:
+ The type of kernel to build for the device.
+ In this case, the OpenEmbedded build system
+ creates a "zImage" image type.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>:
+ The name of the generated Linux kernel device
+ tree (i.e. the <filename>.dtb</filename>) file.
+ All the device trees for the various BeagleBone
+ devices are included.
+<!--
+ You have to include some *.inc files according to the definition of KERNEL_DEVICETREE.
+ I don't see where these are being provided.
+-->
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>:
+ Additional <filename>make</filename>
+ command-line arguments the OpenEmbedded build
+ system passes on when compiling the kernel.
+ In this example, "LOADADDR=${UBOOT_ENTRYPOINT}"
+ is passed as a command-line argument.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>:
+ Defines the Secondary Program Loader (SPL) binary
+ type.
+ In this case, the SPL binary is set to
+ "MLO", which stands for Multimedia card LOader.
+ </para>
- <para>
- 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.
- </para>
- </section>
-
-
- <section id='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
- <title>Creating a new BSP Layer Using the yocto-bsp Script</title>
-
- <para>
- The <filename>yocto-bsp</filename> script creates a new
- <link linkend='bsp-layers'>BSP layer</link> for any architecture supported
- by the Yocto Project, as well as QEMU versions of the same.
- The default mode of the script's operation is to prompt you for information needed
- to generate the BSP layer.
- </para>
-
- <para>
- For the current set of BSPs, the script prompts you for various important
- parameters such as:
+ <para>The BeagleBone development board requires an
+ SPL to boot and that SPL file type must be MLO.
+ Consequently, the machine configuration needs to
+ define <filename>SPL_BINARY</filename> as "MLO".
+ <note>
+ For more information on how the SPL variables
+ are used, see the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink>
+ include file.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>:
+ Defines various U-Boot configurations needed
+ to build a U-Boot image.
+ In this example, a U-Boot image is required
+ to boot the BeagleBone device.
+ See the following variables for more information:
<itemizedlist>
- <listitem><para>The kernel to use</para></listitem>
- <listitem><para>The branch of that kernel to use (or re-use)</para></listitem>
- <listitem><para>Whether or not to use X, and if so, which drivers to use</para></listitem>
- <listitem><para>Whether to turn on SMP</para></listitem>
- <listitem><para>Whether the BSP has a keyboard</para></listitem>
- <listitem><para>Whether the BSP has a touchscreen</para></listitem>
- <listitem><para>Remaining configurable items associated with the BSP</para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>:
+ Points to the generated U-Boot extension.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>:
+ Specifies the value passed on the make command line when building a U-Boot image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>:
+ Specifies the entry point for the U-Boot image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>:
+ Specifies the load address for the U-Boot image.
+ </para></listitem>
</itemizedlist>
- </para>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>:
+ Specifies the list of hardware features the
+ BeagleBone device is capable of supporting.
+ In this case, the device supports
+ "usbgadget usbhost vfat alsa".
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>:
+ Files installed into the device's boot partition
+ when preparing the image using the Wic tool
+ with the <filename>bootimg-partition</filename>
+ source plugin.
+ In this case, the "u-boot.${UBOOT_SUFFIX}" and
+ "MLO" files are installed.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
- <para>
- You use the <filename>yocto-bsp create</filename> sub-command to create
- a new BSP layer.
- This command requires you to specify a particular kernel architecture
- (<filename>karch</filename>) on which to base the BSP.
- Assuming you have sourced the environment, you can use the
- <filename>yocto-bsp list karch</filename> sub-command to list the
- architectures available for BSP creation as follows:
- <literallayout class='monospaced'>
- $ yocto-bsp list karch
- Architectures available:
- powerpc
- x86_64
- i386
- arm
- qemu
- mips
- mips64
- </literallayout>
- </para>
+ <section id='bsp-kernel-recipe-example'>
+ <title>BSP Kernel Recipe Example</title>
- <para>
- The remainder of this section presents an example that uses
- <filename>myarm</filename> as the machine name and <filename>qemu</filename>
- as the machine architecture.
- Of the available architectures, <filename>qemu</filename> 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.
- </para>
+ <para>
+ The kernel recipe used to build the kernel image
+ for the BeagleBone device was established in the
+ machine configuration:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+ PREFERRED_VERSION_linux-yocto ?= "4.12%"
+ </literallayout>
+ The <filename>meta-yocto-bsp/recipes-kernel/linux</filename>
+ directory in the layer contains metadata used
+ to build the kernel.
+ In this case, a kernel append file is used to
+ override an established kernel recipe, which is
+ located in
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>
+ and named
+ <filename>linux-yocto_4.12.bb</filename>.
+ </para>
- <para>
- As the <filename>yocto-bsp create</filename> command runs, default values for
- the prompts appear in brackets.
- Pressing enter without supplying anything on the command line or pressing enter
- with an invalid response causes the script to accept the default value.
- Once the script completes, the new <filename>meta-myarm</filename> BSP layer
- is created in the current working directory.
- This example assumes you have sourced the
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
- setup script.
- </para>
+ <para>
+ Following is the contents of the append file:
+ <literallayout class='monospaced'>
+ KBRANCH_genericx86 = "standard/base"
+ KBRANCH_genericx86-64 = "standard/base"
- <para>
- Following is the complete example:
- <literallayout class='monospaced'>
- $ yocto-bsp create myarm qemu
- Checking basic git connectivity...
- Done.
+ KMACHINE_genericx86 ?= "common-pc"
+ KMACHINE_genericx86-64 ?= "common-pc-64"
+ KBRANCH_edgerouter = "standard/edgerouter"
+ KBRANCH_beaglebone-yocto = "standard/beaglebone"
+ KMACHINE_beaglebone-yocto = "beaglebone"
+ KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
- Which qemu architecture would you like to use? [default: i386]
- 1) i386 (32-bit)
- 2) x86_64 (64-bit)
- 3) ARM (32-bit)
- 4) PowerPC (32-bit)
- 5) MIPS (32-bit)
- 6) MIPS64 (64-bit)
- 3
- Would you like to use the default (4.8) kernel? (y/n) [default: y]
- Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]
- Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-4.8.git...
- Please choose a machine branch to base this BSP on: [default: standard/base]
- 1) standard/arm-versatile-926ejs
- 2) standard/base
- 3) standard/beaglebone
- 4) standard/edgerouter
- 5) standard/fsl-mpc8315e-rdb
- 6) standard/mti-malta32
- 7) standard/mti-malta64
- 8) standard/qemuarm64
- 9) standard/qemuppc
- 1
- Would you like SMP support? (y/n) [default: y]
- Does your BSP have a touchscreen? (y/n) [default: n]
- Does your BSP have a keyboard? (y/n) [default: y]
-
- New qemu BSP created in meta-myarm
- </literallayout>
- Take a closer look at the example now:
- <orderedlist>
- <listitem><para>For the QEMU architecture,
- the script first prompts you for which emulated architecture to use.
- In the example, we use the ARM architecture.
- </para></listitem>
- <listitem><para>The script then prompts you for the kernel.
- The default 4.8 kernel is acceptable.
- So, the example accepts the default.
- If you enter 'n', the script prompts you to further enter the kernel
- you do want to use.</para></listitem>
- <listitem><para>Next, the script asks whether you would like to have a new
- branch created especially for your BSP in the local
- Linux Yocto Kernel Git repository .
- If not, then the script re-uses an existing branch.</para>
- <para>In this example, the default (or "yes") is accepted.
- Thus, a new branch is created for the BSP rather than using a common, shared
- branch.
- The new branch is the branch committed to for any patches you might later add.
- The reason a new branch is the default is that typically
- new BSPs do require BSP-specific patches.
- The tool thus assumes that most of time a new branch is required.
- </para></listitem>
- <listitem><para>Regardless of which choice you make in the previous step,
- you are now given the opportunity to select a particular machine branch on
- which to base your new BSP-specific machine branch
- (or to re-use if you had elected to not create a new branch).
- Because this example is generating an ARM-based BSP, the example
- uses <filename>#1</filename> at the prompt, which selects the ARM-versatile branch.
- </para></listitem>
- <listitem><para>The remainder of the prompts are routine.
- Defaults are accepted for each.</para></listitem>
- <listitem><para>By default, the script creates the new BSP Layer in the
- current working directory of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
- (i.e. <filename>poky/build</filename>).
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- Once the BSP Layer is created, you must add it to your
- <filename>bblayers.conf</filename> file.
- Here is an example:
- <literallayout class='monospaced'>
- 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 \
- "
- </literallayout>
- Adding the layer to this file allows the build system to build the BSP and
- the <filename>yocto-kernel</filename> tool to be able to find the layer and
- other Metadata it needs on which to operate.
- </para>
- </section>
-
- <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
- <title>Managing Kernel Patches and Config Items with yocto-kernel</title>
-
- <para>
- Assuming you have created a <link linkend='bsp-layers'>BSP Layer</link> using
- <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
- <filename>yocto-bsp</filename></link> and you added it to your
- <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
- variable in the <filename>bblayers.conf</filename> file, you can now use
- the <filename>yocto-kernel</filename> script to add patches and configuration
- items to the BSP's kernel.
- </para>
-
- <para>
- The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
- and kernel config settings to a BSP's kernel
- <filename>.bbappend</filename> 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 <filename>yocto-kernel</filename> built-in help as follows:
- <literallayout class='monospaced'>
- $ 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.
+ SRCREV_machine_genericx86 ?= "1c4ad569af3e23a77994235435040e322908687f"
+ SRCREV_machine_genericx86-64 ?= "1c4ad569af3e23a77994235435040e322908687f"
+ SRCREV_machine_edgerouter ?= "257f843ea367744620f1d92910afd2f454e31483"
+ SRCREV_machine_beaglebone-yocto ?= "257f843ea367744620f1d92910afd2f454e31483"
+ SRCREV_machine_mpc8315e-rdb ?= "014560874f9eb2a86138c9cc35046ff1720485e1"
+ COMPATIBLE_MACHINE_genericx86 = "genericx86"
+ COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
+ COMPATIBLE_MACHINE_edgerouter = "edgerouter"
+ COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto"
+ COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
- Options:
- --version show program's version number and exit
- -h, --help show this help message and exit
- -D, --debug output debug information
- </literallayout>
- </para>
+ LINUX_VERSION_genericx86 = "4.12.20"
+ LINUX_VERSION_genericx86-64 = "4.12.20"
+ LINUX_VERSION_edgerouter = "4.12.19"
+ LINUX_VERSION_beaglebone-yocto = "4.12.19"
+ LINUX_VERSION_mpc8315e-rdb = "4.12.19"
+ </literallayout>
+ This particular append file works for all the
+ machines that are part of the
+ <filename>meta-yocto-bsp</filename> container
+ layer.
+ The relevant statements are appended with
+ the "beaglebone-yocto" string.
+ The OpenEmbedded build system uses these
+ statements to override similar statements
+ in the kernel recipe:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>:
+ Identifies the kernel branch that is validated,
+ patched, and configured during the build.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>:
+ Identifies the machine name as known by the
+ kernel, which is sometimes a different name
+ than what is known by the OpenEmbedded build
+ system.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
+ Identifies the revision of the source code used
+ to build the image.
+<!--
+ You find out about that point in the kernel source tree by
+ doing the following command:
- <para>
- The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
- patch to a BSP.
- The following example adds two patches to the <filename>myarm</filename> BSP:
- <literallayout class='monospaced'>
- $ yocto-kernel patch add myarm ~/test.patch
- Added patches:
- test.patch
+ git log ‐‐decorate 257f843ea367744620f1d92910afd2f454e31483
- $ yocto-kernel patch add myarm ~/yocto-testmod.patch
- Added patches:
- yocto-testmod.patch
- </literallayout>
- <note>Although the previous example adds patches one at a time, it is possible
- to add multiple patches at the same time.</note>
- </para>
-
- <para>
- You can verify patches have been added by using the
- <filename>yocto-kernel patch list</filename> sub-command.
- Here is an example:
- <literallayout class='monospaced'>
- $ yocto-kernel patch list myarm
- The current set of machine-specific patches for myarm is:
- 1) test.patch
- 2) yocto-testmod.patch
- </literallayout>
- </para>
-
- <para>
- You can also use the <filename>yocto-kernel</filename> script to
- remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command.
- Here is an example:
- <literallayout class='monospaced'>
- $ yocto-kernel patch rm myarm
- Specify the patches to remove:
- 1) test.patch
- 2) yocto-testmod.patch
- 1
- Removed patches:
- test.patch
- </literallayout>
- </para>
-
- <para>
- Again, using the <filename>yocto-kernel patch list</filename> sub-command,
- you can verify that the patch was in fact removed:
- <literallayout class='monospaced'>
- $ yocto-kernel patch list myarm
- The current set of machine-specific patches for myarm is:
- 1) yocto-testmod.patch
- </literallayout>
- </para>
-
- <para>
- In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
- 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
- <filename>myarm</filename> BSP:
- <literallayout class='monospaced'>
- $ 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
- </literallayout>
- <note>
- Although the previous example adds config items one at a time, it is possible
- to add multiple config items at the same time.
- </note>
- </para>
-
- <para>
- 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:
- <literallayout class='monospaced'>
- $ 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
- </literallayout>
- </para>
-
- <para>
- Finally, you can remove one or more config items using the
- <filename>yocto-kernel config rm</filename> sub-command in a manner
- completely analogous to <filename>yocto-kernel patch rm</filename>.
- </para>
- </section>
- </section>
+ Returns information about the commit, which is usually
+ that it is a merge point for a stable kernel release.
+-->
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
+ A regular expression that resolves to one or
+ more target machines with which the recipe
+ is compatible.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
+ The Linux version from kernel.org used by
+ the OpenEmbedded build system to build the
+ kernel image.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
</chapter>