Implement RFC 53: Low-level I/O primitives.

Co-authored-by: Catherine <whitequark@whitequark.org>
Co-authored-by: mcclure <mcclure@users.noreply.github.com>

Author: 3 people

amaranth/back/rtlil.py

@@ -272,7 +272,7 @@ def __init__(self, memid):
 
 
 class ModuleEmitter:
-    def __init__(self, builder, netlist, module, name_map, empty_checker):
+    def __init__(self, builder, netlist: _nir.Netlist, module: _nir.Module, name_map, empty_checker):
         self.builder = builder
         self.netlist = netlist
         self.module = module
@@ -293,6 +293,7 @@ def __init__(self, builder, netlist, module, name_map, empty_checker):
         self.sigport_wires = {} # signal or port name -> (wire, value)
         self.driven_sigports = set() # set of signal or port name
         self.nets = {} # net -> (wire name, bit idx)
+        self.ionets = {} # ionet -> (wire name, bit idx)
         self.cell_wires = {} # cell idx -> wire name
         self.instance_wires = {} # (cell idx, output name) -> wire name
 
@@ -302,6 +303,7 @@ def emit(self):
         self.collect_init_attrs()
         self.emit_signal_wires()
         self.emit_port_wires()
+        self.emit_io_port_wires()
         self.emit_cell_wires()
         self.emit_submodule_wires()
         self.emit_connects()
@@ -406,11 +408,28 @@ def emit_port_wires(self):
             self.sigport_wires[name] = (wire, value)
             if flow == _nir.ModuleNetFlow.Output:
                 continue
-            # If we just emitted an input or inout port, it is driving the value.
+            # If we just emitted an input port, it is driving the value.
             self.driven_sigports.add(name)
             for bit, net in enumerate(value):
                 self.nets[net] = (wire, bit)
 
+    def emit_io_port_wires(self):
+        for idx, (name, (value, dir)) in enumerate(self.module.io_ports.items()):
+            port_id = idx + len(self.module.ports)
+            if self.module.parent is None:
+                port = self.netlist.io_ports[value[0].port]
+                attrs = port.attrs
+                src_loc = port.src_loc
+            else:
+                attrs = {}
+                src_loc = None
+            wire = self.builder.wire(width=len(value),
+                                     port_id=port_id, port_kind=dir.value,
+                                     name=name, attrs=attrs,
+                                     src=_src(src_loc))
+            for bit, net in enumerate(value):
+                self.ionets[net] = (wire, bit)
+
     def emit_driven_wire(self, value):
         # Emits a wire for a value, in preparation for driving it.
         if value in self.value_names:
@@ -454,7 +473,9 @@ def emit_cell_wires(self):
             elif isinstance(cell, _nir.Initial):
                 width = 1
             elif isinstance(cell, _nir.IOBuffer):
-                width = len(cell.pad)
+                if cell.dir is _nir.IODirection.Output:
+                    continue # No outputs.
+                width = len(cell.port)
             else:
                 assert False # :nocov:
             # Single output cell connected to a wire.
@@ -503,6 +524,28 @@ def sigspec(self, *parts: '_nir.Net | Iterable[_nir.Net]'):
             return chunks[0]
         return "{ " + " ".join(reversed(chunks)) + " }"
 
+    def io_sigspec(self, value: _nir.IOValue):
+        chunks = []
+        begin_pos = 0
+        while begin_pos < len(value):
+            end_pos = begin_pos
+            wire, start_bit = self.ionets[value[begin_pos]]
+            bit = start_bit
+            while (end_pos < len(value) and
+                    self.ionets[value[end_pos]] == (wire, bit)):
+                end_pos += 1
+                bit += 1
+            width = end_pos - begin_pos
+            if width == 1:
+                chunks.append(f"{wire} [{start_bit}]")
+            else:
+                chunks.append(f"{wire} [{start_bit + width - 1}:{start_bit}]")
+            begin_pos = end_pos
+
+        if len(chunks) == 1:
+            return chunks[0]
+        return "{ " + " ".join(reversed(chunks)) + " }"
+
     def emit_connects(self):
         for name, (wire, value) in self.sigport_wires.items():
             if name not in self.driven_sigports:
