lib.cdc: expand ResetSynchronizer documentation.

Loosely based on work by @Wren6991.

diff --git a/nmigen/lib/cdc.py b/nmigen/lib/cdc.py
index 602d957a194533c24a111ede9747c434f8b4fd68..c26b961b3ae3f757f234b9f61b62b3a1398baf8b 100644 (file)
--- a/nmigen/lib/cdc.py
+++ b/nmigen/lib/cdc.py
@@ -15,9 +15,9 @@ class FFSynchronizer(Elaboratable):
 
     Parameters
     ----------
-    i : Signal, in
+    i : Signal(n), in
         Signal to be resynchronised.
-    o : Signal, out
+    o : Signal(n), out
         Signal connected to synchroniser output.
     o_domain : str
         Name of output clock domain.
@@ -33,8 +33,8 @@ class FFSynchronizer(Elaboratable):
 
     Platform override
     -----------------
-    Define the ``get_ff_sync`` platform method to override the implementation of :class:`FFSynchronizer`,
-    e.g. to instantiate library cells directly.
+    Define the ``get_ff_sync`` platform method to override the implementation of
+    :class:`FFSynchronizer`, e.g. to instantiate library cells directly.
 
     Note on Reset
     -------------
@@ -81,6 +81,32 @@ MultiReg = deprecated("instead of `MultiReg`, use `FFSynchronizer`")(FFSynchroni
 
 
 class ResetSynchronizer(Elaboratable):
+    """Synchronize deassertion of a clock domain reset.
+
+    The reset of the clock domain driven by the :class:`ResetSynchronizer` is asserted
+    asynchronously and deasserted synchronously, eliminating metastability during deassertion.
+
+    The driven clock domain could use a reset that is asserted either synchronously or
+    asynchronously; a reset is always deasserted synchronously. A domain with an asynchronously
+    asserted reset is useful if the clock of the domain may be gated, yet the domain still
+    needs to be reset promptly; otherwise, synchronously asserted reset (the default) should
+    be used.
+
+    Parameters
+    ----------
+    arst : Signal(1), out
+        Asynchronous reset signal, to be synchronized.
+    domain : str
+        Name of clock domain to reset.
+    stages : int, >=2
+        Number of synchronization stages between input and output. The lowest safe number is 2,
+        with higher numbers reducing MTBF further, at the cost of increased deassertion latency.
+
+    Platform override
+    -----------------
+    Define the ``get_reset_sync`` platform method to override the implementation of
+    :class:`ResetSynchronizer`, e.g. to instantiate library cells directly.
+    """
     def __init__(self, arst, *, domain="sync", stages=2):
         self.arst = arst