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.

Ubuntu 24.04 LTS can also 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).

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

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.

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:

sample output missing...

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

With these installed, the installation of cocotb and lab-bc is just like the other platforms.

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.