Shapes of values

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

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

Shapes from integers

Casting a shape from an integeri is a shorthand for constructing a shape withunsigned(i):

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

Shapes from ranges

Casting a shape from aranger produces a shape that:

• has a width large enough to represent bothmin(r) andmax(r), but not larger, and

• is signed ifr 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)

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

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

Shapes from enumerations

Casting a shape from anenum.Enum subclass requires all of the enumeration members to haveconstant-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:

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

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

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

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

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

Custom shapes

Any Python value that implements theShapeCastable interface can extend the language with a custom shape-like object. For example, the standard library moduleamaranth.lib.data uses this facility to add support for aggregate data types to the language.

Values from integers

Casting a value from an integeri is equivalent toConst(i):

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

Values from enumeration members

Casting a value from an enumeration memberm is equivalent toConst(m.value,type(m)):

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

Signal shapes

A signal can be created with an explicitly specified shape (anyshape-like object); if omitted, the shape defaults tounsigned(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 aname, 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 thename= 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 aninitial value, specified with theinit= 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.

Signalsassigned in acombinational domain assume their initial value when none of the assignments areactive. Signals assigned in asynchronous domain assume their initial value afterpower-on reset and, unless the signal isreset-less,explicit reset. Signals that are used but never assigned are equivalent to constants of their initial value.

>>>Signal(4).init0>>>Signal(4,init=5).init5>>>Signal(Direction,init=Direction.LEFT).init1

Reset-less signals

Signals assigned in asynchronous domain can beresettable orreset-less, specified with thereset_less= parameter. If the parameter is not specified, signals are resettable by default. Resettable signals assume theirinitial value on explicit reset, which can be asserted via theclock domain or bymodifying control flow withResetInserter. Reset-less signals are not affected by explicit reset.

Signals assigned in acombinational domain are not affected by thereset_less parameter.

>>>Signal().reset_lessFalse>>>Signal(reset_less=True).reset_lessTrue

Performing or describing computations?

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

>>>a=5>>>a+16

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

>>>a=Signal(8,init=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:

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

Because the value ofa, and thereforea==0, is not known at the time when theif 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 timea has any concrete value, the Python program has long finished! To solve this problem, Amaranth provides its owncontrol 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 afinite 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 256unsigned(9)

Similarly, although Python integers are always signed and Amaranth values can be eithersigned 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 382signed(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:

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:

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

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

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

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

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

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

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:

Conceptually the same as applying the Pythonall() orany() function to the value viewed as a collection of bits.

Conceptually the same as applying the Pythonbool function to the value viewed as an integer.

While theValue.any() andValue.bool() operators return the same value, the use ofa.any() implies thata is semantically a bit sequence, and the use ofa.bool() implies thata is semantically a number.

Logical operators

Unlike the arithmetic or bitwise operators, it is not possible to change the behavior of the Python logical operatorsnot,and, andor. 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:

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

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

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

>>>stb=Signal()>>>use_stb=True>>>(notuse_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))

Bit sequence operators

Apart from acting as numbers, Amaranth values can also be treated as bitsequences, 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 Pythonints. 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 additionalpart 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:

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

All variations of the Python slice notation are supported, including “extended slicing”. E.g. all ofa[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.

In the concatenated value,a occupies the least significant bits, andb 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:

Match operator

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

If the pattern is astr, it is treated as a bit mask with “don’t care” bits. After removing whitespace, each character of the pattern is compared to the corresponding bit of the value, where the leftmost character of the pattern (with the lowest index) corresponds to the most significant bit of the value. If the pattern character is'0' or'1', the comparison succeeds if the bit equals0 or1 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 iscast to a constant and compared toval using theequality operator.

For example, given a 8-bit valueval,val.matches(1,'---- -01-') is equivalent to(val==1)|((val&0b0000_0110)==0b0000_0010). Bit patterns in this operator are treated similarly tobit sequence operators.

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

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 ofimm to the width ofpc, performs the addition, and produces an unsigned result.

Choice operator

TheMux(sel,val1,val0) choice expression (similar to theconditional expression in Python) is equal to the operandval1 ifsel is non-zero, and to the other operandval0 otherwise. If any ofval1 orval0 are signed, the expression itself is signed as well.

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

Assignable values

An assignment can affect a value that is more complex than just a signal. It is possible to assign to any combination ofsignals,bit slices,concatenations,part selects, andarray proxy objects 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

Them.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, them.d["<domain>"]+=... syntax can be used instead:

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

Every signal bit included in the target of an assignment becomes a part of the domain, or equivalently,driven by that domain. A signal bit can be either undriven or driven by exactly one domain; it is an error to add two assignments to the same signal bit 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) bit 0 from d.sync, but it is already driven from d.comb

However, two different bits of a signal can be driven from two different domains without an issue:

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

In addition to assignments,assertions anddebug prints can be added using the same syntax.

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 assignmentsactive or inactive. If all assignments to some signal bits areinactive, their final values are determined by the signal’s domain,combinational orsynchronous.

Active and inactive assignments

An assignment added inside an Amaranth control structure, i.e.withm.<...>: block, isactive if the condition of the control structure is satisfied, andinactive 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 theassignment 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)withm.If(timer==0):m.d.sync+=timer.eq(10)

Whentimer==0 is true, the code reduces to:

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

Due to theassignment order, it further reduces to:

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

Whentimer==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 awithm.If(cond1): block, which may be followed by one or morewithm.Elif(cond2): blocks, and optionally a finalwithm.Else(): block. This structure parallels Python’s ownif/elif/else control flow syntax. For example:

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

Within a singleIf/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 anElse block is present, then the statements within exactly one block will be active at any time, and the sequence as a whole is called afull condition.

Switch/Case control blocks

Case comparison, where a single value is examined against several differentpatterns, is described using awithm.Switch(value): block. This block can contain any amount ofwithm.Case(*patterns) andwithm.Default(): blocks. This structure parallels Python’s ownmatch/case control flow syntax. For example:

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

Within a singleSwitch block, the statements within at most one block will be active at any time. This will be the firstCase block in the order of definition whose patternmatches the value, or the firstDefault block, whichever is earlier.

If aDefault block is present, or the patterns in theCase blocks cover every possibleSwitch value, then the statements within exactly one block will be active at any time, and the sequence as a whole is called afull condition.

length=Signal(4)squared=Signal.like(length*length)withm.Switch(length):forvalueinrange(length.shape().width):withm.Case(value):m.d.comb+=squared.eq(value*value)

FSM/State control blocks

Simplefinite state machines are described using awithm.FSM(): block. This block can contain one or morewithm.State("Name") blocks. In addition to these blocks, them.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)withm.FSM():withm.State("Set Address"):m.d.sync+=addr.eq(0x1234)m.next="Strobe Read Enable"withm.State("Strobe Read Enable"):m.d.comb+=r_en.eq(1)m.next="Sample Data"withm.State("Sample Data"):m.d.sync+=latched.eq(r_data)withm.If(r_data==0):m.next="Set Address"# try again

