Merge remote branch 'origin/usrp_e_next' into usrp_e_next

8 files changed, 180 insertions, 60 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index bbb8812b0..65db3befc 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -25,6 +25,7 @@ SET(manual_sources
     dboards.rst
     general.rst
     images.rst
+    transport.rst
     usrp1.rst
     usrp2.rst
 )
diff --git a/host/docs/build.rst b/host/docs/build.rst
index f37b5dce7..a41ce8331 100644
--- a/host/docs/build.rst
+++ b/host/docs/build.rst
@@ -47,7 +47,7 @@ CMake
 Boost
 ^^^^^^^^^^^^^^^^
 * **Purpose:** C++ library
-* **Version:** at least 3.6 unix, at least 4.0 windows
+* **Version:** at least 1.36 unix, at least 1.40 windows
 * **Usage:** build time + run time (required)
 * **Download URL:** http://www.boost.org/users/download/
 * **Download URL (windows installer):** http://www.boostpro.com/download
@@ -58,7 +58,8 @@ LibUSB
 * **Purpose:** USB-based hardware support
 * **Version:** at least 1.0
 * **Usage:** build time + run time (optional)
-* **Download URL:** http://www.libusb.org/
+* **Download URL:** http://sourceforge.net/projects/libusb/files/libusb-1.0/
+* **Download URL (windows binaries):** http://www.libusb.org/wiki/windows_backend#LatestBinarySnapshots
 
 ^^^^^^^^^^^^^^^^
 Python
@@ -152,6 +153,19 @@ Generate the project with cmake
 * Click generate and a project file will be created in the build directory.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+LibUSB cmake notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+On Windows, cmake does not have the advantage of pkg-config,
+so we must manually tell cmake how to locate the LibUSB header and lib.
+
+From the cmake gui, select "Advanded View":
+
+* Set LIBUSB_INCLUDE_DIR to the directory with "libusb.h".
+* Set LIBUSB_LIBRARIES to the full path for "libusb-1.0.lib".
+
+Then check the boxes to enable USRP1 support, click configure and generate.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Build the project in MSVC
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Open the generated project file in MSVC.
@@ -177,3 +191,8 @@ Setup the PATH environment variable
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Add the boost library path to %PATH% (usually c:\\program files\\boost\\<version>\\lib)
 * Add the uhd library path to %PATH% (usually c:\\program files\\uhd\\lib)
