memory: restrict resources to wiring.Component objects.

Also, csr.Multiplexer now requires the signature of its memory map
resources to contain a csr.Element.Signature member, named "element"
and oriented as output.

Author: jfng

amaranth_soc/csr/bus.py

@@ -6,14 +6,20 @@
 from amaranth.lib.wiring import In, Out, flipped, connect
 from amaranth.utils import ceil_log2
 
-from . import Element, Multiplexer
+from . import Multiplexer
+from .reg import Register, Field, FieldAction
 from .. import event
 from ..memory import MemoryMap
 
 
 __all__ = ["EventMonitor"]
 
 
+class _EventMaskRegister(Register, access="rw"):
+    def __init__(self, width):
+        super().__init__({"mask": Field(FieldAction, width, access="rw")})
+
+
 class EventMonitor(wiring.Component):
     """Event monitor.
 
@@ -54,15 +60,15 @@ def __init__(self, event_map, *, trigger="level", data_width, alignment=0, name=
             raise ValueError(f"Alignment must be a non-negative integer, not {alignment!r}")
 
         self._monitor = event.Monitor(event_map, trigger=trigger)
-        self._enable  = Element(event_map.size, "rw")
-        self._pending = Element(event_map.size, "rw")
+        self._enable  = _EventMaskRegister(event_map.size)
+        self._pending = _EventMaskRegister(event_map.size)
 
-        elem_size  = ceil(event_map.size / data_width)
-        addr_width = 1 + max(ceil_log2(elem_size), alignment)
+        reg_size   = (event_map.size + data_width - 1) // data_width
+        addr_width = 1 + max(ceil_log2(reg_size), alignment)
         memory_map = MemoryMap(addr_width=addr_width, data_width=data_width, alignment=alignment)
+        memory_map.add_resource(self._enable,  size=reg_size, name="enable")
+        memory_map.add_resource(self._pending, size=reg_size, name="pending")
 
-        self._enable .add_to(memory_map, name="enable")
-        self._pending.add_to(memory_map, name="pending")
         self._mux = Multiplexer(memory_map)
 
         super().__init__({
@@ -81,12 +87,12 @@ def elaborate(self, platform):
         connect(m, flipped(self.src), self._monitor.src)
         connect(m, self.bus, self._mux.bus)
 
-        with m.If(self._enable.w_stb):
-            m.d.sync += self._monitor.enable.eq(self._enable.w_data)
-        m.d.comb += self._enable.r_data.eq(self._monitor.enable)
+        with m.If(self._enable.element.w_stb):
+            m.d.sync += self._monitor.enable.eq(self._enable.element.w_data)
+        m.d.comb += self._enable.element.r_data.eq(self._monitor.enable)
 
-        with m.If(self._pending.w_stb):
-            m.d.comb += self._monitor.clear.eq(self._pending.w_data)
-        m.d.comb += self._pending.r_data.eq(self._monitor.pending)
+        with m.If(self._pending.element.w_stb):
+            m.d.comb += self._monitor.clear.eq(self._pending.element.w_data)
+        m.d.comb += self._pending.element.r_data.eq(self._monitor.pending)
 
         return m

amaranth_soc/csr/event.py

@@ -872,20 +872,20 @@ def traverse_path(path, obj):
         register_map.freeze()
 
         for register, path in register_map.flatten():
-            elem_addr, assigned = traverse_path(path, register_addr)
-            if assigned != path and elem_addr is not None:
+            reg_addr, assigned = traverse_path(path, register_addr)
+            if assigned != path and reg_addr is not None:
                 raise TypeError(f"Register address assignment for the cluster {tuple(assigned)} "
-                                f"must be a dict or None, not {elem_addr!r}")
+                                f"must be a dict or None, not {reg_addr!r}")
 
-            elem_alignment, assigned = traverse_path(path, register_alignment)
-            if assigned != path and elem_alignment is not None:
+            reg_alignment, assigned = traverse_path(path, register_alignment)
+            if assigned != path and reg_alignment is not None:
                 raise TypeError(f"Register alignment assignment for the cluster {tuple(assigned)} "
-                                f"must be a dict or None, not {elem_alignment!r}")
+                                f"must be a dict or None, not {reg_alignment!r}")
 
-            elem_size = (register.element.width + data_width - 1) // data_width
-            elem_name = "__".join(path)
-            memory_map.add_resource(register.element, name=elem_name, size=elem_size,
-                                    addr=elem_addr, alignment=elem_alignment)
+            reg_size = (register.element.width + data_width - 1) // data_width
+            reg_name = "__".join(path)
+            memory_map.add_resource(register, name=reg_name, size=reg_size, addr=reg_addr,
+                                    alignment=reg_alignment)
 
         self._map = register_map
         self._mux = Multiplexer(memory_map)

amaranth_soc/csr/reg.py

@@ -1,5 +1,6 @@
 import bisect
 
+from amaranth.lib import wiring
 from amaranth.utils import bits_for
 
 
@@ -50,12 +51,12 @@ def items(self):
 class ResourceInfo:
     """Resource metadata.
 
-    A wrapper class for resource objects, with their assigned path and address range.
+    A description of a memory map resource with its assigned path and address range.
 
     Parameters
     ----------
-    resource : object
-        Arbitrary object representing a resource. See :meth:`MemoryMap.add_resource` for details.
+    resource : :class:`wiring.Component`
+        A resource located in the memory map. See :meth:`MemoryMap.add_resource` for details.
     path : iter(str)
         Path of the resource. It is composed of the names of each window sitting between
         the resource and the memory map from which this :class:`ResourceInfo` was obtained.
@@ -263,8 +264,8 @@ def add_resource(self, resource, *, name, size, addr=None, alignment=None):
 
         Arguments
         ---------
-        resource : object
-            Arbitrary object representing a resource.
+        resource : :class:`wiring.Component`
+            The resource to be added.
         name : str
             Name of the resource. It must not collide with the name of other resources or windows
             present in this memory map.
@@ -284,18 +285,25 @@ def add_resource(self, resource, *, name, size, addr=None, alignment=None):
 
         Exceptions
         ----------
-        Raises :exn:`ValueError` if one of the following occurs:
-
-        - this memory map is frozen;
-        - the requested address and size, after alignment, would overlap with any resources or
-        windows that have already been added, or would be out of bounds;
-        - the resource has already been added to this memory map;
-        - the name of the resource is already present in the namespace of this memory map;
+        :exc:`ValueError`
+            If the memory map is frozen.
+        :exc:`TypeError`
+            If the resource is not a :class:`wiring.Component`.
+        :exc:`ValueError`
+            If the requested address and size, after alignment, would overlap with any resources or
+            windows that have already been added, or would be out of bounds.
+        :exc:`ValueError`
+            If the resource has already been added to this memory map.
+        :exc:`ValueError`
+            If the name of the resource is already present in the namespace of this memory map.
         """
         if self._frozen:
             raise ValueError("Memory map has been frozen. Cannot add resource {!r}"
                              .format(resource))
 
+        if not isinstance(resource, wiring.Component):
+            raise TypeError(f"Resource must be a wiring.Component, not {resource!r}")
+
         if id(resource) in self._resources:
             _, _, addr_range = self._resources[id(resource)]
             raise ValueError("Resource {!r} is already added at address range {:#x}..{:#x}"