wip

Author: whitequark

amaranth/lib/meta.py

@@ -5,33 +5,45 @@
 __all__ = ["InvalidSchema", "InvalidAnnotation", "Annotation"]
 
 
-def _create_catalog():
-    return jschon.create_catalog('2020-12')
-
-
 class InvalidSchema(Exception):
-    """Exception raised when an annotation with a non-conformant schema is defined."""
+    """Exception raised when a subclass of :class:`Annotation` is defined with a non-conformant
+    :data:`~Annotation.schema`."""
 
 
 class InvalidAnnotation(Exception):
-    """Exception raised when an annotation."""
+    """Exception raised by :meth:`Annotation.validate` when the JSON representation of
+    an annotation does not conform to its schema."""
 
 
 class Annotation(metaclass=ABCMeta):
-    """Signature annotation.
+    """Interface annotation.
+
+    A container for metadata that can be retrieved from an interface object using
+    the :meth:`Signature.annotations <.wiring.Signature.annotations>` method.
 
-    A container for metadata that can be retrieved from a :class:`~amaranth.lib.wiring.Signature`
-    object. Annotation instances can be exported as JSON objects, whose structure is defined using
+    Annotation instances can be exported as JSON objects, whose structure is defined using
     the `JSON Schema`_ language.
     """
 
     #: :class:`dict`: Schema of this annotation, expressed in the `JSON Schema`_ language.
     #:
-    #: Subclasses of :class:`Annotation` must implement this class attribute. If the value of
-    #: the attribute is not a valid Amaranth annotation JSON Schema, :exc:`InvalidSchema` is raised.
+    #: Subclasses of :class:`Annotation` must implement this class attribute.
     schema = {}
 
+    @classmethod
+    def __schema(cls):
+        catalog = jschon.create_catalog('2020-12')
+        return jschon.JSONSchema(cls.schema, catalog=catalog)
+
     def __init_subclass__(cls, **kwargs):
+        """
+        Defining a subclass of :class:`Annotation` causes its :data:`schema` to be validated.
+
+        Raises
+        ------
+        :exc:`InvalidSchema`
+            If :data:`schema` doesn't conform to the `2020-12` draft of `JSON Schema`_.
+        """
         super().__init_subclass__(**kwargs)
 
         if not isinstance(cls.schema, dict):
@@ -41,8 +53,8 @@ def __init_subclass__(cls, **kwargs):
         if "$id" not in cls.schema:
             raise ValueError(f"'$id' keyword is missing from Annotation schema: {cls.schema}")
 
-        schema_validity = jschon.JSONSchema(cls.schema, catalog=_create_catalog()).validate()
-        # TODO
+        schema_validity = cls.__schema().validate()
+        assert schema_validity.valid # TODO
 
     @property
     @abstractmethod
@@ -83,10 +95,10 @@ def validate(cls, instance):
         Raises
         ------
         :exc:`InvalidAnnotation`
-            If :py:`instance` doesn't comply with :attr:`Annotation.schema`.
+            If :py:`instance` doesn't conform to :attr:`Annotation.schema`.
         """
-        validity = JSONSchema(cls.schema, catalog=_create_catalog()).evaluate(instance)
-        # TODO
+        validity = cls.__schema().evaluate(jschon.JSON(instance))
+        assert validity.valid # TODO
 
     def __repr__(self):
         return f"<{type(self).__module__}.{type(self).__qualname__} for {self.origin!r}>"

amaranth/lib/wiring.py

@@ -723,18 +723,6 @@ def members(self):
         """
         return self.__members
 
-    def annotations(self, obj, /):
-        """Get annotations of an interface object.
-
-        Subclasses of :class:`Signature` may override this method to return annotations attached
-        to an interface object compatible with this signature.
-
-        Returns
-        -------
-        iterable of :class:`Annotation`
-        """
-        return ()
-
     def __eq__(self, other):
         """Compare this signature with another.
 
@@ -997,6 +985,21 @@ def my_property(self):
         """
         return PureInterface(self, path=path, src_loc_at=1 + src_loc_at)
 
+    def annotations(self, obj, /):
+        """Annotate an interface object.
+
+        Subclasses of :class:`Signature` may override this method to provide annotations for
+        a corresponding interface object. The default implementation provides none.
+
+        See :mod:`amaranth.lib.meta` for details.
+
+        Returns
+        -------
+        iterable of :class:`~.meta.Annotation`
+            :py:`tuple()`
+        """
+        return tuple()
+
     def __repr__(self):
         if type(self) is Signature:
             return f"Signature({dict(self.members.items())})"
@@ -1257,7 +1260,7 @@ def signature(self):
 
         Returns
         -------
-        Signature
+        :class:`Signature`
             :py:`unflipped.signature.flip()`
         """
         return self.__unflipped.signature.flip()
@@ -1267,7 +1270,7 @@ def __eq__(self, other):
 
         Returns
         -------
