Merge branch 'master' of ettus.sourcerepo.com:ettus/uhdpriv into usrp_e

5 files changed, 188 insertions, 44 deletions

diff --git a/host/include/uhd/usrp/dboard_id.hpp b/host/include/uhd/usrp/dboard_id.hpp
index 4c45e4334..1fda8182e 100644
--- a/host/include/uhd/usrp/dboard_id.hpp
+++ b/host/include/uhd/usrp/dboard_id.hpp
@@ -67,6 +67,12 @@ namespace uhd{ namespace usrp{
         std::string to_string(void) const;
 
         /*!
+         * Get the dboard id represented as a canonical name.
+         * \return the canonical string representation
+         */
+        std::string to_cname(void) const;
+
+        /*!
          * Get the pretty print representation of this dboard id.
          * \return a string with the dboard name and id number
          */
diff --git a/host/include/uhd/usrp/misc_utils.hpp b/host/include/uhd/usrp/misc_utils.hpp
index 2af9f5b40..37860a1a5 100644
--- a/host/include/uhd/usrp/misc_utils.hpp
+++ b/host/include/uhd/usrp/misc_utils.hpp
@@ -20,6 +20,7 @@
 
 #include <uhd/config.hpp>
 #include <uhd/wax.hpp>
+#include <uhd/usrp/dboard_id.hpp>
 #include <uhd/usrp/subdev_spec.hpp>
 #include <uhd/utils/gain_group.hpp>
 
@@ -35,11 +36,13 @@ namespace uhd{ namespace usrp{
 
     /*!
      * Create a gain group that represents the subdevice and its codec.
+     * \param dboard_id the dboard id for this subdevice
      * \param subdev the object with subdevice properties
      * \param codec the object with codec properties
      * \param gain_group_policy the policy to use
      */
     UHD_API gain_group::sptr make_gain_group(
+        const dboard_id_t &dboard_id,
         wax::obj subdev, wax::obj codec,
         gain_group_policy_t gain_group_policy
     );
diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index 6adba85bd..2f71f80b1 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -73,6 +73,9 @@ public:
     //! A wildcard motherboard index
     static const size_t ALL_MBOARDS = size_t(~0);
 
+    //! A wildcard gain element name
+    static const std::string ALL_GAINS;
+
     /*!
      * Make a new multi usrp from the device address.
      * \param dev_addr the device address
@@ -240,27 +243,54 @@ public:
     virtual freq_range_t get_rx_freq_range(size_t chan) = 0;
 
     /*!
-     * Set the RX gain:
-     * Distribute among gain elements in the RX path.
+     * Set the RX gain value for the specified gain element.
+     * For an empty name, distribute across all gain elements.
      * \param gain the gain in dB
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      */
-    virtual void set_rx_gain(float gain, size_t chan) = 0;
+    virtual void set_rx_gain(float gain, const std::string &name, size_t chan) = 0;
+
+    //! A convenience wrapper for setting overall RX gain
+    void set_rx_gain(float gain, size_t chan){
+        return this->set_rx_gain(gain, ALL_GAINS, chan);
+    }
 
     /*!
-     * Get the RX gain:
-     * Summation of gain elements in the RX path.
+     * Get the RX gain value for the specified gain element.
+     * For an empty name, sum across all gain elements.
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      * \return the gain in dB
      */
-    virtual float get_rx_gain(size_t chan) = 0;
+    virtual float get_rx_gain(const std::string &name, size_t chan) = 0;
+
+    //! A convenience wrapper for getting overall RX gain
+    float get_rx_gain(size_t chan){
+        return this->get_rx_gain(ALL_GAINS, chan);
+    }
 
     /*!
-     * Get the RX gain range.
+     * Get the RX gain range for the specified gain element.
+     * For an empty name, calculate the overall gain range.
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      * \return a gain range object
      */
-    virtual gain_range_t get_rx_gain_range(size_t chan) = 0;
+    virtual gain_range_t get_rx_gain_range(const std::string &name, size_t chan) = 0;
+
+    //! A convenience wrapper for getting overall RX gain range
+    gain_range_t get_rx_gain_range(size_t chan){
+        return this->get_rx_gain_range(ALL_GAINS, chan);
+    }
+
+    /*!
+     * Get the names of the gain elements in the RX chain.
+     * Gain elements are ordered from antenna to FPGA.
+     * \param chan the channel index 0 to N-1
+     * \return a vector of gain element names
+     */
+    virtual std::vector<std::string> get_rx_gain_names(size_t chan) = 0;
 
     /*!
      * Select the RX antenna on the subdevice.
@@ -399,27 +429,54 @@ public:
     virtual freq_range_t get_tx_freq_range(size_t chan) = 0;
 
     /*!
-     * Set the TX gain:
-     * Distribute among gain elements in the TX path.
+     * Set the TX gain value for the specified gain element.
+     * For an empty name, distribute across all gain elements.
      * \param gain the gain in dB
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      */
-    virtual void set_tx_gain(float gain, size_t chan) = 0;
+    virtual void set_tx_gain(float gain, const std::string &name, size_t chan) = 0;
+
+    //! A convenience wrapper for setting overall TX gain
+    void set_tx_gain(float gain, size_t chan){
+        return this->set_tx_gain(gain, ALL_GAINS, chan);
+    }
 
     /*!
-     * Get the TX gain:
-     * Summation of gain elements in the TX path.
+     * Get the TX gain value for the specified gain element.
+     * For an empty name, sum across all gain elements.
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      * \return the gain in dB
      */
-    virtual float get_tx_gain(size_t chan) = 0;
+    virtual float get_tx_gain(const std::string &name, size_t chan) = 0;
+
+    //! A convenience wrapper for getting overall TX gain
+    float get_tx_gain(size_t chan){
+        return this->get_tx_gain(ALL_GAINS, chan);
+    }
 
     /*!
-     * Get the TX gain range.
+     * Get the TX gain range for the specified gain element.
+     * For an empty name, calculate the overall gain range.
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      * \return a gain range object
      */
-    virtual gain_range_t get_tx_gain_range(size_t chan) = 0;
+    virtual gain_range_t get_tx_gain_range(const std::string &name, size_t chan) = 0;
+
+    //! A convenience wrapper for getting overall TX gain range
+    gain_range_t get_tx_gain_range(size_t chan){
+        return this->get_tx_gain_range(ALL_GAINS, chan);
+    }
+
+    /*!
+     * Get the names of the gain elements in the TX chain.
+     * Gain elements are ordered from antenna to FPGA.
+     * \param chan the channel index 0 to N-1
+     * \return a vector of gain element names
+     */
+    virtual std::vector<std::string> get_tx_gain_names(size_t chan) = 0;
 
     /*!
      * Select the TX antenna on the subdevice.
diff --git a/host/include/uhd/usrp/single_usrp.hpp b/host/include/uhd/usrp/single_usrp.hpp
index 74a978f05..a068fbed8 100644
--- a/host/include/uhd/usrp/single_usrp.hpp
+++ b/host/include/uhd/usrp/single_usrp.hpp
@@ -43,6 +43,9 @@ class UHD_API single_usrp : boost::noncopyable{
 public:
     typedef boost::shared_ptr<single_usrp> sptr;
 
+    //! A wildcard gain element name
+    static const std::string ALL_GAINS;
+
     /*!
      * Make a new single usrp from the device address.
      * \param dev_addr the device address
@@ -120,7 +123,6 @@ public:
      * Set the RX subdevice specification:
      * The subdev spec maps a physical part of a daughter-board to a channel number.
      * Set the subdev spec before calling into any methods with a channel number.
-     * The subdev spec must be the same size across all motherboards.
      * \param spec the new subdevice specification
      */
     virtual void set_rx_subdev_spec(const uhd::usrp::subdev_spec_t &spec) = 0;
@@ -182,27 +184,54 @@ public:
     virtual freq_range_t get_rx_freq_range(size_t chan = 0) = 0;
 
     /*!
-     * Set the RX gain:
-     * Distribute among gain elements in the RX path.
+     * Set the RX gain value for the specified gain element.
+     * For an empty name, distribute across all gain elements.
      * \param gain the gain in dB
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      */
-    virtual void set_rx_gain(float gain, size_t chan = 0) = 0;
+    virtual void set_rx_gain(float gain, const std::string &name, size_t chan = 0) = 0;
+
+    //! A convenience wrapper for setting overall RX gain
+    void set_rx_gain(float gain, size_t chan = 0){
+        return this->set_rx_gain(gain, ALL_GAINS, chan);
+    }
 
     /*!
-     * Get the RX gain:
-     * Summation of gain elements in the RX path.
+     * Get the RX gain value for the specified gain element.
+     * For an empty name, sum across all gain elements.
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      * \return the gain in dB
      */
-    virtual float get_rx_gain(size_t chan = 0) = 0;
+    virtual float get_rx_gain(const std::string &name, size_t chan = 0) = 0;
+
+    //! A convenience wrapper for getting overall RX gain
+    float get_rx_gain(size_t chan = 0){
+        return this->get_rx_gain(ALL_GAINS, chan);
+    }
 
     /*!
-     * Get the RX gain range.
+     * Get the RX gain range for the specified gain element.
+     * For an empty name, calculate the overall gain range.
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      * \return a gain range object
      */
-    virtual gain_range_t get_rx_gain_range(size_t chan = 0) = 0;
+    virtual gain_range_t get_rx_gain_range(const std::string &name, size_t chan = 0) = 0;
+
+    //! A convenience wrapper for getting overall RX gain range
+    gain_range_t get_rx_gain_range(size_t chan = 0){
+        return this->get_rx_gain_range(ALL_GAINS, chan);
+    }
+
+    /*!
+     * Get the names of the gain elements in the RX chain.
+     * Gain elements are ordered from antenna to FPGA.
+     * \param chan the channel index 0 to N-1
+     * \return a vector of gain element names
+     */
+    virtual std::vector<std::string> get_rx_gain_names(size_t chan = 0) = 0;
 
     /*!
      * Select the RX antenna on the subdevice.
@@ -270,7 +299,6 @@ public:
      * Set the TX subdevice specification:
      * The subdev spec maps a physical part of a daughter-board to a channel number.
      * Set the subdev spec before calling into any methods with a channel number.
-     * The subdev spec must be the same size across all motherboards.
      * \param spec the new subdevice specification
      */
     virtual void set_tx_subdev_spec(const uhd::usrp::subdev_spec_t &spec) = 0;
@@ -332,27 +360,54 @@ public:
     virtual freq_range_t get_tx_freq_range(size_t chan = 0) = 0;
 
     /*!
-     * Set the TX gain:
-     * Distribute among gain elements in the TX path.
+     * Set the TX gain value for the specified gain element.
+     * For an empty name, distribute across all gain elements.
      * \param gain the gain in dB
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      */
-    virtual void set_tx_gain(float gain, size_t chan = 0) = 0;
+    virtual void set_tx_gain(float gain, const std::string &name, size_t chan = 0) = 0;
+
+    //! A convenience wrapper for setting overall TX gain
+    void set_tx_gain(float gain, size_t chan = 0){
+        return this->set_tx_gain(gain, ALL_GAINS, chan);
+    }
 
     /*!
-     * Get the TX gain:
-     * Summation of gain elements in the TX path.
+     * Get the TX gain value for the specified gain element.
+     * For an empty name, sum across all gain elements.
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      * \return the gain in dB
      */
-    virtual float get_tx_gain(size_t chan = 0) = 0;
+    virtual float get_tx_gain(const std::string &name, size_t chan = 0) = 0;
+
+    //! A convenience wrapper for getting overall TX gain
+    float get_tx_gain(size_t chan = 0){
+        return this->get_tx_gain(ALL_GAINS, chan);
+    }
 
     /*!
-     * Get the TX gain range.
+     * Get the TX gain range for the specified gain element.
+     * For an empty name, calculate the overall gain range.
+     * \param name the name of the gain element
      * \param chan the channel index 0 to N-1
      * \return a gain range object
      */
-    virtual gain_range_t get_tx_gain_range(size_t chan = 0) = 0;
+    virtual gain_range_t get_tx_gain_range(const std::string &name, size_t chan = 0) = 0;
+
+    //! A convenience wrapper for getting overall TX gain range
+    gain_range_t get_tx_gain_range(size_t chan = 0){
+        return this->get_tx_gain_range(ALL_GAINS, chan);
+    }
+
+    /*!
+     * Get the names of the gain elements in the TX chain.
+     * Gain elements are ordered from antenna to FPGA.
+     * \param chan the channel index 0 to N-1
+     * \return a vector of gain element names
+     */
+    virtual std::vector<std::string> get_tx_gain_names(size_t chan = 0) = 0;
 
     /*!
      * Select the TX antenna on the subdevice.
diff --git a/host/include/uhd/utils/gain_group.hpp b/host/include/uhd/utils/gain_group.hpp
index 3955dfa9a..c863248ce 100644
--- a/host/include/uhd/utils/gain_group.hpp
+++ b/host/include/uhd/utils/gain_group.hpp
@@ -23,6 +23,8 @@
 #include <boost/shared_ptr.hpp>
 #include <boost/function.hpp>
 #include <boost/utility.hpp>
+#include <vector>
+#include <string>
 
 namespace uhd{
 
@@ -40,36 +42,57 @@ public:
     typedef boost::shared_ptr<gain_group> sptr;
 
     /*!
-     * Get the overall gain range for this group.
+     * Get the gain range for the gain element specified by name.
+     * For an empty name, get the overall gain range for this group.
      * Overall step is defined as the minimum step size.
+     * \param name name of the gain element (optional)
      * \return a gain range with overall min, max, step
      */
-    virtual gain_range_t get_range(void) = 0;
+    virtual gain_range_t get_range(const std::string &name = "") = 0;
 
     /*!
-     * Get the overall gain value for this group.
-     * \return a summation of all the gain values
+     * Get the gain value for the gain element specified by name.
+     * For an empty name, get the overall gain value for this group.
+     * \param name name of the gain element (optional)
+     * \return a gain value of the element or all elements
      */
-    virtual float get_value(void) = 0;
+    virtual float get_value(const std::string &name = "") = 0;
 
     /*!
-     * Set the overall gain value for this group.
+     * Set the gain value for the gain element specified by name.
+     * For an empty name, set the overall gain value for this group.
      * The power will be distributed across individual gain elements.
      * The semantics of how to do this are determined by the priority.
-     * \param gain the gain to set across the group
+     * \param gain the gain to set for the lement or across the group
+     * \param name name of the gain element (optional)
      */
-    virtual void set_value(float gain) = 0;
+    virtual void set_value(float gain, const std::string &name = "") = 0;
 
     /*!
-     * Register a set of gain functions into this group.
+     * Get a list of names of registered gain elements.
+     * The names are in the order that they were registered.
+     * \return a vector of gain name strings
+     */
+    virtual const std::vector<std::string> get_names(void) = 0;
+
+    /*!
+     * Register a set of gain functions into this group:
+     *
+     * The name should be a unique and non-empty name.
+     * Othwerwise, the implementation will rename it.
+     *
      * Priority determines how power will be distributed
      * with higher priorities getting the power first,
      * and lower priorities getting the remainder power.
+     *
+     * \param name the name of the gain element
      * \param gain_fcns the set of gain functions
      * \param priority the priority of the gain element
      */
     virtual void register_fcns(
-        const gain_fcns_t &gain_fcns, size_t priority = 0
+        const std::string &name,
+        const gain_fcns_t &gain_fcns,
+        size_t priority = 0
     ) = 0;
 
     /*!