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:
A “port” could refer to an interface port (
Signal
objects created by theamaranth.lib.wiring
module), a core I/O port (amaranth.hdl.IOPort
object), or a library I/O port (amaranth.lib.io.PortLike
object).A “I/O buffer” could refer to an I/O buffer instance (
amaranth.hdl.IOBufferInstance
) or a I/O buffer component (amaranth.lib.io.Buffer
,FFBuffer
, orDDRBuffer
objects).
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
returnsself
.Bidir & other
returnsother
.Input & Output
raisesValueError
.
- 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
andDifferentialPort
. Platforms may define additional port types where appropriate.Note
amaranth.hdl.IOPort
is not an instance ofamaranth.lib.io.PortLike
.- 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:
- abstract __getitem__(key)
Slices the port.
- 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
ando
members of an I/O buffer component for that port.
- 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 ofbool
) – Polarity inversion. If the value is a simplebool
, it specifies inversion for the entire port. If the value is an iterable ofbool
, the iterable must have the same length as the width ofio
, and the inversion is specified for individual wires.direction (
Direction
orstr
) – Set of allowed buffer directions. A string is converted to aDirection
first. If equal toDirection.Input
orDirection.Output
, this port can only be used with buffers of matching direction. If equal toDirection.Bidir
, this port can be used with buffers of any direction.
- Attributes:
- __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 fromself
followed by wires fromother
, preserving their polarity inversion.- Return type:
- Raises:
ValueError – If an input port is concatenated with an output port.
TypeError – If
self
andother
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 asp
.invert (
bool
or iterable ofbool
) – Polarity inversion. If the value is a simplebool
, it specifies inversion for the entire port. If the value is an iterable ofbool
, the iterable must have the same length as the width ofp
andn
, and the inversion is specified for individual wires.direction (
Direction
orstr
) – Set of allowed buffer directions. A string is converted to aDirection
first. If equal toDirection.Input
orDirection.Output
, this port can only be used with buffers of matching direction. If equal toDirection.Bidir
, this port can be used with buffers of any direction.
- Attributes:
- __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 fromself
followed by pairs of wires fromother
, preserving their polarity inversion.- Return type:
- Raises:
ValueError – If an input port is concatenated with an output port.
TypeError – If
self
andother
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
, andoe
members:- Parameters:
- 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:
- Members:
i (
In(width)
) – Present ifdirection in (Input, Bidir)
.o (
Out(width)
) – Present ifdirection in (Output, Bidir)
.oe (
Out(1, init=0)
) – Present ifdirection is Bidir
.oe (
Out(1, init=1)
) – Present ifdirection 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
, andoe
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
, andoe
members: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 whendirection in (Input, Bidir)
. Defaults to"sync"
.o_domain (
str
) – Name of the output and output enable registers’ clock domain. Used whendirection 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:
- Members:
i (
In(width)
) – Present ifdirection in (Input, Bidir)
.o (
Out(width)
) – Present ifdirection in (Output, Bidir)
.oe (
Out(1, init=0)
) – Present ifdirection is Bidir
.oe (
Out(1, init=1)
) – Present ifdirection 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
, andoe
members: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 ofo
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 ofi
, 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 register’s clock domain. Used whendirection in (Input, Bidir)
. Defaults to"sync"
.o_domain (
str
) – Name of the output and output enable registers’ clock domain. Used whendirection in (Output, Bidir)
. Defaults to"sync"
.
- Attributes:
signature (
DDRBuffer.Signature
) –Signature(direction, len(port)).flip()
.
- class Signature(direction, width)
Signature of a double data rate I/O buffer.
- Parameters:
- Members:
i (
In(ArrayLayout(width, 2))
) – Present ifdirection in (Input, Bidir)
.o (
Out(ArrayLayout(width, 2))
) – Present ifdirection in (Output, Bidir)
.oe (
Out(1, init=0)
) – Present ifdirection is Bidir
.oe (
Out(1, init=1)
) – Present ifdirection is Output
.