Software

The following is a list with all the software to install in order to compile FPGA models, load them into ROACH, and interact with them via Python:

  1. Ubuntu 16.04/18.04
  2. MATLAB R2013b
  3. Xilinx ISE 14.7
  4. The CASPER Library (mlib_devel)
  5. corr and other Python2.7 libraries

Installation Instructions

Most of the installation instructions already exist somewhere in the Internet, and we limit ourself to link them for you:

Ubuntu 16.04 / 18.04

  1. Download it from here or here.
  2. If you don't know how to install Ubuntu follow the instructions from here and here.


MATLAB R2013b

MATLAB is proprietary software, so it cannot be distributed freely over the Internet.

  1. Ask for someone in the lab to 'provide' you with a MATLAB copy and an updated MATLAB license.
  2. Follow the instructions from the install_notes.txt file provided with the MATLAB copy. Make sure to install Simulink and, if possible, all MATLAB toolboxes, as some are needed for CASPER.


Xilinx ISE 14.7

  1. Download Xilinx ISE Design Suite from here (Full Installer for Linux). You'll need to log in with a specific account, ask in the lab for help.
  2. Follow the installation instructions in here.
  3. Make the changes listed here.
  4. Activate your Xilinx installation with the proper licence, for this you have to:
    1. Go to the Xilinx Product Licensing page (you'll need a Xilinx account).
    2. In the 'Create New Licenses' tab, select 'ISE Design Suite - System Edition, University License 25 Seats', and click in 'Generate Node-Locked License'.
    3. In the 'Select a host...' drop-down menu select 'Add a host...'
      • Note: you don't need to do this and the next step if your computer is already registered in the host list.
    4. Fill the necessary information for your computer. The Operating System should be Linux 64-bits and the Ethernet MAC address of your computer can be found using the ip command. And then click 'Add' -> 'Next' -> 'Next'
    5. Go the 'Manage Licenses' tab, find your computer info in the list and click on it. Find and click the download button (little blue down arrow) for the license. Save the license in a convenient place.
    6. Now in the terminal run the Xilinx License Configuration Manager:
      • sudo /opt/Xilinx/14.7/ISE_DS/common/bin/lin64/./xlcm
      • If you have the following error: libQt_Network.so: cannot open shared object file: No such file or directory, check the Troubleshooting page.
    7. In the 'Manage Licenses' tab, click in 'Load License...' and locate your license.
    8. Once you load your license the information table should fill. Make sure the Expiration Date column reads 'Permanent' for all of the features, and that the Network Interface Card (NIC) ID reads the MAC address of your PC.
      • If in the MAC address reads 000000000000, you have to change yout network interface name, check the Troubleshooting page.


CASPER Library

  1. Git clone this repository. In terminal:
    • git clone https://github.com/francocalan/mlib_devel.git
  2. Switch to the branch we use in the lab. In terminal:
    • git checkout roach2
    • Note: This is our own version of the CASPER Library, which we added some blocks of our own (grouped in the Calan Library) that are needed for some models to work properly. If you want to use a vanilla CASPER Library use the roach2 branch from https://github.com/casper-astro/mlib_devel.git.
  3. Add a file in the cloned repository called startsg.local. This file must contain the local path to your ISE and MATLAB installation. Here is an example:
    • LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu/:/lib/x86_64-linux-gnu:/lib64/:/lib/
    • export MATLAB_PATH=/usr/local/MATLAB/R2013b
    • export XILINX_PATH=/opt/Xilinx/14.7/ISE_DS
    • export XILINX_PLATFORM=lin64
    • export JASPER_BACKEND=ise
    • Modify the file content if you install MATLAB or Xilinx ISE in a location other that the default.
  4. Make the following tweaks from "Tweaks to be able to compile ".
  5. Follow the instructions from this link in order to fix a bug with MATLAB starting from a startup.m script. If you don't do this your MATLAB will freeze at startup in step 6. If you can't access the attachment from the link you can download it here. Basically you just have to unzip the content of the file in the root directory of the MATLAB installation (default: /usr/local/MATLAB/R2013b/).
  6. Run sudo ./startsg from terminal in the location of your mlib_devel repository, it should open MATLAB and load all the Xilinx and CASPER libraries without throwing any errors or warnings.


corr and Python2.7 Libraries

Nowadays CASPER uses their new casperfpga package for FPGA communication. However, we still use the old corr package for 3 main reasons:

  • We are more familiar with it.
  • It has better support for ROACH1.
  • Unlike casperfpga, it support our current (old) kernel version that we use in the ROACHs, so we avoid the hassle to update it.

The installation instructions from CASPER are a little outdated, so here it is our more updated version:

  1. Make sure you are running python 2.7.X as your main python software: type python -V at the terminal.
  2. Install these packages:
    • sudo apt install python-dev python-tk g++
  3. Install pip (python package manager) if you don't have it already:
    • sudo apt install python-pip
  4. Sometimes pip needs to be updated in order to all wok properly:
    • sudo pip install --upgrade pip
  5. Intstall setuptools to be able to install other packages:
    • sudo pip install setuptools
  6. Download the corr package and its requirements, which are listed in this file (the package versions are important!):
      • You can either download each package individually:
        • sudo pip install <package_name>==X.X.X
        • sudo pip install git+https://github.com/<repo_owner>/<repo_name>.git
      • Or make pip read the text file to install all the packages automatically:
        • sudo pip install -r REQUIREMENTS

If you want, you can create a virtual environment in order to keep the required packages versions for corr isolated from the packages installed in your main python environment. You can read how it's done here.

Who is who in the Toolflow

The amount of software needed to use the ROACHs can be a bit baffling, so here is a brief explanation in what do what:

  • Xilinx ISE: is the main software to create circuit models for the ROACHs FPGA. Is not used directly, but rather as an under the hood compiling tool.
  • MATLAB and Simulink: The front-end chosen by CASPER to actually create the models. It uses Simulink with Xilinx libraries to design the models in a graphical environment.
  • CASPER Library: An additional library created by CASPER that provides several useful blocks for radio astronomy signal processing: Polyphase FIR Filters, Fast Fourier Transform (FFT) blocks, accumulators, etc. It also has the so called "yellow blocks", that provide an easy way to interface with the ROACH resources (ADCs, DACs, 10GbE, registers, block RAMs, DRAM, etc).
  • corr: A python library that let you communicate with the ROACH to set parameters, and extract data (interfacing with the yellow blocks).