uhd: updated docs usb post-install, added uhd-usrp.rules

6 files changed, 61 insertions, 51 deletions

diff --git a/host/docs/build.rst b/host/docs/build.rst
index 063b2b371..e3a877a4b 100644
--- a/host/docs/build.rst
+++ b/host/docs/build.rst
@@ -202,3 +202,10 @@ Setup the PATH environment variable
 **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.
+
+------------------------------------------------------------------------
+Post-Install Tasks
+------------------------------------------------------------------------
+For USB-based devices,
+see the `USB Transport Application Notes <./transport.html#usb-transport-libusb>`_
+for platform-specific post-installation tasks.
diff --git a/host/docs/transport.rst b/host/docs/transport.rst
index b601cd8ff..1ee5b0879 100644
--- a/host/docs/transport.rst
+++ b/host/docs/transport.rst
@@ -19,10 +19,8 @@ The transport parameters are defined below for the various transports in the UHD
 ------------------------------------------------------------------------
 UDP transport (sockets)
 ------------------------------------------------------------------------
-The UDP transport is implemented with user-space sockets:
-
-* **UNIX:** standard Berkeley sockets API using send()/recv()
-* **Windows:** Windows Sockets API (WSA) using overlapped IO
+The UDP transport is implemented with user-space sockets.
+This means standard Berkeley sockets API using send()/recv().
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Transport parameters
@@ -118,9 +116,6 @@ 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
@@ -131,4 +126,28 @@ The following parameters can be used to alter the transport's default behavior:
 * **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
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setup Udev for USB (Linux)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+On Linux, Udev handles USB plug and unplug events.
+The following commands install a Udev rule
+so that non-root users may access the device:
+
+::
+
+    cd <install-path>
+    sudo cp uhd-usrp.rules /etc/udev/rules.d/
+    sudo udevadm control --reload-rules
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Install USB driver (Windows)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A driver package must be installed to use a USB-based product with UHD:
+
+* Download the driver from the UHD wiki page.
+* Unzip the file into a known location. We will refer to this as the <directory>.
+* Open the device manager and plug-in the USRP. You will see an unrecognized USB device in the device manager.
+* Right click on the unrecognized USB device and select update/install driver software (may vary for your OS).
+* In the driver installation wizard, select "browse for driver", browse to the <directory>, and select the .inf file.
+* Continue through the installation wizard until the driver is installed.
diff --git a/host/docs/usrp1.rst b/host/docs/usrp1.rst
index de9950c7c..8b274a2b3 100644
--- a/host/docs/usrp1.rst
+++ b/host/docs/usrp1.rst
@@ -62,31 +62,6 @@ List of missing features
 * Start of burst flags for transmit/receive
 
 ------------------------------------------------------------------------
-OS specific notes
-------------------------------------------------------------------------
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Linux - setup udev
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-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:
-
-::
-
-    echo 'ACTION=="add", BUS=="usb", SYSFS{idVendor}=="fffe", SYSFS{idProduct}=="0002", MODE:="0666"' > tmpfile
-    sudo chown root.root tmpfile
-    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.
-
-------------------------------------------------------------------------
 Hardware setup notes
 ------------------------------------------------------------------------
 
diff --git a/host/docs/usrp_b1xx.rst b/host/docs/usrp_b1xx.rst
index 2f7385070..75b901a86 100644
--- a/host/docs/usrp_b1xx.rst
+++ b/host/docs/usrp_b1xx.rst
@@ -56,21 +56,3 @@ Example:
 ::
 
     uhd_usrp_probe --args="master_clock_rate=52e6"
-
-------------------------------------------------------------------------
-OS specific notes
-------------------------------------------------------------------------
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Linux - setup udev
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-On Linux, udev handles USB plug and unplug events.
-The following commands create a udev rule for the B100
-so that non-root users may access the device:
-
-::
-
-    echo 'ACTION=="add", BUS=="usb", SYSFS{idVendor}=="2500", SYSFS{idProduct}=="0001", MODE:="0666"' > tmpfile
-    sudo chown root.root tmpfile
-    sudo mv tmpfile /etc/udev/rules.d/10-usrp_b100.rules
-    sudo udevadm control --reload-rules
diff --git a/host/utils/CMakeLists.txt b/host/utils/CMakeLists.txt
index b2dd697fc..1b70be7a4 100644
--- a/host/utils/CMakeLists.txt
+++ b/host/utils/CMakeLists.txt
@@ -45,6 +45,14 @@ IF(ENABLE_USRP1)
     )
 ENDIF(ENABLE_USRP1)
 
+IF(LINUX AND ENABLE_USB)
+    INSTALL(FILES
+        uhd-usrp.rules
+        DESTINATION ${PKG_DATA_DIR}/utils
+        COMPONENT utilities
+    )
+ENDIF(LINUX AND ENABLE_USB)
+
 #for each source: build an executable and install
 FOREACH(util_source ${util_share_sources})
     GET_FILENAME_COMPONENT(util_name ${util_source} NAME_WE)
diff --git a/host/utils/uhd-usrp.rules b/host/utils/uhd-usrp.rules
new file mode 100644
index 000000000..65b9121a4
--- /dev/null
+++ b/host/utils/uhd-usrp.rules
@@ -0,0 +1,19 @@
+#
+# Copyright 2011 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/>.
+#
+
+ACTION=="add", BUS=="usb", SYSFS{idVendor}=="fffe", SYSFS{idProduct}=="0002", MODE:="0666"
+ACTION=="add", BUS=="usb", SYSFS{idVendor}=="2500", SYSFS{idProduct}=="0001", MODE:="0666"