Merge branch 'master' of ettus.sourcerepo.com:ettus/uhdpriv into usrp2p

Conflicts:
	host/lib/usrp/usrp2/io_impl.cpp

5 files changed, 105 insertions, 30 deletions

diff --git a/host/docs/build.rst b/host/docs/build.rst
index d7dfd05e5..9cf37db4a 100644
--- a/host/docs/build.rst
+++ b/host/docs/build.rst
@@ -40,7 +40,7 @@ CMake
 ^^^^^^^^^^^^^^^^
 * **Purpose:** generates project build files
 * **Version:** at least 2.8
-* **Required for:** build time
+* **Usage:** build time (required)
 * **Download URL:** http://www.cmake.org/cmake/resources/software.html
 
 ^^^^^^^^^^^^^^^^
@@ -48,24 +48,25 @@ Boost
 ^^^^^^^^^^^^^^^^
 * **Purpose:** C++ library
 * **Version:** at least 3.6 unix, at least 4.0 windows
-* **Required for:** build time + run time
+* **Usage:** build time + run time (required)
 * **Download URL:** http://www.boost.org/users/download/
 * **Download URL (windows installer):** http://www.boostpro.com/download
 
 ^^^^^^^^^^^^^^^^
 LibUSB
 ^^^^^^^^^^^^^^^^
-* **Purpose:** USB userspace library
+* **Purpose:** USB-based hardware support
 * **Version:** at least 1.0
-* **Required for:** build time + run time (optional)
-* **Download URL:** http://www.libusb.org/
+* **Usage:** build time + run time (optional)
+* **Download URL:** http://sourceforge.net/projects/libusb/files/libusb-1.0/
+* **Download URL (windows binaries):** http://www.libusb.org/wiki/windows_backend#LatestBinarySnapshots
 
 ^^^^^^^^^^^^^^^^
 Python
 ^^^^^^^^^^^^^^^^
 * **Purpose:** used by Cheetah and utility scripts
 * **Version:** at least 2.6
-* **Required for:** build time + run time utility scripts
+* **Usage:** build time + run time utility scripts (required)
 * **Download URL:** http://www.python.org/download/
 
 ^^^^^^^^^^^^^^^^
@@ -73,7 +74,7 @@ Cheetah
 ^^^^^^^^^^^^^^^^
 * **Purpose:** source code generation
 * **Version:** at least 2.0
-* **Required for:** build time
+* **Usage:** build time (required)
 * **Download URL:** http://www.cheetahtemplate.org/download.html
 * **Download URL (windows installer):** http://feisley.com/python/cheetah/
 
@@ -81,14 +82,14 @@ Cheetah
 Doxygen
 ^^^^^^^^^^^^^^^^
 * **Purpose:** generates html api documentation
-* **Required for:** build time (optional)
+* **Usage:** build time (optional)
 * **Download URL:** http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
 
 ^^^^^^^^^^^^^^^^
 Docutils
 ^^^^^^^^^^^^^^^^
 * **Purpose:** generates html user manual
-* **Required for:** build time (optional)
+* **Usage:** build time (optional)
 * **Download URL:** http://docutils.sourceforge.net/
 
 ------------------------------------------------------------------------
@@ -105,9 +106,16 @@ Generate Makefiles with cmake
     cd build
     cmake ../
 
-**Notes:**
+Additionally, configuration variables can be passed into cmake via the command line.
+The following common-use configuration variables are listed below:
 
-* For a custom prefix, use: cmake -DCMAKE_INSTALL_PREFIX=<prefix> ../
+* For a custom install prefix: -DCMAKE_INSTALL_PREFIX=<prefix>
+* To install libs into lib64: cmake -DLIB_SUFFIX=64
+
+Example usage:
+::
+
+    cmake -DCMAKE_INSTALL_PREFIX=/opt/uhd ../
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Build and install
@@ -145,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.
@@ -155,14 +176,23 @@ Build the project in MSVC
 **Note:** you may not have permission to build the install target.
 You need to be an administrator or to run MSVC as administrator.
 
-** alternative command line instructions **
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Build the project in MSVC (command line)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Open the Visual Studio Command Prompt Shorcut:
+::
 
-* Open the Visual Studio Command Prompt Shorcut
-* DevEnv <uhd-repo-path>\host\build\ALL_BUILD.vcproj /Build Release
-* DevEnv <uhd-repo-path>\host\build\INSTALL.vcproj /Build Release
+    cd <uhd-repo-path>\host\build
+    DevEnv ALL_BUILD.vcproj /Build Release
+    DevEnv INSTALL.vcproj /Build Release
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 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 23f350b0f..d6a19d250 100644
--- a/host/docs/coding.rst
+++ b/host/docs/coding.rst
@@ -23,11 +23,11 @@ The device API provides ways to:
 See the documentation in *device.hpp* for reference.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-High-Level: The simple usrp
