Implement RFC 15: Lifting shape-castable objects.

See amaranth-lang/rfcs#15 and #784.

Note that this RFC breaks the existing syntax for initializing a view
with a new signal. Instances of `View(layout)` *must* be changed to
`Signal(layout)`.

Author: whitequark

amaranth/hdl/ast.py

@@ -1,4 +1,5 @@
 from abc import ABCMeta, abstractmethod
+import inspect
 import warnings
 import functools
 from collections import OrderedDict
@@ -45,6 +46,9 @@ def __init_subclass__(cls, **kwargs):
         if not hasattr(cls, "as_shape"):
             raise TypeError(f"Class '{cls.__name__}' deriving from `ShapeCastable` must override "
                             f"the `as_shape` method")
+        if not (hasattr(cls, "__call__") and inspect.isfunction(cls.__call__)):
+            raise TypeError(f"Class '{cls.__name__}' deriving from `ShapeCastable` must override "
+                            f"the `__call__` method")
         if not hasattr(cls, "const"):
             raise TypeError(f"Class '{cls.__name__}' deriving from `ShapeCastable` must override "
                             f"the `const` method")
@@ -949,8 +953,16 @@ def __repr__(self):
         return "(repl {!r} {})".format(self.value, self.count)
 
 
+class _SignalMeta(ABCMeta):
+    def __call__(cls, shape=None, src_loc_at=0, **kwargs):
+        signal = super().__call__(shape, **kwargs, src_loc_at=src_loc_at + 1)
+        if isinstance(shape, ShapeCastable):
+            return shape(signal)
+        return signal
+
+
 # @final
-class Signal(Value, DUID):
+class Signal(Value, DUID, metaclass=_SignalMeta):
     """A varying integer value.
 
     Parameters

amaranth/lib/data.py

@@ -390,6 +390,13 @@ def size(self):
         """
         return max((field.width for field in self._fields.values()), default=0)
 
+    def const(self, init):
+        if init is not None and len(init) > 1:
+            raise ValueError("Initializer for at most one field can be provided for "
+                             "a union layout (specified: {})"
+                             .format(", ".join(init.keys())))
+        return super().const(init)
+
     def __repr__(self):
         return f"UnionLayout({self.members!r})"
 
