Abstract Syntax Tree¶

torii.hdl.ast.AnyConst(shape, *, src_loc_at: int = 0) → AnyValue¶

Return type:: AnyValue

Todo

Document Me

torii.hdl.ast.AnySeq(shape, *, src_loc_at: int = 0) → AnyValue¶

Return type:: AnyValue

Todo

Document Me

class torii.hdl.ast.Array(iterable: Sequence[Value] = ()) → None¶

Addressable multiplexer.

An array is similar to a list that can also be indexed by a Value; indexing by an integer or a slice works the same as for Python lists, but indexing by a Value results in a proxy.

The array proxy can be used as an ordinary Value, i.e. participate in calculations and assignments, provided that all elements of the array are values. The array proxy also supports attribute access and further indexing, each returning another array proxy; this means that the results of indexing into arrays, arrays of records, and arrays of arrays can all be used as first-class values.

It is an error to change an array or any of its elements after an array proxy was created. Changing the array directly will raise an exception. However, it is not possible to detect the elements being modified; if an element’s attribute or element is modified after the proxy for it has been created, the proxy will refer to stale data.

Examples

Simple array:

gpios = Array(Signal() for _ in range(10))
with m.If(bus.we):
        m.d.sync += gpios[bus.addr].eq(bus.w_data)
with m.Else():
        m.d.sync += bus.r_data.eq(gpios[bus.addr])

Multidimensional array:

mult = Array(Array(x * y for y in range(10)) for x in range(10))
a = Signal.range(10)
b = Signal.range(10)
r = Signal(8)
m.d.comb += r.eq(mult[a][b])

Array of records:

layout = [
        ("r_data", 16),
        ("r_en",   1),
]
buses  = Array(Record(layout) for busno in range(4))
master = Record(layout)
m.d.comb += [
        buses[sel].r_en.eq(master.r_en),
        master.r_data.eq(buses[sel].r_data),
]

insert(index: SupportsIndex, value: Value) → None¶: Todo

Document Me

Todo

Document Me

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

Return type:: Property

Todo

Document Me

class torii.hdl.ast.Assign(lhs: Value | int | bool | EnumType | ValueCastable | ValueLike, rhs: Value | int | bool | EnumType | ValueCastable | ValueLike, *, src_loc_at: int = 0) → None¶: Todo

Document Me

Return type:: Property

Todo

Document Me

class torii.hdl.ast.Cat(*args: ValueCastT | Iterable[ValueCastT], src_loc_at: int = 0) → None¶

Concatenate values.

Form a compound Value from several smaller ones by concatenation. The first argument occupies the lower bits of the result. The return value can be used on either side of an assignment, that is, the concatenated value can be used as an argument on the RHS or as a target on the LHS. If it is used on the LHS, it must solely consist of Signal s, slices of Signal s, and other concatenations meeting these properties. The bit length of the return value is the sum of the bit lengths of the arguments:

len(Cat(args)) == sum(len(arg) for arg in args)

Parameters:: *args (Values or iterables of Values, inout) – Value s to be concatenated.
Returns:: Value – Resulting Value obtained by concatenation.

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

class torii.hdl.ast.ClockSignal(domain: str = 'sync', *, src_loc_at: int = 0) → None¶

Clock signal for a clock domain.

Any ClockSignal is equivalent to cd.clk for a clock domain with the corresponding name. All of these signals ultimately refer to the same signal, but they can be manipulated independently of the clock domain, even before the clock domain is created.

Parameters:: domain (str) – Clock domain to obtain a clock signal for. Defaults to sync.

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

A constant, literal integer value.

Parameters:

value (int)
shape (int | tuple[int, bool] | None) – Either an integer width or a tuple (width, signed) specifying the number of bits in this constant and whether it is signed (can represent negative values). shape defaults to the minimum possible width and signedness of value.

Attributes:

width (int)
signed (bool)

src_loc: tuple[str, int] | None = None¶: Todo

Document Me

static normalize(value: int, shape: Shape) → int¶

Return type:: int

Todo

Document Me

Converts obj to an Torii constant.

First, obj is converted to a value using Value.cast(). If it is a constant, it is returned. If it is a constant-castable expression, it is evaluated and returned. Otherwise, TypeError is raised.

Return type:: Const

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

Return type:: Property

Todo

Document Me

Check if the given Signal rose or fell in the past clocks + 1 clock cycles.

Parameters:

expr (ValueCastT) – The Signal or Const expression to sample.
clocks (int) – The number of clock cycles in the past this sample should represent.
domain (str | None) – The domain this sample should be taken on. If None the default domain is used.

Return type:

Operator

Returns:

Operator – If the sample rose or fell between clocks and clocks + 1

Check if the given Signal fell in the past clocks + 1 clock cycles.

Parameters:

