# Examples

The repository includes several examples demonstrating different design types and testbench modes. Each example is in the `examples/` directory with its own README and Makefile.

## Combinational Logic — ALU

### SystemVerilog Mode

```bash
cd examples/ALU

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

./tb_alu_exe
# Generates test_stats.json with detailed statistics
```

### C++ Mode

```bash
cd examples/ALU_cc

# Stage 1: Generate template
stg generate \
  --verilog gate_level.v \
  --module alu_gate_level \
  --type combinational \
  --out tb.cpp \
  --out-header my_golden.h \
  --cc \
  --control-signals op

# Stage 2: Edit my_golden.h, then compile
stg generate \
  --verilog gate_level.v \
  --module alu_gate_level \
  --golden my_golden.h \
  --type combinational \
  --out tb.cpp \
  --out-exe tb_exe \
  --cc \
  --control-signals op

./tb_exe
```

## Sequential Clocked — Counter

### SystemVerilog Mode

```bash
cd examples/pingpong

stg generate \
  --verilog up_only.v \
  --module counter_up_only \
  --golden golden.v \
  --golden-module counter_golden \
  --type seq_clocked \
  --out tb.sv \
  --out-exe tb_exe \
  --clock clk \
  --reset rst_n \
  --reset-active low \
  --random-samples 1000

./tb_exe
```

### SystemC Golden Model

```bash
cd examples/pingpong_sc

stg generate \
  --verilog up_only.v \
  --golden golden_model_sc.h \
  --type seq_clocked \
  --out tb.cpp \
  --out-exe tb_exe \
  --cc \
  --clock clk \
  --reset rst_n \
  --reset-active low \
  --random-samples 100

./tb_exe
```

## Sequential with Done Signal — GCD

```bash
cd examples/GCD

stg generate \
  --verilog gcd_buggy.v \
  --module gcd \
  --golden gcd_golden.v \
  --golden-module gcd_golden \
  --type seq_done \
  --out tb.sv \
  --out-exe tb_exe \
  --clock clk \
  --reset rst \
  --reset-active high \
  --done done \
  --control-signals "" \
  --data-signals a b \
  --random-samples 100

./tb_exe
```

## Multi-DUT Comparison — ALU Implementations

Compare multiple ALU implementations against the same golden model:

```bash
cd examples/multi_dut/ALU

stg generate \
  --verilog dut1_buggy_add.v --module alu_v1 \
  --verilog dut2_buggy_sub.v --module alu_v2 \
  --verilog dut3_same_name.v --module alu_v1 \
  --golden golden_model.h \
  --type combinational \
  --out tb_multi.cpp \
  --out-exe tb_multi_exe \
  --cc \
  --control-signals op \
  --random-samples 500

./tb_multi_exe
cat test_stats.json
```

**Example output:**
```json
{
  "dut0": {"out": {"tests": 4000, "success": 3500, "score": 87.50}},
  "dut1": {"out": {"tests": 4000, "success": 3000, "score": 75.00}},
  "dut2": {"out": {"tests": 4000, "success": 4000, "score": 100.00}}
}
```

## FSM Coverage — Traffic Light

```bash
cd examples/traffic_light

stg generate-fsm traffic_light_controller.sv \
  --golden traffic_light_controller_golden.sv \
  --out tb.cpp \
  --out-exe tb \
  --clock clk \
  --reset rst_n \
  --reset-active low \
  --fsm-method deterministic \
  --verilator-coverage

./tb
```

## FSM Coverage — Sequence Detector

```bash
cd examples/seq_detector

# Set API key: export GOOGLE_API_KEY="..."
stg generate-fsm seq_detector.sv \
  --golden seq_detector_golden.sv \
  --out tb.cpp \
  --out-exe tb \
  --fsm-method lm \
  --lm-provider gemini \
  --state-analysis state_analysis.json

./tb
```

## See Also

- [Getting Started](getting_started.md) — Installation and quick start
- [Modes Overview](user_guide/modes_overview.md) — Understanding modes and design types
- [Multi-DUT Support](user_guide/multi_dut.md) — Multi-DUT details
- [FSM Coverage](user_guide/fsm_coverage.md) — FSM-based testing guide