+
+ +
+

Input/output buffers

+

The amaranth.lib.io module provides a platform-independent way to instantiate platform-specific input/output buffers: combinational, synchronous, and double data rate (DDR).

+
+

Introduction

+

The Amaranth language provides core I/O values that designate connections to external devices, and I/O buffer instances that implement platform-independent combinational I/O buffers. This low-level mechanism is foundational to all I/O in Amaranth and must be used whenever a device-specific platform is unavailable, but is limited in its capabilities. The amaranth.lib.io module builds on top of it to provide library I/O ports that specialize and annotate I/O values, and buffer components that connect ports to logic.

+
+

Note

+

Unfortunately, the terminology related to I/O has several ambiguities:

+ +

Amaranth documentation always uses the least ambiguous form of these terms.

+
+
+
+

Examples

+

All of the following examples assume that one of the built-in FPGA platforms is used.

+
from amaranth.lib import io, wiring
+from amaranth.lib.wiring import In, Out
+
+
+
+

LED output

+

In this example, a library I/O port for a LED is requested from the platform and driven to blink the LED:

+
class Toplevel(Elaboratable):
+    def elaborate(self, platform):
+        m = Module()
+
+        delay = Signal(24)
+        state = Signal()
+        with m.If(delay == 0):
+            m.d.sync += delay.eq(~0)
+            m.d.sync += state.eq(~state)
+        with m.Else():
+            m.d.sync += delay.eq(delay - 1)
+
+        m.submodules.led = led = io.Buffer("o", platform.request("led", dir="-"))
+        m.d.comb += led.o.eq(state)
+
+        return m
+
+
+
+
+

Clock input

+

In this example, a clock domain is created and driven from an external clock source:

+
class Toplevel(Elaboratable):
+    def elaborate(self, platform):
+        m = Module()
+
+        m.domains.sync = cd_sync = ClockDomain(local=True)
+
+        m.submodules.clk24 = clk24 = io.Buffer("i", platform.request("clk24", dir="-"))
+        m.d.comb += cd_sync.clk.eq(clk24.i)
+
+        ...
+
+        return m
+
+
+
+
+

Bidirectional bus

+

This example implements a peripheral for a clocked parallel bus. This peripheral can store and recall one byte of data. The data is stored with a write enable pulse, and recalled with a read enable pulse:

+
class Toplevel(Elaboratable):
+    def elaborate(self, platform):
+        m = Module()
+
+        m.submodules.bus_d = bus_d = io.FFBuffer("io", platform.request("d", dir="-"))
+        m.submodules.bus_re = bus_re = io.Buffer("i", platform.request("re", dir="-"))
+        m.submodules.bus_we = bus_we = io.Buffer("i", platform.request("we", dir="-"))
+
+        data = Signal.like(bus_d.i)
+        with m.If(bus_re.i):
+            m.d.comb += bus_d.oe.eq(1)
+            m.d.comb += bus_d.o.eq(data)
+        with m.Elif(bus_we.i):
+            m.d.sync += data.eq(bus_d.i)
+
+        return m
+
+
+

This bus requires a turn-around time of at least 1 cycle to avoid electrical contention.

+

Note that data appears on the bus one cycle after the read enable input is asserted, and that the write enable input stores the data present on the bus in the previous cycle. This is called pipelining and is typical for clocked buses; see FFBuffer for a waveform diagram. Although it increases the maximum clock frequency at which the bus can run, it also makes the bus signaling more complicated.

+
+
+

Clock forwarding

+

In this example of a source-synchronous interface, a clock signal is generated with the same phase as the DDR data signals associated with it:

+
class SourceSynchronousOutput(wiring.Component):
+    dout: In(16)
+
+    def elaborate(self, platform):
+        m = Module()
+
+        m.submodules.bus_dclk = bus_dclk = \
+            io.DDRBuffer("o", platform.request("dclk", dir="-"))
+        m.d.comb += [
+            bus_dclk.o[0].eq(1),
+            bus_dclk.o[1].eq(0),
+        ]
+
+        m.submodules.bus_dout = bus_dout = \
+            io.DDRBuffer("o", platform.request("dout", dir="-"))
+        m.d.comb += [
+            bus_dout.o[0].eq(self.dout[:8]),
+            bus_dout.o[1].eq(self.dout[8:]),
+        ]
+
+        return m
+
+
+

This component transmits dout on each cycle as two halves: the low 8 bits on the rising edge of the data clock, and the high 8 bits on the falling edge of the data clock. The transmission is edge-aligned, meaning that the data edges exactly coincide with the clock edges.

+
+
+
+

Ports

