Implement RFC 45: Move hdl.Memory to lib.Memory.

Author: wanda-phi

amaranth/hdl/__init__.py

@@ -4,7 +4,7 @@
 from ._dsl import SyntaxError, SyntaxWarning, Module
 from ._cd import DomainError, ClockDomain
 from ._ir import UnusedElaboratable, Elaboratable, DriverConflict, Fragment, Instance
-from ._mem import Memory, ReadPort, WritePort, DummyPort
+from ._mem import MemoryIdentity, MemoryInstance, Memory, ReadPort, WritePort, DummyPort
 from ._rec import Record
 from ._xfrm import DomainRenamer, ResetInserter, EnableInserter
 
@@ -21,7 +21,7 @@
     # _ir
     "UnusedElaboratable", "Elaboratable", "DriverConflict", "Fragment", "Instance",
     # _mem
-    "Memory", "ReadPort", "WritePort", "DummyPort",
+    "MemoryIdentity", "MemoryInstance", "Memory", "ReadPort", "WritePort", "DummyPort",
     # _rec
     "Record",
     # _xfrm

amaranth/hdl/_ir.py

@@ -1109,7 +1109,7 @@ def emit_read_port(self, module_idx: int, fragment: '_mem.MemoryInstance',
                 en=en,
                 clk=clk,
                 clk_edge=cd.clk_edge,
-                transparent_for=tuple(write_ports[idx] for idx in port._transparency),
+                transparent_for=tuple(write_ports[idx] for idx in port._transparent_for),
                 src_loc=port._data.src_loc,
             )
         data = self.netlist.add_value_cell(len(port._data), cell)

amaranth/hdl/_mem.py

@@ -33,18 +33,19 @@ def __init__(self, identity, addr, data):
 
 class MemoryInstance(Fragment):
     class _ReadPort:
-        def __init__(self, *, domain, addr, data, en, transparency):
+        def __init__(self, *, domain, addr, data, en, transparent_for):
             assert isinstance(domain, str)
             self._domain = domain
             self._addr = Value.cast(addr)
             self._data = Value.cast(data)
             self._en = Value.cast(en)
-            self._transparency = tuple(transparency)
+            self._transparent_for = tuple(transparent_for)
             assert len(self._en) == 1
             if domain == "comb":
                 assert isinstance(self._en, Const)
                 assert self._en.width == 1
                 assert self._en.value == 1
+                assert not self._transparent_for
 
     class _WritePort:
         def __init__(self, *, domain, addr, data, en):
@@ -70,23 +71,25 @@ def __init__(self, *, identity, width, depth, init=None, attrs=None, src_loc=Non
         self._identity = identity
         self._width = operator.index(width)
         self._depth = operator.index(depth)
-        self._init = tuple(init) if init is not None else ()
+        mask = (1 << self._width) - 1
+        self._init = tuple(item & mask for item in init) if init is not None else ()
         assert len(self._init) <= self._depth
         self._init += (0,) * (self._depth - len(self._init))
         for x in self._init:
             assert isinstance(x, int)
         self._attrs = attrs or {}
         self._src_loc = src_loc
-        self._read_ports = []
-        self._write_ports = []
+        self._read_ports: "list[MemoryInstance._ReadPort]" = []
+        self._write_ports: "list[MemoryInstance._WritePort]" = []
 
-    def read_port(self, *, domain, addr, data, en, transparency):
-        port = self._ReadPort(domain=domain, addr=addr, data=data, en=en, transparency=transparency)
+    def read_port(self, *, domain, addr, data, en, transparent_for):
+        port = self._ReadPort(domain=domain, addr=addr, data=data, en=en, transparent_for=transparent_for)
         assert len(port._data) == self._width
         assert len(port._addr) == ceil_log2(self._depth)
-        for x in port._transparency:
-            assert isinstance(x, int)
-            assert x in range(len(self._write_ports))
+        for idx in port._transparent_for:
+            assert isinstance(idx, int)
+            assert idx in range(len(self._write_ports))
+            assert self._write_ports[idx]._domain == port._domain
         for signal in port._data._rhs_signals():
             self.add_driver(signal, port._domain)
         self._read_ports.append(port)
@@ -209,12 +212,12 @@ def elaborate(self, platform):
         for port in self._read_ports:
             port._MustUse__used = True
             if port.domain == "comb":
-                f.read_port(domain="comb", addr=port.addr, data=port.data, en=Const(1), transparency=())
+                f.read_port(domain="comb", addr=port.addr, data=port.data, en=Const(1), transparent_for=())
             else:
-                transparency = []
+                transparent_for = []
                 if port.transparent:
-                    transparency = write_ports.get(port.domain, [])
-                f.read_port(domain=port.domain, addr=port.addr, data=port.data, en=port.en, transparency=transparency)
+                    transparent_for = write_ports.get(port.domain, [])
+                f.read_port(domain=port.domain, addr=port.addr, data=port.data, en=port.en, transparent_for=transparent_for)
         return f
 
 

amaranth/hdl/_xfrm.py

@@ -263,7 +263,7 @@ def on_fragment(self, fragment):
                     addr=port._addr,
                     data=port._data,
                     en=port._en,
-                    transparency=port._transparency,
+                    transparent_for=port._transparent_for,
                 )
                 for port in fragment._read_ports
             ]

amaranth/lib/fifo.py

@@ -7,6 +7,7 @@
 from ..utils import ceil_log2
 from .coding import GrayEncoder, GrayDecoder
 from .cdc import FFSynchronizer, AsyncFFSynchronizer
+from .memory import Memory
 
 
 __all__ = ["FIFOInterface", "SyncFIFO", "SyncFIFOBuffered", "AsyncFIFO", "AsyncFIFOBuffered"]
@@ -130,7 +131,7 @@ def elaborate(self, platform):
         do_read  = self.r_rdy & self.r_en
         do_write = self.w_rdy & self.w_en
 
-        storage = m.submodules.storage = Memory(width=self.width, depth=self.depth)
+        storage = m.submodules.storage = Memory(shape=self.width, depth=self.depth, init=[])
         w_port  = storage.write_port()
         r_port  = storage.read_port(domain="comb")
         produce = Signal(range(self.depth))
@@ -257,9 +258,9 @@ def elaborate(self, platform):
 
         do_inner_read  = inner_r_rdy & (~self.r_rdy | self.r_en)
 
-        storage = m.submodules.storage = Memory(width=self.width, depth=inner_depth)
+        storage = m.submodules.storage = Memory(shape=self.width, depth=inner_depth, init=[])
         w_port  = storage.write_port()
-        r_port  = storage.read_port(domain="sync", transparent=False)
+        r_port  = storage.read_port(domain="sync")
         produce = Signal(range(inner_depth))
         consume = Signal(range(inner_depth))
 
@@ -438,9 +439,9 @@ def elaborate(self, platform):
         m.d[self._w_domain] += self.w_level.eq(produce_w_bin - consume_w_bin)
         m.d.comb += self.r_level.eq(produce_r_bin - consume_r_bin)
 
-        storage = m.submodules.storage = Memory(width=self.width, depth=self.depth)
+        storage = m.submodules.storage = Memory(shape=self.width, depth=self.depth, init=[])
         w_port  = storage.write_port(domain=self._w_domain)
-        r_port  = storage.read_port (domain=self._r_domain, transparent=False)
+        r_port  = storage.read_port (domain=self._r_domain)
         m.d.comb += [
             w_port.addr.eq(produce_w_bin[:-1]),
             w_port.data.eq(self.w_data),