# Multi-DUT Support

STG can test multiple Design Under Test (DUT) implementations simultaneously against the same golden reference, making it easy to compare different implementations.

## Basic Multi-DUT Usage

Specify multiple DUT files with repeated `--verilog` flags:

```bash
stg generate \
  --verilog dut1.v --verilog dut2.v --verilog dut3.v \
  --golden golden_model.h \
  --type combinational \
  --out testbench.cpp \
  --out-exe testbench_exe \
  --cc
```

Or use comma-separated syntax:

```bash
stg generate \
  --verilog dut1.v,dut2.v,dut3.v \
  --golden golden_model.h \
  --type combinational \
  --out testbench.cpp \
  --out-exe testbench_exe \
  --cc
```

## Module Selection

STG provides three ways to specify modules for multiple DUTs:

### Single Module Name (Used for All DUTs)

When all DUT files contain the same module name:

```bash
stg generate \
  --verilog dut1.v --verilog dut2.v \
  --module alu_v1 \
  --golden golden_model.h \
  --type combinational \
  --out testbench.cpp \
  --cc
```

### Comma-Separated Module Names

Match modules serially with DUT files:

```bash
stg generate \
  --verilog dut1.v --verilog dut2.v --verilog dut3.v \
  --module alu_v1,alu_v2,alu_v1 \
  --golden golden_model.h \
  --type combinational \
  --out testbench.cpp \
  --cc
```

### Interleaved Specification (Explicit Pairing)

Pair each `--verilog` with a `--module` for clarity:

```bash
stg generate \
  --verilog dut1.v --module alu_v1 \
  --verilog dut2.v --module alu_v2 \
  --verilog dut3.v --module alu_v1 \
  --golden golden_model.h \
  --type combinational \
  --out testbench.cpp \
  --cc
```

### No Module Specified

STG uses the first module from each DUT file:

```bash
stg generate \
  --verilog dut1.v --verilog dut2.v \
  --golden golden_model.h \
  --type combinational \
  --out testbench.cpp \
  --cc
```

## Multi-DUT in SystemVerilog Mode

In SV mode, use `--emplace-module` when DUT modules have naming conflicts:

```bash
stg generate \
  --verilog dut1.v --verilog dut2.v \
  --golden golden.v \
  --type combinational \
  --out testbench.sv \
  --out-exe testbench_exe \
  --emplace-module
```

This adds prefixes like `V0_`, `V1_` to differentiate DUT modules.

## Multi-DUT in C++/SystemC Mode

In CC/SC mode, each DUT is compiled with a unique prefix automatically (no `--emplace-module` needed):

```bash
stg generate \
  --verilog dut1.v --verilog dut2.v --verilog dut3.v \
  --golden golden_model.h \
  --type combinational \
  --out testbench.cpp \
  --out-exe testbench_exe \
  --cc
```

This generates classes like `V0_DUT`, `V1_DUT`, `V2_DUT` for each DUT.

## Multi-DUT with Sequential Designs

Multi-DUT works with all design types:

```bash
stg generate \
  --verilog gcd_impl1.sv --verilog gcd_impl2.sv --verilog gcd_impl3.sv \
  --golden gcd_golden.h \
  --type seq_done \
  --out testbench.cpp \
  --out-exe testbench_exe \
  --cc \
  --clock clk \
  --reset rst_n \
  --done done \
  --random-samples 50
```

In `seq_done` mode, the testbench waits for all DUTs to complete before comparing results.

## Test Statistics (JSON Output)

Multi-DUT testbenches generate per-DUT statistics in `test_stats.json`:

```json
{
  "dut0": {
    "out": {"tests": 1024, "success": 1020, "score": 99.61}
  },
  "dut1": {
    "out": {"tests": 1024, "success": 856, "score": 83.59}
  },
  "dut2": {
    "out": {"tests": 1024, "success": 1024, "score": 100.00}
  }
}
```

Each entry contains:
- **tests**: Total number of test cases per output signal
- **success**: Number of successful comparisons
- **score**: Success rate as a percentage

### Custom Statistics File Location

Use the `+STATS_FILE=` runtime argument to specify a custom output path:

```bash
./tb_exe +STATS_FILE=results/comparison_$(date +%Y%m%d).json
```

## See Also

- [SystemVerilog Mode](sv_mode.md) — SV mode details including module emplacement
- [C++/SystemC Mode](cc_sc_mode.md) — CC/SC mode two-stage workflow
- [Examples](../examples.md) — Multi-DUT example with ALU implementations