cocotb 1.9.2__cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl

cocotb/types/logic_array.py

@@ -0,0 +1,298 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+import typing
+
+from cocotb.binary import BinaryRepresentation, BinaryValue
+from cocotb.types.array import Array
+from cocotb.types.logic import Logic, LogicConstructibleT
+from cocotb.types.range import Range
+
+LogicT = typing.TypeVar("LogicT", bound=Logic)
+S = typing.TypeVar("S")
+Self = typing.TypeVar("Self", bound="LogicArray")
+
+
+class LogicArray(Array[Logic]):
+    r"""
+    Fixed-sized, arbitrarily-indexed, array of :class:`cocotb.types.Logic`.
+
+    .. currentmodule:: cocotb.types
+
+    :class:`LogicArray`\ s can be constructed from either iterables of values
+    constructible into :class:`Logic`: like :class:`bool`, :class:`str`, :class:`int`;
+    or from integers.
+    If constructed from a positive integer, an unsigned bit representation is used to
+    construct the :class:`LogicArray`.
+    If constructed from a negative integer, a two's complement bit representation is
+    used.
+    Like :class:`Array`, if no *range* argument is given, it is deduced from the length
+    of the iterable or bit string used to initialize the variable.
+    If a *range* argument is given, but no value,
+    the array is filled with the default value of Logic().
+
+    .. code-block:: python3
+
+        >>> LogicArray("01XZ")
+        LogicArray('01XZ', Range(3, 'downto', 0))
+
+        >>> LogicArray([0, True, "X"])
+        LogicArray('01X', Range(2, 'downto', 0))
+
+        >>> LogicArray(0xA)  # picks smallest range that can fit the value
+        LogicArray('1010', Range(3, 'downto', 0))
+
+        >>> LogicArray(-4, Range(0, "to", 3))  # will sign-extend
+        LogicArray('1100', Range(0, 'to', 3))
+
+        >>> LogicArray(range=Range(0, "to", 3))  # default values
+        LogicArray('XXXX', Range(0, 'to', 3))
+
+    :class:`LogicArray`\ s support the same operations as :class:`Array`;
+    however, it enforces the condition that all elements must be a :class:`Logic`.
+
+    .. code-block:: python3
+
+        >>> la = LogicArray("1010")
+        >>> la[0]                               # is indexable
+        Logic('0')
+
+        >>> la[1:]                              # is slice-able
+        LogicArray('10', Range(1, 'downto', 0))
+
+        >>> Logic("0") in la                    # is a collection
+        True
+
+        >>> list(la)                            # is an iterable
+        [Logic('1'), Logic('0'), Logic('1'), Logic('0')]
+
+    When setting an element or slice, the *value* is first constructed into a
+    :class:`Logic`.
+
+    .. code-block:: python3
+
+        >>> la = LogicArray("1010")
+        >>> la[3] = "Z"
+        >>> la[3]
+        Logic('Z')
+
+        >>> la[2:] = ['X', True, 0]
+        >>> la
+        LogicArray('ZX10', Range(3, 'downto', 0))
+
+    :class:`LogicArray`\ s can be converted into :class:`str`\ s or :class:`int`\ s.
+
+    .. code-block:: python3
+
+        >>> la = LogicArray("1010")
+        >>> la.binstr
+        '1010'
+
+        >>> la.integer          # uses unsigned representation
+        10
+
+        >>> la.signed_integer   # uses two's complement representation
+        -6
+
+    :class:`LogicArray`\ s also support element-wise logical operations: ``&``, ``|``,
+    ``^``, and ``~``.
+
+    .. code-block:: python3
+
+        >>> def big_mux(a: LogicArray, b: LogicArray, sel: Logic) -> LogicArray:
+        ...     s = LogicArray([sel] * len(a))
+        ...     return (a & ~s) | (b & s)
+
+        >>> la = LogicArray("0110")
+        >>> p = LogicArray("1110")
+        >>> sel = Logic('1')        # choose second option
+        >>> big_mux(la, p, sel)
+        LogicArray('1110', Range(3, 'downto', 0))
+
+    Args:
+        value: Initial value for the array.
+        range: Indexing scheme of the array.
+
+    Raises:
+        ValueError: When argument values cannot be used to construct an array.
+        TypeError: When invalid argument types are used.
+    """
+
+    __slots__ = ()
+
+    @typing.overload
+    def __init__(
+        self,
+        value: typing.Union[int, typing.Iterable[LogicConstructibleT], BinaryValue],
+        range: typing.Optional[Range],
+    ):
+        ...
+
+    @typing.overload
+    def __init__(
+        self,
+        value: typing.Union[
+            int, typing.Iterable[LogicConstructibleT], BinaryValue, None
+        ],
+        range: Range,
+    ):
+        ...
+
+    def __init__(
+        self,
+        value: typing.Union[
+            int, typing.Iterable[LogicConstructibleT], BinaryValue, None
+        ] = None,
+        range: typing.Optional[Range] = None,
+    ) -> None:
+        if value is None and range is None:
+            raise ValueError(
+                "at least one of the value and range input parameters must be given"
+            )
+        if value is None:
+            self._value = [Logic() for _ in range]
+        elif isinstance(value, int):
+            if value < 0:
+                bitlen = int.bit_length(value + 1) + 1
+            else:
+                bitlen = max(1, int.bit_length(value))
+            if range is None:
+                self._value = [Logic(v) for v in _int_to_bitstr(value, bitlen)]
+            else:
+                if bitlen > len(range):
+                    raise ValueError(f"{value} will not fit in {range}")
+                self._value = [Logic(v) for v in _int_to_bitstr(value, len(range))]
+        elif isinstance(value, typing.Iterable):
+            self._value = [Logic(v) for v in value]
+        elif isinstance(value, BinaryValue):
+            self._value = [Logic(v) for v in value.binstr]
+        else:
+            raise TypeError(
+                f"cannot construct {type(self).__qualname__} from value of type {type(value).__qualname__}"
+            )
+        if range is None:
+            self._range = Range(len(self._value) - 1, "downto", 0)
+        else:
+            self._range = range
+        if len(self._value) != len(self._range):
+            raise ValueError(
+                f"value of length {len(self._value)} will not fit in {self._range}"
+            )
+
+    @property
+    def binstr(self) -> str:
+        return "".join(str(bit) for bit in self)
+
+    @property
+    def is_resolvable(self) -> bool:
+        return all(bit in (Logic(0), Logic(1)) for bit in self)
+
+    @property
+    def integer(self) -> int:
+        value = 0
+        for bit in self:
+            value = value << 1 | int(bit)
+        return value
+
+    @property
+    def signed_integer(self) -> int:
+        value = self.integer
+        if value >= (1 << (len(self) - 1)):
+            value -= 1 << len(self)
+        return value
+
+    @typing.overload
+    def __setitem__(self, item: int, value: LogicConstructibleT) -> None:
+        ...
+
+    @typing.overload
+    def __setitem__(
+        self, item: slice, value: typing.Iterable[LogicConstructibleT]
+    ) -> None:
+        ...
+
+    def __setitem__(
+        self,
+        item: typing.Union[int, slice],
+        value: typing.Union[LogicConstructibleT, typing.Iterable[LogicConstructibleT]],
+    ) -> None:
+        if isinstance(item, int):
+            super().__setitem__(item, Logic(typing.cast(LogicConstructibleT, value)))
+        elif isinstance(item, slice):
+            super().__setitem__(
+                item,
+                (
+                    Logic(v)
+                    for v in typing.cast(typing.Iterable[LogicConstructibleT], value)
+                ),
+            )
+        else:
+            raise TypeError(
+                f"indexes must be ints or slices, not {type(item).__name__}"
+            )
+
+    def __repr__(self) -> str:
+        return "{}({!r}, {!r})".format(type(self).__qualname__, self.binstr, self.range)
+
+    def __and__(self: Self, other: Self) -> Self:
+        if isinstance(other, type(self)):
+            if len(self) != len(other):
+                raise ValueError(
+                    f"cannot perform bitwise & "
+                    f"between {type(self).__qualname__} of length {len(self)} "
+                    f"and {type(other).__qualname__} of length {len(other)}"
+                )
+            return type(self)(a & b for a, b in zip(self, other))  # type: ignore
+        return NotImplemented
+
+    def __rand__(self: Self, other: Self) -> Self:
+        return self & other
+
+    def __or__(self: Self, other: Self) -> Self:
+        if isinstance(other, type(self)):
+            if len(self) != len(other):
+                raise ValueError(
+                    f"cannot perform bitwise | "
+                    f"between {type(self).__qualname__} of length {len(self)} "
+                    f"and {type(other).__qualname__} of length {len(other)}"
+                )
+            return type(self)(a | b for a, b in zip(self, other))  # type: ignore
+        return NotImplemented
+
+    def __ror__(self: Self, other: Self) -> Self:
+        return self | other
+
+    def __xor__(self: Self, other: Self) -> Self:
+        if isinstance(other, type(self)):
+            if len(self) != len(other):
+                raise ValueError(
+                    f"cannot perform bitwise ^ "
+                    f"between {type(self).__qualname__} of length {len(self)} "
+                    f"and {type(other).__qualname__} of length {len(other)}"
+                )
+            return type(self)(a ^ b for a, b in zip(self, other))  # type: ignore
+        return NotImplemented
+
+    def __rxor__(self: Self, other: Self) -> Self:
+        return self ^ other
+
+    def __invert__(self: Self) -> Self:
+        return type(self)(~v for v in self)
+
+    def to_BinaryValue(
+        self,
+        bigEndian: bool = True,
+        binaryRepresentation: BinaryRepresentation = BinaryRepresentation.UNSIGNED,
+    ) -> BinaryValue:
+        return BinaryValue(
+            value=self.binstr,
+            n_bits=len(self),
+            bigEndian=bigEndian,
+            binaryRepresentation=binaryRepresentation,
+        )
+
+
+def _int_to_bitstr(value: int, n_bits: int) -> str:
+    if value < 0:
+        value += 1 << n_bits
+    return format(value, f"0{n_bits}b")

