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.

9 files changed, 114 insertions, 44 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
diff --git a/host/lib/CMakeLists.txt b/host/lib/CMakeLists.txt
index 390349906..b1daf22d1 100644
--- a/host/lib/CMakeLists.txt
+++ b/host/lib/CMakeLists.txt
@@ -22,6 +22,7 @@ SET(libuhd_sources
     device.cpp
     device_addr.cpp
     gain_handler.cpp
+    metadata.cpp
     wax.cpp
     transport/udp_simple.cpp
     transport/vrt.cpp
diff --git a/host/lib/metadata.cpp b/host/lib/metadata.cpp
new file mode 100644
index 000000000..40fdb7c73
--- /dev/null
+++ b/host/lib/metadata.cpp
@@ -0,0 +1,37 @@
+//
+// Copyright 2010 Ettus Research LLC
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+#include <uhd/metadata.hpp>
+
+using namespace uhd;
+
+rx_metadata_t::rx_metadata_t(void){
+    stream_id = 0;
+    has_stream_id = false;
+    time_spec = time_spec_t();
+    has_time_spec = false;
+    is_fragment = false;
+}
+
+tx_metadata_t::tx_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;
+}
diff --git a/host/lib/transport/vrt.cpp b/host/lib/transport/vrt.cpp
index 19bfc1d19..5029df217 100644
--- a/host/lib/transport/vrt.cpp
+++ b/host/lib/transport/vrt.cpp
@@ -22,12 +22,12 @@
 using namespace uhd::transport;
 
 void vrt::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
 ){
     uint32_t vrt_hdr_flags = 0;
     num_header_words32 = 1;
@@ -58,7 +58,7 @@ void vrt::pack(
 }
 
 void vrt::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
@@ -66,7 +66,7 @@ void vrt::unpack(
     size_t &packet_count             //output
 ){
     //clear the metadata
-    metadata = metadata_t();
+    metadata = rx_metadata_t();
 
     //extract vrt header
     uint32_t vrt_hdr_word = ntohl(header_buff[0]);
diff --git a/host/lib/usrp/usrp2/io_impl.cpp b/host/lib/usrp/usrp2/io_impl.cpp
index 642b6b08b..5529cfe57 100644
--- a/host/lib/usrp/usrp2/io_impl.cpp
+++ b/host/lib/usrp/usrp2/io_impl.cpp
@@ -119,7 +119,7 @@ static inline void usrp2_items_to_host_items(
 /***********************************************************************
  * Receive Raw Data
  **********************************************************************/
-void usrp2_impl::recv_raw(uhd::metadata_t &metadata){
+void usrp2_impl::recv_raw(rx_metadata_t &metadata){
     //do a receive
     _rx_smart_buff = _data_transport->recv();
 
@@ -161,8 +161,8 @@ void usrp2_impl::recv_raw(uhd::metadata_t &metadata){
  * Send Data
  **********************************************************************/
 size_t usrp2_impl::send(
-    const boost::asio::const_buffer &buff,
-    const uhd::metadata_t &metadata,
+    const asio::const_buffer &buff,
+    const tx_metadata_t &metadata,
     const std::string &type
 ){
     uint32_t tx_mem[_mtu/sizeof(uint32_t)];
@@ -210,13 +210,19 @@ size_t usrp2_impl::send(
  * Receive Data
  **********************************************************************/
 size_t usrp2_impl::recv(
-    const boost::asio::mutable_buffer &buff,
-    uhd::metadata_t &metadata,
+    const asio::mutable_buffer &buff,
+    rx_metadata_t &metadata,
     const std::string &type
 ){
     //perform a receive if no rx data is waiting to be copied
-    if (asio::buffer_size(_rx_copy_buff) == 0) recv_raw(metadata);
-    //TODO otherwise flag the metadata to show that is is a fragment
+    if (asio::buffer_size(_rx_copy_buff) == 0){
+        recv_raw(metadata);
+    }
+    //otherwise flag the metadata to show that is is a fragment
+    else{
+        metadata = rx_metadata_t();
+        metadata.is_fragment = true;
+    }
 
     //extract the number of samples available to copy
     //and a pointer into the usrp2 received items memory
diff --git a/host/lib/usrp/usrp2/usrp2_impl.hpp b/host/lib/usrp/usrp2/usrp2_impl.hpp
index 083ad7096..f4e6054bd 100644
--- a/host/lib/usrp/usrp2/usrp2_impl.hpp
+++ b/host/lib/usrp/usrp2/usrp2_impl.hpp
@@ -100,12 +100,12 @@ public:
     double get_master_clock_freq(void);
 
     //the io interface
-    size_t send(const boost::asio::const_buffer &, const uhd::metadata_t &, const std::string &);
-    size_t recv(const boost::asio::mutable_buffer &, uhd::metadata_t &, const std::string &);
+    size_t send(const boost::asio::const_buffer &, const uhd::tx_metadata_t &, const std::string &);
+    size_t recv(const boost::asio::mutable_buffer &, uhd::rx_metadata_t &, const std::string &);
 
 private:
     //the raw io interface (samples are in the usrp2 native format)
-    void recv_raw(uhd::metadata_t &);
+    void recv_raw(uhd::rx_metadata_t &);
     uhd::dict<uint32_t, size_t> _tx_stream_id_to_packet_seq;
     uhd::dict<uint32_t, size_t> _rx_stream_id_to_packet_seq;
     static const size_t _mtu = 1500; //FIXME we have no idea
diff --git a/host/test/vrt_test.cpp b/host/test/vrt_test.cpp
index a4fad78fc..d80908c74 100644
--- a/host/test/vrt_test.cpp
+++ b/host/test/vrt_test.cpp
@@ -21,7 +21,7 @@
 using namespace uhd::transport;
 
 static void pack_and_unpack(
-    const uhd::metadata_t &metadata,
+    const uhd::tx_metadata_t &metadata,
     size_t num_payload_words32,
     size_t packet_count
 ){
@@ -39,7 +39,7 @@ static void pack_and_unpack(
         packet_count         //input
     );
 
-    uhd::metadata_t metadata_out;
+    uhd::rx_metadata_t metadata_out;
     size_t num_header_words32_out;
     size_t num_payload_words32_out;
     size_t packet_count_out;
@@ -70,19 +70,19 @@ static void pack_and_unpack(
 }
 
 BOOST_AUTO_TEST_CASE(test_with_none){
-    uhd::metadata_t metadata;
+    uhd::tx_metadata_t metadata;
     pack_and_unpack(metadata, 300, 1);
 }
 
 BOOST_AUTO_TEST_CASE(test_with_sid){
-    uhd::metadata_t metadata;
+    uhd::tx_metadata_t metadata;
     metadata.has_stream_id = true;
     metadata.stream_id = 6;
     pack_and_unpack(metadata, 400, 2);
 }
 
 BOOST_AUTO_TEST_CASE(test_with_time_spec){
-    uhd::metadata_t metadata;
+    uhd::tx_metadata_t metadata;
     metadata.has_time_spec = true;
     metadata.time_spec.secs = 7;
     metadata.time_spec.ticks = 2000;
@@ -90,7 +90,7 @@ BOOST_AUTO_TEST_CASE(test_with_time_spec){
 }
 
 BOOST_AUTO_TEST_CASE(test_with_sid_and_time_spec){
-    uhd::metadata_t metadata;
+    uhd::tx_metadata_t metadata;
     metadata.has_stream_id = true;
     metadata.stream_id = 2;
     metadata.has_time_spec = true;