Merge branch 'master' into usrp_e

9 files changed, 100 insertions, 32 deletions

diff --git a/host/include/uhd/device.hpp b/host/include/uhd/device.hpp
index 4d4196d98..ae75e6dc8 100644
--- a/host/include/uhd/device.hpp
+++ b/host/include/uhd/device.hpp
@@ -83,6 +83,7 @@ public:
      * If the buffer has more samples than the maximum supported,
      * the send method will send the maximum number of samples
      * as supported by the transport and return the number sent.
+     * In this case, the end of burst flag will be forced to false.
      * It is up to the caller to call send again on the un-sent
      * portions of the buffer, until the buffer is exhausted.
      *
@@ -112,6 +113,7 @@ public:
      * and will flag the metadata to show that this is a fragment.
      * The next call to receive, after the remainder becomes exahausted,
      * will perform an over-the-wire receive as usual.
+     * See the rx metadata fragment flags and offset fields for details.
      *
      * This is a blocking call and will not return until the number
      * of samples returned have been written into the buffer.
diff --git a/host/include/uhd/types/device_addr.hpp b/host/include/uhd/types/device_addr.hpp
index 1162884fb..f5dd9371c 100644
--- a/host/include/uhd/types/device_addr.hpp
+++ b/host/include/uhd/types/device_addr.hpp
@@ -32,7 +32,7 @@ namespace uhd{
      *
      * To narrow down the discovery process to a particular device,
      * specify a transport key/value pair specific to your device.
-     * Ex, to find a usrp2: my_dev_addr["addr"] = <resolvable_hostname_or_ip>
+     * Ex, to find a usrp2: my_dev_addr["addr"] = [resolvable_hostname_or_ip]
      *
      * The device address can also be used to pass arguments into
      * the transport layer control to set (for example) buffer sizes.
diff --git a/host/include/uhd/types/dict.hpp b/host/include/uhd/types/dict.hpp
index 7fb712e76..c8fbc5a9f 100644
--- a/host/include/uhd/types/dict.hpp
+++ b/host/include/uhd/types/dict.hpp
@@ -62,7 +62,7 @@ namespace uhd{
 
         /*!
          * Get the number of elements in this dict.
-         * \param the number of elements
+         * \return the number of elements
          */
         std::size_t size(void) const{
             return _map.size();
@@ -73,7 +73,7 @@ namespace uhd{
          * Key order depends on insertion precedence.
          * \return vector of keys
          */
-        std::vector<Key> get_keys(void) const{
+        const std::vector<Key> keys(void) const{
             std::vector<Key> keys;
             BOOST_FOREACH(const pair_t &p, _map){
                 keys.push_back(p.first);
@@ -86,7 +86,7 @@ namespace uhd{
          * Value order depends on insertion precedence.
          * \return vector of values
          */
-        std::vector<Val> get_vals(void) const{
+        const std::vector<Val> vals(void) const{
             std::vector<Val> vals;
             BOOST_FOREACH(const pair_t &p, _map){
                 vals.push_back(p.second);
diff --git a/host/include/uhd/types/metadata.hpp b/host/include/uhd/types/metadata.hpp
index 6e93040d9..20f483bed 100644
--- a/host/include/uhd/types/metadata.hpp
+++ b/host/include/uhd/types/metadata.hpp
@@ -29,11 +29,45 @@ namespace uhd{
      * The receive routines will convert IF data headers into metadata.
      */
     struct UHD_API rx_metadata_t{
-        boost::uint32_t stream_id;
-        time_spec_t time_spec;
+        /*!
+         * Stream IDs may be used to identify source DSP units.
+         * --Not currently used in any known device implementation.--
+         */
         bool has_stream_id;
+        boost::uint32_t stream_id;
+
+        /*!
+         * Time specification:
+         * Set from timestamps on incoming data when provided.
+         */
         bool has_time_spec;
-        bool is_fragment;
+        time_spec_t time_spec;
+
+        /*!
+         * Fragmentation flag and offset:
+         * Similar to IPv4 fragmentation: http://en.wikipedia.org/wiki/IPv4#Fragmentation_and_reassembly
+         * More fragments is true when the input buffer has insufficient size to fit
+         * an entire received packet. More fragments will be false for the last fragment.
+         * The fragment offset is the sample number at the start of the receive buffer.
+         * For non-fragmented receives, the fragment offset should always be zero.
+         */
+        bool more_fragments;
+        size_t fragment_offset;
+
+        /*!
+         * Burst flags:
+         * Start of burst will be true for the first packet in the chain.
+         * End of burst will be true for the last packet in the chain.
+         * --Not currently used in any known device implementation.--
+         */
+        //bool start_of_burst;
+        //bool end_of_burst;
+
+        /*!
+         * Error conditions (TODO):
+         * Previous packets dropped?
+         * Timed-out on receive?
+         */
 
         //default constructor
         rx_metadata_t(void);
@@ -45,10 +79,26 @@ namespace uhd{
      * The send routines will convert the metadata to IF data headers.
      */
     struct UHD_API tx_metadata_t{
-        boost::uint32_t stream_id;
-        time_spec_t time_spec;
+        /*!
+         * Stream IDs may be used to identify destination DSP units.
+         * --Not currently used in any known device implementation.--
+         */
         bool has_stream_id;
+        boost::uint32_t stream_id;
+
+        /*!
+         * Time specification:
+         * Set has time spec to false to perform a send "now".
+         * Or, set to true, and fill in time spec for a send "at".
+         */
         bool has_time_spec;
+        time_spec_t time_spec;
+
+        /*!
+         * Burst flags:
+         * Set start of burst to true for the first packet in the chain.
+         * Set end of burst to true for the last packet in the chain.
+         */
         bool start_of_burst;
         bool end_of_burst;
 
diff --git a/host/include/uhd/types/stream_cmd.hpp b/host/include/uhd/types/stream_cmd.hpp
index 97a6b73ce..41708e2e2 100644
--- a/host/include/uhd/types/stream_cmd.hpp
+++ b/host/include/uhd/types/stream_cmd.hpp
@@ -31,24 +31,32 @@ namespace uhd{
      * Granular control over what the device streams to the host can be
      * achieved through submission of multiple (carefully-crafted) commands.
      *
-     * The stream_now parameter controls when the stream begins.
+     * The mode parameter controls how streaming is issued to the device:
+     *   - "Start continuous" tells the device to stream samples indefinitely.
+     *   - "Stop continuous" tells the device to end continuous streaming.
+     *   - "Num samps and done" tells the device to stream num samps and
+     *      to not expect a future stream command for contiguous samples.
+     *   - "Num samps and more" tells the device to stream num samps and
+     *      to expect a future stream command for contiguous samples.
+     *
+     * The stream now parameter controls when the stream begins.
      * When true, the device will begin streaming ASAP. When false,
      * the device will begin streaming at a time specified by time_spec.
-     *
-     * The continuous parameter controls the number of samples received.
-     * When true, the device continues streaming indefinitely. When false,
-     * the device will stream the number of samples specified by num_samps.
-     *
-     * Standard usage case:
-     * To start continuous streaming, set stream_now to true and continuous to true.
-     * To end continuous streaming, set stream_now to true and continuous to false.
      */
     struct UHD_API stream_cmd_t{
+
+        enum stream_mode_t {
+            STREAM_MODE_START_CONTINUOUS   = 'a',
+            STREAM_MODE_STOP_CONTINUOUS    = 'o',
+            STREAM_MODE_NUM_SAMPS_AND_DONE = 'd',
+            STREAM_MODE_NUM_SAMPS_AND_MORE = 'm'
+        } stream_mode;
+        size_t num_samps;
+
         bool stream_now;
         time_spec_t time_spec;
-        bool continuous;
-        size_t num_samps;
-        stream_cmd_t(void);
+
+        stream_cmd_t(const stream_mode_t &stream_mode);
     };
 
 } //namespace uhd
diff --git a/host/include/uhd/usrp/dsp_props.hpp b/host/include/uhd/usrp/dsp_props.hpp
index 60c0df942..75d8c0a60 100644
--- a/host/include/uhd/usrp/dsp_props.hpp
+++ b/host/include/uhd/usrp/dsp_props.hpp
@@ -24,15 +24,24 @@ namespace uhd{ namespace usrp{
 
     /*!
      * Possible device dsp properties:
-     *   A dsp can have a wide range of possible properties.
-     *   A ddc would have a properties "decim", "freq", "taps"...
-     *   Other properties could be gains, complex scalars, enables...
-     *   For this reason the only required properties of a dsp is a name
-     *   and a property to get list of other possible properties.
+     *   A dsp is a black box fpga component found between
+     *   the over-the-wire data and the codec pins.
+     *
+     *   The host rate can be modified to control resampling.
+     *   Resampling can take the form of decimation, interpolation,
+     *   or more complex fractional resampling techniques.
+     *   As usual, read back the host rate after setting it
+     *   to get the actual rate that was set (implementation dependent).
+     *
+     *   A dsp can also shift the digital stream in frequency.
+     *   Set the shift property and read it back to get actual shift.
      */
     enum dsp_prop_t{
-        DSP_PROP_NAME   = 'n', //ro, std::string
-        DSP_PROP_OTHERS = 'o'  //ro, prop_names_t
+        DSP_PROP_NAME         = 'n', //ro, std::string
+        DSP_PROP_OTHERS       = 'o', //ro, prop_names_t
+        DSP_PROP_FREQ_SHIFT   = 'f', //rw, double Hz
+        DSP_PROP_CODEC_RATE   = 'c', //ro, double Sps
+        DSP_PROP_HOST_RATE    = 'h'  //rw, double Sps
     };
 
 }} //namespace
diff --git a/host/include/uhd/usrp/mboard_props.hpp b/host/include/uhd/usrp/mboard_props.hpp
index cfc1f412e..55c11b822 100644
--- a/host/include/uhd/usrp/mboard_props.hpp
+++ b/host/include/uhd/usrp/mboard_props.hpp
@@ -42,7 +42,8 @@ namespace uhd{ namespace usrp{
         MBOARD_PROP_TX_DBOARD_NAMES = 'V', //ro, prop_names_t
         MBOARD_PROP_CLOCK_CONFIG    = 'C', //rw, clock_config_t
         MBOARD_PROP_TIME_NOW        = 't', //wo, time_spec_t
-        MBOARD_PROP_TIME_NEXT_PPS   = 'T'  //wo, time_spec_t
+        MBOARD_PROP_TIME_NEXT_PPS   = 'T', //wo, time_spec_t
+        MBOARD_PROP_STREAM_CMD      = 's'  //wo, stream_cmd_t
     };
 
 }} //namespace
diff --git a/host/include/uhd/usrp/simple_usrp.hpp b/host/include/uhd/usrp/simple_usrp.hpp
index 2d6ad2a0f..6f74a406b 100644
--- a/host/include/uhd/usrp/simple_usrp.hpp
+++ b/host/include/uhd/usrp/simple_usrp.hpp
@@ -59,7 +59,6 @@ public:
      ******************************************************************/
     virtual void set_rx_rate(double rate) = 0;
     virtual double get_rx_rate(void) = 0;
-    virtual std::vector<double> get_rx_rates(void) = 0;
 
     virtual tune_result_t set_rx_freq(double freq) = 0;
     virtual freq_range_t get_rx_freq_range(void) = 0;
@@ -77,7 +76,6 @@ public:
      ******************************************************************/
     virtual void set_tx_rate(double rate) = 0;
     virtual double get_tx_rate(void) = 0;
-    virtual std::vector<double> get_tx_rates(void) = 0;
 
     virtual tune_result_t set_tx_freq(double freq) = 0;
     virtual freq_range_t get_tx_freq_range(void) = 0;
diff --git a/host/include/uhd/usrp/subdev_props.hpp b/host/include/uhd/usrp/subdev_props.hpp
index 92d18340b..d35793c6b 100644
--- a/host/include/uhd/usrp/subdev_props.hpp
+++ b/host/include/uhd/usrp/subdev_props.hpp
@@ -39,7 +39,7 @@ namespace uhd{ namespace usrp{
         SUBDEV_PROP_QUADRATURE        = 'q', //ro, bool
         SUBDEV_PROP_IQ_SWAPPED        = 'i', //ro, bool
         SUBDEV_PROP_SPECTRUM_INVERTED = 's', //ro, bool
-        SUBDEV_PROP_LO_INTERFERES     = 'l'  //ro, bool
+        SUBDEV_PROP_USE_LO_OFFSET     = 'l'  //ro, bool
         //SUBDEV_PROP_RSSI,              //ro, float //----> not on all boards, use named prop
         //SUBDEV_PROP_BANDWIDTH          //rw, double //----> not on all boards, use named prop
     };