Open Embedded: An alternative way to build embedded Linux distributions

Nick Lethaby and Denys Dmytriyenko, Texas Instruments

August 3, 2011

Nick Lethaby and Denys Dmytriyenko, Texas Instruments

OE Configuration Files
Configuration files fall primarily into two classes: machine configuration and distribution (distro) configuration. There is also a local configuration file and a file called bitbake.conf. bitbake.conf is the first file read by BitBake and includes all the other configuration files. In addition, it defines many global variables and is called bitbake.conf. It is not recommended to modify bitbake.conf directly, but rather place overrides either in the distro or local configurations. Machine configuration files define the particular boards being targeted. Distribution configuration files define a specific Linux distribution (e.g. a set of specific package versions) for one or more machines.

The distro configuration file is the best place to make global settings that apply to all the images generated from the distribution. OE enables developers to override these settings for particular images or packages, providing flexibility if there are special cases to handle. For example, the local.conf (local configuration) file is usually used to contain user-specific configurations to slightly modify default distro configuration settings. We will overview some of the additional configuration settings made in the Arago local.conf file once we have discussed the distro and machine configuration files in further detail.

The distro configuration file specifies a number of basic ‘housekeeping’ parameters (see Listing #5) such as the name of the distro, directories where sources are downloaded and built packages are stored, and the supported file formats for the uImage:

Listing #5: Configuration File Snippet

# For now Arago is not big enough to warrant a separate distribution,
# reuse Angstrom, but set the name to Arago
DISTRO = "angstrom-2008.1"

# Set the distro name and version, since we now produce own SDK
DISTRO_NAME = "Arago"
DISTRO_VERSION = "2010.05"
BUILDNAME = "${DISTRO_NAME} ${DISTRO_VERSION}"

# Use this to specify where BitBake should place the downloaded sources into
DL_DIR = "${SCRATCH}/downloads"

# Put resulting images and packages in deploy directory outside of temp
#DEPLOY_DIR = "${OEBASE}/arago-deploy"
……

# Add the required image file system types below. Valid are
# jffs2, tar(.gz|bz2), cpio(.gz), cramfs, ext2(.gz), ext3(.gz)
# squashfs, squashfs-lzma
IMAGE_FSTYPES = "jffs2 tar.gz ext2.gz"

The distro configuration file also specifies which machines the distro will be built for, although the details of booting Linux for each machine are contained in the machine configuration files. Since the distro configuration is where tool chain versions are specified, supporting a large number of machines tends to cause the file to become more complex. For example, it may be necessary to specify multiple glibc patches or different toolchain versions to accommodate all different machines. Other architecture-related items that may need to be specified in the distro config file include hardware v. software floating-point, whether different instruction sets (ARM v. Thumb) are supported, and various addressing modes that may not work well for some of the packages included in the distro.

Selection of package versions is one of the more important functions commonly found in distro configuration files and helps ensure known compatible versions are used. There are a number of ways in which versions may be selected. If no version is specified the latest version is selected. Similarly, it is possible to specify a version that is “n revs behind” the most recent release. For packages where a specific version is desired, a default preferred version can be specified for the whole distribution in the distro config file, as illustrated (see Listing #6) in the snippet from the Angstrom distro configuration file.

Listing #6: Distro Configuration File Snippet

ANGSTROM_QT_VERSION ?= "4.6.2"
CE_VERSION ?= "latest"

PREFERRED_VERSION_autoconf = "2.65"
PREFERRED_VERSION_autoconf-native = "2.65"
PREFERRED_VERSION_automake-native = "1.10.3"
PREFERRED_VERSION_busybox       = "1.13.2"
PREFERRED_VERSION_glib-2.0      = "2.24.0"
PREFERRED_VERSION_glib-2.0-native = "2.24.0"

Another important function of a distribution is providing a set of feeds that enable access to pre-built binary packages. A distribution typically uses the binary feeds to dynamically load new packages at run-time. To add packages in a robust manner, distributions incorporate a package management system. The Angstrom distribution, for example, began with the ipkg package manager (it recently switched to opkg), as this has some advantages for space-constrained embedded applications compared to desktop package managements like dpkg or RPM. ipk format was originally based on deb format and is handled by either ipkg or opkg package managers, opkg being the newer and preferred one. The package format results in additional metadata being stored in the package. This ensures incompatible packages are not loaded and that the correct run-time dependencies will be brought in as well. Arago defines its own feeds of pre-built IPKs (see Listing #7), but it may not have the widest variety of packages. In cases where more packages are needed, the Angstrom feeds can be enabled, although caution is required when mixing different feeds.

Listing #7: Distro Configuration File Snippet

ANGSTROM_PKG_FORMAT ?= "ipk"
require conf/distro/include/
angstrom-package${ANGSTROM_PKG_FORMAT}.inc
#Use this variable to select which recipe you want to use to 
#get feed configs (/etc/ipkg/, #/etc/apt/sources.list). Useful 
#for derivative distros and local testing
ANGSTROM_FEED_CONFIGS = "arago-feed-configs"

# Feed configuration
ARAGO_URI = "http://feeds.arago-project.org"
ARAGO_FEED_BASEPATH = "feeds/live/${ANGSTROM_PKG_FORMAT}"
DISTRO_FEED_URI = "${ARAGO_URI}/${ARAGO_FEED_BASEPATH}"

Many other general build parameters may be set in the distro config file. For example, the developer can specify that builds with additional debug or profiling information are done as a standard procedure. Such lines can be commented out or overridden by a “production code” image recipe to improve performance in the final production:

Listing #8: Distro Configuration File Snippet

# Comment these two out if you want BitBake to build 
# production images. 
DEBUG_BUILD = "1"
INHIBIT_PACKAGE_STRIP = "1"

# Build a package such that you can use gprof to profile it.
PROFILE_OPTIMIZATION = "-pg"
SELECTED_OPTIMIZATION = "${PROFILE_OPTIMIZATION}"
LDFLAGS =+ "-pg

Machine configuration files define the basics needed to boot Linux onto the board. For example, the target CPU, such as ARM926 or ARM Cortex-A8, is defined along with the preferred recipe provider for the Linux kernel and the appropriate bootloader, as in Listing #9 which shows the DM365 machine configuration file that is used for an ARM9-based video device from TI.

Listing #9: Machine Configuration File

#@TYPE: Machine
#@NAME: DM365 CPUs on a Davinci DM365 EVM board
#@DESCRIPTION: Machine configuration for the TI Davinci 
DM365 EVM board

require conf/machine/include/dm365.inc
require conf/machine/include/tune-arm926ejs.inc

# Increase this everytime you change something in the kernel
MACHINE_KERNEL_PR = "r45"

TARGET_ARCH = "arm"

KERNEL_IMAGETYPE = "uImage"

PREFERRED_PROVIDER_virtual/kernel = "linux-davinci-staging"

PREFERRED_PROVIDER_virtual/bootloader = "u-boot"
UBOOT_MACHINE = "davinci_dm365_evm_config"

UBOOT_ENTRYPOINT = "0x80008000"
UBOOT_LOADADDRESS = "0x80008000"

EXTRA_IMAGEDEPENDS += "u-boot"
SERIAL_CONSOLE ?= "115200 ttyS0"

EXTRA_IMAGECMD_jffs2 = "--pad --little-endian 
--eraseblock=0x20000 -n"

#ROOT_FLASH_SIZE = "29"

MACHINE_FEATURES = "kernel26 serial ethernet usbhost 
usbgadget mmc alsa"

Machine configuration files will be needed for each board. Since configuration steps for different boards using the same or similar devices will often be the same, in practice the common steps can be coalesced into include files. This simplifies creating new machine configuration files in an error-free and easy-to-maintain manner. In the above example, we ‘exploded’ some of the include files to give a more meaningful representation of what the full machine configuration file would look like.