docs: adding page for NIRIO kernel driver install, linking to it

3 files changed, 168 insertions, 11 deletions

diff --git a/host/docs/mainpage.dox b/host/docs/mainpage.dox
index 47be99411..597938c35 100644
--- a/host/docs/mainpage.dox
+++ b/host/docs/mainpage.dox
@@ -2,7 +2,9 @@
 
 \tableofcontents
 
-Welcome to the manual pages for the USRP Hardware Driver (UHD), the host driver for Ettus Research devices. Here, you will find information on how to use the devices and how to use the API to connect to them through your own software.
+Welcome to the manual pages for the USRP Hardware Driver (UHD), the host driver
+for Ettus Research devices. Here, you will find information on how to use the
+devices and how to use the API to connect to them through your own software.
 
 # Building and Installing UHD
 
@@ -45,6 +47,7 @@ Welcome to the manual pages for the USRP Hardware Driver (UHD), the host driver
 \li \subpage page_gpsdo_x3x0
 \li \subpage page_gpio_api
 \li \subpage page_usrp_x3x0_config
+\li \subpage page_ni_rio_kernel
 
 ## USRP Legacy Series
 
diff --git a/host/docs/ni_rio_kernel.dox b/host/docs/ni_rio_kernel.dox
new file mode 100644
index 000000000..d364cad3c
--- /dev/null
+++ b/host/docs/ni_rio_kernel.dox
@@ -0,0 +1,142 @@
+/*! \page page_ni_rio_kernel NI RIO Kernel Modules for X-Series PCIe Connectivity
+
+\tableofcontents
+
+\section linux_rio Linux NI RIO Installation and Usage
+
+\subsection linux_requirements Requirements
+
+In order to use the PCIe transport connection on the USRP X300 / X310 devices,
+you must install the NI USRP RIO driver stack. These include kernel modules
+which must be loaded.
+
+Your kernel version must be supported by the kernel modules. Only 64-bit kernels
+are supported.
+
+<b>Currently, the latest supported kernel version is 3.14.x.</b>
+
+\subsection linux_installation Installing the Drivers in Linux
+
+The NI USRP RIO installer can be found <a
+href=http://files.ettus.com/binaries/niusrprio/niusrprio-installer.tar.gz>here</a>.
+
+Download the installer and extract it with the following command:
+
+    tar zxf niusrprio-installer.tar.gz
+
+The files will be extracted into a directory called <b>niusrprio-installer</b>.
+
+To install the NI USRPRIO kernel modules and RPC server, run the following
+command:
+
+    sudo niusrprio-installer/INSTALL
+
+Select 'y' for each prompt, and the script will install all necessary
+components.  This script will automatically load all necessary kernel modules
+for the duration of the session.
+
+\subsection linux_enabling Enabling and Disabling Usage
+
+Once everything is installed, run the following commands to enable use of the
+X300/X310 over PCI Express:
+
+    sudo /usr/local/bin/niusrprio_pcie start
+
+To stop these processes, run the following command:
+
+    sudo /usr/local/bin/niusrprio_pcie stop
+
+To check if the kernel modules are loaded and if the RPC server is running, run
+the following command:
+
+    /usr/local/bin/niusrprio_pcie status
+
+<b>NOTE:</b> niusrprio_pcie start does not run when the host system is booted.
+If you would like the USRP PCIe device to be available automatically after
+a system restart, please create an init.d script that runs niusrprio_pcie start.
+
+\subsection linux_swapping Hot-Plugging and Power-Cycling
+
+The NI USRPRIO kernel modules are built for a specific kernel version. If you
+upgrade/downgrade the linux kernel on the host to a version different from the
+one that the installer was run on, then you may see the following error message
+when running `niusrprio star`.
+
+    ERROR: could not insert 'NiRioSrv': Unknown symbol in module, or unknown
+    parameter (see dmesg) ERROR: could not insert 'niusrpriok': Unknown symbol
+    in module, or unknown parameter (see dmesg)
+
+To rebuild the kernel modules for the currently running kernel, simple run the
+following
+
+    sudo /usr/local/bin/niusrprio_pcie stop sudo /usr/local/bin/updateNIDrivers
+    --no-prompt sudo /usr/local/bin/niusrprio_pcie start
+
+\subsection linux_uninstalling Uninstalling in Linux
+
+To uninstall the NI USRP RIO kernel modules and RPC server, run the following
+command:
+
+    sudo niusrprio-installer/UNINSTALL
+
+Select y at the prompt, and the script will uninstall all installed components.
+
+
+\section windows_rio Windows NI RIO Installation and Usage
+
+\subsection win_requirements Requirements
+
+The kernel driver is only supported on:
+
+- Windows 8.1 32-bit
+- Windows 8.1 64-bit
+- Windows 7 32-bit
+- Windows 7 64-bit
+- Windows Vista 32-bit
+- Windows Vista 64-bit
+- Windows XP (SP3) 32-bit.
+
+\subsection win_install Installing NI-USRP in Windows
+
+The NI-USRP 1.3 installer can be found <a
+href="http://www.ni.com/download/ni-usrp-1.3/4711/en/">here</a> You will need to
+create a free NI User Account to download the installer.
+
+Perform the following steps to download and install the NI-USRP exe driver
+package:
+
+- Choose the "2. Standard Download:NIUSRP130.exe" option to download
+- NIUSRP130.exe to your computer Run NIUSRP130.exe as an Administrator and
+- extract the contents to 'C:\\National Instruments Downloads\\NI-USRP\\1.3' In the
+- extract location, run setup.exe and follow the prompts.
+
+Reboot the computer after both the NI-USRP package has been installed.
+
+\subsection win_enabling Enabling and Disabling Usage
+
+Once everything is installed and the system is rebooted, your X300/X310 PCI
+Express device should automatically be detected by the Windows Device Manager.
+The device should be enabled by default.
+
+- To disable the USRPRIO device, navigate to "Device Manager", locate your
+- USRPRIO-X3x0 device, right-click on it and choose "Disable".  To enable the
+- USRPRIO device, navigate to "Device Manager", locate your USRPRIO-X3x0 device,
+- right-click on it and choose "Enable".
+
+\subsection win_swapping Hot-plugging and Power-cycling
+
+The USRP X3x0, NI USRP-294x and NI USRP-295x devices <b>cannot</b> be hot-swapped
+when connected over PCI Express. Unplugging the PCI Express connection or
+powering the device should be done only after disabling the device.
+
+<b>WARNING:</b> If the device is unplugged without running the above command, the
+system could become unstable.
+
+\subsection win_uninstall Uninstalling NI-USRP in Windows
+
+Navigate to the Control Panel and open "Programs". Then select National
+Instruments Software and select NI-USRP and NI-RIO from the list. Click on
+uninstall to remove the drivers from your system.
+
+*/
+// vim:ft=doxygen:
diff --git a/host/docs/usrp_x3x0.dox b/host/docs/usrp_x3x0.dox
index 42574334b..0b46f0d16 100644
--- a/host/docs/usrp_x3x0.dox
+++ b/host/docs/usrp_x3x0.dox
@@ -11,7 +11,7 @@
 	- External PPS input & output
 	- External 10 MHz input & output
 	- Expandable via 2nd SFP+ interface
