siliconcompiler 0.36.2__py3-none-any.whl → 0.36.4__py3-none-any.whl

siliconcompiler/tools/_common/cocotb/cocotb_task.py

@@ -0,0 +1,286 @@
+import os
+import sys
+from pathlib import Path
+from typing import Optional, Union, Dict
+import xml.etree.ElementTree as ET
+
+from siliconcompiler import Task
+
+try:
+    import cocotb_tools.config
+    from cocotb_tools.runner import Runner
+    _has_cocotb = True
+except ModuleNotFoundError:
+    _has_cocotb = False
+    Runner = object
+
+
+def get_cocotb_config(sim="icarus"):
+    if not _has_cocotb:
+        raise NotImplementedError("COCOTB must be installed to use get_cocotb_config")
+
+    libs_dir = cocotb_tools.config.libs_dir
+    lib_name = cocotb_tools.config.lib_name("vpi", sim)
+    share_dir = cocotb_tools.config.share_dir
+
+    return libs_dir, lib_name, share_dir
+
+
+class CocotbRunnerDummy(Runner):
+    """
+    A minimal Runner subclass used solely to retrieve the libpython path.
+
+    This class provides access to the libpython shared library location
+    without adding ``find_libpython`` as a direct dependency. It leverages
+    cocotb's existing Runner infrastructure, which handles libpython
+    discovery internally via the ``_set_env()`` method.
+
+    The abstract methods required by the Runner base class are implemented
+    as no-ops or raise NotImplementedError, as they are not intended to be
+    called. This class should only be instantiated to call
+    ``get_libpython_path()``.
+
+    Example:
+        >>> libpython = CocotbRunnerDummy().get_libpython_path()
+        >>> print(libpython)
+        /usr/lib/x86_64-linux-gnu/libpython3.10.so
+    """
+
+    def __init__(self):
+        if not _has_cocotb:
+            raise NotImplementedError("COCOTB must be installed to use get_cocotb_config")
+
+        super().__init__()
+        # These attributes are required by _set_env() which uses them to
+        # populate environment variables.
+        self.sim_hdl_toplevel = ""
+        self.test_module = ""
+        self.hdl_toplevel_lang = ""
+
+    def _simulator_in_path(self):
+        # No-op: This dummy class doesn't require any simulator executable.
+        pass
+
+    def _build_command(self):
+        raise NotImplementedError(
+            "CocotbRunnerDummy is not intended for building HDL sources")
+
+    def _test_command(self):
+        raise NotImplementedError(
+            "CocotbRunnerDummy is not intended for running tests")
+
+    def _get_define_options(self, defines):
+        raise NotImplementedError(
+            "CocotbRunnerDummy is not intended for HDL compilation")
+
+    def _get_include_options(self, includes):
+        raise NotImplementedError(
+            "CocotbRunnerDummy is not intended for HDL compilation")
+
+    def _get_parameter_options(self, parameters):
+        raise NotImplementedError(
+            "CocotbRunnerDummy is not intended for HDL compilation")
+
+    def get_libpython_path(self):
+        """
+        Retrieve the path to the libpython shared library.
+
+        This method uses cocotb's ``Runner._set_env()`` which internally
+        calls ``find_libpython.find_libpython()`` to locate the library.
+
+        Returns:
+            str: Absolute path to the libpython shared library.
+
+        Raises:
+            ValueError: If libpython cannot be found.
+        """
+        self._set_env()
+        return self.env["LIBPYTHON_LOC"]
+
+
+class CocotbTask(Task):
+
+    def __init__(self):
+        super().__init__()
+
+        self.add_parameter("cocotb_random_seed", "int",
+                           'Random seed for cocotb test reproducibility. '
+                           'If not set, cocotb will generate a random seed.')
+
+    def set_cocotb_randomseed(
+        self, seed: int,
+        step: Optional[str] = None,
+        index: Optional[Union[str, int]] = None
+    ):
+        """
+        Sets the random seed for cocotb tests.
+
+        Args:
+            seed (int): The random seed value.
+            step (str, optional): The specific step to apply this configuration to.
+            index (str, optional): The specific index to apply this configuration to.
+        """
+        self.set("var", "cocotb_random_seed", seed, step=step, index=index)
+
+    def task(self):
+        return "exec_cocotb"
+
+    def _get_test_modules(self):
+        """
+        Get cocotb test module names from Python files in filesets.
+
+        Returns:
+            tuple: (module_names, module_dirs) where module_names is a
+                   comma-separated string and module_dirs is a list of
+                   directories containing the modules.
+        """
+        module_names = []
+        module_dirs = []
+        seen_dirs = set()
+
+        for lib, fileset in self.project.get_filesets():
+            for pyfile in lib.get_file(fileset=fileset, filetype="python"):
+                path = Path(pyfile)
+                # Module name is the filename without .py extension
+                module_name = path.stem
+                module_names.append(module_name)
+                # Track the directory for PYTHONPATH
+                dir_path = str(path.parent.resolve())
+                if dir_path not in seen_dirs:
+                    seen_dirs.add(dir_path)
+                    module_dirs.append(dir_path)
+
+        return ",".join(module_names), module_dirs
+
+    def _get_toplevel_lang(self):
+        """
+        Determine the HDL toplevel language from the design schema.
+
+        For Icarus Verilog, this is always "verilog" since Icarus
+        doesn't support VHDL. SystemVerilog is treated as Verilog
+        for cocotb's TOPLEVEL_LANG.
+
+        Returns:
+            str: The toplevel language ("verilog").
+        """
+        # Icarus only supports Verilog/SystemVerilog, not VHDL
+        # cocotb uses "verilog" for both Verilog and SystemVerilog
+        return "verilog"
+
+    def __setup_cocotb_environment(self):
+        """
+        Set up all required environment variables for cocotb execution.
+        """
+
+        test_modules, _ = self._get_test_modules()
+        libpython_path = CocotbRunnerDummy().get_libpython_path()
+
+        # LIBPYTHON_LOC: path to libpython shared library
+        self.set_environmentalvariable("LIBPYTHON_LOC", libpython_path)
+        self.add_required_key("env", "LIBPYTHON_LOC")
+
+        # COCOTB_TOPLEVEL: the HDL toplevel module name
+        self.set_environmentalvariable("COCOTB_TOPLEVEL", self.design_topmodule)
+        self.add_required_key("env", "COCOTB_TOPLEVEL")
+
+        # COCOTB_TEST_MODULES: comma-separated list of Python test modules
+        self.set_environmentalvariable("COCOTB_TEST_MODULES", test_modules)
+        self.add_required_key("env", "COCOTB_TEST_MODULES")
+
+        # TOPLEVEL_LANG: HDL language of the toplevel
+        self.set_environmentalvariable("TOPLEVEL_LANG", self._get_toplevel_lang())
+        self.add_required_key("env", "TOPLEVEL_LANG")
+
+        # COCOTB_RESULTS_FILE: path to xUnit XML results
+        self.set_environmentalvariable("COCOTB_RESULTS_FILE", "outputs/results.xml")
+        self.add_required_key("env", "COCOTB_RESULTS_FILE")
+
+        # COCOTB_RANDOM_SEED: optional random seed for reproducibility
+        random_seed = self.get("var", "cocotb_random_seed")
+        if random_seed is not None:
+            self.set_environmentalvariable("COCOTB_RANDOM_SEED", str(random_seed))
+            self.add_required_key("env", "COCOTB_RANDOM_SEED")
+
+    def setup(self):
+        super().setup()
+
+        if not _has_cocotb:
+            raise RuntimeError("Cocotb is not installed; cannot run test.")
+
+        # Output: xUnit XML results file
+        self.add_output_file(file="results.xml")
+
+        self.add_required_key("option", "design")
+        self.add_required_key("option", "fileset")
+        if self.project.get("option", "alias"):
+            self.add_required_key("option", "alias")
+
+        # Require Python test modules
+        for lib, fileset in self.project.get_filesets():
+            if lib.has_file(fileset=fileset, filetype="python"):
+                self.add_required_key(lib, "fileset", fileset, "file", "python")
+
+        if self.get("var", "cocotb_random_seed") is not None:
+            self.add_required_key("var", "cocotb_random_seed")
+
+        # Set up cocotb environment variables
+        self.__setup_cocotb_environment()
+
+    def get_runtime_environmental_variables(self, include_path: bool = True) -> Dict[str, str]:
+        envs = super().get_runtime_environmental_variables(include_path)
+
+        _, module_dirs = self._get_test_modules()
+        libs_dir = cocotb_tools.config.libs_dir
+
+        # PATH: add cocotb libs directory
+        current_path = os.environ.get("PATH", "")
+        new_path = f"{libs_dir}{os.pathsep}{current_path}"
+        envs["PATH"] = new_path
+
+        # PYTHONPATH: add directories containing test modules
+        current_pythonpath = os.environ.get("PYTHONPATH", "")
+        pythonpath_parts = module_dirs + ([current_pythonpath] if current_pythonpath else [])
+        envs["PYTHONPATH"] = os.pathsep.join(pythonpath_parts)
+
+        # PYGPI_PYTHON_BIN: Python executable
+        envs["PYGPI_PYTHON_BIN"] = sys.executable
+
+        return envs
+
+    def _parse_cocotb_results(self, results_file: Path):
+        """
+        Parse the cocotb xUnit XML results file and extract metrics.
+
+        Args:
+            results_file: Path to the results.xml file.
+        """
+        try:
+            tree = ET.parse(results_file)
+            root = tree.getroot()
+
+            # Count testcases and failures/errors
+            testcases = root.findall(".//testcase")
+            tests = len(testcases)
+            failures = len(root.findall(".//failure"))
+            errors = len(root.findall(".//error"))
+
+            passed = tests - failures - errors
+
+            self.logger.info(f"Cocotb results: {passed}/{tests} tests passed")
+            if failures > 0:
+                self.logger.warning(f"Cocotb: {failures} test(s) failed")
+            if errors > 0:
+                self.logger.warning(f"Cocotb: {errors} test(s) had errors")
+
+            self.record_metric("errors", errors + failures, source_file=results_file)
+
+        except Exception as e:
+            self.logger.warning(f"Failed to parse cocotb results: {e}")
+
+    def post_process(self):
+        super().post_process()
+
+        # Parse cocotb results XML and report metrics
+        results_file = Path("outputs/results.xml")
+        if results_file.exists():
+            self._parse_cocotb_results(results_file)

