usrp1: Additional comments on libusb transport implemenation

5 files changed, 87 insertions, 3 deletions

diff --git a/host/lib/transport/libusb1_base.cpp b/host/lib/transport/libusb1_base.cpp
index 493d4eff3..92dcd969f 100644
--- a/host/lib/transport/libusb1_base.cpp
+++ b/host/lib/transport/libusb1_base.cpp
@@ -21,6 +21,15 @@
 
 using namespace uhd::transport;
 
+/**********************************************************
+ * Helper Methods
+ **********************************************************/
+/*
+ * Check for FSF device
+ * Compare the device's descriptor Vendor ID
+ * \param dev pointer to libusb_device
+ * \return true if Vendor ID matches 0xfffe
+ */
 bool check_fsf_device(libusb_device *dev)
 {
     libusb_device_descriptor desc;
@@ -32,6 +41,9 @@ bool check_fsf_device(libusb_device *dev)
     return desc.idVendor == 0xfffe;
 }
 
+/**********************************************************
+ * libusb namespace 
+ **********************************************************/
 void libusb::init(libusb_context **ctx, int debug_level)
 {
     if (libusb_init(ctx) < 0)
diff --git a/host/lib/transport/libusb1_base.hpp b/host/lib/transport/libusb1_base.hpp
index 708a42c73..442f89ded 100644
--- a/host/lib/transport/libusb1_base.hpp
+++ b/host/lib/transport/libusb1_base.hpp
@@ -25,17 +25,77 @@
 namespace uhd { namespace transport {
 
 namespace libusb {
+    /*
+     * Initialize libusb and set debug level
+     * Takes a pointer to context pointer because that's
+     * how libusb rolls. Debug levels.
+     *     
+     *   Level 0: no messages ever printed by the library (default)
+     *   Level 1: error messages are printed to stderr
+     *   Level 2: warning and error messages are printed to stderr
+     *   Level 3: informational messages are printed to stdout, warning
+     *            and error messages are printed to stderr
+     *
+     * \param ctx pointer to context pointer
+     * \param debug_level
+     */
     void init(libusb_context **ctx, int debug_level);
 
+    /*
+     * Get a list of Free Software Foundation devices (Vendor ID 0xfffe)
+     * As opposed to the public USB device handle interface, which returns
+     * generic identifiers, this call returns device pointers speficic
+     * to libusb.
+     * \param ctx the libusb context used for init
+     * \return a vector of libusb devices
+     */
     std::vector<libusb_device *> get_fsf_device_list(libusb_context *ctx);
 
+    /*
+     * Open the device specified by a generic handle
+     * Find the libusb_device cooresponding to the generic handle
+     * and open it for I/O, which returns a libusb_device_handle
+     * ready for an interface
+     * \param ctx the libusb context used for init
+     * \return a libusb_device_handle ready for action 
+     */
     libusb_device_handle *open_device(libusb_context *ctx,
                                       usb_device_handle::sptr handle);
 
+    /*
+     * Compare a libusb device with a generic handle 
+     * Check the descriptors and open the device to check the
+     * serial number string. Compare values against the given
+     * handle. The libusb context is already implied in the
+     * libusb_device.
+     * \param dev a libusb_device pointer
+     * \param handle a generic handle specifier
+     * \return true if handle and device match, false otherwise
+     */
     bool compare_device(libusb_device *dev, usb_device_handle::sptr handle);
 
+    /*
+     * Open an interface to the device
+     * This is a logical operation for operating system housekeeping as
+     * nothing is sent over the bus. The interface much correspond
+     * to the USB device descriptors.
+     * \param dev_handle libusb handle to an opened device
+     * \param interface integer of the interface to use
+     * \return true on success, false on error
+     */
     bool open_interface(libusb_device_handle *dev_handle, int interface);
 
+    /*
+     * Get serial number 
+     * The standard USB device descriptor contains an index to an
+     * actual serial number string descriptor. The index is readily
+     * readble, but the string descriptor requires probing the device.
+     * Because this call attempts to open the device, it may not
+     * succeed because not all USB devices are readily opened.
+     * The default language is used for the request (English).
+     * \param dev a libusb_device pointer
+     * \return string serial number or 0 on error or unavailablity
+     */
     std::string get_serial(libusb_device *dev);
 }
 
diff --git a/host/lib/transport/libusb1_control.cpp b/host/lib/transport/libusb1_control.cpp
index 4b827c350..3531128b2 100644
--- a/host/lib/transport/libusb1_control.cpp
+++ b/host/lib/transport/libusb1_control.cpp
@@ -48,8 +48,15 @@ libusb_control_impl::libusb_control_impl(usb_device_handle::sptr handle)
 {
     libusb::init(&_ctx, libusb_debug_level);
 
+    // Find and open the libusb_device corresponding to the
+    // given handle and return the libusb_device_handle
+    // that can be used for I/O purposes.
     _dev_handle = libusb::open_device(_ctx, handle);
 
+    // Open USB interfaces for control using magic value
+    // IN interface:      2
+    // OUT interface:     1
+    // Control interface: 0
     libusb::open_interface(_dev_handle, 0);
 }
 
diff --git a/host/lib/transport/libusb1_device_handle.cpp b/host/lib/transport/libusb1_device_handle.cpp
index 3476fdc4e..5d9d8faf0 100644
--- a/host/lib/transport/libusb1_device_handle.cpp
+++ b/host/lib/transport/libusb1_device_handle.cpp
@@ -22,6 +22,9 @@ using namespace uhd::transport;
 
 const int libusb_debug_level = 0;
 
+/****************************************************************
+ * libusb USB device handle implementation class
+ ***************************************************************/
 class libusb1_device_handle_impl : public usb_device_handle {
 public:
     libusb1_device_handle_impl(std::string serial,
diff --git a/host/lib/transport/libusb1_zero_copy.cpp b/host/lib/transport/libusb1_zero_copy.cpp
index 518b8baf0..b890a87f9 100644
--- a/host/lib/transport/libusb1_zero_copy.cpp
+++ b/host/lib/transport/libusb1_zero_copy.cpp
@@ -30,9 +30,11 @@ const int libusb_timeout = 0;
 
 /***********************************************************************
  * Helper functions
- *
- * Print to stdout the values of a libusb_transfer struct
  ***********************************************************************/
+/*
+ * Print the values of a libusb_transfer struct
+ * http://libusb.sourceforge.net/api-1.0/structlibusb__transfer.html
+ */
 void pp_transfer(libusb_transfer *lut)
 {
     std::cout << "Libusb transfer"       << std::endl;
@@ -46,7 +48,7 @@ void pp_transfer(libusb_transfer *lut)
 }
 
 /***********************************************************************
- * USB asynchronous phony zero_copy endpoint
+ * USB asynchronous zero_copy endpoint
  *   This endpoint implementation provides asynchronous I/O to libusb-1.0
  *   devices. Each endpoint is directional and two can be combined to
  *   create a bidirectional interface. It is a zero copy implementation