DSIM UVM Test Workflow

PowerShell script-based workflow for the AXIUART_RV32I verification environment.

When to Use This Skill

Compiling or running UVM tests
Executing regression test suites
Troubleshooting DSIM environment issues
Understanding VS Code task integration

Primary Workflow (MANDATORY)

Use PowerShell scripts in scripts/

| Script | Purpose | |--------|---------| | run_test.ps1 | Single test execution | | run_regression.ps1 | Batch test execution |

Note: MCP-based execution has been deprecated. The deprecated_mcp_server/ directory is retained for reference only.

Standard UVM Test Sequence

1. Run Single Test

.\scripts\run_test.ps1 <test_name> [-Verbosity <level>] [-Waves] [-Seed <n>]

Examples:

# Basic test execution
.\scripts\run_test.ps1 vexriscv_regfile_test

# With waveform capture
.\scripts\run_test.ps1 vexriscv_alu_test -Waves

# With higher verbosity
.\scripts\run_test.ps1 vexriscv_pipeline_flow_test -Verbosity UVM_MEDIUM

2. Run Regression Suite

.\scripts\run_regression.ps1 [-Stage <n>] [-Tests <list>] [-Verbosity <level>] [-Waves] [-StopOnFail]

Examples:

# Run all Stage 1 tests
.\scripts\run_regression.ps1 -Stage 1

# Run specific tests
.\scripts\run_regression.ps1 -Tests vexriscv_regfile_test,vexriscv_alu_test

# Stop on first failure
.\scripts\run_regression.ps1 -Stage 1 -StopOnFail

Available Tests (Stage 1)

| Test Name | Purpose | |-----------|---------| | vexriscv_regfile_test | Register file read/write | | vexriscv_alu_test | ALU operations | | vexriscv_pipeline_flow_test | Pipeline instruction flow | | vexriscv_ibus_fetch_test | Instruction bus fetching | | vexriscv_memory_access_test | Load/Store operations | | vexriscv_ex_bypass_test | EX stage forwarding | | vexriscv_mem_bypass_test | MEM stage forwarding | | vexriscv_wb_bypass_test | WB stage forwarding | | vexriscv_load_use_stall_test | Load-use hazard stall | | vexriscv_dbus_access_test | Data bus access |

Script Parameters

run_test.ps1

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | -TestName | string | (required) | UVM test class name | | -Verbosity | enum | UVM_LOW | UVM_LOW, UVM_MEDIUM, UVM_HIGH, UVM_DEBUG | | -Waves | switch | false | Enable waveform capture (.mxd) | | -Seed | int | 1 | Random seed | | -CompileOnly | switch | false | Compile without running | | -RunOnly | switch | false | Run using existing compiled image |

run_regression.ps1

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | -Stage | int | 0 | Run tests for specific stage (1, 2, etc.) | | -Tests | string[] | @() | Comma-separated list of specific tests | | -Verbosity | enum | UVM_LOW | UVM verbosity level | | -Waves | switch | false | Enable waveform capture for all tests | | -StopOnFail | switch | false | Stop regression on first failure | | -ReportFile | string | auto | Custom report file path |

VS Code Task Integration

Use VS Code tasks from the Command Palette (Ctrl+Shift+P > "Tasks: Run Task"):

| Task | Description | |------|-------------| | DSIM: Run Single Test | Run selected test with chosen verbosity | | DSIM: Run Single Test with Waves | Run with waveform capture | | DSIM: Run Stage 1 Regression | Run all Stage 1 tests | | DSIM: Run Selected Tests | Run comma-separated test list | | DSIM: Run regfile_test | Quick access to regfile test | | DSIM: Run alu_test | Quick access to ALU test |

Output Locations

| Output Type | Location | |-------------|----------| | Test logs | sim/exec/logs/<test_name>_<timestamp>.log | | Result JSON | sim/exec/logs/<test_name>_<timestamp>_result.json | | Waveforms | sim/exec/wave/<test_name>_<timestamp>.mxd | | Regression report | sim/exec/logs/regression_<timestamp>.txt | | Regression JSON | sim/exec/logs/regression_<timestamp>.json |

Result JSON Format

Single Test Result

{
  "test_name": "vexriscv_regfile_test",
  "status": "success",
  "exit_code": 0,
  "log_file": "sim/exec/logs/vexriscv_regfile_test_20260131_111315.log",
  "wave_file": "",
  "timestamp": "20260131_111315"
}

Regression Result

{
  "timestamp": "20260131_111114",
  "total_tests": 3,
  "passed": 3,
  "failed": 0,
  "skipped": 0,
  "status": "PASS",
  "results": {
    "vexriscv_regfile_test": "PASS",
    "vexriscv_alu_test": "PASS",
    "vexriscv_pipeline_flow_test": "PASS"
  }
}

Common Workflows

Quick Compile-Run Cycle

# Compile only
.\scripts\run_test.ps1 my_test -CompileOnly

# Run using compiled image
.\scripts\run_test.ps1 my_test -RunOnly

Debug with Waveforms

.\scripts\run_test.ps1 vexriscv_memory_access_test -Waves -Verbosity UVM_DEBUG

Full Stage 1 Regression

.\scripts\run_regression.ps1 -Stage 1 -Verbosity UVM_LOW

DSIM Environment

Scripts automatically configure DSIM environment:

