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

.. py:module:: chipflow.rtl

.. autoapi-nested-parse::

   RTL integration for ChipFlow.

   This module provides infrastructure for integrating external RTL (Verilog,
   SystemVerilog, SpinalHDL, etc.) into Amaranth designs via TOML configuration.

   Example usage::

       from chipflow.rtl import RTLWrapper, load_wrapper_from_toml

       # Load a timer peripheral from TOML configuration
       timer = load_wrapper_from_toml("wb_timer.toml", generate_dest="build/gen")

       # Add to SoC
       wb_decoder.add(timer.bus, name="timer", addr=TIMER_BASE)
       m.submodules.timer = timer

       # Build a standalone CXXRTL simulator for testing
       sim = timer.build_simulator("build/sim")
       sim.set("i_clk", 1)
       sim.step()



Submodules
----------

.. toctree::
   :maxdepth: 1

   /chipflow-lib/autoapi/chipflow/rtl/wrapper/index


Classes
-------

.. autoapisummary::

   chipflow.rtl.RTLWrapper


Functions
---------

.. autoapisummary::

   chipflow.rtl.load_wrapper_from_toml


Package 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