Language guide

Warning

This guide is a work in progress and is seriously incomplete!

This guide introduces the Amaranth language in depth. It assumes familiarity with synchronous digital logic and the Python programming language, but does not require prior experience with any hardware description language. See the tutorial for a step-by-step introduction to the language.

The prelude

Because Amaranth is a regular Python library, it needs to be imported before use. The root amaranth module, called the prelude, is carefully curated to export a small amount of the most essential names, useful in nearly every design. In source files dedicated to Amaranth code, it is a good practice to use a glob import for readability:

from amaranth import *

However, if a source file uses Amaranth together with other libraries, or if glob imports are frowned upon, it is conventional to use a short alias instead:

import amaranth as am

All of the examples below assume that a glob import is used.

Shapes

A Shape is an object with two attributes, .width and .signed. It can be constructed directly:

>>> Shape(width=5, signed=False)
unsigned(5)
>>> Shape(width=12, signed=True)
signed(12)

However, in most cases, the shape is always constructed with the same signedness, and the aliases signed and unsigned are more convenient:

>>> unsigned(5) == Shape(width=5, signed=False)
True
>>> signed(12) == Shape(width=12, signed=True)
True

Shapes of values

All values have a .shape() method that computes their shape. The width of a value v, v.shape().width, can also be retrieved with len(v).

>>> Const(5).shape()
unsigned(3)
>>> len(Const(5))
3

Values

The basic building block of the Amaranth language is a value, which is a term for a binary number that is computed or stored anywhere in the design. Each value has a width—the amount of bits used to represent the value—and a signedness—the interpretation of the value by arithmetic operations—collectively called its shape. Signed values always use two’s complement representation.

Constants

The simplest Amaranth value is a constant, representing a fixed number, and introduced using Const(...) or its short alias C(...):

>>> ten = Const(10)
>>> minus_two = C(-2)

The code above does not specify any shape for the constants. If the shape is omitted, Amaranth uses unsigned shape for positive numbers and signed shape for negative numbers, with the width inferred from the smallest amount of bits necessary to represent the number. As a special case, in order to get the same inferred shape for True and False, 0 is considered to be 1-bit unsigned.

>>> ten.shape()
unsigned(4)
>>> minus_two.shape()
signed(2)
>>> C(0).shape()
unsigned(1)

The shape of the constant can be specified explicitly, in which case the number’s binary representation will be truncated or extended to fit the shape. Although rarely useful, 0-bit constants are permitted.

>>> Const(360, unsigned(8)).value
104
>>> Const(129, signed(8)).value
-127
>>> Const(1, unsigned(0)).value
0

Shape casting

Shapes can be cast from other objects, which are called shape-like. Casting is a convenient way to specify a shape indirectly, for example, by a range of numbers representable by values with that shape.

Casting to a shape can be done explicitly with Shape.cast, but is usually implicit, since shape-like objects are accepted anywhere shapes are.

Shapes from integers

Casting a shape from an integer i is a shorthand for constructing a shape with unsigned(i):

>>> Shape.cast(5)
unsigned(5)
>>> C(0, 3).shape()
unsigned(3)

Shapes from ranges

Casting a shape from a range r produces a shape that:

• has a width large enough to represent both min(r) and max(r), but not larger, and

• is signed if r contains any negative values, unsigned otherwise.

Specifying a shape with a range is convenient for counters, indexes, and all other values whose width is derived from a set of numbers they must be able to fit:

>>> Const(0, range(100)).shape()
unsigned(7)
>>> items = [1, 2, 3]
>>> C(1, range(len(items))).shape()
unsigned(2)

Note

Python ranges are exclusive or half-open, meaning they do not contain their .stop element. Because of this, values with shapes cast from a range(stop) where stop is a power of 2 are not wide enough to represent stop itself:

>>> fencepost = C(256, range(256))
<...>:1: SyntaxWarning: Value 256 equals the non-inclusive end of the constant shape range(0, 256); this is likely an off-by-one error
  fencepost = C(256, range(256))
>>> fencepost.shape()
unsigned(8)
>>> fencepost.value
0

Amaranth detects uses of Const and Signal that invoke such an off-by-one error, and emits a diagnostic message.

Note

An empty range always casts to an unsigned(0), even if both of its bounds are negative. This happens because, being empty, it does not contain any negative values.

>>> Shape.cast(range(-1, -1))
unsigned(0)

Shapes from enumerations

Casting a shape from an enum.Enum subclass requires all of the enumeration members to have constant-castable values. The shape has a width large enough to represent the value of every member, and is signed only if there is a member with a negative value.

Specifying a shape with an enumeration is convenient for finite state machines, multiplexers, complex control signals, and all other values whose width is derived from a few distinct choices they must be able to fit:

class Direction(enum.Enum):
    TOP    = 0
    LEFT   = 1
    BOTTOM = 2
    RIGHT  = 3

>>> Shape.cast(Direction)
unsigned(2)

The amaranth.lib.enum module extends the standard enumerations such that their shape can be specified explicitly when they are defined:

