diff options
| author |   Scott Rifenbark <srifenbark@gmail.com> | 2018-03-09 13:11:53 -0800 |
|---|---|---|
| committer |   Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-03-25 09:41:12 +0100 |
| commit | fdd79ab4cb37993b6d94cfcae470a1ce0f0517e1 (patch) | |
| tree | a598da3d4a7df1c13d44f6ee6ee8db4affcd6680 /documentation/bsp-guide | |
| parent | 7f141cf9a0e357bcd11ad50d7b40cea5a388df3c (diff) | |
| download | openembedded-core-contrib-fdd79ab4cb37993b6d94cfcae470a1ce0f0517e1.tar.gz | |
bsp-guide: Removed deprecated tool sections
I took out the sections at the end of the manual that talked
about the yocto-kernel tool. This tool is no longer maintained
and there is no equivalent tool. I also fixed the yocto-bsp
tool to be the bitbake-layers tool. This involved some
consolidation of sections.
I fixed some links in the kernel-dev and toaster-manual.
(From yocto-docs rev: 20cda99b301b6327d816c4a4cfb3511ad25c987c)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/bsp-guide')
| -rw-r--r-- | documentation/bsp-guide/bsp.xml | 3312 |
1 files changed, 1491 insertions, 1821 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 1edbc049de..a93ac50f6f 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -4,230 +4,231 @@ <chapter id='bsp'> - <title>Board Support Packages (BSP) - Developer's Guide</title> - - <para> - A Board Support Package (BSP) is a collection of information that - defines how to support a particular hardware device, set of devices, or - hardware platform. - The BSP includes information about the hardware features - present on the device and kernel configuration information along with any - additional hardware drivers required. - The BSP also lists any additional software - components required in addition to a generic Linux software stack for both - essential and optional platform features. - </para> - - <para> - This 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> - - <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, BSP layers in the Yocto Project - use the following well-established naming convention: - <literallayout class='monospaced'> +<title>Board Support Packages (BSP) - Developer's Guide</title> + +<para> + A Board Support Package (BSP) is a collection of information that + defines how to support a particular hardware device, set of devices, or + hardware platform. + The BSP includes information about the hardware features + present on the device and kernel configuration information along with any + additional hardware drivers required. + The BSP also lists any additional software + components required in addition to a generic Linux software stack for both + essential and optional platform features. +</para> + +<para> + This 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> + + <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_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, 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_GS_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 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'> + </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, 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_GS_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 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> - - <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> - 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 - <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'> + </literallayout> + </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> + 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 + <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> - - <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 layers function as a layer to hold other BSP layers. - 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 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> - - <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> + </literallayout> + </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 layers function as a layer to hold other BSP layers. + 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 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> + + <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'>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 + <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>" - 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. + (e.g. <filename>poky</filename>). + <literallayout class='monospaced'> + $ cd /home/<replaceable>you</replaceable>/poky + </literallayout> </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>). - <literallayout class='monospaced'> - $ cd /home/<replaceable>you</replaceable>/poky - </literallayout> - </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: 15585, done. @@ -236,44 +237,44 @@ Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done. Resolving deltas: 100% (9123/9123), done. Checking connectivity... done. - </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'> + </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'> $ 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> - <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> + </literallayout> + <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> - <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-raspberrypi</filename>, - clone that layer: - <literallayout class='monospaced'> + </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-raspberrypi</filename>, + clone that layer: + <literallayout class='monospaced'> $ git clone git://git.yoctoproject.org/meta-raspberrypi Cloning into 'meta-raspberrypi'... remote: Counting objects: 4743, done. @@ -282,88 +283,88 @@ Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done. Resolving deltas: 100% (2447/2447), done. Checking connectivity... done. - </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. - <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_GS_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> + </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_GS_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_name</replaceable>/ meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> meta-<replaceable>bsp_name</replaceable>/README @@ -375,13 +376,13 @@ 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 - </literallayout> - </para> + </literallayout> + </para> - <para> - Below is an example of the Raspberry Pi BSP - layer that ships with the Yocto Project: - <literallayout class='monospaced'> + <para> + Below is an example of the Raspberry Pi BSP + layer that ships with the Yocto Project: + <literallayout class='monospaced'> meta-raspberrypi/COPYING.MIT meta-raspberrypi/README.md meta-raspberrypi/classes @@ -535,167 +536,167 @@ meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend meta-raspberrypi/wic meta-raspberrypi/wic/sdimage-raspberrypi.wks - </literallayout> - </para> + </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'> + <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> + </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. - 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> + <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'> + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/README - </literallayout> - </para> + </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 - 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'> + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/README.sources - </literallayout> - </para> + </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 and usually does not exist. - </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_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'> + <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> + </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 - <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> + <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'> + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/conf/layer.conf - </literallayout> - </para> + </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> 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_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}" @@ -708,14 +709,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}" @@ -732,1429 +733,1098 @@ . . . - </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'> + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf - </literallayout> - </para> + </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. - 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> + 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 - <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> + 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> - 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, 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> - 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'> + <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> + </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'> + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* - </literallayout> - </para> + </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> - - <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'> + <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> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* - </literallayout> - </para> + </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'> + <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> + meta-<replaceable>bsp_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 recipe. + This area of the BSP hierarchy can contain both these + types of files. + </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_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_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> - - <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> - - <section id='developing-a-board-support-package-bsp'> - <title>Developing a Board Support Package (BSP)</title> - - <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> - - <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> - The following illustration and list summarize the BSP - creation general workflow. - </para> - - <para> - <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" /> - </para> + </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> - <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'>Setting Up the Development Host to Use the Yocto Project</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>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_GS_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" - section in the Getting Started With Yocto Project - 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. - </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. - </para></listitem> - <listitem><para> - <filename>intel-quark</filename>, - which is a BSP optimized for the - Intel Galileo gen1 & gen2 - development boards. - </para></listitem> - </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>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> + 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> - <para> - Following are the requirements for a released BSP - that conform to the Yocto Project: + <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 an + include file. + </para> + </section> +</section> + +<section id='developing-a-board-support-package-bsp'> + <title>Developing a Board Support Package (BSP)</title> + + <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> + 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> + The following illustration and list summarize the BSP + creation general workflow. + </para> + + <para> + <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" /> + </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'>Setting Up the Development Host to Use the Yocto Project</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>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_GS_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" + section in the Getting Started With Yocto Project + 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> - <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_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_name</replaceable> - 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: + 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> - A brief description about the hardware the BSP - targets. + Texas Instruments Beaglebone + (<filename>beaglebone-yocto</filename> </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. + Freescale MPC8315E-RDB + (<filename>mpc8315e-rdb</filename>) </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> + Ubiquiti Networks EdgeRouter Lite + (<filename>edgerouter</filename>) + </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. + 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> - Instructions on how to boot the BSP build - from the BSP layer. + <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. </para></listitem> <listitem><para> - Instructions on how to boot the binary - images contained in the - <filename>binary</filename> directory, - if present. + <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. </para></listitem> <listitem><para> - Information on any known bugs or issues - that users should know about when either - building or booting the BSP binaries. + <filename>intel-quark</filename>, + which is a BSP optimized for the + Intel Galileo gen1 & gen2 + development boards. </para></listitem> </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>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_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_name</replaceable> + 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> - <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_name</replaceable> - directory. - This file specifies exactly where you can find - the sources used to generate the binary images. + A brief description about the hardware the BSP + targets. </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_name</replaceable> - directory. - This file identifies the - <filename>meta-</filename><replaceable>bsp_name</replaceable> - BSP layer as a layer to the build system. + 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>Machine Configuration File:</emphasis> - You must include one or more - <filename>conf/machine/</filename><replaceable>bsp_name</replaceable><filename>.conf</filename> - files in the - <filename>meta-</filename><replaceable>bsp_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> + 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> - </itemizedlist> - </para> - </section> - - <section id='released-bsp-recommendations'> - <title>Released BSP Recommendations</title> - - <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> - - <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 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_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> + 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>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. + Instructions on how to build the BSP using + the BSP layer. </para></listitem> - </itemizedlist> - </para> - </section> - </section> - - <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'> - 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'> - 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 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_CM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>" - section in the Yocto Project Concepts 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 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> - - <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_GS_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> - </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: - - Create a customized Yocto BSP layer. - - usage: yocto-bsp [--version] [--help] COMMAND [ARGS] - - Current 'yocto-bsp' commands are: - create Create a new Yocto BSP - list List available values for options and BSP properties - - See 'yocto-bsp help COMMAND' for more information on a specific command. - - - Options: - --version show program's version number and exit - -h, --help show this help message and exit - -D, --debug output debug information - </literallayout> - </para> - - <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 - - Usage: - - Create a new Yocto BSP - - usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] - [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] - - This command creates a Yocto BSP based on the specified parameters. - The new BSP will be a new Yocto BSP layer contained by default within - the top-level directory specified as 'meta-bsp-name'. The -o option - can be used to place the BSP layer in a directory with a different - name and location. - - The value of the 'karch' parameter determines the set of files that - will be generated for the BSP, along with the specific set of - 'properties' that will be used to fill out the BSP-specific portions - of the BSP. The possible values for the 'karch' parameter can be - listed via 'yocto-bsp list karch'. - - ... - </literallayout> - </para> - - <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 - - NAME - yocto-bsp create - Create a new Yocto BSP - - SYNOPSIS - yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] - [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] - - DESCRIPTION - This command creates a Yocto BSP based on the specified - parameters. The new BSP will be a new Yocto BSP layer contained - by default within the top-level directory specified as - 'meta-bsp-name'. The -o option can be used to place the BSP layer - in a directory with a different name and location. - - ... - </literallayout> - </para> - - <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. - </note> - </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-bitbake-layers-script'> - <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title> - - <para role='writernotes'> - I have put in information that will be the basis of this section, - but it is missing a lot at this point. - This whole section needs reviewed and filled in with proper - information. - </para> - - <para> - [INTRODUCE THE PROCEDURE AND LINK BACK TO <link linkend='bsp-layers'>BSP layer</link>. - IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET - UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.] - <itemizedlist> - <listitem><para>[PARAMETER 1]</para></listitem> - <listitem><para>[PARAMETER 2]</para></listitem> - <listitem><para>[PARAMETER 3]</para></listitem> - <listitem><para>[PARAMETER 4]</para></listitem> - <listitem><para>[PARAMETER 5]</para></listitem> - <listitem><para>[PARAMETER 6]</para></listitem> - <listitem><para>[PARAMETER 7]</para></listitem> - </itemizedlist> - </para> - - <para> - The following procedure creates a BSP layer: - <itemizedlist> <listitem><para> - <emphasis>Create 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. + Instructions on how to boot the BSP build + from the BSP layer. </para></listitem> <listitem><para> - <emphasis>Create a Machine Configuration File:</emphasis> - Create a <filename>conf/machine/>machine<.conf</filename> - file. - See <filename>meta-yocto-bsp/conf/machine</filename> for sample - <filename>>machine.conf<</filename> files. - Other samples exist from other vendors such as - <filename>meta-intel</filename>, <filename>meta-ti</filename>, - and <filename>meta-freescale</filename> that have more specific machine - and tuning examples. + Instructions on how to boot the binary + images contained in the + <filename>binary</filename> directory, + if present. </para></listitem> <listitem><para> - <emphasis>Create a Kernel Recipe:</emphasis> - Create a kernel recipe in <filename>recipes-kernel/linux</filename> - either using a linux-yocto kernel with a <filename>.bbappend</filename> - file or a new custom kernel recipe file (i.e. <filename>.bb</filename> - file). - The BSP layers mentioned in the previous step also contain different - kernel examples. - You can start with the linux-yocto or use a custom kernel. - See the - "<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. + Information on any known bugs or issues + that users should know about when either + building or booting the BSP binaries. </para></listitem> </itemizedlist> - </para> - - <para role='writernotes'> - [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO - BE PROVIDED BY ENGINEERS.] - </para> - - <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></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_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_name</replaceable> + directory. + This file identifies the + <filename>meta-</filename><replaceable>bsp_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_name</replaceable><filename>.conf</filename> + files in the + <filename>meta-</filename><replaceable>bsp_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> -<!-- <para> - [ASSUMING SIMILAR ACTION OCCURS]As the [SUBCOMMAND] 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> ---> + <section id='released-bsp-recommendations'> + <title>Released BSP Recommendations</title> - <para> - Following is a complete example: + <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> + + <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 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_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;/cgit.cgi'>Source Repositories</ulink> + for these kernels. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<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'> + 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'> - [INSERT EXAMPLE - NEED EXAMPLE] + meta-xyz/recipes-core/init-ifupdown/files/interfaces </literallayout> -<!-- - <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'> + </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_CM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>" + section in the Yocto Project Concepts 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 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> + +<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> + + <para> + [INTRODUCE THE PROCEDURE AND LINK BACK TO <link linkend='bsp-layers'>BSP layer</link>. + IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET + UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.] + <itemizedlist> + <listitem><para>[PARAMETER 1]</para></listitem> + <listitem><para>[PARAMETER 2]</para></listitem> + <listitem><para>[PARAMETER 3]</para></listitem> + <listitem><para>[PARAMETER 4]</para></listitem> + <listitem><para>[PARAMETER 5]</para></listitem> + <listitem><para>[PARAMETER 6]</para></listitem> + <listitem><para>[PARAMETER 7]</para></listitem> + </itemizedlist> + </para> + + <para> + The following procedure creates a BSP layer: + <itemizedlist> + <listitem><para> + <emphasis>Create 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 Machine Configuration File:</emphasis> + Create a <filename>conf/machine/>machine<.conf</filename> + file. + See <filename>meta-yocto-bsp/conf/machine</filename> for sample + <filename>>machine.conf<</filename> files. + Other samples exist from other vendors such as + <filename>meta-intel</filename>, <filename>meta-ti</filename>, + and <filename>meta-freescale</filename> 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> + either using a linux-yocto kernel with a <filename>.bbappend</filename> + file or a new custom kernel recipe file (i.e. <filename>.bb</filename> + file). + The BSP layers mentioned in the previous step also contain different + kernel examples. + You can start with the linux-yocto or use a custom kernel. + See the + "<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> + [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO + BE PROVIDED BY ENGINEERS.] + </para> + + <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> + Following is a complete example: + <literallayout class='monospaced'> + [INSERT EXAMPLE - NEED EXAMPLE] + </literallayout> + </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 - find the layer along with other Metadata it needs. - </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-bitbake-layers-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. - - - - Options: - --version show program's version number and exit - -h, --help show this help message and exit - -D, --debug output debug information - </literallayout> - </para> - - <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 - - $ 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> + </literallayout> + Adding the layer to this file allows the build system to build the BSP and + find the layer along with other Metadata it needs. + </para> +</section> </chapter> |