CS378H: Concurrency: Honors: FPGA Lab: Cascade Environment Instructions

This document provides instructions for bringing up the Cascade lab development environment on a Windows, MacOS, or Linux machine. These instructions are certified to work with Windows 10, macOS Catalina, and Ubuntu 18.04, and 19.10.

Ubuntu (or another APT-manged Linux distro) is the preferred environment for running Cascade and interfacing with the DE10-Nano. MacOS can run Cascade natively for software simulations, but is not supported by Intel's Quartus FPGA compiler to target the DE10-Nano. Windows is currently not supported by Cascade. Therefore, you will likely need to install Linux in order to access all the features of Cascade needed for this lab. For most students, this will involve running Linux from within a VirtualBox VM. While it is also possible to install Linux natively or with commercial VM software, you do so at your own risk. If you already have admin privileges on a native Ubuntu installation or on macOS, you can skip the VirtualBox VM sections.

Installing VirtualBox

Installing VirtualBox is fairly straightforward. You will want to visit the VirtualBox downloads page (virtualbox.org/wiki/Downloads) and grab the latest copy of your OS as well as the corresponding version of the VirtualBox Extension Pack. The Extension Pack enables better USB and graphics support that you will likely want to take advantage of.

To install VirtualBox on Windows, simply run VirtualBox-*-Win.exe. On macOS, open VirtualBox-*-OSX.dmg and run VirtualBox.pkg from the newly-mounted disk image. The installer is pretty straightforward, just follow the directions and opt to install USB drivers if prompted. After VirtualBox is installed, open it and install the Extension Pack. If VirtualBox does not prompt you do to this automatically, you can open the downloaded extension pack with VirtualBox to install it or install it through the Extensions pane in the Settings / Preferences dialog.

Creating a Linux VM

Once you have Virtualox set up, you'll need to set up a Linux VM. If you would like to get started as soon as possible, we've prepared a VM with all the necessary software that you can import and start using right away. However, if you already have a Linux VM, would like to customize your installation, or want to learn more about installing Linux, Cascade, and Quartus, we also have instructions for setting up your own VM.

Importing an Existing VM

First, start by downloading our prebuilt VM: Cascade.ova. This will take a while as the VM is several GB in size. Once that's done, import the VM with File→Import Appliance. Select Cascade.ova and wait for the import to complete. You may want to tweak a few VM settings, like reducing the RAM allocation if your computer has 8 or less GB of RAM.

To verify everything worked, launch the VM. The default username and password are "cascade". The VM should already have Cascade, Quartus, and the VirtualBox Guest Additions installed. A clone of the Cascade source code is provided in "~/cascade" for convenience. The Quartus installation is in "~/intelFPGA_lite/19.1/". There are links to both these locations on the Desktop as well. You may want to install updates, pull the latest copy of Cascade, and do a clean build and install to make sure you have the latest bug fixes before starting.

Creating a New VM

If you would like to create a VM from scratch, the following instructions should work for Ubuntu or other Debian-based distributions. We recommend Ubuntu 18.04 and 19.10 as we know Cascade works well with these releases.

In virtual box create a new VM (Machine→New...).
Choose a name (e.g. "cascade-lab").
The VM type should be Linux.
Version is Ubuntu 64-bit.
The default memory is a bit small. We recommend at least 4GB memory.
Hard disk option: create a virtual hard disk. If you would like to be able split your disk image into chunks of 2GB or less (to make transferring the files easier or to reduce the size of incremental backups), choose the VMDK option. Otherwise the default format is fine. You probably want a capacity between 25 GB (minimum) to 50 GB (recommended). Dynamic sizing is highly recommended for larger disk sizes.
Power on your machine by double clicking on it in the left pane in VirtualBox.
The "Select start-up disk" dialog will come up. Select a file option and to point it to your Linux ISO: ubuntu-19.10-desktop-amd64.iso
An ubuntu installer should boot up. Press the "Install Ubuntu" button. You can choose either a minimal or normal installation. The minimal install will save some space at the cost of having to install a few extra programs.
Choose "Erase disk and install Ubuntu, and press "Install Now".
When the "who are you" dialog comes up, be sure to choose something you'll remember! Choosing whether to log in automatically is optional.
You can log into your VM after clicking "Restart Now".
After the installer completes and you've logged in, the system will probably prompt you about installing updates. It shouldn't matter whether you do or not, but we still recommend you do.
After installing updates, install the guest additions. While the VM is running, select Devices→"Insert Guest Additions CD" from the top menu. A CD will mount in your guest with the installer, and you can either go find the appropriate *.run file in /mnt, or let the auto-installer run it (a dialog will come up after the CD mounts). There is a nice tutorial on using guest additions for host/guest file sharing here.

