chipflow.rtl.wrapper
====================

.. py:module:: chipflow.rtl.wrapper

.. autoapi-nested-parse::

   RTL wrapper for external Verilog/SystemVerilog/SpinalHDL modules.

   This module provides a TOML-based configuration system for wrapping external RTL
   modules as Amaranth wiring.Component classes. It supports:

   - Automatic Signature generation from TOML port definitions
   - SpinalHDL code generation
   - SystemVerilog to Verilog conversion via sv2v or yosys-slang
   - Clock and reset signal mapping
   - Port and pin interface mapping to RTL signals
   - CXXRTL simulation via chipflow.sim integration



Classes
-------

.. autoapisummary::

   chipflow.rtl.wrapper.RTLWrapper


Functions
---------

.. autoapisummary::

   chipflow.rtl.wrapper.load_wrapper_from_toml


Module Contents
---------------

.. py:class:: RTLWrapper(config, verilog_files = None)

   Bases: :py:obj:`amaranth.lib.wiring.Component`


   Dynamic Amaranth Component that wraps an external RTL module.

   This component is generated from TOML configuration and creates the appropriate
   Signature and elaborate() implementation to instantiate the RTL module.

   When a driver configuration is provided, the component uses SoftwareDriverSignature
   to enable automatic driver generation and register struct creation.

   Auto-mapping works by parsing the Verilog files to find actual port names,
   then matching patterns to identify which signals correspond to interface members.


   .. py:method:: elaborate(platform)

      Generate the Amaranth module with Verilog instance.

      Creates an Instance() of the wrapped Verilog module with all
      port mappings configured from the TOML specification.



   .. py:method:: get_source_files()

      Get the list of Verilog/SystemVerilog source files.

      :returns: List of paths to source files for this wrapper.



   .. py:method:: get_top_module()

      Get the top module name.

      :returns: Name of the top-level Verilog module.



   .. py:method:: get_signal_map()

      Get the mapping from Amaranth port paths to Verilog signal names.

      :returns: Dictionary mapping port names to signal path → Verilog name mappings.
                Example: {'bus': {'cyc': 'i_wb_cyc', 'stb': 'i_wb_stb', ...}}



   .. py:method:: build_simulator(output_dir, *, optimization = '-O2', debug_info = True)

      Build a CXXRTL simulator for this wrapper.

      This compiles the Verilog/SystemVerilog sources into a CXXRTL shared
      library and returns a simulator instance ready for use.

      :param output_dir: Directory for build artifacts (library, object files, etc.)
      :param optimization: C++ optimization level (default: -O2)
      :param debug_info: Include CXXRTL debug info for signal access (default: True)

      :returns: CxxrtlSimulator instance configured for this wrapper.

      :raises ImportError: If chipflow.sim is not installed
      :raises RuntimeError: If compilation fails

      Example::

          wrapper = load_wrapper_from_toml("wb_timer.toml")
          sim = wrapper.build_simulator("build/sim")

          # Reset
          sim.set("i_rst_n", 0)
          sim.set("i_clk", 0)
          sim.step()
          sim.set("i_clk", 1)
          sim.step()
          sim.set("i_rst_n", 1)

          # Access signals using Verilog names
          sim.set("i_wb_cyc", 1)
          sim.step()
          value = sim.get("o_wb_dat")

          sim.close()



.. py:function:: load_wrapper_from_toml(toml_path, generate_dest = None)

   Load an RTLWrapper from a TOML configuration file.

   :param toml_path: Path to the TOML configuration file
   :param generate_dest: Destination directory for generated Verilog (if using SpinalHDL)

   :returns: Configured RTLWrapper component

   :raises ChipFlowError: If configuration is invalid or generation fails