Merge branch 'amaranth-lang:main' into main

Author: slagernate

.github/workflows/main.yaml

@@ -60,6 +60,9 @@ jobs:
         uses: actions/checkout@v3
         with:
           fetch-depth: 0
+      - name: Fetch tags from upstream repository
+        run: |
+          git fetch --tags https://github.com/amaranth-lang/amaranth.git
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
@@ -71,24 +74,62 @@ jobs:
       - name: Build documentation
         run: |
           sphinx-build docs docs/_build
+      - name: Upload documentation archive
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: docs/_build
+  publish-docs:
+    needs: document
+    if: github.repository == 'amaranth-lang/amaranth'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Download documentation archive
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: docs/
       - name: Publish development documentation
         if: github.event_name == 'push' && github.event.ref == 'refs/heads/main'
         uses: JamesIves/github-pages-deploy-action@releases/v4
         with:
           repository-name: amaranth-lang/amaranth-lang.github.io
           ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
           branch: main
-          folder: docs/_build
+          folder: docs/
           target-folder: docs/amaranth/latest/
-      - name: Extract release version
-        if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
-        run: echo "VERSION=$(python setup.py --version)" >>$GITHUB_ENV
       - name: Publish release documentation
         if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
         uses: JamesIves/github-pages-deploy-action@releases/v4
         with:
           repository-name: amaranth-lang/amaranth-lang.github.io
           ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
           branch: main
-          folder: docs/_build
-          target-folder: docs/amaranth/v${{ env.VERSION }}/
+          folder: docs/
+          target-folder: docs/amaranth/${{ github.ref_name }}/
+  publish-docs-dev:
+    needs: document
+    if: github.repository != 'amaranth-lang/amaranth'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Download documentation archive
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: pages/docs/${{ github.ref_name }}/
+      - name: Disable Jekyll
+        run: |
+          touch pages/.nojekyll
+      - name: Publish documentation for a branch
+        uses: JamesIves/github-pages-deploy-action@releases/v4
+        with:
+          folder: pages/
+          clean: false

amaranth/build/plat.py

@@ -76,7 +76,10 @@ def _toolchain_env_var(self):
     # TODO(amaranth-0.5): remove
     @property
     def _all_toolchain_env_vars(self):