Installing Cascade and Quartus

To install Cascade, follow the setup instructions on github.com/eschkufz/cascade. If you are running Cascade natively on a Mac, you may need to install Xcode and Homebrew first. Otherwise, if you are on Linux and want to use Cascade's JIT functionality, you'll also need to install Intel's FPGA compiler, Quartus.

Download the latest Quartus Lite edition from Intel. If you don't want to create an Intel account, you can directly download the Quartus Prime (includes Nios II EDS) installer and Cyclone V device support package using the provided links.

fpgasoftware.intel.com/?edition=lite

You can install the quartus tools by marking the installer as executable with chmod +x QuartusLiteSetup*.run and then running it. The installer should automatically detect and install the Cyclone V device files.
If you opt for the full installer, you'll need to extract it with tar -xvf . Quartus-lite-*-linux.tar and run it with ./setup.sh. Only install device files for the Cyclone V FPGAs as those are the only ones you need.
Due to a bug in Quartus 19.1, a workaround is necessary to make it work on Ubuntu. If you are using the provided VM, we have already patched this for you. The fix is fairly easy and documented here: armadeus.org/wiki/index.php?title=Quartus_installation_on_Linux#Perl_Getopt::Long. In short, just run:
- sudo apt install libgetopt-simple-perl
- cd ~/intelFPGA_lite/19.1/quartus/linux64/perl/bin
- mv perl perl_old
- ln -s /usr/bin/perl
To save on space, you may want to delete the installer and device files once you're done

Setting up Cascade on the DE10-Nano

Note that due to COVID-19, you are not expected to use the DE10-Nano, and running in simulation is sufficient. Instructions to use the software backend for Cascade can be found here. The remaining instructions are here for people who actually have access to the DE10, but it is not expected that you use it. NOTE: some set up of Cascade on the DE10 is required whether you use our pre-built VM or not. The simplest way is to use the microSD card image provided.

Once you've got your Linux installation working, you will be able to use all the Verilog capabilities necessary to write your code for the lab. However, since the hardware you describe with your code is being simulated in software, you may find it runs slower than desired. For this purpose, Cascade can take advantage of the FPGA on the DE10-Nano to run your hardware as intended. This required getting Linux working on the DE10 (to run Cascade), configuring your VM to be able to connect to the DE10, and configuring Linux on your VM to do the JIT compliation to convert your Verilog to an actual hardware configuration.

Due to the complexity of getting Cascade running on a DE10-Nano, we have compiled a microSD card image that contains everything you need to get Cascade running on the DE10. Before proceeding make sure you have:

The DE10 FPGA board with microSD card
The micro-USB cable that come with your DE10 FPGA board
A microSD card reader / SD card reader with microSD card adapter
The microSD card image linked to in the Cascade repo README, downloaded onto your Linux installation

Initialize the microSD Card

First, pass through the SD card reader to the virtual machine. In VirtualBox, go to Devices→USB in the menu, and select your SD card reader. It will probably contain the name Card Reader or similar.

Next, determine which device Linux has assigned to your SD card reader. It is extremely important that you get this right as overwriting the wrong device can cause you to lose all the files in your VM and make it unusable. Open the Disks utility and select the entry on the right corresponding to your microSD reader. On the right window, look for Device /dev/sdX# and note the letter corresponding to the microSD reader.