+
+
+class amaranth.lib.io.Direction
+

Represents direction of a library I/O port, or of an I/O buffer component.

+
+
+Input = 'i'
+

Input direction (from outside world to Amaranth design).

+
+ +
+
+Output = 'o'
+

Output direction (from Amaranth design to outside world).

+
+ +
+
+Bidir = 'io'
+

Bidirectional (can be switched between input and output).

+
+ +
+
+__and__(other)
+

Narrow the set of possible directions.

+
    +

  • self & self returns self.

    • +

  • Bidir & other returns other.

    • +

  • Input & Output raises ValueError.

    • +
+
+ +
+ +
+
+class amaranth.lib.io.PortLike
+

Represents an abstract library I/O port that can be passed to a buffer.

+

The port types supported by most platforms are SingleEndedPort and +DifferentialPort. Platforms may define additional port types where appropriate.

+
+

Note

+

amaranth.hdl.IOPort is not an instance of amaranth.lib.io.PortLike.

+
+
+
+abstract property direction
+

Direction of the port.

+
+
Return type:
+

Direction

+
+
+
+ +
+
+abstract __len__()
+

Computes the width of the port.

+
+
Returns:
+

The number of wires (for single-ended library I/O ports) or wire pairs (for differential +library I/O ports) this port consists of.

+
+
Return type:
+

int

+
+
+
+ +
+
+abstract __getitem__(key)
+

Slices the port.

+
+
Returns:
+

A new PortLike instance of the same type as self, containing a selection +of wires of this port according to key. Its width is the same as the length of +the slice (if key is a slice); or 1 (if key is an int).

+
+
Return type:
+

PortLike

+
+
+
+ +
+
+abstract __invert__()
+

Inverts polarity of the port.

+

Inverting polarity of a library I/O port has the same effect as adding inverters to +the i and o members of an I/O buffer component for that port.

+
+
Returns:
+

A new PortLike instance of the same type as self, containing the same +wires as this port, but with polarity inverted.

+
+
Return type:
+

PortLike

+
+
+
+ +
+ +
+
+class amaranth.lib.io.SingleEndedPort(io, *, invert=False, direction=Direction.Bidir)
+

Represents a single-ended library I/O port.

+

Implements the PortLike interface.

+
+
Parameters:
+
    +

  • io (IOValue) – Underlying core I/O value.

    • +

  • invert (bool or iterable of bool) – Polarity inversion. If the value is a simple bool, it specifies inversion for +the entire port. If the value is an iterable of bool, the iterable must have the +same length as the width of io, and the inversion is specified for individual wires.

    • +

  • direction (Direction or str) – Set of allowed buffer directions. A string is converted to a Direction first. +If equal to Direction.Input or Direction.Output, this port can only be used +with buffers of matching direction. If equal to Direction.Bidir, this port can be +used with buffers of any direction.

    • +
+
+
Attributes:
+
    +

  • io (IOValue) – The io parameter.

    • +

  • invert (tuple of bool) – The invert parameter, normalized to specify polarity inversion per-wire.

    • +

  • direction (Direction) – The direction parameter, normalized to the Direction enumeration.

    • +
+
+
+
+
+__add__(other)
+

Concatenates two single-ended library I/O ports.

+

The direction of the resulting port is:

+
    +

  • The same as the direction of both, if the two ports have the same direction.

    • +

  • Direction.Input if a bidirectional port is concatenated with an input port.

    • +

  • Direction.Output if a bidirectional port is concatenated with an output port.

    • +
+
+
Returns:
+

A new SingleEndedPort which contains wires from self followed by wires +from other, preserving their polarity inversion.

+
+
Return type:
+

SingleEndedPort

+
+
Raises:
+
    +

  • ValueError – If an input port is concatenated with an output port.

    • +

  • TypeError – If self and other have incompatible types.

    • +
+
+
+
+ +
+ +
+
+class amaranth.lib.io.DifferentialPort(p, n, *, invert=False, direction=Direction.Bidir)
+

Represents a differential library I/O port.

+

Implements the PortLike interface.

+
+
Parameters:
+
    +

  • p (IOValue) – Underlying core I/O value for the true (positive) half of the port.

    • +

  • n (IOValue) – Underlying core I/O value for the complement (negative) half of the port. +Must have the same width as p.

    • +

  • invert (bool or iterable of bool) – Polarity inversion. If the value is a simple bool, it specifies inversion for +the entire port. If the value is an iterable of bool, the iterable must have the +same length as the width of p and n, and the inversion is specified for +individual wires.

    • +

  • direction (Direction or str) – Set of allowed buffer directions. A string is converted to a Direction first. +If equal to Direction.Input or Direction.Output, this port can only be used +with buffers of matching direction. If equal to Direction.Bidir, this port can be +used with buffers of any direction.

    • +
