diff --git a/documentation/dev-manual/dev-manual-bsp-appendix.xml b/documentation/dev-manual/dev-manual-bsp-appendix.xml
deleted file mode 100644
index a4de731dfa..0000000000
--- a/documentation/dev-manual/dev-manual-bsp-appendix.xml
+++ /dev/null
@@ -1,713 +0,0 @@
- %poky; ] >
-
-
-
-BSP Development Example
-
-
- This appendix provides a complete BSP development example.
- The example assumes the following:
-
- No previous preparation or use of the Yocto Project.
- Use of the Fish River Island 2 Board Support Package (BSP) as a "base" BSP from
- which to work.
- The example begins with the Fish River Island 2 BSP as the starting point
- but ends by building a new 'atom-pc' BSP, which was based on the Fish River Island 2 BSP.
-
- Shell commands assume bash
- Example was developed on an Intel-based Core i7 platform running
- Ubuntu 10.04 LTS released in April of 2010.
-
-
-
-
- Getting Local Source Files and BSP Files
-
-
- You need to have the Source Directory
- available on your host system.
- You can set up this directory through tarball extraction or by cloning the
- poky Git repository.
- The following paragraphs describe both methods.
- For additional information, see the bulleted item
- "Yocto Project Release".
-
-
-
- As mentioned, one way to set up the Source Directory is to use Git to clone the
- poky repository.
- These commands create a local copy of the Git repository.
- By default, the top-level directory of the repository is named poky:
-
- $ git clone git://git.yoctoproject.org/poky
- $ cd poky
-
- Alternatively, you can start with the downloaded Poky "&DISTRO_NAME;" tarball.
- These commands unpack the tarball into a Source Directory structure.
- By default, the top-level directory of the Source Directory is named
- &YOCTO_POKY;:
-
- $ tar xfj &YOCTO_POKY_TARBALL;
- $ cd &YOCTO_POKY;
-
- 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 &DISTRO_NAME; release tarballs.
- Consequently, there is nothing left to do other than extract those tarballs into the
- proper locations.
-
- 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 Poky 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.
- See the
- "Repositories, Tags, and Branches" section
- for more discussion around these differences.
-
-
-
- With the local poky 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.
-
- $ git branch -a
- $ git tag -l
-
- 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:
-
- $ cd ~/poky
- $ git fetch --tags
- $ git checkout -b &DISTRO_NAME;-&POKYVERSION; origin/&DISTRO_NAME;
- Switched to a new branch '&DISTRO_NAME;-&POKYVERSION;'
-
- The git fetch --tags is somewhat redundant since you just set
- up the repository and should have all the tags.
- The fetch command makes sure all the tags are available in your
- local repository.
- The Git checkout command with the -b option
- creates a local branch for you named &DISTRO_NAME;-&POKYVERSION;.
- Your local branch begins in the same state as the Yocto Project &DISTRO; released tarball
- marked with the &DISTRO_NAME;-&POKYVERSION; tag in the source repositories.
-
-
-
-
- Choosing a Base BSP
-
-
- For this example, the base BSP is the Intel
- Atom Processor E660 with Intel Platform
- Controller Hub EG20T Development Kit, which is otherwise referred to as "Fish River Island 2."
- The BSP layer is meta-fri2.
- The base BSP is simply the BSP
- we will be using as a starting point, so don't worry if you don't actually have Fish River Island 2
- hardware.
- The remainder of the example transforms the base BSP into a BSP that should be
- able to boot on generic atom-pc (netbook) hardware.
-
-
-
- For information on how to choose a base BSP, see
- "Developing a Board Support Package (BSP)".
-
-
-
-
- Getting Your Base BSP
-
-
- You need to have the base BSP layer on your development system.
- Similar to the local Source Directory,
- you can get the BSP
- layer in a couple of different ways:
- download the BSP tarball and extract it, or set up a local Git repository that
- has the BSP layers.
- You should use the same method that you used to set up the Source Directory earlier.
- See "Getting Setup" for information on how to get
- the BSP files.
-
-
-
- This example assumes the BSP layer will be located within a directory named
- meta-intel contained within the poky
- parent directory.
- The following steps will automatically create the
- meta-intel directory and the contained
- meta-fri2 starting point in both the Git and the tarball cases.
-
-
-
- If you're using the Git method, you could do the following to create
- the starting layout after you have made sure you are in the poky
- directory created in the previous steps:
-
- $ git clone git://git.yoctoproject.org/meta-intel.git
- $ cd meta-intel
-
- Alternatively, you can start with the downloaded Fish River Island 2 tarball.
- You can download the &DISTRO_NAME; version of the BSP tarball from the
- Downloads page of the
- Yocto Project website.
- Here is the specific link for the tarball needed for this example:
- .
- Again, be sure that you are already in the poky directory
- as described previously before installing the tarball:
-
- $ tar xfj fri2-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2
- $ cd meta-intel
-
-
-
-
- The meta-intel directory contains all the metadata
- that supports BSP creation.
- If you're using the Git method, the following
- 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 meta-intel 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 &DISTRO_NAME;
- branch.
-
- $ git checkout -b &DISTRO_NAME;-&POKYVERSION; origin/&DISTRO_NAME;
- Branch &DISTRO_NAME;-&POKYVERSION; set up to track remote branch &DISTRO_NAME; from origin.
- Switched to a new branch '&DISTRO_NAME;-&POKYVERSION;'
-
-
-
-
-
- Making a Copy of the Base BSP to Create Your New BSP Layer
-
-
- Now that you have set up the Source Directory and included the base BSP files, you need to
- create a new layer for your BSP.
- To create your BSP layer, you simply copy the meta-fri2
- layer to a new layer.
-
-
-
- For this example, the new layer will be named meta-mymachine.
- The name should follow the BSP layer naming convention, which is
- meta-<name>.
- The following assumes your working directory is meta-intel
- inside your Source Directory.
- To start your new layer, just copy the new layer alongside the existing
- BSP layers in the meta-intel directory:
-
- $ cp -a meta-fri2/ meta-mymachine
-
-
-
-
-
- Making Changes to Your BSP
-
-
- Right now you have two identical BSP layers with different names:
- meta-fri2 and meta-mymachine.
- You need to change your configurations so that they work for your new BSP and
- your particular hardware.
- The following sections look at each of these areas of the BSP.
-
-
-
- Changing the BSP Configuration
-
-
- We will look first at the configurations, which are all done in the layer’s
- conf directory.
-
-
-
- First, since in this example the new BSP will not support EMGD, we will get rid of the
- fri2.conf file and then rename the
- fri2-noemgd.conf file to mymachine.conf.
- Much of what we do in the configuration directory is designed to help the OpenEmbedded
- 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
- mymachine.conf.
-
- $ rm meta-mymachine/conf/machine/fri2.conf
- $ mv meta-mymachine/conf/machine/fri2-noemgd.conf \
- meta-mymachine/conf/machine/mymachine.conf
-
-
-
-
- Next, we need to make changes to the mymachine.conf itself.
- The only changes we want to make for this example are to the comment lines.
- Changing comments, of course, is never strictly necessary, but it's always good form to make
- them reflect reality as much as possible.
-
- Here, simply substitute the Fish River Island 2 name with an appropriate name for the BSP
- (mymachine in this case) and change the description to
- something that describes your hardware.
-
-
-
- Note that inside the mymachine.conf is the
- PREFERRED_VERSION_linux-yocto statement.
- This statement identifies the kernel that the BSP is going to use.
- In this case, the BSP is using linux-yocto, which is the
- current Yocto Project kernel based on the Linux 3.4 release.
-
-
-
- The next configuration file in the new BSP layer we need to edit is
- meta-mymachine/conf/layer.conf.
- This file identifies build information needed for the new layer.
- You can see the
- "Layer Configuration File" 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.
-
-
-
- The file contains these statements that reference the Fish River Island 2 BSP:
-
- BBFILE_COLLECTIONS += "fri2"
- BBFILE_PATTERN_fri2 := "^${LAYERDIR}/"
- BBFILE_PRIORITY_fri2 = "6"
-
- LAYERDEPENDS_fri2 = "intel"
-
-
-
-
- Simply substitute the machine string name fri2
- with the new machine name mymachine to get the following:
-
- BBFILE_COLLECTIONS += "mymachine"
- BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
- BBFILE_PRIORITY_mymachine = "6"
-
- LAYERDEPENDS_mymachine = "intel"
-
-
-
-
-
- Changing the Recipes in Your BSP
-
-
- 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 .bb files, while append files take
- the form of .bbappend files.
- If you want to leverage the existing recipes the OpenEmbedded build system uses
- but change those recipes, you can use .bbappend files.
- All new recipes and append files for your layer must go in the layer’s
- recipes-bsp, recipes-kernel,
- recipes-core, and
- recipes-graphics directories.
-
-
-
- Changing recipes-bsp
-
-
- First, let's look at recipes-bsp.
- 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 recipes-bsp recipes:
-
- $ rm -rf meta-mymachine/recipes-bsp/formfactor/formfactor/fri2
- $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/fri2-noemgd/ \
- meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
-
-
-
-
-
- Changing recipes-graphics
-
-
- Now let's look at recipes-graphics.
- 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 recipes-graphics directory:
-
- $ rm -rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/fri2
- $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/fri2-noemgd \
- meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine
-
-
-
-
- At this point the recipes-graphics directory just has files that
- support Video Electronics Standards Association (VESA) graphics modes and not EMGD.
-
-
-
-
- Changing recipes-kernel
-
-
- Finally, let's look at recipes-kernel changes.
- Recall that the BSP uses the linux-yocto kernel as determined
- earlier in the mymachine.conf.
- The recipe for that kernel is not located in the
- BSP layer but rather in the Source Directory at
- meta/recipes-kernel/linux and is
- named linux-yocto_3.4.bb.
- The SRCREV_machine and SRCREV_meta
- 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.
- In other words, the SRCREV values are simply Git commit
- IDs that identify which commit on each
- of the kernel branches (machine and meta) will be checked out and used to build
- the kernel.
-
-
-
- However, in the meta-mymachine layer in
- recipes-kernel/linux resides a .bbappend
- file named linux-yocto_3.4.bbappend that
- appends the information to the recipe of the same name
- that is found in meta/recipes-kernel/linux.
- Thus, the SRCREV statements in our
- mymachine append file override
- the more general statements found in the more general recipe.
-
-
-
- The SRCREV statements in the
- mymachine append file currently identify
- the kernel that supports the Fish River Island 2 BSP with and without EMGD support.
- Here are the statements:
- The commit ID strings used in this manual might not match the actual commit
- ID strings found in the linux-yocto_3.4.bbappend file.
- For the example, this difference does not matter.
-
- SRCREV_machine_pn-linux-yocto_fri2 ?= \
- "59c3ff750831338d05ab67d5efd7fc101c451aff"
- #SRCREV_meta_pn-linux-yocto_fri2 ?= \
- "c5bddf8ea379406ffec550528e17b777a0eba24b"
-
- SRCREV_machine_pn-linux-yocto_fri2-noemgd ?= \
- "59c3ff750831338d05ab67d5efd7fc101c451aff"
- #SRCREV_meta_pn-linux-yocto_fir2-noemgd ?= \
- "c5bddf8ea379406ffec550528e17b777a0eba24b"
-
- The SRCREV_meta_pn-linux-yocto_fir2-noemgd
- statements in the mymachine append file,
- which originated from the Fish River Island 2 BSP, are
- commented out.
- The reason they are not used is because the commit IDs are identical to
- those in the general linux-yocto_3.4.bbappend recipe,
- which is found in meta/recipes-kernel/linux.
-
-
-
-
- You will notice that there are two pairs of SRCREV 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:
- linux-yocto.
- At this point though, the unique commit strings all are still associated with
- Fish River Island 2 and not meta-mymachine.
-
-
-
- To fix this situation in linux-yocto_3.4.bbappend
- for mymachine,
- we delete the two SRCREV statements that support
- EMGD (the top pair).
- We also change the remaining pair to specify mymachine
- and insert the commit identifiers to identify the kernel in which we
- are interested, which will be based on the atom-pc-standard
- kernel.
- In this case, because we're working with the &DISTRO_NAME; branch of everything, we
- need to use the SRCREV values for the atom-pc branch
- that are associated with the &DISTRO_NAME; release.
-
-
-
- To find the machine value, we need to find the SRCREV
- value that &DISTRO_NAME; uses for the atom-pc branch, which we find in the
- poky/meta-yocto-bsp/recipes-kernel/linux/linux-yocto_3.4.bbappend
- file.
- The machine SRCREV we want is in the
- SRCREV_machine_atom-pc variable.
-
-
-
- The meta SRCREV isn't specified in this file, so if you
- needed it, you would find it in the base kernel recipe in the
- poky/meta/recipes-kernel/linux/linux-yocto_3.4.bb.
- Recall that for this example the commit ID's for the SRCREV
- meta statements are identical and do not have to be used in the
- mymachine append file.
-
-
-
- Here are the final SRCREV statements for the
- mymachine append file:
-
- SRCREV_machine_pn-linux-yocto_mymachine ?= \
- "0985844fa6235422c67ef269952fa4e765f252f9"
- #SRCREV_meta_pn-linux-yocto_mymachine ?= \
- "c5bddf8ea379406ffec550528e17b777a0eba24b"
-
-
-
-
- In this example, we're using the SRCREV values we
- 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 SRCREV values taken directly from the kernel's
- repository.
- We will not be doing that for this example.
- However, if you do base a future BSP on master and
- 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 SRCREV statements.
- You can find all the machine and meta
- branch points (commits) for the linux-yocto-3.4 kernel at
- .
-
-
-
- If you need a little more assistance after going to the link then do the following:
-
- Expand the list of branches by clicking […]
- Click on the standard/default/common-pc/atom-pc
- branch
- Click on the commit column header to view the top commit
- Copy the commit string for use in the
- linux-yocto_3.4.bbappend file
-
-
-
-
- For the SRCREV statement that points to the meta
- branch use the same procedure except expand the meta
- branch in step 2 above.
-
-
-
- Also in the linux-yocto_3.4.bbappend file are
- COMPATIBLE_MACHINE,
- KMACHINE,
- and
- KBRANCH 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 mymachine replaces
- fri2-noemgd and fri2.
-
-
-
- Because we are using the atom-pc branch for this new BSP, we can also find
- the exact branch we need for the KMACHINE
- and KBRANCH variables in our new BSP from the value
- we find in the
- poky/meta-yocto-bsp/recipes-kernel/linux/linux-yocto_3.4.bbappend
- file we looked at in a previous step.
- In this case, the values we want are in the KMACHINE_atom-pc variable
- and the KBRANCH_atom-pc variables in that file.
- Here is the final linux-yocto_3.4.bbappend file after all
- the edits:
-
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
-
- COMPATIBLE_MACHINE_mymachine = "mymachine"
- KMACHINE_mymachine = "atom-pc"
- KBRANCH_mymachine = "standard/default/common-pc/atom-pc"
-
- SRCREV_machine_pn-linux-yocto_mymachine ?= \
- "f29531a41df15d74be5ad47d958e4117ca9e489e"
- SRCREV_meta_pn-linux-yocto_mymachine ?= \
- "b14a08f5c7b469a5077c10942f4e1aec171faa9d"
-
-
-
-
-
-
- BSP Recipe Change Summary
-
-
- 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
- meta-mymachine of any code that supported the EMGD features
- and making sure we were identifying the kernel that supports our example, which
- is the atom-pc-standard kernel.
- We did not introduce any new recipes to the layer.
-
-
-
- Finally, it is also important to update the layer’s README
- file so that the information in it reflects your BSP.
-
-
-
-
-
- Preparing for the Build
-
-
- To get ready to build your image that uses the new layer you need to do the following:
-
- Get the environment ready for the build by sourcing the environment
- script.
- The environment script is in the top-level of the Source Directory.
- The script has the string
- init-build-env in the file’s name.
- For this example, the following command gets the build environment ready:
-
- $ source oe-init-build-env yocto-build
-
- When you source the script, a build directory is created in the current
- working directory.
- In our example we were in the poky directory.
- Thus, entering the previous command created the yocto-build directory.
- If you do not provide a name for the build directory it defaults to
- build.
- The yocto-build directory contains a
- conf directory that has
- two configuration files you will need to check: bblayers.conf
- and local.conf.
- Check and edit the resulting local.conf file.
- This file minimally identifies the machine for which to build the image by
- configuring the MACHINE variable.
- For this example you must set the variable to mymachine as follows:
-
- MACHINE ??= “mymachine”
-
- You should also be sure any other variables in which you are interested are set.
- Some variables to consider are BB_NUMBER_THREADS
- and PARALLEL_MAKE, both of which can greatly reduce your build time
- if your development system supports multiple cores.
- For development systems that support multiple cores, a good rule of thumb is to set
- both the BB_NUMBER_THREADS and PARALLEL_MAKE
- variables to twice the number of cores your system supports.
- Update the bblayers.conf file so that it includes
- both the path to your new BSP layer and the path to the
- meta-intel layer.
- In this example, you need to include both these paths as part of the
- BBLAYERS variable:
-
- $HOME/poky/meta-intel
- $HOME/poky/meta-intel/meta-mymachine
-
-
-
-
-
- The
- Variables Glossary chapter in the
- Yocto Project Reference Manual has more information on configuration variables.
-
-
-
-
- Building and Booting the Image
-
-
- To build the image for our meta-mymachine BSP enter the following command
- from the same shell from which you ran the setup script.
- You should run the bitbake command without any intervening shell commands.
- For example, moving your working directory around could cause problems.
- Here is the command for this example:
-
- $ bitbake -k core-image-sato
-
-
-
-
- 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.
-
-
-
- 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 .hddimg file, located in the
- poky/build/tmp/deploy/images
- directory after a successful build to the flash drive.
- Assuming the USB flash drive takes device /dev/sdf,
- use dd to copy the live image to it.
- For example:
-
- # dd if=core-image-sato-mymachine-20111101223904.hddimg of=/dev/sdf
- # sync
- # eject /dev/sdf
-
- You should now have a bootable USB flash device.
-
-
-
- Insert the device
- into a bootable USB socket on the target, and power it on.
- The system should boot to the Sato graphical desktop.
- 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
- mymachine.conf
- contents with the contents of atom-pc.conf and replace
- xorg.conf with atom-pc xorg.conf
- in meta-yocto 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.
-
-
-
- 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:
-
- 260538368 2012-04-27 01:44 core-image-sato-mymachine-20120427025051.hddimg
-
- The previous instructions are also present in the README that was copied
- from meta-fri2, which should also be updated to reflect the specifics of your
- new BSP.
- That file and the README.hardware file in the top-level
- poky directory
- also provides some suggestions for things to try if booting fails and produces
- strange error messages.
-
-
-
-
-
-
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
index 0cbd85fc3b..a5856e0995 100644
--- a/documentation/dev-manual/dev-manual.xml
+++ b/documentation/dev-manual/dev-manual.xml
@@ -80,8 +80,6 @@
-
-