cocotb 1.8.1__cp312-cp312-win32.whl → 1.9.0rc2__cp312-cp312-win32.whl

cocotb/runner.py

@@ -6,7 +6,7 @@
 
 # TODO: maybe do globbing and expanduser/expandvars in --include, --vhdl-sources, --verilog-sources
 # TODO: create a short README and a .gitignore (content: "*") in both build_dir and test_dir? (Some other tools do this.)
-# TODO: support timescale
+# TODO: support timescale on all simulators
 # TODO: support custom dependencies
 
 import abc
@@ -20,8 +20,8 @@ import tempfile
 import warnings
 from contextlib import suppress
 from pathlib import Path
-from typing import Dict, List, Mapping, Optional, Sequence, Tuple, Type, Union
-from xml.etree import cElementTree as ET
+from typing import Dict, List, Mapping, Optional, Sequence, TextIO, Tuple, Type, Union
+from xml.etree import ElementTree as ET
 
 import find_libpython
 
@@ -29,6 +29,7 @@ import cocotb.config
 
 PathLike = Union["os.PathLike[str]", str]
 Command = List[str]
+Timescale = Tuple[str, str]
 
 warnings.warn(
     "Python runners and associated APIs are an experimental feature and subject to change.",
@@ -59,6 +60,14 @@ def shlex_join(split_command):
     return " ".join(shlex.quote(arg) for arg in split_command)
 
 
+class VHDL(str):
+    """Tags source files and build arguments to :meth:`~cocotb.runner.Simulator.build` as VHDL-specific."""
+
+
+class Verilog(str):
+    """Tags source files and build arguments to :meth:`~cocotb.runner.Simulator.build` as Verilog-specific."""
+
+
 class Simulator(abc.ABC):
 
     supported_gpi_interfaces: Dict[str, List[str]] = {}
@@ -93,10 +102,17 @@ class Simulator(abc.ABC):
             ValueError: *hdl_toplevel_lang* is not supported by the simulator.
         """
         if hdl_toplevel_lang is None:
-            if self.vhdl_sources and not self.verilog_sources:
+            if self.vhdl_sources and not self.verilog_sources and not self.sources:
                 lang = "vhdl"
-            elif self.verilog_sources and not self.vhdl_sources:
+            elif self.verilog_sources and not self.vhdl_sources and not self.sources:
                 lang = "verilog"
+            elif self.sources and not self.vhdl_sources and not self.verilog_sources:
+                if is_vhdl_source(self.sources[-1]):
+                    lang = "vhdl"
+                elif is_verilog_source(self.sources[-1]):
+                    lang = "verilog"
+                else:
+                    raise UnknownFileExtension(self.sources[-1])
             else:
                 raise ValueError(
                     f"{type(self).__qualname__}: Must specify a hdl_toplevel_lang in a mixed-language design"
@@ -119,7 +135,12 @@ class Simulator(abc.ABC):
             self.env[e] = os.environ[e]
 
         if "LIBPYTHON_LOC" not in self.env:
-            self.env["LIBPYTHON_LOC"] = find_libpython.find_libpython()
+            libpython_path = find_libpython.find_libpython()
+            if not libpython_path:
+                raise ValueError(
+                    "Unable to find libpython, please make sure the appropriate libpython is installed"
+                )
+            self.env["LIBPYTHON_LOC"] = libpython_path
 
         self.env["PATH"] += os.pathsep + cocotb.config.libs_dir
         self.env["PYTHONPATH"] = os.pathsep.join(sys.path)
@@ -144,21 +165,58 @@ class Simulator(abc.ABC):
         hdl_library: str = "top",
         verilog_sources: Sequence[PathLike] = [],
         vhdl_sources: Sequence[PathLike] = [],
+        sources: Sequence[Union[PathLike, VHDL, Verilog]] = [],
         includes: Sequence[PathLike] = [],
         defines: Mapping[str, object] = {},
         parameters: Mapping[str, object] = {},
-        build_args: Sequence[str] = [],
+        build_args: Sequence[Union[str, VHDL, Verilog]] = [],
         hdl_toplevel: Optional[str] = None,
         always: bool = False,
         build_dir: PathLike = "sim_build",
+        clean: bool = False,
         verbose: bool = False,
+        timescale: Optional[Timescale] = None,
+        waves: Optional[bool] = None,
+        log_file: Optional[PathLike] = None,
     ) -> None:
         """Build the HDL sources.
 
+        With mixed language simulators, *sources* will be built,
+        followed by *vhdl_sources*, then *verilog_sources*.
+        With simulators that only support either VHDL or Verilog, *sources* will be built,
+        followed by *vhdl_sources* and *verilog_sources*, respectively.
+
+        If your source files use an atypical file extension,
+        use :class:`VHDL` and :class:`Verilog` to tag the path as a VHDL or Verilog source file, respectively.
+        If the filepaths aren't tagged, the extension is used to determine if they are VHDL or Verilog files.
+
+        +----------+------------------------------------+
+        | Language | File Extensions                    |
+        +==========+====================================+
+        | VHDL     | ``.vhd``, ``.vhdl``                |
+        +----------+------------------------------------+
+        | Verilog  | ``.v``, ``.sv``, ``.vh``, ``.svh`` |
+        +----------+------------------------------------+
+
+
+        .. code-block:: python3
+
+            runner.build(
+                sources=[
+                    VHDL("/my/file.is_actually_vhdl"),
+                    Verilog("/other/file.verilog"),
+                ],
+            )
+
+        The same tagging works for *build_args*.
+        Tagged *build_args* only supply that option to the compiler when building the source file for the tagged language.
+        Non-tagged *build_args* are supplied when compiling any language.
+
         Args:
             hdl_library: The library name to compile into.
             verilog_sources: Verilog source files to build.
             vhdl_sources: VHDL source files to build.
+            sources: Language-agnostic list of source files to build.
             includes: Verilog include directories.
             defines: Defines to set.
             parameters: Verilog parameters or VHDL generics.
@@ -166,10 +224,17 @@ class Simulator(abc.ABC):
             hdl_toplevel: The name of the HDL toplevel module.
             always: Always run the build step.
             build_dir: Directory to run the build step in.
+            clean: Delete build_dir before building
             verbose: Enable verbose messages.
+            timescale: Tuple containing time unit and time precision for simulation.
+            waves: Record signal traces.
+            log_file: File to write the build log to.
         """
 
+        self.clean: bool = clean
         self.build_dir = get_abs_path(build_dir)
+        if self.clean:
+            self.rm_build_folder(self.build_dir)
         os.makedirs(self.build_dir, exist_ok=True)
 
         # note: to avoid mutating argument defaults, we ensure that no value
@@ -179,6 +244,7 @@ class Simulator(abc.ABC):
         self.hdl_library: str = hdl_library
         self.verilog_sources: List[Path] = get_abs_paths(verilog_sources)
         self.vhdl_sources: List[Path] = get_abs_paths(vhdl_sources)
+        self.sources: List[Path] = get_abs_paths(sources)
         self.includes: List[Path] = get_abs_paths(includes)
         self.defines = dict(defines)
         self.parameters = dict(parameters)
@@ -186,6 +252,10 @@ class Simulator(abc.ABC):
         self.always: bool = always
         self.hdl_toplevel: Optional[str] = hdl_toplevel
         self.verbose: bool = verbose
+        self.timescale: Optional[Timescale] = timescale
+        self.log_file: Optional[PathLike] = log_file
+
+        self.waves = bool(waves)
 
         for e in os.environ:
             self.env[e] = os.environ[e]
@@ -210,8 +280,11 @@ class Simulator(abc.ABC):
         parameters: Mapping[str, object] = None,
         build_dir: Optional[PathLike] = None,
         test_dir: Optional[PathLike] = None,
-        results_xml: str = "results.xml",
+        results_xml: Optional[str] = None,
+        pre_cmd: List[str] = [],
         verbose: bool = False,
+        timescale: Optional[Timescale] = None,
+        log_file: Optional[PathLike] = None,
     ) -> Path:
         """Run the tests.
 
@@ -235,15 +308,17 @@ class Simulator(abc.ABC):
             build_dir: Directory the build step has been run in.
             test_dir: Directory to run the tests in.
             results_xml: Name of xUnit XML file to store test results in.
-                When running with pytest, the testcase name is prefixed to this name.
+                If an absolute path is provided it will be used as-is,
+                ``{build_dir}/results.xml`` otherwise.
+                This argument should not be set when run with ``pytest``.
             verbose: Enable verbose messages.
+            pre_cmd: Commands to run before simulation begins.
+            timescale: Tuple containing time unit and time precision for simulation.
+            log_file: File to write the test log to.
 
         Returns:
             The absolute location of the results XML file which can be
             defined by the *results_xml* argument.
-            The default is :file:`{build_dir}/{pytest_test_name}.results.xml`
-            when run with ``pytest``,
-            :file:`{build_dir}/results.xml` otherwise.
         """
 
         __tracebackhide__ = True  # Hide the traceback when using pytest
@@ -279,6 +354,8 @@ class Simulator(abc.ABC):
             for gpi_if in self.supported_gpi_interfaces.values():
                 self.gpi_interfaces.append(gpi_if[0])
 
+        self.pre_cmd = pre_cmd
+
         self.test_args = list(test_args)
         self.plusargs = list(plusargs)
         self.env = dict(extra_env)
@@ -292,22 +369,31 @@ class Simulator(abc.ABC):
         if seed is not None:
             self.env["RANDOM_SEED"] = str(seed)
 
+        self.log_file = log_file
         self.waves = bool(waves)
         self.gui = bool(gui)
+        self.timescale: Optional[Timescale] = timescale
 
         if verbose is not None:
             self.verbose = verbose
 
         # When using pytest, use test name as result file name
-        pytest_current_test = os.getenv("PYTEST_CURRENT_TEST", "")
-        if pytest_current_test:
+        pytest_current_test = os.getenv("PYTEST_CURRENT_TEST", None)
+        test_dir_path = Path(self.test_dir)
+        self.current_test_name = "test"
+        if results_xml is not None:
+            # PYTEST_CURRENT_TEST only allowed when results_xml is not set
+            assert not pytest_current_test
+            results_xml_path = Path(results_xml)
+            if results_xml_path.is_absolute():
+                results_xml_file = results_xml_path
+            else:
+                results_xml_file = test_dir_path / results_xml_path
+        elif pytest_current_test is not None:
             self.current_test_name = pytest_current_test.split(":")[-1].split(" ")[0]
-            results_xml_name = f"{self.current_test_name}.{results_xml}"
+            results_xml_file = test_dir_path / f"{self.current_test_name}.{results_xml}"
         else:
-            self.current_test_name = "test"
-            results_xml_name = results_xml
-
-        results_xml_file = Path(self.test_dir) / results_xml_name
+            results_xml_file = test_dir_path / "results.xml"
 
         with suppress(OSError):
             os.remove(results_xml_file)
@@ -350,19 +436,38 @@ class Simulator(abc.ABC):
 
         __tracebackhide__ = True  # Hide the traceback when using PyTest.
 
+        if self.log_file is None:
+            self._execute_cmds(cmds, cwd)
+        else:
+            with open(self.log_file, "w") as f:
+                self._execute_cmds(cmds, cwd, f)
+
+    def _execute_cmds(
+        self, cmds: Sequence[Command], cwd: PathLike, stdout: Optional[TextIO] = None
+    ) -> None:
+        __tracebackhide__ = True  # Hide the traceback when using PyTest.
+
         for cmd in cmds:
             print(f"INFO: Running command {shlex_join(cmd)} in directory {cwd}")
 
             # TODO: create a thread to handle stderr and log as error?
             # TODO: log forwarding
 
-            process = subprocess.run(cmd, cwd=cwd, env=self.env)
+            stderr = None if stdout is None else subprocess.STDOUT
+            process = subprocess.run(
+                cmd, cwd=cwd, env=self.env, stdout=stdout, stderr=stderr
+            )
 
             if process.returncode != 0:
                 raise SystemExit(
                     f"Process {process.args[0]!r} terminated with error {process.returncode}"
                 )
 
+    def rm_build_folder(self, build_dir: Path):
+        if os.path.isdir(build_dir):
+            print("Removing:", build_dir)
+            shutil.rmtree(build_dir, ignore_errors=True)
+
 
 def get_results(results_xml_file: Path) -> Tuple[int, int]:
     """Return number of tests and fails in *results_xml_file*.
@@ -446,6 +551,40 @@ def get_abs_paths(paths: Sequence[PathLike]) -> List[Path]:
     return [get_abs_path(path) for path in paths]
 
 
+_verilog_extensions = (".v", ".sv", ".vh", ".svh")
+_vhdl_extensions = (".vhd", ".vhdl")
+
+_vhdl_extensions_s = ", ".join(f"`{c}`" for c in _vhdl_extensions)
+_verilog_extensions_s = ", ".join(f"`{c}`" for c in _verilog_extensions)
+
+
+class UnknownFileExtension(ValueError):
+    def __init__(self, source: PathLike) -> None:
+        super().__init__(
+            f"Can't determine if {source} is a VHDL or Verilog file. "
+            f"Use a standard file extension ({_vhdl_extensions_s} for VHDL files and {_verilog_extensions_s} for Verilog files) "
+            "or tag the source with `VHDL(source)` or `Verilog(source)`."
+        )
+
+
+def is_vhdl_source(source: PathLike) -> bool:
+    if isinstance(source, VHDL):
+        return True
+    source_as_path = Path(source)
+    if source_as_path.suffix in _vhdl_extensions:
+        return True
+    return False
+
+
+def is_verilog_source(source: PathLike) -> bool:
+    if isinstance(source, Verilog):
+        return True
+    source_as_path = Path(source)
+    if source_as_path.suffix in _verilog_extensions:
+        return True
+    return False
+
+
 class Icarus(Simulator):
     supported_gpi_interfaces = {"verilog": ["vpi"]}
 
@@ -469,11 +608,39 @@ class Icarus(Simulator):
             for name, value in parameters.items()
         ]
 
