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

Author: Wren6991

nmigen/lib/cdc.py

@@ -5,7 +5,40 @@
 
 
 class MultiReg:
+    """Resynchronise a signal to a different clock domain.
+
+    Consists of a chain of flipflops. Eliminates metastabilities
+    at the output, but does not provide any other guarantees as
+    to the safe domain-crossing of a signal.
+
+    Parameters
+    ----------
+    i : Signal(), in
+        Signal to be resynchronised
+    o : Signal(), out
+        Signal connected to synchroniser output
+    odomain : str
+        Name of output clock domain
+    n : int
+        Number of flops between input and output.
+        To avoid exposing output domain to metastabilities,
+        n should be >= 2.
+    reset : int
+        Reset value of the flipflops.
+        TODO: but it's reset_less???
+
+    Override
+    --------
+    Define the `get_multi_reg` platform attribute to override
+    the implementation of MultiReg, e.g. to instantiate
+    library cells directly.
+    """
     def __init__(self, i, o, odomain="sync", n=2, reset=0):
+        if not isinstance(n, int) or n < 1:
+            raise TypeError("n must be a positive integer, not '{!r}'".format(n))
+        if not isinstance(reset, int):
+            raise TypeError("reset must be a constant integer, not '{!r}'".format(reset))
+
         self.i = i
         self.o = o
         self.odomain = odomain
@@ -26,7 +59,33 @@ def elaborate(self, platform):
 
 
 class ResetSynchronizer:
+    """Synchronise the deassertion of a reset to a local clock.
+
+    The reset may still be asserted asynchronously. This module
+    assists with guaranteeing a minimum pulse width, and
+    meeting removal/recovery constraints.
+
+    Parameters
+    ----------
+    arst : Signal(1), out
+        Resynchronised reset signal.
+        Asserted when this module is reset,
+        deasserted after n clocks.
+    domain : str
+        Name of domain to synchronise 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(TypeError):
+            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()