docs: Clarify docs around setting clock source and side-effects

2 files changed, 43 insertions, 4 deletions

diff --git a/host/include/uhd/rfnoc/mb_controller.hpp b/host/include/uhd/rfnoc/mb_controller.hpp
index 5969764ce..483603c8c 100644
--- a/host/include/uhd/rfnoc/mb_controller.hpp
+++ b/host/include/uhd/rfnoc/mb_controller.hpp
@@ -134,6 +134,11 @@ public:
 
         /*! Set the time at next PPS from a time spec
          *
+         * \b Note: When changing clock sources, a previously set time will
+         * most likely be lost. It is recommended to set the time after
+         * changing the clock source. Otherwise, an unexpected time may line
+         * up with future PPS edges.
+         *
          * This will convert \p time into a tick count value and use that to
          * call set_ticks_next_pps().
          */
@@ -348,8 +353,8 @@ public:
      *
      * Example:
      * ~~~{.cpp}
-     * auto usrp = uhd::usrp::multi_usrp::make("");
-     * usrp->set_sync_source(
+     * auto graph = uhd::rfnoc::rfnoc_graph::make("");
+     * graph->get_mb_controller(0)->set_sync_source(
      *     device_addr_t("clock_source=external,time_source=external"));
      * ~~~
      *
@@ -357,6 +362,14 @@ public:
      * hardware when the value does not change. See also set_time_source() and
      * set_clock_source() for more details.
      *
+     * \b Note: Reconfiguring the sync source may affect the clocking
+     * within the FPGAs of USRPs, and affect timekeeping as well as proper
+     * functioning of blocks that depend on these clocks. It is therefore
+     * strongly recommended to configure clock and time source before doing
+     * anything else. In particular, setting the device time should be done
+     * after calling this, and there should be no ongoing streaming operation
+     * while reconfiguring the sync source.
+     *
      * \param sync_source A dictionary representing the various source settings.
      * \throws uhd::value_error if the sources don't actually exist or if the
      *         combination of clock and time source is invalid.
diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index 1e06cf80b..090714db7 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -277,17 +277,22 @@ public:
      * 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 edge, the time
+     * \b 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
+     * \b 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 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).
      *
+     * \b Note: When changing clock sources, a previously set time will most
+     * likely be lost. It is recommended to set the time after changing the
+     * clock source. Otherwise, an unexpected time may line up with future PPS
+     * edges.
+     *
      * \param time_spec the time to latch into the usrp device
      * \param mboard the motherboard index 0 to M-1
      */
@@ -307,6 +312,11 @@ public:
      * - Step1: wait for the last pps time to transition to catch the edge
      * - Step2: set the time at the next pps (synchronous for all boards)
      *
+     * \b Note: When changing clock sources, a previously set time will most
+     * likely be lost. It is recommended to set the time after changing the
+     * clock source. Otherwise, an unexpected time may line up with future PPS
+     * edges.
+     *
      * \param time_spec the time to latch at the next pps after catching the edge
      */
     virtual void set_time_unknown_pps(const time_spec_t& time_spec) = 0;
@@ -447,6 +457,14 @@ public:
      * // The clock source is still guaranteed to be "internal" at this point
      * ~~~
      *
+     * \b Note: Reconfiguring the clock source will affect the clocking
+     * within the FPGAs of USRPs, and affect timekeeping as well as proper
+     * functioning of blocks that depend on these clocks. It is therefore
+     * strongly recommended to configure clock and time source before doing
+     * anything else. In particular, setting the device time should be done
+     * after calling this, and there should be no ongoing streaming operation
+     * while reconfiguring the clock/time source.
+     *
      * See also:
      * - set_time_source()
      * - set_sync_source()
@@ -503,6 +521,14 @@ public:
      * hardware when the value does not change. See also set_time_source() and
      * set_clock_source() for more details.
      *
+     * \b Note: Reconfiguring the sync source may affect the clocking
+     * within the FPGAs of USRPs, and affect timekeeping as well as proper
+     * functioning of blocks that depend on these clocks. It is therefore
+     * strongly recommended to configure clock and time source before doing
+     * anything else. In particular, setting the device time should be done
+     * after calling this, and there should be no ongoing streaming operation
+     * while reconfiguring the sync source.
+     *
      * \param sync_source A dictionary representing the various source settings.
      * \param mboard which motherboard to set the config
      * \throws uhd::value_error if the sources don't actually exist or if the