The initial (and reset) state of the FSM can be provided when defining it using thewithm.FSM(init="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:

withm.FSM(init="Set Address"):...

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

withm.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:

withm.FSM()asfsm:...withm.If(fsm.ongoing("Set Address")):...

Note that in Python, assignments made usingwithx()asy: syntax persist past the end of the block.

Late binding of clock and reset signals

Clock domains arelate bound, which means that their signals and properties can be referred to using the domain’s name before theClockDomain object with that name is created and added to the design. This happens wheneveran 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. TheClockSignal andResetSignal values make this possible:

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

In this example, once the design is processed, the clock signal of the clock domainsync found in this module or one of its containing modules will be equal tobus_clk. The reset signal of the same clock domain will be equal to the negatedbus_rstn. With thesync 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),]

TheClockSignal andResetSignal 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".

Submodules

An elaboratable can be included within another elaboratable, which is called itscontaining elaboratable, by adding it as a submodule:

m.submodules.counter=counter=Counter()

If the name of a submodule is not known upfront, a different syntax should be used:

forninrange(3):m.submodules[f"counter_{n}"]=Counter()

A submodule can also be added without specifying a name:

counter=Counter()m.submodules+=counter

A non-Amaranth design unit can be added as a submodule using aninstance.

Modifying control flow

Control flow within an elaboratable can be altered without introducing a new clock domain by usingcontrol flow modifiers that affectsynchronous evaluation of signals in a specified domain (or domains). They never affectcombinational evaluation. There are two control flow modifiers:

