From 7082a56c9568730abcff359809ea7732cf5df440 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 14 Jun 2012 10:51:45 -0700 Subject: 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 Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-bsp-appendix.xml | 212 ++++++++++++--------- 1 file 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 @@ +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[ %poky; ] > BSP Development Example - This appendix provides a complete BSP example. + This appendix provides a complete BSP development example. The example assumes the following: No previous preparation or use of the Yocto Project. @@ -31,47 +32,77 @@ The following paragraphs describe both methods. For additional information, see the bulleted item "Yocto Project Release". - + As mentioned, one way to get the Yocto Project files is to use Git to clone the - poky repository: + 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 "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 + &YOCTO_POKY;: - $ tar xfj poky-edison-6.0.1.tar.bz2 - $ cd poky + $ tar xfj &YOCTO_POKY_TARBALL; + $ cd &YOCTO_POKY; - If you're using the tarball method, you can ignore all the following steps that + 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. + 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 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. - Once you have the local poky 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 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 1.1.1 Release, which is code - named "edison". - These commands create a local branch named edison - 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: - $ 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;' + 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;. + 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 @@ -100,7 +131,7 @@ 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 @@ meta-intel contained within the poky parent directory. The following steps will automatically create the - meta-intel directory and the contained meta-crownbay - starting point in both the Git and the tarball cases. + meta-intel directory and the contained + meta-crownbay starting point in both the Git and the tarball cases. @@ -125,12 +156,16 @@ $ git clone git://git.yoctoproject.org/meta-intel.git $ cd meta-intel - Alternatively, you can start with the downloaded meta-intel - 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 + Download 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: + as described previously before installing the tarball: - $ tar xfj crownbay-noemgd-edison-6.0.1.tar.bz2 + $ tar xfj crownbay-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2 $ cd meta-intel @@ -139,15 +174,16 @@ 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 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 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 edison branch. + For this example we are going to use the &DISTRO_NAME; branch. - $ 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;'
@@ -234,10 +270,8 @@ 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. + "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. @@ -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 .bb 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 Yocto Project 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 @@ -278,7 +313,7 @@
- Changing <filename>recipes-bsp</filename> + Changing  <filename>recipes-bsp</filename> First, let's look at recipes-bsp. @@ -295,7 +330,7 @@
- Changing <filename>recipes-graphics</filename> + Changing  <filename>recipes-graphics</filename> Now let's look at recipes-graphics. @@ -316,7 +351,7 @@
- Changing <filename>recipes-core</filename> + Changing  <filename>recipes-core</filename> Now let's look at changes in recipes-core. @@ -324,7 +359,7 @@ recipes-core/tasks appends the similarly named recipe located in the local Yocto Project files at meta/recipes-core/tasks. - 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: @@ -345,7 +380,7 @@
- Changing <filename>recipes-kernel</filename> + Changing  <filename>recipes-kernel</filename> Finally, let's look at recipes-kernel changes. @@ -368,15 +403,18 @@ However, in the meta-mymachine layer in recipes-kernel/linux resides a .bbappend file named linux-yocto_3.0.bbappend that - is appended to the recipe of the same name in meta/recipes-kernel/linux. - Thus, the SRCREV statements in the "append" file override + appends information to the recipe of the same name in meta/recipes-kernel/linux. + Thus, the SRCREV statements in the append file override the more general statements found in meta. - The SRCREV statements in the "append" file currently identify + The SRCREV 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: + The commit ID strings used in this manual might not match the actual commit + ID strings found in the linux-yocto_3.0.bbappend file. + For the example, this difference does not matter. 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 atom-pc-standard 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 SRCREV 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 SRCREV - 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 poky/meta-yocto/recipes-kernel/linux/linux-yocto_3.0.bbappend file. @@ -423,9 +461,7 @@ The meta SRCREV isn't specified in this file, so it must be specified in the base kernel recipe in the poky/meta/recipes-kernel/linux/linux-yocto_3.0.bb - file, in the SRCREV_meta variable found there. - It happens to be the same as the value we already inherited from the - meta-crownbay BSP. + file, in the SRCREV_meta variable found there. Here are the final SRCREV statements: SRCREV_machine_pn-linux-yocto_mymachine ?= \ @@ -437,8 +473,8 @@ In this example, we're using the SRCREV 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 SRCREV values taken directly from the kernel repo. We will not be doing that for this example. @@ -448,7 +484,7 @@ the SRCREV statements. You can find all the machine and meta branch points (commits) for the linux-yocto-3.0 kernel at - . + . @@ -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 mymachine replaces crownbay-noemgd and crownbay. - 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 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 we find in the poky/meta-yocto/recipes-kernel/linux/linux-yocto_3.0.bbappend 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 KMACHINE_atom-pc variable in that file. Here is the final linux-yocto_3.0.bbappend file after all the edits: @@ -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 - meta-machine of any code that supported the EMGD features + 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. @@ -544,7 +580,7 @@ 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 yocot-build directory contains a + The yocto-build directory contains a conf directory that has two configuration files you will need to check: bblayers.conf and local.conf. @@ -558,15 +594,17 @@ 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 you are using a multi-threaded development system (e.g. values of - 8 and j 6, respectively are optimal - for a development machine that has four available cores). + 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 - the path to your new BSP layer. - In this example you need to include the pathname to meta-mymachine. - For this example the - BBLAYERS variable in the file would need to include the following path: + 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 @@ -574,7 +612,7 @@ The appendix - + Reference: Variables Glossary in the Yocto Project Reference Manual has more information on configuration variables. @@ -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 .hddimage, located in the + 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/sdc, @@ -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. + 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 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. - - - 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 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. -
-- cgit v1.2.3-54-g00ecf