siliconcompiler/tools/builtin/wait.py

@@ -0,0 +1,152 @@
+from typing import TYPE_CHECKING
+
+from siliconcompiler.tools.builtin import BuiltinTask
+
+if TYPE_CHECKING:
+    from siliconcompiler import Flowgraph
+
+
+class Wait(BuiltinTask):
+    '''
+    A wait task that stalls the flow until all inputs are available.
+    '''
+    def __init__(self):
+        super().__init__()
+
+    def _set_io_files(self):
+        # No file IO needed for wait task
+        return
+
+    def task(self):
+        return "wait"
+
+    @staticmethod
+    def __has_path(flowgraph: "Flowgraph", source: tuple, target: tuple) -> bool:
+        '''
+        Helper method to check if there's any path from source to target node.
+
+        Args:
+            flowgraph: The flowgraph to search.
+            source: Tuple of (step, index) for the source node.
+            target: Tuple of (step, index) for the target node.
+
+        Returns:
+            bool: True if there's a path from source to target, False otherwise.
+        '''
+        if source == target:
+            return True
+
+        visited = set()
+        to_visit = [source]
+
+        while to_visit:
+            current = to_visit.pop(0)
+            if current == target:
+                return True
+            if current in visited:
+                continue
+            visited.add(current)
+
+            # Add all output nodes to the queue
+            outputs = flowgraph.get_node_outputs(current[0], current[1])
+            to_visit.extend(outputs)
+
+        return False
+
+    @staticmethod
+    def serialize_tool_tasks(flowgraph: "Flowgraph", tool_name: str) -> None:
+        '''
+        Adds wait tasks between nodes of the same tool that could execute in parallel.
+
+        This method inserts `Wait` task nodes between nodes that use the same
+        tool, but only when those nodes could execute in parallel (i.e., there's
+        no dependency path between them). This ensures that tool instances don't
+        execute in parallel, while avoiding unnecessary wait tasks for nodes
+        that already have a dependency relationship.
+
+        The method modifies the flowgraph in-place by:
+        1. Finding all nodes that use the specified tool
+        2. For each pair of tool nodes with no dependency path, inserting a wait task
+        3. Using naming convention: {target_step}.wait
+           (named after the node being delayed)
+
+        Args:
+            flowgraph: The flowgraph to modify.
+            tool_name (str): The name of the tool (e.g., 'openroad', 'yosys').
+                All nodes using this tool will be serialized.
+
+        Raises:
+            ValueError: If the flowgraph is invalid or tool_name is empty.
+
+        Example:
+            >>> flow = Flowgraph("myflow")
+            >>> flow.node("place1", openroad.Place, index=0)
+            >>> flow.node("syn", yosys.Syn, index=0)
+            >>> flow.node("place2", openroad.Place, index=1)
+            >>> flow.edge("place1", "syn")
+            >>> flow.edge("syn", "place2")
+            >>> Wait.serialize_tool_tasks(flow, "openroad")
+            >>> # No wait task added - place1 and place2 already have a dependency path
+        '''
+        if not tool_name or not isinstance(tool_name, str):
+            raise ValueError(f"tool_name must be a non-empty string, not {tool_name}")
+
+        if not flowgraph.validate():
+            raise ValueError(f"Flowgraph '{flowgraph.name}' is invalid before serialization")
+
+        # Find all nodes using the specified tool
+        tool_nodes = []
+        for step, index in flowgraph.get_nodes():
+            graph_node = flowgraph.get_graph_node(step, index)
+            if graph_node.get_tool() == tool_name:
+                tool_nodes.append((step, index))
+
+        if not tool_nodes or len(tool_nodes) < 2:
+            # Need at least 2 nodes to create wait tasks
+            return
+
+        # Sort nodes by execution order to establish a consistent serialization
+        execution_order = flowgraph.get_execution_order()
+        node_order_map = {}
+        for level_idx, level in enumerate(execution_order):
+            for node_idx, node in enumerate(level):
+                node_order_map[node] = (level_idx, node_idx)
+
+        sorted_tool_nodes = sorted(
+            tool_nodes, key=lambda n: node_order_map.get(n, (float('inf'), 0)))
+
+        # Check if there are pairs without dependency paths that need serialization
+        needs_serialization = False
+        for i in range(len(sorted_tool_nodes)):
+            for j in range(i + 1, len(sorted_tool_nodes)):
+                node1 = sorted_tool_nodes[i]
+                node2 = sorted_tool_nodes[j]
+                if not Wait.__has_path(flowgraph, node1, node2):
+                    needs_serialization = True
+                    break
+            if needs_serialization:
+                break
+
+        if not needs_serialization:
+            # All tool nodes already have dependency paths, no wait nodes needed
+            return
+
+        # Create wait nodes between each pair of consecutive tool nodes
+        # Chain: tool[0] -> wait_1 -> tool[1] -> wait_2 -> tool[2] -> ...
+        for i in range(len(sorted_tool_nodes) - 1):
+            curr_node = sorted_tool_nodes[i]
+            next_node = sorted_tool_nodes[i + 1]
+
+            # Check if there's already a dependency path between them
+            if Wait.__has_path(flowgraph, curr_node, next_node):
+                # Already serialized, skip
+                continue
+
+            # Create wait node named after the next node (the one being delayed)
+            wait_step = f"{next_node[0]}.wait"
+            wait_index = next_node[1]
+            flowgraph.node(wait_step, Wait(), index=wait_index)
+
+            # Connect: curr_node -> wait_node -> next_node
+            flowgraph.edge(curr_node[0], wait_step, tail_index=curr_node[1], head_index=wait_index)
+            flowgraph.edge(wait_step, next_node[0], tail_index=wait_index, head_index=next_node[1])

