MCP Workflow for DSIM UVM Testing

FastMCP + VS Code MCP integration workflow for the AXIUART_RV32I verification environment.

When to Use This Skill

• Compiling or running UVM tests
• Executing regression test suites
• Troubleshooting MCP server connectivity
• Understanding VS Code task integration
• Configuring test timeout policies

Primary Workflow (MANDATORY)

Use FastMCP + VS Code MCP integration - configured in .vscode/mcp.json

Do not violate this rule. MCP server provides structured JSON outputs, automatic timeout management, and integrated telemetry.

Standard UVM Test Sequence

1. Check DSIM Environment

python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool check_dsim_environment

Verifies:

• DSIM_HOME, DSIM_ROOT, DSIM_LIB_PATH, DSIM_LICENSE environment variables
• DSIM executable accessibility
• License validity

2. List Available Tests

python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool list_available_tests

Returns: JSON list of all UVM tests in sim/tests/

3. Compile Test

python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_uvm_simulation \
    --test-name <test> \
    --mode compile \
    --verbosity UVM_LOW

Example:

python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_uvm_simulation \
    --test-name axiuart_basic_test \
    --mode compile \
    --verbosity UVM_LOW

4. Run Simulation

python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_uvm_simulation \
    --test-name <test> \
    --mode run \
    --verbosity UVM_MEDIUM \
    --waves

Example:

python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_uvm_simulation \
    --test-name axiuart_basic_test \
    --mode run \
    --verbosity UVM_MEDIUM \
    --waves

Timeout Policy (CRITICAL)

NEVER specify --timeout parameter

MCP server auto-selects timeout from test_timing_config.json or uses null (no timeout) by default.

Timeout Configuration

{
  "default_timeout": 300,
  "test_timeouts": {
    "axiuart_basic_test": 120,
    "axiuart_stress_test": 600,
    "axiuart_long_run_test": null
  }
}

Rules:

• null timeout = no timeout (runs until completion)
• Specific test timeout overrides default
• Do not hardcode timeouts in command line

Regression Testing

Smoke Suite (Quick Validation)

python mcp_server/run_regression.py --suite smoke

Characteristics:

• 2 tests: axiuart_basic_test, uart_loopback_test
• Runtime: ~40 seconds
• Use for: Quick sanity checks, pre-commit validation

Full Suite (Complete Regression)

python mcp_server/run_regression.py --suite full --format html

Characteristics:

• All tests in regression_tests.json
• HTML report generated in sim/reports/
• Use for: Nightly builds, release validation

Via MCP Tool

python mcp_server/mcp_client.py \
    --workspace e:\Nautilus\workspace\fpgawork\AXIUART_RV32I \
    --tool run_regression_suite \
    --suite smoke

VS Code Task Integration

Compile-Only Task

Task: DSIM: Run Basic Test (Compile Only - MCP)

Wraps:

python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name axiuart_basic_test --mode compile --verbosity UVM_LOW

Full Simulation Task

Task: DSIM: Run Basic Test (Full Simulation - MCP)

Wraps:

python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name axiuart_basic_test --mode run --verbosity UVM_MEDIUM --waves

MCP Server Startup

Task: 🚀 Start Enhanced MCP Server (FastMCP Edition)

Starts background MCP server when required.

JSON Output Consumption

MCP server produces structured JSON outputs:

Test Results

Location: sim/logs/<test_name>_result.json

{
  "test_name": "axiuart_basic_test",
  "status": "PASSED",
  "duration_seconds": 45.3,
  "errors": 0,
  "warnings": 2,
  "coverage": {
    "line": 87.5,
    "toggle": 92.1
  }
}

Telemetry

Location: sim/logs/<test_name>_telemetry.json

Contains DSIM performance metrics, memory usage, compilation time.

Coverage Data

Location: sim/reports/coverage/

Parse coverage database for detailed metrics.

MCP Client API Usage

Python Integration

from mcp_server.client_api import DSIMClient

client = DSIMClient(workspace="e:\\Nautilus\\workspace\\fpgawork\\AXIUART_RV32I")

# Check environment
env_status = client.check_dsim_environment()
print(f"DSIM ready: {env_status['valid']}")

# List tests
tests = client.list_available_tests()
print(f"Available tests: {tests}")

# Run test
result = client.run_uvm_simulation(
    test_name="axiuart_basic_test",
    mode="run",
    verbosity="UVM_MEDIUM",
    waves=True
)
print(f"Test result: {result['status']}")

Fallback Path (Only if MCP Unavailable)

When to Use Fallback

• MCP server unreachable
• Python environment issues
• Debugging MCP infrastructure problems

Document the reason for fallback in development diary.

Initialization

cd e:\Nautilus\workspace\fpgawork\AXIUART_RV32I
.\workspace_init.ps1
Test-WorkspaceMCPUVM

Execution

.\sim\exec\run_uvm.ps1 `
    -TestName axiuart_basic_test `
    -Waves `
    -Coverage

Prohibited

Never call archived scripts or archive/legacy_mcp_files/ assets.

MCP Server Configuration

Server Location

mcp_server/dsim_fastmcp_server.py

Configuration File

.vscode/mcp.json

{
  "mcpServers": {
    "dsim-uvm": {
      "command": "python",
      "args": ["mcp_server/dsim_fastmcp_server.py"],
      "env": {
        "WORKSPACE_ROOT": "e:\\Nautilus\\workspace\\fpgawork\\AXIUART_RV32I"
      }
    }
  }
}

Common Workflows

Quick Compile-Run Cycle

# Compile
python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name my_test --mode compile --verbosity UVM_LOW

# If successful, run
python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name my_test --mode run --verbosity UVM_MEDIUM --waves

Debug with Assertions Enabled

python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name my_test --mode run --waves \
    --compile-args "+define+ENABLE_ASSERTIONS"

Coverage-Enabled Run

python mcp_server/mcp_client.py --workspace . --tool run_uvm_simulation \
    --test-name my_test --mode run --coverage --waves

Output Locations

Troubleshooting

MCP Server Not Responding

1. Check background task: 🚀 Start Enhanced MCP Server (FastMCP Edition)
2. Verify Python environment: python --version (requires 3.8+)
3. Test direct invocation: python mcp_server/dsim_fastmcp_server.py --help

DSIM Environment Errors

python mcp_server/mcp_client.py --workspace . --tool check_dsim_environment

Review output for missing environment variables. See dsim-debugging skill for detailed troubleshooting.

Test Not Found

python mcp_server/mcp_client.py --workspace . --tool list_available_tests

Verify test exists in sim/tests/ and is registered in regression_tests.json.

Additional Resources

• MCP server implementation: mcp_server/README.md
• Regression configuration: mcp_server/REGRESSION.md
• DSIM debugging: Reference dsim-debugging skill
• Test execution: docs/vexriscv_test_quickstart.md

Summary

MCP workflow principles:

1. Always use FastMCP + VS Code MCP integration (mandatory)
2. Never specify --timeout parameter (auto-selected from test_timing_config.json)
3. Standard sequence: check_dsim_environment → list_available_tests → compile → run
4. Prefer VS Code tasks for common operations
5. Consume JSON outputs from sim/logs/ and sim/reports/
6. Use fallback PowerShell path only when MCP unavailable (document reason)
7. Smoke suite (~40s) for quick validation, full suite for complete regression