+    def _create_cmd_file(self) -> None:
+        with open(self.cmds_file, "w") as f:
+            f.write("+timescale+{}/{}\n".format(*self.timescale))
+
+    def _create_iverilog_dump_file(self) -> None:
+        dumpfile_path = Path(self.build_dir, f"{self.hdl_toplevel}.fst").as_posix()
+        with open(self.iverilog_dump_file, "w") as f:
+            f.write("module cocotb_iverilog_dump();\n")
+            f.write("initial begin\n")
+            f.write(f'    $dumpfile("{dumpfile_path}");\n')
+            f.write(f"    $dumpvars(0, {self.hdl_toplevel});\n")
+            f.write("end\n")
+            f.write("endmodule\n")
+
     @property
     def sim_file(self) -> Path:
         return self.build_dir / "sim.vvp"
 
+    @property
+    def iverilog_dump_file(self) -> Path:
+        return self.build_dir / "cocotb_iverilog_dump.v"
+
+    @property
+    def cmds_file(self) -> Path:
+        return self.build_dir / "cmds.f"
+
     def _test_command(self) -> List[Command]:
+        plusargs = self.plusargs
+        if self.waves:
+            plusargs += ["-fst"]
+
+        if self.pre_cmd:
+            print("WARNING: pre_cmd is not implemented for Icarus Verilog.")
 
         return [
             [
@@ -485,26 +652,56 @@ class Icarus(Simulator):
             ]
             + self.test_args
             + [str(self.sim_file)]
-            + self.plusargs
+            + plusargs
         ]
 
     def _build_command(self) -> List[Command]:
+        for source in self.sources:
+            if not is_verilog_source(source):
+                raise ValueError(
+                    f"{type(self).__qualname__} only supports Verilog. {str(source)!r} cannot be compiled."
+                )
+        for arg in self.build_args:
+            if type(arg) not in (str, Verilog):
+                print(
+                    f"WARNING: {type(self).__qualname__} only supports Verilog. build_args {arg!r} will not be applied."
+                )
 
-        if self.vhdl_sources:
-            raise ValueError(
-                f"{type(self).__qualname__}: Simulator does not support VHDL"
-            )
+        build_args = list(self.build_args)
+        if self.waves:
+            self._create_iverilog_dump_file()
+            build_args += ["-s", "cocotb_iverilog_dump"]
 
-        cmds = []
-        if outdated(self.sim_file, self.verilog_sources) or self.always:
+        if self.timescale is not None:
+            self._create_cmd_file()
+            build_args += ["-f", str(self.cmds_file)]
 
+        cmds = []
+        sources = [
+            source for source in self.sources if is_verilog_source(source)
+        ] + self.verilog_sources
+        if outdated(self.sim_file, sources) or self.always:
             cmds = [
-                ["iverilog", "-o", str(self.sim_file), "-D", "COCOTB_SIM=1", "-g2012"]
+                [
+                    "iverilog",
+                    "-o",
+                    str(self.sim_file),
+                    "-D",
+                    "COCOTB_SIM=1",
+                    "-s",
+                    self.hdl_toplevel,
+                    "-g2012",
+                ]
                 + self._get_define_options(self.defines)
                 + self._get_include_options(self.includes)
                 + self._get_parameter_options(self.parameters)
-                + self.build_args
-                + [str(source_file) for source_file in self.verilog_sources]
+                + [arg for arg in build_args if type(arg) in (str, Verilog)]
+                + [str(source_file) for source_file in sources]
+                + [
+                    str(source_file)
+                    for source_file in [self.iverilog_dump_file]
+                    if self.waves
+                ]
             ]
 
         else:
@@ -540,35 +737,48 @@ class Questa(Simulator):
 
         cmds = []
 
-        if self.vhdl_sources:
-            cmds.append(["vlib", as_tcl_value(self.hdl_library)])
-            cmds.append(
-                ["vcom"]
-                + ["-work", as_tcl_value(self.hdl_library)]
-                + [as_tcl_value(v) for v in self.build_args]
-                + [as_tcl_value(str(v)) for v in self.vhdl_sources]
-            )
-
-        if self.verilog_sources:
-            cmds.append(["vlib", as_tcl_value(self.hdl_library)])
-            cmds.append(
-                ["vlog"]
-                + ([] if self.always else ["-incr"])
-                + ["-work", as_tcl_value(self.hdl_library)]
-                + ["+define+COCOTB_SIM"]
-                + ["-sv"]
-                + self._get_define_options(self.defines)
-                + self._get_include_options(self.includes)
-                + [as_tcl_value(v) for v in self.build_args]
-                + [as_tcl_value(str(v)) for v in self.verilog_sources]
-            )
+        cmds.append(["vlib", as_tcl_value(self.hdl_library)])
+        for source in self.sources:
+            if is_vhdl_source(source):
+                cmds.append(self._build_vhdl_command(source))
+            elif is_verilog_source(source):
+                cmds.append(self._build_verilog_command(source))
+            else:
+                raise UnknownFileExtension(source)
+        for source in self.vhdl_sources:
+            cmds.append(self._build_vhdl_command(source))
+        for source in self.verilog_sources:
+            cmds.append(self._build_verilog_command(source))
 
         return cmds
 
+    def _build_vhdl_command(self, source: PathLike) -> Command:
+        return (
+            ["vcom"]
+            + ["-work", as_tcl_value(self.hdl_library)]
+            + [as_tcl_value(v) for v in self.build_args if type(v) in (str, VHDL)]
+            + [as_tcl_value(str(source))]
+        )
+
+    def _build_verilog_command(self, source: PathLike) -> Command:
+        return (
+            ["vlog"]
+            + ([] if self.always else ["-incr"])
+            + ["-work", as_tcl_value(self.hdl_library)]
+            + ["-sv"]
+            + self._get_define_options(self.defines)
+            + self._get_include_options(self.includes)
+            + [as_tcl_value(v) for v in self.build_args if type(v) in (str, Verilog)]
+            + [as_tcl_value(str(source))]
+        )
+
     def _test_command(self) -> List[Command]:
 
         cmds = []
 