-	- Supported master clock rates: 200 MHz, 184.32 MHz
+	- Supported master clock rates: 200 MHz, 184.32 MHz, 120 MHz
 	- External GPIO Connector with UHD API control
 	- External USB Connection for built-in JTAG debugger
 	- Internal GPSDO option
@@ -130,6 +130,12 @@ The LEDs on the front panel can be useful in debugging hardware and software iss
 <b>Important Note: The USRP X-Series provides PCIe connectivity over MXI cable.
 We will use the 'MXI' nomenclature for the rest of this manual.</b>
 
+### Installing the PCIe Kernel Drivers
+
+In order to use the USRP X-Series on a PCIe-over-MXI connection, you need to
+install the NI RIO drivers on your system. Please follow the insructions here:
+\ref page_ni_rio_kernel
+
 ### Installing the PCI Express Interface Kit
 
 Follow the instructions listed in the <a href="http://www.ni.com/pdf/manuals/371976c.pdf">Set Up Your MXI-Express x4 System</a>
@@ -143,7 +149,7 @@ document to setup the NI PCIe-8371 module.
 - Power on the USRP X300/X310 device using the power switch located in the bottom-right corner of the front panel.
 - Power on the PC (The OS automatically recognizes the new device)
 
-<b>Note:</b> The USRP device is not hot-pluggable over PCI Express. Any connection changes with only be detected by your 
+<b>Note:</b> The USRP device is not hot-pluggable over PCI Express. Any connection changes with only be detected by your
 computer after a successful reboot.
 
 ### Troubleshooting
