chipflow.sim

CXXRTL-based simulation infrastructure for ChipFlow.

This module provides Python bindings for CXXRTL simulation, enabling fast compiled simulation of mixed Amaranth/Verilog/SystemVerilog designs.

Example usage:

from chipflow.sim import CxxrtlSimulator, build_cxxrtl

# Build CXXRTL shared library from sources
lib_path = build_cxxrtl(
    sources=["design.v", "ip.sv"],
    top_module="design",
    output_dir=Path("build/sim")
)

# Create simulator and run testbench
sim = CxxrtlSimulator(lib_path, top_module="design")
sim.reset()

# Access signals
sim.set("clk", 1)
sim.step()
value = sim.get("data_out")

Submodules

Classes

CxxrtlSimulator

Python wrapper for CXXRTL simulation.

Functions

build_cxxrtl(sources, top_module, output_dir[, ...])

Build a CXXRTL shared library from HDL sources.

Package Contents

class chipflow.sim.CxxrtlSimulator(library_path, top_module)

Python wrapper for CXXRTL simulation.

This class provides a Pythonic interface to CXXRTL compiled simulations, supporting signal access, stepping, and VCD tracing.

Example:

sim = CxxrtlSimulator("build/design.so", "design")
sim.reset()

# Clock cycle
sim.set("clk", 0)
sim.step()
sim.set("clk", 1)
sim.step()

# Read output
value = sim.get("data_out")
Parameters:
reset()

Reset the simulation to initial state.

Return type:

None

eval()

Evaluate combinatorial logic.

Returns:

True if the design converged immediately

Return type:

bool

commit()

Commit sequential state.

Returns:

True if any state changed

Return type:

bool

step()

Simulate to a fixed point (eval + commit until stable).

Returns:

Number of delta cycles

Return type:

int

get(name)

Get the current value of a signal.

Parameters:

name (str) – Signal name (e.g., “i_clk” or “o_data”)

Returns:

Current value as an integer

Return type:

int

set(name, value)

Set the next value of a signal.

Parameters:

  • name (str) – Hierarchical signal name

  • value (int) – Value to set

Return type:

None

signals()

Iterate over all signals in the design.

Yields:

Tuples of (name, object) for each signal

Return type:

Iterator[Tuple[str, CxxrtlObject]]

inputs()

Iterate over input signals.

Return type:

Iterator[Tuple[str, CxxrtlObject]]

outputs()

Iterate over output signals.

Return type:

Iterator[Tuple[str, CxxrtlObject]]

close()

Release simulation resources.

Return type:

None

chipflow.sim.build_cxxrtl(sources, top_module, output_dir, output_name=None, include_dirs=None, defines=None, optimization='-O2', debug_info=True)

Build a CXXRTL shared library from HDL sources.

Parameters:

  • sources (Sequence[Union[str, pathlib.Path]]) – List of Verilog/SystemVerilog source files

  • top_module (str) – Name of the top-level module

  • output_dir (Union[str, pathlib.Path]) – Directory for build artifacts

  • output_name (Optional[str]) – Name for output library (default: top_module)

  • include_dirs (Optional[Sequence[Union[str, pathlib.Path]]]) – Additional include directories for Verilog

  • defines (Optional[dict[str, str]]) – Verilog preprocessor defines

  • optimization (str) – C++ optimization level (default: -O2)

  • debug_info (bool) – Include CXXRTL debug info (default: True)

Returns:

Path to the compiled shared library

Return type:

pathlib.Path