cocotb 1.9.2__cp310-cp310-win32.whl → 2.0.0rc2__cp310-cp310-win32.whl

cocotb/_xunit_reporter.py

@@ -0,0 +1,66 @@
+# 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 xml.etree.ElementTree as ET
+from typing import Union
+from xml.etree.ElementTree import Element, SubElement
+
+
+class XUnitReporter:
+    last_testsuite: Element
+    last_testcase: Element
+
+    def __init__(self, filename: str = "results.xml") -> None:
+        self.results = Element("testsuites", name="results")
+        self.filename = filename
+
+    def add_testsuite(self, **kwargs: str) -> Element:
+        self.last_testsuite = SubElement(self.results, "testsuite", kwargs)
+        return self.last_testsuite
+
+    def add_testcase(
+        self, testsuite: Union[Element, None] = None, **kwargs: str
+    ) -> Element:
+        if testsuite is None:
+            testsuite = self.last_testsuite
+        self.last_testcase = SubElement(testsuite, "testcase", kwargs)
+        return self.last_testcase
+
+    def add_property(
+        self, testsuite: Union[Element, None] = None, **kwargs: str
+    ) -> Element:
+        if testsuite is None:
+            testsuite = self.last_testsuite
+        self.last_property = SubElement(testsuite, "property", kwargs)
+        return self.last_property
+
+    def add_failure(self, testcase: Union[Element, None] = None, **kwargs: str) -> None:
+        if testcase is None:
+            testcase = self.last_testcase
+        SubElement(testcase, "failure", kwargs)
+
+    def add_skipped(self, testcase: Union[Element, None] = None, **kwargs: str) -> None:
+        if testcase is None:
+            testcase = self.last_testcase
+        SubElement(testcase, "skipped", kwargs)
+
+    def indent(self, elem: Element, level: int = 0) -> None:
+        i = "\n" + level * "  "
+        if len(elem):
+            if not elem.text or not elem.text.strip():
+                elem.text = i + "  "
+            if not elem.tail or not elem.tail.strip():
+                elem.tail = i
+            for sub_elem in elem:
+                self.indent(sub_elem, level + 1)
+            if not sub_elem.tail or not sub_elem.tail.strip():
+                sub_elem.tail = i
+        elif level and (not elem.tail or not elem.tail.strip()):
+            elem.tail = i
+
+    def write(self) -> None:
+        self.indent(self.results)
+        ET.ElementTree(self.results).write(self.filename, encoding="UTF-8")

cocotb/clock.py

@@ -1,89 +1,112 @@
+# Copyright cocotb contributors
 # Copyright (c) 2013 Potential Ventures Ltd
 # Copyright (c) 2013 SolarFlare Communications Inc
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#     * Redistributions of source code must retain the above copyright
-#       notice, this list of conditions and the following disclaimer.
-#     * Redistributions in binary form must reproduce the above copyright
-#       notice, this list of conditions and the following disclaimer in the
-#       documentation and/or other materials provided with the distribution.
-#     * Neither the name of Potential Ventures Ltd,
-#       SolarFlare Communications Inc nor the
-#       names of its contributors may be used to endorse or promote products
-#       derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL POTENTIAL VENTURES LTD BE LIABLE FOR ANY
-# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
 
 """A clock class."""
 
-import itertools
+import logging
 import warnings
 from decimal import Decimal
-from numbers import Real
-from typing import Union
+from fractions import Fraction
+from logging import Logger
+from typing import ClassVar, Type, Union
 
-from cocotb.log import SimLog
-from cocotb.triggers import Timer
-from cocotb.utils import get_sim_steps, get_time_from_sim_steps, lazy_property
+import cocotb
+from cocotb._py_compat import (
+    Literal,
+    TypeAlias,
+    cached_property,
+)
+from cocotb._typing import TimeUnit
+from cocotb.handle import (
+    Deposit,
+    Force,
+    Immediate,
+    LogicObject,
+    _GPISetAction,
+    _trust_inertial,
+)
+from cocotb.simulator import clock_create
+from cocotb.task import Task
+from cocotb.triggers import (
+    Event,
+    FallingEdge,
+    NullTrigger,
+    RisingEdge,
+    Timer,
+    ValueChange,
+)
+from cocotb.utils import get_sim_steps, get_time_from_sim_steps
 
