librelane 2.4.0.dev0__py3-none-any.whl

librelane/steps/tclstep.py

@@ -0,0 +1,288 @@
+# Copyright 2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import os
+import threading
+from enum import Enum
+from decimal import Decimal
+from abc import abstractmethod
+from dataclasses import is_dataclass, asdict
+from typing import (
+    Any,
+    ClassVar,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+    Dict,
+    Union,
+)
+
+from .step import ViewsUpdate, MetricsUpdate, Step, StepException
+
+from ..state import State, DesignFormat
+from ..common import (
+    Path,
+    TclUtils,
+    get_script_dir,
+    protected,
+    is_string,
+)
+
+
+class TclStep(Step):
+    """
+    A subclass of :class:`Step` that primarily deals with running Tcl-based utilities,
+    such as Yosys, OpenROAD and Magic.
+
+    A TclStep Step should ideally correspond to running one Tcl script with such
+    a utility.
+
+    :cvar reproducibles_allowed: Whether this class can generate reproducibles.
+    """
+
+    reproducibles_allowed: ClassVar[bool] = True
+
+    @staticmethod
+    def value_to_tcl(value: Any) -> str:
+        """
+        Converts an arbitrary Python value to Tcl as follows:
+
+        * If the value is an instance of a dataclass, it is serialized as a JSON object.
+        * If the value is a list, it is joined using :meth:`TclUtils.join`.
+        * If the value is a dict, the keys and values are escaped recursively using:
+            joined using :meth:`TclUtils.join`.
+        * If the value is an Enum, its name is returned.
+        * If the value is Boolean, "1" is returned for True and "0" for False.
+        * If the value is numeric, it is converted to a string.
+        * Otherwise, the value is passed to ``str()``.
+        """
+        if not isinstance(value, type) and is_dataclass(value):
+            return TclStep.value_to_tcl(asdict(value))
+        elif isinstance(value, Mapping):
+            result = []
+            for v_key, v_value in value.items():
+                result.append(TclStep.value_to_tcl(v_key))
+                result.append(TclStep.value_to_tcl(v_value))
+            return TclUtils.join(result)
+        elif isinstance(value, Iterable) and not is_string(value):
+            result = []
+            for item in value:
+                result.append(TclStep.value_to_tcl(item))
+            return TclUtils.join(result)
+        elif isinstance(value, Enum):
+            return value.name
+        elif isinstance(value, bool):
+            return "1" if value else "0"
+        elif isinstance(value, Decimal) or isinstance(value, int):
+            return str(value)
+        else:
+            return str(value)
+
+    @protected
+    @abstractmethod
+    def get_script_path(self) -> str:
+        """
+        :returns: A path to the Tcl script to be run by this step.
+        """
+        pass
+
+    @protected
+    def get_command(self) -> List[str]:
+        """
+        This command should be overridden by subclasses and replaced with a
+        command incorporating the  appropriate tool: e.g. ``openroad``,
+        ``yosys``, et cetera.
+
+        :returns: A list of strings representing the command used to run the script,
+            including the result of :meth:`get_script_path`.
+        """
+        return ["tclsh", self.get_script_path()]
+
+    @protected
+    def prepare_env(self, env: dict, state: State) -> dict:
+        """
+        Creates a copy of an environment dictionary, then converts all accessible
+        ``self.config`` variables and state inputs to environment variables so
+        they may be used as inputs to the scripts.
+
+        Inputs are assigned the keys ``CURRENT_{ID}`` where ID is
+        the relevant :class:`DesignFormat`'s enum name.
+
+        Outputs are assigned the keys ``CURRENT_{ID}`` where ID is
+        the relevant :class:`DesignFormat`'s enum name, although outputs with
+        multiple values (SPEF, etc) will be skipped and a step is expected to
+        handle creating variables for them on its own.
+
+        The values are converted to strings as per :meth:`value_to_tcl`.
+
+        :param env: The input environment dictionary
+        :param state: The input state
+        :returns: a copy of the environment dictionary where ``self.config`` variables
+        """
+        env = env.copy()
+
+        env["STEP_ID"] = self.get_implementation_id()
+        env["SCRIPTS_DIR"] = os.path.abspath(get_script_dir())
+        env["STEP_DIR"] = os.path.abspath(self.step_dir)
+
+        tech_lefs = self.toolbox.filter_views(self.config, self.config["TECH_LEFS"])
+        if len(tech_lefs) != 1:
+            raise StepException(
+                "Misconfigured SCL: 'TECH_LEFS' must return exactly one Tech LEF for its default timing corner."
+            )
+
+        env["TECH_LEF"] = tech_lefs[0]
+
+        macro_lefs = self.toolbox.get_macro_views(self.config, DesignFormat.LEF)
+        env["MACRO_LEFS"] = TclUtils.join([str(lef) for lef in macro_lefs])
+
+        for element in self.config.keys():
+            value = self.config[element]
+            if value is None:
+                continue
+            env[element] = TclStep.value_to_tcl(value)
+
+        for input in self.inputs:
+            key = f"CURRENT_{input.name}"
+            env[key] = TclStep.value_to_tcl(state[input])
+
+        for output in self.outputs:
+            if output.value.multiple:
+                # Too step-specific.
+                continue
+            filename = f"{self.config['DESIGN_NAME']}.{output.value.extension}"
+            env[f"SAVE_{output.name}"] = os.path.join(self.step_dir, filename)
+
+        return env
+
+    @protected
+    def run(self, state_in: State, **kwargs) -> Tuple[ViewsUpdate, MetricsUpdate]:
+        """
+        This overridden :meth:`run` function prepares configuration variables and
+        inputs for use with Tcl: specifically, it converts them all to
+        environment variables so they may be used by the Tcl scripts being called.
+        See :meth:`prepare_env` for more info.
+
+        Additionally, it logs the output to a ``.log`` file named after the script.
+
+        When overriding in a subclass, you may find it useful to use this pattern:
+
+        .. code-block:: python
+
+            kwargs, env = self.extract_env(kwargs)
+            env["CUSTOM_ENV_VARIABLE"] = "1"
+            return super().run(state_in, env=env, **kwargs)
+
+        This will allow you to add further custom environment variables to a call
+        while still respecting an ``env`` argument further up the call-stack.
+
+        :param state_in: See superclass.
+        :param \\*\\*kwargs: Passed on to subprocess execution: useful if you want to
+            redirect stdin, stdout, etc.
+        :returns: see superclass
+        """
+        command = self.get_command()
+
+        kwargs, env = self.extract_env(kwargs)
+
+        env = self.prepare_env(env, state_in)
+
+        subprocess_result = self.run_subprocess(
+            command,
+            env=env,
+            **kwargs,
+        )
+
+        overrides: ViewsUpdate = {}
+        for output in self.outputs:
+            if output.value.multiple:
+                # Too step-specific.
+                continue
+            path = Path(env[f"SAVE_{output.name}"])
+            if not path.exists():
+                continue
+            overrides[output] = path
+
+        return overrides, subprocess_result["generated_metrics"]
+
+    def _reroute_env(
+        self,
+        env: Dict[str, str],
+        report_dir: Optional[Union[str, os.PathLike]] = None,
+    ):
+        thread_postfix = f"_{threading.current_thread().name}"
+        if threading.current_thread() is threading.main_thread():
+            thread_postfix = ""
+
+        env_in_dir = report_dir or self.step_dir
+        env_in_file = os.path.join(env_in_dir, f"_env{thread_postfix}.tcl")
+
+        ENV_ALLOWLIST = [
+            "PATH",
+            "PYTHONPATH",
+            "SCRIPTS_DIR",
+            "DESIGN_DIR",
+            "STEP_DIR",
+            "PDK_ROOT",
+            "PDK",
+            "_TCL_ENV_IN",
+        ]
+        env_in: List[Tuple[str, str]] = list(env.items())
+
+        # Create new "blank" env dict
+        #
+        # For all values:
+        # If a value is unchanged: keep as is
+        # If a value is changed and is in ENV_ALLOWLIST: emplace in dict
+        # If a value is changed and is not in ENV_ALLOWLIST: write to file
+        #
+        # Emplace file to be sourced in dict with key ``_TCL_ENV_IN``
+        env = os.environ.copy()
+        with open(env_in_file, "a+") as f:
+            for key, value in env_in:
+                if key in env and env[key] == value:
+                    continue
+                if key in ENV_ALLOWLIST or key.startswith("_"):
+                    env[key] = value
+                else:
+                    f.write(
+                        f"set ::env({key}) {TclUtils.escape(TclStep.value_to_tcl(value))}\n"
+                    )
+        env["_TCL_ENV_IN"] = env_in_file
+        return env
+
+    @protected
+    def run_subprocess(
+        self,
+        cmd: Sequence[Union[str, os.PathLike]],
+        log_to: Optional[Union[str, os.PathLike]] = None,
+        silent: bool = False,
+        report_dir: Optional[Union[str, os.PathLike]] = None,
+        env: Optional[Dict[str, str]] = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        if env is not None:
+            env = self._reroute_env(env, report_dir=report_dir)
+        return super().run_subprocess(
+            cmd=cmd,
+            log_to=log_to,
+            silent=silent,
+            report_dir=report_dir,
+            env=env,
+            **kwargs,
+        )

librelane/steps/verilator.py

@@ -0,0 +1,222 @@
+# Copyright 2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+import re
+from typing import List, Optional, Set, Tuple
+
+from .step import Step, StepException, ViewsUpdate, MetricsUpdate
+from ..config import Variable
+from ..state import DesignFormat, State
+from ..common import Path
+
+
+@Step.factory.register()
+class Lint(Step):
+    """
+    Lints inputs RTL Verilog files.
+
+    The linting is done with the defines for power and ground inputs on, as more
+    macros are available with powered netlists than unpowered netlists.
+    """
+
+    id = "Verilator.Lint"
+    name = "Verilator Lint"
+    long_name = "Verilator Lint"
+    inputs = []  # The input RTL is part of the configuration
+    outputs = []
+
+    config_vars = [
+        Variable(
+            "VERILOG_FILES",
+            List[Path],
+            "The paths of the design's Verilog files.",
+        ),
+        Variable(
+            "VERILOG_INCLUDE_DIRS",
+            Optional[List[Path]],
+            "Specifies the Verilog `include` directories.",
+        ),
+        Variable(
+            "VERILOG_POWER_DEFINE",
+            Optional[str],
+            "Specifies the name of the define used to guard power and ground connections in the input RTL.",
+            deprecated_names=["SYNTH_USE_PG_PINS_DEFINES", "SYNTH_POWER_DEFINE"],
+            default="USE_POWER_PINS",
+        ),
+        Variable(
+            "LINTER_INCLUDE_PDK_MODELS",
+            bool,
+            "Include Verilog models of the PDK",
+            default=False,
+        ),
+        Variable(
+            "LINTER_RELATIVE_INCLUDES",
+            bool,
+            "When a file references an include file, resolve the filename relative to the path of the referencing file, instead of relative to the current directory.",
+            default=True,
+            deprecated_names=["VERILATOR_RELATIVE_INCLUDES"],
+        ),
+        Variable(
+            "LINTER_ERROR_ON_LATCH",
+            bool,
+            "When a latch is inferred by an `always` block that is not explicitly marked as `always_latch`, report this as a linter error.",
+            default=True,
+        ),
+        Variable(
+            "VERILOG_DEFINES",
+            Optional[List[str]],
+            "Preprocessor defines for input Verilog files",
+            deprecated_names=["SYNTH_DEFINES"],
+        ),
+        Variable(
+            "LINTER_DEFINES",
+            Optional[List[str]],
+            "Linter-specific preprocessor definitions; overrides VERILOG_DEFINES for the lint step if exists",
+        ),
+    ]
+
+    def run(self, state_in: State, **kwargs) -> Tuple[ViewsUpdate, MetricsUpdate]:
+        kwargs, env = self.extract_env(kwargs)
+        views_updates: ViewsUpdate = {}
+        metrics_updates: MetricsUpdate = {}
+        extra_args = []
+
+        blackboxes = []
+
+        model_list: List[str] = []
+        model_set: Set[str] = set()
+
+        if cell_verilog_models := self.config["CELL_VERILOG_MODELS"]:
+            blackboxes.append(
+                self.toolbox.create_blackbox_model(
+                    frozenset(cell_verilog_models),
+                    frozenset(["USE_POWER_PINS"]),
+                )
+            )
+
+        macro_views = self.toolbox.get_macro_views_by_priority(
+            self.config,
+            [
+                DesignFormat.VERILOG_HEADER,
+                DesignFormat.POWERED_NETLIST,
+                DesignFormat.NETLIST,
+            ],
+        )
+        for view, format in macro_views:
+            if format == DesignFormat.VERILOG_HEADER:
+                blackboxes.append(str(view))
+            else:
+                str_view = str(view)
+                if str_view not in model_set:
+                    model_set.add(str_view)
+                    model_list.append(str_view)
+
+        if extra_verilog_models := self.config["EXTRA_VERILOG_MODELS"]:
+            for model in extra_verilog_models:
+                str_model = str(model)
+                if str_model not in model_set:
+                    model_set.add(str_model)
+                    model_list.append(str_model)
+        defines = [
+            f"PDK_{self.config['PDK']}",
+            f"SCL_{self.config['STD_CELL_LIBRARY']}",
+            "__librelane__",
+            "__pnr__",
+        ]
+        if verilog_power_define := self.config.get("VERILOG_POWER_DEFINE"):
+            defines += [verilog_power_define]
+
+        defines += self.config["LINTER_DEFINES"] or self.config["VERILOG_DEFINES"] or []
+
+        if len(model_list):
+            bb_path = self.toolbox.create_blackbox_model(
+                tuple(model_list),
+                frozenset(defines),
+            )
+            blackboxes.append(bb_path)
+
+        vlt_file = os.path.join(self.step_dir, "_deps.vlt")
+        with open(vlt_file, "w") as f:
+            f.write("`verilator_config\n")
+            f.write("lint_off -rule DECLFILENAME\n")
+            f.write("lint_off -rule EOFNEWLINE\n")
+            for blackbox in blackboxes:
+                f.write(f'lint_off -rule UNDRIVEN -file "{blackbox}"\n')
+                f.write(f'lint_off -rule UNUSEDSIGNAL -file "{blackbox}"\n')
+
+        extra_args.append("--Wno-fatal")
+
+        if self.config["LINTER_RELATIVE_INCLUDES"]:
+            extra_args.append("--relative-includes")
+
+        if self.config["LINTER_ERROR_ON_LATCH"]:
+            extra_args.append("--Werror-LATCH")
+
+        if include_dirs := self.config["VERILOG_INCLUDE_DIRS"]:
+            extra_args.extend([f"-I{dir}" for dir in include_dirs])
+
+        for define in defines:
+            extra_args.append(f"+define+{define}")
+
+        result = self.run_subprocess(
+            [
+                "verilator",
+                "--lint-only",
+                "--Wall",
+                "--Wno-DECLFILENAME",
+                "--Wno-EOFNEWLINE",
+                "--top-module",
+                self.config["DESIGN_NAME"],
+                vlt_file,
+            ]
+            + blackboxes
+            + self.config["VERILOG_FILES"]
+            + extra_args,
+            env=env,
+            check=False,
+        )
+
+        warnings_count = 0
+        errors_count = 0
+        latch_count = 0
+        timing_constructs = 0
+
+        exiting_rx = re.compile(r"^\s*%Error: Exiting due to (\d+) error\(s\)")
+        with open(self.get_log_path(), "r", encoding="utf8") as f:
+            for line in f:
+                line = line.strip()
+                if r"%Warning-" in line:
+                    warnings_count += 1
+                if r"%Error-LATCH" in line or r"%Warning-LATCH" in line:
+                    latch_count += 1
+                if r"%Error-NEEDTIMINGOPT" in line:
+                    timing_constructs += 1
+                if match := exiting_rx.search(line):
+                    errors_count = int(match[1])
+
+            if result["returncode"] != 0 and errors_count == 0:
+                raise StepException(
+                    f"Verilator exited unexpectedly with return code {result['returncode']}"
+                )
+
+        metrics_updates.update({"design__lint_error__count": errors_count})
+        metrics_updates.update(
+            {"design__lint_timing_construct__count": timing_constructs}
+        )
+        metrics_updates.update({"design__lint_warning__count": warnings_count})
+        metrics_updates.update({"design__inferred_latch__count": latch_count})
+        return views_updates, metrics_updates
+
+    def layout_preview(self) -> Optional[str]:
+        return None