Filed in: RaspberryPi.Software · Modified on : Sat, 04 Apr 15

Your Trail: RaspberryPi/Software

Edit this page to change styles

--- Boxes and outlines ---

--- Headers beyond ordinary "!" level headers

--- Stegi specific stylings ---

--- Text warnings, notices, hilights ---

--- Directory paths ---

--- Calendar specific ---

PiBox Development Platform Software Development Guide

A customizable embedded distribution for the Raspberry Pi.

1. Repositories and External Information

The information on this page describes the build system for the PiBox Development Platform. This platform is designed to allow users to create their own software distribution for a Raspberry Pi.

The PiBox Development Platform is the software platform for both the PiBox Media Server and the PiBox Media Player.

1.1. Basic System Build Process

  1. Configure the shell environment
  2. Setup build system prerequisites
  3. Build or acquire a toolchain
  4. Grab firmware files for Raspberry Pi
  5. Build a Linux kernel and its associated driver modules
  6. Retrieve and build the OpenGL package
  7. Build a root file system
  8. Copy driver modules to root file system
  9. Create or acquire configuration text files required by firmware
  10. Format an SD card with FAT32 and ext2 partition
  11. Copy firmware, text files and kernel image to first SD partition
  12. Copy rootfs to second SD partition
  13. Boot the board with the SD card

Additional firmware files may be needed for other hardware, such as wifi adapters. This firmware should not be confused with the firmware required by the Raspberry Pi for booting and video support.

1.2. Build System Basics

To use the build system, you should load the cdtools shell function.

Configure environment for PiBox builds
cp docs/ ~/bin/env/rpi
vi ~/bin/env/rpi
<edit lines as appropriate>
source ~/bin/env/rpi

If you don't already have the source tree cloned then you can grab the shell function directly from gitorious' raw blob data.

To get help with the build system and the many available targets, use the help target

Getting Build Help
make help

All software components have identical (or nearly identical) sets of targets of the following format.

Common build targets
make <component>
make <component>-pkg
make <component>-clean
make <component>-clobber

2. Build system prerequisites

PiBox is designed to be built on Linux systems. It is not supported on Windows, Cygwin or Macs. *BSD users can contact me about adding support for their platforms.

Linux Distribution Version Status Prerequisites
Fedora 16 Working

Configure the following repositories:

  • RPMFusion

Required package groups

  • Development Tools
  • Development Libraries

Other Packages

  • gperf makeinfo texinfo glibc-static redhat-lsb perl-Switch libstdc++-static ncurses-devel
17 Untried
18 Untried (not recommended)
19 Working with Crosstool-NG 1.19.0

Crosstool-NG pre 1.19.0 ppl build fails. This is because the ppl build relies on the build hosts gmp installation. Fedora 19 has gmp 5.1.1. But this incompatible with the most recently available version of PPL (0.11.2) that you can configure in Crosstool-NG. This is true for all versions of Crosstool-NG from 0.15.2 to 0.18.0. This is fixed in Crosstool-NG 1.19.0.

Configure the following repositories:

  • RPMFusion

Required package groups

  • Development Tools
  • Development Libraries

Other Packages

  • gperf makeinfo texinfo glibc-static redhat-lsb perl-Switch libstdc++-static ncurses-devel gmp-devel python-devel expat-devel cmake
20 Working with Crosstool-NG 1.19.0 Same issues as fedora 19, with updated packages list. Mercurial and freetype-devel are needed for Buildroot 2015.02.

Configure the following repositories:

  • RPMFusion

Required package groups

  • Development Tools
  • Development Libraries

Other Packages

  • gperf makeinfo texinfo glibc-static redhat-lsb perl-Switch libstdc++-static ncurses-devel gmp-devel python-devel expat-devel cmake freetype-devel mercurial
CentOS 6.2 Working

Configure the following repositories:

  • EPEL (See RPMFusion site)
  • RPMFusion

Required package groups

  • Development Tools
  • Development Libraries

Other Packages

  • gperf texinfo glibc-static redhat-lsb perl-Switch libstdc++-devel
6.3 Working

Configure the following repositories:

  • EPEL (See RPMFusion site)
  • RPMFusion

Required package groups

  • Development Tools
  • Development Libraries

Other Packages

  • gperf texinfo glibc-static redhat-lsb perl-Switch libstdc++-devel
