Notes on the 2014.11 release - adapteva/epiphany-sdk GitHub Wiki

This page holds documentation relating to how to check out, build, develop and use the Epiphany SDK release 2014.11.

The tool chain offers two new features

1. Software caching is a new feature to fit larger programs into each core's memory.

2. The GNU debugger (GDB) now uses a single port for its target, with each core appearing as a thread.

3. The epiphany libraries have been tidied up, so it is no longer necessary to run the e-server as superuser. The scripts for building the SDK have been extended to try to resolve common issues identified.

4. e-shm: Makes it easier to share memory between the host and Epiphany programs. See https://github.com/adapteva/epiphany-examples/tree/2014.11/apps/shm_test

5. e-sim: An experimental Epiphany multicore simulator. It is only included in the x86_64 SDK.

Before starting, some prior reading should ensure you are familiar with the core technologies in developing code for Parallella.

You should also make sure you meet the general requirements for any system you will be using to develop code for Parallella (and the Parallella itself is perfectly suitable as a code development system).

This release will only work with a very new Linux kernel, which includes the new Epiphany drivers. At present you need to build from source. The source for the Parallella linux kernel is at https://github.com/parallella/parallella-linux and can be cloned from:

git clone [email protected]:parallella/parallella-linux.git

Note. This is already cloned as part of the SDK build script, after which it will be found in the SDK directory. There is no need to clone it again!

The default main branch is the correct one to use. If necessary do a checkout of this branch

cd parallella-linux
git checkout main

The kernel is big, and for speed, it is wise to build it on a PC using an ARM cross-compiler, rather than on the Parallella. You will need mkimage to create the uBoot image. On a recent Ubuntu system this can be installed with:

sudo apt-get install u-boot-tools

