cocotb 1.9.2__cp313-cp313-win_amd64.whl → 2.0.0b1__cp313-cp313-win_amd64.whl

cocotb/_gpi_triggers.py

@@ -0,0 +1,382 @@
+# Copyright cocotb contributors
+# Copyright (c) 2013 Potential Ventures Ltd
+# Copyright (c) 2013 SolarFlare Communications Inc
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""A collection of triggers which a testbench can :keyword:`await`."""
+
+import warnings
+from decimal import Decimal
+from fractions import Fraction
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Generic,
+    Optional,
+    TypeVar,
+    Union,
+)
+
+import cocotb
+import cocotb.handle
+from cocotb import simulator
+from cocotb._base_triggers import Trigger
+from cocotb._deprecation import deprecated
+from cocotb._py_compat import Self
+from cocotb._typing import RoundMode, TimeUnit
+from cocotb._utils import pointer_str, singleton
+from cocotb.utils import get_sim_steps, get_time_from_sim_steps
+
+
+class GPITrigger(Trigger):
+    """A trigger for a simulation event."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cbhdl: Optional[simulator.gpi_cb_hdl] = None
+
+    def _unprime(self) -> None:
+        """Disable a primed trigger, can be re-primed."""
+        if self._cbhdl is not None:
+            self._cbhdl.deregister()
+        return super()._unprime()
+
+    def _cleanup(self) -> None:
+        self._cbhdl = None
+        return super()._cleanup()
+
+
+class Timer(GPITrigger):
+    r"""Fire after the specified simulation time period has elapsed.
+
+    This trigger will *always* consume some simulation time
+    and will return control to the :keyword:`await`\ ing task at the beginning of the time step.
+
+    Args:
+        time: The time value.
+
+            .. versionchanged:: 1.5
+                Previously this argument was misleadingly called `time_ps`.
+
+        unit: The unit of the time value.
+
+            One of ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``.
+            When *unit* is ``'step'``,
+            the timestep is determined by the simulator (see :make:var:`COCOTB_HDL_TIMEPRECISION`).
+
+            .. versionchanged:: 2.0
+                Renamed from ``units``.
+
+        round_mode:
+
+            String specifying how to handle time values that sit between time steps
+            (one of ``'error'``, ``'round'``, ``'ceil'``, ``'floor'``, ``None``).
+            A ``None`` argument is converted to the current value of :attr:`.Timer.round_mode`.
+
+    Raises:
+        ValueError: If a non-positive value is passed for Timer setup.
+
+    Usage:
+        >>> await Timer(100, unit="ps")
+
+        The time can also be a ``float``:
+
+        >>> await Timer(100e-9, unit="sec")
+
+        which is particularly convenient when working with frequencies:
+
+        >>> freq = 10e6  # 10 MHz
+        >>> await Timer(1 / freq, unit="sec")
+
+        Other built-in exact numeric types can be used too:
+
+        >>> from fractions import Fraction
+        >>> await Timer(Fraction(1, 10), unit="ns")
+
+        >>> from decimal import Decimal
+        >>> await Timer(Decimal("100e-9"), unit="sec")
+
+        These are most useful when using computed durations while
+        avoiding floating point inaccuracies.
+
+    .. versionchanged:: 1.5
+        Raise an exception when Timer uses a negative value as it is undefined behavior.
+        Warn for 0 as this will cause erratic behavior in some simulators as well.
+
+    .. versionchanged:: 1.5
+        Support ``'step'`` as the *unit* argument to mean "simulator time step".
+
+    .. versionchanged:: 1.6
+        Support rounding modes.
+
+    .. versionremoved:: 2.0
+        Passing ``None`` as the *unit* argument was removed, use ``'step'`` instead.
+
+    .. versionremoved:: 2.0
+        The ``time_ps`` parameter was removed, use the ``time`` parameter instead.
+
+    .. versionchanged:: 2.0
+        Passing ``0`` as the *time* argument now raises a :exc:`ValueError`.
+    """
+
+    round_mode: ClassVar[RoundMode] = "error"
+    """The default rounding mode."""
+
+    def __init__(
+        self,
+        time: Union[float, Fraction, Decimal],
+        unit: TimeUnit = "step",
+        *,
+        round_mode: Optional[RoundMode] = None,
+        units: None = None,
+    ) -> None:
+        super().__init__()
+        if time <= 0:
+            raise ValueError("Timer argument time must be positive")
+        if units is not None:
+            warnings.warn(
+                "The 'units' argument has been renamed to 'unit'.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            unit = units
+        if round_mode is None:
+            round_mode = type(self).round_mode
+        self._sim_steps = get_sim_steps(time, unit, round_mode=round_mode)
+        # If we round to 0, we fix it up to 1 step as rounding is imprecise,
+        # and Timer(0) is invalid.
+        if self._sim_steps == 0:
+            self._sim_steps = 1
+
+    def _prime(self, callback: Callable[["Self"], None]) -> None:
+        """Register for a timed callback."""
+        if self._cbhdl is None:
+            self._cbhdl = simulator.register_timed_callback(
+                self._sim_steps, callback, self
+            )
+            if self._cbhdl is None:
+                raise RuntimeError(f"Unable set up {self!s} Trigger")
+        super()._prime(callback)
+
+    def __repr__(self) -> str:
+        return "<{} of {:1.2f}ps at {}>".format(
+            type(self).__qualname__,
+            get_time_from_sim_steps(self._sim_steps, unit="ps"),
+            pointer_str(self),
+        )
+
+
+@singleton
+class ReadOnly(GPITrigger):
+    """Fires when the current simulation timestep moves to the read-only phase.
+
+    The read-only phase is entered when the current timestep no longer has any further delta steps.
+    This will be a point where all the signal values are stable as there are no more RTL events scheduled for the timestep.
+    The simulator will not allow scheduling of more events in this timestep.
+    Useful for monitors which need to wait for all processes to execute (both RTL and cocotb) to ensure sampled signal values are final.
+    """
+
+    def _prime(self, callback: Callable[["Self"], None]) -> None:
+        if isinstance(current_gpi_trigger(), ReadOnly):
+            raise RuntimeError(
+                "Attempted illegal transition: awaiting ReadOnly in ReadOnly phase"
+            )
+        if self._cbhdl is None:
+            self._cbhdl = simulator.register_readonly_callback(callback, self)
+            if self._cbhdl is None:
+                raise RuntimeError(f"Unable set up {self!s} Trigger")
+        super()._prime(callback)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__qualname__}()"
+
+
+@singleton
+class ReadWrite(GPITrigger):
+    """Fires when the read-write simulation phase is reached."""
+
+    def _prime(self, callback: Callable[["Self"], None]) -> None:
+        if isinstance(current_gpi_trigger(), ReadOnly):
+            raise RuntimeError(
+                "Attempted illegal transition: awaiting ReadWrite in ReadOnly phase"
+            )
+        if self._cbhdl is None:
+            self._cbhdl = simulator.register_rwsynch_callback(callback, self)
+            if self._cbhdl is None:
+                raise RuntimeError(f"Unable set up {self!s} Trigger")
+        super()._prime(callback)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__qualname__}()"
+
+
+@singleton
+class NextTimeStep(GPITrigger):
+    """Fires when the next time step is started."""
+
+    def _prime(self, callback: Callable[["Self"], None]) -> None:
+        if self._cbhdl is None:
+            self._cbhdl = simulator.register_nextstep_callback(callback, self)
+            if self._cbhdl is None:
+                raise RuntimeError(f"Unable set up {self!s} Trigger")
+        super()._prime(callback)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__qualname__}()"
+
+
+_SignalType = TypeVar("_SignalType", bound="cocotb.handle.ValueObjectBase[Any, Any]")
+
+
+class _EdgeBase(GPITrigger, Generic[_SignalType]):
+    """Internal base class that fires on a given edge of a signal."""
+
+    _edge_type: ClassVar[int]
+    signal: _SignalType
+
+    @classmethod
+    def _make(cls, signal: _SignalType) -> "Self":
+        self = GPITrigger.__new__(cls)
+        GPITrigger.__init__(self)
+        self.signal = signal
+        return self
+
+    def __init__(self, _: _SignalType) -> None:
+        pass
+
+    def _prime(self, callback: Callable[["Self"], None]) -> None:
+        if self._cbhdl is None:
+            self._cbhdl = simulator.register_value_change_callback(
+                self.signal._handle, callback, type(self)._edge_type, self
+            )
+            if self._cbhdl is None:
+                raise RuntimeError(f"Unable set up {self!s} Trigger")
+        super()._prime(callback)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__qualname__}({self.signal!r})"
+
+
+class RisingEdge(_EdgeBase["cocotb.handle.LogicObject"]):
+    """Fires on the rising edge of *signal*, on a transition to ``1``.
+
+    Only valid for scalar ``logic`` or ``bit``-typed signals.
+
+    Args:
+        signal: The signal upon which to wait for a rising edge.
+
+    Raises:
+        TypeError: If *signal* is not a 1-bit ``logic`` or ``bit``-typed object.
+
+    .. note::
+        Prefer :attr:`await signal.rising_edge <cocotb.handle.LogicObject.rising_edge>` to ``await RisingEdge(signal)``.
+
+    .. warning::
+        On many simulators this will trigger on transitions from non-``0``/``1`` value to ``1``,
+        not just from ``0`` to ``1`` like the ``rising_edge`` function in VHDL.
+    """
+
+    _edge_type = simulator.RISING
+
+    def __new__(cls, signal: "cocotb.handle.LogicObject") -> "RisingEdge":
+        if not (isinstance(signal, cocotb.handle.LogicObject)):
+            raise TypeError(
+                f"{cls.__qualname__} requires a scalar LogicObject. Got {signal!r} of type {type(signal).__qualname__}"
+            )
+        return signal.rising_edge
+
+
+class FallingEdge(_EdgeBase["cocotb.handle.LogicObject"]):
+    """Fires on the falling edge of *signal*, on a transition to ``0``.
+
+    Only valid for scalar ``logic`` or ``bit``-typed signals.
+
+    Args:
+        signal: The signal upon which to wait for a rising edge.
+
+    Raises:
+        TypeError: If *signal* is not a 1-bit ``logic`` or ``bit``-typed object.
+
+    .. note::
+        Prefer :attr:`await signal.falling_edge <cocotb.handle.LogicObject.falling_edge>` to ``await FallingEdge(signal)``.
+
+    .. warning::
+        On many simulators this will trigger on transitions from non-``0``/``1`` value to ``0``,
+        not just from ``1`` to ``0`` like the ``falling_edge`` function in VHDL.
+    """
+
+    _edge_type = simulator.FALLING
+
+    def __new__(cls, signal: "cocotb.handle.LogicObject") -> "FallingEdge":
+        if not (isinstance(signal, cocotb.handle.LogicObject)):
+            raise TypeError(
+                f"{cls.__qualname__} requires a scalar LogicObject. Got {signal!r} of type {type(signal).__qualname__}"
+            )
+        return signal.falling_edge
+
+
+class ValueChange(_EdgeBase["cocotb.handle._NonIndexableValueObjectBase[Any, Any]"]):
+    """Fires on any value change of *signal*.
+
+    Args:
+        signal: The signal upon which to wait for a value change.
+
+    Raises:
+        TypeError: If the signal is not an object which can change value.
+
+    .. note::
+        Prefer :attr:`await signal.value_change <cocotb.handle.NonArrayValueObject.value_change>` to ``await ValueChange(signal)``.
+
+    .. versionadded:: 2.0
+    """
+
+    _edge_type = simulator.VALUE_CHANGE
+
+    def __new__(
+        cls, signal: "cocotb.handle._NonIndexableValueObjectBase[Any, Any]"
+    ) -> "ValueChange":
+        if not isinstance(signal, cocotb.handle._NonIndexableValueObjectBase):
+            raise TypeError(
+                f"{cls.__qualname__} requires a simulation object derived from ValueObjectBase. "
+                f"Got {signal!r} of type {type(signal).__qualname__}"
+            )
+        return signal.value_change
+
+
+class Edge(ValueChange):
+    """Fires on any value change of *signal*.
+
+    Args:
+        signal: The signal upon which to wait for a value change.
+
+    Raises:
+        TypeError: If the signal is not an object which can change value.
+
+    .. deprecated:: 2.0
+
+        Use :attr:`signal.value_change <cocotb.handle.NonArrayValueObject.value_change>` instead.
+    """
+
+    @deprecated("Use `signal.value_change` instead.")
+    def __new__(
+        cls, signal: "cocotb.handle._NonIndexableValueObjectBase[Any, Any]"
+    ) -> "Edge":
+        if not isinstance(signal, cocotb.handle._NonIndexableValueObjectBase):
+            raise TypeError(
+                f"{cls.__qualname__} requires a simulation object derived from ValueObjectBase. "
+                f"Got {signal!r} of type {type(signal).__qualname__}"
+            )
+        return signal._edge
+
+
+# The initializer is a lie, but a useful one. Perhaps one day this can be something like `StartupTrigger`.`
+_current_gpi_trigger = Timer(1, "step")  # type: Union[None, GPITrigger]
+
+
+def current_gpi_trigger() -> GPITrigger:
+    """Return the last GPITrigger that fired."""
+    if _current_gpi_trigger is None:
+        raise RuntimeError("No GPI trigger has fired.")
+    return _current_gpi_trigger