6.4 Testing

Configure the following repositories:

  • EPEL (See RPMFusion site)
  • RPMFusion

Required package groups

  • Development Tools
  • Development Libraries

Other Packages

  • gperf texinfo glibc-static redhat-lsb perl-Switch libstdc++-devel expat-devel
Ubuntu 12.10 Working

Other packages

  • build-essential git bison flex gperf texinfo libtool automake ncurses-dev gawk libexpat-dev python-dev gettext subversion cmake


  1. installation of gawk may cause issues with system scripts that use mawk. Fix this with
    sudo update-alternatives --config awk
  2. You must have /bin/sh point to /bin/bash, not the default shell (dash). Use this command:
    sudo dpkg-reconfigure dash

2.1. Integration with XBMCBox

XBMCBox is an installable package that can be used with PiBox. If you plan on using PiBox as the core platform for XBMCBox, you're build system should be a 32bit platform. Building PiBox on a 64bit system and then building XBMCBox to use with it will fail because Python dependencies in XBMC require the build system to have the same bitness as the target system (the Raspberry Pi, which is 32bit).

XBMCBox is a work in progress. It is not yet fully functional on PiBox. The PiBox Media Server opkg extensions are designed as a lightweight alternative to using XBMC.

3. Cross Toolchain

This information is based on information gathered from lots of net-surfing and a basic understanding of the Crosstool-NG configuration process. It is unverified at this time though the toolchain does build and generates an untested kernel image. As soon as I get my SD card build set up properly, I'll be able to test the toolchain by testing the kernel boot.

You can use available toolchains such as CodeSourcery's. However, if you want to build your own, using tools such as Crosstool-NG, you should note the following.

  1. Architecture Level: armv6k
  2. Emit Assembly for: arm1176jzf-s
  3. Tune for: arm1176jzf-s
  4. FPU: vfp
  5. Use MMU: yes
  6. Binutils version: 2.21.1a
  7. GCC version: Linaro 4-7-2012.07
  8. GCC core extra config: --with-fpu=vfp --with-float=hard
  9. GCC extra config: --with-fpu=vfp --with-float=hard

There are some possible configurations available from the RaspberryPi Tools repository as well as frgodzilla's, which includes a Buildroot configuration as well.

Which libc you choose for your toolchain is a personal matter. I'm using glibc as opposed to uClibc due to some applications that are sometimes difficult to compile with the latter, such as Connman. I'm using glibc 2.13.

3.1. To build with PiBox:

Current Crosstool-NG version: 1.15.2

Build PiBox cross toolchain and install it
make xcc
make xcc-pkg
sudo rpm -ivh rpiToolchain*

Change the first line to specify the alternate version of Crosstool-NG.

make XV=1.19.0 xcc

Be sure to source the shell function script under docs before running any PiBox builds:

 vi docs/
 <edit lines as appropriate>
 source docs/

Also, building the RPM is not required, but recommended if you plan on doing any application development outside of the PiBox tree.

3.2. Verification

Check your cross compiler configuration:

Check your cross compiler configuration
% /opt/rpiTC/bin/arm-unknown-linux-gnueabi-gcc --version --verbose
Using built-in specs.
arm-unknown-linux-gnueabi-gcc (crosstool-NG 1.16.0 - PiBox 0.1.0) 4.6.4 20120630 (prerelease)
Copyright (C) 2011 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO

Target: arm-unknown-linux-gnueabi
Configured with: /home/mjhammel/src/ximba/raspberrypi/src/../bld/crosstool-ng-1.16.0.bld/work/src/gcc-linaro-4.6-20
12.07/configure --build=x86_64-build_unknown-linux-gnu --host=x86_64-build_unknown-linux-gnu --target=arm-unknown-l
inux-gnueabi --prefix=/home/mjhammel/src/ximba/raspberrypi/src/../bld/crosstool-ng-1.16.0.bld/install --with-sysroo
 --enable-languages=c,c++ --with-arch=armv6 --with-fpu=vfp --with-float=hard --with-pkgversion='crosstool-NG 1.16.0
 - PiBox 0.1.0' --enable-__cxa_atexit --disable-libmudflap --disable-libgomp --disable-libssp --disable-libquadmath
 --disable-libquadmath-support --with-gmp=/home/mjhammel/src/ximba/raspberrypi/src/../bld/crosstool-ng-1.16.0.bld/w
