aboutsummaryrefslogtreecommitdiffstats
path: root/host/docs
diff options
context:
space:
mode:
Diffstat (limited to 'host/docs')
-rw-r--r--host/docs/CMakeLists.txt11
-rw-r--r--host/docs/build.dox20
-rw-r--r--host/docs/c_api.dox86
-rw-r--r--host/docs/coding.dox5
-rw-r--r--host/docs/dboards.dox4
-rw-r--r--host/docs/general.dox41
-rw-r--r--host/docs/ni_rio_kernel.dox49
-rw-r--r--host/docs/octoclock.dox31
-rw-r--r--host/docs/uhd.dox1
-rw-r--r--host/docs/uhd_image_loader.1130
-rw-r--r--host/docs/usrp2.dox29
-rw-r--r--host/docs/usrp_b200.dox120
-rw-r--r--host/docs/usrp_e3x0.dox22
-rw-r--r--host/docs/usrp_x3x0.dox43
-rw-r--r--host/docs/usrp_x3x0_config.dox167
-rw-r--r--host/docs/vrt_chdr.dox83
16 files changed, 569 insertions, 273 deletions
diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index d0f060ceb..3090d3f80 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -1,5 +1,5 @@
#
-# Copyright 2010-2013 Ettus Research LLC
+# Copyright 2010-2013,2015 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
@@ -28,7 +28,7 @@ SET(ENABLE_MANUAL_OR_DOXYGEN false)
########################################################################
# Setup Manual (using Doxygen)
########################################################################
-LIBUHD_REGISTER_COMPONENT("Manual" ENABLE_MANUAL ON "DOXYGEN_FOUND" OFF)
+LIBUHD_REGISTER_COMPONENT("Manual" ENABLE_MANUAL ON "DOXYGEN_FOUND" OFF OFF)
# Check if fpga submodule is there. If yes:
# - Add fpga-src/docs and fpga-src/README.md to inputs
@@ -64,7 +64,7 @@ ENDIF(ENABLE_MANUAL)
# Setup API documentation (using Doxygen)
########################################################################
MESSAGE(STATUS "")
-LIBUHD_REGISTER_COMPONENT("API/Doxygen" ENABLE_DOXYGEN ON "DOXYGEN_FOUND" OFF)
+LIBUHD_REGISTER_COMPONENT("API/Doxygen" ENABLE_DOXYGEN ON "DOXYGEN_FOUND" OFF OFF)
OPTION(ENABLE_DOXYGEN_FULL "Use Doxygen to document the entire source tree (not just API)" OFF)
IF(LIBUHDDEV_PKG)
@@ -75,6 +75,8 @@ IF(ENABLE_DOXYGEN)
SET(ENABLE_MANUAL_OR_DOXYGEN true)
#make doxygen directory depend on the header files
FILE(GLOB_RECURSE header_files ${CMAKE_SOURCE_DIR}/include/*.hpp)
+ FILE(GLOB_RECURSE h_files ${CMAKE_SOURCE_DIR}/include/*.h)
+ LIST(APPEND header_files ${h_files})
SET(DOXYGEN_DEPENDENCIES ${DOXYGEN_DEPENDENCIES} ${header_files})
IF(ENABLE_DOXYGEN_FULL)
SET(DOXYGEN_INPUT_DIRS "${DOXYGEN_INPUT_DIRS} ${CMAKE_SOURCE_DIR}/include ${CMAKE_SOURCE_DIR}/lib")
@@ -120,6 +122,7 @@ SET(man_page_sources
uhd_cal_tx_dc_offset.1
uhd_cal_tx_iq_balance.1
uhd_find_devices.1
+ uhd_image_loader.1
uhd_images_downloader.1
uhd_usrp_probe.1
usrp_n2xx_simple_net_burner.1
@@ -138,7 +141,7 @@ IF(NOT WIN32)
SET(NOT_WIN32 TRUE)
ENDIF(NOT WIN32)
-LIBUHD_REGISTER_COMPONENT("Man Pages" ENABLE_MAN_PAGES ON "GZIP_FOUND;NOT_WIN32" OFF)
+LIBUHD_REGISTER_COMPONENT("Man Pages" ENABLE_MAN_PAGES ON "GZIP_FOUND;NOT_WIN32" OFF OFF)
IF(ENABLE_MAN_PAGES)
#Generate man pages
diff --git a/host/docs/build.dox b/host/docs/build.dox
index 1097ab5ab..0e722e376 100644
--- a/host/docs/build.dox
+++ b/host/docs/build.dox
@@ -11,7 +11,7 @@ package manager.
<b>Mac OS X Notes:</b>
Install the Xcode app to get the build tools (GCC and Make).
-Use MacPorts to get the Boost and Cheetah dependencies.
+Use MacPorts to get the Boost and Mako dependencies.
Other dependencies can be downloaded as DMG installers from the web
or installed via MacPorts.
See the UHD OS X build instructions for more information: \ref build_instructions_osx
@@ -28,7 +28,7 @@ The following compilers are known to work and officially supported:
- GCC >= 4.4
- Clang >= 3.1
-- MSVC >= 2010
+- MSVC >= 2012
Other compilers (or lower versions) may work, but are unsupported.
@@ -57,22 +57,20 @@ Other compilers (or lower versions) may work, but are unsupported.
### Python
-- **Purpose:** used by Cheetah and utility scripts
+- **Purpose:** used by mako and utility scripts
- **Minimum Version:** 2.6
- **Usage:** build time + runtime utility scripts (required)
- **Download URL:** http://www.python.org/download/
-### Cheetah
+### Mako
- **Purpose:** source code generation
-- **Minimum Version:** 2.0
+- **Minimum Version:** 0.5.0
- **Usage:** build time (required)
-- **Download URL:** http://www.cheetahtemplate.org/download.html
-- **Download URL (Windows installer):** http://feisley.com/python/cheetah/
+- **Download URL:** http://www.makotemplates.org/download.html
**Alternative method:**
-Install **setuptools**, and use the **easy_install** command to install Cheetah.
-http://pypi.python.org/pypi/setuptools
+You can use `pip` or `easy_install` to install Mako from PyPi.
### Doxygen
@@ -96,7 +94,7 @@ or install msysGit from http://code.google.com/p/msysgit/downloads/list.
You can install all the dependencies through the package manager:
- sudo apt-get install libboost-all-dev libusb-1.0-0-dev python-cheetah doxygen python-docutils cmake
+ sudo apt-get install libboost-all-dev libusb-1.0-0-dev python-mako doxygen python-docutils cmake build-essential
Your actual command may differ.
@@ -104,7 +102,7 @@ Your actual command may differ.
You can install all the dependencies through the package manager:
- sudo yum -y install boost-devel libusb1-devel python-cheetah doxygen python-docutils cmake
+ sudo yum -y install boost-devel libusb1-devel python-mako doxygen python-docutils cmake make gcc gcc-c++
Your actual command may differ.
diff --git a/host/docs/c_api.dox b/host/docs/c_api.dox
new file mode 100644
index 000000000..5b5790f21
--- /dev/null
+++ b/host/docs/c_api.dox
@@ -0,0 +1,86 @@
+/*! \page page_c_api UHD - C API
+
+\tableofcontents
+
+\section c_api_intro Introduction
+
+Alongside its C++ API, UHD provides a C API wrapper for the uhd::usrp::multi_usrp and
+uhd::usrp_clock::multi_usrp_clock classes, as well as their associated classes and
+structs. Other important UHD functions are also included in this API. To use this
+API, simply:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
+#include <uhd.h>
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+...and all UHD C-level structs and functions will be available to you. The sections below
+give more detail on the key features of the C API.
+
+\subsection c_api_handles C-Level Handles
+
+Most of the UHD classes that can be accessed on the C level are done so through handles,
+which internally store the C++ representation and allow access to internal values
+through helper functions.
+
+All handles have associated *_make() and *_free() functions. After creating a handle, it must
+be passed through its make() function before it can be used in your program. Before the program
+terminates, you must pass the handle into its free() function, or your program will have a memory
+leak. The example below shows the proper usage of an RX metadata handle over the course of its
+lifetime, from instantiation to destruction.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+uhd_rx_metadata_handle md;
+uhd_rx_metadata_make(&md);
+
+// Streaming here puts useful information into metadata
+time_t full_secs;
+double frac_secs;
+uhd_rx_metadata_time_spec(md, &full_secs, &frac_secs);
+
+uhd_rx_metadata_free(&md);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Again, make sure to pass your handle into a make() function before using it, or you will
+run into undefined behavior. Also be careful not to use the handle after passing it into
+a free() function, or your program will segfault.
+
+\subsection c_api_errorcode Error Codes
+
+As C cannot handle C++ runtime exceptions, UHD's C wrapper functions catch all exceptions
+and translate them into error codes, which are returned by each function. Any output variables
+are passed in as pointers into the function, which will set them internally.
+
+Each uhd::runtime_error has a corresponding ::uhd_error value. Separate error codes indicate
+that a boost::exception or std::exception has been thrown, and any other exceptions are
+indicated by a catch-all ::UHD_ERROR_UNKNOWN code.
+
+All UHD C-level handles store the string representation of the last C++ exception thrown internally.
+These handles have corresponding *_get_last_error() functions that will place the error string into a
+supplied string buffer.
+
+For example, if a USRP device's handle throws an exception internally, the following code can access
+its error info:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+char err_msg[256];
+uhd_usrp_handle usrp;
+double gain;
+// USRP configuration done here
+uhd_error error_code = uhd_usrp_get_rx_gain(usrp, 0, "", &gain);
+if(error_code){
+ uhd_usrp_get_last_error(usrp, err_msg, 256);
+ fprintf(stderr, "Error code %d: %s\n", error_code, err_msg);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All error codes can be found in <uhd/error.h>.
+
+\subsection c_api_examples Example Code
+
+UHD provides two examples that demonstrate the typical use case of the C API: RX and TX streaming.
+The <b>rx_samples_c</b> example is a simplified C version of <b>rx_samples_to_file</b>,
+and the <b>tx_samples_c</b> example is a simplified C version of <b>tx_waveforms</b>. These examples
+can be easily adapted or serve as a starting point for your own UHD C applications.
+
+*/
+// vim:ft=doxygen:
diff --git a/host/docs/coding.dox b/host/docs/coding.dox
index 32dbe944a..6a15098d7 100644
--- a/host/docs/coding.dox
+++ b/host/docs/coding.dox
@@ -16,6 +16,11 @@ The Multi-USRP-Clock class provides a high-level interface to a single clock
device or set of clock devices, from which the time can be queried. See the
documentation for uhd::usrp_clock::multi_usrp_clock.
+\subsection coding_api_hilevelc High-Level: The C API
+
+Both USRP and clock devices can be interacted with using a C API wrapper included
+by default in all UHD builds. More information can be found \subpage page_c_api "here".
+
\subsection coding_api_lowlevel Low-Level: The device API
A device is an abstraction for hardware that is connected to the host
diff --git a/host/docs/dboards.dox b/host/docs/dboards.dox
index 3d6866a42..812a3a09e 100644
--- a/host/docs/dboards.dox
+++ b/host/docs/dboards.dox
@@ -372,6 +372,10 @@ Sensors:
- **rssi**: float for measured RSSI in dBm
- **temperature**: float for measured temperature in degC
+\subsection dboards_e300 E310 MIMO XCVR board
+
+Please refer to \ref e3x0_dboard_e310.
+
\subsection dboards_dbsrxmod DBSRX - Modifying for other boards that USRP1
Due to different clocking capabilities, the DBSRX will require
diff --git a/host/docs/general.dox b/host/docs/general.dox
index e4ffcfb6e..3e9dfc63a 100644
--- a/host/docs/general.dox
+++ b/host/docs/general.dox
@@ -34,6 +34,8 @@ support this functionality are:
- SBX-120
- CBX
- CBX-120
+- UBX
+- UBX-160
\subsubsection general_tuning_rxchain Tuning the receive chain:
@@ -78,6 +80,45 @@ second).
usrp->issue_stream_command(...);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+\section general_sampleratenotes Sample rate notes
+
+Sample rates as delivered to the host computer for USRP devices are constrained to follow several important rules.
+
+It is important to understand that strictly-integer <b>decimation</b> and <b>interpolation</b> are used within USRP
+hardware to meet the requested sample-rate requirements of the application at hand. That means that the desired
+sample rate must meet the requirement that master-clock-rate/desired-sample-rate be an integer ratio. Further, it is
+strongly desirable for that ratio to be <b>even</b>.
+
+There are further constraints on the desired sample rate, such that if the required decimation or interpolation exceeds 128,
+then the resulting decimation <b>must</b> be evenly divisible by 2, and that if the required decimation exceeds 256, the
+resulting decimation \b must be evenly divisible by 4.
+
+For USRP devices with fixed master clocks (notably: USRP1, USRP2, N2xx), there are fewer effective sample rates available than
+on USRP hardware that provides some flexibility in selecting a master clock. Several USRP devices support flexible master
+clock selection, allowing a broader range of sample rate selections by applications. See the individual devices' manual
+pages for more details.
+
+In many cases using USRPs with flexible master-clock rates, it is possible to achieve lower sample rates without running into
+the constraints of higher decimations, simply by choosing a lower master-clock rate to keep required decimation below 128.
+
+\subsection general_sampleratenotes_automatic Automatic master-clock selection
+
+In recent versions of UHD software (3.8.5 and newer), and on some devices (currently: B2xx and E3xx series),
+the master clock rate is chosen automatically (unless specified by the user).
+UHD will select a master clock rate that is consistent with the desired sample rate indicated by the application.
+
+\subsection general_sampleratenotes_nyquist Master clock rate and Nyquist
+
+In selecting a master clock rate on certain USRP hardware (X3xx and B1xx), it is important to select a rate that still provides
+correct alias suppression by the analog hardware. For daughtercards with a 40 MHz analog bandwidth, this means the clock rate
+must be <b>at least</b> 40 MHz, with better performance to be expected with a higher clock rate. For daughtercards
+with 160 MHz bandwidth, it must be <b>at least</b> 160 MHz, again, better performance is to expected with a higher clock rate.
+
+For hardware with fixed master clock rates, of course, this isn't a consideration.
+
+For B2xx and E3xx hardware, the alias suppression is handled differently by the AD936x RFIC, and master clock rate
+is significantly more flexible as a result.
+
\section general_ounotes Overflow/Underflow Notes
<b>Note:</b> The following overflow/underflow notes do not apply to USRP1,
diff --git a/host/docs/ni_rio_kernel.dox b/host/docs/ni_rio_kernel.dox
index d364cad3c..1fd2f0681 100644
--- a/host/docs/ni_rio_kernel.dox
+++ b/host/docs/ni_rio_kernel.dox
@@ -13,16 +13,16 @@ 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>
+<b>Currently, the latest supported kernel version is 4.2.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>.
+href=http://files.ettus.com/binaries/niusrprio/niusrprio-installer-15.0.0.tar.gz>here</a>.
Download the installer and extract it with the following command:
- tar zxf niusrprio-installer.tar.gz
+ tar zxf niusrprio-installer-15.0.0.tar.gz
The files will be extracted into a directory called <b>niusrprio-installer</b>.
@@ -57,10 +57,18 @@ a system restart, please create an init.d script that runs niusrprio_pcie start.
\subsection linux_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 or
+powering off the host computer.
+
+<b>WARNING:</b> If the device is unplugged without running the `niusrprio_pcie stop` command, the system could become unstable.
+
+\subsection linux_upgrades Upgrading Kernels
+
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`.
+when running `niusrprio start`.
ERROR: could not insert 'NiRioSrv': Unknown symbol in module, or unknown
parameter (see dmesg) ERROR: could not insert 'niusrpriok': Unknown symbol
@@ -69,15 +77,16 @@ when running `niusrprio star`.
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
+ 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
+ sudo /usr/local/bin/niusrprio_uninstall
Select y at the prompt, and the script will uninstall all installed components.
@@ -98,17 +107,16 @@ The kernel driver is only supported on:
\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
+The NI-USRP 14.5 installer can be found <a
+href="http://search.ni.com/nisearch/app/main/p/bot/no/ap/global/lang/en/pg/1/q/NI-USRP%2014.5/">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.
+- Choose the "2. Standard Download:NIUSRP1450.zip" option to download NIUSRP1450.zip to your computer
+- Extract the contents of NIUSRP1450.zip to 'C:\\National Instruments Downloads\\NI-USRP\\14.5'
+- In the extract location, run setup.exe and follow the prompts.
Reboot the computer after both the NI-USRP package has been installed.
@@ -118,19 +126,16 @@ 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".
+- 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.
+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 or
+powering off the host computer.
-<b>WARNING:</b> If the device is unplugged without running the above command, the
-system could become unstable.
+<b>WARNING:</b> If the device is unplugged without disabling it in device manager, the system could become unstable.
\subsection win_uninstall Uninstalling NI-USRP in Windows
diff --git a/host/docs/octoclock.dox b/host/docs/octoclock.dox
index 7469e0719..362ee779f 100644
--- a/host/docs/octoclock.dox
+++ b/host/docs/octoclock.dox
@@ -7,41 +7,24 @@
- Hardware Capabilities:
- Fully integrated timing source with 8-Way distribution (10 MHz and 1 PPS)
- User selection between internal GPSDO (when present) or external 10 MHz/1 PPS source
+ - Ethernet bootloader for easy firmware upgrade
- Source detection with automatic switch over in case of failure or disconnect
- Streaming GPS time and NMEA strings over Ethernet (OctoClock-G only)
\section octoclock_load Loading Firmware onto the Octoclock
-\subsection bootloader OctoClock bootloader
-
-If you purchased your OctoClock device before Ethernet functionality was introduced, or if your unit's
-bootloader has somehow become corrupted, you must burn the bootloader onto the device before you can load
-the primary firmware.
-
-To load the bootloader onto the OctoClock, two things are needed:
-
-- AVR programmer
-- AVRdude software
-
-Connect the AVR programmer to J108, as specified on the <a href="http://files.ettus.com/schematics/octoclock/octoclock.pdf">
-schematics</a>. Once you verify that the programmer is properly connected, run the following commands to burn the firmware:
+First, the OctoClock's bootloader needs to be loaded onto the device. Connect the AVR programmer to J108, as
+specified on the <a href="http://files.ettus.com/schematics/octoclock/octoclock.pdf">schematics</a>. Once you
+verify that the programmer is properly connected, run the following commands to load the bootloader:
cd <install path>/share/uhd/images
- avrdude -p atmega128 -c <programmer name> -P usb -U efuse:w:0xFF:m -U hfuse:w:0x80:m -U lfuse:w:0xFF:m -U flash:w:octoclock_bootloader.hex:i
+ avrdude -p atmega128 -c <programmer name> -P usb -U efuse:w:0xFF:m -U hfuse:w:0x80:m -U lfuse:w:0xEF:m -U flash:w:octoclock_r4_fw.hex:i
+
+When the bootloader is loaded, it will have a default IP address of `192.168.10.3`.
\b Note:
On Linux, `sudo avrdude ...` might be necessary to gain access to the programmer.
-Once the bootloader has been burned, power-cycle your OctoClock device and refer to the below instructions on burning the OctoClock's
-primary firmware.
-
-\subsection application Primary Octoclock firmware
-
-To load firmware onto the OctoClock, you must use the `octoclock_firmware_burner` utility, specifying the IP
-address of the OctoClock device, as follows:
-
- octoclock_firmware_burner --addr=192.168.10.3
-
\section octoclock_network Setting Up Networking
\subsection host_interface Setting up the host interface
diff --git a/host/docs/uhd.dox b/host/docs/uhd.dox
index 949c710b1..fcd0a25b0 100644
--- a/host/docs/uhd.dox
+++ b/host/docs/uhd.dox
@@ -12,6 +12,7 @@ Some additional pages on developing UHD are also available here:
\li \subpage page_coding
\li \subpage page_converters
\li \subpage page_stream
+\li \subpage page_rtp
*/
// vim:ft=doxygen:
diff --git a/host/docs/uhd_image_loader.1 b/host/docs/uhd_image_loader.1
new file mode 100644
index 000000000..5d5c88ec5
--- /dev/null
+++ b/host/docs/uhd_image_loader.1
@@ -0,0 +1,130 @@
+.TH "uhd_image_loader" 1 "3.9.0" UHD "User Commands"
+.SH NAME
+uhd_image_loader - UHD Image Loader
+
+.SH DESCRIPTION
+Burn firmware and FPGA images onto connected Ettus Research devices.
+
+.SH SYNOPSIS
+.B uhd_image_loader [OPTIONS]
+
+.SH OPTIONS
+.IP "List options:"
+--help
+.IP "Device and loader arguments:"
+--args=""
+.IP "Custom firmware filepath:"
+--fw-path=""
+.IP "Custom FPGA filepath:"
+--fpga-path=""
+.IP "Don't burn firmware:"
+--no-fw
+.IP "Don't burn FPGA:"
+--no-fpga
+
+.SH SPECIFYING A PARTICULAR DEVICE
+.sp
+Without any arguments given through the \fIargs=""\fR option, this utility will start a session
+with the first Ettus Research device it sees. The arguments shown below will narrow down the
+utility's search for a particular device:
+
+.SS All devices
+.sp
+The \fIname=\fR and \fIserial=\fR arguments can be used to specify any device except an
+uninitialized USB device or an OctoClock bootloader. The \fItype=\fR argument can be used
+to specify any device, as described below:
+
+"type=" argument
+
+Argument | Device
+
+type=usrp2 | USRP N200, USRP N210
+
+type=b200 | USRP B200, USRP B210
+
+type=e100 | USRP E100, USRP E110
+
+type=e3x0 | USRP E310
+
+type=octoclock | OctoClock
+
+.sp
+NOTE: The USRP1, USRP2, and USRP B100 are not supported.
+
+.SS Network devices
+.sp
+By default, this utility will check all network interfaces for network-based devices, but a specific
+IP address can be specified with the \fIaddr=\fR argument.
+
+.SS NI-RIO devices
+.sp
+An X-Series devices connected via PCIe can be specified by its NI-RIO resource through the \fIresource=\fR
+argument, and the RPC port through which to communicate with it can be specified with the \fIrpc-port=\fR
+argument. Using these options is not recommended, as their default values are almost always used.
+
+.SS OctoClock devices
+An OctoClock's name and serial are only exposed when the firmware is loaded, so if the device only has a
+bootloader, only the \fIaddr=\fR argument can be used to find it.
+
+.SH DEVICE-SPECIFIC LOADER OPTIONS
+.sp
+Certain devices have specific options for customizing their image loading process, and these can be passed
+in through the \fI--args=""\fR option. These arguments are specified below:
+
+.SS USRP N200, USRP N210
+.sp
+The \fIoverwrite-safe\fR option will overwrite the device's safe-mode firmware and FPGA images. This is
+NOT RECOMMENDED, as these images serve as the backup if the device's primary images are corrupted.
+
+.sp
+The \fIreset\fR option will automatically reset the device once the loading process finishes. When the
+device resets, it will have its new images loaded.
+
+.SS USRP X300, USRP X310 (Ethernet only)
+.sp
+The \fIconfigure\fR option will automatically reset the device once the loading process finishes. When
+the device resets, it will have its new FPGA image loaded.
+
+.sp
+The \fIverify\fR option will tell the device to internally verify the integrity of the image as it loads.
+This greatly increases the loading time.
+
+.SH EXAMPLES
+
+.SS Load only the default FPGA image onto a specific N2x0 device and reset
+.sp
+uhd_image_loader --args="type=usrp2,addr=192.168.10.2,reset" --no-fw
+.ft
+
+.SS Load a custom FPGA image onto a specific X3x0 device
+.sp
+uhd_image_loader --args="type=x300,addr=192.168.40.2" --fpga-path="/home/user/my_x300_fpga_image.bit"
+.ft
+
+.fi
+
+.SH SEE ALSO
+UHD documentation:
+.B http://files.ettus.com/manual/
+.LP
+GR-UHD documentation:
+.B http://gnuradio.org/doc/doxygen/page_uhd.html
+.LP
+Other UHD programs:
+.sp
+uhd_images_downloader(1) usrp2_card_burner(1)
+.SH AUTHOR
+This manual page was written by Nicholas Corgan
+for the Debian project (but may be used by others).
+.SH COPYRIGHT
+Copyright (c) 2015 Ettus Research LLC
+.LP
+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.
+.LP
+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.
diff --git a/host/docs/usrp2.dox b/host/docs/usrp2.dox
index 7b6cb9ed0..3f85e45b5 100644
--- a/host/docs/usrp2.dox
+++ b/host/docs/usrp2.dox
@@ -62,32 +62,21 @@ both the FPGA and firmware images before power cycling. This ensures
that when the device reboots, it has a compatible set of images to boot
into.
-\subsection usrp2_loadflash_netburner Use the net burner tool
+\subsection usrp2_loadflash_imageloader Use the image loader
Use default images:
- usrp_n2xx_simple_net_burner --addr=<IP address>
+ uhd_image_loader --args="type=usrp2,addr=<IP address>"
Use custom-built images:
- usrp_n2xx_simple_net_burner --addr=<IP address> --fw=<firmware path> --fpga=<FPGA path>
+ uhd_image_loader --args="type=usrp2,addr=<IP address>" --fw-path="<firmware path>" --fpga-path="<FPGA path>"
<b>Note:</b> Different hardware revisions require different FPGA images.
Determine the revision number from the sticker on the rear of the
chassis. Use this number to select the correct FPGA image for your
device.
-For users who would prefer a graphical utility, a Python-based
-alternative exists.
-
-\subsection usrp2_loadflash_gui Use the graphical net burner tool (Linux)
-
- <install-path>/lib/uhd/utils/usrp_n2xx_net_burner_gui.py
-
-\subsection usrp2_loadflash_guiwin Use the graphical net burner tool (Windows)
-
- <path_to_python.exe> <install-path>/lib/uhd/utils/usrp_n2xx_net_burner_gui.py
-
\subsection usrp2_loadflash_brick Device recovery and bricking
Its possible to put the device into an unusable state by loading bad
@@ -438,22 +427,20 @@ There is a sub-directory in the archive below the firmware/images called 'bit'.
The USRP should now be able to communicate on the network (you'll see some LEDs light up and network link be established). The next step is to flash the device and program the serial number. Both these steps can be done with UHD (the JTAG step is complete).
-To be sure, run `uhd_find_devices` and it should appear in the list - remember this IP address for the burner utility (should be 192.168.10.2 - make sure your network settings enable to you communicate with that subnet!).
+To be sure, run `uhd_find_devices` and it should appear in the list - remember this IP address for the image loader utility (should be 192.168.10.2 - make sure your network settings enable to you communicate with that subnet!).
-The first step is to flash the unit's safe-mode image, and then do a normal flash - both with the USRP N-series image burner utility.
+The first step is to flash the unit's safe-mode image, and then do a normal flash - both with the UHD Image Loader utility.
Make sure you have UHD installed, and the images from before, and follow the instructions in \ref usrp2_load.
-You can combine the `--fw` and `--fpga` arguments into the single invocation of the burner.
+You can combine the `--fw-path` and `--fpga-path` arguments into the single invocation of the image loader.
You will probably use "usrp_n210_fw.bin" for the firmware and "usrp_n210_r4_fpga.bin" for the FPGA image parameters (use the full/relative file path if your current directory is not that of the images).
- usrp_n2xx_net_burner.py --addr=192.168.10.2 --fw=usrp_n210_fw.bin --fpga=usrp_n210_r4_fpga.bin --overwrite-safe
+ uhd_image_loader --args="type=usrp2,addr=192.168.10.2,overwrite-safe" --fw-path=usrp_n210_fw.bin --fpga-path=usrp_n210_r4_fpga.bin
-Use `--overwrite-safe` the first time, and then repeat without it for the second time.
+Use the `overwrite-safe` option the first time, and then repeat without it for the second time.
Don't forget to power-cycle the device after it has been flashed.
-If you see a Python exception thrown (e.g. KeyError 65535) and something about if(check_rev)... use the --dont-check-rev option too (this is when the EEPROM has not yet been initialised, or has been blanked).
-
You can change the normal IP address by following the instructions in \ref usrp2_network_changeip.
If you run `uhd_usrp_probe`, you can see the EEPROM keys at the top. Example:
diff --git a/host/docs/usrp_b200.dox b/host/docs/usrp_b200.dox
index bd79c4470..6c4e52dd6 100644
--- a/host/docs/usrp_b200.dox
+++ b/host/docs/usrp_b200.dox
@@ -2,7 +2,7 @@
\tableofcontents
-\section b200_features Comparative features list - B200/B210
+\section b200_features Comparative features list - B200/B210/B200mini
- Hardware Capabilities:
- Integrated RF frontend (70 MHz - 6 GHz)
@@ -10,16 +10,20 @@
- External 10 MHz reference input
- Configurable clock rate
- Variable analog bandwidth (200 kHz - 56 MHz)
- - Internal GPSDO option (see \subpage page_gpsdo_b2x0 for details)
- - B210 Only:
- - MICTOR Debug Connector
- - JTAG Connector
- - Revision 6 with GPIO header
+ - GPIO header
+ - [B200/B210] Internal GPSDO option (see \subpage page_gpsdo_b2x0 for details)
+ - [B210/B200mini] JTAG Connector
+ - [B210] MICTOR Debug Connector
- FPGA Capabilities:
- Timed commands in FPGA
- Timed sampling in FPGA
-\section b200_imgs Specify a Non-standard Image
+\section b200_power Power
+In most cases, USB 3.0 bus power will be sufficient to power the device.
+If using USB 2.0 or a internal GPSDO, an external power supply or a cable designed
+to pull power from 2 USB ports (USB 3.0 dual A to micro-B or B) must be used.
+
+\section b200_imgs Specifying a Non-standard Image
UHD software will automatically select the USRP B2X0 images from the
installed images package. The image selection can be overridden with the
@@ -38,15 +42,40 @@ images:
The master clock rate feeds the RF frontends and the DSP chains. Users
may select non-default clock rates to acheive integer decimations or
-interpolations in the DSP chains. The default master clock rate defaults
-to 32 MHz, but can be set to any rate between 5 MHz and 61.44 MHz.
+interpolations in the DSP chains. The clock rate can be set to any value
+between 5 MHz and 61.44 MHz (or 30.72 MHz for dual-channel mode).
+Note that rates above 56 MHz are possible, but not recommended.
The user can set the master clock rate through the usrp API call
uhd::usrp::multi_usrp::set_master_clock_rate(), or the clock rate can be set through the
-device arguments, which many applications take: :
+device arguments, which many applications take:
uhd_usrp_probe --args="master_clock_rate=52e6"
+The property to control the master clock rate is a double value, called `tick_rate`.
+
+\subsection b200_auto_mcr Automatic Clock Rate Setting
+
+The default clock rate setting is to automatically set a clock rate
+depending on the requested sampling rate. The automatic clock rate selection
+is disabled when either `master_clock_rate` is given in the device initialization
+arguments, or when uhd::usrp::multi_usrp::set_master_clock_rate() is called.
+
+Note that the master clock rate must be an integer multiple of the sampling
+rate. If a master clock rate is chosen for which this condition does not
+hold, a warning will be displayed and a different sampling rate is used internally.
+
+Nevertheless, there are multiple valid values for the master clock rate
+for most sampling rates. The auto clock rate selection attempts to use
+the largest possible clock rate as to enable as many half-band filters
+as possible. Expert users might have cases where a more fine-grained
+control over the resampling stages is required, in which case manually
+selecting a master clock rate might be more suitable than the automatic
+rate.
+
+The property to dis- or enable the auto tick rate is a boolean value,
+`auto_tick_rate`.
+
\section b200_fe RF Frontend Notes
The B200 features an integrated RF frontend.
@@ -54,7 +83,7 @@ The B200 features an integrated RF frontend.
\subsection b200_fe_tuning Frontend tuning
The RF frontend has individually tunable receive and transmit chains. On
-the B200, there is one transmit and one receive RF frontend. On the
+the B200 and B200 mini, there is one transmit and one receive RF frontend. On the
B210, both transmit and receive can be used in a MIMO configuration. For
the MIMO case, both receive frontends share the RX LO, and both transmit
frontends share the TX LO. Each LO is tunable between 50 MHz and 6 GHz.
@@ -89,7 +118,7 @@ rate.
\subsection LED Indicators
-Below is a table of the LED indicators and their meanings:
+Below is a table of the B200/B210 LED indicators and their meanings:
<table>
<tr>
@@ -125,6 +154,36 @@ Below is a table of the LED indicators and their meanings:
</tr>
</table>
+Below is a table of the B200mini LED indicators and their meanings:
+
+<table>
+ <tr>
+ <th>Component ID</th><th>Description</th><th>Details</th>
+ </tr>
+ <tr>
+ <td>PWR LED</td> <td>Power Indicator</td> <td>off = no power applied<br>
+ on = power applied (external or USB)</td>
+ </tr>
+ <tr>
+ <td>TRX LED</td> <td>TX/RX Activity</td> <td>off = no activity<br>
+ green = receiving<br>
+ red = transmitting<br>
+ orange = switching between transmitting and receiving</td>
+ </tr>
+ <tr>
+ <td>RX2 LED</td> <td>RX2 Activity</td> <td>off = no activity<br>
+ green = receiving</td>
+ </tr>
+ <tr>
+ <td>S0 LED</td> <td>Reference Lock</td> <td>off = no activity
+ green = locked</td>
+ </tr>
+ <tr>
+ <td>S1 LED</td> <td>Reference Present</td> <td>off = reference level low or not present<br>
+ green = reference level high</td>
+ </tr>
+</table>
+
TX LED indicators are on when transimitting data and off when no samples are
available to transmit. RX LED indicators are on when sending samples to the
host and off when unable to do so. This means that TX/RX activity LED
@@ -135,7 +194,7 @@ well.
\subsection External Connections
-Below is a table showing the external connections and respective power information:
+Below is a table showing the B200/B210 external connections and respective power information:
<table>
<tr>
@@ -172,15 +231,36 @@ Below is a table showing the external connections and respective power informati
</tr>
</table>
+Below is a table showing the B200mini external connections and respective power information:
+
+<table>
+<tr>
+ <th>Component ID</th> <th>Description</th> <th> Details</th>
+</tr>
+<tr>
+ <td>USB3</td> <td>USB Connector</td> <td>USB 3.0</td>
+</tr>
+<tr>
+ <td>J1</td> <td>TRX</td> <td>TX power +20dBm max<br>
+ RX power -15dBm max</td>
+</tr>
+<tr>
+ <td>J2</td> <td>RX2</td> <td>RX power -15dBm max</td>
+</tr>
+<tr>
+ <td>J3</td> <td>External 10MHz/PPS Reference</td> <td>+15 dBm max</td
+</tr>
+</table>
+
\subsection b200_switches On-Board Connectors and Switches
-Below is a table showing the on-board connectors and switches:
+Below is a table showing the B200/B210 on-board connectors and switches:
Component ID | Description | Details
------------------------|----------------------------|---------------------------------------------------
J502<sup>1</sup> | Mictor Connector | Interface to FPGA for I/O and inspection.
J503<sup>1</sup> | JTAG Header | Interface to FPGA for programming and debugging.
- J504<sup>2</sup> | GPIO Header | Header running to the FPGA for GPIO purposes.
+ J504<sup>2</sup> | GPIO Header | Header connected to the FPGA for GPIO purposes.
S700 | FX3 Hard Reset Switch | Resets the USB controller / System reset
U100 | GPSDO socket | Interface to GPS disciplined reference oscillator
@@ -188,6 +268,16 @@ Component ID | Description | Details
<sup>2</sup> Only since rev. 6 (green board)
+Below is a table showing the B200mini on-board connectors and switches:
+
+Component ID | Description | Details
+------------------------|----------------------------|---------------------------------------------------
+ J5 | JTAG Header | Interface to FPGA for programming and debugging.
+ J6<sup>1</sup> | GPIO Header | Header connected to the FPGA for GPIO purposes.
+ SW1 | FX3 Hard Reset Switch | Resets the USB controller / System reset
+
+ <sup>1</sup> GPIO pinout is 1=3.3V, 2=GPIO_0, 3=GPIO_1, 4=GPIO_2, 5=GPIO_3, 6=GND, 7=3.3V, 8=GPIO_4, 9=GPIO_5, 10=,GPIO_6 11=GPIO_7, 12=GND
+
*/
// vim:ft=doxygen:
diff --git a/host/docs/usrp_e3x0.dox b/host/docs/usrp_e3x0.dox
index ac9687f4f..db4114360 100644
--- a/host/docs/usrp_e3x0.dox
+++ b/host/docs/usrp_e3x0.dox
@@ -134,6 +134,8 @@ which should return 'arm-oe-linux-gnueabi'.
$ cmake -DCMAKE_TOOLCHAIN_FILE=<youruhdsrc>/host/cmake/Toolchains/oe-sdk_cross.cmake -DCMAKE_INSTALL_PREFIX=/usr -DENABLE_E300=ON ..
$ make
+For instructions on building UHD on a PC to interact with your E-Series device, follow these instructions: \ref e3x0_uhd_build
+
\subsubsection e3x0_sdk_usage_gnuradio Building GNU Radio
-# Obtain the gnuradio source code via git.
@@ -188,9 +190,9 @@ builds)
$ export MACHINE="ettus-e300"
$ bitbake gnuradio-dev-image
\endcode
-When this completes, the files needed to create the sd card are in
-`tmp-glibc/deploy/images/ettus-e300`. See \ref e3x0_upgrade_sd_card for instructions to write the image to your sd card.
+When this completes, the files needed to create the SD card are in
+`tmp-glibc/deploy/images/ettus-e300`
-# Build the toolchain.
\code{.sh}
@@ -693,16 +695,28 @@ usrp->set_rx_subdev_spec("A:A A:B");
The following sensors are available for the USRP-E Series motherboards;
they can be queried through the API.
-- **fe_locked** - rx / tx frontend pll locked
+- **fe_locked** - rx / tx frontend PLL locked
- **temp** - processor temperature value
- **gps_time** and **gps_locked** sensors are added when the GPS is found
\subsection e3x0_network_mode Network Mode
-Your USRP-E series device can be used in network mode for narrow band signal observation, evaluation and debugging purposes.
+Your USRP-E series device can be used in network mode for narrow band signal observation, evaluation and debugging purposes. See the instructions below for how to use network mode.
Please note that when compared with normal operation as a standalone device the usable bandwidth is limited and therefore Network Mode is not the recommended mode of operation.
+\subsubsection e3x0_uhd_build Building UHD
+
+To work with your E-Series device in network mode, you will need to build UHD on your PC with extra CMake flags. Assuming you are in the host/build directory,
+see below:
+
+ $ cmake -DENABLE_E300=ON -DE300_FORCE_NETWORK=ON ..
+ $ make
+
+Once UHD is installed on your device, it will be able to interact with an E-Series device with network mode active (see below).
+
+\subsubsection e3x0_activating_network Activating Network Mode on the Device
+
In order to use the device in network mode it is necessary to start the *usrp_e3x0_network_mode* executable on the device.
In order to start the executable please log into your device either via SSH or serial console(see \ref e3x0_first_boot) and type
diff --git a/host/docs/usrp_x3x0.dox b/host/docs/usrp_x3x0.dox
index d9657424e..766766c21 100644
--- a/host/docs/usrp_x3x0.dox
+++ b/host/docs/usrp_x3x0.dox
@@ -89,13 +89,13 @@ number, you will have to update the FPGA image before you can start using your U
1. Download the current UHD images. You can use the `uhd_images_downloader` script provided
with UHD (see also \ref page_images).
-2. Use the `usrp_x3xx_fpga_burner` utility to update the FPGA image. On the command line, run:
+2. Use the `uhd_image_loader` utility to update the FPGA image. On the command line, run:
- usrp_x3xx_fpga_burner --addr=192.168.10.2 --type=HGS
+ uhd_image_loader --args="type=x300,addr=192.168.10.2,fpga=HGS"
If you have installed the images to a non-standard location, you might need to run (change the filename according to your device):
- usrp_x3xx_fpga_burner --addr=192.168.10.2 --fpga-path <path_to_images>/usrp_x310_fpga_HGS.bit
+ uhd_image_loader --args="type=x300,addr=192.168.10.2" --fpga-path="<path_to_images>/usrp_x310_fpga_HGS.bit"
The process of updating the FPGA image will take several minutes. Make sure the process of flashing the image does not get interrupted.
@@ -303,31 +303,31 @@ detect your device information, and you will need to use this number to
select which image to burn.
\b Note:
-The burner utility will default to using the appropriate BIT file if no custom
+The image loader utility will default to using the appropriate BIT file if no custom
FPGA image path is specified, but it is compatible with BIN, BIT, and LVBITX
images.
-\subsection x3x0_flash_burner_tool Use the burner tool over Ethernet
+\subsection uhd_image_loader_tool Use the image loader over Ethernet
Automatic FPGA path, detect image type:
- usrp_x3xx_fpga_burner --addr=<IP address>
+ uhd_image_loader --args="type=x300,addr=<IP address>"
Automatic FPGA path, select image type:
- usrp_x3xx_fpga_burner --addr=<IP address> --type=<HGS or XGS>
+ uhd_image_loader --args="type=x300,addr=<IP address>,fpga=<HGS or XGS>"
Manual FPGA path:
- usrp_x3xx_fpga_burner --addr=<IP address> --fpga-path=<path to FPGA image>
+ uhd_image_loader --args="type=x300,addr=<IP address>" --fpga-path="<path to FPGA image>"
-\subsection x3x0_flash_burner_tool_pcie Use the burner tool over PCI Express
+\subsection uhd_image_loader_tool_pcie Use the image loader over PCI Express
Automatic FPGA path, detect image type:
- usrp_x3xx_fpga_burner --resource=<NI-RIO resource>
+ uhd_image_loader --args="type=x300,resource=<NI-RIO resource>"
Automatic FPGA path, select image type:
- usrp_x3xx_fpga_burner --resource=<NI-RIO resource> --type=<HGS or XGS>
+ uhd_image_loader --args="type=x300,resource=<NI-RIO resource>,fpga=<HGS or XGS>"
Manual FPGA path:
- usrp_x3xx_fpga_burner --resource=<NI-RIO resource> --fpga-path=<path to FPGA image>
+ uhd_image_loader --args="type=x300,resource=<NI-RIO resource>" --fpga-path="<path to FPGA image>"
\subsection x3x0_flash_bricking Device recovery and bricking
It is possible to put the device into an unusable state by loading bad images ("bricking").
@@ -480,7 +480,7 @@ and that it is using the expected IP address.
ping 192.168.10.2
-\subsection x3x0_comm_problems_not_enumerated USRP device not enumerated (Linux)
+\subsection x3x0_comm_problems_not_enumerated Device not enumerated over PCI-Express (Linux)
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
@@ -493,19 +493,24 @@ run the following command:
If the device still does not enumerate after starting the device manager, make sure that the host computer
has successfully detected it. You can do so by running the following command:
- lspci -k -d 1093:c4c4
+ lspci -k -d 1093:c4c4
A device similar to the following should be detected:
- $ lspci -k -d 1093:c4c4
- 04:00.0 Signal processing controller: National Instruments ...
+ $ lspci -k -d 1093:c4c4
+ 04:00.0 Signal processing controller: National Instruments ...
Subsystem: National Instruments Device 76ca
Kernel driver in use: niusrpriok_shipped
-- A USRP X300 should appear with 'Subsystem: National Instruments Device 7736'
-- A USRP X310 should appear with 'Subsystem: National Instruments Device 76ca'
+- All USRP X-Series devices should appear with 'Subsystem: National Instruments Device'
+- The device ID following can be:
+ - USRP X300: 7736 or 7861
+ - USRP X310: 76CA or 7862
+ - NI-USRP 294xR: 772B, 77FB, 772C, 77FC, 772D, 77FD, 772E, 7853, 785B, 7854, 785C, 7855, 785D or 7856
+ - NI-USRP 295xR: 772F, 77FE, 7730, 77FF, 7731, 7800, 7732, 7857, 785E, 7858, 785F, 7859, 7860 or 785A
-\subsection x3x0_comm_problems_not_enumerated_win USRP device not enumerated (Windows)
+
+\subsection x3x0_comm_problems_not_enumerated_win Device not enumerated over PCI-Express (Windows)
UHD requires the RIO device manager service to be running in order to
communicate with an X-Series USRP over PCIe.
diff --git a/host/docs/usrp_x3x0_config.dox b/host/docs/usrp_x3x0_config.dox
index 2ee449cc2..adada7623 100644
--- a/host/docs/usrp_x3x0_config.dox
+++ b/host/docs/usrp_x3x0_config.dox
@@ -133,134 +133,19 @@ The above file was generated and modified on a Fedora 20 system.
\subsection x3x0cfg_hostpc_pcie PCI Express Configuration
+\ref page_ni_rio_kernel
+
\b Note: These instructions are \b only relevant for using a
USRP X3xx device over a cabled PCIe transport (PCIe over MXIe cable).
If you are using your USRP X3xx device over 1 Gigabit Ethernet or
10 Gigabit Ethernet, these instructions do <em>not apply to you.</em>
-\subsubsection x3x0cfg_hostpc_pcie_linux Linux Systems
-
In order to use the USRP X300/X310 with PCI Express on Linux,
NI USRP RIO kernel modules needs to be installed. In order to use
the PCIe kernel module, and thus PCIe-over-cable with the X3xx,
-your kernel version must be supported by the kernel module.
-Only 64-bit kernels are supported. To check if your kernel is supported
-by the drivers, check the NI USRP RIO website.
-
-#### Downloading and Extracting Installer
-
-- Download the installer from here: http://files.ettus.com/binaries/niusrprio/niusrprio-installer.tar.gz
-- Extract it with the following command:
-
- tar zxf niusrprio-installer.tar.gz
-
-The files will be extracted into a directory called `niusrprio-installer`.
-
-#### Installation
-
-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.
-
-#### Enabling/Disabling Usage
-
-Once everything is installed, run the following commands to enable
-use of the X300/X310 over PCI Express (the assumption is that `niusrprio_pcie`
-was installed into your `$PATH`):
-
- sudo niusrprio_pcie start
-
-To stop these processes, run the following command:
-
- sudo niusrprio_pcie stop
-
-To check if the kernel modules are loaded and if the RPC server
-is running, run the following command:
-
- niusrprio_pcie status
-
-\b Note: `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`.
-
-#### Hot-plugging/Power-cycling
-
-The USRP X3x0, NI USRP-294x and NI USRP-295x devices cannot 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 using the following command.
-
- sudo /usr/local/bin/niusrprio_pcie stop
-
-\b Warning: If the device is unplugged without running the above command, the system
-can become unstable and crash.
-
-#### Linux kernel upgrades
-
-The NI USRP RIO 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 start`:
-
- 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
-
-#### Uninstallation
+your operating and kernel must be supported by the drivers. Please look
+at the page above for a list of supported OS/kernel versions.
-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.
-
-\subsubsection x3x0cfg_hostpc_pcie_windows Windows
-
-In order to use the USRP X300/X310 with PCI Express on Windows, the
-NI-RIO driver package and the NI-USRP RIO kernel driver needs to be installed.
-
-\b Note: The kernel driver is only supported with certain Windows versions.
-Check the NI USRP RIO website to see if your version is supported.
-
-#### Installing NI-USRP
-
-The NI-USRP 1.3 installer can be downloaded from this location: http://www.ni.com/download/ni-usrp-1.3/4711/en/
-
-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.
-
-#### Enabling/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".
-
-#### Hot-plugging/Power-cycling
-
-The USRP X3x0, NI USRP-294x and NI USRP-295x devices cannot 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: If the device is unplugged without running the above command, the system can become unstable and crash
-
-#### Uninstalling NI-USRP
-
-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.
\subsection x3x0cfg_hostpc_pwr Power Management
@@ -282,20 +167,22 @@ issues, set the governor to "performance".
1. Install cpufrequtils:
- sudo apt-get install cpufrequtils
+ `sudo apt-get install cpufrequtils`
2. Edit `/etc/init.d/cpufrequtils` and set `GOVERNOR="performance"` on the
appropriate line (run as root):
- sed s/^GOVERNOR=.*$/GOVERNOR=\"performance\"/g /etc/init.d/cpufrequtils > /etc/init.d/cpufrequtils
+ `sed s/^GOVERNOR=.*$/GOVERNOR=\"performance\"/g /etc/init.d/cpufrequtils > /etc/init.d/cpufrequtils`
3. Restart cpufrequtils:
- sudo /etc/init.d/cpufrequtils restart
+ `sudo /etc/init.d/cpufrequtils restart`
\b Fedora:
- sudo cpupower frequency-set -g performance
+1. Change the CPU governor:
+
+ `sudo cpupower frequency-set -g performance`
\subsection x3x0cfg_hostpc_rtprio Real-Time & Priority Scheduling
@@ -320,38 +207,12 @@ Real-time scheduling is enabled via different methods depending on your
application and operating system. In GNU Radio Companion, it can be
turned on in each individual flowgraph.
-\subsection x3x0cfg_hostpc_volk Building with ORC & Volk
+\subsection x3x0cfg_hostpc_volk SIMD Acceleration
Especially when running high-performance applications, processing
-performance can be dramatically improved by SIMD instructions. UHD uses
-ORC to provide SIMD capability, and GNU Radio includes a SIMD library
-called "Volk". These should both be used to guarantee optimum
-performance.
-
-\subsubsection x3x0cfg_hostpc_volk_orc Compiling UHD with ORC
-
-ORC, the <a href="http://code.entropywave.com/orc/">Oil Runtime Compiler</a>,
-is a third-party compiler that UHD uses to create efficient SIMD code for
-your particular computer. ORC is generally easily installed from your
-OS's package manager.
-
-On Fedora:
-
- $ sudo yum update; sudo yum install orc-compiler orc-devel
-
-On Ubuntu:
-
- $ sudo apt-get update; sudo apt-get install liborc-<version> liborc-<version>-dev
-
-After installing ORC, when building UHD from source, you should see
-"ORC" as one of the configured UHD components.
-
- -- ######################################################
- -- # UHD enabled components
- -- ######################################################
- -- * LibUHD
- <cut for brevity>
- -- * ORC
+performance can be dramatically improved by SIMD instructions.
+GNU Radio includes a SIMD library
+called "Volk", which should be used to guarantee optimum performance.
\subsubsection x3x0cfg_hostpc_volk_volk Compiling GNURadio with Volk
diff --git a/host/docs/vrt_chdr.dox b/host/docs/vrt_chdr.dox
new file mode 100644
index 000000000..8ab177b21
--- /dev/null
+++ b/host/docs/vrt_chdr.dox
@@ -0,0 +1,83 @@
+/*! \page page_rtp Radio Transport Protocols
+
+\tableofcontents
+
+Radio transport protocols are used to exchange samples (or other items) between host and devices.
+If one were to sniff Ethernet traffic between a USRP and a PC, the packets would conform to a
+radio transport protocol.
+
+For USRP devices, two radio transport protocols are relevent: VRT (the VITA Radio Transport protocol)
+and CVITA (compressed VITA), also known as CHDR. Generation-3 devices and the B200 use CHDR, the rest
+use VRT.
+
+\section rtp_vrt VRT
+
+VRT is an open protocol defined by the VITA-49 standard. It was designed for interoperability,
+and to allow different device types to work with different software stacks.
+
+VRT is a very verbose standard, and only a subset is implemented in UHD/USRPs.
+The full standard is available from the VITA website: http://www.vita.com .
+
+
+\section rtp_chdr CVITA (CHDR)
+
+For the third generation of Ettus devices, a new type transport protocol was designed.
+It reduces the complexity of the original standard and uses a fixed-length 64-Bit header
+for everything except the timestamp. Because this is a "compressed" form of VITA, it
+was dubbed "Compressed VITA" (CVITA). The compressed header is called CHDR, which is why
+the protocol is often called CHDR itself (pronounced like the cheese "cheddar").
+
+By compressing all information into a 64-bit line, the header can efficiently be parsed
+in newer FPGAs, where the common streaming protocol is 64-Bit AXI. The first line in a
+packet already provides all necessary information to proceed.
+
+Some CHDR-specific functions can be found in: uhd::transport::vrt::chdr.
+
+The form of a CVITA packet is the following:
+
+Address (Bytes) | Length (Bytes) | Payload
+----------------|----------------|----------------------------
+0 | 8 | Compressed Header (CHDR)
+8 | 8 | Fractional Time (Optional!)
+8/16 | - | Data
+
+If there is no timestamp present, the data starts at address 8, otherwise, it starts at 16.
+
+The 64 Bits in the compressed header have the following meaning:
+
+Bits | Meaning
+-------|--------------------------------------------------
+63:62 | Packet Type
+61 | Has fractional time stamp (1: Yes)
+60 | End-of-burst or error flag
+59:48 | 12-bit sequence number
+47:32 | Total packet length in Bytes
+31:0 | Stream ID (SID)
+
+
+The packet type is determined mainly by the first two bits, although
+the EOB or error flag are also taken into consideration:
+
+Bit 63 | Bit 62 | Bit 60 | Packet Type
+-------|--------|--------|--------------
+0 | 0 | 0 | Data
+0 | 0 | 1 | Data (End-of-burst)
+0 | 1 | 0 | Flow Control
+1 | 0 | 0 | Command Packet
+1 | 1 | 0 | Command Response
+1 | 1 | 1 | Command Response (Error)
+
+\section vrt_tools Tools
+
+For CHDR, we provide a Wireshark dissector under tools/chdr_dissector. It can be used
+for Ethernet links as well as USB (e.g., for the B210).
+
+\section vrt_code Code
+
+Relevent code sections for the radio transport layer are:
+* uhd::transport::vrt - Namespace for radio transport protocol related functions and definitions
+* uhd::transport::vrt::chdr - Sub-namespace specifically for CVITA/CHDR
+* uhd::sid_t - Datatype to represent SIDs
+
+*/
+// vim:ft=doxygen:
generated by cgit v1.2.3 (git 2.39.1) at 2025-01-31 06:23:17 +0000