+* Add the libusb library to %PATH% (if using usb support)
+
+**Note:**
+The interface for editing environment variable paths in Windows is very poor.
+I recommend using "Rapid Environment Editor" (http://www.rapidee.com) over the default editor.
diff --git a/host/docs/coding.rst b/host/docs/coding.rst
index d6a19d250..7533445ea 100644
--- a/host/docs/coding.rst
+++ b/host/docs/coding.rst
@@ -41,13 +41,13 @@ The single usrp provides ways to:
 See the documentation in *usrp/single_usrp.hpp* for reference.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-High-Level: The mimo usrp
+High-Level: The multi usrp
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The mimo usrp API provides a wrapper around a device that represents several motherboards.
+The multi usrp API provides a wrapper around a device that represents several motherboards.
 This API provides convenience calls just like the single usrp,
 however the calls either work across all channels in the configuration,
 or take a channel argument to specify which channel to configure.
-The mimo usrp provides ways to:
+The multi usrp provides ways to:
 
 * Set and get the sample rate across all channels.
 * Issue a stream command across all channels.
@@ -57,7 +57,7 @@ The mimo usrp provides ways to:
 * Tune individual DSPs and daughterboards.
 * Get the underlying device (as discussed above).
 
-See the documentation in *usrp/mimo_usrp.hpp* for reference.
+See the documentation in *usrp/multi_usrp.hpp* for reference.
 
 ------------------------------------------------------------------------
 Integrating custom hardware
diff --git a/host/docs/dboards.rst b/host/docs/dboards.rst
index 738a0696d..d93fb9d6a 100644
--- a/host/docs/dboards.rst
+++ b/host/docs/dboards.rst
@@ -26,6 +26,10 @@ The boards have no tunable elements or programmable gains.
 Though the magic of aliasing, you can down-convert signals
 greater than the Nyquist rate of the ADC.
 
+BasicRX Bandwidth (Hz): 250M
+
+LFRX Bandwidth (Hz): 30M
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Basic TX and and LFTX
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -40,6 +44,10 @@ The boards have no tunable elements or programmable gains.
 Though the magic of aliasing, you can up-convert signals
 greater than the Nyquist rate of the DAC.
 
+BasicTX Bandwidth (Hz): 250M
+
+LFTX Bandwidth (Hz): 30M
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 DBSRX
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -49,10 +57,12 @@ Receive Antennas: **J3**
 
 The board has no user selectable antenna setting
 
-Recieve Gains: 
+Receive Gains: 
     **GC1**, Range: 0-56dB
     **GC2**, Range: 0-24dB
 
+Bandwidth (Hz): 8M-66M
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 RFX Series
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -64,26 +74,29 @@ The user may set the receive antenna to be TX/RX or RX2.
 However, when using an RFX board in full-duplex mode,
 the receive antenna will always be set to RX2, regardless of the settings.
 
-Recieve Gains: **PGA0**, Range: 0-70dB (except RFX400 range is 0-45dB)
+Receive Gains: **PGA0**, Range: 0-70dB (except RFX400 range is 0-45dB)
+
+Bandwidths (Hz):
+ * **RX**: 40M
+ * **TX**: 40M
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 XCVR 2450
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The XCVR2450 has a non-contiguous tuning range consisting of a high band and a low band.
-The high band consists of frequencies between...TODO
+The XCVR2450 has a non-contiguous tuning range consisting of a 
+high band (4.9-6.0GHz) and a low band (2.4-2.5GHz).
 
 Transmit Antennas: **J1** or **J2**
 
 Receive Antennas: **J1** or **J2**
 
-When using the XCVR2450 in full-duplex mode,
-the user must set the receive antenna and the transmit antenna to be different;
-not doing so will yeild undefined results.
-
 The XCVR2450 uses a common LO for both receive and transmit.
 Even though the API allows the RX and TX LOs to be individually set,
 a change of one LO setting will be reflected in the other LO setting.
 
+The XCVR2450 does not support full-duplex mode, attempting to operate 
+in full-duplex will result in transmit-only operation.
+
 Transmit Gains:
  * **VGA**, Range: 0-30dB
  * **BB**, Range: 0-5dB
@@ -92,6 +105,10 @@ Receive Gains:
  * **LNA**, Range: 0-30.5dB
  * **VGA**, Range: 0-62dB
 
+Bandwidths (Hz):
+ * **RX**: 15M, 19M, 28M, 36M; (each +-0, 5, or 10%)
+ * **TX**: 24M, 36M, 48M
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 WBX Series
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -105,7 +122,22 @@ the receive antenna will always be set to RX2, regardless of the settings.
 
 Transmit Gains: **PGA0**, Range: 0-25dB
 
-Recieve Gains: **PGA0**, Range: 0-31.5dB
+Receive Gains: **PGA0**, Range: 0-31.5dB
+
+Bandwidths (Hz):
+ * **RX**: 40M
+ * **TX**: 40M
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+TVRX
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Receive Antennas: RX
+
+Receive Gains:
+ * **RF**, Range: -13.3-50.3dB (frequency-dependent)
+ * **IF**, Range: -1.5-32.5dB
+
+Bandwidth: 6MHz
 
 ------------------------------------------------------------------------
 Daughterboard Modifications
diff --git a/host/docs/index.rst b/host/docs/index.rst
index bd55edc0b..7f8129e2d 100644
--- a/host/docs/index.rst
+++ b/host/docs/index.rst
@@ -20,11 +20,12 @@ Building the UHD
 ^^^^^^^^^^^^^^^^^^^^^
 Application Notes
 ^^^^^^^^^^^^^^^^^^^^^
-* `General App Notes <./general.html>`_
+* `General Application Notes <./general.html>`_
 * `Firmware and FPGA Image Notes <./images.html>`_
-* `USRP1 App Notes <./usrp1.html>`_
-* `USRP2 App Notes <./usrp2.html>`_
-* `Daughterboard App Notes <./dboards.html>`_
+* `USRP1 Application Notes <./usrp1.html>`_
+* `USRP2 Application Notes <./usrp2.html>`_
+* `Daughterboard Application Notes <./dboards.html>`_
+* `Transport Application Notes <./transport.html>`_
 
 ^^^^^^^^^^^^^^^^^^^^^
 API Documentation
diff --git a/host/docs/transport.rst b/host/docs/transport.rst
new file mode 100644
index 000000000..432db4bb5
--- /dev/null
+++ b/host/docs/transport.rst
@@ -0,0 +1,88 @@
+========================================================================
+UHD - Transport Application Notes
+========================================================================
+
+.. contents:: Table of Contents
+
+------------------------------------------------------------------------
+Introduction
+------------------------------------------------------------------------
+A transport is the layer between the packet interface and a device IO interface.
+The advanced user can pass optional parameters
+into the underlying transport layer through the device address.
+These optional parameters control how the transport object allocates memory,
+resizes kernel buffers, spawns threads, etc.
+When not spcified, the transport layer will use values for these parameters
+that are known to perform well on a variety of systems.
+The transport parameters are defined below for the various transports in the UHD:
+
+------------------------------------------------------------------------
+UDP transport (ASIO)
+------------------------------------------------------------------------
+The UDP transport is implemented with Boost's ASIO library.
+ASIO provides an asynchronous API for user-space sockets.
+The transport implementation allocates a number of buffers
+and submits asynchronous requests for send and receive.
+IO service threads run in the background to process these requests.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Transport parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following parameters can be used to alter the transport's default behavior:
+
+* **recv_frame_size:** The size of a single receive buffer in bytes
+* **num_recv_frames:** The number of receive buffers to allocate
+* **send_frame_size:** The size of a single send buffer in bytes
+* **num_send_frames:** The number of send buffers to allocate
+* **concurrency_hint:** The number of threads to run the IO service
+
+**Note:** num_send_frames and concurrency_hint will not have an effect
+as the asynchronous send implementation is currently disabled.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Resize socket buffers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+It may be useful increase the size of the socket buffers to
+move the burden of buffering samples into the kernel, or to
+buffer incoming samples faster than they can be processed.
+However, if your application cannot process samples fast enough,
+no amount of buffering can save you.
+The following parameters can be used to alter socket's buffer sizes:
+
+* **recv_buff_size:** The desired size of the receive buffer in bytes
+* **send_buff_size:** The desired size of the send buffer in bytes
+
+**Note:** Large send buffers tend to decrease transmit performance.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Linux specific notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+On linux, the maximum buffer sizes are capped by the sysctl values
+**net.core.rmem_max** and **net.core.wmem_max**.
+To change the maximum values, run the following commands:
+::
+
+    sudo sysctl -w net.core.rmem_max=<new value>
+    sudo sysctl -w net.core.wmem_max=<new value>
+
+Set the values permanently by editing */etc/sysctl.conf*
+
+------------------------------------------------------------------------
+USB transport (libusb)
+------------------------------------------------------------------------
+The USB transport is implemented with libusb.
+Libusb provides an asynchronous API for USB bulk transfers.
+The transport implementation allocates a number of buffers
+and submits asynchronous requests through libusb.
+Event handler threads run in the background to process these requests.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Transport parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following parameters can be used to alter the transport's default behavior:
+
+* **recv_frame_size:** The size of a single receive transfers in bytes
+* **num_recv_frames:** The number of simultaneous receive transfers
+* **send_frame_size:** The size of a single send transfers in bytes
+* **num_send_frames:** The number of simultaneous send transfers
+* **concurrency_hint:** The number of threads to run the event handler
diff --git a/host/docs/usrp1.rst b/host/docs/usrp1.rst
index 3c1431d30..3443fd871 100644
--- a/host/docs/usrp1.rst
+++ b/host/docs/usrp1.rst
@@ -100,10 +100,10 @@ OS Specific Notes
 ------------------------------------------------------------------------
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Setup Udev on Linux
+Linux - setup udev
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-On Linux, Udev handles USB plug and unplug events.
-The following command creates a Udev rule for the USRP1
+On Linux, udev handles USB plug and unplug events.
+The following commands create a udev rule for the USRP1
 so that non-root users may access the device:
 
 ::
@@ -113,3 +113,9 @@ so that non-root users may access the device:
     sudo mv tmpfile /etc/udev/rules.d/10-usrp.rules
     sudo udevadm control --reload-rules
 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Windows - install driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+On Windows, a driver must be installed the first time the USRP1 is attached to the host computer.
+A download link for this driver can be found on the UHD wiki page.
+Download and unpack the driver, and direct the Windows driver install wizard to the .inf file.
diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst
index 4c95fb24c..0ddcaa4e5 100644
--- a/host/docs/usrp2.rst
+++ b/host/docs/usrp2.rst
@@ -158,7 +158,7 @@ The value for the addr key is a white-space separated list
 of IPv4 addresses or resolvable hostnames.
 The first address in the list will represent channel 0,
 the second channel 1, and so on...
-Use this addressing scheme with the *mimo_usrp* interface.
+Use this addressing scheme with the *multi_usrp* interface.
 
 The device address string representation for 2 USRP2s with IPv4 addresses 192.168.10.2 and 192.168.20.2
 ::
@@ -166,49 +166,22 @@ The device address string representation for 2 USRP2s with IPv4 addresses 192.16
     addr=192.168.10.2 192.168.20.2
 
 ------------------------------------------------------------------------
-Resize the send and receive buffers
+Hardware setup notes
 ------------------------------------------------------------------------
-It may be useful increase the size of the socket buffers to
-move the burden of buffering samples into the kernel, or to
-buffer incoming samples faster than they can be processed.
-However, if you application cannot process samples fast enough,
-no amount of buffering can save you.
-
-By default, the UHD will try to resize both the send and receive buffer for optimum performance.
-A warning will be printed on instantiation if the actual buffer size is insufficient.
-See the OS specific notes below:
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-OS specific notes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-On linux, the maximum buffer sizes are capped by the sysctl values
-**net.core.rmem_max** and **net.core.wmem_max**.
-To change the maximum values, run the following commands:
-::
-
-    sudo sysctl -w net.core.rmem_max=<new value>
-    sudo sysctl -w net.core.wmem_max=<new value>
-
-Set the values permanently by editing */etc/sysctl.conf*
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Device address params
+Front panel LEDs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To manually set the size of the buffers,
-the usrp2 will accept two optional parameters in the device address.
-Each parameter will accept a numeric value for the number of bytes.
-
-* recv_buff_size
-* send_buff_size
-
-Example, set the args string to the following:
-::
+The LEDs on the front panel can be useful in debugging hardware and software issues.
+The LEDs reveal the following about the state of the device:
 
-    addr=192.168.10.2, recv_buff_size=100e6
+* **LED A:** transmitting
+* **LED B:** undocumented
+* **LED C:** receiving
+* **LED D:** firmware loaded
+* **LED E:** undocumented
+* **LED F:** FPGA loaded
 
-------------------------------------------------------------------------
-Hardware setup notes
-------------------------------------------------------------------------
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Ref Clock - 10MHz