# 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 ```bash pip install -r requirements.txt pip install -r requirements-dev.txt # optional: dev/lint ``` ### 2. Generate a UVM testbench ```bash # 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 ```yaml 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 ```systemverilog // 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 ```bash # 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 ```yaml 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 ```bash # 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 ```bash docker-compose up --build # Frontend: http://localhost:7860 # API: http://localhost:8000/docs ``` ## License MIT License — see LICENSE file.