fixup! docs: Improve documentation on timekeepers

4 files changed, 30 insertions, 41 deletions

diff --git a/host/docs/timed_cmd.dox b/host/docs/timed_cmd.dox
index 27c783d09..d20918a21 100644
--- a/host/docs/timed_cmd.dox
+++ b/host/docs/timed_cmd.dox
@@ -110,10 +110,9 @@ that is in the past) are executed immediately.
 In RFNoC devices, each RFNoC block has its own command queue. Older devices have
 fewer (or only one command queue).
 
-When the command queue is full, UHD will attempt to hold on to the command in a
-software queue until the USRP has signaled that there is space for more commands.
-When this happens, it is possible that timed commands reach the FPGA after their
-desired execution time.
+When the command queue is full, UHD will block until the USRP has signaled that
+there is space for more commands. That can cause timed commands to reach the FPGA
+after their desired execution time.
 
 \subsection timedcmds_gen_cmds_what Which commands can be timed?
 
diff --git a/host/docs/usrp_x4xx.dox b/host/docs/usrp_x4xx.dox
index 59be4db89..5033b3c2f 100644
--- a/host/docs/usrp_x4xx.dox
+++ b/host/docs/usrp_x4xx.dox
@@ -983,7 +983,10 @@ with the following restrictions:
     lockstep. By default, the time for both daughterboards is thus synchronized.
   - When using multi_usrp API calls, e.g. uhd::usrp::multi_usrp::set_time_now(),
     UHD will set the time on all available timekeepers. However, this means that
-    it is possible to desynchronize the time between daughterboards.
+    it is possible to desynchronize the time between daughterboards.  It is
+    recommended to use uhd::usrp::multi_usrp::set_time_next_pps() or
+    uhd::usrp::multi_usrp::set_time_unknown_pps() to keep all timekeepers
+    synchronized.
   - When using the motherboard controller directly, attention must be paid to
     not only access timekeeper zero
 
diff --git a/host/include/uhd/rfnoc/mb_controller.hpp b/host/include/uhd/rfnoc/mb_controller.hpp
index 6c64d0da1..701460b65 100644
--- a/host/include/uhd/rfnoc/mb_controller.hpp
+++ b/host/include/uhd/rfnoc/mb_controller.hpp
@@ -186,16 +186,16 @@ public:
     //! Returns the number of timekeepers, which equals the number of timebases
     // on this device.
     //
-    // Most USRPs have one timekeeper. Custom FPGA images can implement multiple
-    // timekeepers for various purposes. The USRP X440 has a minimum of two
-    // timekeepers, one for each daughterboard.
+    // Most USRPs have one timekeeper. Refer to the manual for your device
+    // family for potential exceptions to this behavior. Custom FPGA images
+    // may also implement multiple timekeepers for various purposes.
     size_t get_num_timekeepers() const;
 
     //! Return a reference to the \p tk_idx-th timekeeper on this motherboard
     //
     // For most USRPs, timekeeper index 0 is used to access the main timekeeper.
-    // On the USRP X440, timekeeper index 0 used to keep time for daughterboard
-    // 0, and timekeeper index 1 is used to keep time for daughterboard 1.
+    // When using a USRP with multiple timekeepers, refer to the relevant device
+    // family manual for more information on timekeeper mapping and enumeration.
     //
     // Custom FPGA images can implement multiple timekeepers.
     //
diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index 05575c44e..1e06cf80b 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -258,21 +258,9 @@ public:
 
     /*! Sets the time registers on the USRP immediately.
      *
-     * This will set the tick count on the remote device's timekeeper as soon
-     * as possible. Note that there is some amount of lag between executing
-     * this call and when the device's time will be updated, e.g., due to
-     * network latency. This call is therefore unsuitable for setting the time
-     * on multiple devices synchronously.  Please use the set_time_next_pps() or
-     * set_time_unknown_pps() calls with a PPS signal for this use case.
-     *
-     * The one exception is when using a pair of USRP2/N200/N210 with a MIMO
-     * cable: If only one MIMO master is present in your configuration,
-     * set_time_now is safe to use because the slave's time automatically
-     * follows the master's time.
-     *
-     * On RFNoC devices, this will call
-     * uhd::rfnoc::mb_controller::timekeeper::set_time_now() on all available timekeepers
-     * (usually there is one timekeeper per device, with the exception of the USRP X440).
+     * This will set the tick count on the timekeepers of all devices as soon
+     * as possible.  It is done serially for multiple timekeepers, so times
+     * across multiple timekeepers will not be synchronized.
      *
      * \param time_spec the time to latch into the usrp device
      * \param mboard the motherboard index 0 to M-1
@@ -280,26 +268,25 @@ public:
     virtual void set_time_now(
         const time_spec_t& time_spec, size_t mboard = ALL_MBOARDS) = 0;
 
-    /*! Set the time registers on the USRP at the next PPS tick.
+    /*! Set the time registers on the USRP at the next PPS rising edge.
      *
-     * The values will not be latched in until the pulse occurs.
-     * It is recommended that the user sleep(1) after calling to ensure
-     * that the time registers will be in a known state prior to use.
+     * This will set the tick count on the timekeepers of all devices on
+     * the next rising edge of the PPS trigger signal.  It is important
+     * to note that this means the time may not be set for up to 1 second
+     * after this call is made, so it is recommended to wait for 1 second
+     * after this call before making any calls that depend on the time to
+     * ensure that the time registers will be in a known state prior to use.
      *
-     * Note: Because this call sets the time on the "next" pps,
-     * the seconds in the time spec should be current seconds + 1.
+     * Note: Because this call sets the time on the next PPS edge, the time
+     * spec supplied should correspond to the next pulse (i.e. current
+     * time + 1 second).
      *
      * Note: Make sure to not call this shortly before the next PPS edge. This
-     * should be called with plenty of time before the next PPS edge (at least
-     * 50 ms) to ensure that all devices will execute this command on the same
-     * PPS edge. If not, devices could be unsynchronized in time by exactly one
-     * second. If in doubt, use set_time_unknown_pps() which will take care of
-     * this issue (but will also take longer to execute).
-     *
-     * On RFNoC devices, this will call
-     * uhd::rfnoc::mb_controller::timekeeper::set_time_next_pps() on all available
-     * timekeepers (usually there is one timekeeper per device, with the exception of the
-     * USRP X440).
+     * should be called with plenty of time before the next PPS edge to ensure
+     * that all timekeepers on all devices will execute this command on the
+     * same PPS edge. If not, timekeepers could be unsynchronized in time by
+     * exactly one second. If in doubt, use set_time_unknown_pps() which will
+     * take care of this issue (but will also take longer to execute).
      *
      * \param time_spec the time to latch into the usrp device
      * \param mboard the motherboard index 0 to M-1