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-<version>/linux-2.6.11. This folder con- tains the standard Linux source tree. From here, use menuconfig as normal to configure the kernel parameters: % cd ~/travis-dev-kit/tmp/work/linux-alchemy-2.6.11-r000058/linux-2.6.11 % make menuconfig 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.