uhd: created tune request struct and implemented more fine grained tuning calls

7 files changed, 137 insertions, 86 deletions

diff --git a/host/include/uhd/types/CMakeLists.txt b/host/include/uhd/types/CMakeLists.txt
index dbce21c98..661dd2d39 100644
--- a/host/include/uhd/types/CMakeLists.txt
+++ b/host/include/uhd/types/CMakeLists.txt
@@ -28,6 +28,7 @@ INSTALL(FILES
     serial.hpp
     stream_cmd.hpp
     time_spec.hpp
+    tune_request.hpp
     tune_result.hpp
     DESTINATION ${INCLUDE_DIR}/uhd/types
 )
diff --git a/host/include/uhd/types/tune_request.hpp b/host/include/uhd/types/tune_request.hpp
new file mode 100644
index 000000000..f80d2cb15
--- /dev/null
+++ b/host/include/uhd/types/tune_request.hpp
@@ -0,0 +1,97 @@
+//
+// Copyright 2010 Ettus Research LLC
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+#ifndef INCLUDED_UHD_TYPES_TUNE_REQUEST_HPP
+#define INCLUDED_UHD_TYPES_TUNE_REQUEST_HPP
+
+#include <uhd/config.hpp>
+
+namespace uhd{
+
+    /*!
+     * A tune request instructs the implementation how to tune the RF chain.
+     * The policies can be used to select automatic tuning or
+     * fined control over the daughterboard IF and DSP tuning.
+     * Not all combinations of policies are applicable.
+     * Convenience constructors are supplied for most use cases.
+     */
+    struct UHD_API tune_request_t{
+        /*!
+         * Make a new tune request for a particular center frequency.
+         * Use an automatic policy for the intermediate and DSP frequency
+         * to tune the chain as close as possible to the target frequency.
+         * \param target_freq the target frequency in Hz
+         */
+        tune_request_t(double target_freq = 0);
+
+        /*!
+         * Make a new tune request for a particular center frequency.
+         * Use a manual policy for the intermediate frequency,
+         * and an automatic policy for the DSP frequency,
+         * to tune the chain as close as possible to the target frequency.
+         * \param target_freq the target frequency in Hz
+         * \param lo_off the LO offset frequency in Hz
+         */
+        tune_request_t(double target_freq, double lo_off);
+
+        /*!
+         * Policy types for tune arguments:
+         * - None: do not set this argument, use current setting
+         * - Auto: automatically determine the argument's value
+         * - Manual: use the argument's value for the setting
+         */
+        enum policy_t {
+            POLICY_NONE   = 'N',
+            POLICY_AUTO   = 'A',
+            POLICY_MANUAL = 'M'
+        };
+
+        /*!
+         * The target frequency of the overall chain in Hz.
+         * Use when one of the policies is set to automatic.
+         */
+        double target_freq;
+
+        /*!
+         * The policy for the intermediate frequency.
+         * Automatic behavior: the target frequency + default LO offset.
+         */
+        policy_t inter_freq_policy;
+
+        /*!
+         * The intermediate frequency in Hz.
+         * Set when the policy is set to manual.
+         */
+        double inter_freq;
+
+        /*!
+         * The policy for the DSP frequency.
+         * Automatic behavior: the difference between the target and IF.
+         */
+        policy_t dsp_freq_policy;
+
+        /*!
+         * The DSP frequency in Hz.
+         * Set when the policy is set to manual.
+         */
+        double dsp_freq;
+
+    };
+
+} //namespace uhd
+
+#endif /* INCLUDED_UHD_TYPES_TUNE_REQUEST_HPP */
diff --git a/host/include/uhd/usrp/mimo_usrp.hpp b/host/include/uhd/usrp/mimo_usrp.hpp
index 78833e24e..b5acf84e1 100644
--- a/host/include/uhd/usrp/mimo_usrp.hpp
+++ b/host/include/uhd/usrp/mimo_usrp.hpp
@@ -127,7 +127,7 @@ public:
     virtual double get_rx_rate_all(void) = 0;
 
     virtual tune_result_t set_rx_freq(size_t chan, double freq) = 0;
