Implement RFC 55: New lib.io components.

amaranth/build/res.py

@@ -1,8 +1,10 @@
+import warnings
 from collections import OrderedDict
 
 from ..hdl import *
 from ..hdl._ast import SignalDict
 from ..lib import wiring, io
+from .._utils import _ignore_deprecated
 
 from .dsl import *
 
@@ -247,6 +249,10 @@ class ResourceManager:
                 if dir == "-":
                     return port
                 else:
+                    warnings.warn(f"Using platform.request without `dir=\"-\"` is deprecated; "
+                                  f"use `amaranth.lib.io.*Buffer` components instead",
+                                  DeprecationWarning, stacklevel=2)
+                    with _ignore_deprecated():
                         pin = wiring.flipped(io.Pin(len(phys), dir, xdr=xdr, path=path))
                     buffer = PinBuffer(pin, port)
                     self._pins.append((pin, port, buffer))

amaranth/lib/io.py

@@ -6,6 +6,7 @@ from collections.abc import Iterable
 from ..hdl import *
 from ..lib import wiring, data
 from ..lib.wiring import In, Out
+from .._utils import deprecated, _ignore_deprecated
 from .. import tracer
 
 
@@ -889,6 +890,8 @@ class Pin(wiring.PureInterface):
         """A signature for :class:`Pin`.  The parameters are as defined on the ``Pin`` class,
         and are accessible as attributes.
         """
+        # TODO(amaranth-0.6): remove
+        @deprecated("`amaranth.lib.io.Pin` is deprecated, use `amaranth.lib.io.*Buffer` instead")
         def __init__(self, width, dir, *, xdr=0):
             if not isinstance(width, int) or width < 0:
                 raise TypeError("Width must be a non-negative integer, not {!r}"
@@ -942,16 +945,19 @@ class Pin(wiring.PureInterface):
         def create(self, *, path=None, src_loc_at=0):
             return Pin(self.width, self.dir, xdr=self.xdr, path=path, src_loc_at=1 + src_loc_at)
 
+    # TODO(amaranth-0.6): remove
+    @deprecated("`amaranth.lib.io.Pin` is deprecated, use `amaranth.lib.io.*Buffer` instead")
     def __init__(self, width, dir, *, xdr=0, name=None, path=None, src_loc_at=0):
         if name is not None:
             if path is not None:
                 raise ValueError("Cannot pass both name and path")
             path = (name,)
         if path is None:
-            name = tracer.get_var_name(depth=2 + src_loc_at, default="$pin")
+            name = tracer.get_var_name(depth=3 + src_loc_at, default="$pin")
             path = (name,)
         self.path = tuple(path)
         self.name = "__".join(path)
+        with _ignore_deprecated():
             signature = Pin.Signature(width, dir, xdr=xdr)
         super().__init__(signature, path=path, src_loc_at=src_loc_at + 1)
 

docs/changes.rst

@@ -41,7 +41,8 @@ Apply the following changes to code written against Amaranth 0.4 to migrate it t
 * Remove any usage of ``name=`` with assertions, possibly replacing them with custom messages
 * Ensure all elaboratables are subclasses of :class:`Elaboratable`
 * Ensure clock domains aren't used outside the module that defines them, or its submodules; move clock domain definitions upwards in the hierarchy as necessary
-* Remove uses of ``amaranth.lib.coding.*`` by inlining or copying the implementation of the modules.
+* Remove uses of ``amaranth.lib.coding.*`` by inlining or copying the implementation of the modules
+* Update uses of ``platform.request`` to pass ``dir="-"`` and use :mod:`amaranth.lib.io` buffers
 
 
 Implemented RFCs
@@ -74,6 +75,7 @@ Implemented RFCs
 * `RFC 50`_: ``Print`` statement and string formatting
 * `RFC 51`_: Add ``ShapeCastable.from_bits`` and ``amaranth.lib.data.Const``
 * `RFC 53`_: Low-level I/O primitives
+* `RFC 55`_: New ``lib.io`` components
 * `RFC 58`_: Core support for ``ValueCastable`` formatting
 * `RFC 59`_: Get rid of upwards propagation of clock domains
 * `RFC 62`_: The ``MemoryData`` class

tests/test_build_res.py

@@ -5,6 +5,7 @@ from amaranth.lib.wiring import *
 from amaranth.lib.io import *
 from amaranth.build.dsl import *
 from amaranth.build.res import *
+from amaranth._utils import _ignore_deprecated
 
 from .utils import *
 
@@ -56,6 +57,7 @@ class ResourceManagerTestCase(FHDLTestCase):
 
     def test_request_basic(self):
         r = self.cm.lookup("user_led", 0)
+        with _ignore_deprecated():
             user_led = self.cm.request("user_led", 0)
 
         self.assertIsInstance(flipped(user_led), Pin)
@@ -74,6 +76,7 @@ class ResourceManagerTestCase(FHDLTestCase):
         self.assertEqual(port.invert, (False,))
 
     def test_request_with_dir(self):
+        with _ignore_deprecated():
             i2c = self.cm.request("i2c", 0, dir={"sda": "o"})
         self.assertIsInstance(flipped(i2c.sda), Pin)
         self.assertEqual(i2c.sda.dir, "o")
@@ -82,6 +85,7 @@ class ResourceManagerTestCase(FHDLTestCase):
         sda_buffer._MustUse__silence = True
 
     def test_request_tristate(self):
+        with _ignore_deprecated():
             i2c = self.cm.request("i2c", 0)
         self.assertEqual(i2c.sda.dir, "io")
 
@@ -97,6 +101,7 @@ class ResourceManagerTestCase(FHDLTestCase):
         self.assertEqual(sda_port.io.metadata[0].name, "N11")
 
     def test_request_diffpairs(self):
+        with _ignore_deprecated():
             clk100 = self.cm.request("clk100", 0)
         self.assertIsInstance(flipped(clk100), Pin)
         self.assertEqual(clk100.dir, "i")
@@ -120,8 +125,10 @@ class ResourceManagerTestCase(FHDLTestCase):
         ]
         self.cm.add_resources(new_resources)
 