To build the kernel, use the following commands (based on https://github.com/parallella/parallella-bin/blob/master/README.md).

export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-
export PATH=:$PATH
make ARCH=arm parallella_defconfig
make ARCH=arm LOADADDR=0x8000 uImage

Note. arm-linux-gnueabihf- is the correct cross-compile prefix to use on a recent Ubuntu system, but you should substitute the prefix of the ARM cross-compiler installed on your system.

You will also need a new device tree. The instructions on parallella-bin are not suitable. Instead use

scripts/dtc/dtc -I dts -O dtb -o arch/arm/boot/zynq-parallella1-hdmi.dtb arch/arm/boot/dts/zynq-parallella1-hdmi.dts

for a system with HDMI enabled, or

scripts/dtc/dtc -I dts -O dtb -o arch/arm/boot/zynq-parallella1-headless.dtb arch/arm/boot/dts/zynq-parallella1-headless.dts

for a headless system.

You now need to copy these into the boot partition of your SD card. Remove it from your Parallella system and mount it on your PC. You should see two partitions appear (use the df command) one will be installed as the BOOT subdirectory. On Ubuntu this will be typically mounted on /run/media/<username>/BOOT/. You should copy the kernel image and device tree across, for example for if you are logged in as user myname:

cp arch/arm/boot/zynq-parallella1-hdmi.dtb /run/media/myname/BOOT/devicetree.dtb
cp arch/arm/boot/uImage /run/media/myname/BOOT/uImage

(substitute the zynq-parallella1-headless.dtb if you are building a headless system)

You can now replace your SD card in the Parallella and reboot. There is one more change needed before the system can work - an update to the udev rules for the new device. To do this create a new file /etc/udev/rules.d/90-epiphany-device.rules with the following contents:

################################################
##/etc/udev/rules.d/90-epiphany-device.rules

# Set appropriate permissions on the epiphany device node
KERNEL=="epiphany", MODE="0666"

One more reboot and your system will upgraded ready to run the new tools.

The SDK is held in several repositories for its various components, which need to be downloaded into various directories. The main repository, containing all the build scripts is this one. If you have git installed you can clone this repository using:

git clone https://github.com/adapteva/epiphany-sdk --branch 2014.11 sdk 

Alternatively you can download an unpack a zipped up version of the repository:

wget https://github.com/adapteva/epiphany-sdk/archive/2014.11.zip
unzip 2014.11.zip
mv epiphany-sdk-2014.11 sdk

By default the SDK build script will download and buld the tool chain for you. However the GNU tool chain is quite slow (several hours) to build on the ARM processor of the Parallella board, because it does a lot of file I/O (SD cards are relatively slow), and GCC really benefits from building in parallel with much more memory than is available with the ARM processor.

The alternative is to build the compiler on a standard Linux PC and copy it across to Parallella. This can reduce the compile time to a few minutes on a modern large processor. Such a build is known as Canadian Cross build. It builds a compiler on one machine (the PC), to run on a second machine (the ARM processor on Parallella) where it will generate code for a third machine (the Epiphany chip). To avoid confusion, these are known as respectively the build machine, the host machine and the target machine_.

On your PC, checkout the SDK repository as above:

git clone https://github.com/adapteva/epiphany-sdk sdk --branch 2014.11

Then change to the sdk directory, and use the download-toolchain.sh script to download all the components of the tool chain.

cd sdk

It might be necessary to checkout the 2014.11 branch.

git checkout 2014.11

There are two possible mechanisms to get the toolchain components. The default downloads zipped up versions of each component:

You can clone the repositories, or you can download zipped up versions. To use git to clone the various components use

./download-toolchain.sh

However if you want to experiment with changing the tool chain, you may prefer to clone the repositories instead. You can do this with:

./download-toolchain.sh --clone

There are a large number of options to the download-toolchain.sh script. You can get a short summary with:

./download-toolchain.sh --help

For fuller details see the download script page.

To build the toolchain, you will need to have C and C++ cross-compiler toolchains for ARM installed on your Linux platform. The details vary from platform to platform, but for a modern Ubuntu, you can achieve this with:

sudo apt-get install gcc-4.8-arm-linux-gnueabihf
sudo apt-get install g++-4.8-arm-linux-gnueabihf

You can then run arm-linux-gnueabi-gcc and arm-linux-gnueabi-g++ to compile C and C++ programs on your PC, but generated code for an ARM Linux system.

To build the tool chain, you then run

./build-toolchain.sh --host arm-linux-gnueabihf

This actually builds two tool chains. First a minimal Epiphany tool chain to run on your PC, needed to create the libraries for Epiphany. Then a full Epiphany tool chain to run on the Parallella ARM system. It is this latter tool chain you will copy across to Parallella.

The default installation locations, as per the Parallella programming manual are:

/opt/adapteva/esdk.2014.08/tools/e-gnu.x86_64

for the minimal Epiphany tool chain to run on the PC, and

/opt/adapteva/esdk.2014.08/tools/e-gnu.armv7l

for the full Epiphany tool chain to run on the Parallella ARM system. Symbolic links are set up, so the host tool chain will also appear as:

/opt/adapteva/esdk/tools/e-gnu

If you do not have write access to /opt/adapteva, you can specify alternative locations, for example

./build-toolchain.sh --host arm-linux-gnueabi --install-dir-host ${HOME}/e-gnu.armv7l \
    --install-dir-build ${HOME}/e-gnu.x86_64

Once the tool chain has built, it can be copied to the Parallella using standard operating system commands. For example, a Parallella board which appears on the network as melchior could be copied

scp -r /opt/adapteva/esdk/tools/e-gnu melchior:/opt/adapteva/esdk/tools

(substitute the actual install directory of the host tool chain if you have changed that)

Once this done, you can run the script to build the SDK on Parallella (see below), but first ensure your PATH includes the epiphany tools, and set the EPIPHANY_BUILD_TOOLCHAIN environment variable to no:

PATH=opt/adapteva/esdk/tools/e-gnu/bin:$PATH
export EPIPHANY_BUILD_TOOLCHAIN="no"

The build-toolchain.sh script includes numerous options to control the build process. You can find out about them with

./build-toolchain.sh --help

and there is commenting explaining what they do at the top of the file itself.

The toolchain and SDK are built in several steps, as described in Building the SDK.

More detailed information regarding how to build on Linux, Mac and Windows can be found on their respective pages.

Issues building or using the SDK should be sent to the Parallella SDK Forum. Bugs relating to the SDK should be reported to the Epiphany SDK Bug Tracker.

Please refer to Submitting Bug Reports and Submitting Patches for advice and best practices on submitting bug reports.

Feel free to update this wiki with information regarding building and using the SDK as you find information that may be of use to other SDK users.