From 1e869aedd3d4edaf38d6d1d16e40da3c36aa153c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20J=C3=B6rdens?= Date: Tue, 3 Aug 2021 11:36:04 +0200 Subject: [PATCH] docs: clarify rtio_clock=e req's and use case This regularly leads to people misunderstanding the setting. Mentioning the Si5324 specifically or Urukul synchronization doesn't help constraining or explaining the feature, its consequences and requirements. Despite being non-standard this feature is also generally not sufficient to achieve cross-device determinism as the other devices need to be made deterministic as well. --- doc/manual/core_device.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/core_device.rst b/doc/manual/core_device.rst index 9488e4d33..bb38c2b9e 100644 --- a/doc/manual/core_device.rst +++ b/doc/manual/core_device.rst @@ -164,6 +164,6 @@ See :mod:`artiq.coredevice.i2c` for more details. Clocking ++++++++ -The KC705 supports an internal 125MHz RTIO clock (based on its crystal oscillator) and an external clock, that can be selected using the ``rtio_clock`` configuration entry. Valid values are ``i`` and ``e``, and the default is ``i``. The selected option can be observed in the core device boot logs. +The KC705 supports an internal 125 MHz RTIO clock (based on its crystal oscillator) and an external clock, that can be selected using the ``rtio_clock`` configuration entry. Valid values are ``i`` and ``e``, and the default is ``i``. The selected option can be observed in the core device boot logs. -On Kasli, when set to ``e``, the ``rtio_clock`` setting overrides the built-in (and variant-dependent) Si5324 synthesizer configuration and disables the Si5324. The user must apply a clock at the RTIO frequency on the Kasli front panel SMA. As the Si5324 is bypassed in this mode, its skew is deterministic, which is useful to distribute clocks externally to Kasli and Urukul when Urukul phase synchronization is desired. +On Kasli, ``rtio_clock=i`` is the default and generates the RTIO clock using a PLL locked either to an internal crystal or to an external frequency reference (variant-dependent). ``rtio_clock=e`` bypasses that PLL and the user must supply the RTIO clock (typically 125 MHz) at the Kasli front panel SMA input. Bypassing the PLL ensures the skews between input clock, Kasli downstream clock outputs, and RTIO clock are deterministic accross reboots of the system. This is useful when phase determinism is required in situtations where the reference clock fans out to other devices before reaching Kasli.