STG-Rust - Structured Testbench Generation

Our papers using STG

1. Structured Testbench Generation for LLM-Driven HDL Design and Verification-Oriented Data Curation, arXiv preprint, 2026
2. EvolVE: Evolutionary Search for LLM-based Verilog Generation and Optimization, arXiv preprint, 2026
3. Another two papers under reviewing...

What is STG?

STG automatically generates comprehensive testbenches for digital designs by:

• Parsing your Verilog/SystemVerilog modules
• Classifying signals (control vs. data, inputs vs. outputs)
• Generating semi-exhaustive test patterns
• Comparing DUT (Design Under Test) against a golden reference
• Supporting both SystemVerilog and C++/SystemC testbenches

Installation

Prerequisites

• Rust toolchain (1.70 or later)
• Custom Verilator (branch feat/cpp-linecount, based on v5.044)
• iverilog (optional, for SystemVerilog mode fallback parsing)

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Restart terminal to update environment variables

Install System-Wide (Recommended)

cargo install --path .

This process compiles stg on your computer and installs it to $HOME/.cargo/bin/. The compilation process involves compiling third-party dependencies, but it will not take long. By default, after installing Rust's toolchain, $HOME/.cargo/bin will be added to your $PATH environment variable. Therefore, you can invoke stg directly from anywhere, without setting up a virtual environment like Python.

Install Verilator

This repository requires a custom Verilator (modified from Verilator v5.044) on the feat/cpp-linecount branch. The stock Verilator from your distribution will not work. Use the following script to build and install it to a custom path:

# Prerequisites (Ubuntu/Debian):
sudo apt-get install git help2man perl python3 make autoconf g++ flex bison ccache
sudo apt-get install libgoogle-perftools-dev numactl perl-doc
sudo apt-get install libfl2 libfl-dev        # Ubuntu only (ignore errors)
sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore errors)

# Set your desired install location
PREFIX=$HOME/.local/verilator

git clone https://github.com/AS-SiliconMind/verilator.git /tmp/verilator
cd /tmp/verilator
git switch feat/cpp-linecount

unset VERILATOR_ROOT
autoconf
./configure --prefix=$PREFIX
make -j `nproc`
make install
cd -
rm -rf /tmp/verilator

# Add Verilator to PATH (current session + persist across logins)
export PATH=$PREFIX/bin:$PATH
echo 'export PATH=$HOME/.local/verilator/bin:$PATH' >> ~/.bashrc

Install Icarus Verilog (iVerilog)

This repository utilizes iVerilog v11 for module's name and port parsing if sv-parser does not parse the modules correctly. It is recommended to install iVerilog, but it is not nessecerly.

IVERILOG_VERSION=v11-branch
PREFIX=$HOME/.usr

pushd /tmp/
git clone https://github.com/steveicarus/iverilog.git
cd iverilog
git checkout ${IVERILOG_VERSION}

sh autoconf.sh
./configure --prefix=${PREFIX}
make -j `nproc`
make install
popd
rm -r /tmp/iverilog

# Set the PATH environment variable
export PATH=${PREFIX}/bin:$PATH
echo export PATH=${PREFIX}/bin:\$PATH >> ~/.bashrc

Build STG from Source

cd stg-rust
cargo build --release

The binary will be available at target/release/stg.

Tests

A group of tests are provided to verify if the current stg works as expected, but it does not cover all combinations. Check tests/README.md for detailed information.

# Perform all tests
cargo test

Quick Start

Basic Testbench Generation (SystemVerilog)

stg generate \
  --verilog examples/ALU/gate_level.v \
  --module alu_gate_level \
  --golden examples/ALU/golden.v \
  --golden-module alu_golden \
  --type combinational \
  --out tb_alu.sv \
  --out-exe tb_alu_exe \
  --control-signals op

# Run the testbench
./tb_alu_exe

C++ Testbench with Custom Golden Model in C++

STG also supports System-C, replace --cc with --sc to use System-C.

Stage 1: Generate template

stg generate \
  --verilog examples/ALU/gate_level.v \
  --type combinational \
  --out tb.cpp \
  --out-header golden_model.h \
  --cc \
  --control-signals op

Stage 2: Implement golden model in golden_model.h, then compile

stg generate \
  --verilog examples/ALU/gate_level.v \
  --golden golden_model.h \
  --type combinational \
  --out tb.cpp \
  --out-exe tb_exe \
  --cc \
  --control-signals op

# Run the testbench
./tb_exe

Performance Benefits

The Rust implementation offers:

• Better error messages with detailed context
• Type safety preventing entire classes of bugs
• Native binary - no Python interpreter required, the compiled binary can be shipped to anywhere

Documentation

• USAGE.md - Comprehensive usage guide covering:
  • SystemVerilog mode (traditional)
  • C++/SystemC mode (two-stage workflow)
  • Compilation options and flags
  • Advanced features and examples

Available Commands

• stg generate - Generate testbench (and optionally compile)
• stg identify - Identify and classify signals in a module
• stg compile - Compile user-provided testbench files

Run stg --help or stg <command> --help for detailed options.

Examples

The repository includes several examples demonstrating different use cases:

• examples/ALU/ - Combinational logic (ALU with 8 operations)
• examples/ALU_cc/ - Same ALU with C++ testbench
• examples/pingpong/ - Sequential clocked design (counter)
• examples/pingpong_sc/ - Same counter with SystemC golden model
• examples/GCD/ - seq_done design (GCD algorithm)

License

MIT (same as the Python version)