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.

5 files changed, 140 insertions, 0 deletions

diff --git a/host/lib/include/uhdlib/rfnoc/radio_control_impl.hpp b/host/lib/include/uhdlib/rfnoc/radio_control_impl.hpp
index c3a6bd507..4916ecf6f 100644
--- a/host/lib/include/uhdlib/rfnoc/radio_control_impl.hpp
+++ b/host/lib/include/uhdlib/rfnoc/radio_control_impl.hpp
@@ -72,6 +72,8 @@ public:
     virtual double set_rx_bandwidth(const double bandwidth, const size_t chan);
     virtual void set_tx_gain_profile(const std::string& profile, const size_t chan);
     virtual void set_rx_gain_profile(const std::string& profile, const size_t chan);
+    virtual void set_rx_power_reference(const double power_dbm, const size_t chan);
+    virtual void set_tx_power_reference(const double power_dbm, const size_t chan);
 
     // Getters
     virtual std::string get_tx_antenna(const size_t chan) const;
@@ -100,6 +102,10 @@ public:
     virtual double get_rx_bandwidth(const size_t);
     virtual meta_range_t get_tx_bandwidth_range(size_t chan) const;
     virtual meta_range_t get_rx_bandwidth_range(size_t chan) const;
+    virtual bool has_rx_power_reference(const size_t chan);
+    virtual bool has_tx_power_reference(const size_t chan);
+    virtual double get_rx_power_reference(const size_t chan);
+    virtual double get_tx_power_reference(const size_t chan);
 
     /**************************************************************************
      * LO Controls
diff --git a/host/lib/rfnoc/radio_control_impl.cpp b/host/lib/rfnoc/radio_control_impl.cpp
index 4f1246e5c..e34a9b430 100644
--- a/host/lib/rfnoc/radio_control_impl.cpp
+++ b/host/lib/rfnoc/radio_control_impl.cpp
@@ -404,6 +404,28 @@ double radio_control_impl::set_rx_gain(
     return set_rx_gain(gain, chan);
 }
 
+bool radio_control_impl::has_rx_power_reference(const size_t)
+{
+    return false;
+}
+
+bool radio_control_impl::has_tx_power_reference(const size_t)
+{
+    return false;
+}
+
+void radio_control_impl::set_rx_power_reference(const double, const size_t)
+{
+    throw uhd::not_implemented_error(
+        "set_rx_power_reference() is not supported on this radio!");
+}
+
+void radio_control_impl::set_tx_power_reference(const double, const size_t)
+{
+    throw uhd::not_implemented_error(
+        "set_tx_power_reference() is not supported on this radio!");
+}
+
 void radio_control_impl::set_rx_agc(const bool, const size_t)
 {
     throw uhd::not_implemented_error("set_rx_agc() is not supported on this radio!");
@@ -575,6 +597,20 @@ uhd::meta_range_t radio_control_impl::get_rx_bandwidth_range(size_t chan) const
     return result;
 }
 
+double radio_control_impl::get_rx_power_reference(const size_t)
+{
+    throw uhd::not_implemented_error(
+        "get_rx_power_reference() is not supported on this radio!");
+    return 0.0;
+}
+
+double radio_control_impl::get_tx_power_reference(const size_t)
+{
+    throw uhd::not_implemented_error(
+        "get_tx_power_reference() is not supported on this radio!");
+    return 0.0;
+}
+
 /******************************************************************************
  * LO Default API
  *****************************************************************************/
diff --git a/host/lib/usrp/multi_usrp.cpp b/host/lib/usrp/multi_usrp.cpp
index c91f596cd..0392d4df9 100644
--- a/host/lib/usrp/multi_usrp.cpp
+++ b/host/lib/usrp/multi_usrp.cpp
@@ -1718,6 +1718,34 @@ public:
         return rx_gain_group(chan)->get_names();
     }
 
