piel.flows.digital_logic
========================

.. py:module:: piel.flows.digital_logic


Functions
---------

.. autoapisummary::

   piel.flows.digital_logic.generate_verilog_and_verification_from_truth_table
   piel.flows.digital_logic.layout_truth_table
   piel.flows.digital_logic.read_simulation_data_to_truth_table
   piel.flows.digital_logic.run_verification_simulation_for_design
   piel.flows.digital_logic.get_latest_digital_run_component


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

.. py:function:: generate_verilog_and_verification_from_truth_table(module: piel.types.PathTypes, truth_table: piel.types.TruthTable, target_file_name: str = 'truth_table_module')

   Processes a truth table to generate an Amaranth module, converts it to Verilog,
   and creates a testbench for verification.

   Parameters:
   - truth_table (dict): The truth table defining the logic. It should be a dictionary where keys are
                         port names and values are lists of binary strings representing the truth table entries.
                         Example: {"detector_in": ["00", "01", "10", "11"], "phase_map_out": ["00", "10", "11", "11"]}
   - input_ports (list of str): A list of input port names that correspond to keys in the truth table.
                                Example: ["detector_in"]
   - output_ports (list of str): A list of output port names that correspond to keys in the truth table.
                                 Example: ["phase_map_out"]
   - module (str): The name or path of the module within the design hierarchy where the generated files
                   will be placed. This is used to determine the file structure and directory paths.
                   Example: "full_flow_demo"
   - target_file_name (str): The verilog and vcd file name.

   Returns:
   - None

   Steps:
   1. Combines the input and output connection into a single list.
   2. Constructs an Amaranth module from the provided truth table.
   3. Determines the appropriate directory and source folder for the design.
   4. Generates a Verilog file from the Amaranth module.
   5. Creates a testbench to verify the generated module logic and produces a VCD file.


.. py:function:: layout_truth_table(truth_table: piel.types.TruthTable, module: piel.types.PathTypes) -> piel.types.ElectronicCircuitComponent

   Layout a truth table through the OpenLane flow and create a GDSFactory component.

   Parameters:
   - truth_table (TruthTable): The truth table object containing the input and output port files.
   - module (str): The name or path of the module within the design hierarchy where the generated files
                   will be placed. This is used to determine the file structure and directory paths.
                   Example: "full_flow_demo"

   Returns:
   - digital_component (gf.Component): The GDSFactory component representing the layout of the truth table as implemented by OpenLane


.. py:function:: read_simulation_data_to_truth_table(file_path: piel.types.PathTypes, input_ports: piel.types.LogicSignalsList, output_ports: piel.types.LogicSignalsList, *args, **kwargs) -> piel.types.TruthTable

   The goal of this function is to read an existing simulation files output from cocotb and convert it into a valid Dataframe with proper type validation of bit signals into the corresponding byte formats.

   Args:
   - file_path (PathTypes): The path to the simulation files file.
   - input_ports (LogicSignalsList): The list of input port names.
   - output_ports (LogicSignalsList): The list of output port names.

   Returns:
   - truth_table (TruthTable): The truth table object containing the input and output port files.

   Examples:
   >>> read_simulation_data_to_truth_table("simulation_data.csv", ["input_port"], ["output_port"])
   TruthTable(input_ports=["input_port"], output_ports=["output_port"], ...)


.. py:function:: run_verification_simulation_for_design(module: piel.types.PathTypes, top_level_verilog_module: str, test_python_module: str, simulator: piel.types.HDLSimulator = 'icarus')

   Configures and runs a Cocotb simulation for a given design module and retrieves the simulation files.
   TODO possibly in the future swap the methodology of running the simulation here.

   Parameters:
   - module (str): The name or path of the module within the design hierarchy where the generated files
                   will be placed. This is used to determine the file structure and directory paths.
                   Example: "full_flow_demo"
   - top_level_verilog_module (str): The name of the top-level Verilog module in the design.
                                       Example: "full_flow_demo_module"
   - test_python_module (str): The name of the Python test module for the design.
                               Example: "test_full_flow_demo"
   - simulator (HDLSimulator): The simulator to use for the Cocotb simulation. Default is "icarus".

   Returns:
   - example_simulation_data: The simulation files read from the output files.


.. py:function:: get_latest_digital_run_component(module: piel.types.PathTypes, *args, **kwargs) -> piel.types.CircuitComponent