docs/USER_GUIDE.md

UVM Verification Framework — User Guide

Overview

Automated UVM testbench generation from YAML / FuseSoC .core specifications. Outputs a complete, ready-to-compile UVM environment for protocol interfaces (UART, SPI, I2C, APB, AXI4-Lite, Wishbone) with AI/ML-powered coverage optimization.

Architecture

Spec (.core / .yaml)
       |
       v
 Generation Engine (Jinja2 + ML)
       |
       v
 +----------------------------+
 |  Generated UVM Testbench  |
 |  +----------------------+ |
 |  | testbench.sv          | |
 |  | interface_{name}.sv   | |
 |  | sequence_item_{n}.sv  | |
 |  | driver_{name}.sv      | |
 |  | monitor_{name}.sv     | |
 |  | agent_{name}.sv       | |
 |  | env_{name}.sv         | |
 |  | scoreboard_{name}.sv  | |
 |  | coverage_collector.sv | |
 |  | protocol_checker.sv   | |
 |  | ral_model_{name}.sv   | |
 |  | base_sequence_{n}.sv  | |
 |  | test_{name}.sv        | |
 |  +----------------------+ |
 +----------------------------+

Quick Start

1. Install

pip install -r requirements.txt
pip install -r requirements-dev.txt   # optional: dev/lint

2. Generate a UVM testbench

# From YAML spec
python -m src.main --spec configs/uart_demo.yaml

# From FuseSoC .core spec
python -m src.main --spec configs/uart16550-1.5.core

# With auto-training (AI coverage optimization)
python -m src.main --spec configs/uart16550-1.5.core --auto-train --max-iterations 3

3. Output

output/{design_name}_tb/
  testbench.sv              # Top-level module
  interface_{name}.sv       # Clocking + modport
  sequence_item_{name}.sv   # Transaction object
  driver_{name}.sv          # Bus driver
  monitor_{name}.sv         # Bus monitor
  agent_{name}.sv           # Agent (sequencer + driver + monitor)
  environment_{name}.sv     # Env (agent + scoreboard + coverage + RAL)
  scoreboard_{name}.sv      # Scoreboard (TX/RX compare, error check)
  coverage_collector_{name}.sv  # Functional coverage groups
  protocol_checker_{name}.sv    # SVA assertions
  ral_model_{name}.sv       # RAL model + adapter + predictor
  base_sequence_{name}.sv   # Sequence library
  test_{name}.sv            # Test library
  compile.f                 # Compile file list
  sim_{name}.tcl            # Simulation script

Spec Format

YAML format

design_name: uart16550
protocol: uart

interfaces:
  - name: bus
    direction: slave
    protocol: wishbone
    signals:
      - {name: addr, direction: input, width: 3}
      - {name: data_in, direction: input, width: 8}
      - {name: data_out, direction: output, width: 8}

  - name: serial
    direction: master
    protocol: uart
    signals:
      - {name: tx, direction: output, width: 1}
      - {name: rx, direction: input, width: 1}

registers:
  - name: RBR
    address: 0x00
    access: ro
    size: 8
    description: Receiver Buffer Register
  - name: THR
    address: 0x00
    access: wo
    size: 8
  - name: IER
    address: 0x01
    access: rw
    size: 8
  - name: LCR
    address: 0x03
    access: rw
    size: 8
    reset: 0x03

clocks:
  clk: 50MHz
  reset: {name: rst_n, polarity: active_low}

FuseSoC .core format

See configs/uart16550-1.5.core for a complete example.

UVM VIP Integration

Packaging as a VIP

The generated output is structured as a self-contained UVM Verification IP:

{design_name}_vip/
  pkg/
    {design_name}_vip_pkg.sv       # UVM package (all files)
    {design_name}_reg_pkg.sv        # RAL package
  src/
    {design_name}_if.sv             # Interface
    {design_name}_agent.sv          # Agent
    {design_name}_env.sv            # Environment
    {design_name}_driver.sv         # Driver
    {design_name}_monitor.sv        # Monitor
    {design_name}_scoreboard.sv     # Scoreboard
    {design_name}_coverage.sv       # Coverage collector
    {design_name}_checker.sv        # Protocol checker
    {design_name}_ral.sv            # RAL model
    {design_name}_sequences.sv      # Sequence library
    {design_name}_tests.sv          # Test library
  sim/
    compile.f                       # Compile list
    sim.do                          # Questa script
    sim.tcl                         # Generic TCL script
  examples/
    smoke_test.sv                   # Standalone testbench