@@ -609,33 +616,21 @@ class View(ValueCastable):
     classes provided in this module are subclasses of :class:`View` that also provide a concise way
     to define a layout.
     """
-    def __init__(self, layout, target=None, *, name=None, reset=None, reset_less=None,
-            attrs=None, decoder=None, src_loc_at=0):
+    def __init__(self, layout, target):
         try:
             cast_layout = Layout.cast(layout)
         except TypeError as e:
             raise TypeError("View layout must be a layout, not {!r}"
                             .format(layout)) from e
-        if target is not None:
-            if (name is not None or reset is not None or reset_less is not None or
-                    attrs is not None or decoder is not None):
-                raise ValueError("View target cannot be provided at the same time as any of "
-                                 "the Signal constructor arguments (name, reset, reset_less, "
-                                 "attrs, decoder)")
-            try:
-                cast_target = Value.cast(target)
-            except TypeError as e:
-                raise TypeError("View target must be a value-castable object, not {!r}"
-                                .format(target)) from e
-            if len(cast_target) != cast_layout.size:
-                raise ValueError("View target is {} bit(s) wide, which is not compatible with "
-                                 "the {} bit(s) wide view layout"
-                                 .format(len(cast_target), cast_layout.size))
-        else:
-            if reset_less is None:
-                reset_less = False
-            cast_target = Signal(layout, name=name, reset=reset, reset_less=reset_less,
-                attrs=attrs, decoder=decoder, src_loc_at=src_loc_at + 1)
+        try:
+            cast_target = Value.cast(target)
+        except TypeError as e:
+            raise TypeError("View target must be a value-castable object, not {!r}"
+                            .format(target)) from e
+        if len(cast_target) != cast_layout.size:
+            raise ValueError("View target is {} bit(s) wide, which is not compatible with "
+                             "the {} bit(s) wide view layout"
+                             .format(len(cast_target), cast_layout.size))
         self.__orig_layout = layout
         self.__layout = cast_layout
         self.__target = cast_target
@@ -752,8 +747,8 @@ def __new__(metacls, name, bases, namespace):
         elif all(not hasattr(base, "_AggregateMeta__layout") for base in bases):
             # This is a leaf class with its own layout. It is shape-castable and can
             # be instantiated. It can also be subclassed, and used to share layout and behavior.
-            layout = dict()
-            reset  = dict()
+            layout  = dict()
+            default = dict()
             for name in {**namespace["__annotations__"]}:
                 try:
                     Shape.cast(namespace["__annotations__"][name])
@@ -762,15 +757,15 @@ def __new__(metacls, name, bases, namespace):
                     continue
                 layout[name] = namespace["__annotations__"].pop(name)
                 if name in namespace:
-                    reset[name] = namespace.pop(name)
+                    default[name] = namespace.pop(name)
             cls = type.__new__(metacls, name, bases, namespace)
             if cls.__layout_cls is UnionLayout:
-                if len(reset) > 1:
+                if len(default) > 1:
                     raise ValueError("Reset value for at most one field can be provided for "
                                      "a union class (specified: {})"
-                                     .format(", ".join(reset.keys())))
-            cls.__layout = cls.__layout_cls(layout)
-            cls.__reset  = reset
+                                     .format(", ".join(default.keys())))
+            cls.__layout  = cls.__layout_cls(layout)
+            cls.__default = default
             return cls
         else:
             # This is a class that has a base class with a layout and annotations. Such a class
@@ -785,28 +780,24 @@ def as_shape(cls):
                             .format(cls.__module__, cls.__qualname__))
         return cls.__layout
 
-    def const(cls, init):
-        return cls.as_shape().const(init)
-
+    def __call__(cls, target):
+        # This method exists to pass the override check done by ShapeCastable.
+        return super().__call__(cls, target)
 
-class _Aggregate(View, metaclass=_AggregateMeta):
-    def __init__(self, target=None, *, name=None, reset=None, reset_less=None,
-            attrs=None, decoder=None, src_loc_at=0):
-        if self.__class__._AggregateMeta__layout_cls is UnionLayout:
-            if reset is not None and len(reset) > 1:
-                raise ValueError("Reset value for at most one field can be provided for "
+    def const(cls, init):
+        if cls.__layout_cls is UnionLayout:
+            if init is not None and len(init) > 1:
+                raise ValueError("Initializer for at most one field can be provided for "
                                  "a union class (specified: {})"
-                                 .format(", ".join(reset.keys())))
-        if target is None and hasattr(self.__class__, "_AggregateMeta__reset"):
-            if reset is None:
-                reset = self.__class__._AggregateMeta__reset
-            elif self.__class__._AggregateMeta__layout_cls is not UnionLayout:
-                reset = {**self.__class__._AggregateMeta__reset, **reset}
-        super().__init__(self.__class__, target, name=name, reset=reset, reset_less=reset_less,
-            attrs=attrs, decoder=decoder, src_loc_at=src_loc_at + 1)
+                                 .format(", ".join(init.keys())))
+            return cls.as_shape().const(init or cls.__default)
+        else:
+            fields = cls.__default.copy()
+            fields.update(init or {})
+            return cls.as_shape().const(fields)
 
 
-class Struct(_Aggregate):
+class Struct(View, metaclass=_AggregateMeta):
     """Structures defined with annotations.
 
     The :class:`Struct` base class is a subclass of :class:`View` that provides a concise way
@@ -842,14 +833,14 @@ def is_subnormal(self):
 
         >>> IEEE754Single.as_shape()
         StructLayout({'fraction': 23, 'exponent': 8, 'sign': 1})
-        >>> Signal(IEEE754Single).width
+        >>> Signal(IEEE754Single).as_value().width
         32
 
     Instances of this class can be used where :ref:`values <lang-values>` are expected:
 
     .. doctest::
 
-        >>> flt = IEEE754Single()
+        >>> flt = Signal(IEEE754Single)
         >>> Signal(32).eq(flt)
         (eq (sig $signal) (sig flt))
 
@@ -866,11 +857,11 @@ def is_subnormal(self):
 
     .. doctest::
 
-        >>> hex(IEEE754Single().as_value().reset)
+        >>> hex(Signal(IEEE754Single).as_value().reset)
         '0x3f800000'
-        >>> hex(IEEE754Single(reset={'sign': 1}).as_value().reset)
+        >>> hex(Signal(IEEE754Single, reset={'sign': 1}).as_value().reset)
         '0xbf800000'
-        >>> hex(IEEE754Single(reset={'exponent': 0}).as_value().reset)
+        >>> hex(Signal(IEEE754Single, reset={'exponent': 0}).as_value().reset)
         '0x0'
 
     Classes inheriting from :class:`Struct` can be used as base classes. The only restrictions
@@ -903,15 +894,15 @@ class HeaderWithParam(HasChecksum):
         Traceback (most recent call last):
           ...
         TypeError: Aggregate class 'HasChecksum' does not have a defined shape
