hdl-simulation

name	hdl-simulation
description	Configure and run HDL simulations with various simulators using the hdlsim DFM package. Use when working with SimImage, SimRun, SimLib, or simulator-specific tasks.

HDL Simulation Package (hdlsim)

The hdlsim package provides tasks for compiling and running HDL simulations with various commercial and open-source simulators. It defines abstract tasks (SimImage, SimRun, SimLib, etc.) that each simulator package implements.

Supported Simulators

Package	Simulator	License
hdlsim.vlt	Verilator	Open Source
hdlsim.vcs	Synopsys VCS	Commercial
hdlsim.xsm	Cadence Xcelium	Commercial
hdlsim.mti	Siemens Questa	Commercial
hdlsim.ivl	Icarus Verilog	Open Source
hdlsim.xcm	AMD Xilinx XSim	Commercial

Quick Start

package:
  name: my_sim

  imports:
    - name: hdlsim.vlt   # Or hdlsim.vcs, hdlsim.xsm, hdlsim.mti
      as: sim

  tasks:
    - name: rtl
      uses: std.FileSet
      with:
        type: systemVerilogSource
        include: "src/**/*.sv"

    - root: build
      uses: sim.SimImage
      needs: [rtl]
      with:
        top: [my_top]

    - root: run
      uses: sim.SimRun
      needs: [build]

Run:

dfm run build          # Compile
dfm run run            # Compile + simulate
dfm run run -c vcs     # Use VCS config (see multi-simulator below)

Core Tasks

SimImage

Compiles HDL sources into a simulation executable.

Parameter	Type	Description
top	list	Top-level module name(s)
args	list	Additional compiler/elaborator arguments
compargs	list	Compilation-specific arguments
elabargs	list	Elaboration-specific arguments
trace	bool	Enable waveform tracing
timing	bool	Enable timing simulation (default: true)
dpilibs	list	DPI libraries to link
vpilibs	list	VPI libraries to link
incdirs	list	Include directories
defines	list	Preprocessor defines
suppress_warnings	list	Warning codes to suppress from markers

Consumes: systemVerilogSource, verilogSource, verilogIncDir, systemVerilogInclude, simLib, cSource, cppSource, systemVerilogDPI, verilogVPI, SimCompileArgs, SimElabArgs, SuppressWarnings

SimRun

Executes a compiled simulation.

Parameter	Type	Description
args	list	Runtime arguments
plusargs	list	Simulation plusargs (e.g., UVM_TESTNAME=test)
dpilibs	list	DPI libraries to load at runtime
vpilibs	list	VPI libraries to load at runtime
trace	bool	Enable runtime tracing
valgrind	bool	Run under valgrind

Consumes: simDir, systemVerilogDPI, verilogVPI, simRunData, SimRunArgs

SimRun has uptodate: false -- it always re-executes.

SimLib

Creates a pre-compiled simulation library. Useful for large designs with shared libraries to improve compilation time.

Parameter	Type	Description
libname	str	Name of the library
args	list	Additional compiler arguments
incdirs	list	Include directories
defines	list	Preprocessor defines
propagate_incdirs	bool	Propagate include dirs to consumers (default: true)
suppress_warnings	list	Warning codes to suppress from markers

SimLibUVM

Provides UVM library support for the target simulator. Each simulator package implements this with the appropriate UVM paths and settings.

tasks:
  - name: uvm
    uses: sim.SimLibUVM

  - name: build
    uses: sim.SimImage
    needs: [rtl, uvm, tb]
    with:
      top: [tb_top]

SimLibDPI

Compiles C/C++ sources into a DPI library.

SimLibVPI

Compiles C/C++ sources into a VPI library.

Data Types

SimCompileArgs

Additional compilation arguments injected via dataflow. Use when adding compile flags from configs or separate tasks.

Parameter	Type	Description
args	list	Compiler arguments
incdirs	list	Include directories
defines	list	Preprocessor defines

SimElabArgs

Additional elaboration arguments. Separates elaboration-phase flags from compilation-phase flags.

Parameter	Type	Description
args	list	Elaboration arguments
dpilibs	list	DPI libraries to link
vpilibs	list	VPI libraries to link

SimRunArgs

Additional runtime arguments for SimRun.

Parameter	Type	Description
args	list	Runtime arguments
plusargs	list	Simulation plusargs
dpilibs	list	DPI libraries to load
vpilibs	list	VPI libraries to load

SuppressWarnings

Carries a list of warning codes to suppress as markers. Connect to SimImage or SimLib via needs or feeds.

Parameter	Type	Description
codes	list	Warning codes to suppress (e.g., TFIPC, vlog-2623)

Direct usage

- name: build
  uses: sim.SimImage
  needs: [rtl, tb]
  with:
    top: [tb_top]
    suppress_warnings: [TFIPC, MAXX]

Shared dataset

- name: suppress
  uses: hdlsim.SuppressWarnings
  with:
    codes: [TFIPC, MAXX]

- name: build
  uses: sim.SimImage
  needs: [rtl, tb, suppress]
  with:
    top: [tb_top]

Via feeds in a config

configs:
  - name: suppress_noisy
    tasks:
      - name: suppress
        uses: hdlsim.SuppressWarnings
        with:
          codes: [TFIPC, MAXX]
        feeds: [my_project.build]

Using feeds in Configs

The feeds field injects data into a task without modifying its definition. This is the recommended way to add simulator arguments from configs.

