From 271deed6ffaf6db715f5f542953d479856648672 Mon Sep 17 00:00:00 2001 From: Catherine Date: Wed, 10 Apr 2024 21:41:06 +0000 Subject: [PATCH] docs/stdlib/io: document I/O buffer library. --- amaranth/lib/io.py | 511 +++++++++++++++++++++++++++++-------------- docs/conf.py | 7 + docs/guide.rst | 32 +-- docs/stdlib.rst | 1 + docs/stdlib/io.rst | 209 ++++++++++++++++++ tests/test_lib_io.py | 13 -- 6 files changed, 581 insertions(+), 192 deletions(-) create mode 100644 docs/stdlib/io.rst diff --git a/amaranth/lib/io.py b/amaranth/lib/io.py index 2d94bfbf4..5541fc387 100644 --- a/amaranth/lib/io.py +++ b/amaranth/lib/io.py @@ -17,24 +17,22 @@ class Direction(enum.Enum): - """Represents a direction of an I/O port, or of an I/O buffer.""" + """Represents direction of a library I/O port, or of an I/O buffer component.""" - #: Input direction (from world to Amaranth design) + #: Input direction (from outside world to Amaranth design). Input = "i" - #: Output direction (from Amaranth design to world) + #: Output direction (from Amaranth design to outside world). Output = "o" - #: Bidirectional (can be switched between input and output) + #: Bidirectional (can be switched between input and output). Bidir = "io" - def __or__(self, other): - if not isinstance(other, Direction): - return NotImplemented - if self == other: - return self - else: - return Direction.Bidir - def __and__(self, other): + """Narrow the set of possible directions. + + * :py:`self & self` returns :py:`self`. + * :py:`Bidir & other` returns :py:`other`. + * :py:`Input & Output` raises :exc:`ValueError`. + """ if not isinstance(other, Direction): return NotImplemented if self == other: @@ -48,66 +46,95 @@ def __and__(self, other): class PortLike(metaclass=ABCMeta): - """Represents an abstract port that can be passed to a buffer. + """Represents an abstract library I/O port that can be passed to a buffer. The port types supported by most platforms are :class:`SingleEndedPort` and - :class:`DifferentialPort`. Platforms may define additional custom port types as appropriate. + :class:`DifferentialPort`. Platforms may define additional port types where appropriate. + + .. note:: + + :class:`amaranth.hdl.IOPort` is not an instance of :class:`amaranth.lib.io.PortLike`. """ @property @abstractmethod def direction(self): - """The direction of this port, as :class:`Direction`.""" + """Direction of the port. + + Returns + ------- + :class:`Direction` + """ raise NotImplementedError # :nocov: @abstractmethod def __len__(self): - """Returns the width of this port in bits.""" + """Computes the width of the port. + + Returns + ------- + :class:`int` + The number of wires (for single-ended library I/O ports) or wire pairs (for differential + library I/O ports) this port consists of. + """ raise NotImplementedError # :nocov: @abstractmethod - def __getitem__(self, index): - """Slices the port, returning another :class:`PortLike` with a subset - of its bits. - - The index can be a :class:`slice` or :class:`int`. If the index is - an :class:`int`, the result is a single-bit :class:`PortLike`.""" + def __getitem__(self, key): + """Slices the port. + + Returns + ------- + :class:`PortLike` + A new :class:`PortLike` instance of the same type as :py:`self`, containing a selection + of wires of this port according to :py:`key`. Its width is the same as the length of + the slice (if :py:`key` is a :class:`slice`); or 1 (if :py:`key` is an :class:`int`). + """ raise NotImplementedError # :nocov: @abstractmethod def __invert__(self): - """Returns a new :class:`PortLike` object like this one, but with inverted polarity. + """Inverts polarity of the port. + + Inverting polarity of a library I/O port has the same effect as adding inverters to + the :py:`i` and :py:`o` members of an I/O buffer component for that port. - The result should be such that using :class:`Buffer` on it is equivalent to using - :class:`Buffer` on the original, with added inverters on the :py:`i` and :py:`o` ports.""" + Returns + ------- + :class:`PortLike` + A new :class:`PortLike` instance of the same type as :py:`self`, containing the same + wires as this port, but with polarity inverted. + """ raise NotImplementedError # :nocov: class SingleEndedPort(PortLike): - """Represents a single-ended I/O port with optional inversion. + """Represents a single-ended library I/O port. + + Implements the :class:`PortLike` interface. Parameters ---------- io : :class:`IOValue` - The raw I/O value being wrapped. + Underlying core I/O value. invert : :class:`bool` or iterable of :class:`bool` - If true, the electrical state of the physical pin will be opposite from the Amaranth value - (the ``*Buffer`` classes will insert inverters on :py:`o` and :py:`i` pins, as appropriate). - - This can be used for various purposes: - - - Normalizing active-low pins (such as ``CS_B``) to be active-high in Amaranth code - - Compensating for boards where an inverting level-shifter (or similar circuitry) was used - on the pin - - If the value is a simple :class:`bool`, it is used for all bits of this port. If the value - is an iterable of :class:`bool`, the iterable must have the same length as :py:`io`, and - the inversion is specified per-bit. + Polarity inversion. If the value is a simple :class:`bool`, it specifies inversion for + the entire port. If the value is an iterable of :class:`bool`, the iterable must have the + same length as the width of :py:`io`, and the inversion is specified for individual wires. direction : :class:`Direction` or :class:`str` - Represents the allowed directions of this port. If equal to :attr:`Direction.Input` or - :attr:`Direction.Output`, this port can only be used with buffers of matching direction. - If equal to :attr:`Direction.Bidir`, this port can be used with buffers of any direction. - If a string is passed, it is cast to :class:`Direction`. + Set of allowed buffer directions. A string is converted to a :class:`Direction` first. + If equal to :attr:`Direction.Input` or :attr:`Direction.Output`, this port can only be used + with buffers of matching direction. If equal to :attr:`Direction.Bidir`, this port can be + used with buffers of any direction. + + Attributes + ---------- + io : :class:`IOValue` + The :py:`io` parameter. + invert : :class:`tuple` of :class:`bool` + The :py:`invert` parameter, normalized to specify polarity inversion per-wire. + direction : :class:`Direction` + The :py:`direction` parameter, normalized to the :class:`Direction` enumeration. """ def __init__(self, io, *, invert=False, direction=Direction.Bidir): self._io = IOValue.cast(io) @@ -126,52 +153,53 @@ def __init__(self, io, *, invert=False, direction=Direction.Bidir): @property def io(self): - """The :py:`io` argument passed to the constructor.""" return self._io @property def invert(self): - """The :py:`invert` argument passed to the constructor, normalized to a :class:`tuple` - of :class:`bool`.""" return self._invert @property def direction(self): - """The :py:`direction` argument passed to the constructor, normalized to :class:`Direction`.""" return self._direction def __len__(self): - """Returns the width of this port in bits. Equal to :py:`len(self.io)`.""" return len(self._io) def __invert__(self): - """Returns a new :class:`SingleEndedPort` with the opposite value of :py:`invert`.""" return SingleEndedPort(self._io, invert=tuple(not inv for inv in self._invert), direction=self._direction) def __getitem__(self, index): - """Slices the port, returning another :class:`SingleEndedPort` with a subset - of its bits. - - The index can be a :class:`slice` or :class:`int`. If the index is - an :class:`int`, the result is a single-bit :class:`SingleEndedPort`.""" return SingleEndedPort(self._io[index], invert=self._invert[index], direction=self._direction) def __add__(self, other): - """Concatenates two :class:`SingleEndedPort` objects together, returning a new - :class:`SingleEndedPort` object. - - When the concatenated ports have different directions, the conflict is resolved as follows: - - - If a bidirectional port is concatenated with an input port, the result is an input port. - - If a bidirectional port is concatenated with an output port, the result is an output port. - - If an input port is concatenated with an output port, :exc:`ValueError` is raised. + """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. + * :attr:`Direction.Input` if a bidirectional port is concatenated with an input port. + * :attr:`Direction.Output` if a bidirectional port is concatenated with an output port. + + Returns + ------- + :class:`SingleEndedPort` + A new :class:`SingleEndedPort` which contains wires from :py:`self` followed by wires + from :py:`other`, preserving their polarity inversion. + + Raises + ------ + :exc:`ValueError` + If an input port is concatenated with an output port. + :exc:`TypeError` + If :py:`self` and :py:`other` have incompatible types. """ if not isinstance(other, SingleEndedPort): return NotImplemented return SingleEndedPort(Cat(self._io, other._io), invert=self._invert + other._invert, - direction=self._direction | other._direction) + direction=self._direction & other._direction) def __repr__(self): if all(self._invert): @@ -184,32 +212,38 @@ def __repr__(self): class DifferentialPort(PortLike): - """Represents a differential I/O port with optional inversion. + """Represents a differential library I/O port. + + Implements the :class:`PortLike` interface. Parameters ---------- p : :class:`IOValue` - The raw I/O value used as positive (true) half of the port. + Underlying core I/O value for the true (positive) half of the port. n : :class:`IOValue` - The raw I/O value used as negative (complemented) half of the port. Must have the same - length as :py:`p`. - invert : :class:`bool` or iterable of :class`bool` - If true, the electrical state of the physical pin will be opposite from the Amaranth value - (the ``*Buffer`` classes will insert inverters on :py:`o` and :py:`i` pins, as appropriate). - - This can be used for various purposes: - - - Normalizing active-low pins (such as ``CS_B``) to be active-high in Amaranth code - - Compensating for boards where the P and N pins are swapped (e.g. for easier routing) - - If the value is a simple :class:`bool`, it is used for all bits of this port. If the value - is an iterable of :class:`bool`, the iterable must have the same length as :py:`io`, and - the inversion is specified per-bit. + Underlying core I/O value for the complement (negative) half of the port. + Must have the same width as :py:`p`. + invert : :class:`bool` or iterable of :class:`bool` + Polarity inversion. If the value is a simple :class:`bool`, it specifies inversion for + the entire port. If the value is an iterable of :class:`bool`, the iterable must have the + same length as the width of :py:`p` and :py:`n`, and the inversion is specified for + individual wires. direction : :class:`Direction` or :class:`str` - Represents the allowed directions of this port. If equal to :attr:`Direction.Input` or - :attr:`Direction.Output`, this port can only be used with buffers of matching direction. - If equal to :attr:`Direction.Bidir`, this port can be used with buffers of any direction. - If a string is passed, it is cast to :class:`Direction`. + Set of allowed buffer directions. A string is converted to a :class:`Direction` first. + If equal to :attr:`Direction.Input` or :attr:`Direction.Output`, this port can only be used + with buffers of matching direction. If equal to :attr:`Direction.Bidir`, this port can be + used with buffers of any direction. + + Attributes + ---------- + p : :class:`IOValue` + The :py:`p` parameter. + n : :class:`IOValue` + The :py:`n` parameter. + invert : :class:`tuple` of :class:`bool` + The :py:`invert` parameter, normalized to specify polarity inversion per-wire. + direction : :class:`Direction` + The :py:`direction` parameter, normalized to the :class:`Direction` enumeration. """ def __init__(self, p, n, *, invert=False, direction=Direction.Bidir): self._p = IOValue.cast(p) @@ -232,58 +266,58 @@ def __init__(self, p, n, *, invert=False, direction=Direction.Bidir): @property def p(self): - """The :py:`p` argument passed to the constructor.""" return self._p @property def n(self): - """The :py:`n` argument passed to the constructor.""" return self._n @property def invert(self): - """The :py:`invert` argument passed to the constructor, normalized to a :class:`tuple` - of :class:`bool`.""" return self._invert @property def direction(self): - """The :py:`direction` argument passed to the constructor, normalized to :class:`Direction`.""" return self._direction def __len__(self): - """Returns the width of this port in bits. Equal to :py:`len(self.p)` (and :py:`len(self.n)`).""" return len(self._p) def __invert__(self): - """Returns a new :class:`DifferentialPort` with the opposite value of :py:`invert`.""" return DifferentialPort(self._p, self._n, invert=tuple(not inv for inv in self._invert), - direction=self._direction) + direction=self._direction) def __getitem__(self, index): - """Slices the port, returning another :class:`DifferentialPort` with a subset - of its bits. - - The index can be a :class:`slice` or :class:`int`. If the index is - an :class:`int`, the result is a single-bit :class:`DifferentialPort`.""" return DifferentialPort(self._p[index], self._n[index], invert=self._invert[index], - direction=self._direction) + direction=self._direction) def __add__(self, other): - """Concatenates two :class:`DifferentialPort` objects together, returning a new - :class:`DifferentialPort` object. - - When the concatenated ports have different directions, the conflict is resolved as follows: - - - If a bidirectional port is concatenated with an input port, the result is an input port. - - If a bidirectional port is concatenated with an output port, the result is an output port. - - If an input port is concatenated with an output port, :exc:`ValueError` is raised. + """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. + * :attr:`Direction.Input` if a bidirectional port is concatenated with an input port. + * :attr:`Direction.Output` if a bidirectional port is concatenated with an output port. + + Returns + ------- + :class:`DifferentialPort` + A new :class:`DifferentialPort` which contains pairs of wires from :py:`self` followed + by pairs of wires from :py:`other`, preserving their polarity inversion. + + Raises + ------ + :exc:`ValueError` + If an input port is concatenated with an output port. + :exc:`TypeError` + If :py:`self` and :py:`other` have incompatible types. """ if not isinstance(other, DifferentialPort): return NotImplemented return DifferentialPort(Cat(self._p, other._p), Cat(self._n, other._n), - invert=self._invert + other._invert, - direction=self._direction | other._direction) + invert=self._invert + other._invert, + direction=self._direction & other._direction) def __repr__(self): if not any(self._invert): @@ -292,36 +326,74 @@ def __repr__(self): invert = True else: invert = self._invert - return f"DifferentialPort({self._p!r}, {self._n!r}, invert={invert!r}, direction={self._direction})" + return (f"DifferentialPort({self._p!r}, {self._n!r}, invert={invert!r}, " + f"direction={self._direction})") class Buffer(wiring.Component): - """A combinational I/O buffer. + """A combinational I/O buffer component. + + This buffer can be used on any platform; if the platform does not specialize its implementation, + an :ref:`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 :py:`i`, :py:`o`, and + :py:`oe` members: + + .. wavedrom:: io/buffer + + { + "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 + } + } Parameters ---------- direction : :class:`Direction` + Direction of the buffer. port : :class:`PortLike` + Port driven by the buffer. + + Raises + ------ + :exc:`ValueError` + Unless :py:`port.direction in (direction, Bidir)`. Attributes ---------- signature : :class:`Buffer.Signature` - Created based on constructor arguments. + :py:`Signature(direction, len(port)).flip()`. """ class Signature(wiring.Signature): - """A signature of a combinational I/O buffer. + """Signature of a combinational I/O buffer. Parameters ---------- direction : :class:`Direction` + Direction of the buffer. width : :class:`int` - - Attributes - ---------- - i: :py:`unsigned(width)` (if :py:`direction in (Direction.Input, Direction.Bidir)`) - o: :py:`unsigned(width)` (if :py:`direction in (Direction.Output, Direction.Bidir)`) - oe: :py:`unsigned(1, init=0)` (if :py:`direction is Direction.Bidir`) - oe: :py:`unsigned(1, init=1)` (if :py:`direction is Direction.Output`) + Width of the buffer. + + Members + ------- + i: :py:`In(width)` + Present if :py:`direction in (Input, Bidir)`. + o: :py:`Out(width)` + Present if :py:`direction in (Output, Bidir)`. + oe: :py:`Out(1, init=0)` + Present if :py:`direction is Bidir`. + oe: :py:`Out(1, init=1)` + Present if :py:`direction is Output`. """ def __init__(self, direction, width): self._direction = Direction(direction) @@ -343,7 +415,8 @@ def width(self): return self._width def __eq__(self, other): - return type(self) is type(other) and self.direction == other.direction and self.width == other.width + return (type(self) is type(other) and self.direction == other.direction and + self.width == other.width) def __repr__(self): return f"Buffer.Signature({self.direction}, {self.width})" @@ -403,47 +476,84 @@ def elaborate(self, platform): m.submodules += IOBufferInstance(self._port.p, o=o_inv, oe=self.oe, i=i_inv) m.submodules += IOBufferInstance(self._port.n, o=~o_inv, oe=self.oe) else: - raise TypeError("Cannot elaborate generic 'Buffer' with port {self._port!r}") + raise TypeError("Cannot elaborate generic 'Buffer' with port {self._port!r}") # :nocov: return m class FFBuffer(wiring.Component): - """A registered I/O buffer. + """A registered I/O buffer component. + + This buffer can be used on any platform; if the platform does not specialize its implementation, + an :ref:`I/O buffer instance ` is used, combined with reset-less + registers on :py:`i`, :py:`o`, and :py:`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 :py:`i`, :py:`o`, and + :py:`oe` members: + + .. wavedrom:: io/ff-buffer + + { + "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 + } + } + + .. 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. - Equivalent to a plain :class:`Buffer` combined with reset-less registers on :py:`i`, :py:`o`, - :py:`oe`. + This limitation will be lifted in the future. Parameters ---------- direction : :class:`Direction` + Direction of the buffer. port : :class:`PortLike` + Port driven by the buffer. i_domain : :class:`str` - Domain for input register. Only used when :py:`direction in (Direction.Input, Direction.Bidir)`. - Defaults to :py:`"sync"` + Name of the input register's clock domain. Used when :py:`direction in (Input, Bidir)`. + Defaults to :py:`"sync"`. o_domain : :class:`str` - Domain for output and output enable registers. Only used when - :py:`direction in (Direction.Output, Direction.Bidir)`. Defaults to :py:`"sync"` + Name of the output and output enable registers' clock domain. Used when + :py:`direction in (Output, Bidir)`. Defaults to :py:`"sync"`. Attributes ---------- - signature : FFBuffer.Signature - Created based on constructor arguments. + signature : :class:`FFBuffer.Signature` + :py:`Signature(direction, len(port)).flip()`. """ class Signature(wiring.Signature): - """A signature of a registered I/O buffer. + """Signature of a registered I/O buffer. Parameters ---------- direction : :class:`Direction` + Direction of the buffer. width : :class:`int` - - Attributes - ---------- - i: :py:`unsigned(width)` (if :py:`direction in (Direction.Input, Direction.Bidir)`) - o: :py:`unsigned(width)` (if :py:`direction in (Direction.Output, Direction.Bidir)`) - oe: :py:`unsigned(1, init=0)` (if :py:`direction is Direction.Bidir`) - oe: :py:`unsigned(1, init=1)` (if :py:`direction is Direction.Output`) + Width of the buffer. + + Members + ------- + i: :py:`In(width)` + Present if :py:`direction in (Input, Bidir)`. + o: :py:`Out(width)` + Present if :py:`direction in (Output, Bidir)`. + oe: :py:`Out(1, init=0)` + Present if :py:`direction is Bidir`. + oe: :py:`Out(1, init=1)` + Present if :py:`direction is Output`. """ def __init__(self, direction, width): self._direction = Direction(direction) @@ -465,7 +575,8 @@ def width(self): return self._width def __eq__(self, other): - return type(self) is type(other) and self.direction == other.direction and self.width == other.width + return (type(self) is type(other) and self.direction == other.direction and + self.width == other.width) def __repr__(self): return f"FFBuffer.Signature({self.direction}, {self.width})" @@ -533,48 +644,117 @@ def elaborate(self, platform): class DDRBuffer(wiring.Component): - """A double data rate registered I/O buffer. - - In the input direction, the port is sampled at both edges of the input clock domain. - The data sampled on the active clock edge of the domain appears on :py:`i[0]` with a delay - of 1 clock cycle. The data sampled on the opposite clock edge appears on :py:`i[1]` with a delay - of 0.5 clock cycle. Both :py:`i[0]` and :py:`i[1]` thus change on the active clock edge of the domain. - - In the output direction, both :py:`o[0]` and :py:`o[1]` are sampled on the active clock edge - of the domain. The value of :py:`o[0]` immediately appears on the output port. The value - of :py:`o[1]` then appears on the output port on the opposite edge, with a delay of 0.5 clock cycle. - - Support for this compoment is platform-specific, and may be missing on some platforms. + """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 :py:`i`, :py:`o`, and + :py:`oe` members: + + .. + This diagram should have `port` phase shifted, but it hits wavedrom/wavedrom#416. + It is also affected by wavedrom/wavedrom#417. + + .. wavedrom:: io/ddr-buffer + + { + "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 + } + } + + The output data (labelled *a*, *b*) is input from :py:`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 :py:`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 :py:`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 :py:`i`, and is 1 for this diagram. + + The output enable signal is input from :py:`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 : :class:`Direction` + Direction of the buffer. port : :class:`PortLike` + Port driven by the buffer. i_domain : :class:`str` - Domain for input register. Only used when :py:`direction in (Direction.Input, Direction.Bidir)`. + Name of the input registers' clock domain. Only used when :py:`direction in (Input, Bidir)`. o_domain : :class:`str` - Domain for output and output enable registers. Only used when - :py:`direction in (Direction.Output, Direction.Bidir)`. + Name of the output and output enable registers' clock domain. Only used when + :py:`direction in (Output, Bidir)`. Attributes ---------- - signature : DDRBuffer.Signature - Created based on constructor arguments. + signature : :class:`DDRBuffer.Signature` + :py:`Signature(direction, len(port)).flip()`. """ class Signature(wiring.Signature): - """A signature of a double data rate registered I/O buffer. + """Signature of a double data rate I/O buffer. Parameters ---------- direction : :class:`Direction` + Direction of the buffer. width : :class:`int` - - Attributes - ---------- - i: :py:`unsigned(ArrayLayout(width, 2))` (if :py:`direction in (Direction.Input, Direction.Bidir)`) - o: :py:`unsigned(ArrayLayout(width, 2))` (if :py:`direction in (Direction.Output, Direction.Bidir)`) - oe: :py:`unsigned(1, init=0)` (if :py:`direction is Direction.Bidir`) - oe: :py:`unsigned(1, init=1)` (if :py:`direction is Direction.Output`) + Width of the buffer. + + Members + ------- + i: :py:`In(ArrayLayout(width, 2))` + Present if :py:`direction in (Input, Bidir)`. + o: :py:`Out(ArrayLayout(width, 2))` + Present if :py:`direction in (Output, Bidir)`. + oe: :py:`Out(1, init=0)` + Present if :py:`direction is Bidir`. + oe: :py:`Out(1, init=1)` + Present if :py:`direction is Output`. """ def __init__(self, direction, width): self._direction = Direction(direction) @@ -596,7 +776,8 @@ def width(self): return self._width def __eq__(self, other): - return type(self) is type(other) and self.direction == other.direction and self.width == other.width + return (type(self) is type(other) and self.direction == other.direction and + self.width == other.width) def __repr__(self): return f"DDRBuffer.Signature({self.direction}, {self.width})" @@ -643,7 +824,7 @@ def elaborate(self, platform): if hasattr(platform, "get_io_buffer"): return platform.get_io_buffer(self) - raise NotImplementedError("DDR buffers cannot be elaborated without a supported platform") + raise NotImplementedError(f"DDR buffers are not supported on {platform!r}") # :nocov: class Pin(wiring.PureInterface): diff --git a/docs/conf.py b/docs/conf.py index 964c54c18..146eb1b20 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,6 +37,7 @@ "members": True } autodoc_preserve_defaults = True +autodoc_inherit_docstrings = False napoleon_google_docstring = False napoleon_numpy_docstring = True @@ -71,3 +72,9 @@ # React page with README content included as a JSON payload. r"^https://github\.com/[^/]+/[^/]+/$", ] + + +# Silence the warnings globally; otherwise they may fire on object destruction and crash completely +# unrelated tests. +import amaranth._unused +amaranth._unused.MustUse._MustUse__silence = True diff --git a/docs/guide.rst b/docs/guide.rst index 6e0b6d6ef..71838a96c 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -1673,9 +1673,9 @@ Amaranth provides support for memories in the standard library module :mod:`amar I/O values ========== -To interoperate with external circuitry, Amaranth provides *I/O values*, which represent bundles of wires carrying uninterpreted signals. Unlike regular :ref:`values `, which represent binary numbers and can be :ref:`assigned ` to create a unidirectional connection or used in computations, I/O values represent electrical signals that may be digital or analog and have no :ref:`shape `, cannot be assigned, used in computations, or simulated. +To interoperate with external circuitry, Amaranth provides *core I/O values*, which represent bundles of wires carrying uninterpreted signals. Unlike regular :ref:`values `, which represent binary numbers and can be :ref:`assigned ` to create a unidirectional connection or used in computations, core I/O values represent electrical signals that may be digital or analog and have no :ref:`shape `, cannot be assigned, used in computations, or simulated. -I/O values are only used to define connections between non-Amaranth building blocks that traverse an Amaranth design, including :ref:`instances ` and :ref:`I/O buffer instances `. +Core I/O values are only used to define connections between non-Amaranth building blocks that traverse an Amaranth design, including :ref:`instances ` and :ref:`I/O buffer instances `. .. _lang-ioports: @@ -1683,7 +1683,7 @@ I/O values are only used to define connections between non-Amaranth building blo I/O ports --------- -An *I/O port* is an I/O value representing a connection to a port of the topmost module in the :ref:`design hierarchy `. It can be created with an explicitly specified width. +A *core I/O port* is a core I/O value representing a connection to a port of the topmost module in the :ref:`design hierarchy `. It can be created with an explicitly specified width. .. testcode:: @@ -1695,7 +1695,7 @@ An *I/O port* is an I/O value representing a connection to a port of the topmost >>> port.width 4 -I/O ports can be named in the same way as :ref:`signals `: +Core I/O ports can be named in the same way as :ref:`signals `: .. doctest:: @@ -1703,7 +1703,7 @@ I/O ports can be named in the same way as :ref:`signals `: >>> clk_port.name 'clk' -If two 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 an I/O port is significant, they should be named unambiguously. +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. .. _lang-ioops: @@ -1711,7 +1711,7 @@ If two I/O ports with the same name exist in a design, one of them will be renam I/O operators ------------- -I/O values support only a limited set of :ref:`sequence ` operators, all of which return another I/O value. The following table lists the I/O operators provided by Amaranth: +Core I/O values support only a limited set of :ref:`sequence ` operators, all of which return another core I/O value. The following table lists the operators provided by Amaranth for core I/O values: =============== ============================== =================== Operation Description Notes @@ -1747,9 +1747,9 @@ An instance can be added as a submodule using the :py:`m.submodules.name = Insta * An attribute is specified using the :py:`a_ANAME=attr` or :py:`("a", "ANAME", attr)` syntaxes. The :py:`attr` must be an :class:`int`, a :class:`str`, or a :class:`Const`. * A parameter is specified using the :py:`p_PNAME=param` or :py:`("p", "PNAME", param)` syntaxes. The :py:`param` must be an :class:`int`, a :class:`str`, or a :class:`Const`. -* An input is specified using the :py:`i_INAME=in_val` or :py:`("i", "INAME", in_val)` syntaxes. The :py:`in_val` must be an :ref:`I/O value ` or a :ref:`value-like ` object. -* An output is specified using the :py:`o_ONAME=out_val` or :py:`("o", "ONAME", out_val)` syntaxes. The :py:`out_val` must be an :ref:`I/O value ` or a :ref:`value-like ` object that casts to a :ref:`signal `, a concatenation of signals, or a slice of a signal. -* An inout is specified using the :py:`io_IONAME=inout_val` or :py:`("io", "IONAME", inout_val)` syntaxes. The :py:`inout_val` must be an :ref:`I/O value `. +* An input is specified using the :py:`i_INAME=in_val` or :py:`("i", "INAME", in_val)` syntaxes. The :py:`in_val` must be a :ref:`core I/O value ` or a :ref:`value-like ` object. +* An output is specified using the :py:`o_ONAME=out_val` or :py:`("o", "ONAME", out_val)` syntaxes. The :py:`out_val` must be a :ref:`core I/O value ` or a :ref:`value-like ` object that casts to a :ref:`signal `, a concatenation of signals, or a slice of a signal. +* An inout is specified using the :py:`io_IONAME=inout_val` or :py:`("io", "IONAME", inout_val)` syntaxes. The :py:`inout_val` must be a :ref:`core I/O value `. The two following examples use both syntaxes to add the same instance of type ``external`` as a submodule named ``processor``: @@ -1833,7 +1833,11 @@ Although an :class:`Instance` is not an elaboratable, as a special case, it can I/O buffer instances ==================== -An *I/O buffer instance* is a submodule that allows connecting :ref:`I/O values ` and regular :ref:`values ` without the use of an external, toolchain- and technology-dependent :ref:`instance `. It can be created in four configurations: input, output, tristatable output, and bidirectional (input/output). +.. note:: + + I/O buffer instances are a low-level primitive which is documented to ensure that the standard library does not rely on private interfaces in the core language. Most designers should use the :mod:`amaranth.lib.io` module instead. + +An *I/O buffer instance* is a submodule that allows connecting :ref:`core I/O values ` and regular :ref:`values ` without the use of an external, toolchain- and technology-dependent :ref:`instance `. It can be created in four configurations: input, output, tristatable output, and bidirectional (input/output). .. testcode:: @@ -1841,7 +1845,7 @@ An *I/O buffer instance* is a submodule that allows connecting :ref:`I/O values m = Module() -In the input configuration, the buffer combinationally drives a signal :py:`i` by the port: +In the input configuration, the buffer instance combinationally drives a signal :py:`i` by the port: .. testcode:: @@ -1849,7 +1853,7 @@ In the input configuration, the buffer combinationally drives a signal :py:`i` b port_i = Signal(4) m.submodules += IOBufferInstance(port, i=port_i) -In the output configuration, the buffer combinationally drives the port by a value :py:`o`: +In the output configuration, the buffer instance combinationally drives the port by a value :py:`o`: .. testcode:: @@ -1857,7 +1861,7 @@ In the output configuration, the buffer combinationally drives the port by a val port_o = Signal(4) m.submodules += IOBufferInstance(port, o=port_o) -In the tristatable output configuration, the buffer combinationally drives the port by a value :py:`o` if :py:`oe` is asserted, and does not drive (leaves in a high-impedance state, or tristates) the port otherwise: +In the tristatable output configuration, the buffer instance combinationally drives the port by a value :py:`o` if :py:`oe` is asserted, and does not drive (leaves in a high-impedance state, or tristates) the port otherwise: .. testcode:: @@ -1866,7 +1870,7 @@ In the tristatable output configuration, the buffer combinationally drives the p port_oe = Signal() m.submodules += IOBufferInstance(port, o=port_o, oe=port_oe) -In the bidirectional (input/output) configuration, the buffer combinationally drives a signal :py:`i` by the port, combinationally drives the port by a value :py:`o` if :py:`oe` is asserted, and does not drive (leaves in a high-impedance state, or tristates) the port otherwise: +In the bidirectional (input/output) configuration, the buffer instance combinationally drives a signal :py:`i` by the port, combinationally drives the port by a value :py:`o` if :py:`oe` is asserted, and does not drive (leaves in a high-impedance state, or tristates) the port otherwise: .. testcode:: diff --git a/docs/stdlib.rst b/docs/stdlib.rst index add7c5136..4fbc51068 100644 --- a/docs/stdlib.rst +++ b/docs/stdlib.rst @@ -19,6 +19,7 @@ The Amaranth standard library is separate from the Amaranth language: everything stdlib/wiring stdlib/meta stdlib/memory + stdlib/io stdlib/cdc stdlib/coding stdlib/fifo diff --git a/docs/stdlib/io.rst b/docs/stdlib/io.rst new file mode 100644 index 000000000..3740ccfdd --- /dev/null +++ b/docs/stdlib/io.rst @@ -0,0 +1,209 @@ +Input/output buffers +==================== + +.. py:module:: amaranth.lib.io + +The :mod:`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 :ref:`core I/O values ` that designate connections to external devices, and :ref:`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 :mod:`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* (:class:`.Signal` objects created by the :mod:`amaranth.lib.wiring` module), a *core I/O port* (:class:`amaranth.hdl.IOPort` object), or a *library I/O port* (:class:`amaranth.lib.io.PortLike` object). + * A "I/O buffer" could refer to an *I/O buffer instance* (:class:`amaranth.hdl.IOBufferInstance`) or a *I/O buffer component* (:class:`amaranth.lib.io.Buffer`, :class:`.FFBuffer`, or :class:`.DDRBuffer` objects). + + Amaranth documentation always uses the least ambiguous form of these terms. + + +Examples +-------- + +.. testsetup:: + + from amaranth import * + + class MockPlatform: + def request(self, name, *, dir): + from amaranth.hdl import IOPort + from amaranth.lib import io + if name == "led": + return io.SingleEndedPort(IOPort(1, name=name), direction="o") + if name == "clk24": + return io.SingleEndedPort(IOPort(1, name=name), direction="i") + if name == "d": + return io.SingleEndedPort(IOPort(8, name=name), direction="io") + if name == "re": + return io.SingleEndedPort(IOPort(1, name=name), direction="i") + if name == "we": + return io.SingleEndedPort(IOPort(1, name=name), direction="i") + if name == "dclk": + return io.SingleEndedPort(IOPort(1, name=name), direction="o") + if name == "dout": + return io.SingleEndedPort(IOPort(8, name=name), direction="o") + raise NameError + + def get_io_buffer(self, buffer): + return Fragment() + + def build(self, top): + from amaranth.back import rtlil + return rtlil.convert(Fragment.get(top, self), ports=[]) + + +All of the following examples assume that one of the built-in FPGA platforms is used. + +.. testcode:: + + 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: + +.. testcode:: + + 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 + +.. testcode:: + :hide: + + MockPlatform().build(Toplevel()) + + +Clock input ++++++++++++ + +In this example, a clock domain is created and driven from an external clock source: + +.. testcode:: + + 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 + +.. testcode:: + :hide: + + MockPlatform().build(Toplevel()) + + +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: + +.. testcode:: + + 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 + +.. testcode:: + :hide: + + MockPlatform().build(Toplevel()) + +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 :class:`.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: + +.. testcode:: + + 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 + +.. testcode:: + :hide: + + MockPlatform().build(SourceSynchronousOutput()) + +This component transmits :py:`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 +----- + +.. autoclass:: Direction() + +.. autoclass:: PortLike +.. autoclass:: SingleEndedPort +.. autoclass:: DifferentialPort + + +Buffers +------- + +.. autoclass:: Buffer(direction, port) +.. autoclass:: FFBuffer(direction, port, *, i_domain=None, o_domain=None) +.. autoclass:: DDRBuffer(direction, port, *, i_domain=None, o_domain=None) diff --git a/tests/test_lib_io.py b/tests/test_lib_io.py index aabf945fe..26ed23fb3 100644 --- a/tests/test_lib_io.py +++ b/tests/test_lib_io.py @@ -11,19 +11,6 @@ class DirectionTestCase(FHDLTestCase): - def test_or(self): - self.assertIs(Direction.Input | Direction.Input, Direction.Input) - self.assertIs(Direction.Input | Direction.Output, Direction.Bidir) - self.assertIs(Direction.Input | Direction.Bidir, Direction.Bidir) - self.assertIs(Direction.Output | Direction.Input, Direction.Bidir) - self.assertIs(Direction.Output | Direction.Output, Direction.Output) - self.assertIs(Direction.Output | Direction.Bidir, Direction.Bidir) - self.assertIs(Direction.Bidir | Direction.Input, Direction.Bidir) - self.assertIs(Direction.Bidir | Direction.Output, Direction.Bidir) - self.assertIs(Direction.Bidir | Direction.Bidir, Direction.Bidir) - with self.assertRaises(TypeError): - Direction.Bidir | 3 - def test_and(self): self.assertIs(Direction.Input & Direction.Input, Direction.Input) self.assertIs(Direction.Input & Direction.Bidir, Direction.Input)