Reference¶

Abstract Types¶

Abstract Base Classes and Protocols for enforcing or checking type capabilities.

class AbstractConstArray(*args, **kwargs)¶

A type-generic fixed-length Sequence-like type with an arbitrary indexing scheme.

Type-generic over the element type, which is covariant. Uses a Range to describe the array’s indexing scheme. Supports most of the same features as Sequence.

abstract property range: Range¶: Returns the Range object that describes the array’s indexing scheme

property left: int¶: Returns the left index bound of the array

property right: int¶: Returns the right index bound of the array

property direction: str¶: Returns the direction (‘to’ or ‘downto’) of the indexes of the array

class AbstractArray(*args, **kwargs)¶

A mutable version of AbstractConstArray.

Type-generic over the element type, which is invariant. Adds support for setting indexes.

class Number(*args, **kwargs)¶

Protocol for number-like types that support arithmetic operations.

Specifically designed to allow writing generic functions that work with int, float, Unsigned, Signed, Ufixed, Sfixed, or Float.

class Integer(*args, **kwargs)¶

Protocol for integer-like types that support arithmetic and bitwise logical operations.

Integers are Numbers that support bitwise logical operators and shifting. Specifically designed to allow writing generic functions that work with int, Unsigned, and Signed.

Logic Types¶

Value types that implement the Logic protocol.

class StdLogic(value: Union[str, StdLogic])¶

A 9-value logic type

The values of this types are: U, X, 0, 1, Z, W, L, H, and -. The value and semantics of this type are defined in IEEE 1164 and are similar to the std_ulogic type in VHDL.

StdLogics are constructable from string literals or are copy constructable from any subclass.

>>> StdLogic("z")  # construct from (lowercase) str
StdLogic('Z')
>>> StdLogic(X01Z("Z"))  # convert subtype
StdLogic('Z')

StdLogics support logical operations &, |, ^, and ~. They can be used in logical operations with subtypes, which will return the widest of the two types.

>>> StdLogic("0") | StdLogic("X")
StdLogic('X')
>>> Bit("0") ^ StdLogic("1")
StdLogic('1')
>>> ~StdLogic("L")
StdLogic('1')

StdLogic supports creating subtypes (like X01Z and Bit); see the module file for more details. Values of a subtype of StdLogic will hash the same and equate, so that they behave as proper subtypes. This results in what may seem like atypical behavior, but it is type-safe.

>>> StdLogic("0") == Bit("0")  # subtypes equate
True
>>> a = {StdLogic("0")}
>>> Bit("0") in a        # subtypes are substitutable in hashed collections
True
>>> isinstance(Bit("0"), StdLogic)  # subtypes pass isinstance checks
True

class X01Z(value: Union[str, StdLogic])¶

A 4-value logic type

A subtype of StdLogic; supporting all the same operations, but only the values X, 0, 1, and Z. Similar to X01Z from VHDL, or logic from Verilog.

class Bit(value: Union[str, StdLogic])¶

A 2-value logic type

A subtype of StdLogic and X01Z; supporting all the same operations, but only the values 0 and 1. Similar to bit from VHDL or Verilog, or bool.

Array and Range Types¶

class Range(left: int, direction: str, right: int)¶

class Range(left: int, right: int)

Integer range with inclusive right bound.

This type mimics Python’s range type, but uses inclusive right bounds as seen in VHDL and Verilog. The attributes left and right are used instead of start and stop to mimic VHDL. Range direction can be specified using 'to' or 'downto' between the left and right bounds. Not specifying a direction will cause the direction to be inferred.

>>> 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)

from_range() and to_range() can be used to convert from and to range.

>>> py_range = range(-2, 4)
>>> hdl_range = Range.from_range(py_range)
>>> hdl_range.to_range()
range(-2, 4)

“Null” ranges, as seen in VHDL, occur when a left bound cannot reach a right bound in the given direction. They have a length of 0, but the left, right, and direction values remain as given.

>>> 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

Null ranges are only possible when specifying the direction.

Ranges implement all the features of Sequence protocol and are hashable and equatable.

>>> r = Range(-2, 2)

>>> 4 in r  # is '4' in the Range?
False
>>> r.index(0)  # what position in the Range is '0'?
2
>>> r[2]  # what value is at position 2 in the Range?
0
>>> r.count(0)  # how many '0's are in the Range?
1

>>> s = {Range(0, 10)}       # Ranges are hashable
>>> Range(0, 'to', 10) in s  # and equatable
True

Args:: left: leftmost bound of range direction: 'to' if values are ascending, 'downto' if descending right: rightmost bound of range (inclusive)

classmethod from_range(range: range) → Range¶: Construct from a range

to_range() → range¶: Convert to range

property left: int¶: The leftmost value in a Range

property direction: str¶: 'to' if values are meant to be ascending, 'downto' otherwise.

property right: int¶: The rightmost value in a Range

class ConstArray(value: Iterable[hdltypes.array.T_co], range: Optional[Range] = None)¶: Immutable version of Array.

class Array(value: Iterable[hdltypes.array.T_co], range: Optional[Range] = None)¶