siliconcompiler/tools/icarus/cocotb_exec.py

@@ -0,0 +1,53 @@
+from siliconcompiler.tools._common.cocotb.cocotb_task import (
+    CocotbTask,
+    get_cocotb_config
+)
+
+
+class CocotbExecTask(CocotbTask):
+    '''
+    Run a cocotb testbench against a compiled Icarus Verilog simulation.
+
+    This task takes a compiled .vvp file from the icarus compile task and
+    executes it with the cocotb VPI module loaded, enabling Python-based
+    testbenches to interact with the simulation.
+
+    The task requires cocotb to be installed in the Python environment.
+    Test modules are specified by adding Python files to the fileset using
+    the "python" filetype.
+    '''
+
+    def tool(self):
+        return "icarus"
+
+    def parse_version(self, stdout):
+        # vvp version output: "Icarus Verilog runtime version 13.0 (devel) ..."
+        return stdout.split()[4]
+
+    def setup(self):
+        super().setup()
+
+        # vvp is the Icarus Verilog runtime
+        self.set_exe("vvp", vswitch="-V")
+        self.add_version(">=10.3")
+
+        self.set_threads()
+
+        # Input: compiled .vvp file from compile task
+        self.add_input_file(ext="vvp")
+
+    def runtime_options(self):
+        options = super().runtime_options()
+
+        libs_dir, lib_name, _ = get_cocotb_config("icarus")
+
+        # -M: VPI module search path
+        options.extend(["-M", str(libs_dir)])
+
+        # -m: VPI module to load
+        options.extend(["-m", lib_name])
+
+        # Input .vvp file
+        options.append(f"inputs/{self.design_topmodule}.vvp")
+
+        return options