cocotb/types/range.py

@@ -0,0 +1,198 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+import typing
+
+T = typing.TypeVar("T")
+
+
+class Range(typing.Sequence[int]):
+    r"""
+    Variant of :class:`range` with inclusive right bound.
+
+    In Python, :class:`range` and :class:`slice` have a non-inclusive right bound.
+    In both Verilog and VHDL, ranges and arrays have an inclusive right bound.
+    This type mimics Python's :class:`range` type, but implements HDL-like inclusive right bounds,
+    using the names :attr:`left` and :attr:`right` as replacements for ``start`` and ``stop`` to
+    match VHDL.
+    Range directionality can be specified using ``'to'`` or ``'downto'`` between the
+    left and right bounds.
+    Not specifying directionality will cause the directionality to be inferred.
+
+    .. code-block:: python3
+
+        >>> r = Range(-2, 3)
+        >>> r.left, r.right, len(r)
+        (-2, 3, 6)
+
+        >>> s = Range(8, 'downto', 1)
+        >>> s.left, s.right, len(s)
+        (8, 1, 8)
+
+    :meth:`from_range` and :meth:`to_range` can be used to convert from and to :class:`range`.
+
+    .. code-block:: python3
+
+        >>> r = Range(-2, 3)
+        >>> r.to_range()
+        range(-2, 4)
+
+    :class:`Range` supports "null" ranges as seen in VHDL.
+    "null" ranges occur when a left bound cannot reach a right bound with the given direction.
+    They have a length of 0, but the :attr:`left`, :attr:`right`, and :attr:`direction` values remain as given.
+
+    .. code-block:: python3
+
+        >>> r = Range(1, 'to', 0)  # no way to count from 1 'to' 0
+        >>> r.left, r.direction, r.right
+        (1, 'to', 0)
+        >>> len(r)
+        0
+
+    .. note::
+        This is only possible when specifying the direction.
+
+    Ranges also support all the features of :class:`range` including, but not limited to:
+
+    - ``value in range`` to see if a value is in the range,
+    - ``range.index(value)`` to see what position in the range the value is,
+
+    The typical use case of this type is in conjunction with :class:`~cocotb.types.Array`.
+
+    Args:
+        left: leftmost bound of range
+        direction: ``'to'`` if values are ascending, ``'downto'`` if descending
+        right: rightmost bound of range (inclusive)
+    """
+
+    __slots__ = ("_range",)
+
+    @typing.overload
+    def __init__(self, left: int, direction: int) -> None:
+        pass  # pragma: no cover
+
+    @typing.overload
+    def __init__(self, left: int, direction: str, right: int) -> None:
+        pass  # pragma: no cover
+
+    @typing.overload
+    def __init__(self, left: int, *, right: int) -> None:
+        pass  # pragma: no cover
+
+    def __init__(
+        self,
+        left: int,
+        direction: typing.Union[int, str, None] = None,
+        right: typing.Union[int, None] = None,
+    ) -> None:
+        start = left
+        stop: int
+        step: int
+        if isinstance(direction, int) and right is None:
+            step = _guess_step(left, direction)
+            stop = direction + step
+        elif direction is None and isinstance(right, int):
+            step = _guess_step(left, right)
+            stop = right + step
+        elif isinstance(direction, str) and isinstance(right, int):
+            step = _direction_to_step(direction)
+            stop = right + step
+        else:
+            raise TypeError("invalid arguments")
+        self._range = range(start, stop, step)
+
+    @classmethod
+    def from_range(cls, range: range) -> "Range":
+        """Convert :class:`range` to :class:`Range`."""
+        return cls(
+            left=range.start,
+            direction=_step_to_direction(range.step),
+            right=(range.stop - range.step),
+        )
+
+    def to_range(self) -> range:
+        """Convert :class:`Range` to :class:`range`."""
+        return self._range
+
+    @property
+    def left(self) -> int:
+        """Leftmost value in a range."""
+        return self._range.start
+
+    @property
+    def direction(self) -> str:
+        """``'to'`` if values are meant to be ascending, ``'downto'`` otherwise."""
+        return _step_to_direction(self._range.step)
+
+    @property
+    def right(self) -> int:
+        """Rightmost value in a range."""
+        return self._range.stop - self._range.step
+
+    def __len__(self) -> int:
+        return len(self._range)
+
+    @typing.overload
+    def __getitem__(self, item: int) -> int:
+        pass  # pragma: no cover
+
+    @typing.overload
+    def __getitem__(self, item: slice) -> "Range":
+        pass  # pragma: no cover
+
+    def __getitem__(self, item: typing.Union[int, slice]) -> typing.Union[int, "Range"]:
+        if isinstance(item, int):
+            return self._range[item]
+        elif isinstance(item, slice):
+            return type(self).from_range(self._range[item])
+        raise TypeError(
+            "indices must be integers or slices, not {}".format(type(item).__name__)
+        )
+
+    def __contains__(self, item: object) -> bool:
+        return item in self._range
+
+    def __iter__(self) -> typing.Iterator[int]:
+        return iter(self._range)
+
+    def __reversed__(self) -> typing.Iterator[int]:
+        return reversed(self._range)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, type(self)):
+            return self._range == other._range
+        return NotImplemented  # must not be in a type narrowing context to be ignored properly
+
+    def __hash__(self) -> int:
+        return hash(self._range)
+
+    def count(self, item: int) -> int:
+        return self._range.count(item)
+
+    def __repr__(self) -> str:
+        return "{}({!r}, {!r}, {!r})".format(
+            type(self).__qualname__, self.left, self.direction, self.right
+        )
+
+
+def _guess_step(left: int, right: int) -> int:
+    if left <= right:
+        return 1
+    return -1
+
+
+def _direction_to_step(direction: str) -> int:
+    direction = direction.lower()
+    if direction == "to":
+        return 1
+    elif direction == "downto":
+        return -1
+    raise ValueError("direction must be 'to' or 'downto'")
+
+
+def _step_to_direction(step: int) -> str:
+    if step == 1:
+        return "to"
+    elif step == -1:
+        return "downto"
+    raise ValueError("step must be 1 or -1")