uhd: Update all headers for setters on multi_usrp re coerce/throw

Our APIs are not consistent when it comes to handling invalid settings.
Some setting (like antenna, LO name, ...) will trigger an exception when
invalid. Other settings (gain, frequency, clock rate) will get coerced
to a valid value.

This behaviour does make sense for the most part (it is more intuitive
that 81 dB gets coerced to 80 dB if that's the maximum, but coercing an
invalid antenna value like "RX1" has no clear alternative). And in any
case, this is the behaviour that UHD has always had.

In this commit, all Doxygen headers in multi_usrp are updated to exactly
describe their behaviour (coerce or throw).

1 files changed, 144 insertions, 50 deletions

diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index e00fe7553..08370471a 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -377,7 +377,7 @@ public:
      *
      * \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
+     * \throws if \p source is an invalid option
      */
     virtual void set_time_source(
         const std::string& source, const size_t mboard = ALL_MBOARDS) = 0;
@@ -436,7 +436,7 @@ public:
      *
      * \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
+     * \throws if \p source is an invalid option
      */
     virtual void set_clock_source(
         const std::string& source, const size_t mboard = ALL_MBOARDS) = 0;
@@ -508,24 +508,36 @@ public:
      */
     virtual std::vector<device_addr_t> get_sync_sources(const size_t mboard) = 0;
 
-    /*!
-     * Send the clock source to an output connector.
+    /*! Send the clock signal to an output connector.
+     *
      * This call is only applicable on devices with reference outputs.
      * By default, the reference output will be enabled for ease of use.
      * This call may be used to enable or disable the output.
+     *
+     * If the device does not support this operation, calling this method will
+     * throw a uhd::runtime_error.
+     *
      * \param enb true to output the clock source.
      * \param mboard which motherboard to set
+     * \throws if the device is incapable of exporting the
+     *         clock signal.
      */
     virtual void set_clock_source_out(
         const bool enb, const size_t mboard = ALL_MBOARDS) = 0;
 
-    /*!
-     * Send the time source to an output connector.
+    /*! Send the time signal (PPS) to an output connector.
+     *
      * This call is only applicable on devices with PPS outputs.
      * By default, the PPS output will be enabled for ease of use.
      * This call may be used to enable or disable the output.
+     *
+     * If the device does not support this operation, calling this method will
+     * throw a uhd::runtime_error.
+     *
      * \param enb true to output the time source.
      * \param mboard which motherboard to set
+     * \throws if the device is incapable of exporting the
+     *         clock signal.
      */
     virtual void set_time_source_out(
         const bool enb, const size_t mboard = ALL_MBOARDS) = 0;
@@ -611,13 +623,15 @@ public:
     /*******************************************************************
      * RX methods
      ******************************************************************/
-    /*!
-     * Set the RX frontend specification:
+    /*! Set the RX frontend specification
+     *
      * The subdev spec maps a physical part of a daughter-board to a channel number.
      * Set the subdev spec before calling into any methods with a channel number.
      * The subdev spec must be the same size across all motherboards.
+     *
      * \param spec the new frontend specification
      * \param mboard the motherboard index 0 to M-1
+     * \throws if an invalid spec is provided.
      */
     virtual void set_rx_subdev_spec(
         const uhd::usrp::subdev_spec_t& spec, size_t mboard = ALL_MBOARDS) = 0;
@@ -643,8 +657,12 @@ public:
      */
     virtual std::string get_rx_subdev_name(size_t chan = 0) = 0;
 
-    /*!
-     * Set the RX sample rate.
+    /*! Set the RX sample rate
+     *
+     * This function will coerce the requested rate to a rate that the device
+     * can handle. A warning may be logged during coercion. Call get_rx_rate()
+     * to identify the actual rate.
+     *
      * \param rate the rate in Sps
      * \param chan the channel index 0 to N-1
      */
@@ -675,8 +693,12 @@ public:
      */
     virtual meta_range_t get_rx_rates(size_t chan = 0) = 0;
 
