Expanded the UDP api:

We can make simple udp transports for discovery and control.
We can support a udp zero copy transport (currently just asio).
Reworked the io_impl for usrp2 to work with the zero copy api.
So far, all of this untested other than compiling.
A cut-down vrt library is in the works to simplify the io impl.

5 files changed, 159 insertions, 23 deletions

diff --git a/host/include/uhd/transport/CMakeLists.txt b/host/include/uhd/transport/CMakeLists.txt
index b786eb945..ba8b33cc5 100644
--- a/host/include/uhd/transport/CMakeLists.txt
+++ b/host/include/uhd/transport/CMakeLists.txt
@@ -17,6 +17,8 @@
 
 
 INSTALL(FILES
-    udp.hpp
+    smart_buffer.hpp
+    udp_simple.hpp
+    udp_zero_copy.hpp
     DESTINATION ${HEADER_DIR}/uhd/transport
 )
diff --git a/host/include/uhd/transport/smart_buffer.hpp b/host/include/uhd/transport/smart_buffer.hpp
new file mode 100644
index 000000000..914c02f50
--- /dev/null
+++ b/host/include/uhd/transport/smart_buffer.hpp
@@ -0,0 +1,45 @@
+//
+// 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 <boost/asio.hpp>
+#include <boost/utility.hpp>
+#include <boost/shared_ptr.hpp>
+
+#ifndef INCLUDED_UHD_TRANSPORT_SMART_BUFFER_HPP
+#define INCLUDED_UHD_TRANSPORT_SMART_BUFFER_HPP
+
+namespace uhd{ namespace transport{
+
+/*!
+ * A buffer that knows how to free itself:
+ *
+ * This is just the smart buffer interface.
+ * A transport implementation will have its own
+ * internal (custom) smart buffer implementation.
+ *
+ * A smart buffer contains a boost asio const buffer.
+ * On destruction, the buffer contents will be freed.
+ */
+class smart_buffer : boost::noncopyable{
+public:
+    typedef boost::shared_ptr<smart_buffer> sptr;
+    virtual const boost::asio::const_buffer &get(void) const = 0;
+};
+
+}} //namespace
+
+#endif /* INCLUDED_UHD_TRANSPORT_SMART_BUFFER_HPP */
diff --git a/host/include/uhd/transport/udp.hpp b/host/include/uhd/transport/udp_simple.hpp
index 8c6fb096f..8663128ec 100644
--- a/host/include/uhd/transport/udp.hpp
+++ b/host/include/uhd/transport/udp_simple.hpp
@@ -19,32 +19,43 @@
 #include <boost/utility.hpp>
 #include <boost/shared_ptr.hpp>
 