siliconcompiler/tools/icarus/compile.py

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import Optional, Union
 from siliconcompiler import Task
 
 
@@ -15,6 +15,11 @@ class CompileTask(Task):
                            'See the corresponding "-g" flags in the Icarus manual for more "'
                            '"information.')
 
+        self.add_parameter("trace", "bool",
+                           'Enable waveform tracing. When enabled, a VCD dump module is '
+                           'auto-generated and compiled with the design to capture all signals.',
+                           defvalue=False)
+
     def set_icarus_veriloggeneration(self, gen: str,
                                      step: Optional[str] = None,
                                      index: Optional[str] = None):
@@ -28,6 +33,22 @@ class CompileTask(Task):
         """
         self.set("var", "verilog_generation", gen, step=step, index=index)
 
+    def set_trace_enabled(self, enabled: bool = True,
+                          step: Optional[str] = None,
+                          index: Optional[Union[str, int]] = None):
+        """
+        Enables or disables waveform tracing.
+
+        When enabled, a VCD dump module is auto-generated and compiled with
+        the design. The waveform file will be written to reports/<topmodule>.vcd.
+
+        Args:
+            enabled (bool): Whether to enable tracing. Defaults to True.
+            step (str, optional): The specific step to apply this configuration to.
+            index (str, optional): The specific index to apply this configuration to.
+        """
+        self.set("var", "trace", enabled, step=step, index=index)
+
     def tool(self):
         return "icarus"
 
@@ -74,6 +95,26 @@ class CompileTask(Task):
         if self.get("var", "verilog_generation"):
             self.add_required_key("var", "verilog_generation")
 
+    def pre_process(self):
+        super().pre_process()
+
+        # Generate VCD dump module if tracing is enabled
+        if self.get("var", "trace"):
+            self._generate_trace_module()
+
+    def _generate_trace_module(self):
+        trace_file = f"reports/{self.design_topmodule}.vcd"
+        dump_module = f"""// Auto-generated waveform dump module
+module sc_trace_dump();
+initial begin
+    $dumpfile("{trace_file}");
+    $dumpvars(0, {self.design_topmodule});
+end
+endmodule
+"""
+        with open("sc_trace_dump.v", "w") as f:
+            f.write(dump_module)
+
     def runtime_options(self):
         options = super().runtime_options()
 
@@ -137,4 +178,9 @@ class CompileTask(Task):
             for value in lib.get_file(fileset=fileset, filetype="verilog"):
                 options.append(value)
 
+        # Add trace dump module if tracing is enabled
+        if self.get("var", "trace"):
+            options.append("sc_trace_dump.v")
+            options.extend(["-s", "sc_trace_dump"])
+
         return options

siliconcompiler/tools/klayout/export.py

@@ -79,8 +79,6 @@ class ExportTask(KLayoutTask, ScreenshotParams):
         self.add_output_file(ext="lyt")
         self.add_output_file(ext="lyp")
 
-        self.add_required_key("var", "stream")
-
         sc_stream_order = [default_stream, *[s for s in ("gds", "oas") if s != default_stream]]
         req_set = False
         for s in sc_stream_order:

siliconcompiler/tools/klayout/merge.py

@@ -0,0 +1,95 @@
+from typing import Optional, Union
+
+from siliconcompiler.tools.klayout import KLayoutTask
+
+
+class Merge(KLayoutTask):
+    """
+    Klayout task to merge multiple GDS files and provide prefixing for cell names.
+    """
+    def __init__(self):
+        super().__init__()
+
+        self.add_parameter("reference", "(<fs,input>,str,str)",
+                           "Reference fileset or input node for merge operation, structured as "
+                           "(fs, library name, fileset) or (input, step, index)")
+        self.add_parameter("merge", "[(<fs,input>,str,str,str)]",
+                           "Fileset or input node to be merge with prefix, structured as "
+                           "(fs, library name, fileset) or (input, step, index) along with prefix "
+                           "string")
+
+    def __fix_type(self, type: str) -> str:
+        if type == "fileset":
+            return "fs"
+        return type
+
+    def set_klayout_reference(self, type: str, source0: str, source1: str,
+                              step: Optional[str] = None,
+                              index: Optional[Union[str, int]] = None):
+        """
+        Sets the reference file for the merge operation.
+        Args:
+            type (str): The reference fileset or input node.
+            source0 (str): The first part of the source (library name or step).
+            source1 (str): The second part of the source (fileset name or index).
+            step (Optional[str]): The specific step to apply this configuration to.
+            index (Optional[Union[str, int]]): The specific index to apply this configuration to.
+        """
+        self.set("var", "reference", (self.__fix_type(type), source0, source1),
+                 step=step, index=index)
+
+    def add_klayout_merge(self, type: str, source0: str, source1: str, prefix: str,
+                          step: Optional[str] = None,
+                          index: Optional[Union[str, int]] = None, clobber: bool = False):
+        """
+        Adds a file to be merged with the reference file.
+        Args:
+            type (str): The fileset or input node to be merged.
+            prefix (str): The prefix to apply during the merge.
+            source0 (str): The first part of the source (library name or step).
+            source1 (str): The second part of the source (fileset name or index).
+            step (Optional[str]): The specific step to apply this configuration to.
+            index (Optional[Union[str, int]]): The specific index to apply this configuration to.
+            clobber (bool, optional): If True, overwrites the existing list of merge files.
+                                      If False, appends to the list. Defaults to False.
+        """
+        if clobber:
+            self.set("var", "merge", (self.__fix_type(type), source0, source1, prefix),
+                     step=step, index=index)
+        else:
+            self.add("var", "merge", (self.__fix_type(type), source0, source1, prefix),
+                     step=step, index=index)
+
+    def task(self) -> str:
+        return 'merge'
+
+    def setup(self) -> None:
+        super().setup()
+
+        self.set_script("klayout_merge.py")
+
+        self.add_required_key("var", "reference")
+        self.add_required_key("var", "merge")
+
+        if self.get("var", "reference"):
+            ref_type, ref_source0, ref_source1 = self.get("var", "reference")
+            if ref_type == 'input':
+                step, index = ref_source0, ref_source1
+                self.add_input_file(
+                    self.compute_input_file_node_name(f"{self.design_topmodule}.gds",
+                                                      step, index))
+            else:
+                lib_name, fileset = ref_source0, ref_source1
+                self.add_required_key("library", lib_name, "fileset", fileset, "file", "gds")
+        for merge_entry in self.get("var", "merge"):
+            merge_type, merge_source0, merge_source1, _ = merge_entry
+            if merge_type == 'input':
+                step, index = merge_source0, merge_source1
+                self.add_input_file(
+                    self.compute_input_file_node_name(f"{self.design_topmodule}.gds",
+                                                      step, index))
+            else:
+                lib_name, fileset = merge_source0, merge_source1
+                self.add_required_key("library", lib_name, "fileset", fileset, "file", "gds")
+
+        self.add_output_file(ext="gds")