-        >>> bare = BareHeader(); bare.checksum()
+        >>> bare = Signal(BareHeader); bare.checksum()
         (+ (+ (+ (const 1'd0) (slice (sig bare) 0:8)) (slice (sig bare) 8:16)) (slice (sig bare) 16:24))
-        >>> param = HeaderWithParam(); param.checksum()
+        >>> param = Signal(HeaderWithParam); param.checksum()
         (+ (+ (+ (+ (const 1'd0) (slice (sig param) 0:8)) (slice (sig param) 8:16)) (slice (sig param) 16:24)) (slice (sig param) 24:32))
     """
     _AggregateMeta__layout_cls = StructLayout
 
 
-class Union(_Aggregate):
+class Union(View, metaclass=_AggregateMeta):
     """Unions defined with annotations.
 
     The :class:`Union` base class is a subclass of :class:`View` that provides a concise way
@@ -931,9 +922,9 @@ class VarInt(Union):
 
     .. doctest::
 
-        >>> VarInt().as_value().reset
+        >>> Signal(VarInt).as_value().reset
         256
-        >>> VarInt(reset={'int8': 10}).as_value().reset
+        >>> Signal(VarInt, reset={'int8': 10}).as_value().reset
         10
     """
     _AggregateMeta__layout_cls = UnionLayout

docs/stdlib/data.rst

@@ -56,7 +56,7 @@ While this implementation works, it is repetitive, error-prone, hard to read, an
         "blue":  5
     })
 
-    i_color = data.View(rgb565_layout)
+    i_color = Signal(rgb565_layout)
     o_gray  = Signal(8)
 
     m.d.comb += o_gray.eq((i_color.red + i_color.green + i_color.blue) << 1)
@@ -82,7 +82,7 @@ For example, consider a module that processes RGB pixels in groups of up to four
         "valid":  4
     })
 
-    i_stream = data.View(input_layout)
+    i_stream = Signal(input_layout)
     r_accum  = Signal(32)
 
     m.d.sync += r_accum.eq(
@@ -120,7 +120,7 @@ In case the data has related operations or transformations, :class:`View` can be
 
 .. testcode::
 
-    class RGBPixelLayout(data.StructLayout):
+    class RGBLayout(data.StructLayout):
         def __init__(self, r_bits, g_bits, b_bits):
             super().__init__({
                 "red":   unsigned(r_bits),
@@ -129,20 +129,20 @@ In case the data has related operations or transformations, :class:`View` can be
             })
 
         def __call__(self, value):
-            return RGBPixelView(self, value)
+            return RGBView(self, value)
 
-    class RGBPixelView(data.View):
+    class RGBView(data.View):
         def brightness(self):
             return (self.red + self.green + self.blue)[-8:]
 
-Here, the ``RGBLayout`` class itself is :ref:`shape-castable <lang-shapecasting>` and can be used anywhere a shape is accepted:
+Here, the ``RGBLayout`` class itself is :ref:`shape-castable <lang-shapecasting>` and can be used anywhere a shape is accepted. When a :class:`Signal` is constructed with this layout, the returned value is wrapped in an ``RGBView``:
 
 .. doctest::
 
-   >>> pixel = Signal(RGBPixelLayout(5, 6, 5))
-   >>> len(pixel)
+   >>> pixel = Signal(RGBLayout(5, 6, 5))
+   >>> len(pixel.as_value())
    16
-   >>> RGBPixelView(RGBPixelLayout(5, 6, 5), pixel).red
+   >>> pixel.red
    (slice (sig pixel) 0:5)
 
 In case the data format is static, :class:`Struct` (or :class:`Union`) can be subclassed instead of :class:`View`, to reduce the amount of boilerplate needed:
@@ -189,7 +189,7 @@ One module could submit a command with:
 
 .. testcode::
 
-    cmd = Command()
+    cmd = Signal(Command)
 
     m.d.comb += [
         cmd.valid.eq(1),

tests/test_hdl_ast.py

@@ -145,8 +145,11 @@ def __init__(self, dest):
     def as_shape(self):
         return self.dest
 
-    def const(self, obj):
-        return Const(obj, self.dest)
+    def __call__(self, value):
+        return value
+
+    def const(self, init):
+        return Const(init, self.dest)
 
 
 class ShapeCastableTestCase(FHDLTestCase):
@@ -1004,6 +1007,9 @@ class CastableFromHex(ShapeCastable):
             def as_shape(self):
                 return unsigned(8)
 
+            def __call__(self, value):
+                return value
+
             def const(self, init):
                 return int(init, 16)