Add annotations for memory maps, wishbone and CSR primitives.

amaranth_soc/csr/bus.py

@@ -1,13 +1,13 @@
 from collections import defaultdict
 from amaranth import *
-from amaranth.lib import enum, wiring
+from amaranth.lib import enum, wiring, meta
 from amaranth.lib.wiring import In, Out, flipped
 from amaranth.utils import ceil_log2
 
 from ..memory import MemoryMap
 
 
-__all__ = ["Element", "Signature", "Interface", "Decoder", "Multiplexer"]
+__all__ = ["Element", "Signature", "Annotation", "Interface", "Decoder", "Multiplexer"]
 
 
 class Element(wiring.PureInterface):
@@ -113,6 +113,32 @@ def create(self, *, path=None, src_loc_at=0):
  """
  return Element(self.width, self.access, path=path, src_loc_at=1 + src_loc_at)
 
+ def annotations(self, element, /):
+ """Get annotations of a compatible CSR element.
+
+ Parameters
+ ----------
+ element : :class:`Element`
+ A CSR element compatible with this signature.
+
+ Returns
+ -------
+ iterator of :class:`meta.Annotation`
+ Annotations attached to ``element``.
+
+ Raises
+ ------
+ :exc:`TypeError`
+ If ``element`` is not an :class:`Element` object.
+ :exc:`ValueError`
+ If ``element.signature`` is not equal to ``self``.
+ """
+ if not isinstance(element, Element):
+ raise TypeError(f"Element must be a csr.Element object, not {element!r}")
+ if element.signature != self:
+ raise ValueError(f"Element signature is not equal to this signature")
+ return (*super().annotations(element), Element.Annotation(element.signature))
+
  def __eq__(self, other):
  """Compare signatures.
 
@@ -125,6 +151,64 @@ def __eq__(self, other):
  def __repr__(self):
  return f"csr.Element.Signature({self.members!r})"
 
+ class Annotation(meta.Annotation):
+ schema = {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://amaranth-lang.org/schema/amaranth-soc/0.1/csr/element.json",
+ "type": "object",
+ "properties": {
+ "width": {
+ "type": "integer",
+ "minimum": 0,
+ },
+ "access": {
+ "enum": ["r", "w", "rw"],
+ },
+ },
+ "additionalProperties": False,
+ "required": [
+ "width",
+ "access",
+ ],
+ }
+
+ """Peripheral-side CSR signature annotation.
+
+ Parameters
+ ----------
+ origin : :class:`Element.Signature`
+ The signature described by this annotation instance.
+
+ Raises
+ ------
+ :exc:`TypeError`
+ If ``origin`` is not a :class:`Element.Signature`.
+ """
+ def __init__(self, origin):
+ if not isinstance(origin, Element.Signature):
+ raise TypeError(f"Origin must be a csr.Element.Signature object, not {origin!r}")
+ self._origin = origin
+
+ @property
+ def origin(self):
+ return self._origin
+
+ def as_json(self):
+ """Translate to JSON.
+
+ Returns
+ -------
+ :class:`dict`
+ A JSON representation of :attr:`~Element.Annotation.origin`, describing its width
+ and access mode.
+ """
+ instance = {
+ "width": self.origin.width,
+ "access": self.origin.access.value,
+ }
+ self.validate(instance)
+ return instance
+
  """Peripheral-side CSR interface.
 
  A low-level interface to a single atomically readable and writable register in a peripheral.
@@ -244,6 +328,35 @@ def create(self, *, path=None, src_loc_at=0):
  return Interface(addr_width=self.addr_width, data_width=self.data_width,
  path=path, src_loc_at=1 + src_loc_at)
 
+ def annotations(self, interface, /):
+ """Get annotations of a compatible CSR bus interface.
+
+ Parameters
+ ----------
+ interface : :class:`Interface`
+ A CSR bus interface compatible with this signature.
+
+ Returns
+ -------
+ iterator of :class:`meta.Annotation`
+ Annotations attached to ``interface``.
+
+ Raises
+ ------
+ :exc:`TypeError`
+ If ``interface`` is not an :class:`Interface` object.
+ :exc:`ValueError`
+ If ``interface.signature`` is not equal to ``self``.
+ """
+ if not isinstance(interface, Interface):
+ raise TypeError(f"Interface must be a csr.Interface object, not {interface!r}")
+ if interface.signature != self:
+ raise ValueError(f"Interface signature is not equal to this signature")
+ annotations = [*super().annotations(interface), Annotation(interface.signature)]
+ if interface._memory_map is not None:
+ annotations.append(interface._memory_map.annotation)
+ return annotations
+
  def __eq__(self, other):
  """Compare signatures.
 
@@ -257,6 +370,66 @@ def __repr__(self):
  return f"csr.Signature({self.members!r})"
 
 
+class Annotation(meta.Annotation):
+ schema = {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://amaranth-lang.org/schema/amaranth-soc/0.1/csr/bus.json",
+ "type": "object",
+ "properties": {
+ "addr_width": {
+ "type": "integer",
+ "minimum": 0,
+ },
+ "data_width": {
+ "type": "integer",
+ "minimum": 0,
+ },
+ },
+ "additionalProperties": False,
+ "required": [
+ "addr_width",
+ "data_width",
+ ],
+ }
+
+ """CPU-side CSR signature annotation.
+
+ Parameters
+ ----------
+ origin : :class:`Signature`
+ The signature described by this annotation instance.
+
+ Raises
+ ------
+ :exc:`TypeError`
+ If ``origin`` is not a :class:`Signature`.
+ """
+ def __init__(self, origin):
+ if not isinstance(origin, Signature):
+ raise TypeError(f"Origin must be a csr.Signature object, not {origin!r}")
+ self._origin = origin
+
+ @property
+ def origin(self):
+ return self._origin
+
+ def as_json(self):
+ """Translate to JSON.
+
+ Returns
+ -------
+ :class:`dict`
+ A JSON representation of :attr:`~Annotation.origin`, describing its address width
+ and data width.
+ """
+ instance = {
+ "addr_width": self.origin.addr_width,
+ "data_width": self.origin.data_width,
+ }
+ self.validate(instance)
+ return instance
+
+
 class Interface(wiring.PureInterface):
  """CPU-side CSR interface.