Type-generic fixed-length mutable sequence type.

Arrays are capable of holding any type. Like list and tuple, they are initialized with any iterable.

>>> Array([123, 456])
Array([123, 456], Range(0, 'to', 1))
>>> Array("abc")
Array(['a', 'b', 'c'], Range(0, 'to', 2))

Unlike list and tuple, arrays can use arbitrary indexing scheme; not just 0 to length-1. The indexing scheme is described using a Range. The left most index of the array is the first value of the range. The right most index of the array is the last value of the range. If no range is given, it is defaulted to Range(0, 'to', len(value) - 1).

>>> a = Array("abcd", Range(4, "downto", 1))
>>> a[4]
'a'
>>> a[1]
'd'

Slicing an array returns a new array with the specified indexes. Right bounds in slices are inclusive, just like ranges. If no left bound is given, it is assumed to be the left-most index. If no right bound is give, it is assumed to be the right-most index.

>>> a = Array([0, 1, 2, "a", "b", "c"])
>>> a[2:4]
Array([2, 'a', 'b'], Range(2, 'to', 4))
>>> a[:2]
Array([0, 1, 2], Range(0, 'to', 2))
>>> a[5:]
Array(['c'], Range(5, 'to', 5))

Arrays have a fixed size once created, but the elements of the array can be changed. Setting a slice requires the new value be an iterable with the same length as the slice.

>>> a = Array("abcd", Range(4, "downto", 1))
>>> a[2] = 8
>>> a
Array(['a', 'b', 8, 'd'], Range(4, 'downto', 1))
>>> a[:] = [1, 2, 3, 4]
>>> a
Array([1, 2, 3, 4], Range(4, 'downto', 1))

Arrays are a lot like Python’s list type and support many of the same operations, including: len(), iteration, reverse iteration, and testing a value for inclusion in the array, equality, and more.

>>> a = Array("1234")
>>> len(a)
4
>>> list(a)
['1', '2', '3', '4']
>>> a[:] = reversed(a)
>>> a
Array(['4', '3', '2', '1'], Range(0, 'to', 3))
>>> '3' in a
True
>>> Array("123") == Array("123", Range(2, 'downto', 0))  # range doesn't matter for equality
True

Arrays support concatenation with other arrays.

>>> Array("123") + Array("456")
Array(['1', '2', '3', '4', '5', '6'], Range(0, 'to', 5))

Warning

Arrays are not sequences because they do not assume 0-based indexing. Beware passing arrays to any function that take sequences.

Args:

value: any iterable to initialize the array.
range: the indexing scheme to use with the array, defaults to Range(0, 'to', len(value) - 1).

property direction: str¶: Returns the direction (‘to’ or ‘downto’) of the indexes of the array

property left: int¶: Returns the left index bound of the array

property range: Range¶: Returns the Range object that describes the array’s indexing scheme

property right: int¶: Returns the right index bound of the array

Logic Array Types¶

class ConstLogicArrayBase(value: Union[str, Iterable[StdLogic]], range: Optional[Range] = None)¶: Immutable version of LogicArrayBase.

class LogicArrayBase(value: Union[str, Iterable[StdLogic]], range: Optional[Range] = None)¶

Bases: hdltypes.logic_array.ConstLogicArrayBase[hdltypes.logic_array.LogicT], hdltypes.array.Array[hdltypes.logic_array.LogicT]

Generic Array of StdLogic which supports bitwise logic operators.

This class is a partial specialization of Array limiting the element type to subtypes of StdLogic. This specialization adds support for bitwise logical operators between two arrays, and construction from literals on construction and when setting indexes.

>>> a = StdLogicArray("01XZ")
>>> a
StdLogicArray('01XZ', Range(0, 'to', 3))
>>> a & StdLogicArray("1101")
StdLogicArray('010X', Range(0, 'to', 3))

Bitwise logical operators and concatenation between logical subtypes is also supported, which will return the widest of the two types.

>>> StdLogicArray("01XZ") | BitArray("1101")
StdLogicArray('11X1', Range(0, 'to', 3))

This type cannot be directly used, use the concrete specializations: StdLogicArray, X01ZArray and BitArray. Creating additional subtypes is supported; see the module file for details.

property direction: str¶: Returns the direction (‘to’ or ‘downto’) of the indexes of the array

property left: int¶: Returns the left index bound of the array

property range: Range¶: Returns the Range object that describes the array’s indexing scheme

property right: int¶: Returns the right index bound of the array

class StdLogicArray(value: Union[str, Iterable[StdLogic]], range: Optional[Range] = None)¶: Bases: hdltypes.logic_array.LogicArrayBase[hdltypes.logic.StdLogic]

class X01ZArray(value: Union[str, Iterable[StdLogic]], range: Optional[Range] = None)¶: Bases: hdltypes.logic_array.LogicArrayBase[hdltypes.logic.X01Z]

class BitArray(value: Union[str, Iterable[StdLogic]], range: Optional[Range] = None)¶: Bases: hdltypes.logic_array.LogicArrayBase[hdltypes.logic.Bit]