-#ifndef INCLUDED_UHD_TRANSPORT_UDP_HPP
-#define INCLUDED_UHD_TRANSPORT_UDP_HPP
+#ifndef INCLUDED_UHD_TRANSPORT_UDP_SIMPLE_HPP
+#define INCLUDED_UHD_TRANSPORT_UDP_SIMPLE_HPP
 
 namespace uhd{ namespace transport{
 
-class udp : boost::noncopyable{
+class udp_simple : boost::noncopyable{
 public:
-    typedef boost::shared_ptr<udp> sptr;
+    typedef boost::shared_ptr<udp_simple> sptr;
 
     /*!
-     * Make a new udp transport.
+     * Make a new connected udp transport:
+     * This transport is for sending and receiving
+     * between this host and a single endpoint.
+     * The primary usage for this transport will be control transactions.
+     * The underlying implementation is simple and portable (not fast).
+     *
      * The address will be resolved, it can be a host name or ipv4.
      * The port will be resolved, it can be a port type or number.
+     *
      * \param addr a string representing the destination address
      * \param port a string representing the destination port
-     * \param bcast if true, enable the broadcast option on the socket
      */
-    static sptr make(const std::string &addr, const std::string &port, bool bcast = false);
+    static sptr make_connected(const std::string &addr, const std::string &port);
 
     /*!
-     * Send a vector of buffer (like send_msg).
-     * Blocks until the data is sent.
-     * \param buffs a vector of asio buffers
-     * \return the number of bytes sent
+     * Make a new broadcasting udp transport:
+     * This transport can send udp broadcast datagrams
+     * and receive datagrams from multiple sources.
+     * The primary usage for this transport will be to discover devices.
+     *
+     * The address will be resolved, it can be a host name or ipv4.
+     * The port will be resolved, it can be a port type or number.
+     *
+     * \param addr a string representing the destination address
+     * \param port a string representing the destination port
      */
-    virtual size_t send(const std::vector<boost::asio::const_buffer> &buffs) = 0;
+    static sptr make_broadcast(const std::string &addr, const std::string &port);
 
     /*!
      * Send a single buffer.
@@ -55,15 +66,7 @@ public:
     virtual size_t send(const boost::asio::const_buffer &buff) = 0;
 
     /*!
-     * Receive a buffer. Write into the memory provided.
-     * Returns empty when data is not available.
-     * \param buffs a vector of asio buffers
-     * \return the number of bytes received.
-     */
-    virtual size_t recv(const std::vector<boost::asio::mutable_buffer> &buffs) = 0;
-
-    /*!
-     * Receive a buffer. Write into the memory provided.
+     * Receive into the provided buffer.
      * Returns empty when data is not available.
      * \param buff a mutable buffer to receive into
      * \return the number of bytes received.
@@ -73,4 +76,4 @@ public:
 
 }} //namespace
 
-#endif /* INCLUDED_UHD_TRANSPORT_UDP_HPP */
+#endif /* INCLUDED_UHD_TRANSPORT_UDP_SIMPLE_HPP */
diff --git a/host/include/uhd/transport/udp_zero_copy.hpp b/host/include/uhd/transport/udp_zero_copy.hpp
new file mode 100644
index 000000000..9c3505dd6
--- /dev/null
+++ b/host/include/uhd/transport/udp_zero_copy.hpp
@@ -0,0 +1,76 @@
+//
+// 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/transport/smart_buffer.hpp>
+#include <boost/asio.hpp>
+#include <boost/utility.hpp>
+#include <boost/shared_ptr.hpp>
+
+#ifndef INCLUDED_UHD_TRANSPORT_UDP_ZERO_COPY_HPP
+#define INCLUDED_UHD_TRANSPORT_UDP_ZERO_COPY_HPP
+
+namespace uhd{ namespace transport{
+
+/*!
+ * A zero copy udp transport provides an efficient way to handle data.
+ * by avoiding the extra copy when recv() is called on the socket.
+ * Rather, the zero copy transport gives the caller a memory reference.
+ * The caller informs the transport when it is finished with the reference.
+ *
+ * On linux systems, the zero copy transport can use a kernel packet ring.
+ * If no platform specific solution is available, make returns a boost asio
+ * implementation that wraps the functionality around a standard recv() call.
+ */
+class udp_zero_copy : boost::noncopyable{
+public:
+    typedef boost::shared_ptr<udp_zero_copy> sptr;
+
+    /*!
+     * Make a new zero copy udp transport:
+     * This transport is for sending and receiving
+     * between this host and a single endpoint.
+     * The primary usage for this transport will be data transactions.
+     * The underlying implementation is fast and platform specific.
+     *
+     * The address will be resolved, it can be a host name or ipv4.
+     * The port will be resolved, it can be a port type or number.
+     *
+     * \param addr a string representing the destination address
+     * \param port a string representing the destination port
+     */
+    static sptr make(const std::string &addr, const std::string &port);
+
+    /*!
+     * Send a single buffer.
+     * Blocks until the data is sent.
+     * \param buff single asio buffer
+     * \return the number of bytes sent
+     */
+    virtual size_t send(const boost::asio::const_buffer &buff) = 0;
+
+    /*!
+     * Receive a buffer.
+     * The memory is managed by the implementation.
+     * Returns an empty buffer when data is not available.
+     * \return a smart buffer with memory and size
+     */
+    virtual smart_buffer::sptr recv(void) = 0;
+};
+
+}} //namespace
+
+#endif /* INCLUDED_UHD_TRANSPORT_UDP_ZERO_COPY_HPP */
diff --git a/host/include/uhd/usrp/usrp2.hpp b/host/include/uhd/usrp/usrp2.hpp
index da7ec595a..b13786546 100644
--- a/host/include/uhd/usrp/usrp2.hpp
+++ b/host/include/uhd/usrp/usrp2.hpp
@@ -29,6 +29,11 @@ class usrp2 : public device{
 public:
     /*!
      * Discover usrp2 devices over the ethernet.
+     *
+     * Recommended key/value pairs for the device hint address:
+     * hint["addr"] = address, where address is a resolvable address
+     * or ip address, which may or may not be a broadcast address.
+     *
      * This static method will be called by the device::discover.
      * \param hint a device addr with the usrp2 address filled in
      * \return a vector of device addresses for all usrp2s found
@@ -37,6 +42,11 @@ public:
 
     /*!
      * Make a usrp2 from a device address.
+     *
+     * Required key/value pairs for the device address:
+     * hint["addr"] = address, where address is a resolvable address
+     * or ip address, which must be the specific address of a usrp2.
+     *
      * \param addr the device address
      * \return a device sptr to a new usrp2
      */