-    virtual tune_result_t set_rx_freq(size_t chan, double freq, double lo_off) = 0;
+    //virtual tune_result_t set_rx_freq(size_t chan, double freq, double lo_off) = 0;
     virtual double get_rx_freq(size_t chan) = 0;
     virtual freq_range_t get_rx_freq_range(size_t chan) = 0;
 
@@ -161,7 +161,7 @@ public:
     virtual double get_tx_rate_all(void) = 0;
 
     virtual tune_result_t set_tx_freq(size_t chan, double freq) = 0;
-    virtual tune_result_t set_tx_freq(size_t chan, double freq, double lo_off) = 0;
+    //virtual tune_result_t set_tx_freq(size_t chan, double freq, double lo_off) = 0;
     virtual double get_tx_freq(size_t chan) = 0;
     virtual freq_range_t get_tx_freq_range(size_t chan) = 0;
 
@@ -345,9 +345,9 @@ public:
         return tune_rx_subdev_and_dsp(_rx_subdev(chan), _rx_dsp(chan), 0, target_freq);
     }
 
-    tune_result_t set_rx_freq(size_t chan, double target_freq, double lo_off){
-        return tune_rx_subdev_and_dsp(_rx_subdev(chan), _rx_dsp(chan), 0, target_freq, lo_off);
-    }
+    //tune_result_t set_rx_freq(size_t chan, double target_freq, double lo_off){
+    //    return tune_rx_subdev_and_dsp(_rx_subdev(chan), _rx_dsp(chan), 0, target_freq, lo_off);
+    //}
 
     double get_rx_freq(size_t chan){
         return derive_freq_from_rx_subdev_and_dsp(_rx_subdev(chan), _rx_dsp(chan), 0);
@@ -425,9 +425,9 @@ public:
         return tune_tx_subdev_and_dsp(_tx_subdev(chan), _tx_dsp(chan), 0, target_freq);
     }
 
