uhd: Add reference power level API to multi_usrp and radio_control

This adds the following API calls:

- multi_usrp::has_{rx,tx}_power_reference()
- multi_usrp::set_{rx,tx}_power_reference()
- multi_usrp::get_{rx,tx}_power_reference()
- radio_control::has_{rx,tx}_power_reference()
- radio_control::set_{rx,tx}_power_reference()
- radio_control::get_{rx,tx}_power_reference()

It also adds a manual page explaining the philosophy of the API.

Note that this does not actually add this feature to any device
implementation. Calling the new API calls will thus result in
`uhd::not_implemented_error` exceptions being thrown. This commit is to
lock down the API and ABI.

2 files changed, 205 insertions, 0 deletions

diff --git a/host/include/uhd/rfnoc/radio_control.hpp b/host/include/uhd/rfnoc/radio_control.hpp
index 9d343cdac..96c3e1bbe 100644
--- a/host/include/uhd/rfnoc/radio_control.hpp
+++ b/host/include/uhd/rfnoc/radio_control.hpp
@@ -189,6 +189,56 @@ public:
     virtual double set_tx_gain(
         const double gain, const std::string& name, const size_t chan) = 0;
 
+    /*! Return true if this channel has a reference power API enabled
+     *
+     * Many devices either don't have a built-in reference power API, or they
+     * require calibration data for it to work. This means that it is not clear,
+     * even when the device type is known, if a device supports setting a power
+     * reference level. Use this method to query the availability of
+     * set_tx_power_reference() and get_tx_power_reference(), which will throw
+     * a uhd::not_implemented_error or uhd::runtime_error if they cannot be used.
+     *
+     * See \ref page_power for more information, or query the specific device's
+     * manual page to see if a power API is available, and how to enable it.
+     *
+     * \param chan The channel for which this feature is queried
+     *
+     * \returns true if this channel has a TX power API available
+     */
+    virtual bool has_tx_power_reference(const size_t chan = 0) = 0;
+
+    /*! Set the reference TX power level for a given channel
+     *
+     * Note: This functionality is not supported for most devices, and will
+     * cause a uhd::not_implemented_error exception to be thrown on devices that
+     * do not have this functionality.
+     *
+     * For more information on how to use this API, see \ref page_power.
+     *
+     * \param power_dbm The reference power level in dBm
+     * \param chan The channel for which this setting applies
+     *
+     * \throws uhd::not_implemented_error if this functionality does not exist
+     *         for this device
+     */
+    virtual void set_tx_power_reference(
+        const double power_dbm, const size_t chan = 0) = 0;
+
+    /*! Return the actual reference TX power level.
+     *
+     * Note: This functionality is not supported for most devices, and will
+     * cause a uhd::not_implemented_error exception to be thrown on devices that
+     * do not have this functionality.
+     *
+     * For more information on how to use this API, see \ref page_power.
+     *
+     * \param chan The channel for which this setting is queried
+     * \throws uhd::not_implemented_error if this functionality does not exist
+     *         for this device
+     */
+    virtual double get_tx_power_reference(const size_t chan = 0) = 0;
+
+
     /*! Return a list of valid RX gain names
      */
     virtual std::vector<std::string> get_rx_gain_names(const size_t chan) const = 0;
@@ -239,6 +289,55 @@ public:
      */
     virtual void set_rx_agc(const bool enable, const size_t chan) = 0;
 
