diff options
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/dev-manual/dev-manual-bsp-appendix.xml | 713 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual.xml | 2 |
2 files changed, 0 insertions, 715 deletions
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 @@ -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"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 development example. - The example assumes the following: - <itemizedlist> - <listitem><para>No previous preparation or use of the Yocto Project.</para></listitem> - <listitem><para>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. - </para></listitem> - <listitem><para>Shell commands assume <filename>bash</filename></para></listitem> - <listitem><para>Example was developed on an Intel-based Core i7 platform running - Ubuntu 10.04 LTS released in April of 2010.</para></listitem> - </itemizedlist> -</para> - -<section id='getting-local-yocto-project-files-and-bsp-files'> - <title>Getting Local Source Files and BSP Files</title> - - <para> - You need to have the <link linkend='source-directory'>Source Directory</link> - available on your host system. - You can set up this directory through tarball extraction or by cloning the - <filename>poky</filename> Git repository. - The following paragraphs describe both methods. - For additional information, see the bulleted item - "<link linkend='local-yp-release'>Yocto Project Release</link>". - </para> - - <para> - As mentioned, one way to set up the Source Directory is to use Git to clone the - <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 "&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 - <filename>&YOCTO_POKY;</filename>: - <literallayout class='monospaced'> - $ tar xfj &YOCTO_POKY_TARBALL; - $ cd &YOCTO_POKY; - </literallayout> - <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 &DISTRO_NAME; release tarballs. - Consequently, there is nothing left to do other than extract those tarballs into the - 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 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 - "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" section - for more discussion around these differences.</para></note> - </para> - - <para> - 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 &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'> - $ cd ~/poky - $ git fetch --tags - $ git checkout -b &DISTRO_NAME;-&POKYVERSION; origin/&DISTRO_NAME; - Switched to a new branch '&DISTRO_NAME;-&POKYVERSION;' - </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;-&POKYVERSION;</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 id='choosing-a-base-bsp-app'> - <title>Choosing a Base BSP</title> - - <para> - For this example, the base BSP is the <trademark class='registered'>Intel</trademark> - <trademark class='trade'>Atom</trademark> Processor E660 with Intel Platform - Controller Hub EG20T Development Kit, which is otherwise referred to as "Fish River Island 2." - The BSP layer is <filename>meta-fri2</filename>. - 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. - </para> - - <para> - For information on how to choose a base BSP, see - "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>". - </para> -</section> - -<section id='getting-your-base-bsp-app'> - <title>Getting Your Base BSP</title> - - <para> - You need to have the base BSP layer on your development system. - Similar to the local <link linkend='source-directory'>Source Directory</link>, - 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 "<link linkend='getting-setup'>Getting Setup</link>" for information on how to get - the BSP files. - </para> - - <para> - This example assumes the BSP layer will be located within a directory named - <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 - <filename>meta-fri2</filename> starting point in both the Git and the tarball cases. - </para> - - <para> - 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 <filename>poky</filename> - directory created in the previous steps: - <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/meta-intel.git - $ cd meta-intel - </literallayout> - 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 - <ulink url='&YOCTO_HOME_URL;/download'>Downloads</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;/fri2-noemgd/fri2-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2'></ulink>. - Again, be sure that you are already in the <filename>poky</filename> directory - as described previously before installing the tarball: - <literallayout class='monospaced'> - $ tar xfj fri2-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2 - $ cd meta-intel - </literallayout> - </para> - - <para> - 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 &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>&DISTRO_NAME;</filename> - branch. - <literallayout class='monospaced'> - $ 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;' - </literallayout> - </para> -</section> - -<section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app'> - <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title> - - <para> - 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 <filename>meta-fri2</filename> - layer to a new layer. - </para> - - <para> - For this example, the new layer will be named <filename>meta-mymachine</filename>. - The name should follow the BSP layer naming convention, which is - <filename>meta-<name></filename>. - The following assumes your working directory is <filename>meta-intel</filename> - inside your Source Directory. - To start your new layer, just copy the new layer alongside the existing - BSP layers in the <filename>meta-intel</filename> directory: - <literallayout class='monospaced'> - $ cp -a meta-fri2/ meta-mymachine - </literallayout> - </para> -</section> - -<section id='making-changes-to-your-bsp-app'> - <title>Making Changes to Your BSP</title> - - <para> - Right now you have two identical BSP layers with different names: - <filename>meta-fri2</filename> and <filename>meta-mymachine</filename>. - 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. - </para> - - <section id='changing-the-bsp-configuration'> - <title>Changing the BSP Configuration</title> - - <para> - 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>fri2.conf</filename> file and then rename the - <filename>fri2-noemgd.conf</filename> file to <filename>mymachine.conf</filename>. - 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 - <filename>mymachine.conf</filename>. - <literallayout class='monospaced'> - $ rm meta-mymachine/conf/machine/fri2.conf - $ mv meta-mymachine/conf/machine/fri2-noemgd.conf \ - meta-mymachine/conf/machine/mymachine.conf - </literallayout> - </para> - - <para> - Next, we need to make changes to the <filename>mymachine.conf</filename> 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 - (<filename>mymachine</filename> in this case) and change the description to - something that describes your hardware. - </para> - - <para> - Note that inside the <filename>mymachine.conf</filename> is the - <filename>PREFERRED_VERSION_linux-yocto</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 Yocto Project kernel based on the Linux 3.4 release. - </para> - - <para> - The next configuration file in the new BSP layer we need to edit is - <filename>meta-mymachine/conf/layer.conf</filename>. - This file identifies build information needed for the new layer. - You can see the - "<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> - - <para> - The file contains these statements that reference the Fish River Island 2 BSP: - <literallayout class='monospaced'> - BBFILE_COLLECTIONS += "fri2" - BBFILE_PATTERN_fri2 := "^${LAYERDIR}/" - BBFILE_PRIORITY_fri2 = "6" - - LAYERDEPENDS_fri2 = "intel" - </literallayout> - </para> - - <para> - Simply substitute the machine string name <filename>fri2</filename> - with the new machine name <filename>mymachine</filename> to get the following: - <literallayout class='monospaced'> - BBFILE_COLLECTIONS += "mymachine" - BBFILE_PATTERN_mymachine := "^${LAYERDIR}/" - BBFILE_PRIORITY_mymachine = "6" - - LAYERDEPENDS_mymachine = "intel" - </literallayout> - </para> - </section> - - <section id='changing-the-recipes-in-your-bsp'> - <title>Changing the Recipes in Your BSP</title> - - <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, while append files take - the form of <filename>.bbappend</filename> files. - If you want to leverage the existing recipes the OpenEmbedded 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> - - <section id='changing-recipes-bsp'> - <title>Changing <filename>recipes-bsp</filename></title> - - <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-bsp/formfactor/formfactor/fri2 - $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/fri2-noemgd/ \ - meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine - </literallayout> - </para> - </section> - - <section id='changing-recipes-graphics'> - <title>Changing <filename>recipes-graphics</filename></title> - - <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-config/fri2 - $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/fri2-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> - </section> - - <section id='changing-recipes-kernel'> - <title>Changing <filename>recipes-kernel</filename></title> - - <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 Source Directory at - <filename>meta/recipes-kernel/linux</filename> and is - named <filename>linux-yocto_3.4.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. - In other words, the <filename>SRCREV</filename> 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. - </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_3.4.bbappend</filename> that - appends the information to the recipe of the same name - that is found in <filename>meta/recipes-kernel/linux</filename>. - Thus, the <filename>SRCREV</filename> statements in our - <filename>mymachine</filename> append file override - the more general statements found in the more general recipe. - </para> - - <para> - The <filename>SRCREV</filename> statements in the - <filename>mymachine</filename> append file currently identify - the kernel that supports the Fish River Island 2 BSP with and without EMGD support. - 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.4.bbappend</filename> file. - For the example, this difference does not matter.</note> - <literallayout class='monospaced'> - 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" - </literallayout> - <note>The <filename>SRCREV_meta_pn-linux-yocto_fir2-noemgd</filename> - statements in the <filename>mymachine</filename> 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 <filename>linux-yocto_3.4.bbappend</filename> recipe, - which is found in <filename>meta/recipes-kernel/linux</filename>. - </note> - </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 - Fish River Island 2 and not <filename>meta-mymachine</filename>. - </para> - - <para> - To fix this situation in <filename>linux-yocto_3.4.bbappend</filename> - for <filename>mymachine</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. - 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 &DISTRO_NAME; release. - </para> - - <para> - To find the machine value, we need to find the <filename>SRCREV</filename> - value that &DISTRO_NAME; uses for the atom-pc branch, which we find in the - <filename>poky/meta-yocto-bsp/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename> - file. - The machine <filename>SRCREV</filename> we want is in the - <filename>SRCREV_machine_atom-pc</filename> variable. - </para> - - <para> - The meta <filename>SRCREV</filename> isn't specified in this file, so if you - needed it, you would find it in the base kernel recipe in the - <filename>poky/meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>. - Recall that for this example the commit ID's for the <filename>SRCREV</filename> - meta statements are identical and do not have to be used in the - <filename>mymachine</filename> append file. - </para> - - <para> - Here are the final <filename>SRCREV</filename> statements for the - <filename>mymachine</filename> append file: - <literallayout class='monospaced'> - SRCREV_machine_pn-linux-yocto_mymachine ?= \ - "0985844fa6235422c67ef269952fa4e765f252f9" - #SRCREV_meta_pn-linux-yocto_mymachine ?= \ - "c5bddf8ea379406ffec550528e17b777a0eba24b" - </literallayout> - </para> - - <para> - In this example, we're using the <filename>SRCREV</filename> 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 <filename>SRCREV</filename> 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 <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.4</filename> kernel at - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/linux-yocto-3.4'></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>standard/default/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_3.4.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_3.4.bbappend</filename> file are - <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> 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>fri2-noemgd</filename> and <filename>fri2</filename>. - </para> - - <para> - 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> - and <filename>KBRANCH</filename> variables in our new BSP from the value - we find in the - <filename>poky/meta-yocto-bsp/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename> - file we looked at in a previous step. - In this case, the values we want are in the <filename>KMACHINE_atom-pc</filename> variable - and the <filename>KBRANCH_atom-pc</filename> variables in that file. - Here is the final <filename>linux-yocto_3.4.bbappend</filename> file after all - the edits: - <literallayout class='monospaced'> - 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" - </literallayout> - </para> - </section> - </section> - - <section id='bsp-recipe-change-summary'> - <title>BSP Recipe Change Summary</title> - - <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-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. - </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> - -<section id='preparing-for-the-build-app'> - <title>Preparing for the Build</title> - - <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 Source Directory. - 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>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> - <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 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 - 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> - </para> - - <para> - The - <ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Variables Glossary</ulink> chapter in the - Yocto Project Reference Manual has more information on configuration variables. - </para> -</section> - -<section id='building-the-image-app'> - <title>Building and Booting the Image</title> - - <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 - </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> - - <para> - 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>.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/sdf</filename>, - use <filename>dd</filename> to copy the live image to it. - For example: - <literallayout class='monospaced'> - # dd if=core-image-sato-mymachine-20111101223904.hddimg of=/dev/sdf - # sync - # eject /dev/sdf - </literallayout> - You should now have a bootable USB flash device. - </para> - - <para> - 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 &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: - <literallayout class='monospaced'> - 260538368 2012-04-27 01:44 core-image-sato-mymachine-20120427025051.hddimg - </literallayout> - <note>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 <filename>README.hardware</filename> file in the top-level - <filename>poky</filename> directory - also provides some suggestions for things to try if booting fails and produces - strange error messages.</note> - </para> -</section> -</appendix> - - -<!-- -vim: expandtab tw=80 ts=4 ---> 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 @@ <xi:include href="dev-manual-model.xml"/> - <xi:include href="dev-manual-bsp-appendix.xml"/> - <xi:include href="dev-manual-kernel-appendix.xml"/> </book> |