ork/arm-unknown-linux-gnueabi/buildtools --with-mpfr=/home/mjhammel/src/ximba/raspberrypi/src/../bld/crosstool-ng-1
.16.0.bld/work/arm-unknown-linux-gnueabi/buildtools --with-mpc=/home/mjhammel/src/ximba/raspberrypi/src/../bld/cros
stool-ng-1.16.0.bld/work/arm-unknown-linux-gnueabi/buildtools --with-ppl=/home/mjhammel/src/ximba/raspberrypi/src/.
./bld/crosstool-ng-1.16.0.bld/work/arm-unknown-linux-gnueabi/buildtools --with-cloog=/home/mjhammel/src/ximba/raspb
errypi/src/../bld/crosstool-ng-1.16.0.bld/work/arm-unknown-linux-gnueabi/buildtools --with-libelf=/home/mjhammel/sr
c/ximba/raspberrypi/src/../bld/crosstool-ng-1.16.0.bld/work/arm-unknown-linux-gnueabi/buildtools --with-host-libstd
cxx='-static-libgcc -Wl,-Bstatic,-lstdc++,-Bdynamic -lm -L/home/mjhammel/src/ximba/raspberrypi/src/../bld/crosstool
-ng-1.16.0.bld/work/arm-unknown-linux-gnueabi/buildtools/lib -lpwl' --enable-threads=posix --enable-target-optspace
 --disable-nls --disable-multilib --with-local-prefix=/home/mjhammel/src/ximba/raspberrypi/src/../bld/crosstool-ng-
1.16.0.bld/install/arm-unknown-linux-gnueabi/sysroot --enable-c99 --enable-long-long --with-fpu=vfp --with-float=ha

And then test the compiler by building the following Hello World example, copying it to the rootfs of an existing distribution (such as Raspbian) and running it.

Hello World test program
#include <stdio.h>
int main() { printf("Hello, world!\n"); return 0; }
Compile test program
/opt/rpiTC/bin/arm-unknown-linux-gnueabi-gcc -o test test.c
Verify binary format
% file test
test: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 3.2.16, not stripped

4. Bootloader

The Raspberry Pi doesn't use a traditional bootloader, such as u-boot. Instead, the GPU knows how to access the SD card at power up. It reads binary blobs from the FAT partition on the SD card and uses it to initialize itself, the CPU and the rest of the board to the point that it can then load a Linux kernel image from the SD card's FAT partition.

The binary blobs are available from the Firmware GIT tree:

  • Firmware - GPU firmware and vidcore files

4.1. Firmware GPU configuration

The firmware's display characteristics can be configured using a text file. The text file is copied into the boot directory of the SD card along with the binary firmware. This file must be named config.txt. A sample version of this file, with all options commented out, is included in the PiBox Build.

4.2. To build with PiBox:

Build PiBox cross toolchain and install it
make rpifw
make rpifw-pkg