+        with _ignore_deprecated():
             cs = self.cm.request("cs")
             clk = self.cm.request("clk")
+
         (
             (cs_pin, cs_port, cs_buffer),
             (clk_pin, clk_port, clk_buffer),
@@ -154,6 +161,7 @@ class ResourceManagerTestCase(FHDLTestCase):
                 Subsignal("copi", Pins("4", conn=("pmod", 0))),
             )
         ])
+        with _ignore_deprecated():
             spi0 = self.cm.request("spi", 0)
         (
             (cs_pin, cs_port, cs_buffer),
@@ -187,6 +195,7 @@ class ResourceManagerTestCase(FHDLTestCase):
                 Subsignal("copi", Pins("4", conn=("pmod_extension", 0))),
             )
         ])
+        with _ignore_deprecated():
             spi0 = self.cm.request("spi", 0)
         (
             (cs_pin, cs_port, cs_buffer),
@@ -208,6 +217,7 @@ class ResourceManagerTestCase(FHDLTestCase):
         self.assertEqual(copi_port.io.metadata[0].name, "B3")
 
     def test_request_clock(self):
+        with _ignore_deprecated():
             clk100 = self.cm.request("clk100", 0)
             clk50 = self.cm.request("clk50", 0, dir="i")
         (
@@ -222,6 +232,7 @@ class ResourceManagerTestCase(FHDLTestCase):
         ])
 
     def test_add_clock(self):