+
+
Attributes:
+
    +

  • p (IOValue) – The p parameter.

    • +

  • n (IOValue) – The n parameter.

    • +

  • invert (tuple of bool) – The invert parameter, normalized to specify polarity inversion per-wire.

    • +

  • direction (Direction) – The direction parameter, normalized to the Direction enumeration.

    • +
+
+
+
+
+__add__(other)
+

Concatenates two differential library I/O ports.

+

The direction of the resulting port is:

+
    +

  • The same as the direction of both, if the two ports have the same direction.

    • +

  • Direction.Input if a bidirectional port is concatenated with an input port.

    • +

  • Direction.Output if a bidirectional port is concatenated with an output port.

    • +
+
+
Returns:
+

A new DifferentialPort which contains pairs of wires from self followed +by pairs of wires from other, preserving their polarity inversion.

+
+
Return type:
+

DifferentialPort

+
+
Raises:
+
    +

  • ValueError – If an input port is concatenated with an output port.

    • +

  • TypeError – If self and other have incompatible types.

    • +
+
+
+
+ +
+ +
+
+

Buffers

+
+
+class amaranth.lib.io.Buffer(direction, port)
+

A combinational I/O buffer component.

+

This buffer can be used on any platform; if the platform does not specialize its implementation, +an I/O buffer instance is used.

+

The following diagram defines the timing relationship between the underlying core I/O value +(for differential ports, the core I/O value of the true half) and the i, o, and +oe members:

+{'signal': [{'name': 'clk', 'wave': 'p.....'}, {'name': 'o', 'wave': 'x345x.', 'data': ['A', 'B', 'C']}, {'name': 'oe', 'wave': '01..0.'}, {}, {'name': 'port', 'wave': 'z345z.', 'data': ['A', 'B', 'C']}, {}, {'name': 'i', 'wave': 'x345x.', 'data': ['A', 'B', 'C']}], 'config': {'hscale': 2, 'skin': 'default'}}
+
Parameters:
+
    +

  • direction (Direction) – Direction of the buffer.

    • +

  • port (PortLike) – Port driven by the buffer.

    • +
+
+
Raises:
+

ValueError – Unless port.direction in (direction, Bidir).

+
+
Attributes:
+

signature (Buffer.Signature) – Signature(direction, len(port)).flip().

+
+
+
+
+class Signature(direction, width)
+

Signature of a combinational I/O buffer.

+
+
Parameters:
+
    +

  • direction (Direction) – Direction of the buffer.

    • +

  • width (int) – Width of the buffer.

    • +
+
+
Members:
+
    +

  • i (In(width)) – Present if direction in (Input, Bidir).

    • +

  • o (Out(width)) – Present if direction in (Output, Bidir).

    • +

  • oe (Out(1, init=0)) – Present if direction is Bidir.

    • +

  • oe (Out(1, init=1)) – Present if direction is Output.

    • +
+
+
+
+ +
+ +
+
+class amaranth.lib.io.FFBuffer(direction, port, *, i_domain=None, o_domain=None)
+

A registered I/O buffer component.

+

This buffer can be used on any platform; if the platform does not specialize its implementation, +an I/O buffer instance is used, combined with reset-less +registers on i, o, and oe members.

+

The following diagram defines the timing relationship between the underlying core I/O value +(for differential ports, the core I/O value of the true half) and the i, o, and +oe members:

+{'signal': [{'name': 'clk', 'wave': 'p......'}, {'name': 'o', 'wave': 'x345x..', 'data': ['A', 'B', 'C']}, {'name': 'oe', 'wave': '01..0..'}, {}, {'name': 'port', 'wave': 'z.345z.', 'data': ['A', 'B', 'C']}, {}, {'name': 'i', 'wave': 'x..345x', 'data': ['A', 'B', 'C']}], 'config': {'hscale': 2, 'skin': 'default'}}
+

Warning

+

On some platforms, this buffer can only be used with rising edge clock domains, and will +raise an exception during conversion of the design to a netlist otherwise.

+

This limitation will be lifted in the future.

+
+
+
Parameters:
+
    +

  • direction (Direction) – Direction of the buffer.

    • +

  • port (PortLike) – Port driven by the buffer.

    • +

  • i_domain (str) – Name of the input register’s clock domain. Used when direction in (Input, Bidir). +Defaults to "sync".

    • +

  • o_domain (str) – Name of the output and output enable registers’ clock domain. Used when +direction in (Output, Bidir). Defaults to "sync".

    • +
