uhd: Improved tuning code and corresponding outputs/warnings

* Added convenience function for frequency comparisons
* ABI change required

2 files changed, 46 insertions, 2 deletions

diff --git a/host/include/uhd/types/tune_result.hpp b/host/include/uhd/types/tune_result.hpp
index e51473085..723adcfbf 100644
--- a/host/include/uhd/types/tune_result.hpp
+++ b/host/include/uhd/types/tune_result.hpp
@@ -24,12 +24,56 @@
 namespace uhd{
 
     /*!
-     * The tune result struct holds result of a 2-phase tuning.
+     * The tune result struct holds the RF and DSP tuned frequencies.
      */
     struct UHD_API tune_result_t{
+        /*! The target RF frequency, clipped to be within system range
+         *
+         * If the requested frequency is within the range of the system, then
+         * this variable will equal the requested frequency. If the requested
+         * frequency is outside of the tunable range, however, this variable
+         * will hold the value that it was 'clipped' to in order to keep tuning
+         * in-bounds. */
+        double clipped_rf_freq;
+
+        /*! Target RF Freq, including RF FE offset
+         *
+         * AUTO Tuning Policy:
+         * This variable holds the requested center frequency, plus any LO
+         * offset required by the radio front-end. Note that this is *not* the
+         * LO offset requested by the user (if one exists), but rather one
+         * required by the hardware (if required).
+         *
+         * MANUAL Tuning Policy:
+         * This variable equals the RF frequency in the tune request. */
         double target_rf_freq;
+
+        /*! The frequency to which the RF LO actually tuned
+         *
+         * If this does not equal the `target_rf_freq`, then it is because the
+         * target was outside of the range of the LO, or the LO was not able to
+         * hit it exactly due to tuning accuracy. */
         double actual_rf_freq;
+
+        /*! The frequency the CORDIC must adjust the RF
+         *
+         * AUTO Tuning Policy:
+         * It is fairly common for the RF LO to not be able to exactly hit the
+         * requested frequency. This variable holds the required adjustment the
+         * CORDIC must make to the signal to bring it to the requested center
+         * frequency.
+         *
+         * MANUAL Tuning Policy
+         * This variable equals the DSP frequency in the tune request, clipped
+         * to be within range of the DSP if it was outside. */
         double target_dsp_freq;
+
+        /*! The frequency to which the CORDIC in the DSP actually tuned
+         *
+         * If we failed to hit the target DSP frequency, it is either because
+         * the requested resolution wasn't possible or something went wrong in
+         * the DSP. In most cases, it should equal the `target_dsp_freq` above.
+         */
         double actual_dsp_freq;
 
         /*!
diff --git a/host/include/uhd/version.hpp b/host/include/uhd/version.hpp
index 0a8347afe..ae583bf96 100644
--- a/host/include/uhd/version.hpp
+++ b/host/include/uhd/version.hpp
@@ -27,7 +27,7 @@
  * The format is oldest API compatible release - ABI compat number.
  * The compatibility number allows pre-release ABI to be versioned.
  */
-#define UHD_VERSION_ABI_STRING "3.7.2-0"
+#define UHD_VERSION_ABI_STRING "3.7.3-0"
 
 namespace uhd{