diff options
Diffstat (limited to 'host/include')
| -rw-r--r-- | host/include/uhd/usrp/multi_usrp.hpp | 109 |
1 files changed, 95 insertions, 14 deletions
diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp index 73fb58332..cdab59da0 100644 --- a/host/include/uhd/usrp/multi_usrp.hpp +++ b/host/include/uhd/usrp/multi_usrp.hpp @@ -342,15 +342,52 @@ public: */ virtual void set_clock_config(const clock_config_t &clock_config, size_t mboard = ALL_MBOARDS) = 0; - /*! - * Set the time source for the usrp device. - * This sets the method of time synchronization, - * typically a pulse per second or an encoded time. - * Typical options for source: external, MIMO. + /*! Set the time source for the USRP device + * + * This sets the method of time synchronization, typically a pulse per + * second signal. In order to time-align multiple USRPs, it is necessary to + * connect all of them to a common reference and provide them with the same + * time source. + * Typical values for \p source are 'internal', 'external'. Refer to the + * specific device manual for a full list of options. + * + * If the value for for \p source is not available for this device, it will + * throw an exception. Calling get_time_sources() will return a valid list + * of options for this method. + * + * Side effects: Some devices only support certain combinations of time and + * clock source. It is possible that the underlying device implementation + * will change the clock source when the time source changes and vice versa. + * Reading back the current values of clock and time source using + * get_clock_source() and get_time_source() is the only certain way of + * knowing which clock and time source are currently selected. + * + * This function does not force a re-initialization of the underlying + * hardware when the value does not change. Consider the following snippet: + * ~~~{.cpp} + * auto usrp = uhd::usrp::multi_usrp::make(device_args); + * // This may or may not cause the hardware to reconfigure, depending on + * // the default state of the device + * usrp->set_time_source("internal"); + * // Now, the time source is definitely set to "internal"! + * // The next call probably won't do anything but will return immediately, + * // because the time source was already set to "internal" + * usrp->set_time_source("internal"); + * // The time source is still guaranteed to be "internal" at this point + * ~~~ + * + * See also: + * - set_clock_source() + * - set_sync_source() + * * \param source a string representing the time source * \param mboard which motherboard to set the config + * \throws uhd::value_error if \p source is an invalid option */ - virtual void set_time_source(const std::string &source, const size_t mboard = ALL_MBOARDS) = 0; + virtual void set_time_source( + const std::string &source, + const size_t mboard = ALL_MBOARDS + ) = 0; /*! * Get the currently set time source. @@ -366,14 +403,52 @@ public: */ virtual std::vector<std::string> get_time_sources(const size_t mboard) = 0; - /*! - * Set the clock source for the usrp device. - * This sets the source for a 10 MHz reference clock. - * Typical options for source: internal, external, MIMO. - * \param source a string representing the clock source + /*! Set the clock source for the USRP device + * + * This sets the source of the frequency reference, typically a 10 MHz + * signal. In order to frequency-align multiple USRPs, it is necessary to + * connect all of them to a common reference and provide them with the same + * clock source. + * Typical values for \p source are 'internal', 'external'. Refer to the + * specific device manual for a full list of options. + * + * If the value for for \p source is not available for this device, it will + * throw an exception. Calling get_clock_sources() will return a valid list + * of options for this method. + * + * Side effects: Some devices only support certain combinations of time and + * clock source. It is possible that the underlying device implementation + * will change the time source when the clock source changes and vice versa. + * Reading back the current values of clock and time source using + * get_clock_source() and get_time_source() is the only certain way of + * knowing which clock and time source are currently selected. + * + * This function does not force a re-initialization of the underlying + * hardware when the value does not change. Consider the following snippet: + * ~~~{.cpp} + * auto usrp = uhd::usrp::multi_usrp::make(device_args); + * // This may or may not cause the hardware to reconfigure, depending on + * // the default state of the device + * usrp->set_clock_source("internal"); + * // Now, the clock source is definitely set to "internal"! + * // The next call probably won't do anything but will return immediately, + * // because the clock source was already set to "internal" + * usrp->set_clock_source("internal"); + * // The clock source is still guaranteed to be "internal" at this point + * ~~~ + * + * See also: + * - set_time_source() + * - set_sync_source() + * + * \param source a string representing the time source * \param mboard which motherboard to set the config + * \throws uhd::value_error if \p source is an invalid option */ - virtual void set_clock_source(const std::string &source, const size_t mboard = ALL_MBOARDS) = 0; + virtual void set_clock_source( + const std::string &source, + const size_t mboard = ALL_MBOARDS + ) = 0; /*! * Get the currently set clock source. @@ -414,12 +489,18 @@ public: * Example: * ~~~{.cpp} * auto usrp = uhd::usrp::multi_usrp::make(""); - * usrp->set_sync_source(device_addr_t("clock_source=external,time_source=external")); + * usrp->set_sync_source( + * device_addr_t("clock_source=external,time_source=external")); * ~~~ * + * This function does not force a re-initialization of the underlying + * hardware when the value does not change. See also set_time_source() and + * set_clock_source() for more details. + * * \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 + * \throws uhd::value_error if the sources don't actually exist or if the + * combination of clock and time source is invalid. */ virtual void set_sync_source( const device_addr_t& sync_source, |