cocotb 1.7.2__tar.gz → 1.8.0rc1__tar.gz

{cocotb-1.7.2/cocotb.egg-info → cocotb-1.8.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cocotb
-Version: 1.7.2
+Version: 1.8.0rc1
 Summary: cocotb is a coroutine based cosimulation library for writing VHDL and Verilog testbenches in Python.
 Home-page: https://www.cocotb.org
 Author: Chris Higgs, Stuart Hodgson
@@ -37,8 +37,7 @@ License-File: LICENSE
 * Read the [documentation](https://docs.cocotb.org)
 * Get involved:
   * [Raise a bug / request an enhancement](https://github.com/cocotb/cocotb/issues/new) (Requires a GitHub account)
-  * [Join the mailing list](https://lists.librecores.org/listinfo/cocotb)
-  * [Join the Gitter chat room](https://gitter.im/cocotb)
+  * [Join the Gitter chat room](https://gitter.im/cocotb/Lobby)
 
 ## Installation
 
@@ -96,22 +95,38 @@ An example of a simple randomized cocotb testbench:
 # test_dff.py
 
 import random
+
 import cocotb
 from cocotb.clock import Clock
-from cocotb.triggers import FallingEdge
+from cocotb.triggers import RisingEdge
+from cocotb.types import LogicArray
 
 @cocotb.test()
-async def test_dff_simple(dut):
-    """ Test that d propagates to q """
+async def dff_simple_test(dut):
+    """Test that d propagates to q"""
+
+    # Assert initial output is unknown
+    assert LogicArray(dut.q.value) == LogicArray("X")
+    # Set initial input value to prevent it from floating
+    dut.d.value = 0
 
     clock = Clock(dut.clk, 10, units="us")  # Create a 10us period clock on port clk
-    cocotb.start_soon(clock.start())  # Start the clock
+    # Start the clock. Start it low to avoid issues on the first RisingEdge
+    cocotb.start_soon(clock.start(start_high=False))
 
+    # Synchronize with the clock. This will regisiter the initial `d` value
+    await RisingEdge(dut.clk)
+    expected_val = 0  # Matches initial input value
     for i in range(10):
         val = random.randint(0, 1)
         dut.d.value = val  # Assign the random value val to the input port d
-        await FallingEdge(dut.clk)
-        assert dut.q.value == val, "output q was incorrect on the {}th cycle".format(i)
+        await RisingEdge(dut.clk)
+        assert dut.q.value == expected_val, f"output q was incorrect on the {i}th cycle"
+        expected_val = val # Save random value for next RisingEdge
+
+    # Check the final input on the next clock
+    await RisingEdge(dut.clk)
+    assert dut.q.value == expected_val, "output q was incorrect on the last cycle"
 ```
 
 A simple Makefile:

{cocotb-1.7.2 → cocotb-1.8.0rc1}/README.md

@@ -9,8 +9,7 @@
 * Read the [documentation](https://docs.cocotb.org)
 * Get involved:
   * [Raise a bug / request an enhancement](https://github.com/cocotb/cocotb/issues/new) (Requires a GitHub account)
-  * [Join the mailing list](https://lists.librecores.org/listinfo/cocotb)
-  * [Join the Gitter chat room](https://gitter.im/cocotb)
+  * [Join the Gitter chat room](https://gitter.im/cocotb/Lobby)
 
 ## Installation
 
@@ -68,22 +67,38 @@ An example of a simple randomized cocotb testbench:
 # test_dff.py
 
 import random
+
 import cocotb
 from cocotb.clock import Clock
-from cocotb.triggers import FallingEdge
+from cocotb.triggers import RisingEdge
+from cocotb.types import LogicArray
 
 @cocotb.test()
-async def test_dff_simple(dut):
-    """ Test that d propagates to q """
+async def dff_simple_test(dut):
+    """Test that d propagates to q"""
+
+    # Assert initial output is unknown
+    assert LogicArray(dut.q.value) == LogicArray("X")
+    # Set initial input value to prevent it from floating
+    dut.d.value = 0
 
     clock = Clock(dut.clk, 10, units="us")  # Create a 10us period clock on port clk
-    cocotb.start_soon(clock.start())  # Start the clock
+    # Start the clock. Start it low to avoid issues on the first RisingEdge
+    cocotb.start_soon(clock.start(start_high=False))
 
+    # Synchronize with the clock. This will regisiter the initial `d` value
+    await RisingEdge(dut.clk)
+    expected_val = 0  # Matches initial input value
     for i in range(10):
         val = random.randint(0, 1)
         dut.d.value = val  # Assign the random value val to the input port d
-        await FallingEdge(dut.clk)
-        assert dut.q.value == val, "output q was incorrect on the {}th cycle".format(i)
+        await RisingEdge(dut.clk)
+        assert dut.q.value == expected_val, f"output q was incorrect on the {i}th cycle"
+        expected_val = val # Save random value for next RisingEdge
+
+    # Check the final input on the next clock
+    await RisingEdge(dut.clk)
+    assert dut.q.value == expected_val, "output q was incorrect on the last cycle"
 ```
 
 A simple Makefile:

{cocotb-1.7.2 → cocotb-1.8.0rc1}/cocotb/__init__.py

@@ -45,12 +45,12 @@ from cocotb._deprecation import deprecated
 from cocotb.log import default_config
 from cocotb.regression import RegressionManager
 from cocotb.scheduler import Scheduler
+from cocotb.task import Task
 
 from ._version import __version__
 
 # Things we want in the cocotb namespace
 from cocotb.decorators import (  # isort: skip # noqa: F401
-    Task,
     coroutine,
     external,
     function,
@@ -322,26 +322,15 @@ def _initialise_testbench_(argv_):
     regression_manager._execute()
 
 
-def _sim_event(level, message):
+def _sim_event(message):
     """Function that can be called externally to signal an event."""
-    # SIM_INFO = 0
-    SIM_TEST_FAIL = 1
-    SIM_FAIL = 2
     from cocotb.result import SimFailure
 
-    if level is SIM_TEST_FAIL:
-        scheduler.log.error("Failing test at simulator request")
-        scheduler._finish_test(
-            AssertionError(f"Failure from external source: {message}")
-        )
-    elif level is SIM_FAIL:
-        # We simply return here as the simulator will exit
-        # so no cleanup is needed
-        msg = f"Failing test at simulator request before test run completion: {message}"
-        scheduler.log.error(msg)
-        scheduler._finish_scheduler(SimFailure(msg))
-    else:
-        scheduler.log.error("Unsupported sim event")
+    # We simply return here as the simulator will exit
+    # so no cleanup is needed
+    msg = f"Failing test at simulator request before test run completion: {message}"
+    scheduler.log.error(msg)
+    scheduler._finish_scheduler(SimFailure(msg))
 
 
 @deprecated("This function is now private")

{cocotb-1.7.2 → cocotb-1.8.0rc1}/cocotb/_sim_versions.py

@@ -68,9 +68,24 @@ class QuestaVersion(LooseVersion):
         True
         >>> QuestaVersion("2020.1 2020.01") > QuestaVersion("10.7c 2018.08")
         True
+        >>> QuestaVersion("2020.1 2020.01") == QuestaVersion("2020.1")
+        True
+        >>> QuestaVersion("2023.1_2 2023.03") > QuestaVersion("2023.1_1")
+        True
     """
 
-    pass
+    def parse(self, vstring):
+        # A Questa version string, as returned by the simulator, consists of two
+        # space-separated parts. The first part is the actual version number,
+        # the second part seems to be the year and month of the initial release.
+        # We only need the first part, which is also used in public
+        # communication by Siemens.
+        try:
+            first_component = vstring.split(" ", 1)[0]
+        except IndexError:
+            first_component = vstring
+
+        super().parse(first_component)
 
 
 class RivieraVersion(LooseVersion):

{cocotb-1.7.2 → cocotb-1.8.0rc1}/cocotb/_version.py

@@ -5,4 +5,4 @@
 # 1) we don't load dependencies by storing it in __init__.py
 # 2) we can import it in setup.py for the same reason
 # 3) we can import it into your module
-__version__ = "1.7.2"
+__version__ = "1.8.0rc1"

{cocotb-1.7.2 → cocotb-1.8.0rc1}/cocotb/clock.py

@@ -29,6 +29,9 @@
 
 import itertools
 import warnings
+from decimal import Decimal
+from numbers import Real
+from typing import Union
 
 from cocotb.log import SimLog
 from cocotb.triggers import Timer
@@ -114,7 +117,9 @@ class Clock(BaseClock):
         Using ``None`` as the *units* argument is deprecated, use ``'step'`` instead.
     """
 
-    def __init__(self, signal, period, units="step"):
+    def __init__(
+        self, signal, period: Union[float, Real, Decimal], units: str = "step"
+    ):
         BaseClock.__init__(self, signal)
         if units is None:
             warnings.warn(
@@ -124,8 +129,8 @@ class Clock(BaseClock):
             )
             units = "step"  # don't propagate deprecated value
         self.period = get_sim_steps(period, units)
-        self.half_period = get_sim_steps(period / 2.0, units)
-        self.frequency = 1.0 / get_time_from_sim_steps(self.period, units="us")
+        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

cocotb-1.8.0rc1/cocotb/decorators.py

@@ -0,0 +1,326 @@
+# 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.
+
+import functools
+import sys
+import typing
+import warnings
+
+import cocotb
+import cocotb.triggers
+from cocotb.log import SimLog
+from cocotb.task import Task as _Task  # noqa: F401
+from cocotb.task import _RunningCoroutine, _RunningTest
+from cocotb.utils import lazy_property
+
+
+def public(f):
+    """Use a decorator to avoid retyping function/class names.
+
+    * Based on an idea by Duncan Booth:
+    http://groups.google.com/group/comp.lang.python/msg/11cbb03e09611b8a
+    * Improved via a suggestion by Dave Angel:
+    http://groups.google.com/group/comp.lang.python/msg/3d400fb22d8a42e1
+    """
+    all = sys.modules[f.__module__].__dict__.setdefault("__all__", [])
+    if f.__name__ not in all:  # Prevent duplicates if run from an IDE.
+        all.append(f.__name__)
+    return f
+
+
+public(public)  # Emulate decorating ourself
+
+
+class coroutine:
+    """Decorator class that allows us to provide common coroutine mechanisms:
+
+    ``log`` methods will log to ``cocotb.coroutine.name``.
+
+    :meth:`~cocotb.task.Task.join` method returns an event which will fire when the coroutine exits.
+
+    Used as ``@cocotb.coroutine``.
+    """
+
+    def __init__(self, func):
+        self._func = func
+        functools.update_wrapper(self, func)
+
+    @lazy_property
+    def log(self):
+        return SimLog(f"cocotb.coroutine.{self._func.__qualname__}.{id(self)}")
+
+    def __call__(self, *args, **kwargs):
+        return _RunningCoroutine(self._func(*args, **kwargs), self)
+
+    def __get__(self, obj, owner=None):
+        """Permit the decorator to be used on class methods
+        and standalone functions"""
+        return type(self)(self._func.__get__(obj, owner))
+
+    def __iter__(self):
+        return self
+
+    def __str__(self):
+        return str(self._func.__qualname__)
+
+
+@public
+class function:
+    """Decorator class that allows a function to block.
+
+    This allows a coroutine that consumes simulation time
+    to be called by a thread started with :class:`cocotb.external`;
+    in other words, to internally block while externally
+    appear to yield.
+    """
+
+    def __init__(self, func):
+        self._coro = cocotb.coroutine(func)
+
+    @lazy_property
+    def log(self):
+        return SimLog(f"cocotb.function.{self._coro.__qualname__}.{id(self)}")
+
+    def __call__(self, *args, **kwargs):
+        return cocotb.scheduler._queue_function(self._coro(*args, **kwargs))
+
+    def __get__(self, obj, owner=None):
+        """Permit the decorator to be used on class methods
+        and standalone functions"""
+        return type(self)(self._coro._func.__get__(obj, owner))
+
+
+@public
+class external:
+    """Decorator to apply to an external function to enable calling from cocotb.
+
+    This turns a normal function that isn't a coroutine into a blocking coroutine.
+    Currently, this creates a new execution thread for each function that is
+    called.
+    Scope for this to be streamlined to a queue in future.
+    """
+
+    def __init__(self, func):
+        self._func = func
+        self._log = SimLog(f"cocotb.external.{self._func.__qualname__}.{id(self)}")
+
+    def __call__(self, *args, **kwargs):
+        return cocotb.scheduler._run_in_executor(self._func, *args, **kwargs)
+
+    def __get__(self, obj, owner=None):
+        """Permit the decorator to be used on class methods
+        and standalone functions"""
+        return type(self)(self._func.__get__(obj, owner))
+
+
+class _decorator_helper(type):
+    """
+    Metaclass that allows a type to be constructed using decorator syntax,
+    passing the decorated function as the first argument.
+
+    So:
+
+        @MyClass(construction, args='go here')
+        def this_is_passed_as_f(...):
+            pass
+
+    ends up calling
+
+        MyClass.__init__(this_is_passed_as_f, construction, args='go here')
+    """
+
+    def __call__(cls, *args, **kwargs):
+        def decorator(f):
+            # fall back to the normal way of constructing an object, now that
+            # we have all the arguments
+            return type.__call__(cls, f, *args, **kwargs)
+
+        return decorator
+
+
+@public
+class test(coroutine, metaclass=_decorator_helper):
+    """
+    Decorator to mark a Callable which returns a Coroutine as a test.
+
+    The test decorator provides a test timeout, and allows us to mark tests as skipped
+    or expecting errors or failures.
+    Tests are evaluated in the order they are defined in a test module.
+
+    Used as ``@cocotb.test(...)``.
+
+    Args:
+        timeout_time (numbers.Real or decimal.Decimal, optional):
+            Simulation time duration before timeout occurs.
+
+            .. versionadded:: 1.3
+
+            .. note::
+                Test timeout is intended for protection against deadlock.
+                Users should use :class:`~cocotb.triggers.with_timeout` if they require a
+                more general-purpose timeout mechanism.
+
+        timeout_unit (str, optional):
+            Units of timeout_time, accepts any units that :class:`~cocotb.triggers.Timer` does.
+
+            .. versionadded:: 1.3
+
+            .. deprecated:: 1.5
+                Using ``None`` as the *timeout_unit* argument is deprecated, use ``'step'`` instead.
+
+        expect_fail (bool, optional):
+            If ``True`` and the test fails a functional check via an ``assert`` statement, :class:`pytest.raises`,
+            :class:`pytest.warns`, or :class:`pytest.deprecated_call` the test is considered to have passed.
+            If ``True`` and the test passes successfully, the test is considered to have failed.
+
+        expect_error (exception type or tuple of exception types, optional):
+            Mark the result as a pass only if one of the exception types is raised in the test.
+            This is primarily for cocotb internal regression use for when a simulator error is expected.
+
+            Users are encouraged to use the following idiom instead::
+
+                @cocotb.test()
+                async def my_test(dut):
+                    try:
+                        await thing_that_should_fail()
+                    except ExceptionIExpect:
+                        pass
+                    else:
+                        assert False, "Exception did not occur"
+
+            .. versionchanged:: 1.3
+                Specific exception types can be expected
+
+            .. deprecated:: 1.5
+                Passing a :class:`bool` value is now deprecated.
+                Pass a specific :class:`Exception` or a tuple of Exceptions instead.
+
+        skip (bool, optional):
+            Don't execute this test as part of the regression. Test can still be run
+            manually by setting :make:var:`TESTCASE`.
+
+        stage (int)
+            Order tests logically into stages, where multiple tests can share a stage.
+            Defaults to 0.
+    """
+
+    _id_count = 0  # used by the RegressionManager to sort tests in definition order
+
+    def __init__(
+        self,
+        f,
+        timeout_time=None,
+        timeout_unit="step",
+        expect_fail=False,
+        expect_error=(),
+        skip=False,
+        stage=0,
+    ):
+
+        if timeout_unit is None:
+            warnings.warn(
+                'Using timeout_unit=None is deprecated, use timeout_unit="step" instead.',
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            timeout_unit = "step"  # don't propagate deprecated value
+        self._id = self._id_count
+        type(self)._id_count += 1
+
+        if timeout_time is not None:
+            co = coroutine(f)
+
+            @functools.wraps(f)
+            async def f(*args, **kwargs):
+                running_co = co(*args, **kwargs)
+
+                try:
+                    res = await cocotb.triggers.with_timeout(
+                        running_co, self.timeout_time, self.timeout_unit
+                    )
+                except cocotb.result.SimTimeoutError:
+                    running_co.kill()
+                    raise
+                else:
+                    return res
+
+        super().__init__(f)
+
+        self.timeout_time = timeout_time
+        self.timeout_unit = timeout_unit
+        self.expect_fail = expect_fail
+        if isinstance(expect_error, bool):
+            warnings.warn(
+                "Passing bool values to `except_error` option of `cocotb.test` is deprecated. "
+                "Pass a specific Exception type instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if expect_error is True:
+            expect_error = (BaseException,)
+        elif expect_error is False:
+            expect_error = ()
+        self.expect_error = expect_error
+        self.skip = skip
+        self.stage = stage
+        self.im_test = True  # For auto-regressions
+        self.name = self._func.__name__
+
+    def __call__(self, *args, **kwargs):
+        inst = self._func(*args, **kwargs)
+        coro = _RunningTest(inst, self)
+        return coro
+
+
+if sys.version_info < (3, 7):
+    Task = _Task
+    RunningTask = _Task
+    RunningCoroutine = _RunningCoroutine
+    RunningTest = _RunningTest
+else:
+
+    def __getattr__(attr: str) -> typing.Any:
+        if attr in ("Task", "RunningTask"):
+            warnings.warn(
+                f"The class {attr} has been renamed to cocotb.task.Task.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            attr = "_Task"
+        elif attr in ("RunningCoroutine", "RunningTest"):
+            warnings.warn(
+                f"The class {attr} is now private. Update all uses to the parent class cocotb.task.Task.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            attr = f"_{attr}"
+        try:
+            return globals()[attr]
+        except KeyError:
+            raise AttributeError(
+                f"module {__name__!r} has no attribute {attr!r}"
+            ) from None

{cocotb-1.7.2 → cocotb-1.8.0rc1}/cocotb/ipython_support.py

@@ -61,7 +61,9 @@ async def embed(user_ns: dict = {}):
     c = load_default_config()
     c.TerminalInteractiveShell.loop_runner = lambda x: _runner(shell, x)
     c.TerminalInteractiveShell.autoawait = True
-
+    # Python3 checks SQLite DB accesses to ensure process ID matches the one that opened the DB and is not propogated
+    # because we launch IPython in a different process, this will cause unnecessary warnings, so disable the PID check
+    c.HistoryAccessor.connection_options = {"check_same_thread": False}
     # create a shell with access to the dut, and cocotb pre-imported
     shell = IPython.terminal.embed.InteractiveShellEmbed(
         user_ns=default_ns,