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.

3 files changed, 98 insertions, 0 deletions

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);