openFPGA Loader

Putting BitFiles on the FPGA

You are not logged in.

Please Log In for full access to the web site.
Note that this link will take you to an external site (https://shimmer.mit.edu) to authenticate, and then you will be redirected back to this page.

After you use Vivado to build your design into a bitstream file like bit.out, you'll want to upload this to your FPGA. We'll use a tool called openFPGAloader for this, which does exactly what the name implies. However, the installation is a little different depending on your operating system.

Even if you have installed Vivado on your computer (excellent), we'd still encourage openFPGALoader. It is very minimal in its capabilities but this actually seems to make it more robust than Vivado's own uploader. Since we aren't planning to use any advanced features (like ILAs) this term, this lightweight one should be sufficient.

Installation

Windows

If you installed openFPGALoader, as detailed in the Windows guide, on WSL, you don't need to worry about Zadig or MSYS2, and can skip to the Usage section to test that everything is working (WSL will use the Linux drivers instead of whatever Windows has configured).

Windows installation is a little bit tricky, and requires a few steps:

  • Install MSYS2 from the official instructions. Leave all options at their defaults. This will install a handful of environments.
  • Launch the UCRT x64 environment, it's the one with the yellow logo.
  • Install openFPGAloader with pacman -S mingw-w64-ucrt-x86_64-openFPGALoader
  • Check that openFPGAloader installed by running openFPGAloader. You should see a help menu.
  • Plug in your FPGA, and wait for Windows to finish installing drivers. Double check this by making sure there isn't a yellow exclaimation mark next to any USB devices in Device Manager.
  • Download the Zadig tool from its homepage.
  • Open Zadig, and refresh devices from the top menu. Select the one labelled 'Digilent USB Device' from the dropdown.
  • Select the WinUSB driver as the replacement for the FTDIBUS driver. Once done, Zadig should look like what's below:

Zadig Driver Replacement Screen

What Zadig should look like right before replacing the driver.
  • Replace the driver. This will take a few minutes, and Zadig should show that the new driver is installed. Make sure you do this for both Digilent USB Device Interface (1) and Interface (2). 1
  • You're almost ready to test! The C drive on MSYS2 is a separate folder, so you'll have to cd /c/Users/<user>/Desktop if your bit file is on the Desktop, for example.
  • Test using the command in the usage section below.

macOS

Installing via Homebrew is the easiest install method on macOS. This is as simple as brew install openFPGAloader, but the official docs contain instructions for compiling from source if you're interested.

Linux

This process varies a bit on what distro you're running, but it's best described on the official docs. If you need to build from source, just leave the build options as their defaults. In our testing we haven't found a reason to change them. I've tested on Ubuntu and Debian.

OpenBSD/Solaris/Plan9

Godspeed, brave soul. 🫡 Let us know if you get it working, though if this is what you roll with, I'm guessing you're used to doing it.

Usage

We'll test your installation by trying to upload an example bitfile to your board. Download the example bitfile here, and plug in your FPGA.

By default the FPGAs are coming from the factory with a jumper not in place. Make sure the blue jumper at the top of the board is set up like shown in the photo below:

position jumper

Make sure the jumper above is in the right location, else the board won't get power.

Load the bitstream onto the board with:

openFPGALoader -b arty_s7_50 setup.bit

This command works for any bitstream built for the Urbana boards. It should hopefully produce output similar to below:

Jtag frequency : requested 6.00MHz  -> real 6.00MHz
Open file DONE
Parse file DONE
load program
Flash SRAM: [===================================================] 100.00%
Done

Once done, your board should be programmed with a file that does some random stuff like blink some LEDs if the switches are in certain configurations! If you see some sort of relational causality to button pushing and LEDs, then you're good. Bitfiles generally get put on correcty or not at all so this is a sufficient test.


 
Footnotes

1For those wondering what's actually going on here - openFPGAloader is built on libusb, which requires the WinUSB driver to be loaded on the USB devices it interacts with on Windows. Windows doesn't know about this, so it'll install it's preferred driver when the FPGA is plugged in. We need to uninstall that driver, and use WinUSB instead. That's what Zadig is for. (click to return to text)