Integration into a larger SoC environment

// 1. Import the VIP
import uart_vip_pkg::*;

// 2. Instantiate interface
uart_if uart_if_inst (
  .clk   (sys_clk),
  .rst_n (sys_rst_n),
  .tx    (uart_tx),
  .rx    (uart_rx)
);

// 3. Configure via config_db
initial begin
  uvm_config_db#(virtual uart_if)::set(
    null, "uvm_test_top", "vif", uart_if_inst
  );
end

// 4. Run test
initial begin
  run_test("uart_smoke_test");
end

Configuration parameters

Parameter	Type	Default	Description
protocol	string	"uart"	Protocol selection
model_type	string	"v2"	Generation model (template / v2)
rl_strategy	string	"ucb"	RL exploration strategy
enable_learning	bool	true	Enable RL + coverage feedback
strict_uvm	bool	true	Generate IEEE 1800.2 compliant code
max_iterations	int	1	Auto-training iterations

AI/ML Features

Coverage Prediction

The coverage predictor uses a 3-model ensemble (RandomForest + GradientBoosting + LinearRegression) with Ridge meta-blender to predict functional coverage gaps and suggest targeted sequences.

Reinforcement Learning

Q-learning with:

• Double Q-learning (two independent Q-tables)
• Prioritized experience replay
• N-step returns
• Eligibility traces
• 5 exploration strategies (epsilon-greedy, softmax, UCB, Thompson, NoisyNet)

States are encoded as {protocol}:{file_type}:{complexity}.

Auto-Training Loop

1. Generate UVM testbench
2. Run simulation (or stub)
3. Predict coverage gaps
4. Generate targeted sequences
5. Re-train RL model
6. Repeat until coverage target met

Regression Management

Running regressions

# Single test
python -m src.main --spec configs/uart16550-1.5.core \
  --test smoke

# All tests
python regression/run_regression.py \
  --spec configs/uart16550-1.5.core

# Multi-seed regression
python regression/run_regression.py \
  --spec configs/uart16550-1.5.core \
  --seeds 100 \
  --tests smoke,loopback,interrupt

YAML regression spec

regression:
  name: uart_full_regression
  spec: configs/uart16550-1.5.core
  tests:
    - uart_smoke_test
    - uart_reg_access_test
    - uart_loopback_test
    - uart_interrupt_test
    - uart_fifo_test
    - uart_random_test
  seeds: [10, 20, 30, 50, 100]
  simulator: questa
  coverage: true
  output: results/

Simulator Support

Simulator	Status	Notes
Questa/ModelSim	✅	Full support via .do / .tcl script
VCS	✅	Compatible (IEEE 1800.2 compliant)
Xcelium	✅	Compatible
Icarus Verilog	✅	Basic support (stub mode)

Project Structure

UVM-verification/
  configs/             # Spec files (.yaml, .core)
  docs/                # Documentation
  frontend/            # React UI
  protocols/           # Protocol definitions (UART, SPI, I2C, etc.)
  regression/          # Regression scripts
  src/                 # Core engine
    features/          # Spec feature extraction
    generation/        # Template engine
      templates/       # Jinja2 UVM templates
    models/            # ML models (RL, coverage predictor, etc.)
    evaluation/        # Quality scoring, SV checking
    pipeline.py        # Auto-training pipeline
  vip/                 # Packaged VIP files
  output/              # Generated testbenches

Testing

# Run unit tests
python -m pytest tests/

# Test coverage prediction
python -m pytest tests/test_coverage_predictor.py -v

# Test RL learner
python -m pytest tests/test_rl_learner.py -v

# Test pipeline end-to-end
python test_pipeline.py

Docker

docker-compose up --build
# Frontend: http://localhost:7860
# API:      http://localhost:8000/docs

License

MIT License — see LICENSE file.