cocotb 2.0.0b1__cp313-cp313-win32.whl → 2.0.0rc2__cp313-cp313-win32.whl

cocotb/simtime.py

@@ -0,0 +1,230 @@
+# 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
+
+"""Tools for dealing with simulated time."""
+
+import warnings
+from decimal import Decimal
+from fractions import Fraction
+from functools import lru_cache
+from math import ceil, floor
+from typing import Union, cast, overload
+
+from cocotb import simulator
+from cocotb._py_compat import Literal, TypeAlias
+from cocotb._typing import RoundMode, TimeUnit
+
+__all__ = (
+    "convert",
+    "get_sim_time",
+    "time_precision",
+)
+
+
+Steps: TypeAlias = Literal["step"]
+TimeUnitWithoutSteps: TypeAlias = Literal["fs", "ps", "ns", "us", "ms", "sec"]
+
+
+@overload
+def convert(
+    value: Union[float, Fraction, Decimal],
+    unit: TimeUnit,
+    *,
+    to: Steps,
+    round_mode: RoundMode = "error",
+) -> int: ...
+
+
+@overload
+def convert(
+    value: Union[float, Fraction, Decimal],
+    unit: TimeUnit,
+    *,
+    to: TimeUnitWithoutSteps,
+    round_mode: RoundMode = "error",
+) -> float: ...
+
+
+def convert(
+    value: Union[float, Decimal, Fraction],
+    unit: TimeUnit,
+    *,
+    to: TimeUnit,
+    round_mode: RoundMode = "error",
+) -> float:
+    """Convert time values from one unit to another unit.
+
+    Args:
+        value: The time value.
+
+        unit: The unit of *value* (one of ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``).
+
+        to: The unit to convert *value* to (one of ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``).
+
+        round_mode:
+            How to handle non-integral step values (one of ``'error'``, ``'round'``, ``'ceil'``, ``'floor'``).
+
+            When *round_mode* is ``"error"``, a :exc:`ValueError` is thrown if the value cannot
+            be accurately represented in terms of simulator time steps.
+            When *round_mode* is ``"round"``, ``"ceil"``, or ``"floor"``, the corresponding
+            rounding function from the standard library will be used to round to a simulator
+            time step.
+
+    Returns:
+        The value scaled by the difference in units.
+
+    .. versionadded:: 2.0
+    """
+    if unit == "step":
+        steps = cast("int", value)
+    else:
+        steps = _get_sim_steps(value, unit, round_mode=round_mode)
+    if to == "step":
+        return steps
+    else:
+        return _get_time_from_sim_steps(steps, to)
+
+
+def get_sim_time(unit: TimeUnit = "step", *, units: None = None) -> float:
+    """Retrieve the simulation time from the simulator.
+
+    Args:
+        unit: String specifying the unit of the result
+            (one of ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``).
+            ``'step'`` will return the raw simulation time.
+
+            .. versionchanged:: 2.0
+                Passing ``None`` as the *unit* argument was removed, use ``'step'`` instead.
+
+            .. versionchanged:: 2.0
+                Renamed from ``units``.
+
+    Raises:
+        ValueError: If *unit* is not a valid unit.
+
+    Returns:
+        The simulation time in the specified unit.
+
+    .. versionchanged:: 1.6
+        Support ``'step'`` as the the *unit* argument to mean "simulator time step".
+
+    .. versionchanged:: 2.0
+        Moved from :mod:`cocotb.utils` to :mod:`cocotb.simtime`.
+    """
+    if units is not None:
+        warnings.warn(
+            "The 'units' argument has been renamed to 'unit'.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        unit = units
+    timeh, timel = simulator.get_sim_time()
+    steps = timeh << 32 | timel
+    return _get_time_from_sim_steps(steps, unit) if unit != "step" else steps
+
+
+@overload
+def _ldexp10(frac: float, exp: int) -> float: ...
+
+
+@overload
+def _ldexp10(frac: Fraction, exp: int) -> Fraction: ...
+
+
+@overload
+def _ldexp10(frac: Decimal, exp: int) -> Decimal: ...
+
+
+def _ldexp10(
+    frac: Union[float, Fraction, Decimal], exp: int
+) -> Union[float, Fraction, Decimal]:
+    """Like :func:`math.ldexp`, but base 10."""
+    # using * or / separately prevents rounding errors if `frac` is a
+    # high-precision type
+    if exp > 0:
+        return frac * (10**exp)
+    else:
+        return frac / (10**-exp)
+
+
+def _get_time_from_sim_steps(
+    steps: int,
+    unit: TimeUnit,
+) -> float:
+    if unit == "step":
+        return steps
+    return _ldexp10(steps, time_precision - _get_log_time_scale(unit))
+
+
+def _get_sim_steps(
+    time: Union[float, Fraction, Decimal],
+    unit: TimeUnit = "step",
+    *,
+    round_mode: RoundMode = "error",
+) -> int:
+    result: Union[float, Fraction, Decimal]
+    if unit != "step":
+        result = _ldexp10(time, _get_log_time_scale(unit) - time_precision)
+    else:
+        result = time
+
+    if round_mode == "error":
+        result_rounded = floor(result)
+        if result_rounded != result:
+            raise ValueError(
+                f"Unable to accurately represent {time}({unit}) with the simulator precision of 1e{time_precision}"
+            )
+    elif round_mode == "ceil":
+        result_rounded = ceil(result)
+    elif round_mode == "round":
+        result_rounded = round(result)
+    elif round_mode == "floor":
+        result_rounded = floor(result)
+    else:
+        raise ValueError(f"Invalid round_mode specifier: {round_mode}")
+
+    return result_rounded
+
+
+@lru_cache(maxsize=None)
+def _get_log_time_scale(unit: TimeUnitWithoutSteps) -> int:
+    """Retrieve the ``log10()`` of the scale factor for a given time unit.
+
+    Args:
+        unit: String specifying the unit
+            (one of ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``).
+
+            .. versionchanged:: 2.0
+                Renamed from ``units``.
+
+    Raises:
+        ValueError: If *unit* is not a valid unit.
+
+    Returns:
+        The ``log10()`` of the scale factor for the time unit.
+    """
+    scale = {"fs": -15, "ps": -12, "ns": -9, "us": -6, "ms": -3, "sec": 0}
+
+    unit_lwr = unit.lower()
+    if unit_lwr not in scale:
+        raise ValueError(f"Invalid unit ({unit}) provided")
+    else:
+        return scale[unit_lwr]
+
+
+time_precision: int = _get_log_time_scale("fs")
+"""The precision of time in the current simulation.
+
+The value is seconds in powers of tens,
+i.e. ``-15`` is ``10**-15`` seconds or 1 femtosecond.
+
+.. versionadded:: 2.0
+"""
+
+
+def _init() -> None:
+    global time_precision
+    time_precision = simulator.get_precision()

cocotb/task.py

@@ -4,13 +4,13 @@
 import collections.abc
 import inspect
 import logging
-import os
 import traceback
 from asyncio import CancelledError, InvalidStateError
 from bdb import BdbQuit
 from enum import auto
-from types import CoroutineType
+from types import SimpleNamespace
 from typing import (
+    TYPE_CHECKING,
     Callable,
     Coroutine,
     Generator,
@@ -30,12 +30,8 @@ from cocotb._outcomes import Error, Outcome, Value
 from cocotb._py_compat import Self, cached_property
 from cocotb._utils import DocEnum, extract_coro_stack, remove_traceback_frames
 
-#: Task result type
-ResultType = TypeVar("ResultType")
-
-# Sadly the Python standard logging module is very slow so it's better not to
-# make any calls by testing a boolean flag first
-_debug = "COCOTB_SCHEDULER_DEBUG" in os.environ
+if TYPE_CHECKING:
+    from types import CoroutineType
 
 
 __all__ = (
@@ -51,6 +47,9 @@ __all__ = (
 bridge.__module__ = __name__
 resume.__module__ = __name__
 
+#: Task result type
+ResultType = TypeVar("ResultType")
+
 
 class _TaskState(DocEnum):
     """State of a Task."""
@@ -83,6 +82,7 @@ class Task(Generic[ResultType]):
     def __init__(
         self, inst: Coroutine[Trigger, None, ResultType], *, name: Optional[str] = None
     ) -> None:
+        self._native_coroutine: bool
         if inspect.iscoroutinefunction(inst):
             raise TypeError(
                 f"Coroutine function {inst} should be called prior to being scheduled."
@@ -92,7 +92,11 @@ class Task(Generic[ResultType]):
                 f"{inst.__qualname__} is an async generator, not a coroutine. "
                 "You likely used the yield keyword instead of await."
             )
-        elif not isinstance(inst, collections.abc.Coroutine):
+        elif inspect.iscoroutine(inst):
+            self._native_coroutine = True
+        elif isinstance(inst, collections.abc.Coroutine):
+            self._native_coroutine = False
+        else:
             raise TypeError(f"{inst} isn't a valid coroutine!")
 
         self._coro = inst
@@ -102,11 +106,40 @@ class Task(Generic[ResultType]):
         self._done_callbacks: List[Callable[[Task[ResultType]], None]] = []
         self._cancelled_msg: Union[str, None] = None
         self._must_cancel: bool = False
+        self._locals = SimpleNamespace()
 
         self._task_id = self._id_count
         type(self)._id_count += 1
         self._name = f"Task {self._task_id}" if name is None else name
 
+    @property
+    def locals(self) -> SimpleNamespace:
+        '''Task-local variables.
+
+        A modifiable namespace where any user-defined variables can be added.
+        Use :func:`~cocotb.task.current_task` to access the current Task's locals.
+
+        .. code-block:: python
+
+            def get_rng() -> random.Random:
+                """Get the random number generator for the current Task."""
+                try:
+                    return current_task().locals.rng
+                except AttributeError:
+                    rng = random.Random()
+                    current_task().locals.rng = rng
+                    return rng
+
+
+            # Use Task-local RNG to drive a signal
+            rng = get_rng()
+            for _ in range(10):
+                await drive(rng.randint(0, 100))
+
+        .. versionadded:: 2.0
+        '''
+        return self._locals
+
     def get_name(self) -> str:
         """Return the name of the :class:`!Task`.
 
@@ -132,7 +165,12 @@ class Task(Generic[ResultType]):
 
     @cached_property
     def _log(self) -> logging.Logger:
-        return logging.getLogger(f"cocotb.{self._name}.{self._coro.__qualname__}")
+        coro_name: str
+        if self._native_coroutine:
+            coro_name = self._coro.__qualname__
+        else:
+            coro_name = type(self._coro).__qualname__
+        return logging.getLogger(f"cocotb.{self._name}.{coro_name}")
 
     def __str__(self) -> str:
         # TODO Do we really need this?
@@ -146,6 +184,11 @@ class Task(Generic[ResultType]):
         Raises:
             TypeError: If :attr:`_coro` is not a native Python coroutine object.
         """
+        if not self._native_coroutine:
+            raise TypeError(
+                "Task._get_coro_stack() can only be called on native Python coroutines."
+            )
+
         coro_stack = extract_coro_stack(
             cast("CoroutineType[Trigger, None, ResultType]", self._coro)
         )
@@ -157,7 +200,7 @@ class Task(Generic[ResultType]):
         return coro_stack
 
     def __repr__(self) -> str:
-        if inspect.iscoroutine(self._coro):
+        if self._native_coroutine:
             coro_stack = self._get_coro_stack()
             try:
                 coro_name = coro_stack[-1].name

cocotb/types/__init__.py

@@ -3,7 +3,8 @@
 # SPDX-License-Identifier: BSD-3-Clause
 from ._abstract_array import AbstractArray, AbstractMutableArray
 from ._array import Array
-from ._logic import Logic
+from ._indexing import IndexingChangedWarning
+from ._logic import Bit, Logic
 from ._logic_array import LogicArray
 from ._range import Range
 
@@ -17,6 +18,8 @@ __all__ = (
     "AbstractArray",
     "AbstractMutableArray",
     "Array",
+    "Bit",
+    "IndexingChangedWarning",
     "Logic",
     "LogicArray",
     "Range",

cocotb/types/_array.py

@@ -1,9 +1,12 @@
 # Copyright cocotb contributors
 # Licensed under the Revised BSD License, see LICENSE for details.
 # SPDX-License-Identifier: BSD-3-Clause
-from typing import Iterable, Iterator, List, TypeVar, Union, cast, overload
+import copy
+import warnings
+from typing import Any, Dict, Iterable, Iterator, List, TypeVar, Union, cast, overload
 
 from cocotb.types._abstract_array import AbstractMutableArray
+from cocotb.types._indexing import IndexingChangedWarning
 from cocotb.types._range import Range
 
 T = TypeVar("T")
@@ -131,9 +134,12 @@ class Array(AbstractMutableArray[T]):
         TypeError: When invalid argument types are used.
     """
 
+    __slots__ = ("_value", "_range", "_warn_indexing")
+
     def __init__(
         self, value: Iterable[T], range: Union[Range, int, None] = None
     ) -> None:
+        self._warn_indexing = False
         self._value = list(value)
         if range is None:
             self._range = Range(0, "to", len(self._value) - 1)
@@ -153,8 +159,11 @@ class Array(AbstractMutableArray[T]):
                 )
 
     @classmethod
-    def _from_handle(cls, value: List[T], range: Range) -> "Array[T]":
+    def _from_handle(
+        cls, value: List[T], range: Range, warn_indexing: bool
+    ) -> "Array[T]":
         self = cls.__new__(cls)
+        self._warn_indexing = warn_indexing
         self._value = value
         self._range = range
         return self
@@ -202,9 +211,23 @@ class Array(AbstractMutableArray[T]):
 
     def __getitem__(self, item: Union[int, slice]) -> Union[T, "Array[T]"]:
         if isinstance(item, int):
+            if self._warn_indexing:
+                warnings.warn(
+                    f"Update index {item} to {self.range[item]}",
+                    IndexingChangedWarning,
+                    stacklevel=2,
+                )
             idx = self._translate_index(item)
             return self._value[idx]
         elif isinstance(item, slice):
+            if self._warn_indexing:
+                start = item.start if item.start is not None else 0
+                stop = item.stop if item.stop is not None else len(self) - 1
+                warnings.warn(
+                    f"Update slice {start}:{stop} to {self.range[start]}:{self.range[stop]}",
+                    IndexingChangedWarning,
+                    stacklevel=2,
+                )
             start = item.start if item.start is not None else self.left
             stop = item.stop if item.stop is not None else self.right
             if item.step is not None:
@@ -262,3 +285,11 @@ class Array(AbstractMutableArray[T]):
             return self._range.index(item)
         except ValueError:
             raise IndexError(f"index {item} out of range") from None
+
+    def __copy__(self) -> "Array":
+        return Array(self._value, self._range)
+
+    def __deepcopy__(self, memo: Dict[int, Any]) -> "Array":
+        return Array(
+            copy.deepcopy(self._value, memo=memo), copy.deepcopy(self._range, memo=memo)
+        )

cocotb/types/_indexing.py

@@ -0,0 +1,17 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+import os
+
+from cocotb.types._range import Range
+
+do_indexing_changed_warning = os.environ.get("COCOTB_INDEXING_CHANGED_WARNING")
+
+
+def indexing_changed(range: Range) -> bool:
+    return not (range.left == 0 and range.direction == "to")
+
+
+class IndexingChangedWarning(UserWarning):
+    """Warning issued when a value is indexed in a way that is different between cocotb 1.x and 2.x."""