-    /*!
-     * Set the RX center frequency.
+    /*! Set the RX center frequency.
+     *
+     * If the requested frequency is outside of the valid frequency range, it
+     * will be coerced to the nearest valid frequency. Check the return value or
+     * call get_rx_freq() to get the actual center frequency.
+     *
      * \param tune_request tune request instructions
      * \param chan the channel index 0 to N-1
      * \return a tune result object
@@ -731,12 +753,19 @@ public:
      *
      * For USRPs that support selectable LO sources, this function allows
      * switching between them. Typical options for source: internal, external.
+     * Call get_rx_lo_sources() to enumerate the list of valid options. Calling
+     * this function with an invalid argument will cause an exception to be
+     * thrown.
      *
      * \param src a string representing the LO source
      * \param name the name of the LO stage to update. If the wildcard value
      *             ALL_LOS is used, the setting will be applied to all LOs on
-     *             this channel.
+     *             this channel. Call get_tx_lo_names() for a list of valid
+     *             argument values.
      * \param chan the channel index 0 to N-1
+     * \throws uhd::not_implemented_error if the device cannot set the LO source
+     * \throws uhd::value_error if the device can set the LO source, but the LO
+     *                          name is invalid.
      */
     virtual void set_rx_lo_source(
         const std::string& src, const std::string& name = ALL_LOS, size_t chan = 0) = 0;
@@ -752,12 +781,13 @@ public:
     virtual const std::string get_rx_lo_source(
         const std::string& name = ALL_LOS, size_t chan = 0) = 0;
 
-    /*!  Get a list of possible LO sources.
+    /*! Get a list of possible LO sources.
      *
      * Channels which do not have controllable LO sources will return
      * "internal". Typical values are "internal" and "external", although the
-     * TwinRX has more options, such as "companion". These options are device-
-     * specific.
+     * TwinRX, for example, has more options, such as "companion". These options
+     * are device-specific, so consult the individual device manual pages for
+     * details.
      *
      * \param name the name of the LO stage to query
      * \param chan the channel index 0 to N-1
@@ -809,6 +839,7 @@ public:
      * \param name the name of the LO stage to update
      * \param chan the channel index 0 to N-1
      * \return a coerced LO frequency
+     * \throws if the LO name is not valid.
      */
     virtual double set_rx_lo_freq(
         double freq, const std::string& name, size_t chan = 0) = 0;
@@ -855,11 +886,15 @@ public:
      *
      * For USRPs that support selectable LO sources, this function allows
      * switching between them. Typical options for source: internal, external.
+     * Call get_tx_lo_sources() to enumerate the list of valid options. Calling
+     * this function with an invalid argument will cause an exception to be
+     * thrown.
      *
      * \param src a string representing the LO source
      * \param name the name of the LO stage to update. If the wildcard value
      *             ALL_LOS is used, the setting will be applied to all LOs on
-     *             this channel.
+     *             this channel. Call get_tx_lo_names() for a list of valid
+     *             argument values.
      * \param chan the channel index 0 to N-1
      */
     virtual void set_tx_lo_source(const std::string& src,
@@ -933,6 +968,7 @@ public:
      * \param name the name of the LO stage to update
      * \param chan the channel index 0 to N-1
      * \return a coerced LO frequency
+     * \throws if the LO name is not valid.
      */
     virtual double set_tx_lo_freq(
         const double freq, const std::string& name, const size_t chan = 0) = 0;
@@ -964,9 +1000,15 @@ public:
     /**************************************************************************
      * Gain controls
      *************************************************************************/
-    /*!
-     * Set the RX gain value for the specified gain element.
+    /*! Set the RX gain value for the specified gain element.
+     *
+     * If the requested gain value is outside the valid range, it will be
+     * coerced to a valid gain value. Call get_rx_gain_range() to return the
+     * currently valid gain range, and call get_rx_gain() after calling this
+     * function to return the actual current gain value after coercion.
+     *
      * For an empty name, distribute across all gain elements.
+     *
      * \param gain the gain in dB
      * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
@@ -987,10 +1029,13 @@ public:
      */
     virtual std::vector<std::string> get_rx_gain_profile_names(const size_t chan = 0) = 0;
 
-    /*!
-     * Set the RX gain profile.
+    /*! Set the RX gain profile.
+     *
+     * Call get_rx_gain_profile_names() for valid names.
+     *
      * \param profile the profile string option
      * \param chan the channel index 0 to N-1
+     * \throws if the requested gain profile name is not valid.
      */
     virtual void set_rx_gain_profile(
         const std::string& profile, const size_t chan = 0) = 0;
@@ -1008,12 +1053,13 @@ public:
         return this->set_rx_gain(gain, ALL_GAINS, chan);
     }
 
