CS378H: Concurrency: Honors: Lab #5: FPGAs: MacOS Environment Instructions

While Cascade can be compiled for MacOS, MacOS lacks the drivers necessary for interfacing with the DE-10 boards and is not supported by Intel's Quartus software. Therefore, you will need to run Linux on your Mac 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 run Linux natively or with commercial VM software, you do so at your own risk.

Installing VirtualBox

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

To install VirtualBox, open the VirtualBox-*-OSX.dmg file, run the VirtualBox.pkg installer, and follow the directions. After VirtualBox is installed, install the Extension Pack. VirtualBox may show a prompt to do this automatically or you may have to add it manually via the Extensions pane in the Preferences dialog.

Installing Linux

With VirtualBox set up, you'll need to download a Linux ISO to set up Linux. We recommend Ubuntu as we have tested Cascade with both the 16.04 and 18.04 Long Term Support releases, though any recent Ubuntu release should work. Ubuntu can be downloaded from ubuntu.com/download/desktop.

Once you have a Linux ISO, it's time to set up a VM to install it in. Create a new VM in VirtualBox and specify the type as Linux, Ubuntu (64-bit). We recommend giving the VM quite a bit of memory as Quartus is a pretty memory-hungry application. If you can, 6 GB is known to work well, but you can probably get away with less. VirtualBox should only allocate RAM as it's used, so you may find that your VM uses less than 6 GB in practice. You'll also want to create a new hard disk for your VM. The VDI format works well and using the dynamically allocated variant is highly recommended. This way disk space is only used as needed. A 50 GB virtual disk should be sufficient when using dynamic allocation. If you want a minimal static size, 25GB is manageable.

Once the VM is created, you'll need to tweak a few of the VM's settings. Under System→Processor, make sure to allocate a more than one CPU core to your VM. This can help improve the time needed to build and run Cascade. You may also want to enable PAE/NX. Under Display→Screen, you may want to increase video memory to 128MB and enable 3D acceleration. Under Storage, you should see an empty disk drive under the IDE controller. Select it and press the disk button under the Attributes pane on the right side of the window. Select the Linux ISO you downloaded earlier. Finally, under Ports→USB, you'll want to select the USB 3.0 controller.

With the VM configured, you should be able to boot it up and install Linux. The installation is generally straightforward, but you may want to shrink any swap partitions the installer creates to save on disk space. Once the installation completes and you're ready to reboot, eject the installer ISO using the disk icon or via the Devices→Optical Drives menu. Once you boot into Linux, you may want to install any updates available. It is then recommended that you install the VirtualBox Guest Additions via Devices→Install Guest Additions CD image. Ubuntu may prompt you to run the installer automatically, but you may have to use the command line to run the installer (likely with sudo). This will enable some handy features (e.g. VM window resizing) and improve performance.

Installing Cascade on Linux

Cascade's README has good directions on how to install it on Linux: github.com/vmware/cascade/blob/master/README.md. It is worth noting that you may not need to install libncurses-dev on Ubuntu (or it may go by another name, like libncurses5-dev). Building and testing your Cascade installation will take some time (around a half hour to an hour for "make check").

Installing Cascade on the DE-10

Due to various issues with the stock DE-10 MicroSD card image and Ethernet access at UT, we will be distributing an image that includes Cascade and the packages needed to build it, no internet access required. When this image is released, we will provide instructions for how to write it to the SD card. You should be able to compile Cascade on the DE-10 in a near-identical manner to how you did it on Linux (if running make or make check encounters a git error, comment out any line containing "git submodule" from the Cascade Makefile and try again).

Installing Quartus on Linux

To enable hardware acceleration of Cascade on the DE-10, you will need an installation of Intel's Quartus Lite software on Linux. We have tested with both versions 17.1 and 18.1, so any recent version should work (we recommend 18.1 for simplicity). Quartus can be downloaded from fpgasoftware.intel.com/?edition=lite. Make sure Linux is your selected OS and that you are doing a direct download. We recommend downloading individual files as this greatly saves on space and download time. You'll need Quartus Prime (includes Nios II EDS) installer and Cyclone V device support package. After downloading, you'll need to make the Quartus Prime installer file executable, which can be done with "chmod +x *.run" from your downloads folder. You should then run the installer as a regular user and follow the instructions to install Quartus. The installer should automatically detect the Cyclone V device file and install it automatically.

Cascade + DE-10

In order to access the DE-10 from your VM, you'll need to configure device filters via the the VM settings→Ports→USB pane. To do this, you'll want to plug in both of the USB cables from the DE-10 to your computer. Make sure the Mini-USB cable is connected to the JTAG programming port (see DE-10 documentation, it should be near the Ethernet jack and not next to where the smaller Micro-USB cable connects, which is the UART port). You can then add a filter by clicking the plus button and selecting a currently-detected USB device to capture. You should add filters for the "Linux 4.1.33-ltsi-altera ... Gadget" and the "Altera DE-SoC". You may need to unplug and reconnect the Mini-USB cable 3-4 times before it is properly detected as the latter device. Once the filters are set, you'll likely need to unplug and reconnect both cables while your VM is running for VirtualBox to detect and capture both devices properly. You should then see them under Devices→USB with a check mark preceding them.

If the Micro-USB cable is working properly, you should see a USB disk appear in Linux with some DE-10 files in it. You should also be able to SSH into "root@192.168.7.1" and access the DE-10's CPU. To verify that the Mini-USB cable is working properly, should run "sudo ./quartus/bin/jtagconfig" from your quartus install directory and see a DE-SoC device detected. See the JIT Backend section of the Cascade README for more information. If the device isn't detected, check your VM device filters, make sure the device shows up as connected, and try disconnecting the JTAG cable, killing the "jtagd" process, and reconnecting the cable. Note that when running quartus_server, your quartus path should look something like "~/intelFPGA_lite/18.1/quartus/" (with the quotes) if you used the default install path. You will likely have to run quartus_server as sudo to ensure it can access the JTAG device.

Finally, you should be able to run Cascade using the de10_jit backend from the DE-10 itself using 192.168.7.5 as the Linux IP. Note that profile_interval should be 10 as it is now in seconds instead of milliseconds. You may also need to use quartus_host instead of quartus_server to specify the destination IP address. If you get a connection error, you may need to restart the quartus_server application on your Linux VM.

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.