@@ -513,10 +556,13 @@ def emit_submodules(self):
             submodule = self.netlist.modules[submodule_idx]
             if not self.empty_checker.is_empty(submodule_idx):
                 dotted_name = ".".join(submodule.name)
-                self.builder.cell(f"\\{dotted_name}", submodule.name[-1], ports={
-                    name: self.sigspec(value)
-                    for name, (value, _flow) in submodule.ports.items()
-                }, src=_src(submodule.cell_src_loc))
+                ports = {}
+                for name, (value, _flow) in submodule.ports.items():
+                    ports[name] = self.sigspec(value)
+                for name, (value, _dir) in submodule.io_ports.items():
+                    ports[name] = self.io_sigspec(value)
+                self.builder.cell(f"\\{dotted_name}", submodule.name[-1], ports=ports,
+                                  src=_src(submodule.cell_src_loc))
 
     def emit_assignment_list(self, cell_idx, cell):
         def emit_assignments(case, cond):
@@ -761,14 +807,19 @@ def emit_flip_flop(self, cell_idx, cell):
         self.builder.cell(cell_type, ports=ports, params=params, src=_src(cell.src_loc))
 
     def emit_io_buffer(self, cell_idx, cell):
-        self.builder.cell("$tribuf", ports={
-            "Y": self.sigspec(cell.pad),
-            "A": self.sigspec(cell.o),
-            "EN": self.sigspec(cell.oe),
-        }, params={
-            "WIDTH": len(cell.pad),
-        }, src=_src(cell.src_loc))
-        self.builder.connect(self.cell_wires[cell_idx], self.sigspec(cell.pad))
+        if cell.dir is not _nir.IODirection.Input:
+            if cell.dir is _nir.IODirection.Output and cell.oe == _nir.Net.from_const(1):
+                self.builder.connect(self.io_sigspec(cell.port), self.sigspec(cell.o))
+            else:
+                self.builder.cell("$tribuf", ports={
+                    "Y": self.io_sigspec(cell.port),
+                    "A": self.sigspec(cell.o),
+                    "EN": self.sigspec(cell.oe),
+                }, params={
+                    "WIDTH": len(cell.port),
+                }, src=_src(cell.src_loc))
+        if cell.dir is not _nir.IODirection.Output:
+            self.builder.connect(self.cell_wires[cell_idx], self.io_sigspec(cell.port))
 
     def emit_memory(self, cell_idx, cell):
         memory_info = self.memories[cell_idx]
@@ -950,8 +1001,8 @@ def emit_instance(self, cell_idx, cell):
             ports[name] = self.sigspec(nets)
         for name in cell.ports_o:
             ports[name] = self.instance_wires[cell_idx, name]
-        for name, nets in cell.ports_io.items():
-            ports[name] = self.sigspec(nets)
+        for name, (ionets, _dir) in cell.ports_io.items():
+            ports[name] = self.io_sigspec(ionets)
         self.builder.cell(f"\\{cell.type}", cell.name, ports=ports, params=cell.parameters,
                           attrs=cell.attributes, src=_src(cell.src_loc))
 

amaranth/build/plat.py

@@ -222,7 +222,7 @@ def get_tristate(self, pin, port, attrs, invert):
 
         m = Module()
         m.submodules += IOBufferInstance(
-            pad=port,
+            port=port,
             o=self._invert_if(invert, pin.o),
             oe=pin.oe,
         )
