# Advanced Features

This page covers advanced STG features including YAML configuration, coverage analysis, custom compiler flags, and best practices.

## YAML Configuration

Create a config file to avoid repeating command-line arguments:

**config.yaml:**
```yaml
module: my_alu
golden_module: alu_golden
clock: clk
reset: rst_n
reset_active: low
control_signals:
  - op
  - mode
data_signals:
  - a
  - b
```

**Usage:**
```bash
stg generate \
  --verilog dut.v \
  --golden golden.v \
  --type combinational \
  --out tb.sv \
  --config config.yaml
```

Command-line arguments override config file values.

## Verilator Coverage Analysis

Enable coverage instrumentation to measure how well your tests exercise the DUT.

```{note}
SV mode does not support coverage analysis with MPI, as multiple processes write to the same file. In CC/SC mode, coverage filenames include rank suffixes to avoid conflicts.
```

### Single DUT

```bash
stg generate \
  --verilog dut.v \
  --golden golden.v \
  --type combinational \
  --out tb.sv \
  --out-exe tb_exe \
  --verilator \
  --verilator-coverage

./tb_exe
# Coverage data written to coverage.dat
verilator_coverage --annotate coverage_report coverage.dat
```

### FSM Runtime Line Checks (`generate-fsm`)

`generate-fsm` supports stricter transition validation with line execution counters:

```bash
stg generate-fsm dut.sv \
  --golden golden.sv \
  --out tb.cpp \
  --out-exe tb \
  --fsm-method deterministic \
  --line-coverage-check
```

Notes:

- `--line-coverage-check` automatically adds Verilator `--coverage` for this flow.
- Transition success requires both state/wait-condition success and coverage counter movement.
- `test_stats.json` includes:
  - `line_coverage_check_enabled`
  - `line_check_passed_transitions`
  - `line_check_failed_transitions`
  - per-edge `lines_executed`

### Verilator Binary Path

STG looks for `verilator` on your `PATH` by default.

To override with a specific binary:

```bash
export STG_VERILATOR_PATH=/path/to/verilator
```

### Multi-DUT (C++/SystemC Mode)

```bash
stg generate \
  --verilog dut1.v --verilog dut2.v \
  --golden golden_model.h \
  --type combinational \
  --out tb.cpp \
  --out-exe tb_exe \
  --cc \
  --verilator-coverage

./tb_exe
verilator_coverage --annotate coverage_report coverage.dat
```

## Custom Compiler Flags

Pass additional flags to iverilog or Verilator:

```bash
stg generate \
  --verilog dut.v \
  --golden golden.v \
  --type combinational \
  --out tb.sv \
  --out-exe tb_exe \
  --verilator \
  --compile-flags --trace --trace-fst
```

## Tips and Best Practices

1. **Start with SV mode** — It's simpler and works for most cases
2. **Use `--cc` for complex golden models** — C++ gives you more flexibility
3. **Specify control signals explicitly** — `--control-signals` improves test coverage
4. **Use Verilator for large designs** — Much faster than iverilog
5. **Enable MPI for very large designs** — Parallel execution can save hours
6. **Use `--debug` to troubleshoot** — Shows detailed signal values
7. **Save configs in YAML** — Reusable and version-controllable
8. **Use `stg compile` for iteration** — Faster when modifying testbenches manually
9. **Check `test_stats.json`** — Automatically generated with per-DUT, per-signal statistics
10. **Use multi-DUT for comparison** — Test multiple implementations simultaneously
11. **Customize statistics output** — Use `+STATS_FILE=custom_name.json` at runtime

## See Also

- [Modes Overview](modes_overview.md) — Compare testbench modes
- [Multi-DUT Support](multi_dut.md) — Multi-DUT testing details
- [CLI Reference](../reference/cli.md) — Complete flag reference
- [Troubleshooting](../troubleshooting.md) — Common issues and solutions