usrp1: Add USB transport interfaces

This patch adds generic interfaces for control and zero-copy
transport of data between the host and a slave device. The
interfaces are separate and generic to accommodate multiple
implementations that may include cross platform libraries
such as libusb or a platform specific implementation such as
Linux usbfs.

5 files changed, 192 insertions, 0 deletions

diff --git a/host/include/uhd/transport/CMakeLists.txt b/host/include/uhd/transport/CMakeLists.txt
index 93e9a6485..dd1a20eed 100644
--- a/host/include/uhd/transport/CMakeLists.txt
+++ b/host/include/uhd/transport/CMakeLists.txt
@@ -25,6 +25,8 @@ INSTALL(FILES
     if_addrs.hpp
     udp_simple.hpp
     udp_zero_copy.hpp
+    usb_control.hpp
+    usb_zero_copy.hpp
     vrt_if_packet.hpp
     zero_copy.hpp
     DESTINATION ${INCLUDE_DIR}/uhd/transport
diff --git a/host/include/uhd/transport/usb_control.hpp b/host/include/uhd/transport/usb_control.hpp
new file mode 100644
index 000000000..6b5591a21
--- /dev/null
+++ b/host/include/uhd/transport/usb_control.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/>.
+//
+
+#ifndef INCLUDED_UHD_TRANSPORT_USB_CONTROL_HPP
+#define INCLUDED_UHD_TRANSPORT_USB_CONTROL_HPP
+
+#include <uhd/config.hpp>
+#include <uhd/types/usb_descriptor.hpp>
+#include <boost/utility.hpp>
+#include <boost/shared_ptr.hpp>
+#include <vector>
+
+namespace uhd { namespace transport {
+
+class UHD_API usb_control : boost::noncopyable {
+public:
+    typedef boost::shared_ptr<usb_control> sptr;
+
+    /*!
+     * Create a new usb control transport:
+     * This transport is for sending and receiving control information from
+     * the host to device using the Default Control Pipe.
+     *
+     * \param descriptor a descriptor that identifies a USB device
+     */
+    static sptr make(usb_descriptor_t descriptor);
+
+    /*!
+     * Submit a USB device request:
+     * Blocks until the request returns
+     *
+     * For format and corresponding USB request fields
+     * see USB Specification Revision 2.0 - 9.3 USB Device Requests
+     *
+     * Usage is device specific
+     *
+     * \param request_type 1-byte bitmask (bmRequestType)
+     * \param request      1-byte (bRequest)
+     * \param value        2-byte (wValue)
+     * \param index        2-byte (wIndex)
+     * \param buff         buffer to hold send or receive data
+     * \param length       2-byte (wLength)
+     * \return             number of bytes submitted
+     */
+    virtual size_t submit(boost::uint8_t request_type,
+                          boost::uint8_t request,
+                          boost::uint16_t value,
+                          boost::uint16_t index, 
+                          unsigned char *buff,
+                          boost::uint16_t length) = 0; 
+
+    /*!
+     * Get a vector of USB device descriptors 
+     *
+     * \return a vector of usb_descriptors
+     */
+    static usb_descriptors_t get_device_list();
+};
+
+}} //namespace
+
+#endif /* INCLUDED_UHD_TRANSPORT_USB_CONTROL_HPP */
diff --git a/host/include/uhd/transport/usb_zero_copy.hpp b/host/include/uhd/transport/usb_zero_copy.hpp
new file mode 100644
index 000000000..7b9692fa5
--- /dev/null
+++ b/host/include/uhd/transport/usb_zero_copy.hpp
@@ -0,0 +1,64 @@
+//
+// 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/>.
+//
+
+#ifndef INCLUDED_UHD_TRANSPORT_USB_ZERO_COPY_HPP
+#define INCLUDED_UHD_TRANSPORT_USB_ZERO_COPY_HPP
+
+#include <uhd/config.hpp>
+#include <uhd/types/usb_descriptor.hpp>
+#include <uhd/transport/zero_copy.hpp>
+#include <boost/shared_ptr.hpp>
+
+namespace uhd { namespace transport {
+
+/*!
+ * A zero copy usb transport provides an efficient way to handle data.
+ * by avoiding the extra copy when recv() or send() is called on the handle.
+ * Rather, the zero copy transport gives the caller memory references.
+ * 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 functionality around standard send/recv calls.
+ */
+class UHD_API usb_zero_copy : public virtual zero_copy_if {
+public:
+    typedef boost::shared_ptr<usb_zero_copy> sptr;
+
+    /*!
+     * Make a new zero copy usb transport:
+     * This transport is for sending and receiving between the host
+     * and a pair of USB bulk transfer endpoints.
+     * The primary usage for this transport is data transactions.
+     * The underlying implementation may be platform specific.
+     *
+     * \param descriptor a USB descriptor identifying the device
+     * \param rx_endpoint an integer specifiying an IN endpoint number 
+     * \param tx_endpoint an integer specifiying an OUT endpoint number
+     * \param buff_size total number of bytes of buffer space to allocate 
+     * \param block_size number of bytes allocated for each I/O transaction 
+     */
+    static sptr make(usb_descriptor_t descriptor,
+                     unsigned int rx_endpoint,
+                     unsigned int tx_endpoint,
+		     size_t buff_size = 0, 
+                     size_t block_size = 0);
+};
+
+}} //namespace
+
+#endif /* INCLUDED_UHD_TRANSPORT_USB_ZERO_COPY_HPP */
diff --git a/host/include/uhd/types/CMakeLists.txt b/host/include/uhd/types/CMakeLists.txt
index dbce21c98..8e302eed2 100644
--- a/host/include/uhd/types/CMakeLists.txt
+++ b/host/include/uhd/types/CMakeLists.txt
@@ -29,5 +29,6 @@ INSTALL(FILES
     stream_cmd.hpp
     time_spec.hpp
     tune_result.hpp
+    usb_descriptor.hpp
     DESTINATION ${INCLUDE_DIR}/uhd/types
 )
diff --git a/host/include/uhd/types/usb_descriptor.hpp b/host/include/uhd/types/usb_descriptor.hpp
new file mode 100644
index 000000000..0e4c8c369
--- /dev/null
+++ b/host/include/uhd/types/usb_descriptor.hpp
@@ -0,0 +1,49 @@
+//
+// 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/>.
+//
+
+#ifndef INCLUDED_UHD_TYPES_USB_DESCRIPTOR_HPP
+#define INCLUDED_UHD_TYPES_USB_DESCRIPTOR_HPP
+
+#include <uhd/config.hpp>
+#include <boost/cstdint.hpp>
+#include <vector>
+#include <string>
+
+namespace uhd{
+
+    /*!
+     * The USB descriptor struct holds identity information for a USB device
+     */
+    struct UHD_API usb_descriptor_t{
+        std::string serial;
+        boost::uint16_t vendor_id;
+        boost::uint16_t product_id;
+        boost::uint16_t device_addr;
+
+        /*!
+         * Create a pretty print string for this USB descriptor struct.
+         * \return the printable string
+         */
+        std::string to_pp_string(void) const;
+    };
+
+    //handy typde for a vector of usb descriptors
+    typedef std::vector<usb_descriptor_t> usb_descriptors_t;
+
+} //namespace uhd
+
+#endif /* INCLUDED_UHD_TYPES_USB_DESCRIPTOR_HPP */