-    /*!
-     * Set the normalized RX gain value.
+    /*! Set the normalized RX gain value.
      *
      * The normalized gain is a value in [0, 1], where 0 is the
      * smallest gain value available, and 1 is the largest, independent
      * of the device. In between, gains are linearly interpolated.
+     * If the requested normalized gain is outside of this range, an exception
+     * is thrown.
      *
      * Check the individual device manual for notes on the gain range.
      *
@@ -1026,13 +1072,22 @@ public:
      */
     virtual void set_normalized_rx_gain(double gain, size_t chan = 0) = 0;
 
-    /*!
-     * Enable or disable the RX AGC module.
+    /*! Enable or disable the RX AGC module.
+     *
+     * Only some devices implement an AGC, including all USRPs from the B200
+     * series, the E310, and the E320.
+     * When called on a device that does not implement an AGC, an exception will
+     * be thrown.
+     *
      * Once this module is enabled manual gain settings will be ignored.
-     * The AGC will start in a default configuration which should be good for most use
-     * cases. Device specific configuration parameters can be found in the property tree.
+     * The AGC will start in a default configuration which should be good for
+     * most use cases. Device specific configuration parameters can be found in
+     * the property tree.
+     *
      * \param enable Enable or Disable the AGC
      * \param chan the channel index 0 to N-1
+     * \throws if the underlying device does not
+     *         implement an AGC.
      */
     virtual void set_rx_agc(bool enable, size_t chan = 0) = 0;
 
@@ -1086,10 +1141,13 @@ public:
      */
     virtual std::vector<std::string> get_rx_gain_names(size_t chan = 0) = 0;
 
-    /*!
-     * Select the RX antenna on the frontend.
-     * \param ant the antenna name
+    /*! Select the RX antenna on the frontend.
+     *
+     * \param ant the antenna name. If an invalid name is provided, an exception
+     *            is thrown. Call get_rx_antennas() to return a valid list of
+     *            antenna names.
      * \param chan the channel index 0 to N-1
+     * \throws if an invalid antenna name is provided
      */
     virtual void set_rx_antenna(const std::string& ant, size_t chan = 0) = 0;
 
@@ -1107,15 +1165,19 @@ public:
      */
     virtual std::vector<std::string> get_rx_antennas(size_t chan = 0) = 0;
 
-    /*!
-     * Set the RX bandwidth on the frontend.
+    /*! Set the RX bandwidth on the frontend.
+     *
+     * If a bandwidth is provided that is outside the valid range, it is coerced
+     * to the nearest valid value. Call get_rx_bandwidth_range() to identify the
+     * valid range of bandwidth values.
+     *
      * \param bandwidth the bandwidth in Hz
      * \param chan the channel index 0 to N-1
      */
     virtual void set_rx_bandwidth(double bandwidth, size_t chan = 0) = 0;
 
-    /*!
-     * Get the RX bandwidth on the frontend.
+    /*! Get the RX bandwidth on the frontend
+     *
      * \param chan the channel index 0 to N-1
      * \return the bandwidth in Hz
      */
@@ -1267,13 +1329,14 @@ public:
     /*******************************************************************
      * TX methods
      ******************************************************************/
-    /*!
-     * Set the TX frontend specification:
+    /*! Set the TX frontend specification:
+     *
      * The subdev spec maps a physical part of a daughter-board to a channel number.
      * Set the subdev spec before calling into any methods with a channel number.
      * The subdev spec must be the same size across all motherboards.
      * \param spec the new frontend specification
      * \param mboard the motherboard index 0 to M-1
+     * \throws if an invalid spec is provided.
      */
     virtual void set_tx_subdev_spec(
         const uhd::usrp::subdev_spec_t& spec, size_t mboard = ALL_MBOARDS) = 0;
@@ -1299,8 +1362,12 @@ public:
      */
     virtual std::string get_tx_subdev_name(size_t chan = 0) = 0;
 
-    /*!
-     * Set the TX sample rate.
+    /*! Set the TX sample rate.
+     *
+     * This function will coerce the requested rate to a rate that the device
+     * can handle. A warning may be logged during coercion. Call get_rx_rate()
+     * to identify the actual rate.
+     *
      * \param rate the rate in Sps
      * \param chan the channel index 0 to N-1
      */
@@ -1320,8 +1387,12 @@ public:
      */
     virtual meta_range_t get_tx_rates(size_t chan = 0) = 0;
 