+__all__ = ("Clock",)
 
-class BaseClock:
-    """Base class to derive from."""
+Impl: TypeAlias = Literal["gpi", "py"]
 
-    def __init__(self, signal):
-        self.signal = signal
 
-    @lazy_property
-    def log(self):
-        return SimLog("cocotb.{}.{}".format(type(self).__qualname__, self.signal._name))
+_valid_impls = ("gpi", "py")
 
 
-class Clock(BaseClock):
+class Clock:
     r"""Simple 50:50 duty cycle clock driver.
 
-    Instances of this class should call its :meth:`start` method
-    and pass the coroutine object to one of the functions in :ref:`task-management`.
-
-    This will create a clocking task that drives the signal at the
-    desired period/frequency.
-
-    Example:
-
     .. code-block:: python
 
-        c = Clock(dut.clk, 10, 'ns')
-        await cocotb.start(c.start())
+        c = Clock(dut.clk, 10, "ns")
+        c.start()
 
     Args:
         signal: The clock pin/signal to be driven.
-        period (int): The clock period. Must convert to an even number of
-            timesteps.
-        units (str, optional): One of
-            ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``.
-            When *units* is ``'step'``,
+        period:
+            The clock period.
+            Must be a multiple of the time precision of the simulator.
+
+        unit:
+            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``.
+
+        impl:
+            One of ``'auto'``, ``'gpi'``, ``'py'``.
+            Specify whether the clock is implemented with a :class:`~cocotb.simulator.GpiClock` (faster), or with a Python coroutine.
+            When ``'auto'`` is used (default), the fastest implementation that supports your environment and use case is picked.
+
+            .. versionadded:: 2.0
+
+        set_action:
+            One of :class:`.Immediate`, :class:`.Deposit`, or :class:`.Force`.
+            Specify the action to use when setting the clock signal value.
+            Defaults to the value of :attr:`default_set_action`.
+
+            .. versionadded:: 2.0
+
+        period_high:
+            The period of time when the clock is driven to ``1``.
+            Defaults to half of the *period*.
+            Must be a multiple of the time precision of the simulator and less than *period*.
+
+            .. versionadded:: 2.0
+
+    When *impl* is ``'auto'``, if :envvar:`COCOTB_TRUST_INERTIAL_WRITES` is defined,
+    the :class:`~cocotb.simulator.GpiClock` implementation will be used.
+    Otherwise, the Python coroutine implementation will be used.
+    See the environment variable's documentation for more information on the consequences
+    of using the simulator's inertial write mechanism.
+
     If you need more features like a phase shift and an asymmetric duty cycle,
-    it is simple to create your own clock generator (that you then :func:`~cocotb.start`):
+    it is simple to create your own clock generator (that you then :func:`cocotb.start_soon`):
 
     .. code-block:: python
 
         async def custom_clock():
             # pre-construct triggers for performance
-            high_time = Timer(high_delay, units="ns")
-            low_time = Timer(low_delay, units="ns")
-            await Timer(initial_delay, units="ns")
+            high_time = Timer(high_delay, unit="ns")
+            low_time = Timer(low_delay, unit="ns")
+            await Timer(initial_delay, unit="ns")
             while True:
                 dut.clk.value = 1
                 await high_time
@@ -100,75 +123,297 @@ class Clock(BaseClock):
         async def custom_clock():
             while True:
                 dut.clk.value = 1
-                await Timer(high_delay, units="ns")
+                await Timer(high_delay, unit="ns")
                 dut.clk.value = 0
-                await Timer(low_delay, units="ns")
+                await Timer(low_delay, unit="ns")
+
 
         high_delay = low_delay = 100
-        await cocotb.start(custom_clock())
-        await Timer(1000, units="ns")
+        cocotb.start_soon(custom_clock())
+        await Timer(1000, unit="ns")
         high_delay = low_delay = 10  # change the clock speed
-        await Timer(1000, units="ns")
+        await Timer(1000, unit="ns")
 
-    .. versionchanged:: 1.5
-        Support ``'step'`` as the *units* argument to mean "simulator time step".
+    .. versionadded:: 1.5
+        Support ``'step'`` as the *unit* argument to mean "simulator time step".
 
-    .. deprecated:: 1.5
-        Using ``None`` as the *units* argument is deprecated, use ``'step'`` instead.
+    .. versionremoved:: 2.0
+        Passing ``None`` as the *unit* argument was removed, use ``'step'`` instead.
+
+    .. versionchanged:: 2.0
+        :meth:`start` now automatically calls :func:`cocotb.start_soon` and stores the Task
+        on the Clock object, so that it may later be :meth:`stop`\ ped.
+    """
+
+    _impl: Impl
+
+    default_set_action: ClassVar[Union[Type[Immediate], Type[Deposit], Type[Force]]] = (
+        Deposit
+    )
+    """The default action used to set the clock signal value.
+    One of :class:`.Immediate`, :class:`.Deposit`, or :class:`.Force`.
+
+    .. versionadded:: 2.0
     """
 
     def __init__(
-        self, signal, period: Union[float, Real, Decimal], units: str = "step"
-    ):
-        BaseClock.__init__(self, signal)
-        if units is None:
+        self,
+        signal: LogicObject,
+        period: Union[float, Fraction, Decimal],
+        unit: TimeUnit = "step",
+        impl: Union[Impl, None] = None,
+        *,
+        units: None = None,
+        set_action: Union[Type[Immediate], Type[Deposit], Type[Force], None] = None,
+        period_high: Union[float, Fraction, Decimal, None] = None,
+    ) -> None:
+        self._signal = signal
+
+        if units is not None:
             warnings.warn(
-                'Using units=None is deprecated, use units="step" instead.',
+                "The 'units' argument has been renamed to 'unit'.",
                 DeprecationWarning,
                 stacklevel=2,
             )
