name: dsim-debugging description: DSIM simulator debugging and troubleshooting. Use when investigating compilation errors, runtime failures, waveform analysis, or DSIM environment issues.

DSIM Debugging and Troubleshooting

Debugging methodology for Metrics DSIM simulator in the AXIUART_RV32I verification environment.

When to Use This Skill

• Investigating compilation or simulation failures
• Analyzing waveform data
• Troubleshooting DSIM environment configuration
• Resolving timescale mismatches or structural errors
• Optimizing simulation performance

DSIM Environment Variables

Required Variables (MANDATORY)

# Check current environment
$env:DSIM_HOME
$env:DSIM_ROOT
$env:DSIM_LIB_PATH
$env:DSIM_LICENSE

Verification

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

Expected output:

{
  "valid": true,
  "DSIM_HOME": "C:\\Metrics\\dsim-20231215",
  "DSIM_ROOT": "C:\\Metrics\\dsim-20231215",
  "DSIM_LIB_PATH": "C:\\Metrics\\dsim-20231215\\lib",
  "DSIM_LICENSE": "27020@license-server.local",
  "executable": "C:\\Metrics\\dsim-20231215\\bin\\dsim.exe"
}

Common Issues

Missing DSIM_HOME:

$env:DSIM_HOME = "C:\Metrics\dsim-20231215"
$env:DSIM_ROOT = $env:DSIM_HOME
$env:DSIM_LIB_PATH = "$env:DSIM_HOME\lib"

License errors:

$env:DSIM_LICENSE = "27020@license-server.local"
dsim -version  # Test license connectivity

Waveform Strategy

MXD vs VCD

Default: MXD waveform format (Metrics proprietary)

MXD advantages:

• Faster dump performance
• Smaller file size
• Better compression
• Native DSIM format

Enable MXD in simulation:

initial begin
    $dumpfile("sim/logs/axiuart_basic_test.mxd");
    $dumpvars(0, tb_axiuart_top);
end

VCD (compatibility mode):

initial begin
    $dumpfile("sim/logs/axiuart_basic_test.vcd");
    $dumpvars(0, tb_axiuart_top);
end

Avoid VCD unless:

• Sharing waveforms with non-DSIM tools
• Post-processing with standard VCD parsers

Assertion-Driven Debugging

Priority Workflow

1. Assertions FIRST → 2. Waveforms SECOND

Investigate assertion failures before opening waveform viewer:

# Check assertion summary in log
grep "Assertion" sim/logs/axiuart_basic_test.log

# Filter for failures
grep "Assertion.*failed" sim/logs/axiuart_basic_test.log

Assertion Error Analysis

Example failure:

** Error: [1250 ns] Assertion a_frame_minimum_length failed
   Frame length violation: byte_count=2
   File: sim/assertions/functional/Frame_Parser_Assertions.sv:15

Investigation steps:

1. Read assertion property definition (line 15)
2. Understand violated specification requirement
3. Determine if DUT bug or assertion bug
4. Use timestamp (1250 ns) to locate failure in waveform

Enabling Assertions

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

Assertions located in:

• sim/assertions/spec/ - Timing specifications
• sim/assertions/functional/ - Functional properties
• sim/assertions/bind/ - Bind statements

Troubleshooting Checklist

1. Confirm DSIM Environment Variables

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

Verify all 4 required variables set correctly.

2. Inspect dsim_config.f Path List

Location: sim/exec/dsim_config.f or similar

# View compilation file list
Get-Content sim/exec/dsim_config.f

Check for:

• Correct file paths (no typos)
• Proper ordering (packages before modules)
• No missing files
• Correct include directories (+incdir+)

3. Ensure Timescale Match

Every file MUST have:

`timescale 1ns / 1ps

Detect mismatches:

# Find files without timescale
Select-String -Path rtl\*.sv, sim\*.sv -Pattern '^`timescale' -NotMatch

Common error:

Error: Timescale mismatch: module 'Frame_Parser' (1ns/1ps) vs 'Uart_Tx' (1ps/1fs)

4. Verify Interface/RTL Structural Alignment

Check bit widths:

// Interface definition
interface uart_if;
    logic [7:0] data;  // 8 bits
endinterface

// Module must match
module Uart_Tx (
    uart_if.master uart  // Uses 8-bit data
);

Check signal directions:

// Interface modport
modport master (
    output tx_data,
    input  rx_data
);

