Windows Guide

The Execution Environments

On Windows, we¹ have many options for running software, which has turned into both a blessing and a curse. The TL;DR is that we will use WSL, but the explanations of the 3 main options are the below:

• Windows: this can be used to run Vivado, some prebuilt versions of iverilog and gtkwave, but openFPGALoader doesn't really have prebuilt binaries, so that is a roadblock. In addition, though PowerShell and Winget aren't terrible, they aren't really as convenient in this case as a Linux package manager and shell.
• WSL: WSL is great for a bunch of reasons. It is pretty easy to install on newer versions of Windows, and gives an almost-full Linux experience, which even includes GUI support these days. Recent versions of iverilog, gtkwave, and openFPGALoader can all be installed with apt or from source in Ubuntu 24.04, but the Achilles' heel of WSL has been support for external devices, including USB devices. However, as a somewhat recent development, there is a Microsoft-endorsed third-party open-source project called usbipd-win, which forwards USB device control from Windows to the WSL Linux kernel, which has gotten to a pretty stable and usable point.
• MSYS2: though not as "official" as Microsoft's WSL effort, MSYS2 has similar functionality. However, instead of running actual Linux, it provides a Linux-like environment and packages that are compiled to run natively on Windows through a compatibility layer. MSYS2 uses pacman, so again, all of the required packages can be easily installed. Because MSYS2 runs natively, it has normal access to external devices, and thus it was, originally and for the past couple years, the 6.205-tested-and-verified way of using openFPGALoader on Windows.

As in the above outline, it is possible to run different software in different environments, but this can lead to some headache trying to remember which packages are installed where, which environment's Python you are using, etc.

So, for that reason, it can make things a lot smoother to load all of the software into a single environment, and use just that for all 6.205-related stuff. In this case, because it is the more modern solution and has reached pretty good stability, we will be recommending WSL², for using the tools needed for the course. MSYS2 can be thought of as the legacy option for those whose Windows installs don't support WSL2 features for some reason or another.

If you are having issues with the WSL installation, either come to office hours, ask for help on Piazza, and if all else fails, try the MSYS2 installation instructions, which are here.

How to Setup WSL2 for 6.205

(Recommended) Installing Windows Terminal

Though WSL can be used through other terminal emulators, I would generally recommend using Windows Terminal, which was built with the whole multiple environments idea in mind.

Windows Terminal can be installed through the Windows Store³ like any other Windows Store app. The link is provided here.

Installing Ubuntu 24.04

If you already have an up-to-date installation of Ubuntu on WSL, you can probably skip this step.

Before installing a distribution, make sure the optional Windows WSL components are enabled by running, in a PowerShell window with admin privileges, the following:

wsl --install --no-distribution

You will likely need to restart your computer for the Windows features to come online.

For a distro, Ubuntu 24.04 LTS can be installed through the Windows Store here. Installing the newest LTS version directly provides access to more up-to-date packages in apt without having to upgrade Ubuntu from 22.04 to 24.04 in WSL⁴.

Once installed, click the Open button on the Windows Store page to open Ubuntu. If Windows Terminal is already installed, opening Ubuntu through the Windows Store should also automatically add a profile called Ubuntu 24.04 LTS in the tab dropdown and open Ubuntu in a new Windows Terminal window.

After some installation and creating a UNIX account, get apt up and running:

sudo apt update
sudo apt upgrade

In order to access external devices in WSL2, systemd needs to be enabled, so make sure the following lines are in /etc/wsl.conf:

[boot]
systemd=true

They should be there automatically on new installations, but WSL didn't always support systemd, so it might be missing from older installations.

Installing Icarus Verilog and GTKWave

They can be can be installed with apt:

sudo apt install iverilog gtkwave

Run iverilog -v, which should show that stable version 12.0 is installed.

To test that WSLg support is working, run gtkwave (without arguments). It should pop up an empty waveform window, with the GTKWave logo, with a small Linux penguin in the corner, on the taskbar.

If GTKWave fails to open and gives an error like the following:

Could not initialize GTK!  Is DISPLAY env var/xhost set?