The binary firmware files will be downloaded and copied into the package directory (see cdp in the

5. Kernel

The Linux kernel used on Raspberry Pi comes from a custom git tree on The tree is currently based on kernel version 3.2.27 with unknown additional patches.

The kernel configuration required can be retrieved by booting a Raspbian image (or other existing distribution for the Raspberry Pi) and copying the output from

   cat /proc/config.gz

to a file that you can integrate into your own kernel build. Note that not every distribution is required to have /proc/config.gz. An alternative is to use the bcmrpi_cutdown_defconfig configuration in the Raspberry Pi kernel git tree and build up your own configuration from there.

After the kernel build completes, you'll need to copy the kernel image to your SD card. The source image to use in this copy is

    <linux source tree>/arch/arm/boot/Image

This file must be copied to the first partition on the SD card.

5.1. Kernel command line options

The Linux kernel can be fed command line options at boot time. Normally, a bootloader passes these options to the kernel. For the Raspberry Pi, a text file with the command line options is placed on the boot partition of the SD card along with the binary firmware and the Linux kernel image. This file must be named cmdline.txt. A sample version of this file, with required configuration options specified, is included in the PiBox Build.

5.2. To build with PiBox:

Build PiBox Linux kernel
make XI=/opt/rpiTC kernel
make XI=/opt/rpiTC kernel-pkg

Alternatively, you can use the toolchain you just built with the xcc targets. The default is to use the default version of Crosstool-NG, so the kernel build would look like this.

make kernel

If you use a different version of Crosstool-NG you can specify it on the kernel build command.

make XV=1.19.0 kernel

The compiled kernel image will be copied into the package directory as kernel.img, which is required by the cmdline.txt file.

The kernel build may fail while working on firmware ti_3410.fw. If this happens, just rerun the build command and it will finish on its own.

6. VidCore / OpenGL / GLES

6.1. VidCore

The VidCore blobs are binaries that allow user space access to hardware accelerated video playback and OpenGL-based displays. Note that video playback (re: video decoding) is a separate issue from OpenGL display. These require separate software support that provide access to different hardware components.

The Raspberry Pi firmware git repository also includes the binary files required to make use of the video subsystems.

These binary blobs are built using a toolchain that uses hardfp support. In order to use these in your own Raspberry Pi system, your toolchain must also support hardfp. Toolchains that support softfp will not work with these files.

Additionally, there are userlands components to assist in using the hardware acceleration.

The VidCore binary blobs are included with the boot firmware and are picked up automatically by the root file system build. There are no additional steps required to get these into the PiBox build.

6.2. OpenGL / GLES Userspace

There is a userspace library and toolset that wraps the binary firmware blobs to provide OpenGL support for the Raspberry Pi. The userspace code is available from a public GIT repository. PiBox will download this repository and build the userspace libraries and tools in such a way that they can be easily picked up by the root file system build.

6.2.1. To build with PiBox:

Build OpenGL
make XI=/opt/rpiTC gles

The GLES target must be built before you build the root file system or the root file system build will generate an error. Also, the -pkg target is not needed with the gles component because the root file system build will integrate the gles build artifacts directly into the root file system.

7. Root File System

The root file system is the collection of files and directories that make up your runtime system. Generally speaking, any root file system can be used for Raspberry Pi as long as it was generated using the same cross toolchain. To build your own, try BusyBox and/or Buildroot. There is a default buildroot configuration available from Nezticle's RaspberryPi-Buildroot git repository or you can try frgodzilla's, which includes a Crosstool-NG configuration as well.

PiBox's Buildroot configuration is designed specifically around building the root file system. It does not use Buildroot to build the cross toolchain or the Linux kernel (although Buildroot can do handle these components as well). The structure and contents of the root file system is specifically targeted at media services, so it contains libraries and files that would be helpful on systems supporting multimedia playback.

7.1. To build with PiBox:

Build PiBox root file system
make XI=/opt/rpiTC buildroot
make XI=/opt/rpiTC buildroot-pkg

The a tar archive of the root file system will be copied into the package directory as ramdisk.tar. This file will be unpacked onto the SD card with the script.

The use of the XI environment variable on the make command line in this example is not required if you have previously built and not cleared the cross toolchain (xcc target). It is shown here as an example of how to use the toolchain from its installed location.

8. DSP

There is a DSP on the Raspberry Pi, but information is not yet available for how to programmatically access it directly (ie direct hardware access without a third party library). However, The VidCore library files provide video decoding support that utilizes the DSP for video playback tools.

9. SD Card format

The minimum requirements for the Raspberry Pi SD card are as follows:

  1. First partition: FAT32
  2. Second partition: root file system (format depends on what the Linux kernel is configured to support, but EXT2 recommended to avoid journaling issues which can reduce the lifespan of the SD card).

9.1. First partition contents

The following items were identified from a Raspbian SD image.

  • arm128_start.elf
  • arm192_start.elf
  • arm224_start.elf
  • arm240_start.elf
  • start.elf
  • bootcode.bin
  • loader.bin
  • cmdline.txt
  • config.txt
  • issue.txt
  • kernel.img
  • kernel_cutdown.img
  • kernel_emergency.img


  1. The arm*.elf files may not be required. The start.elf is the only file in the current firmware git tree (see Bootloader)
  2. start.elf purpose is the GPU firmware image
  3. bootcode.bin purpose is a 2nd stage bootloader that starts with SDRAM disabled
  4. loader.bin purpose is a 3rd stage bootloader that starts with SDRAM enabled. It is not included in the current firmware git tree (see Bootloader) but may not be required
  • cmdline.txt contains kernel boot arguments, similar to uEnv.txt for the BeagleBoard.
  • config.txt contains bootloader configuration information, such as display settings.
  • issue.txt contains comments about the ancestory of these files (who built them, when, etc.)
  • kernel* are Linux kernel images. There various purposes are TBD. The kernel image format is the standard Image file generated by a kernel build.

9.2. Building SD card with PiBox

Be sure to have your SD card installed in an SD card slot. I use USB adapters with SD card readers, which makes the SD card show up as device /dev/sdb<1 or 2> or /dev/sdc<1 or 2>. Other systems with built in SD card readers may show the device as /dev/mmcblk0p<1 or 2>.

Build PiBox SD Card
make pkg-scripts
sudo ./mksd /dev/<sd device>
sudo mkdir -p /media/boot
sudo mount /dev/<sd device partition 1> /media/boot
sudo ./mkinstall -b /media/boot -d /dev/<sd device partition 2>

This process forces you to mount one partition but then specify the device name for the second partition. This is done to ensure you are not accidently trashing the wrong device.

10. Installable packages

PiBox uses opkg formatted files for package management. The distribution is not fully package managed, but you can install and remove package to/from the /opt directory using the opkg-cl command.

10.1. Build and install OPKG

To build opkgs you'll need the opkg-build command. If you don't have that, PiBox can build and install it for you. Use the following commands to build and install opkg.

Build and install OPKG package management on your build host
make opkg-verify
make opkg
make opkg-install

The first command will test if opkg-build is installed under /usr/local/bin. The second command will download and build opkg for you. The last command will install it under /usr/local/bin. The last command must be run as the root user.

10.2. Debug Utilities

The PiBox build currently has only one package that can be installed after the PiBox system is running. That is a debug utilities package from the cross toolchain build. To create the package, you must first compile the cross toolchain. Then run the following command to create an opkg of the debug utilities.

Build debug utilities package
make xcc-opkg
make xcc-opkg-pkg
ls -l *.opk

The displayed file must be copied to the root file system on the target and then installed. You can copy the file using scp if you have wireless or wired networking configured. Alternatively, you can load the SD card in your build system and copy the file manually to the SD card.

To install the package after booting the PiBox build on your Raspberry Pi, change to the directory you copied the package to. Then run the following command:

opkg-cl -f /etc/opkg/opkg.conf install <packagename>

The <packagename> should be xcc-debug_1.15.2_arm.opk or similar, depending on if the cross toolchain has been recently updated or not. After installation, the installed utilities can be found under /opt/debug-root.

The debug utility package includes the following tools:

 # ls -l /opt/debug-root/usr/bin
 -rwxr-xr-x    1 3123     3123         72347 Mar 24 07:37 dmalloc
 -rwxr-xr-x    1 3123     3123       5831726 Mar 24 07:37 gdb
 -rwxr-xr-x    1 3123     3123       1289666 Mar 24 07:37 gdbserver
 -rwxr-xr-x    1 3123     3123        494374 Mar 24 07:37 strace
 -rwxr-xr-x    1 3123     3123          8287 Mar 24 07:37 strace-graph

11. Important Tips

It's possible to modify various parts of the build using environment variables. Most of these can be seen with the help target. Some of the ones to be aware of are listed here.

  • JOBS: set this twice the number of processor cores you have. The default is 8, but that's for a quad-core processor. If

you're building on your laptop you might want to drop this to two. The default can cause build errors on systems with fewer cores.

Example: make JOBS=2 buildroot
  • ?V: Set the version of a particular component. The ? is replaced by a component letter: K for kernel, X for the

cross toolchain.

Example: make XV=1.18.0 xcc
  • ?R: Set the release of a particular component. The ? is replaced by a component letter: B for Buildroot. This is essentially

the same as the ?V variable, but applies only to Buildroot.

Example: make BR=2013.02 buildroot
  • XI: Set the directory of the toolchain. The PiBox cross toolchain build directories are used by default. If you haven't built

this, or you've built it into an RPM and installed it or you're using a different toolchain, set XI.

Example: make XI=/opt/rpiTC buildroot
  • OPKG: Set the directory where opkg-build is installed. The default is /usr/local/bin.


Font Size

Powered by PmWiki