// Module usage must match directions
module Uart_Controller (
    uart_if.master uart
);
    assign uart.tx_data = internal_tx;  // ✅ Output
    // assign uart.rx_data = ...  ❌ Can't drive input

5. Analyze DSIM Log Output

Parse compilation errors:

# Compilation phase errors
grep "Error" sim/logs/axiuart_basic_test.log | Select-Object -First 10

Parse simulation errors:

# Runtime errors
grep "Error\|Fatal" sim/logs/axiuart_basic_test.log

UVM messages:

# UVM_ERROR and UVM_FATAL
grep "UVM_ERROR\|UVM_FATAL" sim/logs/axiuart_basic_test.log

DSIM Telemetry Analysis

Telemetry JSON

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

{
  "compilation_time_seconds": 12.3,
  "simulation_time_seconds": 45.7,
  "memory_usage_mb": 512,
  "peak_memory_mb": 768,
  "events_processed": 1250000
}

Performance Metrics

Slow compilation:

• Check for redundant package imports
• Verify file list ordering (packages first)
• Consider incremental compilation (-genimage)

High memory usage:

• Reduce waveform dump scope
• Limit UVM verbosity to UVM_MEDIUM
• Check for memory leaks in testbench

Waveform Analysis

Opening MXD Files

# DSIM waveform viewer
dsim -waves sim/logs/axiuart_basic_test.mxd

Debugging Strategies

1. Find assertion failure timestamp

grep "Assertion.*failed" sim/logs/axiuart_basic_test.log
# Example: [1250 ns] Assertion a_handshake failed

2. Navigate to timestamp in waveform

• Jump to 1250 ns
• Add relevant signals to waveform view
• Trace signal history 10-20 cycles before failure

3. Verify signal values

• Check handshake signals (valid, ready)
• Verify state machine states
• Inspect data payloads

Common Error Patterns

Compilation Errors

Undeclared identifier:

Error: Undeclared identifier 'uart_if' at Frame_Parser.sv:10

Solution: Add interface to compile list or import package.

Parameter override mismatch:

Error: Parameter 'WIDTH' expects integer, got logic

Solution: Use correct parameter type in instantiation.

Simulation Errors

X-propagation:

Warning: Signal 'data_out' driven with X value at 1250 ns

Solution: Check reset sequencing and initialization.

Assertion failure:

Error: Assertion a_protocol_timing failed at 3450 ns

Solution: Review protocol specification and DUT timing.

Coverage Analysis

Generate Coverage

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

Review Coverage Report

Location: sim/reports/coverage/

# Open HTML report
Start-Process sim/reports/coverage/index.html

Key metrics:

• Line coverage: % of RTL lines executed
• Toggle coverage: % of signals toggled
• Branch coverage: % of branches taken
• FSM coverage: % of state transitions

Log File Organization

Standard Locations

Log Analysis Tools

# Count errors
(Select-String -Path sim/logs/axiuart_basic_test.log -Pattern "Error").Count

# Extract UVM summary
Select-String -Path sim/logs/axiuart_basic_test.log -Pattern "UVM_INFO.*Test.*completed"

# Find assertion failures
Select-String -Path sim/logs/axiuart_basic_test.log -Pattern "Assertion.*failed"

Escalation Criteria

When to Escalate

• DSIM crashes or hangs
• License server connectivity issues
• Persistent X-propagation despite reset
• Coverage data corruption
• Waveform dump failures

Escalation Data

Collect before escalating:

1. Full compilation log
2. Simulation log with +verbose flag
3. Telemetry JSON
4. DSIM version: dsim -version
5. Environment variables snapshot
6. Minimal reproducible test case

Additional Resources

• MCP workflow: Reference mcp-workflow skill for command sequences
• Assertion design: Reference assertion-design skill for property debugging
• Project logs: sim/logs/README.md (if exists)
• DSIM documentation: Check DSIM_HOME/docs/

Summary

DSIM debugging principles:

1. Verify environment variables FIRST (check_dsim_environment)
2. Investigate assertions BEFORE waveforms
3. Enable MXD waveforms (default) over VCD
4. Check timescale consistency across all files
5. Inspect dsim_config.f for path ordering
6. Analyze telemetry JSON for performance insights
7. Parse logs systematically: errors → warnings → UVM messages
8. Use sim/logs/ as single source of truth for debugging data