• ResetInserter introduces a synchronous reset input (or inputs), updating all of the signals in the specified domains to theirinitial value whenever the active edge occurs on the clock of the domainif the synchronous reset input is asserted.

• EnableInserter introduces a synchronous enable input (or inputs), preventing any of the signals in the specified domains from changing value whenever the active edge occurs on the clock of the domainunless the synchronous enable input is asserted.

Control flow modifiers use the syntaxModifier(controls)(elaboratable), wherecontrols is a mapping fromclock domain names to 1-widevalues andelaboratable is anyelaboratable object. When only thesync domain is involved, instead of writingModifier({"sync":input})(elaboratable), the equivalent but shorterModifier(input)(elaboratable) syntax can be used.

The result of applying a control flow modifier to an elaboratable is, itself, an elaboratable object. A common way to use a control flow modifier is to apply it to another elaboratable while adding it as a submodule:

rst=Signal()m.submodules.counter=counter=ResetInserter(rst)(Counter())

A control flow modifier affects all logic within a given elaboratable and clock domain, which includes the submodules of that elaboratable.

Consider the following code:

m=Module()m.d.sync+=n.eq(n+1)m.d.comb+=z.eq(n==0)m=ResetInserter({"sync":rst})(m)m=EnableInserter({"sync":en})(m)

The application of control flow modifiers in it causes the behavior of the finalm to be identical to that of this module:

m=Module()withm.If(en):m.d.sync+=n.eq(n+1)withm.If(rst):m.d.sync+=n.eq(n.init)m.d.comb+=z.eq(n==0)

Renaming domains

A reusableelaboratable usually specifies the use of one or moreclock domains while leaving the details of clocking and initialization to a later phase in the design process.DomainRenamer can be used to alter a reusable elaboratable for integration in a specific design. Most elaboratables use a single clock domain namedsync, andDomainRenamer makes it easy to place such elaboratables in any clock domain of a design.

Clock domains can be renamed using the syntaxDomainRenamer(domains)(elaboratable), wheredomains is a mapping from clock domain names to clock domain names andelaboratable is anyelaboratable object. The keys ofdomains correspond to existing clock domain names specified byelaboratable, and the values ofdomains correspond to the clock domain names from the containing elaboratable that will be used instead. When only thesync domain is being renamed, instead of writingDomainRenamer({"sync":name})(elaboratable), the equivalent but shorterDomainRenamer(name)(elaboratable) syntax can be used.

The result of renaming clock domains in an elaboratable is, itself, an elaboratable object. A common way to rename domains is to applyDomainRenamer to another elaboratable while adding it as a submodule:

m.submodules.counter=counter=DomainRenamer("video")(counter)

Renaming a clock domain affects all logic within a given elaboratable and clock domain, which includes the submodules of that elaboratable. It does not affect any logic outside of that elaboratable.

Consider the following code:

m=Module()m.d.sync+=count.eq(count+1)m.d.comb+=zero.eq(count==0)m=DomainRenamer({"sync":"video"})(m)

The renaming of thesync clock domain in it causes the behavior of the finalm to be identical to that of this module:

m=Module()m.d.video+=count.eq(count+1)m.d.comb+=zero.eq(count==0)

I/O ports

Acore I/O port is a core I/O value representing a connection to a port of the topmost module in thedesign hierarchy. It can be created with an explicitly specified width.

fromamaranth.hdlimportIOPort

>>>port=IOPort(4)>>>port.width4

Core I/O ports can be named in the same way assignals:

>>>clk_port=IOPort(1,name="clk")>>>clk_port.name'clk'

If two core I/O ports with the same name exist in a design, one of them will be renamed to remove the ambiguity. Because the name of a core I/O port is significant, they should be named unambiguously.

I/O operators

Core I/O values support only a limited set ofsequence operators, all of which return another core I/O value. The following table lists the operators provided by Amaranth for core I/O values:

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

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

In the concatenated value,a occupies the lower indices andb the higher indices. Any number of arguments (zero, one, two, or more) are supported.

Concatenation of zero arguments,Cat(), returns a 0-bit regular value, however any such value is accepted (and ignored) anywhere an I/O value is expected.