extended stream cmd with mode enum, and extended fragment flags in metadata

3 files changed, 76 insertions, 17 deletions

diff --git a/host/include/uhd/device.hpp b/host/include/uhd/device.hpp
index 4d4196d98..bf7e0753d 100644
--- a/host/include/uhd/device.hpp
+++ b/host/include/uhd/device.hpp
@@ -112,6 +112,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/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..ff063af29 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