Getting Started

A high-performance Rust implementation of the Structured Testbench Generation tool for automated Verilog/SystemVerilog testbench creation.

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

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 anywhere

Prerequisites

  • Rust toolchain (1.70 or later)

  • Custom Verilator (branch feat/cpp-linecount, based on v5.044)

  • iverilog (optional, for fallback parsing)

Installation

Install Rust

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

Build from Source

cd stg-rust
cargo build --release

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

Install Verilator

This repository requires a custom Verilator (modified from Verilator v5.044) on the feat/cpp-linecount branch. The stock Verilator from your Linux distribution will not work.

Install the build prerequisites first:

# 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)

Then build and install to a custom path:

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

git clone https://github.com/AS-SiliconMind/verilator.git /tmp/verilator
cd /tmp/verilator
git witch 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

You can change PREFIX to any path you prefer (e.g., $HOME/.usr, /opt/verilator). Just make sure $PREFIX/bin is on your PATH.

Install Icarus Verilog (iVerilog)

STG uses iVerilog v11 as a fallback parser when sv-parser cannot parse modules correctly. It is recommended but not strictly required.

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

export PATH=${PREFIX}/bin:$PATH
echo export PATH=${PREFIX}/bin:\$PATH >> ~/.bashrc

Running Tests

cargo test

See tests/README.md for detailed test information.

Quick Start

SystemVerilog Mode

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

./tb_alu_exe

C++ Mode (Two-Stage Workflow)

Stage 1: Generate golden model 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

./tb_exe

STG also supports SystemC — replace --cc with --sc.

Available Commands

Command

Description

stg generate

Generate testbench (and optionally compile)

stg generate-fsm

Generate FSM-coverage-enhanced testbench

stg identify

Identify and classify signals in a module

stg parse

Parse modules and show hierarchy

stg compile

Compile a user-provided testbench

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

What’s Next?