-    tune_result_t set_tx_freq(size_t chan, double target_freq, double lo_off){
-        return tune_tx_subdev_and_dsp(_tx_subdev(chan), _tx_dsp(chan), 0, target_freq, lo_off);
-    }
+    //tune_result_t set_tx_freq(size_t chan, double target_freq, double lo_off){
+    //    return tune_tx_subdev_and_dsp(_tx_subdev(chan), _tx_dsp(chan), 0, target_freq, lo_off);
+    //}
 
     double get_tx_freq(size_t chan){
         return derive_freq_from_tx_subdev_and_dsp(_tx_subdev(chan), _tx_dsp(chan), 0);
diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index 2f71f80b1..5380d177d 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -23,6 +23,7 @@
 #include <uhd/types/ranges.hpp>
 #include <uhd/types/stream_cmd.hpp>
 #include <uhd/types/clock_config.hpp>
+#include <uhd/types/tune_request.hpp>
 #include <uhd/types/tune_result.hpp>
 #include <uhd/usrp/subdev_spec.hpp>
 #include <uhd/usrp/dboard_iface.hpp>
@@ -213,20 +214,13 @@ public:
 
     /*!
      * Set the RX center frequency.
-     * \param freq the frequency in Hz
+     * \param tune_request tune request instructions
      * \param chan the channel index 0 to N-1
      * \return a tune result object
      */
-    virtual tune_result_t set_rx_freq(double freq, size_t chan) = 0;
-
-    /*!
-     * Set the RX center frequency.
-     * \param freq the frequency in Hz
-     * \param lo_off an LO offset in Hz
-     * \param chan the channel index 0 to N-1
-     * \return a tune result object
-     */
-    virtual tune_result_t set_rx_freq(double freq, double lo_off, size_t chan) = 0;
+    virtual tune_result_t set_rx_freq(
+        const tune_request_t &tune_request, size_t chan = 0
+    ) = 0;
 
     /*!
      * Get the RX center frequency.
@@ -399,20 +393,13 @@ public:
 
     /*!
      * Set the TX center frequency.
-     * \param freq the frequency in Hz
-     * \param chan the channel index 0 to N-1
-     * \return a tune result object
-     */
-    virtual tune_result_t set_tx_freq(double freq, size_t chan) = 0;
-
-    /*!
-     * Set the TX center frequency.
-     * \param freq the frequency in Hz
-     * \param lo_off an LO offset in Hz
+     * \param tune_request tune request instructions
      * \param chan the channel index 0 to N-1
      * \return a tune result object
      */
-    virtual tune_result_t set_tx_freq(double freq, double lo_off, size_t chan) = 0;
+    virtual tune_result_t set_tx_freq(
+        const tune_request_t &tune_request, size_t chan = 0
+    ) = 0;
 
     /*!
      * Get the TX center frequency.
diff --git a/host/include/uhd/usrp/simple_usrp.hpp b/host/include/uhd/usrp/simple_usrp.hpp
index 22f4d64ba..59fd9bb09 100644
--- a/host/include/uhd/usrp/simple_usrp.hpp
+++ b/host/include/uhd/usrp/simple_usrp.hpp
@@ -117,7 +117,7 @@ public:
     virtual double get_rx_rate(void) = 0;
 
     virtual tune_result_t set_rx_freq(double freq) = 0;
-    virtual tune_result_t set_rx_freq(double freq, double lo_off) = 0;
+    //virtual tune_result_t set_rx_freq(double freq, double lo_off) = 0;
     virtual double get_rx_freq(void) = 0;
     virtual freq_range_t get_rx_freq_range(void) = 0;
 
@@ -152,7 +152,7 @@ public:
     virtual double get_tx_rate(void) = 0;
 
     virtual tune_result_t set_tx_freq(double freq) = 0;
-    virtual tune_result_t set_tx_freq(double freq, double lo_off) = 0;
+    //virtual tune_result_t set_tx_freq(double freq, double lo_off) = 0;
     virtual double get_tx_freq(void) = 0;
     virtual freq_range_t get_tx_freq_range(void) = 0;
 
@@ -243,9 +243,9 @@ public:
         return _sdev->set_rx_freq(target_freq);
     }
 
-    tune_result_t set_rx_freq(double target_freq, double lo_off){
-        return _sdev->set_rx_freq(target_freq, lo_off);
-    }
+    //tune_result_t set_rx_freq(double target_freq, double lo_off){
+    //    return _sdev->set_rx_freq(target_freq, lo_off);
+    //}
 
     double get_rx_freq(void){
         return _sdev->get_rx_freq();
@@ -318,9 +318,9 @@ public:
         return _sdev->set_tx_freq(target_freq);
     }
 
-    tune_result_t set_tx_freq(double target_freq, double lo_off){
-        return _sdev->set_tx_freq(target_freq, lo_off);
-    }
+    //tune_result_t set_tx_freq(double target_freq, double lo_off){
+    //    return _sdev->set_tx_freq(target_freq, lo_off);
+    //}
 
     double get_tx_freq(void){
         return _sdev->get_tx_freq();
diff --git a/host/include/uhd/usrp/single_usrp.hpp b/host/include/uhd/usrp/single_usrp.hpp
index a068fbed8..26303fe10 100644
--- a/host/include/uhd/usrp/single_usrp.hpp
+++ b/host/include/uhd/usrp/single_usrp.hpp
@@ -23,6 +23,7 @@
 #include <uhd/types/ranges.hpp>
 #include <uhd/types/stream_cmd.hpp>
 #include <uhd/types/clock_config.hpp>
+#include <uhd/types/tune_request.hpp>
 #include <uhd/types/tune_result.hpp>
 #include <uhd/usrp/subdev_spec.hpp>
 #include <uhd/usrp/dboard_iface.hpp>
@@ -154,20 +155,13 @@ public:
 
     /*!
      * Set the RX center frequency.
-     * \param freq the frequency in Hz
+     * \param tune_request tune request instructions
      * \param chan the channel index 0 to N-1
      * \return a tune result object
      */
-    virtual tune_result_t set_rx_freq(double freq, size_t chan = 0) = 0;
-
-    /*!
-     * Set the RX center frequency.
-     * \param freq the frequency in Hz
-     * \param lo_off an LO offset in Hz
-     * \param chan the channel index 0 to N-1
-     * \return a tune result object
-     */
-    virtual tune_result_t set_rx_freq(double freq, double lo_off, size_t chan = 0) = 0;
+    virtual tune_result_t set_rx_freq(
+        const tune_request_t &tune_request, size_t chan = 0
+    ) = 0;
 
     /*!
      * Get the RX center frequency.
@@ -330,20 +324,13 @@ public:
 
     /*!
      * Set the TX center frequency.
-     * \param freq the frequency in Hz
-     * \param chan the channel index 0 to N-1
-     * \return a tune result object
-     */
-    virtual tune_result_t set_tx_freq(double freq, size_t chan = 0) = 0;
-
-    /*!
-     * Set the TX center frequency.
-     * \param freq the frequency in Hz
-     * \param lo_off an LO offset in Hz
+     * \param tune_request tune request instructions
      * \param chan the channel index 0 to N-1
      * \return a tune result object
      */
-    virtual tune_result_t set_tx_freq(double freq, double lo_off, size_t chan = 0) = 0;
+    virtual tune_result_t set_tx_freq(
+        const tune_request_t &tune_request, size_t chan = 0
+    ) = 0;
 
     /*!
      * Get the TX center frequency.
diff --git a/host/include/uhd/usrp/tune_helper.hpp b/host/include/uhd/usrp/tune_helper.hpp
index ec133fa08..db12241c1 100644
--- a/host/include/uhd/usrp/tune_helper.hpp
+++ b/host/include/uhd/usrp/tune_helper.hpp
@@ -20,6 +20,7 @@
 
 #include <uhd/config.hpp>
 #include <uhd/wax.hpp>
+#include <uhd/types/tune_request.hpp>
 #include <uhd/types/tune_result.hpp>
 
 namespace uhd{ namespace usrp{
@@ -32,23 +33,12 @@ namespace uhd{ namespace usrp{
      * \param subdev the dboard subdevice object with properties
      * \param ddc the mboard dsp object with properties
      * \param chan the channel of the dsp to tune
-     * \param target_freq the desired center frequency
-     * \param lo_offset an offset for the subdevice IF from center
+     * \param tune_request tune request instructions
      * \return a tune result struct
      */
     UHD_API tune_result_t tune_rx_subdev_and_dsp(
         wax::obj subdev, wax::obj ddc, size_t chan,
-        double target_freq, double lo_offset
-    );
-
-    /*!
-     * Tune a rx chain to the desired frequency:
-     * Same as the above, except the LO offset
-     * is calculated based on the subdevice and BW.
-     */
-    UHD_API tune_result_t tune_rx_subdev_and_dsp(
-        wax::obj subdev, wax::obj ddc,
-        size_t chan, double target_freq
+        const tune_request_t &tune_request
     );
 
     /*!
@@ -70,23 +60,12 @@ namespace uhd{ namespace usrp{
      * \param subdev the dboard subdevice object with properties
      * \param duc the mboard dsp object with properties
      * \param chan the channel of the dsp to tune
-     * \param target_freq the desired center frequency
-     * \param lo_offset an offset for the subdevice IF from center
+     * \param tune_request tune request instructions
      * \return a tune result struct
      */
     UHD_API tune_result_t tune_tx_subdev_and_dsp(
         wax::obj subdev, wax::obj duc, size_t chan,
-        double target_freq, double lo_offset
-    );
-
-    /*!
-     * Tune a tx chain to the desired frequency:
-     * Same as the above, except the LO offset
-     * is calculated based on the subdevice and BW.
-     */
-    UHD_API tune_result_t tune_tx_subdev_and_dsp(
-        wax::obj subdev, wax::obj duc,
-        size_t chan, double target_freq
+        const tune_request_t &tune_request
     );
 
     /*!