+    /**************************************************************************
+     * RX Power control
+     *************************************************************************/
+    bool has_rx_power_reference(const size_t chan)
+    {
+        return _tree->exists(rx_rf_fe_root(chan) / "ref_power/value");
+    }
+
+    void set_rx_power_reference(const double power_dbm, const size_t chan = 0)
+    {
+        const auto power_ref_path = rx_rf_fe_root(chan) / "ref_power/value";
+        if (!_tree->exists(power_ref_path)) {
+            throw uhd::not_implemented_error(
+                "set_rx_power_reference() not available for this device and channel");
+        }
+        _tree->access<double>(power_ref_path).set(power_dbm);
+    }
+
+    double get_rx_power_reference(const size_t chan = 0)
+    {
+        const auto power_ref_path = rx_rf_fe_root(chan) / "ref_power/value";
+        if (!_tree->exists(power_ref_path)) {
+            throw uhd::not_implemented_error(
+                "get_rx_power_reference() not available for this device and channel");
+        }
+        return _tree->access<double>(power_ref_path).get();
+    }
+
     void set_rx_antenna(const std::string& ant, size_t chan)
     {
         _tree->access<std::string>(rx_rf_fe_root(chan) / "antenna" / "value").set(ant);
@@ -2194,6 +2222,34 @@ public:
         return tx_gain_group(chan)->get_names();
     }
 
+    /**************************************************************************
+     * TX Power Controls
+     *************************************************************************/
+    bool has_tx_power_reference(const size_t chan)
+    {
+        return _tree->exists(tx_rf_fe_root(chan) / "ref_power/value");
+    }
+
+    void set_tx_power_reference(const double power_dbm, const size_t chan = 0)
+    {
+        const auto power_ref_path = tx_rf_fe_root(chan) / "ref_power/value";
+        if (!_tree->exists(power_ref_path)) {
+            throw uhd::not_implemented_error(
+                "set_tx_power_reference() not available for this device and channel");
+        }
+        _tree->access<double>(power_ref_path).set(power_dbm);
+    }
+
+    double get_tx_power_reference(const size_t chan = 0)
+    {
+        const auto power_ref_path = tx_rf_fe_root(chan) / "ref_power/value";
+        if (!_tree->exists(power_ref_path)) {
+            throw uhd::not_implemented_error(
+                "get_tx_power_reference() not available for this device and channel");
+        }
+        return _tree->access<double>(power_ref_path).get();
+    }
+
     void set_tx_antenna(const std::string& ant, size_t chan)
     {
         _tree->access<std::string>(tx_rf_fe_root(chan) / "antenna" / "value").set(ant);
diff --git a/host/lib/usrp/multi_usrp_python.hpp b/host/lib/usrp/multi_usrp_python.hpp
index f4e0a73e1..62f34ffa2 100644
--- a/host/lib/usrp/multi_usrp_python.hpp
+++ b/host/lib/usrp/multi_usrp_python.hpp
@@ -19,6 +19,7 @@ void export_multi_usrp(py::module& m)
     const auto ALL_CHANS   = multi_usrp::ALL_CHANS;
     const auto ALL_LOS     = multi_usrp::ALL_LOS;
 
+    // clang-format off
     py::class_<multi_usrp, multi_usrp::sptr>(m, "multi_usrp")
 
         // Factory
@@ -125,6 +126,8 @@ void export_multi_usrp(py::module& m)
         .def("get_rx_gain_profile"     , &multi_usrp::get_rx_gain_profile, py::arg("chan") = 0)
         .def("set_rx_gain_profile"     , &multi_usrp::set_rx_gain_profile, py::arg("profile"), py::arg("chan") = 0)
         .def("get_rx_gain_profile_names", &multi_usrp::get_rx_gain_profile_names, py::arg("chan") = 0)
+        .def("set_rx_power_reference"  , &multi_usrp::set_rx_power_reference, py::arg("power_dbm"), py::arg("chan") = 0)
+        .def("get_rx_power_reference"  , &multi_usrp::get_rx_power_reference, py::arg("chan") = 0)
 
         // TX methods
         .def("set_tx_subdev_spec"      , &multi_usrp::set_tx_subdev_spec, py::arg("spec"), py::arg("mboard") = ALL_MBOARDS)
@@ -163,6 +166,8 @@ void export_multi_usrp(py::module& m)
         .def("get_tx_gain_profile"     , &multi_usrp::get_tx_gain_profile, py::arg("chan") = 0)
         .def("set_tx_gain_profile"     , &multi_usrp::set_tx_gain_profile, py::arg("profile"), py::arg("chan") = 0)
         .def("get_tx_gain_profile_names", &multi_usrp::get_tx_gain_profile_names, py::arg("chan") = 0)
+        .def("set_tx_power_reference"  , &multi_usrp::set_tx_power_reference, py::arg("power_dbm"), py::arg("chan") = 0)
+        .def("get_tx_power_reference"  , &multi_usrp::get_tx_power_reference, py::arg("chan") = 0)
 
         // GPIO methods
         .def("get_gpio_banks"          , &multi_usrp::get_gpio_banks)
@@ -182,6 +187,7 @@ void export_multi_usrp(py::module& m)
         .def("set_tx_filter"           , &multi_usrp::set_tx_filter)
         // clang-format off
         ;
+    // clang-format on
 }
 
 #endif /* INCLUDED_UHD_USRP_MULTI_USRP_PYTHON_HPP */
