Recent Changes - Search:



Deprecated

Software

Prev Next 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 ---

Software Developers Guide

A customizable embedded distribution for the Raspberry Pi.

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.

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.

Build System Basics

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

Configure environment for PiBox builds
cp docs/bashsetup.sh ~/bin/env/rpi
vi ~/bin/env/rpi
<edit lines as appropriate>
source ~/bin/env/rpi
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

Build system prerequisites

PiBox supports building in a Docker environment. Full instructions are available in the docker/README.md file in the source tree.

The build host is the system on which the PiBox Development Platform is compiled. The target system is a Raspberry Pi. The Docker environment is run from the build host. The Docker environment is configured to provide all build prerequisites.

In summary:

  1. Be sure to have installed and configured cdtools
  2. Clone the source tree: git clone https://gitlab.com/pibox/pibox.git
  3. Change into the docker directory: cd docker
  4. Build the Docker image using the build.sh script. See ./build.sh -? for usage details.
  5. Run the Docker image, which puts you at the shell prompt: sudo docker run -it --rm --privileged=true -v /home/$(whoami):/home/$(whoami) pibox_build
  6. Change back into the source tree if not already there.
  7. Perform the build.

Docker Tips

Add additional mountpoints inside the docker image with the -v option.

The --privileged=true option allows the container to use loopback devices and to mount filesystems which is required when running various -pkg targets of the build.

For machines that have SELinux turned on you may need to add :z to the end of the -v argumments to get permissions set correctly. For example, the home mount would change to: -v /home/$(whoami):/home/$(whoami):z

Docker Usage

Starting the docker image will place you in the home directory of the specified user, which is normally your home directory. You will need to change into the directory containing PiBox to run builds.

See docs/bashsetup.sh and use cdtools to manage source, build and packaging dirctories.

Quick Start

Build Everything
make pkg

To create an sd card, insert the card into the appropriate slot. Be sure to know from which device the card is accessed, such as /dev/sda1 or /dev/mmcblk0p1.

Create installable SD card
cdp (a cdtools alias)
./mksd -d <device>
mount <device><partition 1> /mnt
./mkinstall.sh -b /mnt -d <device><partition 2> -o

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.

To build with PiBox:

Current Crosstool-NG version: 1.15.2

Build PiBox cross toolchain and install it
make xcc
make xcc-pkg
cdp
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/bashsetup.sh
 <edit lines as appropriate>
 source docs/bashsetup.sh
 rpi

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

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.
COLLECT_GCC=/opt/rpiTC/bin/arm-unknown-linux-gnueabi-gcc
COLLECT_LTO_WRAPPER=/opt/rpiTC/bin/../libexec/gcc/arm-unknown-linux-gnueabi/4.6.4/lto-wrapper
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
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


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
t=/home/mjhammel/src/ximba/raspberrypi/src/../bld/crosstool-ng-1.16.0.bld/install/arm-unknown-linux-gnueabi/sysroot
 --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
rd

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

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

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.

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 bashsetup.sh).

Kernel

The Linux kernel used on Raspberry Pi comes from a custom git tree on GitHub.com. 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.

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.

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.

VidCore / OpenGL / GLES

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.

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.

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.

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.

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 mkinstall.sh 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.

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.

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).

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

Notes:

  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.

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
cdp
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.

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.

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.

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
cdp
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

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.
Edit - History - Print - Recent Changes - Search
Page last modified on July 21, 2021, at 09:49 PM