+        with _ignore_deprecated():
             i2c = self.cm.request("i2c")
         self.cm.add_clock_constraint(i2c.scl.o, 100e3)
         self.assertEqual(list(self.cm.iter_clock_constraints()), [
@@ -267,23 +278,27 @@ class ResourceManagerTestCase(FHDLTestCase):
             self.cm.add_clock_constraint(Signal(), None)
 
     def test_wrong_request_duplicate(self):
+        with _ignore_deprecated():
             self.cm.request("user_led", 0)
         (pin, port, buffer), = self.cm.iter_pins()
         buffer._MustUse__silence = True
         with self.assertRaisesRegex(ResourceError,
                 r"^Resource user_led#0 has already been requested$"):
+            with _ignore_deprecated():
                 self.cm.request("user_led", 0)
 
     def test_wrong_request_duplicate_physical(self):
         self.cm.add_resources([
             Resource("clk20", 0, Pins("H1", dir="i")),
         ])
+        with _ignore_deprecated():
             self.cm.request("clk100", 0)
         (pin, port, buffer), = self.cm.iter_pins()
         buffer._MustUse__silence = True
         with self.assertRaisesRegex(ResourceError,
                 (r"^Resource component clk20_0 uses physical pin H1, but it is already "
                     r"used by resource component clk100_0 that was requested earlier$")):
+            with _ignore_deprecated():
                 self.cm.request("clk20", 0)
 
     def test_wrong_request_with_dir(self):
@@ -319,6 +334,7 @@ class ResourceManagerTestCase(FHDLTestCase):
             i2c = self.cm.request("i2c", 0, xdr=2)
 
     def test_wrong_clock_constraint_twice(self):
+        with _ignore_deprecated():
             clk100 = self.cm.request("clk100")
         (pin, port, buffer), = self.cm.iter_pins()
         buffer._MustUse__silence = True

tests/test_lib_io.py

@@ -6,6 +6,7 @@ from amaranth.hdl._ir import build_netlist
 from amaranth.lib.io import *
 from amaranth.lib.wiring import *
 from amaranth.lib import wiring, data
+from amaranth._utils import _ignore_deprecated
 
 from .utils import *
 
@@ -701,34 +702,40 @@ class PinSignatureTestCase(FHDLTestCase):
 
 class PinSignatureCombTestCase(PinSignatureTestCase):
     def test_signature_i(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="i")
         self.assertSignatureEqual(sig_1, {
             "i": In(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="i")
         self.assertSignatureEqual(sig_2, {
             "i": In(2),
         })
 
     def test_signature_o(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="o")
         self.assertSignatureEqual(sig_1, {
             "o": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="o")
         self.assertSignatureEqual(sig_2, {
             "o": Out(2),
         })
 
     def test_signature_oe(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="oe")
         self.assertSignatureEqual(sig_1, {
             "o":  Out(1),
             "oe": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="oe")
         self.assertSignatureEqual(sig_2, {
             "o":  Out(2),
@@ -736,6 +743,7 @@ class PinSignatureCombTestCase(PinSignatureTestCase):
         })
 
     def test_signature_io(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="io")
         self.assertSignatureEqual(sig_1, {
             "i":  In(1),
@@ -743,6 +751,7 @@ class PinSignatureCombTestCase(PinSignatureTestCase):
             "oe": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="io")
         self.assertSignatureEqual(sig_2, {
             "i":  In(2),
@@ -753,12 +762,14 @@ class PinSignatureCombTestCase(PinSignatureTestCase):
 
 class PinSignatureSDRTestCase(PinSignatureTestCase):
     def test_signature_i(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="i", xdr=1)
         self.assertSignatureEqual(sig_1, {
             "i_clk": Out(1),
             "i": In(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="i", xdr=1)
         self.assertSignatureEqual(sig_2, {
             "i_clk": Out(1),
@@ -766,12 +777,14 @@ class PinSignatureSDRTestCase(PinSignatureTestCase):
         })
 
     def test_signature_o(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="o", xdr=1)
         self.assertSignatureEqual(sig_1, {
             "o_clk": Out(1),
             "o": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="o", xdr=1)
         self.assertSignatureEqual(sig_2, {
             "o_clk": Out(1),
@@ -779,6 +792,7 @@ class PinSignatureSDRTestCase(PinSignatureTestCase):
         })
 
     def test_signature_oe(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="oe", xdr=1)
         self.assertSignatureEqual(sig_1, {
             "o_clk": Out(1),
@@ -786,6 +800,7 @@ class PinSignatureSDRTestCase(PinSignatureTestCase):
             "oe": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="oe", xdr=1)
         self.assertSignatureEqual(sig_2, {
             "o_clk": Out(1),
@@ -794,6 +809,7 @@ class PinSignatureSDRTestCase(PinSignatureTestCase):
         })
 
     def test_signature_io(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="io", xdr=1)
         self.assertSignatureEqual(sig_1, {
             "i_clk": Out(1),
@@ -803,6 +819,7 @@ class PinSignatureSDRTestCase(PinSignatureTestCase):
             "oe": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="io", xdr=1)
         self.assertSignatureEqual(sig_2, {
             "i_clk": Out(1),
@@ -815,6 +832,7 @@ class PinSignatureSDRTestCase(PinSignatureTestCase):
 
 class PinSignatureDDRTestCase(PinSignatureTestCase):
     def test_signature_i(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="i", xdr=2)
         self.assertSignatureEqual(sig_1, {
             "i_clk": Out(1),
@@ -822,6 +840,7 @@ class PinSignatureDDRTestCase(PinSignatureTestCase):
             "i1": In(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="i", xdr=2)
         self.assertSignatureEqual(sig_2, {
             "i_clk": Out(1),
@@ -830,6 +849,7 @@ class PinSignatureDDRTestCase(PinSignatureTestCase):
         })
 
     def test_signature_o(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="o", xdr=2)
         self.assertSignatureEqual(sig_1, {
             "o_clk": Out(1),
@@ -837,6 +857,7 @@ class PinSignatureDDRTestCase(PinSignatureTestCase):
             "o1": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="o", xdr=2)
         self.assertSignatureEqual(sig_2, {
             "o_clk": Out(1),
@@ -845,6 +866,7 @@ class PinSignatureDDRTestCase(PinSignatureTestCase):
         })
 
     def test_signature_oe(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="oe", xdr=2)
         self.assertSignatureEqual(sig_1, {
             "o_clk": Out(1),
@@ -853,6 +875,7 @@ class PinSignatureDDRTestCase(PinSignatureTestCase):
             "oe": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="oe", xdr=2)
         self.assertSignatureEqual(sig_2, {
             "o_clk": Out(1),
@@ -862,6 +885,7 @@ class PinSignatureDDRTestCase(PinSignatureTestCase):
         })
 
     def test_signature_io(self):
+        with _ignore_deprecated():
             sig_1 = Pin.Signature(1, dir="io", xdr=2)
         self.assertSignatureEqual(sig_1, {
             "i_clk": Out(1),
@@ -873,6 +897,7 @@ class PinSignatureDDRTestCase(PinSignatureTestCase):
             "oe": Out(1),
         })
 
+        with _ignore_deprecated():
             sig_2 = Pin.Signature(2, dir="io", xdr=2)
         self.assertSignatureEqual(sig_2, {
             "i_clk": Out(1),
@@ -887,16 +912,20 @@ class PinSignatureDDRTestCase(PinSignatureTestCase):
 
 class PinSignatureReprCase(FHDLTestCase):
     def test_repr(self):
+        with _ignore_deprecated():
             sig_0 = Pin.Signature(1, dir="i")
         self.assertRepr(sig_0, "Pin.Signature(1, dir='i')")
+        with _ignore_deprecated():
             sig_0 = Pin.Signature(2, dir="o", xdr=1)
         self.assertRepr(sig_0, "Pin.Signature(2, dir='o', xdr=1)")
+        with _ignore_deprecated():
             sig_0 = Pin.Signature(3, dir="io", xdr=2)
         self.assertRepr(sig_0, "Pin.Signature(3, dir='io', xdr=2)")
 
 
 class PinTestCase(FHDLTestCase):
     def test_attributes(self):
+        with _ignore_deprecated():
             pin = Pin(2, dir="io", xdr=2)
         self.assertEqual(pin.width, 2)
         self.assertEqual(pin.dir,   "io")
@@ -907,10 +936,12 @@ class PinTestCase(FHDLTestCase):
         self.assertEqual(pin.name, "pin")
         self.assertEqual(pin.path, ("pin",))
         self.assertEqual(pin.i0.name, "pin__i0")
+        with _ignore_deprecated():
             pin = Pin(2, dir="io", xdr=2, name="testpin")
         self.assertEqual(pin.name, "testpin")
         self.assertEqual(pin.path, ("testpin",))
         self.assertEqual(pin.i0.name, "testpin__i0")
+        with _ignore_deprecated():
             pin = Pin(2, dir="io", xdr=2, path=["a", "b"])
         self.assertEqual(pin.name, "a__b")
         self.assertEqual(pin.path, ("a", "b"))