-        bool
+        :class:`bool`
             :py:`True` if :py:`other` is an instance :py:`FlippedInterface(other_unflipped)` where
             :py:`unflipped == other_unflipped`, :py:`False` otherwise.
         """

docs/stdlib.rst

@@ -17,8 +17,8 @@ The Amaranth standard library is separate from the Amaranth language: everything
    stdlib/enum
    stdlib/data
    stdlib/wiring
-   stdlib/memory
    stdlib/meta
+   stdlib/memory
    stdlib/cdc
    stdlib/coding
    stdlib/fifo

docs/stdlib/meta.rst

@@ -1,5 +1,5 @@
-Metadata
-########
+Interface metadata
+##################
 
 .. py:module:: amaranth.lib.meta
 
@@ -10,7 +10,7 @@ The :mod:`amaranth.lib.meta` module provides a way to annotate objects in an Ama
 .. testsetup::
 
     from amaranth import *
-    from amaranth.lib import wiring
+    from amaranth.lib import wiring, meta
     from amaranth.lib.wiring import In, Out
 
 
@@ -92,40 +92,145 @@ All metadata in Amaranth must adhere to a schema in the `JSON Schema`_ language,
 
     >>> wiring.ComponentMetadata.validate(adder.metadata.as_json())
 
+The built-in component metadata can be extended to provide arbitrary information about an interface through user-defined annotations. For example, a memory bus interface could provide the layout of any memory-mapped peripherals accessible through that bus.
+
 
 Defining annotations
 --------------------
 
+Consider a simple control and status register (CSR) bus that provides the memory layout of the accessible registers via an annotation:
+
+.. testcode::
+
+    class CSRLayoutAnnotation(meta.Annotation):
+        schema = {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": "https://amaranth-lang.org/schema/example/0/csr-layout.json",
+            "type": "object",
+            "properties": {
+                "registers": {
+                    "type": "object",
+                    "patternProperties": {
+                        "^.+$": {
+                            "type": "integer",
+                            "minimum": 0,
+                        },
+                    },
+                },
+            },
+            "requiredProperties": [
+                "registers",
+            ],
+        }
+
+        def __init__(self, origin):
+            self._origin = origin
+
+        @property
+        def origin(self):
+            return self._origin
+
+        def as_json(self):
+            print(self.origin)
+            print(self.origin.registers)
+            instance = {
+                "registers": self.origin.registers,
+            }
+            # Validating the value returned by `as_json()` ensures its conformance.
+            self.validate(instance)
+            return instance
+
+
+    class CSRSignature(wiring.Signature):
+        def __init__(self):
+            super().__init__({
+                "addr":     Out(16),
+                "w_en":     Out(1),
+                "w_data":   Out(32),
+                "r_en":     Out(1),
+                "r_data":   In(32),
+            })
+
+        def annotations(self, obj, /):
+            # Unfortunately `super()` cannot be used in `wiring.Signature` subclasses;
+            # instead, use a direct call to a superclass method. In this case that is
+            # `wiring.Signature` itself, but in a more complex class hierarchy it could
+            # be different.
+            return wiring.Signature.annotations(self, obj) + (CSRLayoutAnnotation(obj),)
+
+A component that embeds a few CSR registers would define their addresses:
+
+.. testcode::
+
+    class MyPeripheral(wiring.Component):
+        csr_bus: In(CSRSignature())
+
+        def __init__(self):
+            super().__init__()
+            self.csr_bus.registers = {
+                "control": 0x0000,
+                "status":  0x0004,
+                "data":    0x0008,
+            }
+
+.. doctest::
+
+    >>> peripheral = MyPeripheral()
+    >>> peripheral.metadata.as_json()
+    {
+        'interface': {
+            'members': { ... },
+            'annotations': {
+                'https://amaranth-lang.org/schema/example/0/csr-layout.json': {
+                    'registers': {
+                        'control': 0,
+                        'status':  4,
+                        'data':    8
+                    }
+                }
+            }
+        }
+    }
+
+
 .. todo:: Write this.
 
 
-Publishing schemas
-------------------
+Identifying schemas
+-------------------
 
-.. todo:: Write this
+An :class:`Annotation` schema must have a ``"$id"`` property, whose value is a URL that serves as its globally unique identifier. The suggested format of this URL is:
 
-An ``Annotation`` schema must have a ``"$id"`` property, which holds an URL that serves as its
-unique identifier. The suggested format of this URL is:
+.. code::
 
     <protocol>://<domain>/schema/<package>/<version>/<path>.json
 
 where:
+
     * ``<domain>`` is a domain name registered to the person or entity defining the annotation;
-    * ``<package>`` is the name of the Python package providing the ``Annotation`` subclass;
-    * ``<version>`` is the version of the aforementioned package;
+    * ``<package>`` is the name of the Python package providing the :class:`Annotation` subclass;
+    * ``<version>`` is the version of that package;
     * ``<path>`` is a non-empty string specific to the annotation.
 
+.. note::
+
+    Annotations used in the Amaranth project packages are published under https://amaranth-lang.org/schema/ according to this URL format, and are covered by the usual compatibility commitment.
+
+    Other projects that define additional Amaranth annotations are encouraged, but not required, to make their schemas publicly accessible; the only requirement is for the URL to be globally unique.
+
 
 Reference
 ---------
 
-.. todo::
+.. autoexception:: InvalidSchema
 
-    Write this.
+.. autoexception:: InvalidAnnotation
 
 .. autoclass:: Annotation
     :no-members:
     :members: validate, origin, as_json
 
+    .. automethod:: __init_subclass__()
+
     .. autoattribute:: schema
         :annotation: = { "$id": "...", ... }