vi ~/bin/env/rpi
<edit lines as appropriate>
source ~/bin/env/rpi
rpi
Deprecated
|
Software
Software Developers Guide
A customizable embedded distribution for the Raspberry Pi. Repositories Table Of Contents
- Repositories and External Information
- Basic System Build Process - Build System Basics - Build system prerequisites - Docker Tips - Docker Usage - Quick Start - Cross Toolchain - To build with PiBox: - Verification - Bootloader - Firmware GPU configuration - To build with PiBox: - Kernel - Kernel command line options - To build with PiBox: - VidCore / OpenGL / GLES - VidCore - OpenGL / GLES Userspace - To build with PiBox: - Root File System - To build with PiBox: - DSP - SD Card format - First partition contents - Building SD card with PiBox - Installable packages - Build and install OPKG - Debug Utilities - Important Tips 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
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/rpivi ~/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 helpAll 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:
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 pkgTo 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.
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 xccmake 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 --verboseUsing 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.cVerify binary format % file testtest: 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 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 rpifwmake 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 kernelmake 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 glesThe 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 buildrootmake 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:
First partition contents
The following items were identified from a Raspbian SD image.
Notes:
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-scriptscdp 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-verifymake 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-opkgmake 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.
Example: make JOBS=2 buildroot
Example: make XV=1.18.0 xcc
Example: make BR=2013.02 buildroot
Example: make XI=/opt/rpiTC buildroot
|