# Getting Started

A high-performance Rust implementation of the [Structured Testbench Generation](https://github.com/AS-SiliconMind/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](https://github.com/AS-SiliconMind/verilator/) (branch `feat/cpp-linecount`, based on v5.044)
- [iverilog](http://iverilog.icarus.com/) (optional, for fallback parsing)

## Installation

### Install Rust

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

### Install STG System-Wide (Recommended)

```bash
cargo install --path .
```

This compiles `stg` and installs it to `$HOME/.cargo/bin/`. By default, after installing Rust's toolchain, `$HOME/.cargo/bin` is added to your `$PATH`, so you can invoke `stg` directly from anywhere.

### Build from Source

```bash
cd stg-rust
cargo build --release
```

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

### Install Verilator

This repository requires a [custom Verilator](https://github.com/AS-SiliconMind/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:

```bash
# 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:

```bash
# 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](https://github.com/dalance/sv-parser) cannot parse modules correctly. It is recommended but not strictly required.

```bash
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

```bash
cargo test
```

See [tests/README.md](https://github.com/AS-SiliconMind/stg-rust/blob/main/tests/README.md) for detailed test information.

## Quick Start

### SystemVerilog Mode

```bash
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**
```bash
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**
```bash
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?

- [Modes Overview](user_guide/modes_overview.md) — Understand the three testbench modes and design types
- [SystemVerilog Mode](user_guide/sv_mode.md) — Full SV workflow guide
- [C++/SystemC Mode](user_guide/cc_sc_mode.md) — Two-stage CC/SC workflow guide
- [CLI Reference](reference/cli.md) — Complete flag reference for all commands