chipflow.sim
============

.. py:module:: chipflow.sim

.. autoapi-nested-parse::

   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
----------

.. toctree::
   :maxdepth: 1

   /chipflow-lib/autoapi/chipflow/sim/build/index
   /chipflow-lib/autoapi/chipflow/sim/cxxrtl/index


Classes
-------

.. autoapisummary::

   chipflow.sim.CxxrtlSimulator


Functions
---------

.. autoapisummary::

   chipflow.sim.build_cxxrtl


Package Contents
----------------

.. py:class:: 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")


   .. py:method:: reset()

      Reset the simulation to initial state.



   .. py:method:: eval()

      Evaluate combinatorial logic.

      :returns: True if the design converged immediately



   .. py:method:: commit()

      Commit sequential state.

      :returns: True if any state changed



   .. py:method:: step()

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

      :returns: Number of delta cycles



   .. py:method:: get(name)

      Get the current value of a signal.

      :param name: Signal name (e.g., "i_clk" or "o_data")

      :returns: Current value as an integer



   .. py:method:: set(name, value)

      Set the next value of a signal.

      :param name: Hierarchical signal name
      :param value: Value to set



   .. py:method:: signals()

      Iterate over all signals in the design.

      :Yields: Tuples of (name, object) for each signal



   .. py:method:: inputs()

      Iterate over input signals.



   .. py:method:: outputs()

      Iterate over output signals.



   .. py:method:: close()

      Release simulation resources.



.. py:function:: 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.

   :param sources: List of Verilog/SystemVerilog source files
   :param top_module: Name of the top-level module
   :param output_dir: Directory for build artifacts
   :param output_name: Name for output library (default: top_module)
   :param include_dirs: Additional include directories for Verilog
   :param defines: Verilog preprocessor defines
   :param optimization: C++ optimization level (default: -O2)
   :param debug_info: Include CXXRTL debug info (default: True)

   :returns: Path to the compiled shared library