@@ -235,7 +235,7 @@ def get_input_output(self, pin, port, attrs, invert):
         m = Module()
         i = Signal.like(pin.i)
         m.submodules += IOBufferInstance(
-            pad=port,
+            port=port,
             i=i,
             o=self._invert_if(invert, pin.o),
             oe=pin.oe,

amaranth/build/res.py

@@ -14,6 +14,21 @@ class ResourceError(Exception):
     pass
 
 
+class SingleEndedPort:
+    def __init__(self, io):
+        self.io = io
+
+
+class DifferentialPort:
+    def __init__(self, p, n):
+        self.p = p
+        self.n = n
+
+
+class PortGroup:
+    pass
+
+
 class ResourceManager:
     def __init__(self, resources, connectors):
         self.resources  = OrderedDict()
@@ -113,21 +128,13 @@ def resolve(resource, dir, xdr, path, attrs):
                     attrs[attr_key] = attr_value
 
             if isinstance(resource.ios[0], Subsignal):
-                members = OrderedDict()
-                sig_members = OrderedDict()
+                res = PortGroup()
                 for sub in resource.ios:
                     member = resolve(sub, dir[sub.name], xdr[sub.name],
                                                path=path + (sub.name,),
                                                attrs={**attrs, **sub.attrs})
-                    members[sub.name] = member
-                    sig_members[sub.name] = wiring.Out(member.signature)
-                signature = wiring.Signature(sig_members)
-                # Provide members ourselves instead of having the constructor
-                # create ones for us.
-                intf = object.__new__(wiring.PureInterface)
-                intf.signature = signature
-                intf.__dict__.update(members)
-                return intf
+                    setattr(res, sub.name, member)
+                return res
 
             elif isinstance(resource.ios[0], (Pins, DiffPairs)):
                 phys = resource.ios[0]
@@ -136,17 +143,21 @@ def resolve(resource, dir, xdr, path, attrs):
                 # ignore it as well.
                 if isinstance(phys, Pins):
                     phys_names = phys.names
-                    port = wiring.Signature({"io": wiring.In(len(phys))}).create(path=path)
+                    io = IOPort(len(phys), name="__".join(path) + "__io")
+                    port = SingleEndedPort(io)
                 if isinstance(phys, DiffPairs):
                     phys_names = []
-                    sig_members = {}
                     if not self.should_skip_port_component(None, attrs, "p"):
+                        p = IOPort(len(phys), name="__".join(path) + "__p")
                         phys_names += phys.p.names
-                        sig_members["p"] = wiring.In(len(phys))
+                    else:
+                        p = None
                     if not self.should_skip_port_component(None, attrs, "n"):
+                        n = IOPort(len(phys), name="__".join(path) + "__n")
                         phys_names += phys.n.names
-                        sig_members["n"] = wiring.In(len(phys))
-                    port = wiring.Signature(sig_members).create(path=path)
+                    else:
+                        n = None
+                    port = DifferentialPort(p, n)
                 if dir == "-":
                     pin = None
                 else:

amaranth/hdl/__init__.py

@@ -2,9 +2,11 @@
 from ._ast import Value, ValueCastable, ValueLike
 from ._ast import Const, C, Mux, Cat, Array, Signal, ClockSignal, ResetSignal
 from ._ast import Format, Print, Assert, Assume, Cover
+from ._ast import IOValue, IOPort
 from ._dsl import SyntaxError, SyntaxWarning, Module
 from ._cd import DomainError, ClockDomain
-from ._ir import UnusedElaboratable, Elaboratable, DriverConflict, Fragment, Instance
+from ._ir import UnusedElaboratable, Elaboratable, DriverConflict, Fragment
+from ._ir import Instance, IOBufferInstance
 from ._mem import MemoryIdentity, MemoryInstance, Memory, ReadPort, WritePort, DummyPort
 from ._rec import Record
 from ._xfrm import DomainRenamer, ResetInserter, EnableInserter
@@ -16,12 +18,14 @@
     "Value", "ValueCastable", "ValueLike",
     "Const", "C", "Mux", "Cat", "Array", "Signal", "ClockSignal", "ResetSignal",
     "Format", "Print", "Assert", "Assume", "Cover",
+    "IOValue", "IOPort",
     # _dsl
     "SyntaxError", "SyntaxWarning", "Module",
     # _cd
     "DomainError", "ClockDomain",
     # _ir
-    "UnusedElaboratable", "Elaboratable", "DriverConflict", "Fragment", "Instance",
+    "UnusedElaboratable", "Elaboratable", "DriverConflict", "Fragment",
+    "Instance", "IOBufferInstance",
     # _mem
     "MemoryIdentity", "MemoryInstance", "Memory", "ReadPort", "WritePort", "DummyPort",
     # _rec