Once you've identified the microSD device name, open a terminal and navigate to the directory you downloaded the image to. We will use the dd utility to update the image. The next steps will overwrite the microSD card, so make sure you don't have any files you want to keep on it!

First, make sure all partitions on the SD card are unmounted. Run: sudo umount /dev/sdX*

Then, we'll use the dd utility to copy the image over, 4 megabytes at a time, decompressing the image as we go:

tar xzOf cs378h.tar.gz | sudo dd of=/dev/sdX bs=4M

When dd is done, it will output something similar to:

463+1 records in
463+1 records out
1945317376 bytes (1.9 GB, 1.8 GiB) copied, 55.269 s, 35.2 MB/s

The microSD card is now initialized with Linux and ready to go. Insert it into the slot on the underside of the DE10 with the pins facing toward the board.

Connecting to the DE-10

First, start by connecting the cables according to the following image. At a minimum, you should connect the power cable (top left) and micro-USB (top right). The mini-USB cable (bottom left) and Ethernet cable (bottom right) are not needed. The FPGA may need to boot before the micro-USB will work.

In order to access the DE-10 from your VM, you'll want to configure device filters under the the VM's settings→Ports→USB pane. You can add a filter by clicking the plus button and selecting a currently-detected USB device to capture. The Micro-USB cable should show up as Linux 4... or as Netchip RNDIS/Ethernet. It is important to add a filter for this device now because your OS may prevent you from passing it through if it's not captured as soon as it's attached. After you've started your VM, reconnect this cable and check the Devices→USB menu to look for a check mark to make sure it was captured properly. If it wasn't, you may need to reconnect the cable until it is.

In the virtual machine, you should be able to now SSH into the Ubuntu installation running on the ARM cores of the DE10. The username and password are both set to fpga, and the IP address will be 192.168.7.1. In a terminal, connect using:

ssh fpga@192.168.7.1

Type yes to trust the device if prompted, and enter the password: "fpga".

Connecting the DE-10 to the Internet

Without a network cable connected, the DE10 will have no access to the network. Given that you may not have an Ethernet cable, the most straightforward way to connect the DE10 to the internet is via the very USB cable that connects your VM to it. The following instructions will walk you through how to share your VM's internet connection over USB by setting up IP forwarding.

In the VM (not in a SSH session to the FPGA) type:

echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward > /dev/null
sudo iptables -P FORWARD ACCEPT
sudo iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.7.0/24

This will enable network address translation and forward packets coming from 192.168.7.*, which includes the FPGA. From an SSH session with the FPGA you can verify network connectivity by running something like the following command and looking for responses to your packets:

ping google.com

To turn off forwarding, you can type:

echo 0 | sudo tee /proc/sys/net/ipv4/ip_forward > /dev/null
sudo iptables -t nat -F POSTROUTING

If you want to use a traditional Ethernet connection, connecting the DE10 to a router via an Ethernet cable works as well. However, if you are doing this from within the CS building, you will have to authenticate before being allowed to connect. This can be done by running the following command after inserting your UTCS username and password into the appropriate slots:

curl -d "username=XX&password=YY" https://horatio.cs.utexas.edu/login.cgi

Configuring your VM as a JIT Compiler

In order for Cascade to compile programs for the DE10's FPGA, it will need access to your Quartus installation. Run quartus_server and specify the path to where specifically Quartus is installed. The command should look something like this: quartus_server --path ~/Desktop/intelFPGA_lite/18.1/quartus/ --port 9900. When invoking Cascade on the DE10, you should run something like this: sudo cascade --march de10 --quartus_host X.X.X.X --quartus_port 9900. The IP address of your VM should be something like 192.168.7.2 or 192.168.7.5. If you're using Ethernet with your DE10, you'll need your machine's IP address. If you get a connection error, you may need to restart the quartus_server application on your Linux VM and change its port.

Acknowledgements

Thanks to Eric Schkufza and Michael Wei of VMware Research Group for supporting this lab. Thanks to our department head Don Fussell for supporting the project by helping find funds to enable us to loan DE10 hardware to every student.