hdl.ast: deprecate Sample, Past, Rose, Fell, Stable.

See #526.

amaranth/_utils.py

@@ -72,7 +72,7 @@ def _ignore_deprecated(f=None):
         def decorator_like(*args, **kwargs):
             with warnings.catch_warnings():
                 warnings.filterwarnings(action="ignore", category=DeprecationWarning)
-                f(*args, **kwargs)
+                return f(*args, **kwargs)
         return decorator_like
 
 

amaranth/hdl/ast.py

@@ -8,6 +8,7 @@ from itertools import chain
 
 from .. import tracer
 from .._utils import *
+from .._utils import _ignore_deprecated
 from .._unused import *
 
 
@@ -1333,6 +1334,7 @@ class ValueCastable:
         return wrapper_memoized
 
 
+# TODO(amaranth-0.5): remove
 @final
 class Sample(Value):
     """Value from the past.
@@ -1341,6 +1343,7 @@ class Sample(Value):
     of the ``domain`` clock back. If that moment is before the beginning of time, it is equal
     to the value of the expression calculated as if each signal had its reset value.
     """
+    @deprecated("instead of using `Sample`, create a register explicitly")
     def __init__(self, expr, clocks, domain, *, src_loc_at=0):
         super().__init__(src_loc_at=1 + src_loc_at)
         self.value  = Value.cast(expr)
@@ -1367,19 +1370,31 @@ class Sample(Value):
             self.value, "<default>" if self.domain is None else self.domain, self.clocks)
 
 
+# TODO(amaranth-0.5): remove
+@deprecated("instead of using `Past`, create a register explicitly")
 def Past(expr, clocks=1, domain=None):
+    with _ignore_deprecated():
         return Sample(expr, clocks, domain)
 
 
+# TODO(amaranth-0.5): remove
+@deprecated("instead of using `Stable`, create registers and comparisons explicitly")
 def Stable(expr, clocks=0, domain=None):
+    with _ignore_deprecated():
         return Sample(expr, clocks + 1, domain) == Sample(expr, clocks, domain)
 
 
+# TODO(amaranth-0.5): remove
+@deprecated("instead of using `Rose`, create registers and comparisons explicitly")
 def Rose(expr, clocks=0, domain=None):
+    with _ignore_deprecated():
         return ~Sample(expr, clocks + 1, domain) & Sample(expr, clocks, domain)
 
 
+# TODO(amaranth-0.5): remove
+@deprecated("instead of using `Fell`, create registers and comparisons explicitly")
 def Fell(expr, clocks=0, domain=None):
+    with _ignore_deprecated():
         return Sample(expr, clocks + 1, domain) & ~Sample(expr, clocks, domain)
 
 

amaranth/hdl/xfrm.py

@@ -2,7 +2,7 @@ from abc import ABCMeta, abstractmethod
 from collections import OrderedDict
 from collections.abc import Iterable
 
-from .._utils import flatten
+from .._utils import flatten, _ignore_deprecated
 from .. import tracer
 from .ast import *
 from .ast import _StatementList
@@ -526,6 +526,7 @@ class SampleDomainInjector(ValueTransformer, StatementTransformer):
     def __init__(self, domain):
         self.domain = domain
 
+    @_ignore_deprecated
     def on_Sample(self, value):
         if value.domain is not None:
             return value
@@ -555,6 +556,7 @@ class SampleLowerer(FragmentTransformer, ValueTransformer, StatementTransformer)
         else:
             raise NotImplementedError # :nocov:
 
+    @_ignore_deprecated
     def on_Sample(self, value):
         if value in self.sample_cache:
             return self.sample_cache[value]

tests/test_hdl_ast.py

@@ -4,6 +4,7 @@ from enum import Enum
 from amaranth.hdl.ast import *
 
 from .utils import *
+from amaranth._utils import _ignore_deprecated
 
 
 class UnsignedEnum(Enum):
@@ -1187,27 +1188,32 @@ class ValueCastableTestCase(FHDLTestCase):
 
 
 class SampleTestCase(FHDLTestCase):
+    @_ignore_deprecated
     def test_const(self):
         s = Sample(1, 1, "sync")
         self.assertEqual(s.shape(), unsigned(1))
 
