Cross-compiling GNSS-SDR

An embedded system is defined as a computer system with a specific function within a larger mechanical or electrical system. Examples of properties of embedded computers when compared with general-purpose counterparts are low power consumption, small size, rugged operating ranges, and low per-unit cost, at the price of limited processing resources.

This page is devoted to the development cycle for building and executing GNSS-SDR in an embedded computer. In this example we are working with a Zedboard (a development board that ships a Xilinx Zynq-7000 all-programmable SoC, which houses two ARM and one FPGA processor in a single chip), but this procedure is applicable to other embedded platforms without much modification.

Once all the required dependencies are already installed, GNSS-SDR can be built from source in ARM processors without hassle. However, this building process can easily take more than 10 hours if it is executed on the Zynq device. Thus, in order to speed up the development cycle from a change in the source code to the execution in an embedded platform, we need to resort to cross-compilation.

Cross-compilation consists of a building framework capable of creating executable code for a platform other than the one on which the compiler is running. In our example, we would like to build GNSS-SDR with the powerful, fast processor of a general-purpose desktop computer, and to generate binaries that can be directly executed by the Zynq device.

By using cross-compilation, we can shorten the building time from more than 10 hours to less than 10 minutes. This improves Testability, as one of its requirements is that a testing cycle has to be fast.

The cross-compilation environment proposed here is based on OpenEmbedded, a building framework for embedded Linux. OpenEmbedded offers a best-in-class cross-compile environment, allowing developers to create a complete, custom GNU/Linux distribution for embedded systems.

Below we provide a software developer kit (SDK) that installs a ready-to-use cross-compilation environment in your computer.

Getting the SDK

We offer two options here: you can either download a script that will install the full SDK in your computer, or you can customise and build your own SDK. Both options are described below:

Option 1: Downloading the SDK

You can download the SDK from the links below. Version names (Jethro, Krogoth, Morty, …) follow those of the Yocto Project Releases.

The following table lists the available SDK versions:

Check out the manifest files to see the full list of packages and versions each SDK will install in the root filesystem of your device. Releases are listed from the most recent (top) to the oldest (bottom). All the SDKs but Jethro include all the required dependency packages for cross-compiling GNSS-SDR in your own machine, including optional packages such as gr-osmosdr and gr-iio.

Option 2: Building your own SDK

Head to https://github.com/carlesfernandez/oe-gnss-sdr-manifest and follow instructions there. Make sure you have plenty of space in your hard drive (25 GB minimum). In summary, the process is as follows:

1) Install repo:

$ curl https://storage.googleapis.com/git-repo-downloads/repo > repo
$ chmod a+x repo
$ sudo mv repo /usr/local/bin/

2) Create a folder in which all the process will take place:

$ mkdir oe-repo
$ cd oe-repo

3) Initialize repo, download the required tools and prepare your building environment:

$ repo init -u git://github.com/carlesfernandez/oe-gnss-sdr-manifest.git -b thud
$ repo sync
$ TEMPLATECONF=`pwd`/meta-gnss-sdr/conf source ./oe-core/oe-init-build-env ./build ./bitbake

This last command copies default configuration information into the ./build/conf directory and sets up some environment variables for OpenEmbedded.

$ repo init -u git://github.com/carlesfernandez/oe-gnss-sdr-manifest.git -b sumo

$ repo init -u git://github.com/carlesfernandez/oe-gnss-sdr-manifest.git -b thud

4) OPTIONAL: at this point, you can configure your building by editing the file ./conf/conf.local. If you do nothing and leave the configuration by default, the next step will generate an image for a Zedboard. Other platforms can be selected by changing the value of the MACHINE variable. Read the comments at ./conf/conf.local for more options.

5) Build the image and the toolchain installer:

$ bitbake gnss-sdr-dev-image
$ bitbake -c populate_sdk gnss-sdr-dev-image

This process downloads several gigabytes of source code and then proceeds to compile all the required packages for the host and native targets, so it will take time. The first command constructs a complete Linux image for your target device. The second command generates the toolchain installer, a script that installs a cross-compiler, a cross-linker and a cross-debugger, forming a completely self-contained toolchain which allows you to cross-develop on the host machine for the target hardware. The generated script will be found under ./tmp-glibc/deploy/sdk/.

If you are using Rocko or above, you can create a Docker image of the target environment by doing:

$ bitbake gnss-sdr-dev-docker

This will create a .docker file under ./tmp-glibc/deploy/images/ that can be ingested by Docker as:

$ docker load -i /path/to/file.docker

For your convenience, you can also directly pull and run this image from an arm32v7-based device:

$ docker run -it carlesfernandez/gnsssdr-dev-arm32v7:thud /bin/bash

(or carlesfernandez/gnsssdr-dev-arm32v7:sumo for the Sumo image).

Copy the results of your cross-compilation there and you are ready to go. Please note that this image can only be executed by an arm32v7-based system.

