documentation/dev-manual/dev-manual-cases.xml: generalized the BSP case
Because the BSP example is now in an appendix, I re-wrote this section to overview the case. (From yocto-docs rev: c0d88c6050bd17d65d8fe8c8abb227998fd4c11e) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
b67922f0c3
commit
5b8301a3b8
|
|
@ -14,6 +14,11 @@
|
|||
target hardware.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This chapter presents an overview of the primary cases.
|
||||
Supsequent appendices in the manual provide detailed explanations of the examples.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
[WRITERS NOTE: What is undetermined at this point is how much of the entire development process
|
||||
we include in this particular chapter.
|
||||
|
|
@ -52,702 +57,165 @@
|
|||
see <xref linkend='yocto-project-terms'>Yocto Project Terms</xref> in this manual.
|
||||
</note>
|
||||
|
||||
<para>
|
||||
The remainder of this section presents the basic steps to create a BSP basing it on an
|
||||
existing BSP that ships with the Yocto Project.
|
||||
You can reference <xref linkend='dev-manual-bsp-appendix'>BSP Development Case</xref>
|
||||
for a detailed example that uses the Crown Bay BSP as a base BSP from which to start.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Here are the basic steps involved in creating a BSP:
|
||||
<orderedlist>
|
||||
<listitem><para>Be sure your host development system is set up to support
|
||||
development using the Yocto Project.
|
||||
See
|
||||
<listitem><para><emphasis>Set up your host development system to support
|
||||
development using the Yocto Project</emphasis>: See
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
|
||||
The Linux Distributions</ulink> section and
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
|
||||
The Packages</ulink> section both
|
||||
in the Yocto Project Quick Start for requirements.
|
||||
You will also need a release of Yocto Project installed on the host.</para></listitem>
|
||||
<listitem><para>Choose a BSP available with Yocto Project that most closely represents
|
||||
your hardware.</para></listitem>
|
||||
<listitem><para>Get set up with a base BSP.</para></listitem>
|
||||
<listitem><para>Make a copy of the existing BSP and isolate your work by creating a layer
|
||||
for your recipes.</para></listitem>
|
||||
<listitem><para>Make configuration and recipe changes to your new BSP layer.</para></listitem>
|
||||
<listitem><para>Prepare for the build.</para></listitem>
|
||||
<listitem><para>Select and configure the kernel.</para></listitem>
|
||||
<listitem><para>Identify the machine branch.</para></listitem>
|
||||
<listitem><para>Build the image.</para></listitem>
|
||||
<listitem><para><emphasis>Establish a local copy of the Yocto Project files on your
|
||||
system</emphasis>: You need to have the Yocto Project files available on your host system.
|
||||
Having the Yocto Project files on your system gives you access to the build
|
||||
process and tools you need.
|
||||
For information on how to get these files, see the
|
||||
<xref linkend='getting-setup'>Getting Setup</xref> section in this manual.</para></listitem>
|
||||
<listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>:
|
||||
The Yocto Project ships with several BSPs that support various hardware.
|
||||
It is best to base your new BSP on an existing BSP rather than create all the
|
||||
recipes and configuration files from scratch.
|
||||
While it is possible to create everything from scratch, basing your new BSP
|
||||
on something that is close is much easier.
|
||||
Or, at a minimum, it gives you some structure with which to start.</para>
|
||||
<para>At this point you need to understand your target hardware well enough to determine which
|
||||
existing BSP it most closely matches.
|
||||
Things to consider are your hardware’s on-board features such as CPU type and graphics support.
|
||||
You should look at the README files for supported BSPs to get an idea of which one
|
||||
you could use.
|
||||
A generic Atom-based BSP to consider is the Crown Bay that does not support
|
||||
the Intel® Embedded Media Graphics Driver (EMGD).
|
||||
The remainder of this example uses that base BSP.</para>
|
||||
<para>To see the supported BSPs, go to the Yocto Project
|
||||
<ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click
|
||||
on “BSP Downloads.”</para></listitem>
|
||||
<listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having
|
||||
the BSP files on your system gives you access to the build
|
||||
process and tools you need.
|
||||
For information on how to get these files, see
|
||||
<xref linkend='getting-setup'>Getting Setup</xref> earlier in this manual.</para></listitem>
|
||||
<listitem><para><emphasis>Create your own BSP layer</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 for your BSP.
|
||||
In fact, a BSP is, in itself, a special type of layer.
|
||||
Consider an application as another example that illustrates a layer.
|
||||
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 Yocto Project build
|
||||
system knows about.</para>
|
||||
<note>The Yocto Project supports four BSPs that are part of the
|
||||
Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
|
||||
<filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
|
||||
The recipes and configurations for these four BSPs are located and dispersed
|
||||
within local Yocto Project files.
|
||||
Consequently, they are not totally isolated in the spirit of layers unless you think
|
||||
of <filename>meta-yocto</filename> as a layer itself.
|
||||
On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
|
||||
N450, and Sugar Bay are isolated.</note>
|
||||
<para>When you set up a layer for a new BSP you should follow a standard layout.
|
||||
This layout is described in the
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
|
||||
Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
|
||||
Guide.
|
||||
In the standard layout you will notice a suggested structure for recipes and
|
||||
configuration information.
|
||||
You can see the standard layout for the Crown Bay BSP in this example by examining the
|
||||
directory structure of the <filename>meta-crownbay</filename> layer inside the
|
||||
local Yocto Project files.</para></listitem>
|
||||
<listitem><para><emphasis>Make configuration and recipe 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> within the
|
||||
BSP layer.</para>
|
||||
<para>Configuration changes identify where your new layer is on the local system
|
||||
and identify which kernel you are going to use.
|
||||
Recipe changes include altering recipes (<filename>.bb</filename> files), removing
|
||||
recipes you don't use, and adding new recipes that you need to support your hardware.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
|
||||
changes to your BSP layer there remains a few things
|
||||
you need to do for the Yocto Project build system in order for it to create your image.
|
||||
You need to get the build environment ready by sourcing an environment setup script
|
||||
and you need to be sure two key configuration files are configured appropriately.</para>
|
||||
<para>The entire process for building an image is overviewed in the
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>
|
||||
Building an Image</ulink> section of the Yocto Project Quick Start.
|
||||
You might want to reference this information.</para></listitem>
|
||||
<listitem><para><emphasis>Build the image</emphasis>: The Yocto Project uses the BitBake
|
||||
tool to build images based on the type of image
|
||||
you want to create.
|
||||
You can find more information on BitBake
|
||||
<ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para>
|
||||
<para>The build process supports several types of images to satisfy different needs.
|
||||
When you issue the BitBake command you provide a “top-level” recipe that essentially
|
||||
starts the process off of building the type of image you want.</para>
|
||||
<para>[WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]</para>
|
||||
<para>You can find these recipes in the <filename>meta/recipes-core/images</filename> and
|
||||
<filename>meta/recipes-sato/images</filename> directories of your local Yocto Project
|
||||
file structure (Git repository or extracted release tarball).
|
||||
Although the recipe names are somewhat explanatory, here is a list that describes them:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Base</emphasis> – A foundational basic image without support
|
||||
for X that can be reasonably used for customization.</para></listitem>
|
||||
<listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for
|
||||
X that can be reasonably used for customization.</para></listitem>
|
||||
<listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to
|
||||
the disk of the target device.</para></listitem>
|
||||
<listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from
|
||||
a CD without having to first install something.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI.
|
||||
This image is not much more than a kernel with a shell.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for
|
||||
development work.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct
|
||||
Disk image.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> –
|
||||
A minimal image
|
||||
that has the <filename>initramfs</filename> as part of the kernel, which allows the
|
||||
system to find the first “init” program more efficiently.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support
|
||||
for the MTD utilities, which let the user interact with the MTD subsystem in
|
||||
the kernel to perform operations on flash devices.</para></listitem>
|
||||
<listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment
|
||||
and visual style that works well with mobile devices.</para></listitem>
|
||||
<listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for
|
||||
development work.</para></listitem>
|
||||
<listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct
|
||||
Disk image.</para></listitem>
|
||||
<listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem>
|
||||
<listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project
|
||||
toolchain and development libraries.</para></listitem>
|
||||
<listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct
|
||||
Disk image.</para></listitem>
|
||||
<listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live
|
||||
image.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
You can view a video presentation of the BSP creation process
|
||||
<ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>.
|
||||
You can also find supplemental information in the
|
||||
<ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
|
||||
Board Support Package (BSP) Development Guide</ulink>.
|
||||
Finally, there is wiki page write up of the example located
|
||||
<ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
|
||||
here</ulink> you might find helpful.
|
||||
</para>
|
||||
|
||||
<section id='setting-up-yocto-project'>
|
||||
<title>Setting Up Yocto Project</title>
|
||||
|
||||
<para>
|
||||
You need to have the Yocto Project files available on your host system.
|
||||
You can get files through tarball extraction or by cloning the <filename>poky</filename>
|
||||
Git repository.
|
||||
Typically, cloning the Git repository is the method to use.
|
||||
This allows you to maintain a complete history of changes and facilitates you
|
||||
contributing back to the Yocto Project.
|
||||
However, if you just want a hierarchical file structure that contains the recipes
|
||||
and metadata that let you develop you can download tarballs from the
|
||||
<ulink url='http://yoctoproject.org/download'>download page</ulink>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Regardless of the method you use this manual will refer to the resulting
|
||||
hierarchical set of files as "the local Yocto Project files."
|
||||
</para>
|
||||
|
||||
<para>
|
||||
[WRITER'S NOTE: I need to substitute correct and actual filenames for the
|
||||
1.1 release throughout this example once they become available.]
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you download a tarball you can extract it into any directory you want using the
|
||||
tar command.
|
||||
For example, the following command extracts the Yocto Project 1.1 release tarball
|
||||
into the current working directory and sets up a file structure whose top-level
|
||||
directory is named <filename>poky-1.1</filename>:
|
||||
<literallayout class='monospaced'>
|
||||
$ tar xfj poky-1.1.tar.bz2
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following transcript shows how to clone the <filename>poky</filename> Git repository
|
||||
into the current working directory.
|
||||
The command creates the repository in a directory named <filename>poky</filename>:
|
||||
<literallayout class='monospaced'>
|
||||
$ git clone git://git.yoctoproject.org/poky
|
||||
Initialized empty Git repository in /home/scottrif/poky/.git/
|
||||
remote: Counting objects: 107624, done.
|
||||
remote: Compressing objects: 100% (37128/37128), done.
|
||||
remote: Total 107624 (delta 73393), reused 99851 (delta 67287)
|
||||
Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done.
|
||||
Resolving deltas: 100% (73393/73393), done.
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Once you have the local <filename>poky</filename> Git repository set up,
|
||||
you have many development branches from which you can work.
|
||||
From inside the repository you can see the branch names and the tag names used
|
||||
in the Git repository using either of the following two commands:
|
||||
<literallayout class='monospaced'>
|
||||
$ git branch -a
|
||||
$ git tag -l
|
||||
</literallayout>
|
||||
For this example we are going to use the Yocto Project 1.1 Release,
|
||||
which maps to the <filename>1.1</filename> branch in the repository.
|
||||
These commands create a local branch named <filename>1.1</filename>
|
||||
that tracks the remote branch of the same name.
|
||||
<literallayout class='monospaced'>
|
||||
|
||||
$ cd poky
|
||||
$ git checkout -b 1.1 origin/1.1
|
||||
Switched to a new branch '1.1'
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='choosing-a-base-bsp'>
|
||||
<title>Choosing a Base BSP</title>
|
||||
|
||||
<para>
|
||||
The Yocto Project ships with several BSPs that support various hardware.
|
||||
It is best to base your new BSP on an existing BSP rather than create all the
|
||||
recipes and configuration files from scratch.
|
||||
While it is possible to create everything from scratch, basing your new BSP
|
||||
on something that is close is much easier.
|
||||
Or, at a minimum, it gives you some structure with which to start.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
At this point you need to understand your target hardware well enough to determine which
|
||||
existing BSP it most closely matches.
|
||||
Things to consider are your hardware’s on-board features such as CPU type and graphics support.
|
||||
You should look at the README files for supported BSPs to get an idea of which one
|
||||
you could use.
|
||||
A generic Atom-based BSP to consider is the Crown Bay that does not support
|
||||
the Intel® Embedded Media Graphics Driver (EMGD).
|
||||
The remainder of this example uses that base BSP.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To see the supported BSPs, go to the Yocto Project
|
||||
<ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click
|
||||
on “BSP Downloads.”
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='getting-your-base-bsp'>
|
||||
<title>Getting Your Base BSP</title>
|
||||
|
||||
<para>
|
||||
You need to have the base BSP layer on your development system.
|
||||
Like the local Yocto Project files, you can get the BSP
|
||||
layer one of two ways:
|
||||
download the BSP tarball and extract it, or set up a local Git repository that
|
||||
has the Yocto Project BSP layers.
|
||||
You should use the same method that you used to get the local Yocto Project files earlier.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are using tarball extraction, simply download the tarball for the base
|
||||
BSP you chose in the previous step and then extract it into any directory
|
||||
you choose using the tar command.
|
||||
Upon extraction, the BSP source directory (layer) will be named
|
||||
<filename>meta-<BSP_name></filename>.
|
||||
The following command extracts the Crown Bay BSP into the current directory and names it
|
||||
<filename>meta-crownbay</filename>:
|
||||
<literallayout class='monospaced'>
|
||||
$ tar xjf crownbay-noemgd-1.1.tar.bz2
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you cloned a <filename>poky</filename> Git repository
|
||||
then you need to set up a different local Git repository
|
||||
(<filename>meta-intel</filename>) for the BSP.
|
||||
The <filename>meta-intel</filename> Git repository contains all the metadata
|
||||
that supports BSP creation.
|
||||
When you set up the <filename>meta-intel</filename> Git repository you can
|
||||
set it up anywhere you want.
|
||||
We will set up the repository inside the
|
||||
<filename>poky</filename> Git repository in this example.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following transcript shows the steps to clone the <filename>meta-intel</filename>
|
||||
Git repository inside the <filename>poky</filename> Git repository created earlier in this
|
||||
example.
|
||||
<literallayout class='monospaced'>
|
||||
$cd poky
|
||||
$ git clone git://git.yoctoproject.org/meta-intel.git
|
||||
Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
|
||||
remote: Counting objects: 1325, done.
|
||||
remote: Compressing objects: 100% (1078/1078), done.
|
||||
remote: Total 1325 (delta 546), reused 85 (delta 27)
|
||||
Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done.
|
||||
Resolving deltas: 100% (546/546), done.
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Because <filename>meta-intel</filename> is its own Git repository you will want
|
||||
to be sure you are in the appropriate branch for your work.
|
||||
For this example we are going to use the <filename>1.1</filename> branch.
|
||||
<literallayout class='monospaced'>
|
||||
$ cd meta-intel
|
||||
$ git checkout -b 1.1 origin/1.1
|
||||
Switched to a new branch 'bernard'
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer'>
|
||||
<title>Making a Copy of the Base BSP to Create Your New BSP Layer</title>
|
||||
|
||||
<para>
|
||||
Now that you have the local Yocto Project files and the base BSP files you need to create a
|
||||
new layer for your BSP.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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 for your BSP.
|
||||
In fact, a BSP is, in itself, a special type of layer.
|
||||
Consider an application as another example that illustrates a layer.
|
||||
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 Yocto Project build system knows about.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
The Yocto Project supports four BSPs that are part of the
|
||||
Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
|
||||
<filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
|
||||
The recipes and configurations for these four BSPs are located and dispersed
|
||||
within local Yocto Project files.
|
||||
Consequently, they are not totally isolated in the spirit of layers unless you think
|
||||
of <filename>meta-yocto</filename> as a layer itself.
|
||||
On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
|
||||
N450, and Sugar Bay are isolated.
|
||||
</note>
|
||||
|
||||
<para>
|
||||
When you set up a layer for a new BSP you should follow a standard layout.
|
||||
This layout is described in the
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
|
||||
Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
|
||||
Guide.
|
||||
In the standard layout you will notice a suggested structure for recipes and
|
||||
configuration information.
|
||||
You can see the standard layout for the Crown Bay BSP in this example by examining the
|
||||
directory structure of the <filename>meta-crownbay</filename> layer inside the
|
||||
local Yocto Project files.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To create your BSP layer you simply copy the <filename>meta-crownbay</filename>
|
||||
layer to a new layer.
|
||||
For this example the new layer will be named <filename>meta-mymachine</filename>.
|
||||
The name must follow the BSP layer naming convention, which is
|
||||
<filename>meta-<name></filename>.
|
||||
The following example assumes your working directory is <filename>meta-intel</filename>
|
||||
inside the local Yocto Project files.
|
||||
If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting
|
||||
<filename>meta-crownbay</filename> directory structure to a location of your choice.
|
||||
Good practice for a Git repository, however, is to just copy the new layer alongside
|
||||
the existing
|
||||
BSP layers in the <filename>meta-intel</filename> Git repository:
|
||||
<literallayout class='monospaced'>
|
||||
$ cp -a meta-crownbay/ meta-mymachine
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='making-changes-to-your-bsp'>
|
||||
<title>Making Changes to Your BSP</title>
|
||||
|
||||
<para>
|
||||
Right now you have two identical BSP layers with different names:
|
||||
<filename>meta-crownbay</filename> and <filename>meta-mymachine</filename>.
|
||||
You need to change your configurations so that they work for your new BSP and
|
||||
your particular hardware.
|
||||
We will look first at the configurations, which are all done in the layer’s
|
||||
<filename>conf</filename> directory.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
First, since in this example the new BSP will not support EMGD we will get rid of the
|
||||
<filename>crownbay.conf</filename> file and then rename the
|
||||
<filename>crownbay-noemgd.conf</filename> file to <filename>mymachine.conf</filename>.
|
||||
Much of what we do in the configuration directory is designed to help the Yocto Project
|
||||
build system work with the new layer and to be able to find and use the right software.
|
||||
The following two commands result in a single machine configuration file named
|
||||
<filename>mymachine.conf</filename>.
|
||||
<literallayout class='monospaced'>
|
||||
$ rm meta-mymachine/conf/machine/crownbay.conf
|
||||
$ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \
|
||||
meta-mymachine/conf/machine/mymachine.conf
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The next step makes changes to <filename>mymachine.conf</filename> itself.
|
||||
The only changes needed for this example are changes to the comment lines.
|
||||
Here we simply substitute the Crown Bay name with an appropriate name.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note that inside the <filename>mymachine.conf</filename> is the
|
||||
<filename>PREFERRED_PROVIDER_virtual/kernel</filename> statement.
|
||||
This statement identifies the kernel that the BSP is going to use.
|
||||
In this case the BSP is using <filename>linux-yocto</filename>, which is the
|
||||
current Linux Yocto kernel based on the Linux 2.6.37 release.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The next configuration file in the new BSP layer we need to edit is <filename>layer.conf</filename>.
|
||||
This file identifies build information needed for the new layer.
|
||||
You can see the
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout-layer'>
|
||||
Layer Configuration File</ulink> section in the Board Support Packages (BSP) Development Guide
|
||||
for more information on this configuration file.
|
||||
Basically, we are changing the existing statements to work with our BSP.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The file contains these statements that reference the Crown Bay BSP:
|
||||
<literallayout class='monospaced'>
|
||||
BBFILE_COLLECTIONS += "crownbay"
|
||||
BBFILE_PATTERN_crownbay := "^${LAYERDIR}/"
|
||||
BBFILE_PRIORITY_crownbay = "6"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Simply substitute the machine string name <filename>crownbay</filename>
|
||||
with the new machine name <filename>mymachine</filename> to get the following:
|
||||
<literallayout class='monospaced'>
|
||||
BBFILE_COLLECTIONS_mymachine += "mymachine"
|
||||
BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
|
||||
BBFILE_PRIORITY_mymachine = "6"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now we will take a look at the recipes in your new layer.
|
||||
The standard BSP structure has areas for BSP, graphics, core, and kernel recipes.
|
||||
When you create a BSP you use these areas for appropriate recipes and append files.
|
||||
Recipes take the form of <filename>.bb</filename> files.
|
||||
If you want to leverage the existing recipes the Yocto Project build system uses
|
||||
but change those recipes you can use <filename>.bbappend</filename> files.
|
||||
All new recipes and append files for your layer must go in the layer’s
|
||||
<filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>,
|
||||
<filename>recipes-core</filename>, and
|
||||
<filename>recipes-graphics</filename> directories.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
First, let's look at <filename>recipes-bsp</filename>.
|
||||
For this example we are not adding any new BSP recipes.
|
||||
And, we only need to remove the formfactor we do not want and change the name of
|
||||
the remaining one that doesn't support EMGD.
|
||||
These commands take care of the <filename>recipes-bsp</filename> recipes:
|
||||
<literallayout class='monospaced'>
|
||||
$ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd*
|
||||
$ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \
|
||||
meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now let's look at <filename>recipes-graphics</filename>.
|
||||
For this example we want to remove anything that supports EMGD and
|
||||
be sure to rename remaining directories appropriately.
|
||||
The following commands clean up the <filename>recipes-graphics</filename> directory:
|
||||
<literallayout class='monospaced'>
|
||||
$ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd*
|
||||
$ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay
|
||||
$ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \
|
||||
meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
At this point the <filename>recipes-graphics</filename> directory just has files that
|
||||
support Video Electronics Standards Association (VESA) graphics modes and not EMGD.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now let's look at changes in <filename>recipes-core</filename>.
|
||||
The file <filename>task-core-tools.bbappend</filename> in
|
||||
<filename>recipes-core/tasks</filename> appends the similarly named recipe
|
||||
located in the local Yocto Project files at
|
||||
<filename>meta/recipes-core/tasks</filename>.
|
||||
The "append" file in our layer right now is Crown Bay-specific and supports
|
||||
EMGD and non-EMGD.
|
||||
Here are the contents of the file:
|
||||
<literallayout class='monospaced'>
|
||||
RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap"
|
||||
RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>RRECOMMENDS</filename> statements list packages that
|
||||
extend usability.
|
||||
The first <filename>RRECOMMENDS</filename> statement can be removed, while the
|
||||
second one can be changed to reflect <filename>meta-mymachine</filename>:
|
||||
<literallayout class='monospaced'>
|
||||
RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Finally, let's look at <filename>recipes-kernel</filename> changes.
|
||||
Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined
|
||||
earlier in the <filename>mymachine.conf</filename>.
|
||||
The recipe for that kernel is not located in the
|
||||
BSP layer but rather in the local Yocto Project files at
|
||||
<filename>meta/recipes-kernel/linux</filename> and is
|
||||
named <filename>linux-yocto-2.6.37.bb</filename>.
|
||||
The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename>
|
||||
statements point to the exact commits used by the Yocto Project development team
|
||||
in their source repositories that identify the right kernel for our hardware.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
However, in the <filename>meta-mymachine</filename> layer in
|
||||
<filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename>
|
||||
file named <filename>linux-yocto-2.6.37.bbappend</filename> that
|
||||
is appended to the recipe of the same name in <filename>meta/recipes-kernel/link</filename>.
|
||||
Thus, the <filename>SRCREV</filename> statements in the "append" file override
|
||||
the more general statements found in <filename>meta</filename>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>SRCREV</filename> statements in the "append" file currently identify
|
||||
the kernel that supports the Crown Bay BSP with and without EMGD support.
|
||||
Here are the statements:
|
||||
<literallayout class='monospaced'>
|
||||
SRCREV_machine_pn-linux-yocto_crownbay ?= \
|
||||
"372c0ab135978bd8ca3a77c88816a25c5ed8f303"
|
||||
SRCREV_meta_pn-linux-yocto_crownbay ?= \
|
||||
"d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
|
||||
|
||||
SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= \
|
||||
"372c0ab135978bd8ca3a77c88816a25c5ed8f303"
|
||||
SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \
|
||||
"d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You will notice that there are two pairs of <filename>SRCREV</filename> statements.
|
||||
The top pair identifies the kernel that supports
|
||||
EMGD, which we don’t care about in this example.
|
||||
The bottom pair identifies the kernel that we will use:
|
||||
<filename>linux-yocto</filename>.
|
||||
At this point though, the unique commit strings all are still associated with
|
||||
Crown Bay and not <filename>meta-mymachine</filename>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To fix this situation in <filename>linux-yocto-2.6.37.bbappend</filename>
|
||||
we delete the two <filename>SRCREV</filename> statements that support
|
||||
EMGD (the top pair).
|
||||
We also change the remaining pair to specify <filename>mymachine</filename>
|
||||
and insert the commit identifiers to identify the kernel in which we
|
||||
are interested, which will be based on the <filename>atom-pc-standard</filename>
|
||||
kernel.
|
||||
Here are the final <filename>SRCREV</filename> statements:
|
||||
<literallayout class='monospaced'>
|
||||
SRCREV_machine_pn-linux-yocto-_mymachine ?= \
|
||||
"fce17f046d3756045e4dfb49221d1cf60fcae329"
|
||||
SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \
|
||||
"84f1a422d7e21fbc23a687035bdf9d42471f19e0"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are familiar with Git repositories you probably won’t have trouble locating the
|
||||
exact commit strings in the Yocto Project source repositories you need to change
|
||||
the <filename>SRCREV</filename> statements.
|
||||
You can find all the <filename>machine</filename> and <filename>meta</filename>
|
||||
branch points (commits) for the <filename>linux-yocto-2.6.37</filename> kernel
|
||||
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37'>here</ulink>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you need a little more assistance after going to the link then do the following:
|
||||
<orderedlist>
|
||||
<listitem><para>Expand the list of branches by clicking <filename>[…]</filename></para></listitem>
|
||||
<listitem><para>Click on the <filename>yocto/standard/common-pc/atom-pc</filename>
|
||||
branch</para></listitem>
|
||||
<listitem><para>Click on the commit column header to view the top commit</para></listitem>
|
||||
<listitem><para>Copy the commit string for use in the
|
||||
<filename>linux-yocto-2.6.37.bbappend</filename> file</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For the <filename>SRCREV</filename> statement that points to the <filename>meta</filename>
|
||||
branch use the same procedure except expand the <filename>meta</filename>
|
||||
branch in step 2 above.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also in the <filename>linux-yocto-2.6.37.bbappend</filename> file are
|
||||
<filename>COMPATIBLE_MACHINE</filename>, <filename>KMACHINE</filename>,
|
||||
and <filename>KERNEL_FEATURES</filename> statements.
|
||||
Two sets of these exist: one set supports EMGD and one set does not.
|
||||
Because we are not interested in supporting EMGD those three can be deleted.
|
||||
The remaining three must be changed so that <filename>mymachine</filename> replaces
|
||||
<filename>crownbay-noemgd</filename> and <filename>crownbay</filename>.
|
||||
Here is the final <filename>linux-yocto-2.6.37.bbappend</filename> file after all
|
||||
the edits:
|
||||
<literallayout class='monospaced'>
|
||||
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
|
||||
|
||||
COMPATIBLE_MACHINE_mymachine = "mymachine"
|
||||
KMACHINE_mymachine = "yocto/standard/mymachine"
|
||||
KERNEL_FEATURES_append_mymachine += " cfg/smp.scc"
|
||||
|
||||
SRCREV_machine_pn-linux-yocto_mymachine ?= \
|
||||
"fce17f046d3756045e4dfb49221d1cf60fcae329"
|
||||
SRCREV_meta_pn-linux-yocto_mymachine ?= \
|
||||
"84f1a422d7e21fbc23a687035bdf9d42471f19e0"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In summary, the edits to the layer’s recipe files result in removal of any files and
|
||||
statements that do not support your targeted hardware in addition to the inclusion
|
||||
of any new recipes you might need.
|
||||
In this example, it was simply a matter of ridding the new layer
|
||||
<filename>meta-machine</filename> of any code that supported the EMGD features
|
||||
and making sure we were identifying the kernel that supports our example, which
|
||||
is the <filename>atom-pc-standard</filename> kernel.
|
||||
We did not introduce any new recipes to the layer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Finally, it is also important to update the layer’s <filename>README</filename>
|
||||
file so that the information in it reflects your BSP.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='preparing-for-the-build'>
|
||||
<title>Preparing for the Build</title>
|
||||
|
||||
<para>
|
||||
Once you have made all the changes to your BSP layer there remains a few things
|
||||
you need to do for the Yocto Project build system in order for it to create your image.
|
||||
You need to get the build environment ready by sourcing an environment setup script
|
||||
and you need to be sure two key configuration files are configured appropriately.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The entire process for building an image is overviewed in the
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>
|
||||
Building an Image</ulink> section of the Yocto Project Quick Start.
|
||||
You might want to reference this information.
|
||||
The remainder of this section will apply to our example of the
|
||||
<filename>meta-mymachine</filename> layer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To get ready to build your image that uses the new layer you need to do the following:
|
||||
<orderedlist>
|
||||
<listitem><para>Get the environment ready for the build by sourcing the environment
|
||||
script.
|
||||
The environment script is in the top-level of the local Yocto Project files
|
||||
directory structure.
|
||||
The script has the string
|
||||
<filename>init-build-env</filename> in the file’s name.
|
||||
For this example, the following command gets the build environment ready:
|
||||
<literallayout class='monospaced'>
|
||||
$ source oe-init-build-env yocto-build
|
||||
</literallayout>
|
||||
When you source the script a build directory is created in the current
|
||||
working directory.
|
||||
In our example we were in the <filename>poky</filename> directory.
|
||||
Thus, entering the previous command created the <filename>yocto-build</filename> directory.
|
||||
If you do not provide a name for the build directory it defaults to
|
||||
<filename>build</filename>.
|
||||
The <filename>yocot-build</filename> directory contains a
|
||||
<filename>conf</filename> directory that has
|
||||
two configuration files you will need to check: <filename>bblayers.conf</filename>
|
||||
and <filename>local.conf</filename>.</para></listitem>
|
||||
<listitem><para>Check and edit the resulting <filename>local.conf</filename> file.
|
||||
This file minimally identifies the machine for which to build the image by
|
||||
configuring the <filename>MACHINE</filename> variable.
|
||||
For this example you must set the variable to mymachine as follows:
|
||||
<literallayout class='monospaced'>
|
||||
MACHINE ??= “mymachine”
|
||||
</literallayout>
|
||||
You should also be sure any other variables in which you are interested are set.
|
||||
Some variables to consider are <filename>BB_NUMBER_THREADS</filename>
|
||||
and <filename>PARALLEL_MAKE</filename>, both of which can greatly reduce your build time
|
||||
if you are using a multi-threaded development system (e.g. values of
|
||||
<filename>8</filename> and <filename>j 6</filename>, respectively are optimal
|
||||
for a development machine that has four available cores).</para></listitem>
|
||||
<listitem><para>Update the <filename>bblayers.conf</filename> file so that it includes
|
||||
the path to your new BSP layer.
|
||||
In this example you need to include the pathname to <filename>meta-mymachine</filename>.
|
||||
For this example the
|
||||
<filename>BBLAYERS</filename> variable in the file would need to include the following path:
|
||||
<literallayout class='monospaced'>
|
||||
$HOME/poky/meta-intel/meta-mymachine
|
||||
</literallayout></para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The appendix
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-variables-glos'>
|
||||
Reference: Variables Glossary</ulink> in the Yocto Project Reference Manual has more information
|
||||
on configuration variables.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='building-the-image'>
|
||||
<title>Building the Image</title>
|
||||
|
||||
<para>
|
||||
The Yocto Project uses the BitBake tool to build images based on the type of image
|
||||
you want to create.
|
||||
You can find more information on BitBake
|
||||
<ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The build process supports several types of images to satisfy different needs.
|
||||
When you issue the BitBake command you provide a “top-level” recipe that essentially
|
||||
starts the process off of building the type of image you want.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
[WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can find these recipes in the <filename>meta/recipes-core/images</filename> and
|
||||
<filename>meta/recipes-sato/images</filename> directories of your local Yocto Project
|
||||
file structure (Git repository or extracted release tarball).
|
||||
Although the recipe names are somewhat explanatory, here is a list that describes them:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Base</emphasis> – A foundational basic image without support
|
||||
for X that can be reasonably used for customization.</para></listitem>
|
||||
<listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for
|
||||
X that can be reasonably used for customization.</para></listitem>
|
||||
<listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to
|
||||
the disk of the target device.</para></listitem>
|
||||
<listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from
|
||||
a CD without having to first install something.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI.
|
||||
This image is not much more than a kernel with a shell.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for
|
||||
development work.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct Disk image.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> – A minimal image
|
||||
that has the <filename>initramfs</filename> as part of the kernel, which allows the
|
||||
system to find the first “init” program more efficiently.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem>
|
||||
<listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support
|
||||
for the MTD utilities, which let the user interact with the MTD subsystem in
|
||||
the kernel to perform operations on flash devices.</para></listitem>
|
||||
<listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment
|
||||
and visual style that works well with mobile devices.</para></listitem>
|
||||
<listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for
|
||||
development work.</para></listitem>
|
||||
<listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct Disk image.</para></listitem>
|
||||
<listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem>
|
||||
<listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project
|
||||
toolchain and development libraries.</para></listitem>
|
||||
<listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct
|
||||
Disk image.</para></listitem>
|
||||
<listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live image.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The remainder of this section applies to our example of the <filename>meta-mymachine</filename> layer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To build the image for our <filename>meta-mymachine</filename> BSP enter the following command
|
||||
from the same shell from which you ran the setup script.
|
||||
You should run the <filename>bitbake</filename> command without any intervening shell commands.
|
||||
For example, moving your working directory around could cause problems.
|
||||
Here is the command for this example:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake –k core-image-sato-live
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This command specifies an image that has Sato support and that can be run from a USB device or
|
||||
from a CD without having to first install anything.
|
||||
The build process takes significant time and includes thousands of tasks, which are reported
|
||||
at the console.
|
||||
If the build results in any type of error you should check for misspellings in the
|
||||
files you changed or problems with your host development environment such as missing packages.
|
||||
</para>
|
||||
</section>
|
||||
<para>
|
||||
You can view a video presentation of the BSP creation process
|
||||
<ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>.
|
||||
You can also find supplemental information in the
|
||||
<ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
|
||||
Board Support Package (BSP) Development Guide</ulink>.
|
||||
Finally, there is wiki page write up of the example located
|
||||
<ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
|
||||
here</ulink> you might find helpful.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='modifying-a-kernel-kernel-example'>
|
||||
|
|
@ -883,9 +351,9 @@
|
|||
|
||||
<para>
|
||||
You need to have the Yocto Project files available on your host system.
|
||||
The process is identical to that described in getting the files in section
|
||||
<xref linkend='setting-up-yocto-project'>"Setting Up Yocto Project"</xref> for
|
||||
the BSP development case.
|
||||
The process is identical to that described in the
|
||||
<xref linkend='getting-setup'>"Getting Setup"</xref> section earlier in this
|
||||
manual.
|
||||
Be sure to either set up a local Git repository for <filename>poky</filename>
|
||||
or download and unpack the Yocto Project release tarball.
|
||||
</para>
|
||||
|
|
|
|||
Loading…
Reference in New Issue