expr (ValueCastT) – The Signal or Const expression to sample.
clocks (int) – The number of clock cycles in the past this sample should represent.
domain (str | None) – The domain this sample should be taken on. If None the default domain is used.

Return type:

Operator

Returns:

Operator – If the sample fell between clocks and clocks + 1

class torii.hdl.ast.Initial(*, src_loc_at: int = 0) → None¶

Start indicator, for model checking.

An Initial signal is 1 at the first cycle of model checking, and 0 at any other.

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

Choose between two values.

Parameters:

sel (Value) – Selector.
val1 (Value)
val0 (Value) – Input values.

Return type:

Operator

Returns:

Value – Output Value. If sel is asserted, the Mux returns val1, else val0.

Todo

Document Me

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

Todo

Document Me

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

Get a value from the past.

This function is effectively just an alias for constructing a Sample object.

Important

The sample value is likely one extra clock cycle in the past that you would expect, meaning when sampling with 1 clock, 2 clock cycles will have passed, the diagram below shows an example with different clocks values on the sample.

Parameters:

expr (ValueCastT) – The Signal or Const expression to sample.
clocks (int) – The number of clock cycles in the past this sample should represent.
domain (str | None) – The domain this sample should be taken on. If None the default domain is used.

Return type:

Value

Returns:

Sample – The sample value.

Todo

Document Me

class Kind(value)¶: Todo

Document Me

class torii.hdl.ast.ResetSignal(domain: str = 'sync', allow_reset_less: bool = False, *, src_loc_at: int = 0) → None¶

Reset signal for a clock domain.

Any ResetSignal is equivalent to cd.rst for a clock domain with the corresponding name. All of these signals ultimately refer to the same signal, but they can be manipulated independently of the clock domain, even before the clock domain is created.

Parameters:

domain (str) – Clock domain to obtain a reset signal for. Defaults to sync.
allow_reset_less (bool) – If the clock domain is reset-less, act as a constant 0 instead of reporting an error.

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

Check if the given Signal rose in the past clocks + 1 clock cycles.

Parameters:

expr (ValueCastT) – The Signal or Const expression to sample.
clocks (int) – The number of clock cycles in the past this sample should represent.
domain (str | None) – The domain this sample should be taken on. If None the default domain is used.

Return type:

Operator

Returns:

Operator – If the sample rose between clocks and clocks + 1

Value from the past.

A Sample of an expression is equal to the value of the expression clocks clock edges of the domain clock back. If that moment is before the beginning of time, it is equal to the value of the expression calculated as if each signal had its reset value.

Important

Parameters:

expr (ValueCastT) – The Signal or Const expression to sample.
clocks (int) – The number of clock cycles in the past this sample should represent.
domain (str | None) – The domain this sample should be taken on. If None the default domain is used.

Attributes:

value (Value) – The Value of the input expression.
clocks (int) – The number of clock cycles in the past to sample from.
domain (str) – The domain the sample is taken on.

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

class torii.hdl.ast.Shape(width: int = 1, signed: bool = False) → None¶

Bit width and signedness of a value.

A Shape can be constructed using:

explicit bit width and signedness;

aliases signed() and unsigned();

casting from a variety of objects.

A Shape can be cast from:

an integer, where the integer specifies the bit width;

a range, where the result is wide enough to represent any element of the range, and is
signed if any element of the range is signed;

an Enum with all integer members or IntEnum, where the result is wide
enough to represent any member of the enumeration, and is signed if any member of the enumeration is signed.

Parameters:

width (int) – The number of bits in the representation, including the sign bit (if any).
signed (bool) – If False, the value is unsigned. If True, the value is signed two’s complement.

static cast(obj: object, *, src_loc_at: int = 0) → Shape¶

Return type:: Shape

Todo

Document Me

class torii.hdl.ast.ShapeCastable¶

Interface of user-defined objects that can be cast to a Shape.

An object deriving from ShapeCastable is automatically converted to a Shape when it is used in a context where a Shape is expected. Such objects can contain a richer description of the shape than what is supported by the core Torii language, yet still be transparently used with it.

abstractmethod as_shape() → Shape¶

Return type:: Shape

Todo

Document Me

abstractmethod const(val: ValueCastT | None) → Const¶

Return type:: Const

Todo

Document Me

class torii.hdl.ast.ShapeLike(*args, **kwargs)¶

An abstract class representing all objects that can be cast to a Shape.

issubclass(cls, ShapeLike) returns True for:

Shape
ShapeCastable and its subclasses
int and its subclasses
range and its subclasses
enum.EnumMeta and its subclasses
ShapeLike itself

isinstance(obj, ShapeLike) returns True for:

Shape instances
ShapeCastable instances
non-negative int values
range instances
enum.Enum subclasses where all values are value-like

This class is only usable for the above checks — no instances and no (non-virtual) subclasses can be created.

A varying integer value.

Parameters:

shape (Shape-castable object or None) – Specification for the number of bits in this Signal and its signedness (whether it can represent negative values). See Shape.cast for details. If not specified, shape defaults to 1-bit and non-signed.
name (str) – Name hint for this signal. If None (default) the name is inferred from the variable name this Signal is assigned to.
reset (int or integral Enum) – Reset (synchronous) or default (combinatorial) value. When this Signal is assigned to in synchronous context and the corresponding clock domain is reset, the Signal assumes the given value. When this Signal is unassigned in combinatorial context (due to conditional assignments not being taken), the Signal assumes its reset value. Defaults to 0.
reset_less (bool) – If True, do not generate reset logic for this Signal in synchronous statements. The reset value is only used as a combinatorial default or as the initial value. Defaults to False.
attrs (dict) – Dictionary of synthesis attributes.
decoder (function or Enum) – A function converting integer signal values to human-readable strings (e.g. FSM state names). If an Enum subclass is passed, it is concisely decoded using format string "{0.name:}/{0.value:}", or a number if the signal value is not a member of the enumeration.

Attributes:

width (int)
signed (bool)
name (str)
reset (int)
reset_less (bool)
attrs (dict)
decoder (function)

static like(other: Signal, *, name: str | None = None, name_suffix: str | None = None, src_loc_at: int = 0, **kwargs) → Signal¶

Create Signal based on another.

Parameters:: other (Value) – Object to base this Signal on.
Return type:: Signal

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

class torii.hdl.ast.SignalDict(pairs: tuple[tuple[Key, Val], ...] = ()) → None¶: Mapping of Signal objects to arbitrary value types

class torii.hdl.ast.SignalKey(signal: Signal | ClockSignal | ResetSignal) → None¶

Allow aliasing of the same internal signal in a design from multiple object instances.

This allows you to map them as the same key in the resolution collections.

Doing so allows for multiple instances of, say, a ClockSignal with the same domain to refer internally to the same signal upon design flatting.

Meaning that wherever there is a ClockSignal('sync') they all refer to the same internal signal ID.

class torii.hdl.ast.SignalSet(elements: Iterable[Key] = ()) → None¶: Collection of unique Signal objects

torii.hdl.ast.signed(width: int) → Shape¶

Shorthand for Shape(width, signed = True).

Return type:: Shape

Todo

Document Me

shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

Check if a Signal is stable over the given clocks + 1 cycles in the past.

Parameters:

expr (ValueCastT) – The Signal or Const expression to sample.
clocks (int) – The number of clock cycles in the past this sample should represent.
domain (str | None) – The domain this sample should be taken on. If None the default domain is used.

Return type:

Operator

Returns:

Operator – If the sample is stable over clocks + 1 samples.

class torii.hdl.ast.Statement(*, src_loc_at: int = 0) → None¶

Todo

Document Me

static cast(obj: Iterable | Statement)¶: Todo

Document Me

class torii.hdl.ast.Switch(test: Value | int | bool | EnumType | ValueCastable | ValueLike, cases: Mapping[str | int | Enum | None | tuple[str | int | Enum | None, ...], Iterable[object] | _StatementList], *, src_loc: tuple[str, int] | None = None, src_loc_at: int = 0, case_src_locs: dict[str | int | Enum | None | tuple[str | int | Enum | None, ...], tuple[str, int]] = {}) → None¶: Todo

Document Me

torii.hdl.ast.unsigned(width: int) → Shape¶

Shorthand for Shape(width, signed = False).

Return type:: Shape

class torii.hdl.ast.Value(*, src_loc_at: int = 0) → None¶

Todo

Document Me

Converts obj to an Torii value.

Booleans and integers are wrapped into a Const. Enumerations whose members are all integers are converted to a Const with a shape that fits every member. ValueCastable objects are recursively cast to an Torii value.

Return type:: Value

src_loc: tuple[str, int] | None¶: Todo

Document Me

as_unsigned() → Operator¶

Conversion to unsigned.

Return type:: Operator
Returns:: Operator – This Value reinterpreted as a unsigned integer.

as_signed() → Operator¶

Conversion to signed.

Return type:: Operator
Returns:: Operator – This Value reinterpreted as a signed integer.

bool() → Operator¶

Conversion to boolean.

Return type:: Operator
Returns:: Operator – 1 if any bits are set, 0 otherwise.

any() → Operator¶

Check if any bits are 1.

Return type:: Operator
Returns:: Operator – 1 if any bits are set, 0 otherwise.

all() → Operator¶

Check if all bits are 1.

Return type:: Operator
Returns:: Operator – 1 if all bits are set, 0 otherwise.

xor() → Operator¶

Compute pairwise exclusive-or of every bit.

Return type:: Operator
Returns:: Operator – 1 if an odd number of bits are set, 0 if an even number of bits are set.

Implication.