+    @_ignore_deprecated
     def test_signal(self):
         s1 = Sample(Signal(2), 1, "sync")
         self.assertEqual(s1.shape(), unsigned(2))
         s2 = Sample(ClockSignal(), 1, "sync")
         s3 = Sample(ResetSignal(), 1, "sync")
 
+    @_ignore_deprecated
     def test_wrong_value_operator(self):
         with self.assertRaisesRegex(TypeError,
                 (r"^Sampled value must be a signal or a constant, not "
                 r"\(\+ \(sig \$signal\) \(const 1'd1\)\)$")):
             Sample(Signal() + 1, 1, "sync")
 
+    @_ignore_deprecated
     def test_wrong_clocks_neg(self):
         with self.assertRaisesRegex(ValueError,
                 r"^Cannot sample a value 1 cycles in the future$"):
             Sample(Signal(), -1, "sync")
 
+    @_ignore_deprecated
     def test_wrong_domain(self):
         with self.assertRaisesRegex(TypeError,
                 r"^Domain name must be a string or None, not 0$"):

tests/test_hdl_dsl.py

@@ -8,6 +8,7 @@ from amaranth.hdl.dsl import *
 from amaranth.lib.enum import Enum
 
 from .utils import *
+from amaranth._utils import _ignore_deprecated
 
 
 class DSLTestCase(FHDLTestCase):
@@ -131,6 +132,7 @@ class DSLTestCase(FHDLTestCase):
         )
         """)
 
+    @_ignore_deprecated
     def test_sample_domain(self):
         m = Module()
         i = Signal()

tests/test_hdl_xfrm.py

@@ -9,6 +9,7 @@ from amaranth.hdl.xfrm import *
 from amaranth.hdl.mem import *
 
 from .utils import *
+from amaranth._utils import _ignore_deprecated
 
 
 class DomainRenamerTestCase(FHDLTestCase):
@@ -216,6 +217,7 @@ class SampleLowererTestCase(FHDLTestCase):
         self.o2 = Signal()
         self.o3 = Signal()
 
+    @_ignore_deprecated
     def test_lower_signal(self):
         f = Fragment()
         f.add_statements(
@@ -238,6 +240,7 @@ class SampleLowererTestCase(FHDLTestCase):
         self.assertEqual(len(f.drivers["sync"]), 2)
         self.assertEqual(len(f.drivers["pix"]), 1)
 
+    @_ignore_deprecated
     def test_lower_const(self):
         f = Fragment()
         f.add_statements(

tests/test_lib_fifo.py

@@ -6,6 +6,7 @@ from amaranth.sim import *
 from amaranth.lib.fifo import *
 
 from .utils import *
+from amaranth._utils import _ignore_deprecated
 
 
 class FIFOTestCase(FHDLTestCase):
@@ -60,6 +61,7 @@ class FIFOTestCase(FHDLTestCase):
                     r"requested exact depth 16 is not$")):
             AsyncFIFOBuffered(width=8, depth=16, exact_depth=True)
 
+
 class FIFOModel(Elaboratable, FIFOInterface):
     """
     Non-synthesizable first-in first-out queue, implemented naively as a chain of registers.
@@ -128,6 +130,7 @@ class FIFOModelEquivalenceSpec(Elaboratable):
         self.r_domain = r_domain
         self.w_domain = w_domain
 
+    @_ignore_deprecated
     def elaborate(self, platform):
         m = Module()
         m.submodules.dut  = dut  = self.fifo
@@ -168,6 +171,7 @@ class FIFOContractSpec(Elaboratable):
         self.w_domain = w_domain
         self.bound    = bound
 
+    @_ignore_deprecated
     def elaborate(self, platform):
         m = Module()
         m.submodules.dut = fifo = self.fifo

tests/test_sim.py

@@ -11,6 +11,7 @@ from amaranth.hdl.ir import *
 from amaranth.sim import *
 
 from .utils import *
+from amaranth._utils import _ignore_deprecated
 
 
 class SimulatorUnitTestCase(FHDLTestCase):
@@ -811,6 +812,7 @@ class SimulatorIntegrationTestCase(FHDLTestCase):
             sim.add_clock(1e-6)
             sim.add_sync_process(process)
 
+    @_ignore_deprecated
     def test_sample_helpers(self):
         m = Module()
         s = Signal(2)