Split metadata into rx and tx specific metadata.

The rx metadata has fragment flags and the tx metatdata has burst flags.
Made the io impl for usrp2 rx routine fill in the rx metatdata fragment flag.
Added device documentation for send and recv in regards to fragmentation.

3 files changed, 46 insertions, 20 deletions

diff --git a/host/include/uhd/device.hpp b/host/include/uhd/device.hpp
index ba5337d33..1a52867c9 100644
--- a/host/include/uhd/device.hpp
+++ b/host/include/uhd/device.hpp
@@ -70,6 +70,13 @@ public:
     /*!
      * Send a buffer containing IF data with its metadata.
      *
+     * Send handles fragmentation as follows:
+     * 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.
+     * It is up to the caller to call send again on the un-sent
+     * portions of the buffer, until the buffer is exhausted.
+     *
      * \param buff a buffer pointing to some read-only memory
      * \param metadata data describing the buffer's contents
      * \param the type of data loaded in the buffer (32fc, 16sc)
@@ -77,13 +84,23 @@ public:
      */
     virtual size_t send(
         const boost::asio::const_buffer &buff,
-        const metadata_t &metadata,
+        const tx_metadata_t &metadata,
         const std::string &type = "32fc"
     ) = 0;
 
     /*!
      * Receive a buffer containing IF data and its metadata.
      *
+     * Receive handles fragmentation as follows:
+     * If the buffer has insufficient space to hold all samples
+     * that were received in a single packet over-the-wire,
+     * then the buffer will be completely filled and the implementation
+     * will hold a pointer into the remaining portion of the packet.
+     * Subsequent calls will load from the remainder of the packet,
+     * 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.
+     *
      * \param buff the buffer to fill with IF data
      * \param metadata data to fill describing the buffer
      * \param the type of data to fill into the buffer (32fc, 16sc)
@@ -91,7 +108,7 @@ public:
      */
     virtual size_t recv(
         const boost::asio::mutable_buffer &buff,
-        metadata_t &metadata,
+        rx_metadata_t &metadata,
         const std::string &type = "32fc"
     ) = 0;
 };
diff --git a/host/include/uhd/metadata.hpp b/host/include/uhd/metadata.hpp
index 70842e7bc..0588ef0ed 100644
--- a/host/include/uhd/metadata.hpp
+++ b/host/include/uhd/metadata.hpp
@@ -23,12 +23,27 @@
 namespace uhd{
 
 /*!
- * Metadata structure for describing the IF data.
- * Includes stream ID, time specification, and burst flags.
+ * RX metadata structure for describing sent IF data.
+ * Includes stream ID, time specification, and fragmentation flags.
  * The receive routines will convert IF data headers into metadata.
+ */
+struct rx_metadata_t{
+    uint32_t stream_id;
+    bool has_stream_id;
+    time_spec_t time_spec;
+    bool has_time_spec;
+    bool is_fragment;
+
+    //default constructor
+    rx_metadata_t(void);
+};
+
+/*!
+ * TX metadata structure for describing received IF data.
+ * Includes stream ID, time specification, and burst flags.
  * The send routines will convert the metadata to IF data headers.
  */
-struct metadata_t{
+struct tx_metadata_t{
     uint32_t stream_id;
     bool has_stream_id;
     time_spec_t time_spec;
@@ -36,14 +51,8 @@ struct metadata_t{
     bool start_of_burst;
     bool end_of_burst;
 
-    metadata_t(void){
-        stream_id = 0;
-        has_stream_id = false;
-        time_spec = time_spec_t();
-        has_time_spec = false;
-        start_of_burst = false;
-        end_of_burst = false;
-    }
+    //default constructor
+    tx_metadata_t(void);
 };
 
 } //namespace uhd
diff --git a/host/include/uhd/transport/vrt.hpp b/host/include/uhd/transport/vrt.hpp
index 2fb90a497..1700d2785 100644
--- a/host/include/uhd/transport/vrt.hpp
+++ b/host/include/uhd/transport/vrt.hpp
@@ -37,12 +37,12 @@ namespace vrt{
      * \param packet_count the packet count sequence number
      */
     void pack(
-        const metadata_t &metadata, //input
-        uint32_t *header_buff,      //output
-        size_t &num_header_words32, //output
-        size_t num_payload_words32, //input
-        size_t &num_packet_words32, //output
-        size_t packet_count         //input
+        const tx_metadata_t &metadata, //input
+        uint32_t *header_buff,         //output
+        size_t &num_header_words32,    //output
+        size_t num_payload_words32,    //input
+        size_t &num_packet_words32,    //output
+        size_t packet_count            //input
     );
 
     /*!
@@ -55,7 +55,7 @@ namespace vrt{
      * \param packet_count the packet count sequence number
      */
     void unpack(
-        metadata_t &metadata,            //output
+        rx_metadata_t &metadata,         //output
         const uint32_t *header_buff,     //input
         size_t &num_header_words32,      //output
         size_t &num_payload_words32,     //output