AMD Alchemy™ DBAu1200™ Development Board OpenEmbedded Quick Start Guide
1.0 Overview OpenEmbedded (OE) is a repository of metadata that includes information on how to obtain and build various software packages, as well as classes to abstract common steps in the build process. BitBake is a tool derived from Portage, the package management system for the Gentoo Linux distribution, which is used by OpenEmbedded to automate the task of building software packages. This document discusses use of OE and BitBake, in conjunction with the AMD Alchemy™ Au1200™ OE Development Kit, to create a Linux 2.6 image for the AMD Alchemy™ DBAu1200™ development board. Note: This is revision B of this document. The change from revision A (dated January 2006) is the document has been completely reorganized and the titled changed from AMD Alchemy™ DBAu1200™ Development Board Modifica- tions.
2.0 Prerequisite Software OE/BitBake development requires the use of an x86 Linux host PC. Unless otherwise specified, all actions in this document are to be performed on the host PC. Before building an image using OE/BitBake, ensure that the host PC is equipped with all software packages required for development. A list of prerequisite packages is located on the OE Wiki: http://oe.handhelds.org/cgi-bin/moin.cgi/RequiredSoftware The Wiki entry also contains detailed setup instructions for certain packages on certain Linux distributions. Most of the required packages are installed by default or available through the system’s package manager, depending on the host PC’s Linux distribution. For packages unavailable through the system’s package manager, follow the installation guidelines spec- ified on the package’s homepage.
3.0 Installing OE/BitBake Once the prerequisite software packages are installed, set up OE/BitBake on the host PC. Though this document describes the necessary steps to set up and build a basic image using OE/BitBake, developers are encouraged to read through OpenEmbedded’s Getting Started guide (http://oe.handhelds.org/cgi-bin/moin.cgi/GettingStarted) to familiarize themselves with OE.
3.1 Obtain OE Development Kit The AMD Alchemy™ Au1200™ OE Development Kit, available from the AMD Embedded Developer Support web site, is a collection of modifications to the OE metadata that tailors the OE build to the DBAu1200 development platform. To install, extract the archive to a suitable work location (this document assumes the user’s home directory, ~/): % cd ~ % tar xzf au1200-dev-kit_v1.0-r3.tar.gz
3.2 Obtain BitBake BitBake is obtained using the Subversion version control system, as described on the OE Wiki (http://oe.handhelds.org/cgi- bin/moin.cgi/GettingStarted#head-edc470c3655ac7ebac7ae7928ea574819170fa1b). BitBake does not need to be installed to the system, and can be run directly from the OE working directory. Check out BitBake from Subversion into the development kit base directory: % cd ~/travis-dev-kit % svn co svn://svn.berilos.de/bitbake/trunk/bitbake There should now be a bitbake/ directory within ~/travis-dev-kit/. This directory contains the BitBake tools used by OE.
40351B - April 2006 - Confidential 1 Application Note
40351B - April 2006 - Confidential
3.3 Obtain OpenEmbedded OE is obtained using the Monotone version control system, as described on the OE Wiki (http://oe.handhelds.org/cgi- bin/moin.cgi/GettingStarted#head-1c5adf3b1f1467ec9bcb48b5a34c18632557c3c4). Before checking out the OE files, a Monotone database must be built. Building the database from scratch is time intensive, therefore, the recommended method is to download a snapshot of the database from http://ewi546.ewi.utwente.nl/OE/OE.db.bz2, which can then be updated when necessary. Download and extract the bzip archive, then rename the extracted file to “oe.db”: % cd ~/travis-dev-kit % wget http://ewi546.ewi.utwente.nl/OE/OE.db.bz2 % bunzip2 OE.db.bz2 % mv OE.db oe.db Once the database has been obtained, check out OE using Monotone: % cd ~/travis-dev-kit % monotone --db=oe.db checkout --branch=org.openembedded.dev There should now be an org.openembedded.dev/ directory within ~/travis-dev-kit/ directory. This directory contains the metadata and scripts that comprise OE.
3.4 Configure OpenEmbedded Before OE can be used to build Linux for the DBAu1200 development board, AMD-specific modifications must be made to the OE tree. First, copy the example local.conf file from the OE tree to the base directory: % cd ~/travis-dev-kit % cp org.openembedded.dev/conf/local.conf.sample conf/local.conf Modify the following values in the newly created local.conf file: DL_DIR="${TOPDIR}/sources" BBFILES="alchemy/packages/*/*.bb org.openembedded.dev/packages/*/*.bb" DISTRO="travis" MACHINE="db1200" PREMIRROR=${CVS_TARBALL_STASH} After the values have been modified, remove the line containing “REMOVE_THIS_LINE”. To build with uClibc instead of glibc, change the value of DISTRO as follows: DISTRO="travis-uclibc" Next, apply the patches to the OE tree contained in the AMD Alchemy™ Au1200™ OE Development Kit: % cd ~/travis-dev-kit % for foo in *.patch; do patch –p1 < $foo; done Note any patches that failed during the process. The OE tree is checked out from a revision control repository that is updated in real-time, therefore, AMD-provided patches may contain references that are out of date. Any failed patches must be resolved by hand by comparing the newly patched file (filename), the original file (filename.orig), and the rejected hunks of the patch (filename.rej), then manually entering the changes from the reject file to the patched file. Once the changes are made, the original file and reject file may be safely removed. In the past, the differences causing patch failure have generally been minor, resulting from format changes or relocation of specific blocks. However, developers are encouraged to report any substantial changes causing patch failure to their local AMD representative for resolution.
2 AMD Alchemy™ DBAu1200™ Development Board OpenEmbedded Quick Start Guide Application Note
40351B - April 2006 - Confidential
3.5 Obtain AMD Source OE is designed to automatically obtain the source code for the packages it builds from publicly accessible web locations during the build process. Since AMD’s kernel and MAI source are not stored in a publicly-accessible location, they must be acquired manually from the AMD Embedded Developer Support web site and placed in a location that OE can reference. The ~/travis-dev-kit/files/ directory is used for this purpose. % cp linux-alchemy-src-2.6.11-r00058.tar.gz ~/travis-dev-kit/files % cp amdms2-1.0-01.02.75-src.tar.gz ~/travis-dev-kit/files Once the source packages have been placed in the files/ directory, update the OE configuration files to point to the correct version of the AMD source archives. For the filenames listed above, make the following modifications to the file ~/travis-dev- kit/alchemy/packages/linux/linux-alchemy_2.6.11.bb: PR = "r000058" AMD_DRIVER_VERSION="00.00.58" For the files in the example above, make the following modifications to the file ~/travis-dev-kit/alchemy/pack- ages/mae/amdms2_2.6.11.bb: PR = "r010275" AMD_DRIVER_VERSION = "01.02.75" SRC_URI="file://${TOPDIR}/files/amdms2-1.0-${AMD_DRIVER_VERSION}-src.tar.gz \
4.0 Building the Image Once installation is complete, BitBake may be used to build a Linux system for the DBAu1200 development board. Perform the build as a normal user (not as root). No part of the build process should require super-user privileges. Before building, set the environment variable, BBPATH, to point to the location of the “.bb” files, and add the BitBake executable directory to the path: % cd ~/travis-dev-kit % export BBPATH=`pwd`:`pwd`/alchemy:`pwd`/org.openembedded.dev % export PATH=`pwd`/bitbake/bin:$PATH Finally, to build a complete Linux image for the DBAu1200, run BitBake with the DBAu1200 meta-package: % bitbake travis-db1200-2.6 BitBake then downloads and compiles each of the individual packages specified for the travis-db1200-2.6 target. This is a time intensive process. Once the build is complete, the complete Linux system is available in the directory ~/travis-dev- kit/tmp/deploy/images/. For the files in the example above, the Linux kernel is found in S-record format as linux26-db1200- 00.00.58.srec, and the root file system is found in bzipped tarball format as travis-db1200-01.03.00-r3.tar.bz2.
5.0 Using OE/BitBake Once the default build is complete, the OE build may be further tailored to suit the developer’s needs. Browse the OE Wiki for detailed documentation for working within the OE environment (http://oe.handhelds.org/cgi-bin/moin.cgi).
5.1 Configuring the Linux Kernel When building using the travis-db1200-2.6 meta-package, the kernel is automatically configured using a default configura- tion. This configuration may be changed to meet developer requirements. To change the Linux configuration, enter the Linux portion of OE’s working directory, located in tmp/work/linux-alchemy-2.6.11-
AMD Alchemy™ DBAu1200™ Development Board OpenEmbedded Quick Start Guide 3 Application Note
40351B - April 2006 - Confidential
Once the kernel has been configured as desired, save the kernel configuration and exit menuconfig. Copy the new configu- ration file to the “defconfig” file in the parent directory. The defconfig file should also be copied into the global metadata to use the configuration with fresh builds or with updated source packages: % cp .config ../defconfig % cp .config ~/travis-dev-kit/alchemy/packages/linux/files/defconfig
5.2 Adding Packages to the Build The travis-db1200-2.6 meta-package specifies individual software packages to be included in the build and on the final sys- tem. However, OE is aware of many other available packages that can be easily added to the system and built automatically by BitBake. The file ~/travis-dev-kit/alchemy/packages/meta/travis-db1200-2.6_01.03.00.bb specifies which packages are to be built into the DBAu1200 system. To add a package or meta-package to the build, add the package name to the declaration of the DEPENDS and IPKGS variables in the travis-db1200-2.6_01.03.00.bb file. The package name must be recognized by OE. A list of package names recognized by OE is found by listing the contents of the packages/ directory within the OE tree: % ls ~/travis-dev-kit/org.openembedded.dev/packages Below the DEPENDS and IPKGS declarations are additional declarations for the restricted AMD media codecs. These lines are commented-out by default, but may be un-commented to include the restricted codecs in the build if they are available. The source for the restricted codecs must be placed in the ~/travis-dev-kit/files/ directory. Additionally, the version numbers in the .bb files pertaining to those packages must be changed to reflect the version of the source available as in Section 3.5 on page 3. The .bb files are found in ~/travis-dev-kit/alchemy/packages/
5.3 Building Individual Packages with BitBake It may be desirable to simply build a single package using BitBake while bypassing the lengthy parsing phase, for instance, when debugging a failed build of a meta-package. This is accomplished by using the -b flag, and providing BitBake with the .bb file pertaining to the specific package to be built. For example, to build the aumix package, locate its .bb file within the org.openembedded.dev/packages folder and pass it to BitBake with the -b flag: % cd ~/travis-dev-kit % bitbake –b org.openembedded.dev/packages/aumix/aumix_2.8.bb Take care when building a package in this manner, as BitBake will skip all dependency checking, and an unstable system may be created.
5.4 Building Independently of OE/BitBake To build a package that is not included within the OE metadata, the developer must either create a .bb file for the package and add it to the OE tree, or build the package outside of the OE/BitBake framework. If the latter is chosen, it is recom- mended that the developer use the GCC cross-compiler built by OE/BitBake to compile the rest of the system. Once the travis-db1200-2.6 meta-package has been built, the GCC cross-compiler executables are located at ~/travis-dev- kit/tmp/cross/bin/. By adding this directory to the PATH environment variable, the OE cross-compiler may be used to build anywhere on the system by calling its binary (e.g., mipsel-linux-gcc). Note that any packages built outside of the OE/BitBake framework must be manually installed to the OE/BitBake-generated Linux image. Also note that externally built packages may need to be re-installed, or even re-compiled, when the OE/Bit- Bake image is rebuilt.
4 AMD Alchemy™ DBAu1200™ Development Board OpenEmbedded Quick Start Guide © 2006 Advanced Micro Devices, Inc. All rights reserved. The contents of this document are provided in connection with Advanced Micro Devices, Inc. (“AMD”) products. AMD makes no representations or warranties with respect to the accuracy or completeness of the contents of this publication and reserves the right to make changes to specifications and product descriptions at any time without notice. No license, whether express, implied, arising by estoppel or otherwise, to any intellectual property rights is granted by this publication. Except as set forth in AMD’s Standard Terms and Conditions of Sale, AMD assumes no liability whatsoever, and disclaims any express or implied warranty, relating to its products including, but not limited to, the implied warranty of mer- chantability, fitness for a particular purpose, or infringement of any intellectual property right.
AMD’s products are not designed, intended, authorized or warranted for use as components in systems intended for surgical implant into the body, or in other applications intended to support or sustain life, or in any other application in which the failure of AMD’s product could create a situation where personal injury, death, or severe property or environmental damage may occur. AMD reserves the right to discontinue or make changes to its products at any time without notice.
www.amd.com
TRADEMARKS AMD, the AMD Arrow logo, and combinations thereof, and AMD Alchemy, Au1200, and DBAu1200 are trademarks of Advanced Micro Devices,Inc.
Other product names used in this publication are for identification purposes only and may be trademarks of their respective companies.
One AMD Place • P.O. Box 3453 • Sunnyvale, CA 94088-3453 USA • Tel: 408-749-4000 or 800-538-8450 • TWX: 910-339-9280 • TELEX: 34-6306