Verilog Meetup

Language, microarchitecture and design verification – for the industry and education

Notes on using basics-graphics-music repo under Linux and Windows

articles Yuri Panchul

The Git repository of introductory Verilog examples, basics-graphics-music, uses Bash scripts for all user operations on Linux and Windows. For Windows users, we recommend using the Bash shell included in Git for Windows application.

You can download Git for Windows from either https://git-scm.com/download/win or https://gitforwindows.org.

When running the Git for Windows installer, we recommend checking the option “Use Git and optional Unix tools from the Command Prompt.” This will allow running Bash scripts under VSCode, a setup we frequently use during Verilog Meetup seminars.

You can still run Bash scripts if you don’t check this option, but you would have to start a separate Git Bash window and switch between VSCode and Git Bash.

Once you install Git for Windows and the applicable FPGA synthesis toolchain (Xilinx Vivado, Altera Quartus, Gowin IDE or Yosys-based toolchain), you can clone the repository in the command line. This can be done either in Windows Command Prompt or in Git Bash window, or in a terminal inside VsCode:


git clone https://github.com/yuri-panchul/basics-graphics-music.git

If the repository is already cloned, cd inside and “git pull” to get the latest version.

On Linux, you usually have Git already installed. If you don’t, use “sudo apt-get install git” for Ubuntu or similar commands for other distributions.

Also, if you use Linux and Gowin toolchain, you need to install openFPGALoader. For Windows, the scripts use loading software from Gowin, not openFPGALoader.

We usually use the VSCode editor during seminars since it reasonably fits the majority of the students under both Linux and Windows, with different FPGA toolchains. Once you start VSCode, we recommend to open the directory where you cloned the basic-graphics-misic repository:

Then you create a terminal within VSCode:

Then you enter the following commands. You can use <Tab> autocompletion when you enter the commands in the VSCode terminal:

Under Windows:


cd .\labs\2_graphics\2_1_rectangle_ellipse_parabola\
bash 03_synthesize_for_fpga.bash

Under Linux you would enter:


cd labs/2_graphics/2_1_rectangle_ellipse_parabola
./03_synthesize_for_fpga.bash

When you run this script the first time, it will output the following menu so you can choose a board. For Tang Nano 9K with 4.3-inch LCD and attached TM1638-based board, you would enter a number from the corresponding menu line (in this case 53, but this number is not fixed). You don’t need to enter this number every time you run the script – your selection will be recorded until you change it using another script, 06_choose_another_fpga_board.bash.

This selection corresponds to the following setup:

Now the synthesis script starts running. For this particular board, which uses Gowin FPGA, the script expects to find Gowin IDE installed in one of the default locations:

Linux:

  1. $HOME/Gowin
  2. $HOME/gowin
  3. /opt/Gowin
  4. /opt/gowin
  5. /tools/Gowin
  6. /tools/gowin

Windows:

  1. C:\Gowin
  2. D:\Gowin
  3. E:\Gowin

A custom Gowin installation home location can be set by GOWIN_HOME environment variable such as ‘GOWIN_HOME=/home/verilog’. You can also use GOWIN_VERSION_DIR to specify the version subtree location, such as ‘GOWIN_VERSION_DIR=/home/verilog/gowin/0.99’.

If the synthesis script failed at the end because the board is not connected, you don’t need to re-run the synthesis; connect the board and run configuration only:

For Linux:


./04_configure_fpga.bash

For Windows or Linux:


bash 04_configure_fpga.bash

The recommended labs to run to check that everything on the board is working:

  • 1_basics/1_09_hex_counter – checks TM1638.
  • 2_graphics/2_1_rectangle_ellipse_parabola – checks graphics.
  • 3_music/3_1_note_recognizer – checks the microphone.
  • 3_music/3_3_note_synthesizer – checks the audio decoder.
  • 4_microarchitecture/4_2_fifo/4_2_3_fifo_with_better_debug_1 – microarchitectural lab, use keys to push and pop values.
  • 5_cpu/5_1_schoolriscv – a minimalistic RISC-V subset CPU; see another post for more details.

UPD: After this post we at Verilog Meetup worked with Gowin Semiconductor marketing and they helped us prepare the following instructions on how to setup Gowin EDA software, assemble a board set and run the examples:

GOWIN EDA Quick Start Guide V6

TangNano9KBoardSetupV3

Tang Nano 9K Synthesis and Configuration V6