+
+
Attributes:
+

signature (FFBuffer.Signature) – Signature(direction, len(port)).flip().

+
+
+
+
+class Signature(direction, width)
+

Signature of a registered I/O buffer.

+
+
Parameters:
+
    +

  • direction (Direction) – Direction of the buffer.

    • +

  • width (int) – Width of the buffer.

    • +
+
+
Members:
+
    +

  • i (In(width)) – Present if direction in (Input, Bidir).

    • +

  • o (Out(width)) – Present if direction in (Output, Bidir).

    • +

  • oe (Out(1, init=0)) – Present if direction is Bidir.

    • +

  • oe (Out(1, init=1)) – Present if direction is Output.

    • +
+
+
+
+ +
+ +
+
+class amaranth.lib.io.DDRBuffer(direction, port, *, i_domain=None, o_domain=None)
+

A double data rate I/O buffer component.

+

This buffer is only available on platforms that support double data rate I/O.

+

The following diagram defines the timing relationship between the underlying core I/O value +(for differential ports, the core I/O value of the true half) and the i, o, and +oe members:

+{'head': {'tick': 0}, 'signal': [{'name': 'clk', 'wave': 'p.......'}, {'name': 'o[0]', 'wave': 'x357x...', 'node': '.a', 'data': ['A', 'C', 'E']}, {'name': 'o[1]', 'wave': 'x468x...', 'node': '.b', 'data': ['B', 'D', 'F']}, {'name': 'oe', 'wave': '01..0...'}, {'node': '........R.S', 'period': 0.5}, {'name': 'port', 'wave': 'z...345678z.....', 'node': '....123456', 'data': ['A', 'B', 'C', 'D', 'E', 'F'], 'period': 0.5}, {'node': '..P.Q', 'period': 0.5}, {'name': 'i[0]', 'wave': 'x...468x', 'node': '.....d', 'data': ['B', 'D', 'F']}, {'name': 'i[1]', 'wave': 'x..357x.', 'node': '.....e', 'data': ['A', 'C', 'E']}], 'edge': ['a~1', 'b-~2', 'P+Q t1', '5~-d', '6~e', 'R+S t2'], 'config': {'hscale': 2, 'skin': 'default'}}

The output data (labelled a, b) is input from o into internal registers at +the beginning of clock cycle 2, and transmitted at points labelled 1, 2 during the same +clock cycle. The output latency t1 is defined as the amount of cycles between the time of +capture of o and the time of transmission of rising edge data plus one cycle, and is 1 +for this diagram.

+

The received data is captured into internal registers during the clock cycle 4 at points +labelled 5, 6, and output to i during the next clock cycle (labelled d, e). +The input latency t2 is defined as the amount of cycles between the time of reception of +rising edge data and the time of update of i, and is 1 for this diagram.

+

The output enable signal is input from oe once per cycle and affects the entire cycle it +applies to. Its latency is defined in the same way as the output latency, and is equal to t1.

+
+

Warning

+

Some platforms include additional pipeline registers that may cause latencies t1 and t2 +to be higher than one cycle. At the moment there is no way to query these latencies.

+

This limitation will be lifted in the future.

+
+
+

Warning

+

On all supported platforms, this buffer can only be used with rising edge clock domains, +and will raise an exception during conversion of the design to a netlist otherwise.

+

This limitation may be lifted in the future.

+
+
+
Parameters:
+
    +

  • direction (Direction) – Direction of the buffer.

    • +

  • port (PortLike) – Port driven by the buffer.

    • +

  • i_domain (str) – Name of the input registers’ clock domain. Only used when direction in (Input, Bidir).

    • +

  • o_domain (str) – Name of the output and output enable registers’ clock domain. Only used when +direction in (Output, Bidir).

    • +
+
+
Attributes:
+

signature (DDRBuffer.Signature) – Signature(direction, len(port)).flip().

+
+
+
+
+class Signature(direction, width)
+

Signature of a double data rate I/O buffer.

+
+
Parameters:
+
    +

  • direction (Direction) – Direction of the buffer.

    • +

  • width (int) – Width of the buffer.

    • +
+
+
Members:
+
    +

  • i (In(ArrayLayout(width, 2))) – Present if direction in (Input, Bidir).

    • +

  • o (Out(ArrayLayout(width, 2))) – Present if direction in (Output, Bidir).

    • +

  • oe (Out(1, init=0)) – Present if direction is Bidir.

    • +

  • oe (Out(1, init=1)) – Present if direction is Output.

    • +
+
+
+
+ +
+ +
+
+ + +
+