+    /*! Return true if this channel has a reference power API enabled
+     *
+     * Many devices either don't have a built-in reference power API, or they
+     * require calibration data for it to work. This means that it is not clear,
+     * even when the device type is known, if a device supports setting a power
+     * reference level. Use this method to query the availability of
+     * set_rx_power_reference() and get_rx_power_reference(), which will throw
+     * a uhd::not_implemented_error or uhd::runtime_error if they cannot be used.
+     *
+     * See \ref page_power for more information, or query the specific device's
+     * manual page to see if a power API is available, and how to enable it.
+     *
+     * \param chan The channel for which this feature is queried
+     *
+     * \returns true if this channel has an RX power API available
+     */
+    virtual bool has_rx_power_reference(const size_t chan = 0) = 0;
+
+    /*! Set the reference RX power level for a given channel
+     *
+     * Note: This functionality is not supported for most devices, and will
+     * cause a uhd::not_implemented_error exception to be thrown on devices that
+     * do not have this functionality.
+     *
+     * For more information on how to use this API, see \ref page_power.
+     *
+     * \param power_dbm The reference power level in dBm
+     * \param chan The channel for which this setting applies
+     *
+     * \throws uhd::not_implemented_error if this functionality does not exist
+     *         for this device
+     */
+    virtual void set_rx_power_reference(
+        const double power_dbm, const size_t chan = 0) = 0;
+
+    /*! Return the actual reference RX power level.
+     *
+     * Note: This functionality is not supported for most devices, and will
+     * cause a uhd::not_implemented_error exception to be thrown on devices that
+     * do not have this functionality.
+     *
+     * For more information on how to use this API, see \ref page_power.
+     *
+     * \param chan The channel for which this setting is queried
+     * \throws uhd::not_implemented_error if this functionality does not exist
+     *         for this device
+     */
+    virtual double get_rx_power_reference(const size_t chan = 0) = 0;
+
     /*! Return a list of TX gain profiles for this radio
      */
     virtual std::vector<std::string> get_tx_gain_profile_names(
diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index 53e63361f..e177e7cf7 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -22,6 +22,7 @@
 #define UHD_USRP_MULTI_USRP_FILTER_API
 #define UHD_USRP_MULTI_USRP_LO_CONFIG_API
 #define UHD_USRP_MULTI_USRP_TX_LO_CONFIG_API
+#define UHD_USRP_MULTI_USRP_POWER_LEVEL
 
 #include <uhd/config.hpp>
 #include <uhd/device.hpp>
@@ -1176,6 +1177,59 @@ public:
     virtual void set_rx_iq_balance(
         const std::complex<double>& correction, size_t chan = ALL_CHANS) = 0;
 
+
+    /**************************************************************************
+     * Power level controls
+     *************************************************************************/
+    /*! Return true if this channel has a reference power API enabled
+     *
+     * Many devices either don't have a built-in reference power API, or they
+     * require calibration data for it to work. This means that it is not clear,
+     * even when the device type is known, if a device supports setting a power
+     * reference level. Use this method to query the availability of
+     * set_rx_power_reference() and get_rx_power_reference(), which will throw
+     * a uhd::not_implemented_error or uhd::runtime_error if they cannot be used.
+     *
+     * See \ref page_power for more information, or query the specific device's
+     * manual page to see if a power API is available, and how to enable it.
+     *
+     * \param chan The channel for which this feature is queried
+     *
+     * \returns true if this channel has an RX power API available
+     */
+    virtual bool has_rx_power_reference(const size_t chan = 0) = 0;
+
+    /*! Set the reference RX power level for a given channel
+     *
+     * Note: This functionality is not supported for most devices, and will
+     * cause a uhd::not_implemented_error exception to be thrown on devices that
+     * do not have this functionality.
+     *
+     * For more information on how to use this API, see \ref page_power.
+     *
+     * \param power_dbm The reference power level in dBm
+     * \param chan The channel for which this setting applies
+     *
+     * \throws uhd::not_implemented_error if this functionality does not exist
+     *         for this device
+     */
+    virtual void set_rx_power_reference(
+        const double power_dbm, const size_t chan = 0) = 0;
+
+    /*! Return the actual reference RX power level.
+     *
+     * Note: This functionality is not supported for most devices, and will
+     * cause a uhd::not_implemented_error exception to be thrown on devices that
+     * do not have this functionality.
+     *
+     * For more information on how to use this API, see \ref page_power.
+     *
+     * \param chan The channel for which this setting is queried
+     * \throws uhd::not_implemented_error if this functionality does not exist
+     *         for this device
+     */
+    virtual double get_rx_power_reference(const size_t chan = 0) = 0;
+
     /*******************************************************************
      * TX methods
      ******************************************************************/
@@ -1372,6 +1426,58 @@ public:
      */
     virtual std::vector<std::string> get_tx_gain_names(size_t chan = 0) = 0;
 
+    /**************************************************************************
+     * Power level controls
+     *************************************************************************/
+    /*! Return true if this channel has a reference power API enabled
+     *
+     * Many devices either don't have a built-in reference power API, or they
+     * require calibration data for it to work. This means that it is not clear,
+     * even when the device type is known, if a device supports setting a power
+     * reference level. Use this method to query the availability of
+     * set_tx_power_reference() and get_tx_power_reference(), which will throw
+     * a uhd::not_implemented_error or uhd::runtime_error if they cannot be used.
+     *
+     * See \ref page_power for more information, or query the specific device's
+     * manual page to see if a power API is available, and how to enable it.
+     *
+     * \param chan The channel for which this feature is queried
+     *
+     * \returns true if this channel has a TX power API available
+     */
+    virtual bool has_tx_power_reference(const size_t chan = 0) = 0;
+
+    /*! Set the reference TX power level for a given channel
+     *
+     * Note: This functionality is not supported for most devices, and will
+     * cause a uhd::not_implemented_error exception to be thrown on devices that
+     * do not have this functionality.
+     *
+     * For more information on how to use this API, see \ref page_power.
+     *
+     * \param power_dbm The reference power level in dBm
+     * \param chan The channel for which this setting applies
+     *
+     * \throws uhd::not_implemented_error if this functionality does not exist
+     *         for this device
+     */
+    virtual void set_tx_power_reference(
+        const double power_dbm, const size_t chan = 0) = 0;
+
+    /*! Return the actual reference TX power level.
+     *
+     * Note: This functionality is not supported for most devices, and will
+     * cause a uhd::not_implemented_error exception to be thrown on devices that
+     * do not have this functionality.
+     *
+     * For more information on how to use this API, see \ref page_power.
+     *
+     * \param chan The channel for which this setting is queried
+     * \throws uhd::not_implemented_error if this functionality does not exist
+     *         for this device
+     */
+    virtual double get_tx_power_reference(const size_t chan = 0) = 0;
+
     /*!
      * Select the TX antenna on the frontend.
      * \param ant the antenna name