cocotb/_init.py

@@ -0,0 +1,295 @@
+# Copyright cocotb contributors
+# Copyright (c) 2013 Potential Ventures Ltd
+# Copyright (c) 2013 SolarFlare Communications Inc
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+import ast
+import logging
+import os
+import random
+import sys
+import time
+import warnings
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Callable, List, cast
+
+import cocotb
+import cocotb._profiling
+import cocotb.handle
+import cocotb.simulator
+from cocotb._scheduler import Scheduler
+from cocotb.regression import RegressionManager, RegressionMode
+
+log: logging.Logger
+
+
+def _setup_logging() -> None:
+    cocotb.log = logging.getLogger("test")
+    cocotb.log.setLevel(logging.INFO)
+
+    global log
+    log = logging.getLogger("cocotb")
+
+
+_shutdown_callbacks: List[Callable[[], None]] = []
+"""List of callbacks to be called when cocotb shuts down."""
+
+
+def _register_shutdown_callback(cb: Callable[[], None]) -> None:
+    """Register a callback to be called when cocotb shuts down."""
+    _shutdown_callbacks.append(cb)
+
+
+def _shutdown_testbench() -> None:
+    """Call all registered shutdown callbacks."""
+    while _shutdown_callbacks:
+        cb = _shutdown_callbacks.pop(0)
+        cb()
+
+
+def init_package_from_simulation(argv: List[str]) -> None:
+    """Initialize the cocotb package from a simulation context."""
+
+    # register a callback to be called if the simulation fails
+    cocotb.simulator.set_sim_event_callback(_sim_event)
+
+    cocotb.is_simulation = True
+
+    cocotb.argv = argv
+
+    # sys.path normally includes "" (the current directory), but does not appear to when python is embedded.
+    # Add it back because users expect to be able to import files in their test directory.
+    sys.path.insert(0, "")
+
+    _setup_logging()
+
+    # From https://www.python.org/dev/peps/pep-0565/#recommended-filter-settings-for-test-runners
+    # If the user doesn't want to see these, they can always change the global
+    # warning settings in their test module.
+    if not sys.warnoptions:
+        warnings.simplefilter("default")
+
+    cocotb.SIM_NAME = cocotb.simulator.get_simulator_product().strip()
+    cocotb.SIM_VERSION = cocotb.simulator.get_simulator_version().strip()
+
+    log.info("Running on %s version %s", cocotb.SIM_NAME, cocotb.SIM_VERSION)
+
+    cocotb._profiling.initialize()
+    _register_shutdown_callback(cocotb._profiling.finalize)
+
+    _process_plusargs()
+    _process_packages()
+    _setup_random_seed()
+    _setup_root_handle()
+    _start_user_coverage()
+
+    log.info(
+        "Initialized cocotb v%s from %s",
+        cocotb.__version__,
+        Path(__file__).parent.absolute(),
+    )
+
+
+def run_regression(_: object) -> None:
+    """Setup and run a regression."""
+
+    _setup_regression_manager()
+
+    # setup global scheduler system
+    cocotb._scheduler_inst = Scheduler()
+
+    # start Regression Manager
+    log.info("Running tests")
+    cocotb._regression_manager.start_regression()
+
+
+def _sim_event(msg: str) -> None:
+    """Function that can be called externally to signal an event."""
+    # We simply return here as the simulator will exit
+    # so no cleanup is needed
+    if hasattr(cocotb, "_regression_manager"):
+        cocotb._regression_manager._fail_simulation(msg)
+    else:
+        log.error(msg)
+        _shutdown_testbench()
+
+
+def _process_plusargs() -> None:
+    cocotb.plusargs = {}
+
+    for option in cocotb.argv:
+        if option.startswith("+"):
+            if option.find("=") != -1:
+                (name, value) = option[1:].split("=", 1)
+                cocotb.plusargs[name] = value
+            else:
+                cocotb.plusargs[option[1:]] = True
+
+
+def _process_packages() -> None:
+    pkg_dict = {}
+
+    from cocotb import simulator  # noqa: PLC0415
+
+    pkgs = simulator.package_iterate()
+    if pkgs is None:
+        cocotb.packages = SimpleNamespace()
+        return
+
+    for pkg in pkgs:
+        handle = cast(
+            "cocotb.handle.HierarchyObject", cocotb.handle._make_sim_object(pkg)
+        )
+        name = handle._name
+
+        # Icarus doesn't support named access to package objects:
+        # https://github.com/steveicarus/iverilog/issues/1038
+        # so we cannot lazily create handles
+        if cocotb.SIM_NAME == "Icarus Verilog":
+            handle._discover_all()
+        pkg_dict[name] = handle
+
+    cocotb.packages = SimpleNamespace(**pkg_dict)
+
+
+def _start_user_coverage() -> None:
+    coverage_envvar = os.getenv("COCOTB_USER_COVERAGE")
+    if coverage_envvar is None:
+        coverage_envvar = os.getenv("COVERAGE")
+        if coverage_envvar is not None:
+            warnings.warn(
+                "COVERAGE is deprecated in favor of COCOTB_USER_COVERAGE",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+    if coverage_envvar:
+        try:
+            import coverage  # noqa: PLC0415
+        except ImportError:
+            raise RuntimeError(
+                "Coverage collection requested but coverage module not available. Install it using `pip install coverage`."
+            ) from None
+        else:
+            config_filepath = os.getenv("COCOTB_COVERAGE_RCFILE")
+            if config_filepath is None:
+                config_filepath = os.getenv("COVERAGE_RCFILE")
+                if config_filepath is not None:
+                    warnings.warn(
+                        "COVERAGE_RCFILE is deprecated in favor of COCOTB_COVERAGE_RCFILE",
+                        DeprecationWarning,
+                        stacklevel=2,
+                    )
+            if config_filepath is None:
+                # Exclude cocotb itself from coverage collection.
+                log.info(
+                    "Collecting coverage of user code. No coverage config file supplied via COCOTB_COVERAGE_RCFILE."
+                )
+                cocotb_package_dir = Path(__file__).parent.absolute()
+                user_coverage = coverage.coverage(
+                    branch=True, omit=[f"{cocotb_package_dir}/*"]
+                )
+            else:
+                log.info(
+                    "Collecting coverage of user code. Coverage config file supplied."
+                )
+                # Allow the config file to handle all configuration
+                user_coverage = coverage.coverage(config_file=config_filepath)
+            user_coverage.start()
+
+            def stop_user_coverage() -> None:
+                user_coverage.stop()
+                log.debug("Writing user coverage data")
+                user_coverage.save()
+
+            _register_shutdown_callback(stop_user_coverage)
+
+
+def _setup_random_seed() -> None:
+    seed_envvar = os.getenv("COCOTB_RANDOM_SEED")
+    if seed_envvar is None:
+        seed_envvar = os.getenv("RANDOM_SEED")
+        if seed_envvar is not None:
+            warnings.warn(
+                "RANDOM_SEED is deprecated in favor of COCOTB_RANDOM_SEED",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+    if seed_envvar is None:
+        if "ntb_random_seed" in cocotb.plusargs:
+            plusarg_seed = cocotb.plusargs["ntb_random_seed"]
+            if not isinstance(plusarg_seed, str):
+                raise TypeError("ntb_random_seed plusarg is not a valid seed value.")
+            seed = ast.literal_eval(plusarg_seed)
+            if not isinstance(seed, int):
+                raise TypeError("ntb_random_seed plusargs is not a valid seed value.")
+            cocotb.RANDOM_SEED = seed
+        elif "seed" in cocotb.plusargs:
+            plusarg_seed = cocotb.plusargs["seed"]
+            if not isinstance(plusarg_seed, str):
+                raise TypeError("seed plusarg is not a valid seed value.")
+            seed = ast.literal_eval(plusarg_seed)
+            if not isinstance(seed, int):
+                raise TypeError("seed plusargs is not a valid seed value.")
+            cocotb.RANDOM_SEED = seed
+        else:
+            cocotb.RANDOM_SEED = int(time.time())
+        log.info("Seeding Python random module with %d", cocotb.RANDOM_SEED)
+    else:
+        cocotb.RANDOM_SEED = ast.literal_eval(seed_envvar)
+        log.info(
+            "Seeding Python random module with supplied seed %d", cocotb.RANDOM_SEED
+        )
+
+    random.seed(cocotb.RANDOM_SEED)
+
+
+def _setup_root_handle() -> None:
+    root_name = os.getenv("COCOTB_TOPLEVEL")
+    if root_name is not None:
+        root_name = root_name.strip()
+        if root_name == "":
+            root_name = None
+        elif "." in root_name:
+            # Skip any library component of the toplevel
+            root_name = root_name.split(".", 1)[1]
+
+    from cocotb import simulator  # noqa: PLC0415
+
+    handle = simulator.get_root_handle(root_name)
+    if not handle:
+        raise RuntimeError(f"Can not find root handle {root_name!r}")
+
+    cocotb.top = cocotb.handle._make_sim_object(handle)
+
+
+def _setup_regression_manager() -> None:
+    cocotb._regression_manager = RegressionManager()
+
+    # discover tests
+    module_str = os.getenv("COCOTB_TEST_MODULES", "")
+    if not module_str:
+        raise RuntimeError(
+            "Environment variable COCOTB_TEST_MODULES, which defines the module(s) to execute, is not defined or empty."
+        )
+    modules = [s.strip() for s in module_str.split(",") if s.strip()]
+    cocotb._regression_manager.setup_pytest_assertion_rewriting()
+    cocotb._regression_manager.discover_tests(*modules)
+
+    # filter tests
+    testcase_str = os.getenv("COCOTB_TESTCASE", "").strip()
+    test_filter_str = os.getenv("COCOTB_TEST_FILTER", "").strip()
+    if testcase_str and test_filter_str:
+        raise RuntimeError("Specify only one of COCOTB_TESTCASE or COCOTB_TEST_FILTER")
+    elif testcase_str:
+        warnings.warn(
+            "COCOTB_TESTCASE is deprecated in favor of COCOTB_TEST_FILTER",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        filters = [f"{s.strip()}$" for s in testcase_str.split(",") if s.strip()]
+        cocotb._regression_manager.add_filters(*filters)
+        cocotb._regression_manager.set_mode(RegressionMode.TESTCASE)
+    elif test_filter_str:
+        cocotb._regression_manager.add_filters(test_filter_str)
+        cocotb._regression_manager.set_mode(RegressionMode.TESTCASE)