Return type:: Operator
Returns:: Operator – 0 if premise is true and conclusion is not, 1 otherwise.

bit_select(offset: Value | int, width: int) → Value¶

Part-select with bit granularity.

Selects a constant width but variable offset part of a Value, such that successive parts overlap by all but 1 bit.

Parameters:

offset (Value | int) – Index of first selected bit.
width (int) – Number of selected bits.

Return type:

Value

Returns:

Part – Selected part of the Value

word_select(offset: Value | int, width: int) → Value¶

Part-select with word granularity.

Selects a constant width but variable offset part of a Value, such that successive parts do not overlap.

Parameters:

offset (Value | int) – Index of first selected word.
width (int) – Number of selected bits.

Return type:

Value

Returns:

Part – Selected part of the Value

matches(*patterns: int | str | EnumType) → Value¶

Pattern matching.

Matches against a set of patterns, which may be integers or bit strings, recognizing the same grammar as Case().

Parameters:: patterns (int | str | Enum) – Patterns to match against.
Return type:: Value
Returns:: Value – 1 if any pattern matches the value, 0 otherwise.

shift_left(amount: int) → Value¶

Shift left by constant amount.

Parameters:: amount (int) – Amount to shift by.
Return type:: Value
Returns:: Value – If the amount is positive, the input shifted left. Otherwise, the input shifted right.

shift_right(amount: int) → Value¶

Shift right by constant amount.

Parameters:: amount (int) – Amount to shift by.
Return type:: Value
Returns:: Value – If the amount is positive, the input shifted right. Otherwise, the input shifted left.

rotate_left(amount: int) → Value¶

Rotate left by constant amount.

Parameters:: amount (int) – Amount to rotate by.
Return type:: Value
Returns:: Value – If the amount is positive, the input rotated left. Otherwise, the input rotated right.

rotate_right(amount: int) → Value¶

Rotate right by constant amount.

Parameters:: amount (int) – Amount to rotate by.
Return type:: Value
Returns:: Value – If the amount is positive, the input rotated right. Otherwise, the input rotated right.

replicate(count: int) → Value¶

Replication.

A Value is replicated (repeated) several times to be used on the RHS of assignments:

len(v.replicate(n)) == len(v) * n

Parameters:: count (int) – Number of replications.
Return type:: Value
Returns:: Value – Replicated value.

Assignment.

Parameters:: value (Value) – Value to be assigned.
Return type:: Assign
Returns:: Assign – Assignment statement that can be used in combinatorial or synchronous context.

Increment value.

This is shorthand for a.eq(a + n)

Parameters:: value (Value) – Value to increment by.
Return type:: Assign
Returns:: Assign – Assignment statement that can be used in combinatorial or synchronous context.

Decrement value.

This is shorthand for a.eq(a - n)

Parameters:: value (Value) – Value to decrement by.
Return type:: Assign
Returns:: Assign – Assignment statement that can be used in combinatorial or synchronous context.

abstractmethod shape() → Shape¶

Bit width and signedness of a value.

Return type:: Shape
Returns:: Shape – See Shape.

Examples

>>> Signal(8).shape()
Shape(width = 8, signed = False)
>>> Const(0xaa).shape()
Shape(width = 8, signed = False)

class torii.hdl.ast.ValueCastable¶

Interface of user-defined objects that can be cast to Value s.

An object deriving from ValueCastable` is automatically converted to a Value when it is used in a context where a Value` is expected. Such objects can implement different or richer semantics than what is supported by the core Torii language, yet still be transparently used with it as long as the final underlying representation is a single Torii Value. These objects also need not commit to a specific representation until they are converted to a concrete Torii value.

Note that it is necessary to ensure that Torii’s view of representation of all values stays internally consistent. The class deriving from ValueCastable` must decorate the as_value() method with the lowermethod() decorator, which ensures that all calls to as_value() return the same Value representation. If the class deriving from ValueCastable is mutable, it is up to the user to ensure that it is not mutated in a way that changes its representation after the first call to as_value().

static lowermethod(func)¶

Decorator to memoize lowering methods.

Ensures the decorated method is called only once, with subsequent method calls returning the object returned by the first first method call.

This decorator is required to decorate the as_value method of ValueCastable subclasses. This is to ensure that Torii’s view of representation of all values stays internally consistent.

class torii.hdl.ast.ValueDict(pairs: tuple[tuple[Key, Val], ...] = ()) → None¶: Mapping of Value objects to arbitrary value types

class torii.hdl.ast.ValueKey(value: Value | int | bool | EnumType | ValueCastable | ValueLike) → None¶: Todo

Document Me

class torii.hdl.ast.ValueLike(*args, **kwargs)¶: Todo

Document Me

class torii.hdl.ast.ValueSet(elements: Iterable[Key] = ()) → None¶: Collection of unique Value objects