@@ -154,7 +160,7 @@ devices (for example, there is a yellow exclamation point on a PCI to PCI
 bridge in Windows Device Manager, despite drivers for all devices being
 installed). These situations often are due to programming errors in PCI Express
 device configuration of the BIOS. To use this software, you need a MXI-Express
-device that supports Mode 1 operation. 
+device that supports Mode 1 operation.
 Refer to <a href="http://download.ni.com/support/softlib//PXI/MXIe%20Compatibility%20Software/1.5.0/readme.html#SupportedHardware">NI MXI-Express BIOS Compatibility Software Readme</a>
 for more information.
 
@@ -165,6 +171,12 @@ The BIOS Compatibility Software can be downloaded for Windows from the <a href="
 <b>Important Note: The USRP X-Series provides PCIe connectivity over MXI cable
 We will use the 'MXI' nomenclature for the rest of this manual.</b>
 
+### Installing the PCIe Kernel Drivers
+
+In order to use the USRP X-Series on a PCIe-over-MXI connection, you need to
+install the NI RIO drivers on your system. Please follow the insructions here:
+\ref page_ni_rio_kernel
+
 ### Installing the PCI Express Card
 
 Follow the instructions listed in the “Installing an NI ExpressCard-8360 Host Card” section of the
@@ -259,7 +271,7 @@ The \e fpga tag can be set in the optional device args passed to indicate the FP
 If the above tag is specified, UHD will attempt to load the FPGA image with the requested flavor from the
 UHD images directory. If the tag is not specified, UHD will automatically detect the flavor of the image
 and attempt to load the corresponding configuration bitstream onto the device. Note that if UHD detects
-that the requested image is already loaded onto the FPGA then it will not reload it. 
+that the requested image is already loaded onto the FPGA then it will not reload it.
 
 \subsection x3x0_load_fpga_imgs_jtag Use JTAG to load FPGA images
 
@@ -326,8 +338,8 @@ transceiver modules.</b>
 \subsection x3x0_setup_network_host_interface Setup the host interface
 
 The USRP-X Series communicates at the IP/UDP layer over the Gigabit and Ten Gigabit Ethernet.
-The default IP address for the USRP X300/X310 device depends on the Ethernet Port and interface used. 
-You must configure the host Ethernet interface with a static IP address on the same subnet as the connected 
+The default IP address for the USRP X300/X310 device depends on the Ethernet Port and interface used.
+You must configure the host Ethernet interface with a static IP address on the same subnet as the connected
 device to enable communication, as shown in the following table:
 
   Ethernet Interface | USRP Ethernet Port      |  Default USRP IP Address |  Host Static IP Address | Host Static Subnet Mask | Address EEPROM key
@@ -485,8 +497,8 @@ A device similar to the following should be detected:
 UHD requires the RIO device manager service to be running in order to
 communicate with an X-Series USRP over PCIe.
 This service is installed as a part of the USRP RIO (or NI-USRP) installer. On Windows, it can be found in
-the **Services** section in the Control Panel and it is started at system boot time. To ensure that the 
-service is indeed started, navigate to the Services tag in the Windows Task Manager and ensure that the 
+the **Services** section in the Control Panel and it is started at system boot time. To ensure that the
+service is indeed started, navigate to the Services tag in the Windows Task Manager and ensure that the
 status of **niusrpriorpc** is "Running".
 
 If the device still does not enumerate after starting the device manager, make sure that the host computer
@@ -531,7 +543,7 @@ by pinging the USRP and making sure the LEDs start to blink.
 - **REF IN**: Reference clock input
 - **PCIe x4**: Connector for Cabled PCI Express link
 - **PPS/TRIG OUT**: Output port for the PPS signal
-- **PPS/TRIG IN**: Input port for the PPS signal 
+- **PPS/TRIG IN**: Input port for the PPS signal
 - **GPS**: Connection for the GPS antenna
 
 \subsection x3x0_hw_x3x0_hw_ref10M Ref Clock - 10 MHz
@@ -591,7 +603,7 @@ Further information on how to use Chipscope can be found in the Xilinx Chipscope
 
 \subsection x3x0_misc_multirx Multiple RX channels
 
-There are two complete DDC and DUC DSP chains in the FPGA. In the single channel case, 
+There are two complete DDC and DUC DSP chains in the FPGA. In the single channel case,
 only one chain is ever used. To receive from both channels, the user must set the **RX** or **TX**
 subdevice specification.