FPGA Labs

A collection of FPGA labs, most recently for Olin's ENGR3410: Computer Architecture course in Fall '22.

Hardware

Supported Boards

Xilinx Boards:

[*] Cmod A7

Electronics Tools

my preferred options are linked, but many of them are "buy it for life" quality (and price). Feel free to use any compatible tool.

Required:

Solderless Breadboard(s)
Solid core wire/jumper kit
Wire Strippers
Flush Cutters
Multimeter
- Fluke 287
Logic Analyzer
- Saleae Logic 8. If you can afford it get the Pro 8. One of the nicest tools I've ever purchased, hardware and software are both just very well designed. Easy to write your own analysis software for it to, unlike pretty much every other tool on this list.

Recommended:

Bench Power Supply
- something with a programmable current limit, ideally 2 channels
- BK Precision 9132B
Oscilloscope
- any 2-4 channel with at least 100MHz bandwidth is fine
- Rigol makes some decent budget options, their DS1102Z-E is a solid 2 channel scope, and the DS1104Z Plus has 4 channels and can be expanded to include a logic probe which would replace a stand alone logic analyzer.
- Digilent Analog Discovery Pro - it doesn't have a screen, but it is portable, has some great specifications, and has a built in logic analyzer. I haven't tested it yet but it could be a good "buy it for life" option.

Software

This is only tested and maintained on Linux, students have gotten Windows Subsystem for Linux aka WSL to work. Everything except the Xilinx part should run okay on macos, but is unsupported (VMs can work, but some older macs have issues with USB pass through).

Contact the maintainer if you find any issues with with the install process.

Supported Linux Distros:

[*] Ubuntu 22.04
- Explicitly not supported on Ubuntu 20.04, but if needs must, this guide shows you how to get the right version of iverilog. You might still have other issues.
[*] Gentoo
[*] ArchLinux
Probably works fine on other flavors, especially since we're building most of this from source. The following instructions are for ubuntu, you can check out intructions for other distros here

Last, a note on philosophy - there are a lot of techniques to batch together the install of all of these tools (virtual machines, Docker/containers, build scripts, etc.), but a large part of being a good embedded engineer is know how to maintain and install a large set of tools with low to minimal documentation. If you are new to Linux command line/bash installation I recommend you work through the following tutorials before proceeding:

Command Line for Beginners.
Get used to Tab Completion - it saves you time and typos!
Reverse Search - a very powerful tool for when you're rapidly iterating - let's you search your history and quickly re-run commands you've run before.
A guide to bashrc - how you customize your command line (aka shell).
Last but not least, you can get information on most commands by typing man command or command --help.

Strong Recommendation - don't just copy and paste the instructions below - try to run each command one by one to get more familiarity and practice.

Installation checklist:

The install process is split between open source and propriety tools.

Install: Ubuntu 22.04

# Build Tools
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install \
    # good for general development
    build-essential nano python3 libusb-1.0.0 git \
    # cafe specific
    python3-bitstring iverilog gtkwave verilator \
    # required for vivado specifically
    libtinfo5 libxtst6 \

sudo adduser $USER dialout

Digilent:

Go to the runtime and utilities sites and download the "Linux 64-bit.deb" options. Then, from where you downloaded it, run:

sudo dpkg -i digilent.adept.runtime_2.4.1-amd64.deb
sudo dpkg -i digilent.adept.utilities_2.4.1-amd64.deb

(your exact version numbers may be different).

Then you can flash FPGAs without Xilinx tools using:

djtgcfg enum # Will show you the string to put for the -d arg
djtgcfg prog -d CmodA7 -i 0 -f main.bit

Xilinx Install

Xilinx makes the most cutting edge FPGA hardware, but their software leaves a lot to be desired. You have two options:

Official Install (for masochists)

Takes >4 hrs, most of that download time.
Requires ~125GB to install (~75GB final, it's a very bad installer).
Only recommended if you are interested in doing FPGA work later in life. Installing these tools and getting things working is a bit of a rite of passage (unfortunately.)
You've been warned, instructions here if you want to go this route. The exact images might be slightly different from year to year.

Copy from USB Method (recommended method)

Takes 5-30 min. (depending on how fast your USB ports/hard drive are)
Pick an install path for Xilinx Xilinx needs its install location to have no spaces!!!
Plug in the external drive, navigate to the xilinx folder, get a terminal open (you can right-click and pick open terminal in most distros). Below is how to do this from the command line:

sudo mkdir /mnt/tmp
sudo mount /dev/disk/by-label/cafe_install /mnt/tmp
cd /mnt/tmp
# This step will copy the files to your computer, takes 20-30min
sudo ./custom_install.sh /path/to/destination
sudo chown -R $USER /path/to/destination # make sure you own the files once they're copied.

There's a bug in my script, so you might end up with an extra "full_install" folder, e.g. /path/to/destination/full_install/Vivado/.... If that's the case you can do:

cd /path/to/destination
mv full_install/* ./
rmdir full_instll

to fix that issue.

cd /path/to/destination/Vivado/2021.1/
nano settings64.sh # replace all paths with the /path/to/destination you used above
nano .settings64-Vivado.sh # ditto
# Check that it works:
source /path/to/destination/Vivado/2022.1/settings64.sh
vivado &
# after a wait the gui should pop up!

If you want the full install, but don't have the ridiculous 120GB plus Xilinx needs for temporary files, you can follow the above steps, but do ./custom_install.sh /path/to/destination full instead.

Note that you will need to run source /path/to/destination/Vivado/2022.1/settings64.sh in every terminal you plan to run Vivado in! You can save time by editing your ~/.bashrc file and adding this to the end:

function setup_xilinx(){
    # Make a variable with the install path.
    export XILINX_INSTALL_PATH="/mnt/bulk/avinash/embedded/xilinx/"
    VERSION="2022.1"
    export VIVADO_PATH=${XILINX_INSTALL_PATH}/Vivado/${VERSION}
    
    # Calls the Xilinx setup scripts so that you can run the tools.
    source ${VIVADO_PATH}/settings64.sh
}
# setup_xilinx() # Uncomment this if you are only using this linux partition for this class.

Aside: Xilinx clutters your path with a lot of copies of things that are probably better on your main system, so I prefer to call setup_xilinx manually in every terminal I'm using it in (instead of running it all the time by calling it from .bashrc).

Digilent Board Files install

From the digilent docs Replace XILINX_INSTALL_PATH and VIVADO_PATH as appropriate below.

cd $XILINX_INSTALL_PATH 
git clone https://github.com/Digilent/vivado-boards
mkdir -p ${VIVADO_PATH}/data/boards/board_files/
cp -r vivado-boards/new/board_files/* ${VIVADO_PATH}/data/boards/board_files/

Checking the install.

You can check to see that all the tools were installed by running the tools/check_install script.

colemarco/olin-cafe-f22