From f6b0e4a81b077b9a1e1cad267b74bd1101972b63 Mon Sep 17 00:00:00 2001 From: Martin Braun Date: Tue, 19 Mar 2024 17:21:48 +0100 Subject: docs: Clarify docs around setting clock source and side-effects --- host/include/uhd/rfnoc/mb_controller.hpp | 17 +++++++++++++++-- host/include/uhd/usrp/multi_usrp.hpp | 30 ++++++++++++++++++++++++++++-- 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 @@ -133,6 +133,11 @@ public: virtual void set_ticks_now(const uint64_t ticks) = 0; /*! 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 -- cgit v1.2.3-59-g8ed1b