From 18837b9029091e2110e015a038e960a84846497e Mon Sep 17 00:00:00 2001 From: Catherine Date: Mon, 13 Dec 2021 06:23:12 +0000 Subject: [PATCH] docs: cover `amaranth.lib.cdc`. --- amaranth/lib/cdc.py | 48 ++++++++++++++++++++++----------------------- docs/conf.py | 1 + docs/stdlib.rst | 1 + docs/stdlib/cdc.rst | 13 ++++++++++++ 4 files changed, 39 insertions(+), 24 deletions(-) create mode 100644 docs/stdlib/cdc.rst diff --git a/amaranth/lib/cdc.py b/amaranth/lib/cdc.py index 9278c8e..82813cb 100644 --- a/amaranth/lib/cdc.py +++ b/amaranth/lib/cdc.py @@ -31,35 +31,35 @@ class FFSynchronizer(Elaboratable): 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 - ----------------- + Platform overrides + ------------------ 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:: - 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: + :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. - - 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. + 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: - :class:`FFSynchronizer` is reset by the ``o_domain`` reset only. + - 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. """ def __init__(self, i, o, *, o_domain="sync", reset=0, reset_less=True, stages=2, max_input_delay=None): @@ -119,8 +119,8 @@ class AsyncFFSynchronizer(Elaboratable): 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 - ----------------- + Platform overrides + ------------------ Define the ``get_async_ff_sync`` platform method to override the implementation of :class:`AsyncFFSynchronizer`, e.g. to instantiate library cells directly. """ @@ -203,8 +203,8 @@ class ResetSynchronizer(Elaboratable): 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 - ----------------- + Platform overrides + ------------------ Define the ``get_reset_sync`` platform method to override the implementation of :class:`ResetSynchronizer`, e.g. to instantiate library cells directly. """ @@ -227,9 +227,9 @@ class PulseSynchronizer(Elaboratable): """A one-clock pulse on the input produces a one-clock pulse on the output. If the output clock is faster than the input clock, then the input may be safely asserted at - 100% duty cycle. Otherwise, if the clock ratio is `n`:1, the input may be asserted at most once - in every `n` input clocks, else pulses may be dropped. Other than this there is no constraint - on the ratio of input and output clock frequency. + 100% duty cycle. Otherwise, if the clock ratio is ``n``:1, the input may be asserted at most + once in every ``n`` input clocks, else pulses may be dropped. Other than this there is + no constraint on the ratio of input and output clock frequency. Parameters ---------- diff --git a/docs/conf.py b/docs/conf.py index ba3c733..4fe6a3d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,6 +30,7 @@ todo_include_todos = True napoleon_google_docstring = False napoleon_numpy_docstring = True napoleon_use_ivar = True +napoleon_custom_sections = ["Platform overrides"] html_theme = "sphinx_rtd_theme" html_static_path = ["_static"] diff --git a/docs/stdlib.rst b/docs/stdlib.rst index 333db16..5dafadd 100644 --- a/docs/stdlib.rst +++ b/docs/stdlib.rst @@ -9,3 +9,4 @@ Standard library :maxdepth: 2 stdlib/coding + stdlib/cdc diff --git a/docs/stdlib/cdc.rst b/docs/stdlib/cdc.rst new file mode 100644 index 0000000..3619d12 --- /dev/null +++ b/docs/stdlib/cdc.rst @@ -0,0 +1,13 @@ +Clock domain crossing +##################### + +.. py:module:: amaranth.lib.cdc + +The ``amaranth.lib.cdc`` package provides modules for transferring data between clock domains. + + +.. autoclass:: FFSynchronizer() +.. autoclass:: AsyncFFSynchronizer() +.. autoclass:: ResetSynchronizer() +.. autoclass:: PulseSynchronizer() +