package:
  name: my_project

  tasks:
    - root: build
      uses: sim.SimImage
      needs: [rtl, tb]
      with:
        top: [tb_top]

    - root: run
      uses: sim.SimRun
      needs: [build]

  configs:
    - name: debug
      tasks:
        # Compilation-phase flags
        - name: debug_compile_args
          uses: hdlsim.SimCompileArgs
          with:
            args: ["-debug_access+all"]
          feeds: [my_project.build]

        # Elaboration-phase flags
        - name: debug_elab_args
          uses: hdlsim.SimElabArgs
          with:
            args: ["-debug_access+all"]
          feeds: [my_project.build]

        # Runtime flags
        - name: debug_run_args
          uses: hdlsim.SimRunArgs
          with:
            args: ["-gui"]
          feeds: [my_project.run]

        # Copy data files to the test rundir at runtime
        - name: debug_scripts
          uses: std.FileSet
          with:
            type: simRunData
            include: "dump.tcl"
          feeds: [my_project.run]

Usage: dfm run run -c debug

Key points:

• SimCompileArgs for compilation-phase flags
• SimElabArgs for elaboration-phase flags
• SimRunArgs for runtime flags
• std.FileSet with type: simRunData to copy files into the test rundir
• Feed targets use fully-qualified names (package.task)

Multi-Simulator Support

Use package parameters and alias imports to select the simulator at build time:

package:
  name: my_project

  with:
    simulator:
      type: str
      value: vlt

  imports:
    - name: hdlsim.${{ simulator }}
      as: sim

  configs:
    - name: verilator
      with:
        simulator:
          value: vlt
    - name: vcs
      with:
        simulator:
          value: vcs
    - name: questa
      with:
        simulator:
          value: mti

Usage:

dfm run build -c vcs
dfm run build -c questa

Build Reuse with --base-rundir

For regression workflows, build once and reuse compiled artifacts:

# Build phase
dfm run build

# Test phase (no recompilation)
dfm run test_smoke --base-rundir /path/to/build/rundir
dfm run test_full  --base-rundir /path/to/build/rundir

Real-World UVM Example

A multi-fragment UVM testbench structure showing proper dependency chains.

Directory Structure

project/
  flow.dv                    # Root package
  src/rtl/
    flow.dv                  # RTL fragment
    *.sv
  verification_ip/
    pkg_a/
      flow.dv                # VIP package A fragment
      hdl/*.sv
      hvl/*.sv
    pkg_b/
      flow.dv                # VIP package B fragment
      hdl/*.sv
      hvl/*.sv
  tb/
    flow.dv                  # TB fragment
    env/flow.dv              # Environment fragment
    sequences/flow.dv        # Sequences fragment
    tests/flow.dv            # Tests fragment
    hdl_top.sv
    hvl_top.sv

Root Package (flow.dv)

package:
  name: my_project

  imports:
    - name: hdlsim.vlt
      as: sim

  fragments:
    - src/rtl/flow.dv
    - verification_ip/pkg_a/flow.dv
    - verification_ip/pkg_b/flow.dv
    - tb/flow.dv

  configs:
    - name: vcs
      imports:
        - name: hdlsim.vcs
          as: sim
    - name: debug
      tasks:
        - name: debug_compile
          uses: hdlsim.SimCompileArgs
          with:
            args: ["-debug_access+all"]
          feeds: [my_project.build]

RTL Fragment (src/rtl/flow.dv)

fragment:
  tasks:
    - name: rtl
      uses: std.FileSet
      with:
        type: systemVerilogSource
        include: "*.sv"

VIP Fragment (verification_ip/pkg_a/flow.dv)

fragment:
  tasks:
    - name: pkg_a_hdl
      uses: std.FileSet
      with:
        type: systemVerilogSource
        base: hdl
        include: "*.sv"

    - name: pkg_a_hvl
      uses: std.FileSet
      needs: [pkg_a_hdl]
      with:
        type: systemVerilogSource
        base: hvl
        include: "*.sv"

Testbench Fragment (tb/flow.dv)

fragment:
  fragments:
    - env/flow.dv
    - sequences/flow.dv
    - tests/flow.dv

  tasks:
    - name: uvm
      uses: sim.SimLibUVM

    - name: hdl_top
      uses: std.FileSet
      needs: [pkg_a_hdl, pkg_b_hdl]
      with:
        type: systemVerilogSource
        include: "hdl_top.sv"

    - name: hvl_top
      uses: std.FileSet
      needs: [env, sequences]
      with:
        type: systemVerilogSource
        include: "hvl_top.sv"

    - root: build
      uses: sim.SimImage
      needs: [hdl_top, hvl_top, rtl, uvm]
      with:
        top: [hdl_top, hvl_top]

    - root: run
      uses: sim.SimRun
      needs: [build]
      with:
        plusargs: [UVM_TESTNAME=base_test]

Test Fragment (tb/tests/flow.dv)

fragment:
  tasks:
    - name: tests
      uses: std.FileSet
      needs: [env, sequences]
      with:
        type: systemVerilogSource
        include: "*.sv"

    - root: test_smoke
      uses: sim.SimRun
      needs: [build]
      with:
        plusargs: [UVM_TESTNAME=smoke_test]

    - root: test_full
      uses: sim.SimRun
      needs: [build]
      with:
        plusargs: [UVM_TESTNAME=full_test]

Running

dfm run build                   # Compile
dfm run run                     # Run base test
dfm run test_smoke              # Run smoke test
dfm run test_full -c debug      # Run full test with debug
dfm run build -c vcs            # Compile with VCS
dfm graph build -o flow.dot     # Visualize dependency graph