lib.cdc: Add docstrings and basic parameter checking to MultiReg and ResetSynchroniser.

Author: Wren6991

nmigen/lib/cdc.py

@@ -50,6 +50,8 @@ class MultiReg:
     MultiReg is reset by the ``odomain`` reset only.
     """
     def __init__(self, i, o, odomain="sync", n=2, reset=0, reset_less=True):
+        if not isinstance(n, int) or n < 1:
+            raise TypeError("n must be a positive integer, not '{!r}'".format(n))
         self.i = i
         self.o = o
         self.odomain = odomain
@@ -70,7 +72,27 @@ def elaborate(self, platform):
 
 
 class ResetSynchronizer:
+    """Synchronize the deassertion of a reset to a local clock.
+
+    Output `assertion` is asynchronous, so the local clock need not be free-running.
+
+    Parameters
+    ----------
+    arst : Signal(1), out
+        Asynchronous reset signal, to be synchronized.
+    domain : str
+        Name of domain to synchronize reset to.
+    n : int, >=1
+        Number of clock edges from input deassertion to output deassertion
+
+    Override
+    --------
+    Define the ``get_reset_sync`` platform attribute to override the implementation of
+    ResetSynchronizer, e.g. to instantiate library cells directly.
+    """
     def __init__(self, arst, domain="sync", n=2):
+        if not isinstance(n, int) or n < 1:
+            raise TypeError("n must be a positive integer, not '{!r}'".format(n))
         self.arst = arst
         self.domain = domain
 

nmigen/test/test_lib_cdc.py

@@ -7,6 +7,20 @@
 
 
 class MultiRegTestCase(FHDLTestCase):
+    def test_paramcheck(self):
+        i = Signal()
+        o = Signal()
+        with self.assertRaises(TypeError):
+            m = MultiReg(i, o, n=0)
+        with self.assertRaises(TypeError):
+            m = MultiReg(i, o, n="x")
+        with self.assertRaises(ValueError):
+            m = MultiReg(i, o, n=2, reset="a")
+        with self.assertRaises(TypeError):
+            m = MultiReg(i, o, n=2, reset=i)
+        m = MultiReg(i, o, n=1)
+        m = MultiReg(i, o, reset=-1)
+
     def test_basic(self):
         i = Signal()
         o = Signal()
@@ -45,6 +59,14 @@ def process():
 
 
 class ResetSynchronizerTestCase(FHDLTestCase):
+    def test_paramcheck(self):
+        arst = Signal()
+        with self.assertRaises(TypeError):
+            r = ResetSynchronizer(arst, n=0)
+        with self.assertRaises(TypeError):
+            r = ResetSynchronizer(arst, n="a")
+        r = ResetSynchronizer(arst)
+
     def test_basic(self):
         arst = Signal()
         m = Module()