class Funct4(amaranth.lib.enum.Enum, shape=unsigned(4)):
    ADD = 0
    SUB = 1
    MUL = 2

>>> Shape.cast(Funct4)
unsigned(4)

Note

The enumeration does not have to subclass enum.IntEnum or have int as one of its base classes; it only needs to have integers as values of every member. Using enumerations based on enum.Enum rather than enum.IntEnum prevents unwanted implicit conversion of enum members to integers.

Value casting

Like shapes, values may be cast from other objects, which are called value-like. Casting to values allows objects that are not provided by Amaranth, such as integers or enumeration members, to be used in Amaranth expressions directly.

Casting to a value can be done explicitly with Value.cast, but is usually implicit, since value-like objects are accepted anywhere values are.

Values from integers

Casting a value from an integer i is equivalent to Const(i):

>>> Value.cast(5)
(const 3'd5)

Note

If a value subclasses enum.IntEnum or its class otherwise inherits from both int and Enum, it is treated as an enumeration.

Values from enumeration members

Casting a value from an enumeration member m is equivalent to Const(m.value, type(m)):

>>> Value.cast(Direction.LEFT)
(const 2'd1)

Note

If a value subclasses enum.IntEnum or its class otherwise inherits from both int and Enum, it is treated as an enumeration.

Constant casting

A subset of values are constant-castable. If a value is constant-castable and all of its operands are also constant-castable, it can be converted to a Const, the numeric value of which can then be read by Python code. This provides a way to perform computation on Amaranth values while constructing the design.

Constant-castable objects are accepted anywhere a constant integer is accepted. Casting to a constant can also be done explicitly with Const.cast():

>>> Const.cast(Cat(C(10, 4), C(1, 2)))
(const 6'd26)

They may be used in enumeration members, provided the enumeration inherits from amaranth.lib.enum.Enum:

class Funct(amaranth.lib.enum.Enum, shape=4):
    ADD = 0
    ...

class Op(amaranth.lib.enum.Enum, shape=1):
    REG = 0
    IMM = 1

class Instr(amaranth.lib.enum.Enum, shape=5):
    ADD  = Cat(Funct.ADD, Op.REG)
    ADDI = Cat(Funct.ADD, Op.IMM)
    ...

They may also be provided as a pattern to the match operator and the Case block.

Note

At the moment, only the following expressions are constant-castable:

• Const

• Cat

This list will be expanded in the future.

Signals

A signal is a value representing a (potentially) varying number. Signals can be assigned in a combinatorial or synchronous domain, in which case they are generated as wires or registers, respectively. Signals always have a well-defined value; they cannot be uninitialized or undefined.

Signal shapes

A signal can be created with an explicitly specified shape (any shape-like object); if omitted, the shape defaults to unsigned(1). Although rarely useful, 0-bit signals are permitted.

>>> Signal().shape()
unsigned(1)
>>> Signal(4).shape()
unsigned(4)
>>> Signal(range(-8, 7)).shape()
signed(4)
>>> Signal(Direction).shape()
unsigned(2)
>>> Signal(0).shape()
unsigned(0)

Signal names

Each signal has a name, which is used in the waveform viewer, diagnostic messages, Verilog output, and so on. In most cases, the name is omitted and inferred from the name of the variable or attribute the signal is placed into:

>>> foo = Signal()
>>> foo.name
'foo'
>>> self.bar = Signal()
>>> self.bar.name
'bar'

However, the name can also be specified explicitly with the name= parameter:

>>> foo2 = Signal(name="second_foo")
>>> foo2.name
'second_foo'

The names do not need to be unique; if two signals with the same name end up in the same namespace while preparing for simulation or synthesis, one of them will be renamed to remove the ambiguity.

Initial signal values

Each signal has an initial value, specified with the reset= parameter. If the initial value is not specified explicitly, zero is used by default. An initial value can be specified with an integer or an enumeration member.

Signals assigned in a combinatorial domain assume their initial value when none of the assignments are active. Signals assigned in a synchronous domain assume their initial value after power-on reset and, unless the signal is reset-less, explicit reset. Signals that are used but never assigned are equivalent to constants of their initial value.

>>> Signal(4).reset
0
>>> Signal(4, reset=5).reset
5
>>> Signal(Direction, reset=Direction.LEFT).reset
1

Reset-less signals

Signals assigned in a synchronous domain can be resettable or reset-less, specified with the reset_less= parameter. If the parameter is not specified, signals are resettable by default. Resettable signals assume their initial value on explicit reset, which can be asserted via the clock domain or by using ResetInserter. Reset-less signals are not affected by explicit reset.

Signals assigned in a combinatorial domain are not affected by the reset_less parameter.

>>> Signal().reset_less
False
>>> Signal(reset_less=True).reset_less
True

Data structures

Amaranth provides aggregate data structures in the standard library module amaranth.lib.data.

Operators

To describe computations, Amaranth values can be combined with each other or with value-like objects using a rich array of arithmetic, bitwise, logical, bit sequence, and other operators to form expressions, which are themselves values.

Performing or describing computations?

Code written in the Python language performs computations on concrete objects, like integers, with the goal of calculating a concrete result:

>>> a = 5
>>> a + 1
6

In contrast, code written in the Amaranth language describes computations on abstract objects, like signals, with the goal of generating a hardware circuit that can be simulated, synthesized, and so on. Amaranth expressions are ordinary Python objects that represent parts of this circuit:

>>> a = Signal(8, reset=5)
>>> a + 1
(+ (sig a) (const 1'd1))

Although the syntax is similar, it is important to remember that Amaranth values exist on a higher level of abstraction than Python values. For example, expressions that include Amaranth values cannot be used in Python control flow structures:

>>> if a == 0:
...     print("Zero!")
Traceback (most recent call last):
  ...
TypeError: Attempted to convert Amaranth value to Python boolean

Because the value of a, and therefore a == 0, is not known at the time when the if statement is executed, there is no way to decide whether the body of the statement should be executed—in fact, if the design is synthesized, by the time a has any concrete value, the Python program has long finished! To solve this problem, Amaranth provides its own control flow syntax that, also, manipulates circuits.

Width extension

Many of the operations described below (for example, addition, equality, bitwise OR, and part select) extend the width of one or both operands to match the width of the expression. When this happens, unsigned values are always zero-extended and signed values are always sign-extended regardless of the operation or signedness of the result.

Arithmetic operators

Most arithmetic operations on integers provided by Python can be used on Amaranth values, too.

Although Python integers have unlimited precision and Amaranth values are represented with a finite amount of bits, arithmetics on Amaranth values never overflows because the width of the arithmetic expression is always sufficient to represent all possible results.

>>> a = Signal(8)
>>> (a + 1).shape() # needs to represent 1 to 256
unsigned(9)

Similarly, although Python integers are always signed and Amaranth values can be either signed or unsigned, if any of the operands of an Amaranth arithmetic expression is signed, the expression itself is also signed, matching the behavior of Python.

>>> a = Signal(unsigned(8))
>>> b = Signal(signed(8))
>>> (a + b).shape() # needs to represent -128 to 382
signed(10)

While arithmetic computations never result in an overflow, assigning their results to signals may truncate the most significant bits.

The following table lists the arithmetic operations provided by Amaranth:

Operation	Description
a + b	addition
-a	negation
a - b	subtraction
a * b	multiplication
a // b	floor division
a % b	modulo
abs(a)	absolute value

Comparison operators

All comparison operations on integers provided by Python can be used on Amaranth values. However, due to a limitation of Python, chained comparisons (e.g. a < b < c) cannot be used.

Similar to arithmetic operations, if any operand of a comparison expression is signed, a signed comparison is performed. The result of a comparison is a 1-bit unsigned value.

The following table lists the comparison operations provided by Amaranth:

Operation	Description
a == b	equality
a != b	inequality
a < b	less than
a <= b	less than or equal
a > b	greater than
a >= b	greater than or equal

Bitwise, shift, and rotate operators

All bitwise and shift operations on integers provided by Python can be used on Amaranth values as well.

Similar to arithmetic operations, if any operand of a bitwise expression is signed, the expression itself is signed as well. A shift expression is signed if the shifted value is signed. A rotate expression is always unsigned.

Rotate operations with variable rotate amounts cannot be efficiently synthesized for non-power-of-2 widths of the rotated value. Because of that, the rotate operations are only provided for constant rotate amounts, specified as Python ints.

The following table lists the bitwise and shift operations provided by Amaranth:

Operation	Description	Notes
~a	bitwise NOT; complement
a & b	bitwise AND
a | b	bitwise OR
a ^ b	bitwise XOR
a.implies(b)	bitwise IMPLY
a >> b	arithmetic right shift by variable amount	[1], [2]
a << b	left shift by variable amount	[2]
a.rotate_left(i)	left rotate by constant amount	[3]
a.rotate_right(i)	right rotate by constant amount	[3]
a.shift_left(i)	left shift by constant amount	[3]
a.shift_right(i)	right shift by constant amount	[3]

[1]

Logical and arithmetic right shift of an unsigned value are equivalent. Logical right shift of a signed value can be expressed by converting it to unsigned first.

[2] (1,2)

Shift amount must be unsigned; integer shifts in Python require the amount to be positive.

[3] (1,2,3,4)

Shift and rotate amounts can be negative, in which case the direction is reversed.

Note

Because Amaranth ensures that the width of a variable left shift expression is wide enough to represent any possible result, variable left shift by a wide amount produces exponentially wider intermediate values, stressing the synthesis tools:

>>> (1 << C(0, 32)).shape()
unsigned(4294967296)

Although Amaranth will detect and reject expressions wide enough to break other tools, it is a good practice to explicitly limit the width of a shift amount in a variable left shift.

Reduction operators

Bitwise reduction operations on integers are not provided by Python, but are very useful for hardware. They are similar to bitwise operations applied “sideways”; for example, if bitwise AND is a binary operator that applies AND to each pair of bits between its two operands, then reduction AND is an unary operator that applies AND to all of the bits in its sole operand.

The result of a reduction is a 1-bit unsigned value.

The following table lists the reduction operations provided by Amaranth:

Operation	Description	Notes
a.all()	reduction AND; are all bits set?	[4]
a.any()	reduction OR; is any bit set?	[4]
a.xor()	reduction XOR; is an odd number of bits set?
a.bool()	conversion to boolean; is non-zero?	[5]

[4] (1,2)

Conceptually the same as applying the Python all() or any() function to the value viewed as a collection of bits.

[5]

Conceptually the same as applying the Python bool() function to the value viewed as an integer.

Logical operators

Unlike the arithmetic or bitwise operators, it is not possible to change the behavior of the Python logical operators not, and, and or. Due to that, logical expressions in Amaranth are written using bitwise operations on boolean (1-bit unsigned) values, with explicit boolean conversions added where necessary.

The following table lists the Python logical expressions and their Amaranth equivalents:

Python expression	Amaranth expression (any operands)
not a	~(a).bool()
a and b	(a).bool() & (b).bool()
a or b	(a).bool() | (b).bool()

When the operands are known to be boolean values, such as comparisons, reductions, or boolean signals, the .bool() conversion may be omitted for clarity:

Python expression	Amaranth expression (boolean operands)
not p	~(p)
p and q	(p) & (q)
p or q	(p) | (q)

Warning

Because of Python operator precedence, logical operators bind less tightly than comparison operators whereas bitwise operators bind more tightly than comparison operators. As a result, all logical expressions in Amaranth must have parenthesized operands.

Omitting parentheses around operands in an Amaranth a logical expression is likely to introduce a subtle bug:

>>> en = Signal()
>>> addr = Signal(8)
>>> en & (addr == 0) # correct
(& (sig en) (== (sig addr) (const 1'd0)))
>>> en & addr == 0 # WRONG! addr is truncated to 1 bit
(== (& (sig en) (sig addr)) (const 1'd0))

Warning

When applied to Amaranth boolean values, the ~ operator computes negation, and when applied to Python boolean values, the not operator also computes negation. However, the ~ operator applied to Python boolean values produces an unexpected result:

>>> ~False
-1
>>> ~True
-2

Because of this, Python booleans used in Amaranth logical expressions must be negated with the not operator, not the ~ operator. Negating a Python boolean with the ~ operator in an Amaranth logical expression is likely to introduce a subtle bug:

>>> stb = Signal()
>>> use_stb = True
>>> (not use_stb) | stb # correct
(| (const 1'd0) (sig stb))
>>> ~use_stb | stb # WRONG! MSB of 2-bit wide OR expression is always 1
(| (const 2'sd-2) (sig stb))

Amaranth automatically detects some cases of misuse of ~ and emits a detailed diagnostic message.

Bit sequence operators

Apart from acting as numbers, Amaranth values can also be treated as bit sequences, supporting slicing, concatenation, replication, and other sequence operations. Since some of the operators Python defines for sequences clash with the operators it defines for numbers, Amaranth gives these operators a different name. Except for the names, Amaranth values follow Python sequence semantics, with the least significant bit at index 0.

Because every Amaranth value has a single fixed width, bit slicing and replication operations require the subscripts and count to be constant, specified as Python ints. It is often useful to slice a value with a constant width and variable offset, but this cannot be expressed with the Python slice notation. To solve this problem, Amaranth provides additional part select operations with the necessary semantics.

The result of any bit sequence operation is an unsigned value.

The following table lists the bit sequence operations provided by Amaranth:

Operation	Description	Notes
len(a)	bit length; value width	[6]
a[i:j:k]	bit slicing by constant subscripts	[7]
iter(a)	bit iteration
a.bit_select(b, w)	overlapping part select with variable offset
a.word_select(b, w)	non-overlapping part select with variable offset
Cat(a, b)	concatenation	[8]
a.replicate(n)	replication

[6]

Words “length” and “width” have the same meaning when talking about Amaranth values. Conventionally, “width” is used.

[7]

All variations of the Python slice notation are supported, including “extended slicing”. E.g. all of a[0], a[1:9], a[2:], a[:-2], a[::-1], a[0:8:2] select bits in the same way as other Python sequence types select their elements.

[8]

In the concatenated value, a occupies the least significant bits, and b the most significant bits. Any number of arguments (zero, one, two, or more) are supported.

For the operators introduced by Amaranth, the following table explains them in terms of Python code operating on tuples of bits rather than Amaranth values:

Amaranth operation	Equivalent Python code
Cat(a, b)	a + b
a.replicate(n)	a * n
a.bit_select(b, w)	a[b:b+w]
a.word_select(b, w)	a[b*w:b*w+w]

Warning

In Python, the digits of a number are written right-to-left (0th exponent at the right), and the elements of a sequence are written left-to-right (0th element at the left). This mismatch can cause confusion when numeric operations (like shifts) are mixed with bit sequence operations (like concatenations). For example, Cat(C(0b1001), C(0b1010)) has the same value as C(0b1010_1001), val[4:] is equivalent to val >> 4, and val[-1] refers to the most significant bit.

Such confusion can often be avoided by not using numeric and bit sequence operations in the same expression. For example, although it may seem natural to describe a shift register with a numeric shift and a sequence slice operations, using sequence operations alone would make it easier to understand.

Note

Could Amaranth have used a different indexing or iteration order for values? Yes, but it would be necessary to either place the most significant bit at index 0, or deliberately break the Python sequence type interface. Both of these options would cause more issues than using different iteration orders for numeric and sequence operations.

Match operator

The val.matches(*patterns) operator examines a value against a set of patterns. It evaluates to Const(1) if the value matches any of the patterns, and to Const(0) otherwise. What it means for a value to match a pattern depends on the type of the pattern.

If the pattern is a str, it is treated as a bit mask with “don’t care” bits. After removing whitespace, each character of the pattern is compared to the bit of the value in the same position as the character. If the pattern character is '0' or '1', the comparison succeeds if the bit equals 0 or 1 correspondingly. If the pattern character is '-', the comparison always succeeds. Aside from spaces and tabs, which are ignored, no other characters are accepted.

Otherwise, the pattern is cast to a constant and compared to val using the equality operator.

For example, given a 8-bit value val, val.matches(1, '---- -01-') is equivalent to (val == 1) | ((val & 0b0110_0000) == 0b0100_0000). Note that the direction in which bits are specified for the .match() operator (least to most significant) is the opposite of the direction in which an integer literal is written (most to least significant). Bit patterns in this operator are treated similarly to bit sequence operators.

The Case control flow block accepts the same patterns, with the same meaning, as the match operator.

Warning

Do not rely on the behavior of val.matches() with no patterns.

Conversion operators

The .as_signed() and .as_unsigned() conversion operators reinterpret the bits of a value with the requested signedness. This is useful when the same value is sometimes treated as signed and sometimes as unsigned, or when a signed value is constructed using slices or concatenations.

For example, (pc + imm[:7].as_signed()).as_unsigned() sign-extends the 7 least significant bits of imm to the width of pc, performs the addition, and produces an unsigned result.

Choice operator

The Mux(sel, val1, val0) choice expression (similar to the conditional expression in Python) is equal to the operand val1 if sel is non-zero, and to the other operand val0 otherwise. If any of val1 or val0 are signed, the expression itself is signed as well.

Modules

A module is a unit of the Amaranth design hierarchy: the smallest collection of logic that can be independently simulated, synthesized, or otherwise processed. Modules associate signals with control domains, provide control flow syntax, manage clock domains, and aggregate submodules.

Every Amaranth design starts with a fresh module:

>>> m = Module()

Control domains

A control domain is a named group of signals that change their value in identical conditions.

All designs have a single predefined combinatorial domain, containing all signals that change immediately when any value used to compute them changes. The name comb is reserved for the combinatorial domain, and refers to the same domain in all modules.

A design can also have any amount of user-defined synchronous domains, also called clock domains, containing signals that change when a specific edge occurs on the domain’s clock signal or, for domains with asynchronous reset, on the domain’s reset signal. Most modules only use a single synchronous domain, conventionally called sync, but the name sync does not have to be used, and lacks any special meaning beyond being the default.

The behavior of assignments differs for signals in combinatorial and synchronous domains. Collectively, signals in synchronous domains contain the state of a design, whereas signals in the combinatorial domain cannot form feedback loops or hold state.

Assigning to signals

Assignments are used to change the values of signals. An assignment statement can be introduced with the .eq(...) syntax:

>>> s = Signal()
>>> s.eq(1)
(eq (sig s) (const 1'd1))

Similar to how Amaranth operators work, an Amaranth assignment is an ordinary Python object used to describe a part of a circuit. An assignment does not have any effect on the signal it changes until it is added to a control domain in a module. Once added, it introduces logic into the circuit generated from that module.

Assignment targets

The target of an assignment can be more complex than a single signal. It is possible to assign to any combination of signals, bit slices, concatenations, and part selects as long as it includes no other values:

>>> a = Signal(8)
>>> b = Signal(4)
>>> Cat(a, b).eq(0)
(eq (cat (sig a) (sig b)) (const 1'd0))
>>> a[:4].eq(b)
(eq (slice (sig a) 0:4) (sig b))
>>> Cat(a, a).bit_select(b, 2).eq(0b11)
(eq (part (cat (sig a) (sig a)) (sig b) 2 1) (const 2'd3))

Assignment domains

The m.d.<domain> += ... syntax is used to add assignments to a specific control domain in a module. It can add just a single assignment, or an entire sequence of them:

a = Signal()
b = Signal()
c = Signal()
m.d.comb += a.eq(1)
m.d.sync += [
    b.eq(c),
    c.eq(b),
]

If the name of a domain is not known upfront, the m.d["<domain>"] += ... syntax can be used instead:

def add_toggle(num):
    t = Signal()
    m.d[f"sync_{num}"] += t.eq(~t)
add_toggle(2)

Every signal included in the target of an assignment becomes a part of the domain, or equivalently, driven by that domain. A signal can be either undriven or driven by exactly one domain; it is an error to add two assignments to the same signal to two different domains:

>>> d = Signal()
>>> m.d.comb += d.eq(1)
>>> m.d.sync += d.eq(0)
Traceback (most recent call last):
  ...
amaranth.hdl.dsl.SyntaxError: Driver-driver conflict: trying to drive (sig d) from d.sync, but it is already driven from d.comb

Note

Clearly, Amaranth code that drives a single bit of a signal from two different domains does not describe a meaningful circuit. However, driving two different bits of a signal from two different domains does not inherently cause such a conflict. Would Amaranth accept the following code?

e = Signal(2)
m.d.comb += e[0].eq(0)
m.d.sync += e[1].eq(1)

The answer is no. While this kind of code is occasionally useful, rejecting it greatly simplifies backends, simulators, and analyzers.

Assignment order

Unlike with two different domains, adding multiple assignments to the same signal to the same domain is well-defined.

Assignments to different signal bits apply independently. For example, the following two snippets are equivalent:

a = Signal(8)
m.d.comb += [
    a[0:4].eq(C(1, 4)),
    a[4:8].eq(C(2, 4)),
]

a = Signal(8)
m.d.comb += a.eq(Cat(C(1, 4), C(2, 4)))

If multiple assignments change the value of the same signal bits, the assignment that is added last determines the final value. For example, the following two snippets are equivalent:

b = Signal(9)
m.d.comb += [
    b[0:9].eq(Cat(C(1, 3), C(2, 3), C(3, 3))),
    b[0:6].eq(Cat(C(4, 3), C(5, 3))),
    b[3:6].eq(C(6, 3)),
]

b = Signal(9)
m.d.comb += b.eq(Cat(C(4, 3), C(6, 3), C(3, 3)))

Multiple assignments to the same signal bits are more useful when combined with control structures, which can make some of the assignments active or inactive. If all assignments to some signal bits are inactive, their final values are determined by the signal’s domain, combinatorial or synchronous.

Control flow

Although it is possible to write any decision tree as a combination of assignments and choice expressions, Amaranth provides control flow syntax tailored for this task: If/Elif/Else, Switch/Case, and FSM/State. The control flow syntax uses with blocks (it is implemented using context managers), for example:

timer = Signal(8)
with m.If(timer == 0):
    m.d.sync += timer.eq(10)
with m.Else():
    m.d.sync += timer.eq(timer - 1)

While some Amaranth control structures are superficially similar to imperative control flow statements (such as Python’s if), their function—together with expressions and assignments—is to describe circuits. The code above is equivalent to:

timer = Signal(8)
m.d.sync += timer.eq(Mux(timer == 0, 10, timer - 1))

Because all branches of a decision tree affect the generated circuit, all of the Python code inside Amaranth control structures is always evaluated in the order in which it appears in the program. This can be observed through Python code with side effects, such as print():

timer = Signal(8)
with m.If(timer == 0):
    print("inside `If`")
    m.d.sync += timer.eq(10)
with m.Else():
    print("inside `Else`")
    m.d.sync += timer.eq(timer - 1)

inside `If`
inside `Else`

Active and inactive assignments

An assignment added inside an Amaranth control structure, i.e. with m.<...>: block, is active if the condition of the control structure is satisfied, and inactive otherwise. For any given set of conditions, the final value of every signal assigned in a module is the same as if the inactive assignments were removed and the active assignments were performed unconditionally, taking into account the assignment order.

For example, there are two possible cases in the circuit generated from the following code:

timer = Signal(8)
m.d.sync += timer.eq(timer - 1)
with m.If(timer == 0):
    m.d.sync += timer.eq(10)

When timer == 0 is true, the code reduces to:

m.d.sync += timer.eq(timer - 1)
m.d.sync += timer.eq(10)

Due to the assignment order, it further reduces to:

m.d.sync += timer.eq(10)

When timer == 0 is false, the code reduces to:

m.d.sync += timer.eq(timer - 1)

Combining these cases together, the code above is equivalent to:

timer = Signal(8)
m.d.sync += timer.eq(Mux(timer == 0, 10, timer - 1))

If/Elif/Else control blocks

Conditional control flow is described using a with m.If(cond1): block, which may be followed by one or more with m.Elif(cond2): blocks, and optionally a final with m.Else(): block. This structure parallels Python’s own if/elif/else control flow syntax. For example:

with m.If(x_coord < 4):
    m.d.comb += is_bporch.eq(1)
    m.d.sync += x_coord.eq(x_coord + 1)
with m.Elif((x_coord >= 4) & (x_coord < 364)):
    m.d.comb += is_active.eq(1)
    m.d.sync += x_coord.eq(x_coord + 1)
with m.Elif((x_coord >= 364) & (x_coord < 374)):
    m.d.comb += is_fporch.eq(1)
    m.d.sync += x_coord.eq(x_coord + 1)
with m.Else():
    m.d.sync += x_coord.eq(0)

Within a single If/Elif/Else sequence of blocks, the statements within at most one block will be active at any time. This will be the first block in the order of definition whose condition, converted to boolean, is true.

If an Else block is present, then the statements within exactly one block will be active at any time, and the sequence as a whole is called a full condition.

Switch/Case control blocks

Case comparison, where a single value is examined against several different patterns, is described using a with m.Switch(value): block. This block can contain any amount of with m.Case(*patterns) and with m.Default(): blocks. This structure parallels Python’s own match/case control flow syntax. For example:

value = Signal(4)

with m.Switch(value):
    with m.Case(0, 2, 4):
        m.d.comb += is_even.eq(1)
    with m.Case(1, 3, 5):
        m.d.comb += is_odd.eq(1)
    with m.Default():
        m.d.comb += too_big.eq(1)

Within a single Switch block, the statements within at most one block will be active at any time. This will be the first Case block in the order of definition whose pattern matches the value, or the first Default block, whichever is earlier.

If a Default block is present, or the patterns in the Case blocks cover every possible Switch value, then the statements within exactly one block will be active at any time, and the sequence as a whole is called a full condition.

Warning

Do not rely on the behavior of a with m.Case(): with no patterns.

Tip

While all Amaranth control flow syntax can be generated programmatically, the Switch control block is particularly easy to use in this way:

length  = Signal(4)
squared = Signal.like(length * length)

with m.Switch(length):
    for value in range(length.shape().width):
        with m.Case(value):
            m.d.comb += squared.eq(value * value)

FSM/State control blocks

Simple finite state machines are described using a with m.FSM(): block. This block can contain one or more with m.State("Name") blocks. In addition to these blocks, the m.next = "Name" syntax chooses which state the FSM enters on the next clock cycle. For example, this FSM performs a bus read transaction once after reset:

bus_addr = Signal(16)
r_data   = Signal(8)
r_en     = Signal()
latched  = Signal.like(r_data)

with m.FSM():
    with m.State("Set Address"):
        m.d.sync += addr.eq(0x1234)
        m.next = "Strobe Read Enable"

    with m.State("Strobe Read Enable"):
        m.d.comb += r_en.eq(1)
        m.next = "Sample Data"

    with m.State("Sample Data"):
        m.d.sync += latched.eq(r_data)
        with m.If(r_data == 0):
            m.next = "Set Address" # try again

The reset state of the FSM can be provided when defining it using the with m.FSM(reset="Name"): argument. If not provided, it is the first state in the order of definition. For example, this definition is equivalent to the one at the beginning of this section:

with m.FSM(reset="Set Address"):
    ...

The FSM belongs to a clock domain, which is specified using the with m.FSM(domain="dom") argument. If not specified, it is the sync domain. For example, this definition is equivalent to the one at the beginning of this section:

with m.FSM(domain="sync"):
    ...

To determine (from code that is outside the FSM definition) whether it is currently in a particular state, the FSM can be captured; its .ongoing("Name") method returns a value that is true whenever the FSM is in the corresponding state. For example:

with m.FSM() as fsm:
    ...

with m.If(fsm.ongoing("Set Address")):
    ...

Note that in Python, assignments made using with x() as y: syntax persist past the end of the block.

Warning

If you make a typo in the state name provided to m.next = ... or fsm.ongoing(...), an empty and unreachable state with that name will be created with no diagnostic message.

This hazard will be eliminated in the future.

Warning

If a non-string object is provided as a state name to with m.State(...):, it is cast to a string first, which may lead to surprising behavior. with m.State(...): does not treat an enumeration value specially; if one is provided, it is cast to a string, and its numeric value will have no correspondence to the numeric value of the generated state signal.

This hazard will be eliminated in the future.

Note

If you are nesting two state machines within each other, the m.next = ... syntax always refers to the innermost one. To change the state of the outer state machine from within the inner one, use an intermediate signal.

Combinatorial evaluation

Signals in the combinatorial control domain change whenever any value used to compute them changes. The final value of a combinatorial signal is equal to its initial value updated by the active assignments in the assignment order. Combinatorial signals cannot hold any state.

Consider the following code:

a = Signal(8, reset=1)
with m.If(en):
    m.d.comb += a.eq(b + 1)

Whenever the signals en or b change, the signal a changes as well. If en is false, the final value of a is its initial value, 1. If en is true, the final value of a is equal to b + 1.

A combinatorial signal that is computed directly or indirectly based on its own value is a part of a combinatorial feedback loop, sometimes shortened to just feedback loop. Combinatorial feedback loops can be stable (e.g. implement a constant driver or a transparent latch), or unstable (e.g. implement a ring oscillator). Amaranth prohibits using assignments to describe any kind of a combinatorial feedback loop, including transparent latches.

Warning

The current version of Amaranth does not detect combinatorial feedback loops, but processes the design under the assumption that there aren’t any. If the design does in fact contain a combinatorial feedback loop, it will likely be silently miscompiled, though some cases will be detected during synthesis or place & route.

This hazard will be eliminated in the future.

Note

In the exceedingly rare case when a combinatorial feedback loop is desirable, it is possible to implement it by directly instantiating technology primitives (e.g. device-specific LUTs or latches). This is also the only way to introduce a combinatorial feedback loop with well-defined behavior in simulation and synthesis, regardless of the HDL being used.

Synchronous evaluation

Signals in synchronous control domains change whenever the active edge (a 0-to-1 or 1-to-0 transition, configured when creating the domain) occurs on the clock of the synchronous domain. In addition, the signals in clock domains with an asynchronous reset change when such a reset is asserted. The final value of a synchronous signal is equal to its initial value if the reset (of any type) is asserted, or to its current value updated by the active assignments in the assignment order otherwise. Synchronous signals always hold state.

Consider the following code:

timer = Signal(8)

with m.If(up):
    m.d.sync += timer.eq(timer + 1)
with m.Elif(down):
    m.d.sync += timer.eq(timer - 1)

Whenever there is a transition on the clock of the sync domain, the timer signal is incremented by one if up is true, decremented by one if down is true, and retains its value otherwise.

Clock domains

A new synchronous control domain, which is more often called a clock domain, can be defined in a design by creating a ClockDomain object and adding it to the m.domains collection:

m.domains.video = cd_video = ClockDomain(local=True)

If the name of the domain is not known upfront, another, less concise, syntax can be used instead:

def add_video_domain(n):
    cd = ClockDomain(f"video_{n}", local=True)
    m.domains += cd
    return cd

add_video_domain(2)

Tip

Whenever the created ClockDomain object is immediately assigned using the domain_name = ClockDomain(...) or m.domains.domain_name = ClockDomain(...) syntax, the name of the domain may be omitted from the ClockDomain() invocation. In other cases, it must be provided as the first argument.

A clock domain always has a clock signal, which can be accessed through the cd.clk attribute. By default, the active edge of the clock domain is positive; this means that the signals in the domain change when the clock signal transitions from 0 to 1. A clock domain can be configured to have a negative active edge so that signals in it change when the clock signal transitions from 1 to 0:

m.domains.jtag = ClockDomain(clk_edge="neg", local=True)

A clock domain also has a reset signal, which can be accessed through the cd.rst attribute. The reset signal is always active-high: the signals in the clock domain are reset if the value of the reset signal is 1. The initial value of this signal is 0, so if the reset signal is never assigned, the signals in the clock domain are never explicitly reset (they are still reset at power-on). Nevertheless, if its existence is undesirable, the clock domain can be configured to omit it:

m.domains.startup = ClockDomain(reset_less=True, local=True)

If a clock domain is defined in a module, it is also available in all of its submodules.

Warning

Always provide the local=True keyword argument when defining a clock domain. The behavior of clock domains defined without this keyword argument is subject to change in near future, and is intentionally left undocumented.

Warning

Clock domains use synchronous reset unless otherwise specified. Clock domains with asynchronous reset are implemented, but their behavior is subject to change in near future, and is intentionally left undocumented.

Late binding of clock and reset signals

Clock domains are late bound, which means that their signals and properties can be referred to using the domain’s name before the ClockDomain object with that name is created and added to the design. This happens whenever an assignment is added to a domain. In some cases, it is necessary to refer to the domain’s clock or reset signal using only the domain’s name. The ClockSignal and ResetSignal values make this possible:

m.d.comb += [
    ClockSignal().eq(bus_clk),
    ResetSignal().eq(~bus_rstn),
]

In this example, once the design is processed, bus_clk will be assigned to the clock signal of the clock domain sync found in this module or one of its containing modules. The bus_rstn signal will be assigned to the inverted reset signal of the same clock domain. With the sync domain created in the same module, these statements become equivalent to:

m.domains.sync = cd_sync = ClockDomain()
m.d.comb += [
    cd_sync.clk.eq(bus_clk),
    cd_sync.rst.eq(~bus_rstn),
]

The ClockSignal and ResetSignal values may also be assigned to other signals and used in expressions. They take a single argument, which is the name of the domain; if not specified, it defaults to "sync".

Warning

Be especially careful when using ClockSignal or cd.clk in expressions. Assigning to and from a clock signal is usually safe; any other operations may have unpredictable results. Consult the documentation for your synthesis toolchain and platform to understand which operations with a clock signal are permitted.

FPGAs usually have dedicated clocking facilities that can be used to disable, divide, or multiplex clock signals. When targeting an FPGA, these facilities should be used if at all possible, and expressions like ClockSignal() & en or Mux(sel, ClockSignal("a"), ClockSignal("b")) should be avoided.

Elaboration

Todo

Write this section.

Renaming domains

Todo

Write this section about DomainRenamer

Modifying control flow

Todo

Write this section about ResetInserter and EnableInserter

Memory arrays

Todo

Write this section.

Instances

Todo

Write this section.