-        return (f"AMARANTH_ENV_{self.toolchain}", self._toolchain_env_var,)
+        return (
+            f"AMARANTH_ENV_{self.toolchain.replace('-', '_').replace('+', 'X')}",
+            self._toolchain_env_var,
+        )
 
     def build(self, elaboratable, name="top",
               build_dir="build", do_build=True,
@@ -333,7 +336,7 @@ def _extract_override(var, *, expected_type):
                 return re.sub(r'^\"\"$', "", var_env_value)
             elif var in kwargs:
                 kwarg = kwargs[var]
-                if issubclass(expected_type, str) and isinstance(var, Iterable):
+                if issubclass(expected_type, str) and not isinstance(kwarg, str) and isinstance(kwarg, Iterable):
                     kwarg = " ".join(kwarg)
                 if not isinstance(kwarg, expected_type) and not expected_type is None:
                     raise TypeError("Override '{}' must be a {}, not {!r}".format(var, expected_type.__name__, kwarg))

amaranth/build/run.py

@@ -176,7 +176,7 @@ def mkdirs(path):
                 # Show the output from the server while products are built.
                 buf = channel.recv(1024)
                 while buf:
-                    print(buf.decode("utf-8"), end="")
+                    print(buf.decode("utf-8", errors="replace"), end="")
                     buf = channel.recv(1024)
 
         return RemoteSSHBuildProducts(connect_to, root)

amaranth/hdl/ast.py

@@ -1,4 +1,5 @@
 from abc import ABCMeta, abstractmethod
+import inspect
 import warnings
 import functools
 from collections import OrderedDict
@@ -41,12 +42,16 @@ class ShapeCastable:
     a richer description of the shape than what is supported by the core Amaranth language, yet
     still be transparently used with it.
     """
-    def __new__(cls, *args, **kwargs):
-        self = super().__new__(cls)
-        if not hasattr(self, "as_shape"):
+    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")
-        return self
+        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")
 
 
 class Shape:
@@ -572,8 +577,6 @@ def _lhs_signals(self):
     def _rhs_signals(self):
         pass # :nocov:
 
-    __hash__ = None
-
 
 @final
 class Const(Value):
@@ -634,6 +637,13 @@ def __init__(self, value, shape=None, *, src_loc_at=0):
         elif isinstance(shape, int):
             shape = Shape(shape, signed=self.value < 0)
         else:
+            if isinstance(shape, range) and self.value == shape.stop:
+                warnings.warn(
+                    message="Value {!r} equals the non-inclusive end of the constant "
+                            "shape {!r}; this is likely an off-by-one error"
+                            .format(self.value, shape),
+                    category=SyntaxWarning,
+                    stacklevel=2)
             shape = Shape.cast(shape, src_loc_at=1 + src_loc_at)
         self.width  = shape.width
         self.signed = shape.signed
@@ -943,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
@@ -985,7 +1003,7 @@ class Signal(Value, DUID):
     decoder : function
     """
 
-    def __init__(self, shape=None, *, name=None, reset=0, reset_less=False,
+    def __init__(self, shape=None, *, name=None, reset=None, reset_less=False,
                  attrs=None, decoder=None, src_loc_at=0):
         super().__init__(src_loc_at=src_loc_at)
 
@@ -1001,21 +1019,50 @@ def __init__(self, shape=None, *, name=None, reset=0, reset_less=False,
         self.width  = shape.width
         self.signed = shape.signed
 
-        if isinstance(reset, Enum):
-            reset = reset.value
-        if not isinstance(reset, int):
-            raise TypeError("Reset value has to be an int or an integral Enum")
-
-        reset_width = bits_for(reset, self.signed)
-        if reset != 0 and reset_width > self.width:
-            warnings.warn("Reset value {!r} requires {} bits to represent, but the signal "
-                          "only has {} bits"
-                          .format(reset, reset_width, self.width),
-                          SyntaxWarning, stacklevel=2 + src_loc_at)
-
-        self.reset = reset
+        orig_reset = reset
+        if isinstance(orig_shape, ShapeCastable):
+            try:
+                reset = Const.cast(orig_shape.const(reset))
+            except Exception:
+                raise TypeError("Reset value must be a constant initializer of {!r}"
+                                .format(orig_shape))
+            if reset.shape() != Shape.cast(orig_shape):
+                raise ValueError("Constant returned by {!r}.const() must have the shape that "
+                                 "it casts to, {!r}, and not {!r}"
+                                 .format(orig_shape, Shape.cast(orig_shape),
+                                         reset.shape()))
+        else:
+            try:
+                reset = Const.cast(reset or 0)
+            except TypeError:
+                raise TypeError("Reset value must be a constant-castable expression, not {!r}"
+                                .format(orig_reset))
+        if orig_reset not in (None, 0, -1): # Avoid false positives for all-zeroes and all-ones
+            if reset.shape().signed and not self.signed:
+                warnings.warn(
+                    message="Reset value {!r} is signed, but the signal shape is {!r}"
+                            .format(orig_reset, shape),
+                    category=SyntaxWarning,
+                    stacklevel=2)
+            elif (reset.shape().width > self.width or
+                  reset.shape().width == self.width and
+                    self.signed and not reset.shape().signed):
+                warnings.warn(
+                    message="Reset value {!r} will be truncated to the signal shape {!r}"
+                            .format(orig_reset, shape),
+                    category=SyntaxWarning,
+                    stacklevel=2)
+        self.reset = reset.value
         self.reset_less = bool(reset_less)
 
+        if isinstance(orig_shape, range) and self.reset == orig_shape.stop:
+            warnings.warn(
+                message="Reset value {!r} equals the non-inclusive end of the signal "
+                        "shape {!r}; this is likely an off-by-one error"
+                        .format(self.reset, orig_shape),
+                category=SyntaxWarning,
+                stacklevel=2)
+
         self.attrs = OrderedDict(() if attrs is None else attrs)
 
         if decoder is None and isinstance(orig_shape, type) and issubclass(orig_shape, Enum):
@@ -1297,15 +1344,13 @@ class ValueCastable:
     from :class:`ValueCastable` is mutable, it is up to the user to ensure that it is not mutated
     in a way that changes its representation after the first call to :meth:`as_value`.
     """
-    def __new__(cls, *args, **kwargs):
-        self = super().__new__(cls)
-        if not hasattr(self, "as_value"):
+    def __init_subclass__(cls, **kwargs):
+        if not hasattr(cls, "as_value"):
             raise TypeError(f"Class '{cls.__name__}' deriving from `ValueCastable` must override "
                             "the `as_value` method")
-        if not hasattr(self.as_value, "_ValueCastable__memoized"):
+        if not hasattr(cls.as_value, "_ValueCastable__memoized"):
             raise TypeError(f"Class '{cls.__name__}' deriving from `ValueCastable` must decorate "
                             "the `as_value` method with the `ValueCastable.lowermethod` decorator")
-        return self
 
     @staticmethod
     def lowermethod(func):