+        if self.pre_cmd:
+            self.pre_cmd = ["-do"] + self.pre_cmd
+
         do_script = ""
         if self.waves:
             do_script += "log -recursive /*;"
@@ -577,8 +787,6 @@ class Questa(Simulator):
             do_script += "run -all; quit"
 
         gpi_if_entry = self.gpi_interfaces[0]
-        gpi_if_entry_lib_path = cocotb.config.lib_name_path(gpi_if_entry, "questa")
-
         if gpi_if_entry == "fli":
             lib_opts = [
                 "-foreign",
@@ -598,11 +806,6 @@ class Questa(Simulator):
                 as_tcl_value(cocotb.config.lib_name_path("vpi", "questa")),
             ]
 
-        if not Path(gpi_if_entry_lib_path).is_file():
-            raise SystemExit(
-                "ERROR: cocotb was not installed with a {gpi_if_entry} library."
-            )
-
         cmds.append(
             ["vsim"]
             + ["-gui" if self.gui else "-c"]
@@ -612,6 +815,7 @@ class Questa(Simulator):
             + [as_tcl_value(v) for v in self._get_parameter_options(self.parameters)]
             + [as_tcl_value(f"{self.hdl_toplevel_library}.{self.sim_hdl_toplevel}")]
             + [as_tcl_value(v) for v in self.plusargs]
+            + self.pre_cmd
             + ["-do", do_script]
         )
 
@@ -638,22 +842,39 @@ class Ghdl(Simulator):
         if shutil.which("ghdl") is None:
             raise SystemExit("ERROR: ghdl executable not found!")
 
+    def _is_mcode_backend(self) -> bool:
+        """Is GHDL using the mcode backend?"""
+        result = subprocess.run(
+            ["ghdl", "--version"],
+            check=True,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+        )
+        return "mcode" in result.stdout
+
     @staticmethod
     def _get_parameter_options(parameters: Mapping[str, object]) -> Command:
         return [f"-g{name}={value}" for name, value in parameters.items()]
 
     def _build_command(self) -> List[Command]:
-
-        if self.verilog_sources:
-            raise ValueError(
-                f"{type(self).__qualname__}: Simulator does not support Verilog"
-            )
+        for source in self.sources:
+            if not is_vhdl_source(source):
+                raise ValueError(
+                    f"{type(self).__qualname__} only supports VHDL. {str(source)!r} cannot be compiled."
+                )
+        for arg in self.build_args:
+            if type(arg) not in (str, VHDL):
+                print(
+                    f"WARNING: {type(self).__qualname__} only supports VHDL. build_args {arg!r} will not be applied."
+                )
 
         cmds = [
             ["ghdl", "-i"]
             + [f"--work={self.hdl_library}"]
-            + self.build_args
-            + [str(source_file) for source_file in self.vhdl_sources]
+            + [arg for arg in self.build_args if type(arg) in (str, VHDL)]
+            + [str(source) for source in self.sources if is_vhdl_source(source)]
+            + [str(source) for source in self.vhdl_sources]
         ]
 
         if self.hdl_toplevel is not None:
@@ -667,11 +888,42 @@ class Ghdl(Simulator):
         return cmds
 
     def _test_command(self) -> List[Command]:
+        if self.pre_cmd:
+            print("WARNING: pre_cmd is not implemented for GHDL.")
+
+        ghdl_run_args = self.test_args
+
+        if self._is_mcode_backend() and self.timescale:
+            _, precision = self.timescale
+            # Convert the time precision to a format string supported by GHDL,
+            # if possible.
+            # GHDL only supports setting the time precision if the mcode backend
+            # is used, using the --time-resolution argument causes GHDL to error
+            # out otherwise.
+            # https://ghdl.github.io/ghdl/using/InvokingGHDL.html#cmdoption-ghdl-time-resolution
+            if precision == "1fs":
+                ghdl_time_resolution = "fs"
+            elif precision == "1ps":
+                ghdl_time_resolution = "ps"
+            elif precision == "1ns":
+                ghdl_time_resolution = "ns"
+            elif precision == "1us":
+                ghdl_time_resolution = "us"
+            elif precision == "1ms":
+                ghdl_time_resolution = "ms"
+            elif precision == "1s":
+                ghdl_time_resolution = "sec"
+            else:
+                raise ValueError(
+                    "GHDL only supports the following precisions in timescale: 1fs, 1ps, 1us, 1ms, 1s"
+                )
+
+            ghdl_run_args.append(f"--time-resolution={ghdl_time_resolution}")
 
         cmds = [
             ["ghdl", "-r"]
             + [f"--work={self.hdl_toplevel_library}"]
-            + self.test_args
+            + ghdl_run_args
             + [self.sim_hdl_toplevel]
             + ["--vpi=" + cocotb.config.lib_name_path("vpi", "ghdl")]
             + self.plusargs
@@ -681,6 +933,55 @@ class Ghdl(Simulator):
         return cmds
 
 
+class Nvc(Simulator):
+    supported_gpi_interfaces = {"vhdl": ["vhpi"]}
+
+    @staticmethod
+    def _simulator_in_path() -> None:
+        if shutil.which("nvc") is None:
+            raise SystemExit("ERROR: nvc executable not found!")
+
+    @staticmethod
+    def _get_parameter_options(parameters: Mapping[str, object]) -> Command:
+        return [f"-g{name}={value}" for name, value in parameters.items()]
+
+    def _build_command(self) -> List[Command]:
+        for source in self.sources:
+            if not is_vhdl_source(source):
+                raise ValueError(
+                    f"{type(self).__qualname__} only supports VHDL. {str(source)!r} cannot be compiled."
+                )
+        for arg in self.build_args:
+            if type(arg) not in (str, VHDL):
+                print(
+                    f"WARNING: {type(self).__qualname__} only supports VHDL. build_args {arg!r} will not be applied."
+                )
+
+        cmds = [
+            ["nvc", f"--work={self.hdl_library}"]
+            + [arg for arg in self.build_args if type(arg) in (str, VHDL)]
+            + ["-a"]
+            + [str(source) for source in self.sources if is_vhdl_source(source)]
+            + [str(source) for source in self.vhdl_sources]
+        ]
+
+        return cmds
+
+    def _test_command(self) -> List[Command]:
+        cmds = [
+            ["nvc", f"--work={self.hdl_toplevel_library}"]
+            + self.build_args
+            + ["-e", self.sim_hdl_toplevel, "--no-save", "--jit"]
+            + self._get_parameter_options(self.parameters)
+            + ["-r"]
+            + self.test_args
+            + ["--load=" + cocotb.config.lib_name_path("vhpi", "nvc")]
+            + self.plusargs
+        ]
+
+        return cmds
+
+
 class Riviera(Simulator):
     supported_gpi_interfaces = {"verilog": ["vpi"], "vhdl": ["vhpi"]}
 
@@ -705,53 +1006,67 @@ class Riviera(Simulator):
         return [f"-g{name}={value}" for name, value in parameters.items()]
 
     def _build_command(self) -> List[Command]:
-
-        do_script = "\nonerror {\n quit -code 1 \n} \n"
+        do_script: List[str] = ["onerror {\n quit -code 1 \n}"]
 
         out_file = self.build_dir / self.hdl_library / f"{self.hdl_library}.lib"
 
         if outdated(out_file, self.verilog_sources + self.vhdl_sources) or self.always:
-
-            do_script += "alib {RTL_LIBRARY} \n".format(
-                RTL_LIBRARY=as_tcl_value(self.hdl_library)
-            )
-
-            if self.vhdl_sources:
-                do_script += (
-                    "acom -work {RTL_LIBRARY} {EXTRA_ARGS} {VHDL_SOURCES}\n".format(
-                        RTL_LIBRARY=as_tcl_value(self.hdl_library),
-                        VHDL_SOURCES=" ".join(
-                            as_tcl_value(str(v)) for v in self.vhdl_sources
-                        ),
-                        EXTRA_ARGS=" ".join(as_tcl_value(v) for v in self.build_args),
-                    )
-                )
-
-            if self.verilog_sources:
-                do_script += "alog -work {RTL_LIBRARY} +define+COCOTB_SIM -sv {DEFINES} {INCDIR} {EXTRA_ARGS} {VERILOG_SOURCES} \n".format(
-                    RTL_LIBRARY=as_tcl_value(self.hdl_library),
-                    VERILOG_SOURCES=" ".join(
-                        as_tcl_value(str(v)) for v in self.verilog_sources
-                    ),
-                    DEFINES=" ".join(self._get_define_options(self.defines)),
-                    INCDIR=" ".join(self._get_include_options(self.includes)),
-                    EXTRA_ARGS=" ".join(as_tcl_value(v) for v in self.build_args),
-                )
-        else:
-            print("WARNING: Skipping compilation of", out_file)
+            do_script.append(f"alib {as_tcl_value(self.hdl_library)}")
+
+            for source in self.sources:
+                if is_verilog_source(source):
+                    do_script.append(self._build_verilog_source(source))
+                elif is_vhdl_source(source):
+                    do_script.append(self._build_vhdl_source(source))
+                else:
+                    raise UnknownFileExtension(source)
+            for source in self.vhdl_sources:
+                do_script.append(self._build_vhdl_source(source))
+            for source in self.verilog_sources:
+                do_script.append(self._build_verilog_source(source))
+
+        # Explicitly exit the script at the end. In batch mode, which is invoked
+        # implicitly by redirecting STDOUT/STDERR of the alog/acom commands,
+        # the tool exits by itself even without this 'exit' command -- but not
+        # when running from an interactive terminal. Be explicit for predictable
+        # behavior.
+        do_script.append("exit")
 
         do_file = tempfile.NamedTemporaryFile(delete=False)
-        do_file.write(do_script.encode())
+        do_file.write("\n".join(do_script).encode())
         do_file.close()
 
         return [["vsimsa"] + ["-do"] + ["do"] + [do_file.name]]
 
+    def _build_vhdl_source(self, source: PathLike) -> str:
+        return "acom -work {RTL_LIBRARY} {EXTRA_ARGS} {VHDL_SOURCES}".format(
+            RTL_LIBRARY=as_tcl_value(self.hdl_library),
+            VHDL_SOURCES=as_tcl_value(str(source)),
+            EXTRA_ARGS=" ".join(
+                as_tcl_value(v) for v in self.build_args if type(v) in (str, VHDL)
+            ),
+        )
+
+    def _build_verilog_source(self, source: PathLike) -> str:
+        return "alog -work {RTL_LIBRARY} -pli {EXT_NAME} -sv {DEFINES} {INCDIR} {EXTRA_ARGS} {VERILOG_SOURCES}".format(
+            RTL_LIBRARY=as_tcl_value(self.hdl_library),
+            EXT_NAME=as_tcl_value(cocotb.config.lib_name_path("vpi", "riviera")),
+            VERILOG_SOURCES=as_tcl_value(str(source)),
+            DEFINES=" ".join(self._get_define_options(self.defines)),
+            INCDIR=" ".join(self._get_include_options(self.includes)),
+            EXTRA_ARGS=" ".join(
+                as_tcl_value(v) for v in self.build_args if type(v) in (str, Verilog)
+            ),
+        )
+
     def _test_command(self) -> List[Command]:
+        if self.pre_cmd:
+            print("WARNING: pre_cmd is not implemented for Riviera.")
 
-        do_script = "\nonerror {\n quit -code 1 \n} \n"
+        do_script: str = "\nonerror {\n quit -code 1 \n} \n"
 
         if self.hdl_toplevel_lang == "vhdl":
-            do_script += "asim +access +w -interceptcoutput -O2 -loadvhpi {EXT_NAME} {EXTRA_ARGS} {TOPLEVEL} {PLUSARGS}\n".format(
+            do_script += "asim +access +w_nets -interceptcoutput -loadvhpi {EXT_NAME} {EXTRA_ARGS} {TOPLEVEL} {PLUSARGS}\n".format(
                 TOPLEVEL=as_tcl_value(
                     f"{self.hdl_toplevel_library}.{self.sim_hdl_toplevel}"
                 ),
@@ -769,7 +1084,7 @@ class Riviera(Simulator):
                 cocotb.config.lib_name_path("vpi", "riviera") + ":cocotbvpi_entry_point"
             )
         else:
-            do_script += "asim +access +w -interceptcoutput -O2 -pli {EXT_NAME} {EXTRA_ARGS} {TOPLEVEL} {PLUSARGS} \n".format(
+            do_script += "asim +access +w_nets -interceptcoutput -pli {EXT_NAME} {EXTRA_ARGS} {TOPLEVEL} {PLUSARGS} \n".format(
                 TOPLEVEL=as_tcl_value(
                     f"{self.hdl_toplevel_library}.{self.sim_hdl_toplevel}"
                 ),
@@ -804,6 +1119,10 @@ class Verilator(Simulator):
     supported_gpi_interfaces = {"verilog": ["vpi"]}
 
     def _simulator_in_path(self) -> None:
+        # the verilator binary is only needed for building
+        return
+
+    def _simulator_in_path_build_only(self) -> None:
         executable = shutil.which("verilator")
         if executable is None:
             raise SystemExit("ERROR: verilator executable not found!")
@@ -822,15 +1141,22 @@ class Verilator(Simulator):
         return [f"-G{name}={value}" for name, value in parameters.items()]
 
     def _build_command(self) -> List[Command]:
+        self._simulator_in_path_build_only()
 
-        if self.vhdl_sources:
-            raise ValueError(
-                f"{type(self).__qualname__}: Simulator does not support VHDL"
-            )
+        for source in self.sources:
+            if not is_verilog_source(source):
+                raise ValueError(
+                    f"{type(self).__qualname__} only supports Verilog. {str(source)!r} cannot be compiled."
+                )
+        for arg in self.build_args:
+            if type(arg) not in (str, Verilog):
+                print(
+                    f"WARNING: {type(self).__qualname__} only supports Verilog. build_args {arg!r} will not be applied."
+                )
 
         if self.hdl_toplevel is None:
             raise ValueError(
-                f"{type(self).__qualname__}: Simulator requires the hdl_toplevel parameter to be specified"
+                f"{type(self).__qualname__} requires the hdl_toplevel parameter to be specified"
             )
 
         # TODO: set "--debug" if self.verbose
@@ -867,21 +1193,40 @@ class Verilator(Simulator):
                     LIB_DIR=cocotb.config.libs_dir
                 ),
             ]
-            + self.build_args
+            + (["--trace"] if self.waves else [])
+            + [arg for arg in self.build_args if type(arg) in (str, Verilog)]
             + self._get_define_options(self.defines)
             + self._get_include_options(self.includes)
             + self._get_parameter_options(self.parameters)
             + [verilator_cpp]
-            + [str(source_file) for source_file in self.verilog_sources]
+            + [str(source) for source in self.sources if is_verilog_source(source)]
+            + [str(source) for source in self.verilog_sources]
         )
 
-        cmds.append(["make", "-C", str(self.build_dir), "-f", "Vtop.mk"])
+        cmds.append(
+            [
+                "make",
+                "-C",
+                str(self.build_dir),
+                "-f",
+                "Vtop.mk",
+                f"VM_TRACE={int(self.waves)}",
+            ]
+        )
 
         return cmds
 
     def _test_command(self) -> List[Command]:
+        if self.pre_cmd:
+            print("WARNING: pre_cmd is not implemented for Verilator.")
+
         out_file = self.build_dir / self.sim_hdl_toplevel
-        return [[str(out_file)] + self.plusargs]
+        return [
+            [str(out_file)]
+            + (["--trace"] if self.waves else [])
+            + self.test_args
+            + self.plusargs
+        ]
 
 
 class Xcelium(Simulator):
@@ -907,6 +1252,8 @@ class Xcelium(Simulator):
     def _build_command(self) -> List[Command]:
         self.env["CDS_AUTO_64BIT"] = "all"
 
+        assert self.hdl_toplevel, "A HDL toplevel is required in all Xcelium compiles."
+
         verbosity_opts = []
         if self.verbose:
             verbosity_opts += ["-messages"]
@@ -922,6 +1269,11 @@ class Xcelium(Simulator):
             verbosity_opts += ["-quiet"]
             verbosity_opts += ["-plinowarn"]
 
+        vhpi_opts = []
+        # Xcelium 23.09.004 fixes cocotb issue #1076 as long as the
+        # following define is set.
+        vhpi_opts.append("-NEW_VHPI_PROPAGATE_DELAY")
+
         cmds = [
             ["xrun"]
             + ["-logfile"]
@@ -940,6 +1292,7 @@ class Xcelium(Simulator):
                 cocotb.config.lib_name_path("vpi", "xcelium")
                 + ":vlog_startup_routines_bootstrap"
             ]
+            + vhpi_opts
             + [f"-work {self.hdl_library}"]
             + self.build_args
             + ["-define COCOTB_SIM"]
@@ -949,13 +1302,18 @@ class Xcelium(Simulator):
             + [f"-top {self.hdl_toplevel}"]
             + [
                 str(source_file)
-                for source_file in self.vhdl_sources + self.verilog_sources
+                for source_file in (
+                    self.sources + self.vhdl_sources + self.verilog_sources
+                )
             ]
         ]
 
         return cmds
 
     def _test_command(self) -> List[Command]:
