a human-in-the-loop training tool for rtl-developers, microarchitects and verification engineers allowing experiments with flow control and verification techniques
In other words, hdlgadgets
is a python written frontend that provides enhanced visualization and interactive interface for an HDL simulator.
hdlgadgets
contains a library of gadgets
packed in training scenarios. A gadget
may come in different forms but can generally be classified either as: a fixed block that the user can only observe during simulation; a black box container in where they can put a custom HDL code; or an auxiliary block.
- Examples of "fixed gadgets": FIFO, Pipeline register, Credit counter, Skidbuffer.
- Examples of content of a "black box gadget": custom rtl code for glue-logic, custom hdl code for transaction-level-model.
- Examples of "auxiliary gadgets": control dashboard, visual checker.
A gadget
is a module that can be reused in multiple training scenarios.
Here you can see an example of a training scenario comprised of three gadgets
: two FIFOs connected back-to-back and a control dashboard helping the user interact with the design:
hdlgadgets
requires HDL simulator running on the background (it was tested with Icarus Verilog open-source simulator which has support for SystemVerilog). To communicate with the simulator hdlgadgets
needs cocotb library:
hdlgadgets
uses hierarchical references to communicate with the simulated design. This allows to keep HDL code clean so that code can be used as the reference material for the design as is.
hdlgadgets
has been tested with the following software:
- python v3.11
- cocotb v1.8.0
- icarus_verilog v11.0
Update apt
:
sudo apt update
Install git
, IcarusVerilog
, python3
and python3-pip
— python package installer:
sudo apt install git iverilog python3 python3-pip
Install CocoTB
:
pip3 install cocotb
Get hdlgadgets
:
cd ~
git clone https://github.com/FPGA-InsideOut/hdlgadgets.git
Run start.bash
script to run the program.
cd ./hdlgadgets
./start.bash
- Enable Windows Subsystem for Linux (WSL)
- Follow instructions from https://learn.microsoft.com/en-us/windows/wsl/install
- Download Debian from Microsoft Store
- Use the direct download link OR
- Use the following command:
wsl.exe install -d Debian
- Default Windows 10 terminal does NOT support Unicode characters. Please, install the WindowsTerminal from Microsoft Store (Installation link).
Run Debian in WSL from WindowsTerminal.
Update apt
:
sudo apt update
Install git
, IcarusVerilog
, python3
and python3-pip
— python package installer:
sudo apt install git iverilog python3 python3-pip
On some Debian versions cocotb
refuse to install outside python virtual environment - if that is the case then a virtual environment shall be created
Install python3-venv
— module for managing virtual environments:
sudo apt install python3-venv
Create python3 virtual environment in user home directory:
cd ~
python3 -m venv myvirtenv
Activate virtual environment and install CocoTB inside it:
cd ~
source ./myvirtenv/bin/activate
pip3 install cocotb
Leave virtual environment (if you want to):
deactivate
Get hdlgadgets
:
cd ~
git clone https://github.com/FPGA-InsideOut/hdlgadgets.git
Activate virtual environment (if not active) and run start.bash
script to run the program:
cd ~
source ./myvirtenv/bin/activate
cd ./hdlgadgets
./start.bash
-
hdlgadgets
usescurses
library which may crash the program if it tries to draw outside terminal window. Althoughstart.bash
script checks the size of the terminal window before proceeding, it is important not to resize terminal window whilehdlgadgets
is running. -
In case of an unexpected program crash it might not be possible to see an exact reason displayed on the screen because
curses
interceptsstdout
.
To help troubleshoot the problem it is recommended to close current terminal window. And in new terminal window start problematic scenario redirecting stout
to a file on disk:
Start hdlgadgets
scenario directly using make
command:
make -B -f ./Makefile_sc1 >> ./outfile
Then you can analyze outfile
for a possible error that caused program crash.
- For Linux, standard Linux terminal can be used as it has full unicode support. On Windows10 please use WindowsTerminal and run WSL with Linux.