If you are going to build images and the SDK in your own machine, you could be interested in the https://github.com/carlesfernandez/yocto-geniux repo. It provides a Dockerfile that defines a Docker container for building everything in a virtualized environment (including an interactive mode in which you can make changes and experiment), and a script that automates the whole process, so you can build the version you want with a single command line. Check the README.md file on that repo for instructions.

Using the SDK

Installing the SDK

Install some basic packages required by the SDK:

$ sudo apt-get install xz-utils python3

Then, download the SDK shell script (or use a locally created SDK, as explained above) and install it:

$ sudo sh oecore-x86_64-armv7ahf-neon-toolchain-nodistro.0.sh

This will ask you what directory to install the SDK into. Which directory does not matter, just make sure wherever it goes that you have enough disk space. The default is /usr/local.

The SDK comes with everything you need to build GNSS-SDR. The main contents it has are:

• An “environment-setup-...” script that sets up our environmental variables, like editing PATH, CC, CXX, etc.
• Two sysroots; one for the host machine and one for the target device (installed by default at /usr/local/oecore-x86_64/sysroots/).

Setting up the cross-compiling environment

Running the environment script will set up most of the variables you’ll need to compile. You will need to do this each time you want to run the SDK (and since the environment variables are only set for the current shell, you need to source it for every console you will run the SDK from):

$ . /usr/local/oecore-x86_64/environment-setup-armv7ahf-neon-oe-linux-gnueabi

Cross-compiling GNSS-SDR and installing it on the target filesystem

Once the environment script has been run, you can cross-compile GNSS-SDR as:

$ git clone https://github.com/gnss-sdr/gnss-sdr.git
$ cd gnss-sdr
$ git checkout next
$ cd build
$ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/oe-sdk_cross.cmake -DCMAKE_INSTALL_PREFIX=/usr ..
$ make
$ sudo make install DESTDIR=/usr/local/oecore-x86_64/sysroots/armv7ahf-neon-oe-linux-gnueabi/

Please note that we set the install prefix to /usr. That will be the installation location of the project on the embedded device. We use this because all links and references within the file system will be based on this prefix, but it is obviously not where we want to install these files on our own host system. Instead, we use the make program’s DESTDIR directive. On the device itself, however, the file system would have this installed onto /usr, which means all our links and references are correct as far as the device is concerned.

Copying an image file to your SD card

We have several options here:

Using dd

$ mkdir myimage
$ tar -xvzf gnss-sdr-dev-image-zedboard-zynq7-20170103150322.rootfs.tar.gz -C myimage
$ sudo dd status=progress bs=4M if=myimage of=/dev/sdX

where /dev/sdX is the device the card is mounted as. This works, but can be slow.

Using bmaptool

This option is faster:

$ git clone https://github.com/01org/bmap-tools.git
$ cd bmap-tools
$ sudo python setup.py install
$ sudo bmaptool copy gnss-sdr-dev-image-zedboard-zynq7-20170103150322.rootfs.tar.gz /dev/sdX --nobmap

Copying only the sysroot to the SD card using cp

For systems with a dedicated u-boot, devicetree and Kernel, it is possible to copy only the cross-compiled sysroot to the SD ext4 partition. Mount the SD card partition and extract the root filesystem to the mounted root directory (in this example, sdb2 is the SD card device and the ext4 partition is the second partition in the SD partition table), and then use cp with the -a option, which preserves the same directory tree, same file types, same contents, same metadata (times, permissions, extended attributes, etc.) and same symbolic links:

$ mkdir ./mounted_SD
$ sudo mount -rw /dev/sdb2 ./mounted_SD
$ cd ./mounted_SD
$ sudo rm -rf *
$ cd ..
$ sudo cp /usr/local/oecore-x86_64/sysroots/armv7ahf-neon-oe-linux-gnueabi/* -a ./mounted_SD

Copying only GNSS-SDR executables to the device over the network using sshfs

For example, let’s assume that we can address the device by a network name or IP address. Let’s say it’s called “mydevice” and it has an ip address of 192.168.2.2. We would use a mount point created in your home directory. To install sshfs and mount mydevice locally:

$ sudo apt-get install sshfs
$ sudo gpasswd -a $USER fuse
$ cd
$ mkdir mydevice
$ sshfs -o allow_root root@192.168.2.2:/ mydevice

You should be able to ls mydevice and see the contents of mydevice’s file system. Then you can cross-compile GNSS-SDR as before, changing the last command by:

$ sudo make install DESTDIR=~/mydevice

in order to install the GNSS-SDR binary directly in your device. To unmount:

$ fusermount -u ~/mydevice

References

• More information about the development environment and the usage of BitBake can be found in the Yocto Project Documentation.

• This work is heavily based on Embedded Developments with GNU Radio and the work by Philip Balister (and others) on the oe-gnuradio-manifest and the meta-sdr layer.