From 52e761dc33c55df84335c5bc543a8eabebb5ec9c Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Mon, 23 Sep 2019 19:31:23 +0000
Subject: [PATCH] lib.cdc: expand ResetSynchronizer documentation.

Loosely based on work by @Wren6991.
---
 nmigen/lib/cdc.py | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/nmigen/lib/cdc.py b/nmigen/lib/cdc.py
index 602d957..c26b961 100644
--- 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
 
-- 
2.30.2