From 797f69bb211e229a7cc754e7850e640cfc41e2c2 Mon Sep 17 00:00:00 2001 From: Luke Kenneth Casson Leighton Date: Fri, 31 Dec 2021 20:27:17 +0000 Subject: [PATCH] update nmigen/lib/cdc.py docstrings --- nmigen/lib/cdc.py | 49 ++++++++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 20 deletions(-) diff --git a/nmigen/lib/cdc.py b/nmigen/lib/cdc.py index 4bc5252..32adde4 100644 --- a/nmigen/lib/cdc.py +++ b/nmigen/lib/cdc.py @@ -27,39 +27,40 @@ class FFSynchronizer(Elaboratable): o_domain : str Name of output clock domain. reset : int - Reset value of the flip-flops. On FPGAs, even if ``reset_less`` is True, + Reset value of the flip-flops. On FPGAs, even if ``reset_less`` is ``True``, the :class:`FFSynchronizer` is still set to this value during initialization. reset_less : bool If ``True`` (the default), this :class:`FFSynchronizer` is unaffected by ``o_domain`` - reset. See "Note on Reset" below. - stages : int + reset. See the note below for details. + 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 latency. max_input_delay : None or float Maximum delay from the input signal's clock to the first synchronization stage, in seconds. If specified and the platform does not support it, elaboration will fail. - Platform override - ----------------- - Define the ``get_ff_sync`` platform method to override the implementation of - :class:`FFSynchronizer`, e.g. to instantiate library cells directly. - Note on Reset - ------------- - :class:`FFSynchronizer` is non-resettable by default. Usually this is the safest option; - on FPGAs the :class:`FFSynchronizer` will still be initialized to its ``reset`` value when - the FPGA loads its configuration. + .. note:: + + :class:`FFSynchronizer` is non-resettable by default. Usually this is the safest option; + on FPGAs the :class:`FFSynchronizer` will still be initialized to its ``reset`` value when + the FPGA loads its configuration. - However, in designs where the value of the :class:`FFSynchronizer` must be valid immediately - after reset, consider setting ``reset_less`` to False if any of the following is true: + However, in designs where the value of the :class:`FFSynchronizer` must be valid immediately + after reset, consider setting ``reset_less`` to ``False`` if any of the following is true: - - You are targeting an ASIC, or an FPGA that does not allow arbitrary initial flip-flop states; - - Your design features warm (non-power-on) resets of ``o_domain``, so the one-time - initialization at power on is insufficient; - - Your design features a sequenced reset, and the :class:`FFSynchronizer` must maintain - its reset value until ``o_domain`` reset specifically is deasserted. + - You are targeting an ASIC, or an FPGA that does not allow arbitrary initial flip-flop states; + - Your design features warm (non-power-on) resets of ``o_domain``, so the one-time + initialization at power on is insufficient; + - Your design features a sequenced reset, and the :class:`FFSynchronizer` must maintain + its reset value until ``o_domain`` reset specifically is deasserted. - :class:`FFSynchronizer` is reset by the ``o_domain`` reset only. + :class:`FFSynchronizer` is reset by the ``o_domain`` reset only. + + Platform overrides + ------------------ + Define the ``get_ff_sync`` platform method to override the implementation of + :class:`FFSynchronizer`, e.g. to instantiate library cells directly. """ def __init__(self, i, o, *, o_domain="sync", reset=0, reset_less=True, stages=2, max_input_delay=None): @@ -115,6 +116,14 @@ class AsyncFFSynchronizer(Elaboratable): with higher numbers reducing MTBF further, at the cost of increased deassertion latency. async_edge : str The edge of the input signal which causes the output to be set. Must be one of "pos" or "neg". + max_input_delay : None or float + Maximum delay from the input signal's clock to the first synchronization stage, in seconds. + If specified and the platform does not support it, elaboration will fail. + + Platform overrides + ------------------ + Define the ``get_async_ff_sync`` platform method to override the implementation of + :class:`AsyncFFSynchronizer`, e.g. to instantiate library cells directly. """ def __init__(self, i, o, *, o_domain="sync", stages=2, async_edge="pos", max_input_delay=None): _check_stages(stages) -- 2.30.2