diff --git a/host/lib/usrp/multi_usrp_rfnoc.cpp b/host/lib/usrp/multi_usrp_rfnoc.cpp
index 14b5fd50b..a62fe3f8e 100644
--- a/host/lib/usrp/multi_usrp_rfnoc.cpp
+++ b/host/lib/usrp/multi_usrp_rfnoc.cpp
@@ -1396,6 +1396,24 @@ public:
         return rx_chain.radio->get_rx_gain_names(rx_chain.block_chan);
     }
 
+    bool has_rx_power_reference(const size_t chan)
+    {
+        auto& rx_chain = _get_rx_chan(chan);
+        return rx_chain.radio->has_rx_power_reference(rx_chain.block_chan);
+    }
+
+    void set_rx_power_reference(const double power_dbm, const size_t chan)
+    {
+        auto& rx_chain = _get_rx_chan(chan);
+        rx_chain.radio->set_rx_power_reference(power_dbm, rx_chain.block_chan);
+    }
+
+    double get_rx_power_reference(const size_t chan)
+    {
+        auto& rx_chain = _get_rx_chan(chan);
+        return rx_chain.radio->get_rx_power_reference(rx_chain.block_chan);
+    }
+
     void set_rx_antenna(const std::string& ant, size_t chan)
     {
         auto& rx_chain = _get_rx_chan(chan);
@@ -1836,6 +1854,24 @@ public:
         return tx_chain.radio->get_tx_gain_names(tx_chain.block_chan);
     }
 
+    bool has_tx_power_reference(const size_t chan)
+    {
+        auto& tx_chain = _get_tx_chan(chan);
+        return tx_chain.radio->has_rx_power_reference(tx_chain.block_chan);
+    }
+
+    void set_tx_power_reference(const double power_dbm, const size_t chan)
+    {
+        auto& tx_chain = _get_tx_chan(chan);
+        tx_chain.radio->set_tx_power_reference(power_dbm, tx_chain.block_chan);
+    }
+
+    double get_tx_power_reference(const size_t chan)
+    {
+        auto& tx_chain = _get_tx_chan(chan);
+        return tx_chain.radio->get_tx_power_reference(tx_chain.block_chan);
+    }
+
     void set_tx_antenna(const std::string& ant, size_t chan)
     {
         auto tx_chain = _get_tx_chan(chan);