Setting up and running VGASIM - Pokeyy/Verilog-Pong-Project GitHub Wiki

Setting up the VGA simulator from square one takes a lot of time (probably 30min to 1hr), but it is extremely useful and speeds up development time in certain areas. I found this most useful when trying to figure out the visuals of our code, but testing out stuff like the physics/collisions were not as useful since the simulator runs very slow and may act differently compared to on the FPGA. I used Windows Subsystem for Linux, a Linux emulator within Windows, to install Ubuntu and the VGA simulator. It's a lot of work but I think it's worth it.

Pros:

  • Once fully set up, you can compile and simulate your changes in about a minute. Compare this to waiting 5+ minutes to generate bitstream and needing a VGA cable and a VGA monitor.

Cons:

  • Can't simulate UART/USB inputs (I have to detect keyboard inputs through my C++ code)
  • Simulation runs extremely slow compared to the real thing

Introduction

VGASIM and Verilator, the Verilog-to-C++ compiler that VGASIM uses, are best used with a Linux OS (honestly just think Linux is pretty good to develop on and we need real world experience with it too). Fortunately, Windows 10/11 has a built-in Linux emulator called Windows Subsystem for Linux (WSL).

1) Enabling WSL

Windows is actually running a virtual machine of Linux, so there's a few things you need to do:

  1. Enable virtualization in BIOS You can quickly check if you have virtualization enabled by opening Task Manager, going to the Performance tab, and clicking on CPU stats:

If virtualization is disabled, you need to enter your BIOS/UEFI and enable it:

https://support.microsoft.com/en-us/windows/enable-virtualization-on-windows-11-pcs-c5578302-6e43-4b4b-a449-8ced115f58e1

https://helpdeskgeek.com/how-to/how-to-enable-virtualization-in-bios-for-intel-and-amd/

  1. Open Windows search and type Turn Windows features on or off
  2. Scroll down and make sure Virtual Machine Platform and Windows Subsystem for Linux is checkmarked
  3. Hit ok, restart when prompted

2) Installing Ubuntu

  1. Open windows search, type Windows PowerShell and open it

  2. Run the command wsl --set-default-version 2

  3. Run the command wsl --update

  4. Run the command wsl --install; If this command seem to do anything, run the command wsl --install -d Ubuntu

  5. Wait for Ubuntu to install. If Ubuntu doesn't automatically open after it's done installing, you can start/enter Ubuntu by running the command ubuntu in PowerShell, Command Prompt, or searching Ubuntu in Windows search and running it from there.

  6. Ubuntu will ask you make a username and password. Put whatever username you want. When you get to making your password, the password field is in "blind-typing" mode; this means that anything you type won't show up on screen. Type your desired password, and type it again when it asks to confirm it.

  7. After entering your username and password, you should be at the command line:

3) Updating Ubuntu

  1. Run the command sudo apt update && sudo apt full-upgrade. sudo apt update looks if there's been any new releases for the already installed packages on your computer. sudo apt full-upgrade will actually download and install any updates.
  2. Run the command sudo apt install x11-apps
  3. Run the command xcalc. This should launch a calculator window from within Ubuntu. If there is an error saying something like the display cannot be started, then try doing:

---3.1 export DISPLAY=:0, then run xcalc to see if it works. If that doesn't work, then try:

---3.2 Shutdown Ubuntu by typing wsl --shutdown in PowerShell or Command Prompt. Then type wsl --set-version Ubuntu 2. Wait for that to finish, then relaunch Ubuntu again by typing ubuntu in PowerShell or Command Prompt or launching Ubuntu from Windows search. Run xcalc again to see if it works. If that doesn't work then tell me

4) Installing Verilator

Go back to your home directory by typing cd ~. cd stands for change directory, and ~ is a shortcut for your home directory. We will be cloning the Verilator repo to your home directory. Run these commands in order:

  1. sudo apt-get install git help2man perl python3 make autoconf g++ flex bison ccache -y
  2. sudo apt-get install libgoogle-perftools-dev numactl perl-doc -y
  3. sudo apt-get install libfl2 -y (Ignore if this gives an error)
  4. sudo apt-get install libfl-dev -y (Ignore if this gives an error)
  5. sudo apt-get install zlibc zlib1g zlib1g-dev -y (Ignore if this gives an error)
  6. git clone https://github.com/verilator/verilator
  7. unset VERILATOR_ROOT
  8. cd verilator
  9. git pull
  10. git checkout stable
  11. autoconf
  12. ./configure
  13. make -j `nproc`
  14. sudo make install
  15. sudo apt-get install ccache
  16. sudo apt-get install mold
  17. sudo apt-get install libgoogle-perftools-dev numactl

Verilator should now be installed.

5) Cloning our project

  1. Make sure you're at your home directory cd ~
  2. Clone our project by running the command git clone https://github.com/Pokeyy/Verilog-Pong-Project/
  3. Move into our project folder by typing cd Verilog-Pong-Project
  4. Run git pull
  5. You should now have our project files. VGASIM is already included in the project repo and my VSCode compile commands are also included in the .vscode folder.  

6) Setting up Visual Studio Code for WSL

  1. Install Visual Studio Code in Windows
  2. Open the Extensions tab by pressing the button on the left side of the screen or by pressing Ctrl+Shift+X
  3. Look for and install the WSL and Remote Development extensions
  4. In Ubuntu, run the command sudo apt-get install build-essential gdb
  5. You should still be in the directory for our GitHub repo. Run the command code . This will open a VSCode session in the project directory.
  6. Go back to the extensions tab and install C/C++, C/C++ Extensions Pack (both by Microsoft), and Verilog HDL (by leafvmaple). You should be pretty set up at this point. You can familiarize yourself with VSCode if you haven't used it much before.

7) Running Verilator and VGASIM

  1. Whenever you make changes to any Verilog files (.v), you need to rerun Verilator so that it can compile our Verilog modules into C++ code. I already have a command set up for this in the README.md file on the main repo page, but make sure you are in the Verilog-Pong-Project directory first:

verilator -cc -O3 --x-assign fast --x-initial fast --noassert pong_top.v && cd obj_dir && make OPT_FAST="-O1 -fstrict-aliasing -march=native" -f Vpong_top.mk Vpong_top__ALL.a && cd ..

  1. Open/switch to the vgs_tb.cpp file in VSCode. After running Verilator, you can press the Play/Run C++ File button at the top right of the code window (looks like a play button) to compile the C++ code. The simulator should start automatically after building.

  2. You can control the left and right paddles by focusing the VGA simulator window and using W/S keys for left paddle, Up Arrow/Down Arrow for right paddle. Currently, if you release any key it will reset any other input, so the keyboard input on the sim does not match the actual keyboard input on the FPGA.

Extra notes:

  • I recommend working entirely within Ubuntu to simplify organization. That means you need to tell Vivado to open all files from inside Ubuntu. You can open the files by going to \\wsl.localhost\Ubuntu\home, double-clicking your username folder, then going into the Verilog-Pong-Project folder and selecting the .v files.
  • You can shutdown Ubuntu for whatever reason by typing the command wsl --shutdown in PowerShell or Command Prompt or the terminal inside of VSCode.
  • Since Ubuntu is inside a virtual machine, Windows connects to it via a local network interface. Within Ubuntu, you can type explorer.exe . to launch the file explorer at your current directory. You can also add Ubuntu as a network location in your file explorer:
  1. Open This PC on Windows
  2. Right click any blank space and click Add a network location
  3. Click Next twice or until it asks you to specify the location of your website
  4. Enter \\wsl.localhost\Ubuntu and hit next until finished
  5. You can now access Ubuntu's file system.