Overview

This document describes how to build and run MCAPI demo on PC and Terasic VEEK, a Cyclone V SoC FPGA development board. The used MCAPI implementation is PMQ-MCAPI developed at Tampere University of Technology. The demonstration is explained in more detail in Janne Virtanen’s MSc Thesis and a conference paper by Janne Virtanen, Lauri Matilainen, Erno Salminen and Timo D. Hämäläinen, ”Implementation of Multicore Communications API”, International Symposium on System-on-Chip, Oct. 28-29, 2014

The demonstrations come with a pre-configured VirtualBox image. Download and install 64-bit VirtualBox if not yet done.

Setting up the virtual machine

Download the virtual machine image from http://funbase.cs.tut.fi/#examples (File: Ubuntu-Kactus2-PMQ-MCAPI-Demo.ova)

Open VirtualBox → Import the downloaded image

Create shared folder to the host operating system (to move files between host and virtual machine operating systems)

Go settings → Shared Folders → click the folder logo with plus symbol on it. Create a new folder in it, with name "shared" and tick "Make Permanent" and press "ok". Press "ok" again to close the settings.

Now launch the virtual machine by pressing "start". It may take some time. The account name is "default" and its password is also "default".

To switch between full screen and window mode press Right_Ctrl+F

After the virtual machine is launched, mount the host shared folder to the virtual machine side with following commands:
Open terminal by hitting Ctrl-ALT-T

sudo mount -t vboxsf shared ~/shared

Using Kactus2

Kactus2 (funbase.cs.tut.fi) is an extended IP-XACT tool used to pack product design files, documentation and other information in a standard container format. Kactus2 also helps creating MCAPI channels graphically and automatically generating header and make files for compilation.

Launch Kactus2 by pressing the cactus icon in the top left corner in desktop. The components and other entities appear in the VLNV Tree in the left in the IP-XACT Library window.

PC demo

Go down the "VLNV tree" in the left to product.MCAPI_Demo → PC_demo → 1.0

Right-click at 1.0 “Open System Design”

You will see a Kactus2 System design: At background a HW component (blue color box, the PC processor) on which SW components (green boxes) are mapped. Between the SW components there are drawn MCAPI channel between two MCAPI endpoints named “blue” and “green”. Required SW platform components are PMQ-MCAPI library and the Operating system.

Press button "Locked" on the Kactus2 ribbon "Protection" to allow editing of the system design. On the segment "Generation" in the ribbon, press buttons "MCAPI code generation" and "Makefile generation" in this order. This should yield following prints to the output console at the middle bottom:

MCAPI generation complete.
Makefile generation complete.

For information: Generators add to the top component File Sets the following items:

New File Set per instance including instance specific header file and make file.
Make file and launcher for the top component i.e. whole design.

Now go to the library VLNV tree product.MCAPI_Demo → PC_demo → 1.0

Double click "1.0" and the HW component view should open.

You can see under “File sets” the generated files.

Open File Sets and check the path for generated files.

Depending on the operating system file associations and Kactus2 settings, you can launch the demo from opening the tree File sets → system_general_files → /launcher.sh and by hitting the “RUN” button on the right side window.

If this does not work, you can open the terminal and run the script there as follows.

Building and running demo on PC

cd ~/PMQ-MCAPI-Demo/TUT/product.MCAPI_demo/PC_Demo.system/1.0/sw/
make
./launcher.sh

You should see the following:

default@Aihio-VirtualBox:~$ cd PMQ-MCAPI-Demo/TUT/product.MCAPI_demo/PC_demo.system/1.0/sw/
default@Aihio-VirtualBox:~/PMQ-MCAPI-Demo/TUT/product.MCAPI_demo/PC_demo.system/1.0/sw$ ./launcher.sh
Ubuntu-Kactus2-PMQ-MCAPI-Demo_0/bin_Ubuntu-Kactus2-PMQ-MCAPI-Demo_0 MCAPI_demo_receiver_0/bin_MCAPI_demo_receiver_0 MCAPI_demo_sender_0/bin_MCAPI_demo_sender_0
KILLING PROCESSES
LAUNCHING NEW PROCESSES
PROCESSES LAUNCHED
./launcher.sh: line 28: ./Ubuntu-Kactus2-PMQ-MCAPI-Demo_0/bin_Ubuntu-Kactus2-PMQ-MCAPI-Demo_0: No such file or directory
Node 0: Sender here!
Node 1: Receiver here!
Node 1: receiving
Node 0: sending 0xAACC
Node 0: sent
Node 1: received 0xAACC
Node 0: closing!
Node 1: closing!
DONE

ARM demo on Altera Cyclone V SoC -FPGA

Generating files for the ARM system

Go down the "VLNV tree" in the left to product.MCAPI_Demo → ARM_demo → 1.0

Double click "1.0", open the system view and double click "ARM-system" and the ARM system design should open, featuring similar entities as in the PC-System. Now unlock the design and generate MCAPI code and makefiles similarly as in the PC system and the same prints should appear. The generated files appear in the ARM component File sets.

Building and running demo on ARM

To build the ARM demo, open terminal and move to its software directory and call make.

cd ~/PMQ-MCAPI-Demo/TUT/product.MCAPI_demo/ARM_Demo.system/1.0/sw
make

After the binaries are built, transfer the following folder to the file system of the FPGA board: ~/PMQ-MCAPI-Demo/TUT/product.MCAPI_demo/ARM_Demo.system/1.0/sw

To move the file to the host machine, copy it to the shared folder with following command:

sudo cp -rf ~/PMQ-MCAPI-Demo/TUT/product.MCAPI_demo/ARM_Demo.system/1.0/sw
 ~/shared/sw

From there, you should be able to transfer it to the file system of the FPGA board. For example, the SD card containing the system of the board. This guide assumes you use the SD card method.

Your Linux kernel on the FPGA board has to support POSIX message queues. However, it does not by default. If you are using the default built, replace the zImage on the SD card with the image found in Kactus2 on the virtual machine:

sudo cp ~/PMQ-MCAPI-Demo/TUT/product.MCAPI_demo/ARM_Demo/1.0/Images/zImage
 ~/shared/zImage

The virtual machine does not have USB mounted for serial connection to the FPGA board, but you can do it by yourself and access the FPGA board from the virtual machine.

If not, close the virtual box window and go to your host operating system. In the host operating system, you should be able to transfer the files to the FPGA board SD card simply by inserting the card to the PC and drag dropping the files to the card. After you have done this, and inserted SD card back to its lot on the FPGA board, you may boot the FPGA board.

Now you need to access the FPGA board with a serial connection terminal. In case you have not done it before, look for it at this guide: http://www.rocketboards.org/foswiki/Documentation/GSRD131BootLinuxSd#Configuring_Serial_Connection

Open terminal to the FPGA board. Now you need to mount the SD card to the FPGA board filesystem and copy the folder with the following commands. In case the mount directory goes wrong, you may check it with fdisk -l.

mkdir sd
mount /dev/mmcblk0p1 sd
cd sd
cp -rf sw ../sw

Now you should be able to change to the software directory and launch the ARM demo:

cd ~/sw
chmod u+x launcher.sh 
./launcher.sh

MORE INFORMATION

Contact the Funbase team. Contact information is here: http://funbase.cs.tut.fi#contact

KNOWN ISSUES

When using the PMQ-MCAPI, you may not be able restart the application if it crashes or is terminated improperly, unless you boot the platform. This may be avoided by building and running a separate cleaner utility, which is not covered in this tutorial.