piel.tools.amaranth
===================

.. py:module:: piel.tools.amaranth


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/piel/tools/amaranth/construct/index
   /autoapi/piel/tools/amaranth/export/index
   /autoapi/piel/tools/amaranth/verify/index


Functions
---------

.. autoapisummary::

   piel.tools.amaranth.construct_amaranth_module_from_truth_table
   piel.tools.amaranth.generate_verilog_from_amaranth_truth_table
   piel.tools.amaranth.verify_amaranth_truth_table


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

.. py:function:: construct_amaranth_module_from_truth_table(truth_table: piel.types.digital.TruthTable, logic_implementation_type: piel.types.digital.LogicImplementationType = 'combinatorial')

   Constructs an Amaranth module based on the provided truth table.
   # TODO implementation type

   :param truth_table: The truth table to be implemented as a TruthTable object.
   :type truth_table: TruthTable
   :param logic_implementation_type: The type of implementation.
                                     - "combinatorial": Implements the truth table as combinational logic.
                                     - "sequential": Implements the truth table as sequential logic.
                                     - "memory": Implements the truth table using memory elements.
                                     Defaults to "combinatorial".
   :type logic_implementation_type: Literal["combinatorial", "sequential", "memory"], optional

   :returns: An Amaranth module implementing the given truth table.
   :rtype: am.Module

   .. rubric:: Examples

   >>> detector_phase_truth_table = {
   >>>     "detector_in": ["00", "01", "10", "11"],
   >>>     "phase_map_out": ["00", "10", "11", "11"],
   >>> }
   >>> my_truth_table = TruthTable(
   >>>     input_ports=["detector_in"],
   >>>     output_ports=["phase_map_out"],
   >>>     **detector_phase_truth_table
   >>> )
   >>> am_module = construct_amaranth_module_from_truth_table(my_truth_table)


.. py:function:: generate_verilog_from_amaranth_truth_table(amaranth_module: Any, truth_table: piel.types.TruthTable, target_file_name: str, target_directory: piel.types.PathTypes, backend: Literal['verilog', 'vhdl'] = 'verilog') -> None

   Exports an Amaranth module to Verilog code and writes it to a specified path.

   This function converts an Amaranth elaboratable class to Verilog using the specified backend
   and writes the generated code to a file in the target directory. It supports both direct paths
   and paths defined by the project's module structure.

   :param amaranth_module: The Amaranth module to be converted.
   :type amaranth_module: amaranth.Elaboratable
   :param truth_table: A truth table object containing input and output connection.
   :type truth_table: TruthTable
   :param target_file_name: The name of the target file to write the Verilog code to.
   :type target_file_name: str
   :param target_directory: The target directory where the file will be saved.
                            Can be a direct path or a module type path.
   :type target_directory: PathTypes
   :param backend: The backend to use for Verilog conversion. Defaults to `verilog`.
   :type backend: amaranth.back.verilog, optional

   :returns: None

   :raises AttributeError: If any port specified in the truth table is not found in the Amaranth module.

   .. rubric:: Examples

   >>> am_module = MyAmaranthModule()  # Assuming this is a defined Amaranth module.
   >>> truth_table = TruthTable(
   >>>     input_ports=["input1", "input2"],
   >>>     output_ports=["output1"],
   >>>     input1=["00", "01", "10", "11"],
   >>>     output1=["0", "1", "1", "0"]
   >>> )
   >>> generate_verilog_from_amaranth_truth_table(am_module, truth_table, "output.v", "/path/to/save")


.. py:function:: verify_amaranth_truth_table(truth_table_amaranth_module: Any, truth_table: piel.types.digital.TruthTable, vcd_file_name: str, target_directory: piel.types.PathTypes, implementation_type: Literal['combinatorial', 'sequential', 'memory'] = 'combinatorial')

   Verifies that the outputs generated by the given Amaranth module match the provided truth table.

   This function runs a simulation of the Amaranth module and checks if the outputs for each set of inputs
   match the expected outputs as specified in the truth table. It can optionally generate a VCD file for detailed analysis.

   :param truth_table_amaranth_module: The Amaranth module to be verified.
   :type truth_table_amaranth_module: amaranth.Elaboratable
   :param truth_table: The truth table specifying expected inputs and outputs.
   :type truth_table: TruthTable
   :param vcd_file_name: The name of the VCD file to generate for the simulation.
   :type vcd_file_name: str
   :param target_directory: The directory where the VCD file will be saved. Can be a direct path or a module type path.
   :type target_directory: PathTypes
   :param implementation_type: The type of implementation to simulate. Defaults to "combinatorial".
   :type implementation_type: Literal["combinatorial", "sequential", "memory"], optional

   :returns: None

   :raises AttributeError: If the specified connection are not found in the Amaranth module.

   .. rubric:: Examples

   >>> am_module = MyAmaranthModule()  # Assuming this is a defined Amaranth module.
   >>> truth_table = TruthTable(
   >>>     input_ports=["input1"],
   >>>     output_ports=["output1", "output2"],
   >>>     input1=["0", "1"],
   >>>     output1=["1", "0"],
   >>>     output2=["0", "1"]
   >>> )
   >>> verify_amaranth_truth_table(am_module, truth_table, "output.vcd", "/path/to/save")