DSIM_HOME: C:\Program Files\Altair\DSim\2025.1
License auto-discovery from standard locations
PATH includes DSIM binaries and dependencies

Environment Variables (Auto-configured)

| Variable | Value | |----------|-------| | DSIM_HOME | Installation directory | | DSIM_ROOT | Same as DSIM_HOME | | DSIM_LIB_PATH | DSIM_HOME/lib | | DSIM_LICENSE | Auto-discovered license file |

Troubleshooting

DSIM Not Found

Verify DSIM installation:

Test-Path "C:\Program Files\Altair\DSim\2025.1\bin\dsim.exe"

License Issues

Check license file locations:

C:\Program Files\Altair\dsim-license.json
C:\Program Files\Altair\DSim\2025.1\dsim-license.json
$env:LOCALAPPDATA\metrics-ca\dsim-license.json

Test Not Found

Verify test exists in sim/tests/ and is listed in sim/uvm/tb/dsim_config.f.

Compilation Errors

See dsim-debugging skill for detailed troubleshooting.

Deprecated MCP Server

The MCP server has been deprecated. Files are retained in deprecated_mcp_server/ for reference only.

Do not use:

deprecated_mcp_server/mcp_client.py
deprecated_mcp_server/dsim_fastmcp_server.py
deprecated_mcp_server/run_regression.py

Adding a New Test

Use add_test.ps1 to scaffold a new test. The script handles all registration automatically.

Command

.\scripts\add_test.ps1 -TestName <name> [-Description <desc>] [-Category <cat>] [-Stage <n>]

Parameters

| Parameter | Values | Description | |-----------|--------|-------------| | -TestName | *_test | Test class name (must end with _test) | | -Description | string | Purpose of the test | | -Category | smoke, hazard, bus, memory, custom | Test classification | | -Stage | 0, 1 | 0 = no stage, 1 = add to Stage 1 list | | -TimeoutCycles | int | Cycle-based timeout (default: 200) | | -ExpectedDurationSec | int | Expected run time in seconds |

Examples

# New hazard test, added to Stage 1
.\scripts\add_test.ps1 -TestName vexriscv_branch_test `
    -Description "Branch instruction verification" `
    -Category hazard -Stage 1

# New custom test, not added to any stage
.\scripts\add_test.ps1 -TestName vexriscv_csr_test `
    -Description "CSR read/write operations" `
    -Category custom

What the Script Does

The script modifies 4 files automatically:

| File | Action | |------|--------| | sim/tests/<name>.sv | Creates test from template | | sim/uvm/tb/dsim_config.f | Adds compilation entry | | sim/regression_tests.json | Adds to regression suite | | scripts/run_regression.ps1 | Adds to stage list (if -Stage 1) |

After Scaffolding

The generated test file (sim/tests/<name>.sv) has two TODO sections to complete:

1. load_test_program() - Define the instruction sequence:

// Base address: 0x80000000 (program start)
// Data region:  0x80001000 (store/load target, within 8KB BlockRAM)
write_memory_backdoor(32'h80000000, 32'h<encoding>);  // instruction
write_memory_backdoor(32'h80000004, 32'h00100073);    // EBREAK (halt)

2. verify_results() - Check register values:

read_cpu_reg(<reg_num>, reg_val);
if (reg_val != 32'h<expected>) begin
    `uvm_error(get_type_name(),
        $sformatf("FAIL: x%0d = 0x%08X (expected 0x%08X)", <n>, reg_val, <expected>))
    all_pass = 0;
end

Memory Map Reference

BlockRAM: 0x80000000 - 0x80001FFF (8KB total)
  Program: 0x80000000 - 0x800001FF (128 instructions max)
  Data:    0x80001000 - 0x80001FFF (store/load target)

RV32I Encoding Quick Reference

| Instruction | Format | Encoding | |-------------|--------|----------| | ADDI rd, rs1, imm | I-type | imm[11:0]\|rs1[4:0]\|000\|rd[4:0]\|0010011 | | LUI rd, imm | U-type | imm[31:12]\|rd[4:0]\|0110111 | | SW rs2, off(rs1) | S-type | imm[11:5]\|rs2[4:0]\|rs1[4:0]\|010\|imm[4:0]\|0100011 | | LW rd, off(rs1) | I-type | imm[11:0]\|rs1[4:0]\|010\|rd[4:0]\|0000011 | | EBREAK | - | 0x00100073 | | NOP | - | 0x00000013 |

Full Workflow

1. Scaffold     .\scripts\add_test.ps1 -TestName my_test -Category smoke -Stage 1
2. Edit         sim/tests/my_test.sv  (define sequence + checks)
3. Test         .\scripts\run_test.ps1 my_test -Waves -Verbosity UVM_MEDIUM
4. Debug        Open sim/exec/wave/my_test_*.mxd (if failures)
5. Regression   .\scripts\run_regression.ps1 -Stage 1

Summary

Workflow principles:

Use PowerShell scripts in scripts/ (mandatory)
Standard sequence: run_test.ps1 for single tests, run_regression.ps1 for batch
New tests: add_test.ps1 scaffolds and registers automatically
Use VS Code tasks for common operations
Consume JSON outputs from sim/exec/logs/
Check waveforms in sim/exec/wave/ when debugging
See dsim-debugging skill for troubleshooting