Then make sure that the version of WSL being used is the up-to-date by running wsl --update from PowerShell (not Ubuntu) or wsl.exe --update from Ubuntu. Then open a new Ubuntu shell tab/window (the update doesn't take effect until then).

Install openFPGALoader

This is probably the trickiest part to install.

The first step is to install openFPGALoader from source, as recommended in the installation instructions.

Start by installing the build dependencies:

sudo apt install \
  git \
  gzip \
  libftdi1-2 \
  libftdi1-dev \
  libhidapi-hidraw0 \
  libhidapi-dev \
  libudev-dev \
  zlib1g-dev \
  cmake \
  pkg-config \
  make \
  g++

Then clone the repo and build:

git clone https://github.com/trabucayre/openFPGALoader
cd openFPGALoader
mkdir build
cd build
cmake ..
cmake --build .

And lastly, install the outputs to /usr/local:

sudo make install

You also need to update the udev rules, by running the following from the openFPGALoader root directory (cd .. from the build dir):

sudo cp 99-openfpgaloader.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
sudo usermod -a $USER -G plugdev

So, that is the first step. However, if you run openFPGALoader --detect with your FPGA plugged in, you will probably get something like the following:

No cable or board specified: using direct ft2232 interface
unable to open ftdi device: -3 (device not found)
JTAG init failed with: unable to open ftdi device

This is because WSL2 does not have access to external devices by default, so they need to be explicitly delegated to the Linux kernel from Windows. This can be done with the usbipd-win library. To install the library, run the MSI installer from the most recent release (link), or run the following command in PowerShell.

winget install usbipd

Next, open a new PowerShell window in administrator mode, and, with the FPGA powered on and plugged into to your computer, run usbipd list, for which the output should include the following:

BUSID  VID:PID    DEVICE                                                        STATE
2-4    0403:6010  USB Serial Converter A, USB Serial Converter B                Not shared

The BUSID field might be different (it depends on which USB port the FPGA is plugged into), but the VID:PID field should be 0403:6010 as above. For now, the device is not shared, but that is what we are about to change.

To share the device, run usbipd bind --hardware-id=0403:6010. This should share the device, so if you run the usbipd list command again, it should show the following:

BUSID  VID:PID    DEVICE                                                        STATE
2-4    0403:6010  USB Serial Converter A, USB Serial Converter B                Shared

usbipd: warning: USB filter 'xyz' is known to be incompatible with this software; 'bind --force' will be required.

At this point, administrator privileges are not longer required. The commands run above should only need to be run once per device, so it you unplug and replug the same FPGA, the commands should not need to be run again.

In order to move the device from Windows to Linux (only one has ownership at a time), run usbipd attach --wsl --hardware-id=0403:6010. If you have sound on on your computer, you should hear the device unplugged sound. This command does need to be rerun each time the device is plugged in / power cycles, so there is also a --auto-attach flag which will more or less busy loop to reattach the device.

usbipd attach --wsl --hardware-id=0403:6010

usbipd.exe attach --wsl --hardware-id=0403:6010

To check that the USB device is now visible in Linux, the FTDI device should appear in the output of lsusb, and ttyUSB0 and ttyUSB1 should be included in ls /dev in Ubuntu.

At this point, running openFPGALoader --detect should successfully find the FPGA:

$ openFPGALoader --detect
empty
No cable or board specified: using direct ft2232 interface
Jtag frequency : requested 6.00MHz   -> real 6.00MHz
index 0:
        idcode 0x362f093
        manufacturer xilinx
        family spartan7
        model  xc7s50
        irlength 6

Install Python-based Tools

Though python3 is included in Ubuntu, you will need to install pip and venv, separately:

sudo apt install python3-pip python3-venv

Remaining Steps

At this point, the installation of cocotb and lab-bc (the remote Vivado build client) is just like the other platforms and can be done by following the steps for Ubuntu on the main documentation pages. You should also follow the openFPGALoader test on its setup page (skip the MSYS2 and Zadig stuff).

sudo apt install libtinfo6 libncurses6
sudo ln -s /usr/lib/x86_64-linux-gnu/libtinfo.so.6 /usr/lib/x86_64-linux-gnu/libtinfo.so.5
sudo ln -s /usr/lib/x86_64-linux-gnu/libncurses.so.6 /usr/lib/x86_64-linux-gnu/libncurses.so.5

Editors in WSL2

Using WSL2 doesn't come with any downsides in terms of editor choice, as you can use all of the terminal editors like vim, neovim⁸, emacs⁹, you can use the WSL mode in vscode, or, heck, you can even use gedit from the WSLg GUI.