summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-06-14 10:51:45 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-06-29 14:59:24 +0100
commit7082a56c9568730abcff359809ea7732cf5df440 (patch)
tree666ffccd47e8a621d1f9bf8ee04034737b6dc4b6
parent49198215729f92e4dcd7015e88fb416b1e5df830 (diff)
downloadpoky-7082a56c9568730abcff359809ea7732cf5df440.tar.gz
poky-7082a56c9568730abcff359809ea7732cf5df440.tar.bz2
poky-7082a56c9568730abcff359809ea7732cf5df440.zip
documentation/dev-manual/dev-manual-bsp-appendix.xml: 1.1.2 variables and updates
First pass at implementing the poky.ent variables. Also, changed text in areas to better match what is in master. I left any example specific stuff alone for the most part. (From yocto-docs rev: 2b5d3ba8ee877eb55b9c052e0f194b37aa68c76a) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-bsp-appendix.xml212
1 files changed, 124 insertions, 88 deletions
diff --git a/documentation/dev-manual/dev-manual-bsp-appendix.xml b/documentation/dev-manual/dev-manual-bsp-appendix.xml
index 6850224e38..74d5406f4b 100644
--- a/documentation/dev-manual/dev-manual-bsp-appendix.xml
+++ b/documentation/dev-manual/dev-manual-bsp-appendix.xml
@@ -1,12 +1,13 @@
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<appendix id='dev-manual-bsp-appendix'>
<title>BSP Development Example</title>
<para>
- This appendix provides a complete BSP example.
+ This appendix provides a complete BSP development example.
The example assumes the following:
<itemizedlist>
<listitem><para>No previous preparation or use of the Yocto Project.</para></listitem>
@@ -31,47 +32,77 @@
The following paragraphs describe both methods.
For additional information, see the bulleted item
"<link linkend='local-yp-release'>Yocto Project Release</link>".
- </para>
+ </para>
<para>
As mentioned, one way to get the Yocto Project files is to use Git to clone the
- <filename>poky</filename> repository:
+ <filename>poky</filename> repository.
+ These commands create a local copy of the Git repository.
+ By default, the top-level directory of the repository is named <filename>poky</filename>:
<literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/poky
$ cd poky
</literallayout>
- Alternatively, you can start with the downloaded Poky "edison" tarball:
+ Alternatively, you can start with the downloaded Poky "&DISTRO_NAME;" tarball.
+ These commands unpack the tarball into a Yocto Project File directory structure.
+ By default, the top-level directory of the file structure is named
+ <filename>&YOCTO_POKY;</filename>:
<literallayout class='monospaced'>
- $ tar xfj poky-edison-6.0.1.tar.bz2
- $ cd poky
+ $ tar xfj &YOCTO_POKY_TARBALL;
+ $ cd &YOCTO_POKY;
</literallayout>
- <note>If you're using the tarball method, you can ignore all the following steps that
+ <note><para>If you're using the tarball method, you can ignore all the following steps that
ask you to carry out Git operations.
You already have the results of those operations
- in the form of the edison release tarballs.
+ in the form of the &DISTRO_NAME; release tarballs.
Consequently, there is nothing left to do other than extract those tarballs into the
- proper locations.</note>
+ proper locations.</para>
+
+ <para>Once you expand the released tarball, you have a snapshot of the Git repository
+ that represents a specific release.
+ Fundamentally, this is different than having a local copy of the Yocto Project
+ Git repository.
+ Given the tarball method, changes you make are building on top of a release.
+ With the Git repository method you have the ability to track development
+ and keep changes in revision control.</para></note>
</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:
+ With the local <filename>poky</filename> Git repository set up,
+ you have all the development branches available to you from which you can work.
+ Next, you need to be sure that your local repository reflects the exact
+ release in which you are interested.
+ From inside the repository you can see the development branches that represent
+ areas of development that have diverged from the main (master) branch
+ at some point, such as a branch to track a maintenance release's development.
+ You can also see the tag names used to mark snapshots of stable releases or
+ points in the repository.
+ Use the following commands to list out the branches and the tags in the repository,
+ respectively.
<literallayout class='monospaced'>
$ git branch -a
$ git tag -l
</literallayout>
- For this example we are going to use the Yocto Project 1.1.1 Release, which is code
- named "edison".
- These commands create a local branch named <filename>edison</filename>
- that tracks the remote branch of the same name.
+ For this example, we are going to use the Yocto Project &DISTRO; Release, which is code
+ named "&DISTRO_NAME;".
+ To make sure we have a local area (branch in Git terms) on our machine that
+ reflects the &DISTRO; release, we can use the following commands:
<literallayout class='monospaced'>
- $ git checkout -b edison origin/edison
- Switched to a new branch 'edison'
+ $ cd ~/poky
+ $ git fetch --tags
+ $ git checkout &DISTRO_NAME;-&POKYVERSION; -b &DISTRO_NAME;
+ Switched to a new branch '&DISTRO_NAME;'
</literallayout>
+ The <filename>git fetch --tags</filename> is somewhat redundant since you just set
+ up the repository and should have all the tags.
+ The <filename>fetch</filename> command makes sure all the tags are available in your
+ local repository.
+ The Git <filename>checkout</filename> command with the <filename>-b</filename> option
+ creates a local branch for you named <filename>&DISTRO_NAME;</filename>.
+ Your local branch begins in the same state as the Yocto Project &DISTRO; released tarball
+ marked with the <filename>&DISTRO_NAME;-&POKYVERSION;</filename> tag in the source repositories.
</para>
-</section>
+</section>
<section id='choosing-a-base-bsp-app'>
<title>Choosing a Base BSP</title>
@@ -100,7 +131,7 @@
<para>
You need to have the base BSP layer on your development system.
Similar to the local Yocto Project files, you can get the BSP
- layer a couple of different ways:
+ layer in couple of different 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.
@@ -113,8 +144,8 @@
<filename>meta-intel</filename> contained within the <filename>poky</filename>
parent directory.
The following steps will automatically create the
- <filename>meta-intel</filename> directory and the contained meta-crownbay
- starting point in both the Git and the tarball cases.
+ <filename>meta-intel</filename> directory and the contained
+ <filename>meta-crownbay</filename> starting point in both the Git and the tarball cases.
</para>
<para>
@@ -125,12 +156,16 @@
$ git clone git://git.yoctoproject.org/meta-intel.git
$ cd meta-intel
</literallayout>
- Alternatively, you can start with the downloaded <filename>meta-intel</filename>
- edison tarball.
+ Alternatively, you can start with the downloaded Crown Bay tarball.
+ You can download the &DISTRO_NAME; version of the BSP tarball from the
+ <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink> page of the
+ Yocto Project website.
+ Here is the specific link for the tarball needed for this example:
+ <ulink url='&YOCTO_MACHINES_DL_URL;/crownbay-noemgd/crownbay-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2'></ulink>.
Again, be sure that you are already in the <filename>poky</filename> directory
- as described previously:
+ as described previously before installing the tarball:
<literallayout class='monospaced'>
- $ tar xfj crownbay-noemgd-edison-6.0.1.tar.bz2
+ $ tar xfj crownbay-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2
$ cd meta-intel
</literallayout>
</para>
@@ -139,15 +174,16 @@
The <filename>meta-intel</filename> directory contains all the metadata
that supports BSP creation.
If you're using the Git method, the following
- step will switch to the edison metadata.
+ step will switch to the &DISTRO_NAME; metadata.
If you're using the tarball method, you already have the correct metadata and can
skip to the next step.
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>edison</filename> branch.
+ For this example we are going to use the <filename>&DISTRO_NAME;</filename> branch.
<literallayout class='monospaced'>
- $ git checkout -b edison origin/edison
- Switched to a new branch 'edison'
+ $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+ Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
+ Switched to a new branch '&DISTRO_NAME;'
</literallayout>
</para>
</section>
@@ -234,10 +270,8 @@
<filename>meta-mymachine/conf/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.1/bsp-guide/bsp-guide.html#bsp-filelayout-layer'>Layer Configuration File</ulink>" section in
- <ulink url='http://www.yoctoproject.org/docs/1.1.1/bsp-guide/bsp-guide.html'>The Board
- Support Packages (BSP) Development Guide</ulink>
- for more information on this configuration file.
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#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>
@@ -268,7 +302,8 @@
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.
+ Recipes take the form of <filename>.bb</filename> files, while append files take
+ the form of <filename>.bbappend</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
@@ -278,7 +313,7 @@
</para>
<section id='changing-recipes-bsp'>
- <title>Changing <filename>recipes-bsp</filename></title>
+ <title>Changing&nbsp;&nbsp;<filename>recipes-bsp</filename></title>
<para>
First, let's look at <filename>recipes-bsp</filename>.
@@ -295,7 +330,7 @@
</section>
<section id='changing-recipes-graphics'>
- <title>Changing <filename>recipes-graphics</filename></title>
+ <title>Changing&nbsp;&nbsp;<filename>recipes-graphics</filename></title>
<para>
Now let's look at <filename>recipes-graphics</filename>.
@@ -316,7 +351,7 @@
</section>
<section id='changing-recipes-core'>
- <title>Changing <filename>recipes-core</filename></title>
+ <title>Changing&nbsp;&nbsp;<filename>recipes-core</filename></title>
<para>
Now let's look at changes in <filename>recipes-core</filename>.
@@ -324,7 +359,7 @@
<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
+ 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'>
@@ -345,7 +380,7 @@
</section>
<section id='changing-recipes-kernel'>
- <title>Changing <filename>recipes-kernel</filename></title>
+ <title>Changing&nbsp;&nbsp;<filename>recipes-kernel</filename></title>
<para>
Finally, let's look at <filename>recipes-kernel</filename> changes.
@@ -368,15 +403,18 @@
However, in the <filename>meta-mymachine</filename> layer in
<filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename>
file named <filename>linux-yocto_3.0.bbappend</filename> that
- is appended to the recipe of the same name in <filename>meta/recipes-kernel/linux</filename>.
- Thus, the <filename>SRCREV</filename> statements in the "append" file override
+ appends information to the recipe of the same name in <filename>meta/recipes-kernel/linux</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 <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:
+ Here are the statements:
+ <note>The commit ID strings used in this manual might not match the actual commit
+ ID strings found in the <filename>linux-yocto_3.0.bbappend</filename> file.
+ For the example, this difference does not matter.</note>
<literallayout class='monospaced'>
SRCREV_machine_pn-linux-yocto_crownbay ?= \
"2247da9131ea7e46ed4766a69bb1353dba22f873"
@@ -408,11 +446,11 @@
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.
- In this case, because we're working with the edison branch of everything, we
+ In this case, because we're working with the &DISTRO_NAME; branch of everything, we
need to use the <filename>SRCREV</filename> values for the atom-pc branch
- that are associated with the edison release.
+ that are associated with the &DISTRO_NAME; release.
To find those values, we need to find the <filename>SRCREV</filename>
- values that edison uses for the atom-pc branch, which we find in the
+ values that &DISTRO_NAME; uses for the atom-pc branch, which we find in the
<filename>poky/meta-yocto/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>
file.
</para>
@@ -423,9 +461,7 @@
The meta <filename>SRCREV</filename> isn't specified in this file, so it must be
specified in the base kernel recipe in the
<filename>poky/meta/recipes-kernel/linux/linux-yocto_3.0.bb</filename>
- file, in the <filename>SRCREV_meta variable</filename> found there.
- It happens to be the same as the value we already inherited from the
- <filename>meta-crownbay</filename> BSP.
+ file, in the <filename>SRCREV_meta</filename> variable found there.
Here are the final <filename>SRCREV</filename> statements:
<literallayout class='monospaced'>
SRCREV_machine_pn-linux-yocto_mymachine ?= \
@@ -437,8 +473,8 @@
<para>
In this example, we're using the <filename>SRCREV</filename> values we
- found already captured in the edison release because we're creating a BSP based on
- edison.
+ found already captured in the &DISTRO_NAME; release because we're creating a BSP based on
+ &DISTRO_NAME;.
If, instead, we had based our BSP on the master branches, we would want to use
the most recent <filename>SRCREV</filename> values taken directly from the kernel repo.
We will not be doing that for this example.
@@ -448,7 +484,7 @@
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-3.0</filename> kernel at
- <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-3.0'></ulink>.
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/linux-yocto-3.0'></ulink>.
</para>
<para>
@@ -477,12 +513,12 @@
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>.
- Because we are using the atom-pc branch for this new BSP, we can also find
- the exact branch we need for the KMACHINE variable in our new BSP from the value
+ Because we are using the <filename>atom-pc</filename> branch for this new BSP, we can also find
+ the exact branch we need for the <filename>KMACHINE</filename> variable in our new BSP from the value
we find in the
<filename>poky/meta-yocto/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>
file we looked at in a previous step.
- In this case, the value we want is in the KMACHINE_atom-pc variable in that file.
+ In this case, the value we want is in the <filename>KMACHINE_atom-pc</filename> variable in that file.
Here is the final <filename>linux-yocto_3.0.bbappend</filename> file after all
the edits:
<literallayout class='monospaced'>
@@ -509,7 +545,7 @@
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
+ <filename>meta-mymachine</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.
@@ -544,7 +580,7 @@
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
+ The <filename>yocto-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>
@@ -558,15 +594,17 @@
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>
+ if your development system supports multiple cores.
+ For development systems that support multiple cores, a good rule of thumb is to set
+ both the <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
+ variables to twice the number of cores your system supports.</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:
+ both the path to your new BSP layer and the path to the
+ <filename>meta-intel</filename> layer.
+ In this example, you need to include both these paths as part of the
+ <filename>BBLAYERS</filename> variable:
<literallayout class='monospaced'>
+ $HOME/poky/meta-intel
$HOME/poky/meta-intel/meta-mymachine
</literallayout></para></listitem>
</orderedlist>
@@ -574,7 +612,7 @@
<para>
The appendix
- <ulink url='http://www.yoctoproject.org/docs/1.1.1/poky-ref-manual/poky-ref-manual.html#ref-variables-glos'>
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>
Reference: Variables Glossary</ulink> in the Yocto Project Reference Manual has more information
on configuration variables.
</para>
@@ -607,7 +645,7 @@
Finally, once you have an image, you can try booting it from a device
(e.g. a USB device).
To prepare a bootable USB device, insert a USB flash drive into your build system and
- copy the <filename>.hddimage</filename>, located in the
+ copy the <filename>.hddimg</filename> file, located in the
<filename>poky/build/tmp/deploy/images</filename>
directory after a successful build to the flash drive.
Assuming the USB flash drive takes device <filename>/dev/sdc</filename>,
@@ -625,10 +663,26 @@
Insert the device
into a bootable USB socket on the target, and power it on.
The system should boot to the Sato graphical desktop.
+ <footnote><para>Because
+ this new image is not in any way tailored to the system you're
+ booting it on, which is assumed to be some sort of atom-pc (netbook) system for this
+ example, it might not be completely functional though it should at least boot to a text
+ prompt.
+ Specifically, it might fail to boot into graphics without some tweaking.
+ If this ends up being the case, a possible next step would be to replace the
+ <filename>mymachine.conf</filename>
+ contents with the contents of <filename>atom-pc.conf</filename> and replace
+ <filename>xorg.conf</filename> with <filename>atom-pc xorg.conf</filename>
+ in <filename>meta-yocto</filename> and see if it fares any better.
+ In any case, following the previous steps will give you a buildable image that
+ will probably boot on most systems.
+ Getting things working like you want
+ them to for your hardware will normally require some amount of experimentation with
+ configuration settings.</para></footnote>
</para>
<para>
- For reference, the sato image produced by the previous steps for edison
+ For reference, the sato image produced by the previous steps for &DISTRO_NAME;
should look like the following in terms of size.
If your sato image is much different from this,
you probably made a mistake in one of the above steps:
@@ -643,24 +697,6 @@
also provides some suggestions for things to try if booting fails and produces
strange error messages.</note>
</para>
-
- <para>
- Because this new image is not in any way tailored to the system you're
- booting it on, which is assumed to be some sort of atom-pc (netbook) system for this
- example, it might not be completely functional though it should at least boot to a text
- prompt.
- Specifically, it might fail to boot into graphics without some tweaking.
- If this ends up being the case, a possible next step would be to replace the
- <filename>mymachine.conf</filename>
- contents with the contents of <filename>atom-pc.conf</filename> and replace
- <filename>xorg.conf</filename> with <filename>atom-pc xorg.conf</filename>
- in <filename>meta-yocto</filename> and see if it fares any better.
- In any case, following the previous steps should
- probably give you a buildable and bootable image.
- Getting things working like you want
- them to for your hardware will normally require some amount of experimentation with
- configuration settings.
- </para>
</section>
</appendix>