From 24cbfd49267e4a49c97b0da76341a086ac4fda4e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 27 Jul 2011 07:55:55 -0700 Subject: documentation/dev-manual/dev-manual-bsp-appendix.xml: spacing fixed Fixed the spacing to follow my indentation scheme for Docbook files. (From yocto-docs rev: 6ed8cbc7dc48e5a380d27ee280fb92809b931223) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-bsp-appendix.xml | 1658 +++++++------------- 1 file changed, 577 insertions(+), 1081 deletions(-) diff --git a/documentation/dev-manual/dev-manual-bsp-appendix.xml b/documentation/dev-manual/dev-manual-bsp-appendix.xml index cf1033e530..f3927c35d2 100644 --- a/documentation/dev-manual/dev-manual-bsp-appendix.xml +++ b/documentation/dev-manual/dev-manual-bsp-appendix.xml @@ -3,129 +3,62 @@ -Development Cases +BSP Development Case - Many development cases exist for which you can use the Yocto Project. - However, for the purposes of this manual we are going to focus on two common development cases or groupings: - System Development and User Application Development. - System Development covers Board Support Package (BSP) development and kernel modification. - User Application Development covers development of applications that you intend to run on some - target hardware. + This appendix provides a complete BSP example. + The example assumes the following: + + No previous preparation or use of the Yocto Project. + Use of the Crown Bay Board Support Package (BSP) as a base BSP from + which to work from. + Shell commands assume bash + Example was developed on an Intel-based Core i7 platform running + Ubuntu 10.04 LTS released in April of 2010. + - - [WRITERS NOTE: What is undetermined at this point is how much of the entire development process - we include in this particular chapter. - In other words, do we cover debugging and emulation steps here on a case-specific basis? - Or, do we capture that information in the appropriate subsequent chapter by case?] - +
+ Setting Up Yocto Project -
- System Development + + You need to have the Yocto Project files available on your host system. + You can get files through tarball extraction or by cloning the poky + Git repository. + Typically, cloning the Git repository is the method to use. + This allows you to maintain a complete history of changes and facilitates you + contributing back to the Yocto Project. + However, if you just want a hierarchical file structure that contains the recipes + and metadata that let you develop you can download tarballs from the + download page. + - System development involves modification or creation of an image that you want to run on - a specific hardware target. - Usually when you want to create an image that runs on embedded hardware the image does - not require the same amount of features that a full-fledged Linux distribution provides. - Thus, you can create a much smaller image that is designed to just use the hardware - features for your particular hardware. + Regardless of the method you use this manual will refer to the resulting + hierarchical set of files as "the local Yocto Project files." - To help you understand how system development works in the Yocto Project, this section - covers two types of image development: BSP creation and kernel modification. + [WRITER'S NOTE: I need to substitute correct and actual filenames for the + 1.1 release throughout this example once they become available.] -
- Developing a Board Support Package (BSP) - - - A BSP is a package of recipes that when applied while building an image results in - an image you can run on a particular board. - Thus, the package, when compiled into the new image, supports the operation of the board. - - - - For a brief list of terms used when describing the development process in the Yocto Project, - see Yocto Project Terms in this manual. - - - - Here are the basic steps involved in creating a BSP: - - Be sure your host development system is set up to support - development using the Yocto Project. - See - - The Linux Distributions section and - - The Packages section both - in the Yocto Project Quick Start for requirements. - You will also need a release of Yocto Project installed on the host. - Choose a BSP available with Yocto Project that most closely represents - your hardware. - Get set up with a base BSP. - Make a copy of the existing BSP and isolate your work by creating a layer - for your recipes. - Make configuration and recipe changes to your new BSP layer. - Prepare for the build. - Select and configure the kernel. - Identify the machine branch. - Build the image. - - You can view a video presentation of the BSP creation process - here. - You can also find supplemental information in the - - Board Support Package (BSP) Development Guide. - Finally, there is wiki page write up of the example located - - here you might find helpful. - - -
- Setting Up Yocto Project - - - You need to have the Yocto Project files available on your host system. - You can get files through tarball extraction or by cloning the poky - Git repository. - Typically, cloning the Git repository is the method to use. - This allows you to maintain a complete history of changes and facilitates you - contributing back to the Yocto Project. - However, if you just want a hierarchical file structure that contains the recipes - and metadata that let you develop you can download tarballs from the - download page. - - - - Regardless of the method you use this manual will refer to the resulting - hierarchical set of files as "the local Yocto Project files." - - - - [WRITER'S NOTE: I need to substitute correct and actual filenames for the - 1.1 release throughout this example once they become available.] - - - - If you download a tarball you can extract it into any directory you want using the - tar command. - For example, the following command extracts the Yocto Project 1.1 release tarball - into the current working directory and sets up a file structure whose top-level - directory is named poky-1.1: - + + If you download a tarball you can extract it into any directory you want using the + tar command. + For example, the following command extracts the Yocto Project 1.1 release tarball + into the current working directory and sets up a file structure whose top-level + directory is named poky-1.1: + $ tar xfj poky-1.1.tar.bz2 - - + + - - The following transcript shows how to clone the poky Git repository - into the current working directory. - The command creates the repository in a directory named poky: - + + The following transcript shows how to clone the poky Git repository + into the current working directory. + The command creates the repository in a directory named poky: + $ git clone git://git.yoctoproject.org/poky Initialized empty Git repository in /home/scottrif/poky/.git/ remote: Counting objects: 107624, done. @@ -133,103 +66,102 @@ remote: Total 107624 (delta 73393), reused 99851 (delta 67287) Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done. Resolving deltas: 100% (73393/73393), done. - - + + - - 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: - + + 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: + $ git branch -a $ git tag -l - - For this example we are going to use the Yocto Project 1.1 Release, - which maps to the 1.1 branch in the repository. - These commands create a local branch named 1.1 - that tracks the remote branch of the same name. - - + + For this example we are going to use the Yocto Project 1.1 Release, + which maps to the 1.1 branch in the repository. + These commands create a local branch named 1.1 + that tracks the remote branch of the same name. + $ cd poky $ git checkout -b 1.1 origin/1.1 Switched to a new branch '1.1' - - -
- -
- Choosing a Base BSP - - - The Yocto Project ships with several BSPs that support various hardware. - It is best to base your new BSP on an existing BSP rather than create all the - recipes and configuration files from scratch. - While it is possible to create everything from scratch, basing your new BSP - on something that is close is much easier. - Or, at a minimum, it gives you some structure with which to start. - - - - At this point you need to understand your target hardware well enough to determine which - existing BSP it most closely matches. - Things to consider are your hardware’s on-board features such as CPU type and graphics support. - You should look at the README files for supported BSPs to get an idea of which one - you could use. - A generic Atom-based BSP to consider is the Crown Bay that does not support - the Intel® Embedded Media Graphics Driver (EMGD). - The remainder of this example uses that base BSP. - - - - To see the supported BSPs, go to the Yocto Project - download page and click - on “BSP Downloads.” - -
- -
- Getting Your Base BSP - - - You need to have the base BSP layer on your development system. - Like the local Yocto Project files, you can get the BSP - layer one of two ways: - download the BSP tarball and extract it, or set up a local Git repository that - has the Yocto Project BSP layers. - You should use the same method that you used to get the local Yocto Project files earlier. - - - - If you are using tarball extraction, simply download the tarball for the base - BSP you chose in the previous step and then extract it into any directory - you choose using the tar command. - Upon extraction, the BSP source directory (layer) will be named - meta-<BSP_name>. - The following command extracts the Crown Bay BSP into the current directory and names it - meta-crownbay: - + + +
+ +
+ Choosing a Base BSP + + + The Yocto Project ships with several BSPs that support various hardware. + It is best to base your new BSP on an existing BSP rather than create all the + recipes and configuration files from scratch. + While it is possible to create everything from scratch, basing your new BSP + on something that is close is much easier. + Or, at a minimum, it gives you some structure with which to start. + + + + At this point you need to understand your target hardware well enough to determine which + existing BSP it most closely matches. + Things to consider are your hardware’s on-board features such as CPU type and graphics support. + You should look at the README files for supported BSPs to get an idea of which one + you could use. + A generic Atom-based BSP to consider is the Crown Bay that does not support + the Intel® Embedded Media Graphics Driver (EMGD). + The remainder of this example uses that base BSP. + + + + To see the supported BSPs, go to the Yocto Project + download page and click + on “BSP Downloads.” + +
+ +
+ Getting Your Base BSP + + + You need to have the base BSP layer on your development system. + Like the local Yocto Project files, you can get the BSP + layer one of two ways: + download the BSP tarball and extract it, or set up a local Git repository that + has the Yocto Project BSP layers. + You should use the same method that you used to get the local Yocto Project files earlier. + + + + If you are using tarball extraction, simply download the tarball for the base + BSP you chose in the previous step and then extract it into any directory + you choose using the tar command. + Upon extraction, the BSP source directory (layer) will be named + meta-<BSP_name>. + The following command extracts the Crown Bay BSP into the current directory and names it + meta-crownbay: + $ tar xjf crownbay-noemgd-1.1.tar.bz2 - - - - - If you cloned a poky Git repository - then you need to set up a different local Git repository - (meta-intel) for the BSP. - The meta-intel Git repository contains all the metadata - that supports BSP creation. - When you set up the meta-intel Git repository you can - set it up anywhere you want. - We will set up the repository inside the - poky Git repository in this example. - - - - The following transcript shows the steps to clone the meta-intel - Git repository inside the poky Git repository created earlier in this - example. - + + + + + If you cloned a poky Git repository + then you need to set up a different local Git repository + (meta-intel) for the BSP. + The meta-intel Git repository contains all the metadata + that supports BSP creation. + When you set up the meta-intel Git repository you can + set it up anywhere you want. + We will set up the repository inside the + poky Git repository in this example. + + + + The following transcript shows the steps to clone the meta-intel + Git repository inside the poky Git repository created earlier in this + example. + $cd poky $ git clone git://git.yoctoproject.org/meta-intel.git Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ @@ -238,251 +170,251 @@ remote: Total 1325 (delta 546), reused 85 (delta 27) Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done. Resolving deltas: 100% (546/546), done. - - + + - - 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 1.1 branch. - + + 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 1.1 branch. + $ cd meta-intel $ git checkout -b 1.1 origin/1.1 Switched to a new branch 'bernard' - - -
- -
- Making a Copy of the Base BSP to Create Your New BSP Layer - - - Now that you have the local Yocto Project files and the base BSP files you need to create a - new layer for your BSP. - - - - Layers are ideal for isolating and storing work for a given piece of hardware. - A layer is really just a location or area in which you place the recipes for your BSP. - In fact, a BSP is, in itself, a special type of layer. - Consider an application as another example that illustrates a layer. - Suppose you are creating an application that has library or other dependencies in - order for it to compile and run. - The layer, in this case, would be where all the recipes that define those dependencies - are kept. The key point for a layer is that it is an isolated area that contains - all the relevant information for the project that the Yocto Project build system knows about. - - - - The Yocto Project supports four BSPs that are part of the - Yocto Project release: atom-pc, beagleboard, - mpc8315e, and routerstationpro. - The recipes and configurations for these four BSPs are located and dispersed - within local Yocto Project files. - Consequently, they are not totally isolated in the spirit of layers unless you think - of meta-yocto as a layer itself. - On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, - N450, and Sugar Bay are isolated. - - - - When you set up a layer for a new BSP you should follow a standard layout. - This layout is described in the - - Example Filesystem Layout section of the Board Support Package (BSP) Development - Guide. - In the standard layout you will notice a suggested structure for recipes and - configuration information. - You can see the standard layout for the Crown Bay BSP in this example by examining the - directory structure of the meta-crownbay layer inside the - local Yocto Project files. - - - - To create your BSP layer you simply copy the meta-crownbay - layer to a new layer. - For this example the new layer will be named meta-mymachine. - The name must follow the BSP layer naming convention, which is - meta-<name>. - The following example assumes your working directory is meta-intel - inside the local Yocto Project files. - If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting - meta-crownbay directory structure to a location of your choice. - Good practice for a Git repository, however, is to just copy the new layer alongside - the existing - BSP layers in the meta-intel Git repository: - + + +
+ +
+ Making a Copy of the Base BSP to Create Your New BSP Layer + + + Now that you have the local Yocto Project files and the base BSP files you need to create a + new layer for your BSP. + + + + Layers are ideal for isolating and storing work for a given piece of hardware. + A layer is really just a location or area in which you place the recipes for your BSP. + In fact, a BSP is, in itself, a special type of layer. + Consider an application as another example that illustrates a layer. + Suppose you are creating an application that has library or other dependencies in + order for it to compile and run. + The layer, in this case, would be where all the recipes that define those dependencies + are kept. The key point for a layer is that it is an isolated area that contains + all the relevant information for the project that the Yocto Project build system knows about. + + + + The Yocto Project supports four BSPs that are part of the + Yocto Project release: atom-pc, beagleboard, + mpc8315e, and routerstationpro. + The recipes and configurations for these four BSPs are located and dispersed + within local Yocto Project files. + Consequently, they are not totally isolated in the spirit of layers unless you think + of meta-yocto as a layer itself. + On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, + N450, and Sugar Bay are isolated. + + + + When you set up a layer for a new BSP you should follow a standard layout. + This layout is described in the + + Example Filesystem Layout section of the Board Support Package (BSP) Development + Guide. + In the standard layout you will notice a suggested structure for recipes and + configuration information. + You can see the standard layout for the Crown Bay BSP in this example by examining the + directory structure of the meta-crownbay layer inside the + local Yocto Project files. + + + + To create your BSP layer you simply copy the meta-crownbay + layer to a new layer. + For this example the new layer will be named meta-mymachine. + The name must follow the BSP layer naming convention, which is + meta-<name>. + The following example assumes your working directory is meta-intel + inside the local Yocto Project files. + If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting + meta-crownbay directory structure to a location of your choice. + Good practice for a Git repository, however, is to just copy the new layer alongside + the existing + BSP layers in the meta-intel Git repository: + $ cp -a meta-crownbay/ meta-mymachine - - -
- -
- Making Changes to Your BSP - - - Right now you have two identical BSP layers with different names: - meta-crownbay and meta-mymachine. - You need to change your configurations so that they work for your new BSP and - your particular hardware. - We will look first at the configurations, which are all done in the layer’s - conf directory. - - - - First, since in this example the new BSP will not support EMGD we will get rid of the - crownbay.conf file and then rename the - crownbay-noemgd.conf file to mymachine.conf. - Much of what we do in the configuration directory is designed to help the Yocto Project - build system work with the new layer and to be able to find and use the right software. - The following two commands result in a single machine configuration file named - mymachine.conf. - + + +
+ +
+ Making Changes to Your BSP + + + Right now you have two identical BSP layers with different names: + meta-crownbay and meta-mymachine. + You need to change your configurations so that they work for your new BSP and + your particular hardware. + We will look first at the configurations, which are all done in the layer’s + conf directory. + + + + First, since in this example the new BSP will not support EMGD we will get rid of the + crownbay.conf file and then rename the + crownbay-noemgd.conf file to mymachine.conf. + Much of what we do in the configuration directory is designed to help the Yocto Project + build system work with the new layer and to be able to find and use the right software. + The following two commands result in a single machine configuration file named + mymachine.conf. + $ rm meta-mymachine/conf/machine/crownbay.conf $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \ meta-mymachine/conf/machine/mymachine.conf - - - - - The next step makes changes to mymachine.conf itself. - The only changes needed for this example are changes to the comment lines. - Here we simply substitute the Crown Bay name with an appropriate name. - - - - Note that inside the mymachine.conf is the - PREFERRED_PROVIDER_virtual/kernel 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 Linux Yocto kernel based on the Linux 2.6.37 release. - - - - The next configuration file in the new BSP layer we need to edit is 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 Crown Bay BSP: - + + + + + The next step makes changes to mymachine.conf itself. + The only changes needed for this example are changes to the comment lines. + Here we simply substitute the Crown Bay name with an appropriate name. + + + + Note that inside the mymachine.conf is the + PREFERRED_PROVIDER_virtual/kernel 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 Linux Yocto kernel based on the Linux 2.6.37 release. + + + + The next configuration file in the new BSP layer we need to edit is 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 Crown Bay BSP: + BBFILE_COLLECTIONS += "crownbay" BBFILE_PATTERN_crownbay := "^${LAYERDIR}/" BBFILE_PRIORITY_crownbay = "6" - - + + - - Simply substitute the machine string name crownbay - with the new machine name mymachine to get the following: - + + Simply substitute the machine string name crownbay + with the new machine name mymachine to get the following: + BBFILE_COLLECTIONS_mymachine += "mymachine" BBFILE_PATTERN_mymachine := "^${LAYERDIR}/" BBFILE_PRIORITY_mymachine = "6" - - - - - 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. - 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 - recipes-bsp, recipes-kernel, - recipes-core, and - recipes-graphics directories. - - - - 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: - + + + + + 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. + 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 + recipes-bsp, recipes-kernel, + recipes-core, and + recipes-graphics directories. + + + + 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-graphics/xorg-xserver/*emgd* $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \ meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine - - + + - - 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: - + + 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-emgd* $ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \ meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine - - - - - At this point the recipes-graphics directory just has files that - support Video Electronics Standards Association (VESA) graphics modes and not EMGD. - - - - Now let's look at changes in recipes-core. - The file task-core-tools.bbappend in - 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 - EMGD and non-EMGD. - Here are the contents of the file: - + + + + + At this point the recipes-graphics directory just has files that + support Video Electronics Standards Association (VESA) graphics modes and not EMGD. + + + + Now let's look at changes in recipes-core. + The file task-core-tools.bbappend in + 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 + EMGD and non-EMGD. + Here are the contents of the file: + RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap" RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap" - - + + - - The RRECOMMENDS statements list packages that - extend usability. - The first RRECOMMENDS statement can be removed, while the - second one can be changed to reflect meta-mymachine: - + + The RRECOMMENDS statements list packages that + extend usability. + The first RRECOMMENDS statement can be removed, while the + second one can be changed to reflect meta-mymachine: + RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap" - - - - - 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 local Yocto Project files at - meta/recipes-kernel/linux and is - named linux-yocto-2.6.37.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. - + + + + + 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 local Yocto Project files at + meta/recipes-kernel/linux and is + named linux-yocto-2.6.37.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. + - - However, in the meta-mymachine layer in - recipes-kernel/linux resides a .bbappend - file named linux-yocto-2.6.37.bbappend that - is appended to the recipe of the same name in meta/recipes-kernel/link. - 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 kernel that supports the Crown Bay BSP with and without EMGD support. - Here are the statements: - + + However, in the meta-mymachine layer in + recipes-kernel/linux resides a .bbappend + file named linux-yocto-2.6.37.bbappend that + is appended to the recipe of the same name in meta/recipes-kernel/link. + 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 kernel that supports the Crown Bay BSP with and without EMGD support. + Here are the statements: + SRCREV_machine_pn-linux-yocto_crownbay ?= \ "372c0ab135978bd8ca3a77c88816a25c5ed8f303" SRCREV_meta_pn-linux-yocto_crownbay ?= \ @@ -492,74 +424,74 @@ "372c0ab135978bd8ca3a77c88816a25c5ed8f303" SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \ "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b" - - - - - 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 - Crown Bay and not meta-mymachine. - - - - To fix this situation in linux-yocto-2.6.37.bbappend - 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. - Here are the final SRCREV statements: - + + + + + 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 + Crown Bay and not meta-mymachine. + + + + To fix this situation in linux-yocto-2.6.37.bbappend + 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. + Here are the final SRCREV statements: + SRCREV_machine_pn-linux-yocto-_mymachine ?= \ "fce17f046d3756045e4dfb49221d1cf60fcae329" SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \ "84f1a422d7e21fbc23a687035bdf9d42471f19e0" - - - - - 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-2.6.37 kernel - here. - - - - 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 yocto/standard/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-2.6.37.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-2.6.37.bbappend file are - COMPATIBLE_MACHINE, KMACHINE, - and KERNEL_FEATURES 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 - crownbay-noemgd and crownbay. - Here is the final linux-yocto-2.6.37.bbappend file after all - the edits: - + + + + + 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-2.6.37 kernel + here. + + + + 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 yocto/standard/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-2.6.37.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-2.6.37.bbappend file are + COMPATIBLE_MACHINE, KMACHINE, + and KERNEL_FEATURES 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 + crownbay-noemgd and crownbay. + Here is the final linux-yocto-2.6.37.bbappend file after all + the edits: + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" COMPATIBLE_MACHINE_mymachine = "mymachine" @@ -570,622 +502,186 @@ "fce17f046d3756045e4dfb49221d1cf60fcae329" SRCREV_meta_pn-linux-yocto_mymachine ?= \ "84f1a422d7e21fbc23a687035bdf9d42471f19e0" - - - - - 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-machine 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 - - - Once you have made all the changes to your BSP layer there remains a few things - you need to do for the Yocto Project build system in order for it to create your image. - You need to get the build environment ready by sourcing an environment setup script - and you need to be sure two key configuration files are configured appropriately. - - - - The entire process for building an image is overviewed in the - - Building an Image section of the Yocto Project Quick Start. - You might want to reference this information. - The remainder of this section will apply to our example of the - meta-mymachine layer. - - - - 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 local Yocto Project files - directory structure. - 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 yocot-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 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). - 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: - - $HOME/poky/meta-intel/meta-mymachine - - - - - - The appendix - - Reference: Variables Glossary in the Yocto Project Reference Manual has more information - on configuration variables. - -
- -
- Building the Image - - - The Yocto Project uses the BitBake tool to build images based on the type of image - you want to create. - You can find more information on BitBake - here. - - - - The build process supports several types of images to satisfy different needs. - When you issue the BitBake command you provide a “top-level” recipe that essentially - starts the process off of building the type of image you want. - - - - [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.] - - - - You can find these recipes in the meta/recipes-core/images and - meta/recipes-sato/images directories of your local Yocto Project - file structure (Git repository or extracted release tarball). - Although the recipe names are somewhat explanatory, here is a list that describes them: - - Base – A foundational basic image without support - for X that can be reasonably used for customization. - Core – A foundational basic image with support for - X that can be reasonably used for customization. - Direct Disk – An image that you can copy directory to - the disk of the target device. - Live – An image you can run from a USB device or from - a CD without having to first install something. - Minimal – A small image without a GUI. - This image is not much more than a kernel with a shell. - Minimal Development – A Minimal image suitable for - development work. - Minimal Direct Disk – A Minimal Direct Disk image. - Minimal RAM-based Initial Root Filesystem – A minimal image - that has the initramfs as part of the kernel, which allows the - system to find the first “init” program more efficiently. - Minimal Live – A Minimal Live image. - Minimal MTD Utilities – A minimal image that has support - for the MTD utilities, which let the user interact with the MTD subsystem in - the kernel to perform operations on flash devices. - Sato – An image with Sato support, a mobile environment - and visual style that works well with mobile devices. - Sato Development – A Sato image suitable for - development work. - Sato Direct Disk – A Sato Direct Disk image. - Sato Live – A Sato Live image. - Sato SDK – A Sato image that includes the Yocto Project - toolchain and development libraries. - Sato SDK Direct Disk – A Sato SDK Direct - Disk image. - Sato SDK Live – A Sato SDK Live image. - - - - - The remainder of this section applies to our example of the meta-mymachine layer. - - - - 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: + + + + + 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-machine 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 + + + Once you have made all the changes to your BSP layer there remains a few things + you need to do for the Yocto Project build system in order for it to create your image. + You need to get the build environment ready by sourcing an environment setup script + and you need to be sure two key configuration files are configured appropriately. + + + + The entire process for building an image is overviewed in the + + Building an Image section of the Yocto Project Quick Start. + You might want to reference this information. + The remainder of this section will apply to our example of the + meta-mymachine layer. + + + + 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 local Yocto Project files + directory structure. + The script has the string + init-build-env in the file’s name. + For this example, the following command gets the build environment ready: - $ bitbake –k core-image-sato-live + $ source oe-init-build-env yocto-build - - - - 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. - -
-
- -
- Modifying a Kernel - - - Kernel modification involves changing or adding configurations to an existing kernel, or - adding recipes to the kernel that are needed to support specific hardware features. - The process is similar to creating a Board Support Package (BSP) except that it does not - involve a BSP layer. - - - - This section presents a brief overview of the kernel structure and then provides a simple - example that shows how to modify the kernel. - - -
- Yocto Project Kernel Overview - - - When one thinks of the source files for a kernel they usually think of a fixed structure - of files that contain kernel patches. - The Yocto Project, however, employs mechanisims that in a sense result in a kernel source - generator. - - - - The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto - Project files. - Git employs branching strategies that effectively produce a tree-like structure whose - branches represent diversions from more general code. - For example, suppose two kernels are basically identical with the exception of a couple - different features in each. - In the Yocto Project source repositories managed by Git a main branch can contain the - common or shared - parts of the kernel source and two branches that diverge from that common branch can - each contain the features specific to the respective kernel. - The result is a managed tree whose "leaves" represent the end of a specific path that yields - a set of kernel source files necessary for a specific piece of hardware and its features. - - - - A big advantage to this scheme is the sharing of common features by keeping them in - "larger" branches that are further up the tree. - This practice eliminates redundant storage of similar features shared among kernels. - - - - When you build the kernel on your development system all files needed for the build - are taken from the Yocto Project source repositories pointed to by the - SRC_URI variable and gathered in a temporary work area - where they are subsequently used to create the unique kernel. - Thus, in a sense, the process constructs a local source tree specific to your - kernel to generate the new kernel image - a source generator if you will. - - - - For a complete discussion of the Yocto Project kernel's architcture and its branching strategy, - see the - The Yocto Project Kernel Architecture and Use Manual. - - - - You can find a web interface to the Yocto Project source repository at - . - Within the interface you will see groups of related source code, each of which can - be cloned using Git to result in a working Git repository on your local system - (referred to as the "local Yocto Project files" in this manual). - The Yocto Project supports four types of kernels in its source repositories at - : - - linux-yocto-2.6.34 - The - stable Linux Yocto kernel that is based on the Linux 2.6.34 release. - linux-yocto-2.6.37 - The current - Linux Yocto kernel that is based on the Linux 2.6.37 release. - linux-yocto-dev - A development - kernel based on the Linux 2.6.39-rc1 release. - linux-2.6 - A kernel based on - minimal Linux mainline tracking. - [WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this - repository on their development system.] - - -
- -
- Modifying a Kernel Example - - - This section presents a simple example that illustrates kernel modification - based on the linux-yocto-2.6.37 kernel. - The example uses the audio and mixer capabilities supported by the - Advanced Linux - Sound Architecture (ALSA) Project. - As the example progresses you will see how to do the following: - - Iteratively modify a base kernel locally. - Provide a recipe-based solution for your modified kernel. - - Proved an "in-tree" solution for your modified kernel - (i.e. make the modifcations part of the Yocto Project). - - - - - The example flows as follows: - - - - - Be sure your host development system is set up to support - development using the Yocto Project. - See - - The Linux Distributions section and - - The Packages section both - in the Yocto Project Quick Start for requirements. - You will also need a release of Yocto Project installed on the host. - Set up your environment for optimal local kernel development. - - Create a layer to isolate your kernel work. - Next item. - Next item. - Next item. - Next item. - - - -
- Setting Up Yocto Project - - - You need to have the Yocto Project files available on your host system. - The process is identical to that described in getting the files in section - "Setting Up Yocto Project" for - the BSP development case. - Be sure to either set up a local Git repository for poky - or download and unpack the Yocto Project release tarball. - -
- -
- Create a Git Repository of <filename>poky-extras</filename> - - - Everytime you change a configuration or add a recipe to the kernel you need to - do a fetch from the Linux Yocto kernel source repositories. - This can get tedious and time consuming if you need to fetch the entire - Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change - to the kernel. - - - - You can get around this by setting up a meta-kernel-dev - area on your local system. - This area contains "append" files for every kernel recipe, which also include - a KSRC statement that points to the kernel source files. - You can set up the environment so that the KSRC points to the - meta-kernel-dev, thus pulling source from a local area. - This setup can speed up development time. - - - - To get set up you need to do two things: create a local Git repository - of the poky-extras repository, and create a bare clone of the - Linux Yocto 2.6.37 kernel Git repository. - - - - The following transcript shows how to clone the poky-extras - Git repository into the current working directory, which is poky - in this example. - The command creates the repository in a directory named poky-extras: - - $ git clone git://git.yoctoproject.org/poky-extras - Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/ - remote: Counting objects: 532, done. - remote: Compressing objects: 100% (472/472), done. - remote: Total 532 (delta 138), reused 307 (delta 39) - Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done. - Resolving deltas: 100% (138/138), done. - - - - - This transcript shows how to clone a bare Git repository of the Linux Yocto - 2.6.37 kernel: - - $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37 - Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/ - remote: Counting objects: 1886034, done. - remote: Compressing objects: 100% (314326/314326), done. - remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798) - Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done. - Resolving deltas: 100% (1570202/1570202), done. - - - - - The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors - the upstream repository of the kernel. - You can effectively point to this local clone now during development to avoid - having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a - kernel change. - -
- -
- Create a Layer for Your Kernel Work - - - It is always good to isolate your work using your own layer. - Doing so allows you to experiment and easily start over should things go wrong. - This example uses a layer named meta-amixer. - - - - When you set up a layer for kernel work you should follow the general layout - guidelines as described for BSP layers. - This layout is described in the - - Example Filesystem Layout section of the Board Support Package (BSP) Development - Guide. - In the standard layout you will notice a suggested structure for recipes and - configuration information. - [WRITER'S NOTE: The meta-elc example uses an - images directory. - Currently, images is not part of the standard BSP layout. - I need to find out from Darren if this directory is required for kernel work.] - - - - [WRITER'S NOTE: I need a paragraph here describing how to set up the layer. - I am not sure if you should copy an existing BSP layer and modify from there. - Or, if you should just look at a BSP layer and then create your own files. - Email to Darren on this but no answer yet.] - -
- -
- Making Changes to Your Kernel Layer - - - In the standard layer structure you have several areas that you need to examine or - modify. - For this example the layer contains four areas: - - conf - Contains the - layer.conf that identifies the location of the recipe files. - - images - Contains the - image recipe file. - This recipe includes the base image you will be using and specifies other - packages the image might need. - recipes-bsp - Contains - recipes specific to the hardware for which you are developing the kernel. - - recipes-kernel - Contains the - "append" files that add information to the main recipe kernel. - - - - - - Let's take a look at the layer.conf in the - conf directory first. - This configuration file enables the Yocto Project build system to locate and - use the information in your new layer. - - - - The variable BBPATH needs to include the path to your layer - as follows: - - BBPATH := "${BBPATH}:${LAYERDIR}" - - And, the variable BBFILES needs to be modified to include your - recipe and append files: - - BBFILES := "${BBFILES} ${LAYERDIR}/images/*.bb \ - ${LAYERDIR}/images/*.bbappend \ - ${LAYERDIR}/recipes-*/*/*.bb \ - ${LAYERDIR}/recipes-*/*/*.bbappend" - - Finally, you need to be sure to use your layer name in these variables at the - end of the file: - - BBFILE_COLLECTIONS += "elc" - BBFILE_PATTERN_elc := "^${LAYERDIR}/" - BBFILE_PRIORITY_elc = "9" - - - - - The images directory contains an append file that helps - further define the image. - In our example, the base image is core-image-minimal. - The image does, however, need some additional modules that we are using - for this example. - These modules support the amixer functionality. - Here is the append file: - - require recipes-core/images/poky-image-minimal.bb - - IMAGE_INSTALL += "dropbear alsa-utils-aplay alsa-utils-alsamixer" - IMAGE_INSTALL_append_qemux86 += " kernel-module-snd-ens1370 \ - kernel-module-snd-rawmidi kernel-module-loop kernel-module-nls-cp437 \ - kernel-module-nls-iso8859-1 qemux86-audio alsa-utils-amixer" - - LICENSE = "MIT" - - - - - While the focus of this example is not on the BSP, it is worth mentioning that the - recipes-bsp directory has the recipes and append files for - features that the hardware requires. - In this example, there is a script and a recipe to support the - amixer functionality in QEMU. - It is beyond the scope of this manual to go too deeply into the script. - Suffice it to say that the script tests for the presence of the mixer, sets up - default mixer values, enables the mixer, unmutes master and then - sets the volume to 100. - - - - The recipe qemu86-audio.bb installs and runs the - amixer when the system boots. - Here is the recipe: - - SUMMARY = "Provide a basic init script to enable audio" - DESCRIPTION = "Set the volume and unmute the Front mixer setting during boot." - SECTION = "base" - LICENSE = "MIT" - LIC_FILES_CHKSUM = "file://${POKYBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58" - - PR = "r4" - - inherit update-rc.d - - RDEPENDS = "alsa-utils-amixer" - - SRC_URI = "file://qemux86-audio" - - INITSCRIPT_NAME = "qemux86-audio" - INITSCRIPT_PARAMS = "defaults 90" - - do_install() { - install -d ${D}${sysconfdir} \ - ${D}${sysconfdir}/init.d - install -m 0755 ${WORKDIR}/qemux86-audio ${D}${sysconfdir}/init.d - cat ${WORKDIR}/${INITSCRIPT_NAME} | \ - sed -e 's,/etc,${sysconfdir},g' \ - -e 's,/usr/sbin,${sbindir},g' \ - -e 's,/var,${localstatedir},g' \ - -e 's,/usr/bin,${bindir},g' \ - -e 's,/usr,${prefix},g' > ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME} - chmod 755 ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME} - } + 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 yocot-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” - - - - The last area to look at is recipes-kernel. - This area holds configuration fragments and kernel append files. - The append file must have the same name as the kernel recipe, which is - linux-yocto-2.6.37 in this example. - The file can SRC_URI statements to point to configuration - fragments you might have in the layer. - The file can also contain KERNEL_FEATURES statements that specify - included kernel configurations that ship with the Yocto Project. - -
-
-
+ 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). + 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: + + $HOME/poky/meta-intel/meta-mymachine + + + + + + The appendix + + Reference: Variables Glossary in the Yocto Project Reference Manual has more information + on configuration variables. +
- +
+ Building the Image + + The Yocto Project uses the BitBake tool to build images based on the type of image + you want to create. + You can find more information on BitBake + here. + - - + + The build process supports several types of images to satisfy different needs. + When you issue the BitBake command you provide a “top-level” recipe that essentially + starts the process off of building the type of image you want. + - + +