-            units = "step"  # don't propagate deprecated value
-        self.period = get_sim_steps(period, units)
-        self.half_period = get_sim_steps(period / 2, units)
-        self.frequency = 1 / get_time_from_sim_steps(self.period, units="us")
-        self.hdl = None
-        self.signal = signal
-        self.coro = None
-        self.mcoro = None
-
-    async def start(self, cycles=None, start_high=True):
-        r"""Clocking coroutine.  Start driving your clock by :func:`cocotb.start`\ ing a
-        call to this.
+            unit = units
+        self._unit: TimeUnit = unit
+
+        self._period = period
+        try:
+            self._period_steps = get_sim_steps(self._period, self._unit)
+        except ValueError as e:
+            raise ValueError(f"Bad `period`: {e}") from None
+
+        if set_action is None:
+            set_action = type(self).default_set_action
+        if set_action not in (Immediate, Deposit, Force):
+            raise TypeError(
+                "Invalid value for `set_action`. `set_action` must be one of Immediate, Deposit, or Force"
+            )
+        self._set_action = set_action
+
+        if impl is None:
+            self._impl = "gpi" if _trust_inertial else "py"
+        elif impl in _valid_impls:
+            self._impl = impl
+        else:
+            valid_impls_str = ", ".join([repr(i) for i in _valid_impls])
+            raise ValueError(
+                f"Invalid clock impl {impl!r}, must be one of: {valid_impls_str}"
+            )
+
+        self._period_high: Union[float, Fraction, Decimal]
+        if period_high is not None:
+            if period_high >= self._period:
+                raise ValueError("`period_high` must be strictly less than `period`.")
+            self._period_high = period_high
+            try:
+                self._period_high_steps = get_sim_steps(self._period_high, self._unit)
+            except ValueError as e:
+                raise ValueError(f"Bad `period_high`: {e}") from None
+        else:
+            if self._period_steps % 2 != 0:
+                raise ValueError(
+                    "Bad `period`: Must be divisible by 2 if `period_high` is not given."
+                )
+            self._period_high = period / 2
+            self._period_high_steps = self._period_steps // 2
+
+        self._task: Union[Task[None], None] = None
+
+    @property
+    def signal(self) -> LogicObject:
+        """The clock signal being driven."""
+        return self._signal
+
+    @property
+    def period(self) -> Union[float, Fraction, Decimal]:
+        """The clock period.
+
+        The unit is :attr:`unit`.
+        """
+        return self._period
+
+    @property
+    def period_high(self) -> Union[float, Fraction, Decimal]:
+        """The period of time when the clock is driven to ``1``.
+
+        The unit is :attr:`unit`.
+
+        .. versionadded:: 2.0
+        """
+        return self._period_high
+
+    @property
+    def unit(self) -> TimeUnit:
+        """The unit of the clock period.
+
+        .. versionadded:: 2.0
+        """
+        return self._unit
+
+    @property
+    def impl(self) -> Impl:
+        """The concrete implementation of the clock used.
+
+        ``"gpi"`` if the clock is implemented in C in the GPI layer,
+        or ``"py"`` if the clock is implemented in Python using cocotb Tasks.
+
+        .. versionadded:: 2.0
+        """
+        return self._impl
+
+    @property
+    def set_action(self) -> Union[Type[Immediate], Type[Deposit], Type[Force]]:
+        """The value setting action used to set the clock signal value.
+
+        .. versionadded:: 2.0
+        """
+        return self._set_action
+
+    def start(self, start_high: bool = True) -> Task[None]:
+        r"""Start driving the clock signal.
+
+        You can later stop the clock by calling :meth:`stop`.
 
         Args:
-            cycles (int, optional): Cycle the clock *cycles* number of times,
-                or if ``None`` then cycle the clock forever.
-                Note: ``0`` is not the same as ``None``, as ``0`` will cycle no times.
-            start_high (bool, optional): Whether to start the clock with a ``1``
+            start_high: Whether to start the clock with a ``1``
                 for the first half of the period.
                 Default is ``True``.
 
                 .. versionadded:: 1.3
+
+        Raises:
+            RuntimeError: If attempting to start a clock that has already been started.
+
+        Returns:
+            Object which can be passed to :func:`cocotb.start_soon` or ignored.
+
+        .. versionremoved:: 2.0
+            Removed ``cycles`` arguments for toggling for a finite amount of cycles.
+            Use :meth:`stop` to stop a clock from running.
+
+        .. versionchanged:: 2.0
+            Previously, this method returned a :term:`coroutine` which needed to be passed to :func:`cocotb.start_soon`.
+            Now the Clock object keeps track of its own driver Task, so this is no longer necessary.
+            Simply call ``clock.start()`` to start running the clock.
         """
-        t = Timer(self.half_period)
-        if cycles is None:
-            it = itertools.count()
-        else:
-            it = range(cycles)
-
-        # branch outside for loop for performance (decision has to be taken only once)
-        if start_high:
-            for _ in it:
-                self.signal.value = 1
-                await t
-                self.signal.value = 0
-                await t
+        if self._task is not None:
+            raise RuntimeError("Starting clock that has already been started.")
+
+        if self._impl == "gpi":
+            clkobj = clock_create(self._signal._handle)
+            set_action = {
+                Deposit: _GPISetAction.DEPOSIT,
+                Immediate: _GPISetAction.NO_DELAY,
+                Force: _GPISetAction.FORCE,
+            }[self._set_action]
+            clkobj.start(
+                self._period_steps,
+                self._period_high_steps,
+                start_high,
+                set_action.value,
+            )
+
+            async def drive() -> None:
+                # The clock is meant to toggle forever, so awaiting this should
+                # never return by awaiting on Event that's never set.
+                e = Event()
+                try:
+                    await e.wait()
+                finally:
+                    clkobj.stop()
+
         else:
-            for _ in it:
-                self.signal.value = 0
-                await t
-                self.signal.value = 1
-                await t
-
-    def __str__(self):
-        return type(self).__qualname__ + "(%3.1f MHz)" % self.frequency
+
+            async def drive() -> None:
+                timer_high = Timer(self._period_high_steps)
+                timer_low = Timer(self._period_steps - self._period_high_steps)
+                if start_high:
+                    self._signal.set(self._set_action(1))
+                    await timer_high
+                while True:
+                    self._signal.set(self._set_action(0))
+                    await timer_low
+                    self._signal.set(self._set_action(1))
+                    await timer_high
+
+        self._task = cocotb.start_soon(drive())
+        return self._task
+
+    def stop(self) -> None:
+        """Stop driving the clock signal.
+
+        You can later start the clock again by calling :meth:`start`.
+
+        Raises:
+            RuntimeError: If attempting to stop a clock that has never been started.
+
+        .. versionadded:: 2.0
+        """
+        if self._task is None:
+            raise RuntimeError("Stopping a clock that was never started.")
+        self._task.cancel()
+        self._task = None
+
+    async def cycles(
+        self,
+        num_cycles: int,
+        edge_type: Union[
+            Type[RisingEdge], Type[FallingEdge], Type[ValueChange]
+        ] = RisingEdge,
+    ) -> None:
+        """Wait for a number of clock cycles.
+
+        Args:
+            num_cycles: The number of clock cycles to wait.
+            edge_type:
+                The edge of the clock to wait on.
+                Must be one of :class:`.RisingEdge`, :class:`.FallingEdge`, or :class:`.ValueChange`.
+
+        Raises:
+            ValueError: if *num_cycles* is negative.
+        """
+        if num_cycles == 0:
+            await NullTrigger()
+            return
+        elif num_cycles < 0:
+            raise ValueError("`num_cycles` cannot be negative")
+
+        # Synchronize first.
+        await edge_type(self._signal)
+        num_cycles -= 1
+
+        # Use Timer as an optimization if we are waiting long enough.
+        if num_cycles >= 2:
+            # NOTE: num_cycles must end 1 higher than expected because all edge_types occur
+            # strictly after beginning of time steps, so the last edge_type will jump within
+            # the same time step.
+            if edge_type is ValueChange:
+                # Make cycles_skipped the nearest even number so division by 2 doesn't cause issues.
+                cycles_skipped = (num_cycles // 2) * 2
+                await Timer(self._period_steps * cycles_skipped / 2, "step")
+                num_cycles = num_cycles - cycles_skipped + 1
+            else:
+                await Timer(self._period_steps * num_cycles, "step")
+                num_cycles = 1
+
+        # Run N edge_type trigger.
+        for _ in range(num_cycles):
+            await edge_type(self._signal)
+
+    def __repr__(self) -> str:
+        return self._repr
+
+    @cached_property
+    def _repr(self) -> str:
+        freq_mhz = 1 / get_time_from_sim_steps(
+            get_sim_steps(self._period, self._unit), "us"
+        )
+        return f"<{type(self).__qualname__}, {self._signal._path} @ {freq_mhz} MHz>"
+
+    @cached_property
+    def _log(self) -> Logger:
+        return logging.getLogger(
+            f"cocotb.{type(self).__qualname__}.{self._signal._name}"
+        )

cocotb/debug.py

@@ -0,0 +1,24 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+import os
+
+debug: bool = bool(os.getenv("COCOTB_SCHEDULER_DEBUG"))
+"""Global flag to enable additional debugging functionality.
+
+Defaults to ``True`` if the :envvar:`COCOTB_SCHEDULER_DEBUG` environment variable is set,
+but can be programmatically set by the user afterwards.
+
+The ``"cocotb"`` logger should have its logging level set to :data:`logging.DEBUG`
+to see additional debugging information in the test log.
+This can be accomplished by setting the :envvar:`COCOTB_LOG_LEVEL` environment variable
+to ``DEBUG``,
+or using the following code.
+
+.. code-block:: python
+
+    import logging
+    logging.getLogger("cocotb").setLevel(logging.DEBUG)
+
+"""