n3xx: Add comments on clock_source=external,time_source=gpsdo

It is, in principle, possible to use an external clock to synchronize
N3x0 devices in frequency, and then use a GPSDO for a coarse time
synchronization. This use case is deliberately not supported, as the
GPSDO PPS signal and the external clock signal are by definition not
matched, which will remove any guarantees on time/phase alignment.

Because there are certain, niche use cases where the lack of phase
alignment is acceptable, but only an external clock is available (no
shared external PPS), usage of GPS for generating a PPS signal may be
fine. This patch does not enable the usage of this combination out of
the box, but adds comments and an update to the manual to explain the
risks of this combination, and how to enable it (by patching MPM).

4 files changed, 39 insertions, 3 deletions

diff --git a/fpga/usrp3/top/n3xx/n3xx_clocking.v b/fpga/usrp3/top/n3xx/n3xx_clocking.v
index a1d07702a..0eeebb154 100644
--- a/fpga/usrp3/top/n3xx/n3xx_clocking.v
+++ b/fpga/usrp3/top/n3xx/n3xx_clocking.v
@@ -237,11 +237,17 @@ module n3xx_clocking (
   //  ____________|              PPS              |
   // |   Clocks   | External | FPGA  | GPSDO | WR |
   // |--------------------------------------------|
-  // |External 10 |    x     |  x    |       |    |
+  // |External 10 |    x     |  x    |  (x)  |    |
   // |Internal 25 |          |  x    |       | x  |
   // |GPSDO    20 |          |       |   x   |    |
   // |--------------------------------------------|
   //
+  // A note on external clock + GPSDO timing: The hardware doesn't prohibit this
+  // use case, but GPSDO and external clock are guaranteed to be not matched, so
+  // this will certainly cause a non-deterministic time alignment between devices.
+  // Using this combination will still allow receiving samples, but there is no
+  // guarantee regarding phase/time alignment whatsoever.
+  //
   ///////////////////////////////////////////////////////////////////////////////////////
 
   wire pps_ext_refclk;
diff --git a/host/docs/sync.dox b/host/docs/sync.dox
index 9ce618010..9174bf5de 100644
--- a/host/docs/sync.dox
+++ b/host/docs/sync.dox
@@ -17,7 +17,8 @@ USRP devices take two reference signals in order to synchronize clocks
 and time:
 
 -   A 10 MHz reference to provide a single frequency reference for all
-    devices.
+    devices (in some devices, other reference frequencies than 10 MHz are
+    also supported).
 -   A pulse-per-second (PPS) to synchronize the sample time across
     devices.
 
diff --git a/host/docs/usrp_n3xx.dox b/host/docs/usrp_n3xx.dox
index 21b156296..4524a2e03 100644
--- a/host/docs/usrp_n3xx.dox
+++ b/host/docs/usrp_n3xx.dox
@@ -671,6 +671,28 @@ will look like this:
 
 \section n3xx_synchronization Clock/Time Synchronization
 
+\subsection n3xx_synchronization_overview Overview
+
+To choose a source for clock (frequency) and PPS (time), use the `clock_source`
+and `time_source` device arguments just like with any other USRP (see also
+\ref page_sync). The following combinations are supported:
+
+`clock_source`  | `time_source`  | Notes
+----------------|----------------|---------------------------------------------
+`internal`      | `internal`     | Default value
+`external`      | `internal`     | The PPS will be generated from the reference signal, but this does not allow time synchronization between devices.
+`external`      | `external`     | The device assumes that the external reference clock and PPS are synchronized.
+`gpsdo`         | `gpsdo`        | This will work even without GPS reception (see below).
+
+The combination of `clock_source=external,time_source=gpsdo` is not available
+out of the box, but can be enabled by patching the MPM source code (n3xx.py).
+This is considered an advanced and unsupported use case. Read the appropriate
+source code for a description of drawbacks. Using this mode will cause unreliable
+phase alignment.
+
+See the following sections for more details on the individual synchronization
+options.
+
 \subsection n3xx_synchronization_internal Internal references
 
 The N3xx series has an onboard GPSDO as well as a 25 MHz reference oscillator,
diff --git a/mpm/python/usrp_mpm/periph_manager/n3xx.py b/mpm/python/usrp_mpm/periph_manager/n3xx.py
index ddb40d0d4..1da1f1e5d 100644
--- a/mpm/python/usrp_mpm/periph_manager/n3xx.py
+++ b/mpm/python/usrp_mpm/periph_manager/n3xx.py
@@ -166,13 +166,20 @@ class n3xx(ZynqComponents, PeriphManagerBase):
     #########################################################################
     # Others properties
     #########################################################################
-     # All valid sync_sources for N3xx in the form of (clock_source, time_source)
+    # All valid sync_sources for N3xx in the form of (clock_source, time_source)
+    # When changing this list, also update usrp_n3xx.dox (Section "Clock/Time
+    # Synchronization").
     valid_sync_sources = {
         ('internal', 'internal'),
         ('internal', 'sfp0'),
         ('external', 'external'),
         ('external', 'internal'),
         ('gpsdo', 'gpsdo'),
+        # To enable the external reference and GPSDO PPS combination, uncomment
+        # the following line. Note that using this combination will cause loss
+        # of phase alignment between devices.  See also comments in
+        # n3xx_clocking.v ("PPS Capture and Generation").
+        # ('external', 'gpsdo'),
     }
     @classmethod
     def generate_device_info(cls, eeprom_md, mboard_info, dboard_infos):