-    /*!
-     * Set the TX center frequency.
+    /*! Set the TX center frequency.
+     *
+     * If the requested frequency is outside of the valid frequency range, it
+     * will be coerced to the nearest valid frequency. Check the return value or
+     * call get_tx_freq() to get the actual center frequency.
+     *
      * \param tune_request tune request instructions
      * \param chan the channel index 0 to N-1
      * \return a tune result object
@@ -1354,9 +1425,15 @@ public:
      */
     virtual freq_range_t get_fe_tx_freq_range(size_t chan = 0) = 0;
 
-    /*!
-     * Set the TX gain value for the specified gain element.
+    /*! Set the TX gain value for the specified gain element.
+     *
+     * If the requested gain value is outside the valid range, it will be
+     * coerced to a valid gain value. Call get_rx_gain_range() to return the
+     * currently valid gain range, and call get_rx_gain() after calling this
+     * function to return the actual current gain value after coercion.
+     *
      * For an empty name, distribute across all gain elements.
+     *
      * \param gain the gain in dB
      * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
@@ -1377,10 +1454,13 @@ public:
      */
     virtual std::vector<std::string> get_tx_gain_profile_names(const size_t chan = 0) = 0;
 
-    /*!
-     * Set the TX gain profile.
-     * \param profile the profile string option
+    /*! Set the TX gain profile.
+     *
+     * Call get_tx_gain_profile_names() for valid names.
+     *
+     * \param profile the profile string option.
      * \param chan the channel index 0 to N-1
+     * \throws if the requested gain profile name is not valid.
      */
     virtual void set_tx_gain_profile(
         const std::string& profile, const size_t chan = 0) = 0;
@@ -1403,6 +1483,8 @@ public:
      *
      * See set_normalized_rx_gain() for a discussion on normalized
      * gains.
+     * If the requested normalized gain is outside of this range, an exception
+     * is thrown.
      *
      * \param gain the normalized gain value
      * \param chan the channel index 0 to N-1
@@ -1525,8 +1607,11 @@ public:
 
     /*!
      * Select the TX antenna on the frontend.
-     * \param ant the antenna name
+     * \param ant the antenna name. If an invalid name is provided, an exception
+     *            is thrown. Call get_tx_antennas() to return a valid list of
+     *            antenna names.
      * \param chan the channel index 0 to N-1
+     * \throws if an invalid antenna name is provided
      */
     virtual void set_tx_antenna(const std::string& ant, size_t chan = 0) = 0;
 
@@ -1544,8 +1629,12 @@ public:
      */
     virtual std::vector<std::string> get_tx_antennas(size_t chan = 0) = 0;
 
-    /*!
-     * Set the TX bandwidth on the frontend.
+    /*! Set the TX bandwidth on the frontend.
+     *
+     * If a bandwidth is provided that is outside the valid range, it is coerced
+     * to the nearest valid value. Call get_tx_bandwidth_range() to identify the
+     * valid range of bandwidth values.
+     *
      * \param bandwidth the bandwidth in Hz
      * \param chan the channel index 0 to N-1
      */
@@ -1625,8 +1714,8 @@ public:
      */
     virtual std::vector<std::string> get_gpio_banks(const size_t mboard) = 0;
 
-    /*!
-     * Set a GPIO attribute on a particular GPIO bank.
+    /*! Set a GPIO attribute on a particular GPIO bank.
+     *
      * Possible attribute names:
      *  - CTRL - 1 for ATR mode 0 for GPIO mode
      *  - DDR - 1 for output 0 for input
@@ -1640,6 +1729,7 @@ public:
      * \param value the new value for this GPIO bank
      * \param mask the bit mask to effect which pins are changed
      * \param mboard the motherboard index 0 to M-1
+     * \throws an exception if either bank or attr are invalid values.
      */
     virtual void set_gpio_attr(const std::string& bank,
         const std::string& attr,
@@ -1715,6 +1805,10 @@ public:
      *        calling get_gpio_src_banks().
      * \param src a list of strings specifying the source of each pin in a GPIO bank
      * \param mboard the motherboard index 0 to M-1
+     * \throws uhd::key_error if the bank does not exist
+     * \throws uhd::value_error if the source does not exist
+     * \throws uhd::not_implemented_error if the current motherboard does not
+     *         support this feature
      */
     virtual void set_gpio_src(const std::string& bank,
         const std::vector<std::string>& src,