+High-Level: The single usrp
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The goal of the simple usrp API is to wrap high level functions around the device properties.
-The simple usrp provides a fat interface to access the most common properties.
-The simple usrp provides ways to:
+The goal of the single usrp API is to wrap high level functions around the device properties.
+The single usrp provides a fat interface to access the most common properties.
+The single usrp provides ways to:
 
 * Set and get daughterboard gains.
 * Set and get daughterboard antennas.
@@ -38,13 +38,13 @@ The simple usrp provides ways to:
 * Set the usrp time registers.
 * Get the underlying device (as discussed above).
 
-See the documentation in *usrp/simple_usrp.hpp* for reference.
+See the documentation in *usrp/single_usrp.hpp* for reference.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 High-Level: The mimo usrp
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The mimo usrp API provides a wrapper around a device that represents several motherboards.
-This API provides convenience calls just like the simple usrp,
+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:
diff --git a/host/docs/dboards.rst b/host/docs/dboards.rst
index 985fbc12b..738a0696d 100644
--- a/host/docs/dboards.rst
+++ b/host/docs/dboards.rst
@@ -15,11 +15,12 @@ properties of each board as well.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Basic RX and and LFRX
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Basic RX and LFRX boards have 3 subdevices:
+The Basic RX and LFRX boards have 4 subdevices:
 
 * **Subdevice A:** real signal on antenna RXA
 * **Subdevice B:** real signal on antenna RXB
-* **Subdevice AB:** quadrature subdevice using both antennas
+* **Subdevice AB:** quadrature subdevice using both antennas (IQ)
+* **Subdevice BA:** quadrature subdevice using both antennas (QI)
 
 The boards have no tunable elements or programmable gains.
 Though the magic of aliasing, you can down-convert signals
@@ -28,11 +29,12 @@ greater than the Nyquist rate of the ADC.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Basic TX and and LFTX
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Basic TX and LFTX boards have 3 subdevices:
+The Basic TX and LFTX boards have 4 subdevices:
 
 * **Subdevice A:** real signal on antenna TXA
 * **Subdevice B:** real signal on antenna TXB
-* **Subdevice AB:** quadrature subdevice using both antennas
+* **Subdevice AB:** quadrature subdevice using both antennas (IQ)
+* **Subdevice BA:** quadrature subdevice using both antennas (QI)
 
 The boards have no tunable elements or programmable gains.
 Though the magic of aliasing, you can up-convert signals
diff --git a/host/docs/usrp1.rst b/host/docs/usrp1.rst
index 3c1431d30..0baa93a45 100644
--- a/host/docs/usrp1.rst
+++ b/host/docs/usrp1.rst
@@ -60,6 +60,29 @@ Example device address string representations to specify non-standard firmware a
 
     fpga=usrp1_fpga_4rx.rbf, fw=usrp1_fw_custom.ihx
 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Change USB transfer parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The advanced user may manipulate parameters of the usb bulk transfers
+for various reasons, such as lowering latency or increasing buffer size.
+By default, the UHD will use values for these parameters
+that are known to perform well on a variety of systems.
+The following device address parameters can be used to manipulate USB bulk transfers:
+
+* **recv_xfer_size:** the size of each receive bulk transfer in bytes
+* **recv_num_xfers:** the number of simultaneous receive bulk transfers
+* **send_xfer_size:** the size of each send bulk transfer in bytes
+* **send_num_xfers:** the number of simultaneous send bulk transfers
+
+Example usage, set the device address markup string to the following:
+::
+
+    serial=12345678, recv_num_xfers=16
+
+   -- OR --
+
+    serial=12345678, recv_xfer_size=2048, recv_num_xfers=16
+
 ------------------------------------------------------------------------
 Specifying the subdevice to use
 ------------------------------------------------------------------------
@@ -100,10 +123,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 +136,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 745361b77..70e5ea28b 100644
--- a/host/docs/usrp2.rst
+++ b/host/docs/usrp2.rst
@@ -174,7 +174,7 @@ 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 request a reasonably large buffer size for both send and receive.
+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:
 
@@ -201,7 +201,7 @@ 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:
+Example usage, set the device address markup string to the following:
 ::
 
     addr=192.168.10.2, recv_buff_size=100e6
@@ -211,6 +211,20 @@ Hardware setup notes
 ------------------------------------------------------------------------
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Front panel LEDs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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:
+
+* **LED A:** transmitting
+* **LED B:** undocumented
+* **LED C:** receiving
+* **LED D:** firmware loaded
+* **LED E:** undocumented
+* **LED F:** FPGA loaded
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Ref Clock - 10MHz
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Using an external 10MHz reference clock requires a signal level between