+        if self.pre_cmd:
+            print("WARNING: pre_cmd is not implemented for Xcelium.")
+
         self.env["CDS_AUTO_64BIT"] = "all"
 
         verbosity_opts = []
@@ -980,6 +1338,21 @@ class Xcelium(Simulator):
         else:
             xrun_top = self.sim_hdl_toplevel
 
+        if self.waves:
+            input_tcl = [
+                f'-input "@database -open cocotb_waves -default" '
+                f'-input "@probe -database cocotb_waves -create {xrun_top} -all -depth all" '
+                f'-input "@run" '
+                f'-input "@exit" '
+            ]
+        else:
+            input_tcl = ["-input", "@run; exit;"]
+
+        vhpi_opts = []
+        # Xcelium 23.09.004 fixes cocotb issue #1076 as long as the
+        # following define is set.
+        vhpi_opts.append("-NEW_VHPI_PROPAGATE_DELAY")
+
         cmds = [["mkdir", "-p", tmpdir]]
         cmds += [
             ["xrun"]
@@ -990,20 +1363,13 @@ class Xcelium(Simulator):
             + ["-cds_implicit_tmpdir"]
             + [tmpdir]
             + ["-licqueue"]
+            + vhpi_opts
             + verbosity_opts
             + ["-R"]
             + self.test_args
             + self.plusargs
             + ["-gui" if self.gui else ""]
-            + ["-input"]
-            + [
-                f'-input "@database -open cocotb_waves -default" '
-                f'-input "@probe -database cocotb_waves -create {xrun_top} -all -depth all" '
-                f'-input "@run" '
-                f'-input "@exit" '
-                if self.waves
-                else "@run; exit;"
-            ]
+            + input_tcl
         ]
         self.env["GPI_EXTRA"] = (
             cocotb.config.lib_name_path("vhpi", "xcelium") + ":cocotbvhpi_entry_point"
@@ -1022,6 +1388,7 @@ def get_runner(simulator_name: str) -> Simulator:
         "riviera": Riviera,
         "verilator": Verilator,
         "xcelium": Xcelium,
+        "nvc": Nvc,
         # TODO: "vcs": Vcs,
         # TODO: "activehdl": ActiveHdl,
     }