From a63682f981c3d4b828b5454a7d4849d181b9c8b3 Mon Sep 17 00:00:00 2001 From: Martin Braun Date: Wed, 19 Feb 2020 12:38:30 -0800 Subject: 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. --- host/include/uhd/rfnoc/radio_control.hpp | 99 +++++++++++++++++++++++++++++ host/include/uhd/usrp/multi_usrp.hpp | 106 +++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) (limited to 'host/include') 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 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 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 #include @@ -1176,6 +1177,59 @@ public: virtual void set_rx_iq_balance( const std::complex& 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 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 -- cgit v1.2.3