diff options
Diffstat (limited to 'host/docs')
-rw-r--r-- | host/docs/CMakeLists.txt | 8 | ||||
-rw-r--r-- | host/docs/Doxyfile.in | 2 | ||||
-rw-r--r-- | host/docs/build.dox | 24 | ||||
-rw-r--r-- | host/docs/configuration.dox | 7 | ||||
-rw-r--r-- | host/docs/dboards.dox | 14 | ||||
-rw-r--r-- | host/docs/transport.dox | 12 | ||||
-rw-r--r-- | host/docs/uhd_config_info.1 | 64 | ||||
-rw-r--r-- | host/docs/usrp_b200.dox | 4 | ||||
-rw-r--r-- | host/docs/usrp_x3x0.dox | 53 | ||||
-rw-r--r-- | host/docs/usrp_x3xx_fpga_burner.1 | 4 |
10 files changed, 163 insertions, 29 deletions
diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt index 7cb047264..e60f6a35d 100644 --- a/host/docs/CMakeLists.txt +++ b/host/docs/CMakeLists.txt @@ -45,6 +45,10 @@ IF(ENABLE_MANUAL) SET(DOXYGEN_DEP_COMPONENT "manual") SET(DOXYGEN_FPGA_MANUAL_REFERENCE "<a href=\"http://files.ettus.com/manual/md_fpga.html\">Part III: FPGA Manual</a>") SET(DOXYGEN_STRIP_EXTRA "") + SET(DOXYGEN_EXCLUDE_DIRS "") + IF(NOT ENABLE_RFNOC) + SET(DOXYGEN_EXCLUDE_DIRS "${DOXYGEN_EXCLUDE_DIRS} ${CMAKE_SOURCE_DIR}/include/uhd/rfnoc") + ENDIF(NOT ENABLE_RFNOC) # Now, check if we have the FPGA sources as well. # If so, pull them in: IF(HAS_FPGA_SUBMODULE) @@ -63,7 +67,6 @@ ENDIF(ENABLE_MANUAL) ######################################################################## # Setup API documentation (using Doxygen) ######################################################################## -MESSAGE(STATUS "") 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) OPTION(ENABLE_DOXYGEN_DOT "Let Doxygen use dot (requires graphviz)" OFF) @@ -92,7 +95,6 @@ ENDIF(ENABLE_DOXYGEN) ######################################################################## # Run Doxygen (on code and/or manual, depending on CMake flags) ######################################################################## -MESSAGE(STATUS "") IF(ENABLE_MANUAL_OR_DOXYGEN) #generate the doxygen configuration file SET(CMAKE_CURRENT_BINARY_DIR_DOXYGEN ${CMAKE_CURRENT_BINARY_DIR}/doxygen) @@ -134,6 +136,7 @@ SET(man_page_sources uhd_cal_rx_iq_balance.1 uhd_cal_tx_dc_offset.1 uhd_cal_tx_iq_balance.1 + uhd_config_info.1 uhd_find_devices.1 uhd_image_loader.1 uhd_images_downloader.1 @@ -146,7 +149,6 @@ SET(man_page_sources ######################################################################## # Setup man pages ######################################################################## -MESSAGE(STATUS "") FIND_PACKAGE(GZip) # No elegant way in CMake to reverse a boolean diff --git a/host/docs/Doxyfile.in b/host/docs/Doxyfile.in index 1533f7edc..556f2f4b1 100644 --- a/host/docs/Doxyfile.in +++ b/host/docs/Doxyfile.in @@ -687,7 +687,7 @@ RECURSIVE = YES # run. EXCLUDE = @CMAKE_SOURCE_DIR@/include/uhd/transport/nirio \ - @CMAKE_SOURCE_DIR@/include/uhd/transport/nirio_zero_copy.hpp + @CMAKE_SOURCE_DIR@/include/uhd/transport/nirio_zero_copy.hpp @DOXYGEN_EXCLUDE_DIRS@ # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded diff --git a/host/docs/build.dox b/host/docs/build.dox index 1390a8b6d..95f7bab85 100644 --- a/host/docs/build.dox +++ b/host/docs/build.dox @@ -26,8 +26,8 @@ follow the auxiliary download URL for the Windows installer (below). The following compilers are known to work and officially supported: -- GCC >= 4.4 -- Clang >= 3.1 +- GCC >= 4.8 +- Clang >= 3.3 - MSVC >= 2012; the free <a href="https://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx">Visual Studio Express Edition for Desktop</a> works. Other compilers (or lower versions) may work, but are unsupported. @@ -35,14 +35,14 @@ Other compilers (or lower versions) may work, but are unsupported. ### CMake - **Purpose:** generates project build files -- **Minimum Version:** 2.6 +- **Minimum Version:** 2.8 - **Usage:** build time (required) - **Download URL:** http://www.cmake.org/cmake/resources/software.html ### Boost - **Purpose:** C++ library -- **Minimum Version:** 1.46 +- **Minimum Version:** 1.53 - **Usage:** build time + runtime (required) - **Download URL:** http://www.boost.org/users/download/ - **Download URL (Windows installer):** http://sourceforge.net/projects/boost/files/boost-binaries/ @@ -58,7 +58,7 @@ Other compilers (or lower versions) may work, but are unsupported. ### Python - **Purpose:** used by mako and utility scripts -- **Minimum Version:** 2.6 +- **Minimum Version:** 2.7 - **Usage:** build time + runtime utility scripts (required) - **Download URL:** http://www.python.org/download/ @@ -99,6 +99,10 @@ You can install all the dependencies through the package manager: sudo yum -y install boost-devel libusb1-devel python-mako doxygen python-docutils cmake make gcc gcc-c++ +or + + sudo dnf -y install boost-devel libusb1-devel python-mako doxygen python-docutils cmake make gcc gcc-c++ + Your actual command may differ. \section build_get_source Getting the source code @@ -116,21 +120,21 @@ This will populate the `fpga-src` submodule inside the repository. You can also git submodule init git submodule update -Our source code repository contains two branches: +Our source code repository contains of two main branches: \li \b master: This is the main development branch, with updated new features and bug fixes. \li \b maint: This branch has all bugfixes since the last major release, but there are no new features. This is what you should be using if you need a stable release. We might also be publishing experimental feature branches which can then be found in the same repository. -All of our releases are associated with tags in the repository. +All of our versioned releases are associated with tags in the repository. \li <a href="https://github.com/EttusResearch/UHD/tags">Source archives for release tags</a> \section build_pybombs Using PyBOMBS -PyBOMBS is a command-line tool for Linuxes (and some Unixes) from the GNU Radio ecosystem and will do a source build of UHD, including setting up prerequisites/dependencies (regardless of the distribution) with the following command: +PyBOMBS is a command-line tool for Linuxes (and some Unixes) from the GNU Radio ecosystem and will do a source build of UHD, including setting up prerequisites/dependencies (regardless of the distribution). Assuming you have PyBOMBS set up, you can install UHD with the following command: - $ ./pybombs install uhd + $ pybombs install uhd Head to the <a href="https://github.com/gnuradio/pybombs/#installation">PyBOMBS Homepage</a> for more instructions. PyBOMBS can install UHD (as well as GNU Radio or similar projects) both into system directories as well as into user's home directories, omitting the requirement for superuser access. @@ -297,7 +301,7 @@ If your application uses CMake as a build system, the following command will setup up your build environment to link against UHD: \code{.cmake} -find_package(UHD "3.8.0") +find_package(UHD "3.10.0") \endcode This will set the CMake variable `UHD_INCLUDE_DIRS` and `UHD_LIBRARIES` diff --git a/host/docs/configuration.dox b/host/docs/configuration.dox index e16d1979e..4d6a6d504 100644 --- a/host/docs/configuration.dox +++ b/host/docs/configuration.dox @@ -27,9 +27,16 @@ and possible more options. fw | Provide alternative firmware | All USB Devices, X3x0 | fw=/path/to/fw.bin ignore-cal-file | Ignores existing device calibration files | All Devices with cal-file support| See \ref ignore_cal_file master_clock_rate | Master Clock Rate in Hz | X3x0, B2x0, B1x0, E3x0, E1x0 | master_clock_rate=16e6 + dboard_clock_rate | Daughterboard clock rate in Hz | X3x0 | dboard_clock_rate=50e6 mcr | Override master clock rate settings (see \ref usrp1_hw_extclk) | USRP1 | mcr=52e6 niusrprpc_port | RPC Port for NI USRP RIO | X3x0 | niusrprpc_port=5445 system_ref_rate | Reference Clock Rate in Hz | X3x0 | system_ref_rate=10e6 + self_cal_adc_delay | Run ADC transfer delay self-calibration. | X3x0 | self_cal_adc_delay=1 + ext_adc_self_test | Run an extended ADC self test (more than the usual) | X3x0 | ext_adc_self_test=1 + recover_mb_eeprom | Disable version checks. Can damage hardware. Only recommended for recovering devices with corrupted EEPROMs. | X3x0, N230 | recover_mb_eeprom=1 + skip_dram | Ignore DRAM FIFO block. Connect Tx streamers straight into DUC or radio. | X3x0 | skip_dram=1 + skip_ddc | Ignore DDC block. Connect Rx streamers straight into radio. | X3x0 | skip_ddc=1 + skip_duc | Ignore DUC block. Connect Rx streamers or DRAM straight into radio. | X3x0 | skip_duc=1 In addition, many of the streaming-related options can be set per-device at configuration time. diff --git a/host/docs/dboards.dox b/host/docs/dboards.dox index 99314b105..2ce6c4563 100644 --- a/host/docs/dboards.dox +++ b/host/docs/dboards.dox @@ -82,6 +82,8 @@ Sensors: The DBSRX2 board has 1 quadrature frontend. It defaults to direct conversion, but can use a low IF through `lo_offset` in uhd::tune_request_t. +Frequency Range: 800 MHz to 2.3 GHz + Receive Antennas: **J3** - **Frontend 0:** Complex baseband signal from antenna J3 @@ -93,7 +95,7 @@ Receive Gains: - **GC1**, Range: 0-73dB - **BBG**, Range: 0-15dB -Bandwidth (Hz): 8 MHz -80 MHz +Bandwidth (Hz): 8 MHz-80 MHz Sensors: @@ -184,6 +186,8 @@ Features: - Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t +Frequency Range: 50 MHz to 2.2 GHz + Transmit Antennas: **TX/RX** Receive Antennas: **TX/RX** or **RX2** @@ -219,6 +223,8 @@ Features: receive frequencies - Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t +Frequency Range: 400 MHz to 4.4 GHz + Transmit Antennas: **TX/RX** Receive Antennas: **TX/RX** or **RX2** @@ -261,6 +267,8 @@ Features: receive frequencies - Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t +Frequency Range: 1.2 GHz to 6 GHz + Transmit Antennas: **TX/RX** Receive Antennas: **TX/RX** or **RX2** @@ -303,6 +311,8 @@ Features: receive frequencies - Can be set to use Integer-N tuning for better spur performance with uhd::tune_request_t +Frequency Range: 10 MHz to 6 GHz + Transmit Antennas: **TX/RX** Receive Antennas: **TX/RX** or **RX2** @@ -352,6 +362,8 @@ Bandwidth: 6 MHz The TVRX2 board has 2 real-mode frontends. It is operated at a low IF. +Frequency Range: 50 MHz to 860 MHz + Receive Frontends: - **Frontend RX1:** real-mode baseband from antenna J100 diff --git a/host/docs/transport.dox b/host/docs/transport.dox index 72d59fb2a..ab163341d 100644 --- a/host/docs/transport.dox +++ b/host/docs/transport.dox @@ -95,6 +95,18 @@ values, run the following commands: : Set the values permanently by editing `/etc/sysctl.conf`. +It is also possible to tune the network interface controller (NIC) +by using ethtool. Increasing the number of descriptors for TX or RX can +dramatically boost performance on some hosts. + +To change the number of TX/RX descriptors, run the following command: + + sudo ethtool -G <interface> tx <N> rx <N> + +One can query the maximums and current settings with the following command: + + ethtool -g <interface> + \subsection transport_udp_windows Windows specific notes <b>UDP send fast-path:</b> It is important to change the default UDP diff --git a/host/docs/uhd_config_info.1 b/host/docs/uhd_config_info.1 new file mode 100644 index 000000000..edc1b7532 --- /dev/null +++ b/host/docs/uhd_config_info.1 @@ -0,0 +1,64 @@ +.TH "uhd_find_devices" 1 "3.9.1" UHD "User Commands" +.SH NAME +uhd_config_info \- USRP Hardware Driver Build Configuration Info +.SH DESCRIPTION +Print build information corresponding to this installation of the USRP +Hardware Driver (UHD). +.LP +The UHD package is the universal hardware driver for Ettus Research +products. The goal is to provide a host driver and API for +current and future Ettus Research products. Users will be able to use +the UHD driver standalone or with 3rd party applications. + +.SH SYNOPSIS +.B uhd_config_info [OPTIONS] + +.SH OPTIONS +.IP "Print date this build was compiled:" +--boost-version +.IP "Print Boost version used:" +--build-date +.IP "Print C compiler used:" +--c-compiler +.IP "Print C++ compiler used:" +--cxx-compiler +.IP "Print C compile flags:" +--c-flags +.IP "Print C++ compile flags:" +--cxx-flags +.IP "Print UHD components included in this build (comma-delimited):" +--enabled-components +.IP "Print default install prefix for this build:" +--install-prefix +.IP "Print libusb version used" +--libusb-version +.IP "Print all information listed above:" +--print-all +.IP "Print UHD version:" +--version +.IP "This help information:" +--help + +.SH SEE ALSO +UHD documentation: +.B http://files.ettus.com/manual/ +.LP +GR-UHD documentation: +.B http://gnuradio.org/doc/doxygen/page_uhd.html + +.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 National Instruments Corp. +.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/usrp_b200.dox b/host/docs/usrp_b200.dox index 248f07e85..c846e916f 100644 --- a/host/docs/usrp_b200.dox +++ b/host/docs/usrp_b200.dox @@ -214,7 +214,7 @@ Below is a table showing the B200/B210 external connections and respective power <td>J101</td> <td>GPS Antenna</td> <td>GPSDO will supply nominal voltage to antenna.</td> </tr> <tr> - <td>J100</td> <td>External 10 MHz Input</td> <td>+15 dBm max</td + <td>J100</td> <td>External 10 MHz Input</td> <td>+15 dBm max</td> </tr> <tr> <td>J800</td> <td>RF B: TX/RX</td> <td>TX power +20dBm max<br> @@ -249,7 +249,7 @@ Below is a table showing the B200mini external connections and respective power <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 + <td>J3</td> <td>External 10MHz/PPS Reference</td> <td>+15 dBm max</td> </tr> </table> diff --git a/host/docs/usrp_x3x0.dox b/host/docs/usrp_x3x0.dox index a37cc6ff4..db19ca551 100644 --- a/host/docs/usrp_x3x0.dox +++ b/host/docs/usrp_x3x0.dox @@ -91,11 +91,11 @@ number, you will have to update the FPGA image before you can start using your U with UHD (see also \ref page_images). 2. Use the `uhd_image_loader` utility to update the FPGA image. On the command line, run: - uhd_image_loader --args="type=x300,addr=192.168.10.2,fpga=HGS" + uhd_image_loader --args="type=x300,addr=192.168.10.2,fpga=HG" If you have installed the images to a non-standard location, you might need to run (change the filename according to your device): - uhd_image_loader --args="type=x300,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_HG.bit" The process of updating the FPGA image will take several minutes. Make sure the process of flashing the image does not get interrupted. @@ -131,6 +131,23 @@ Installation instructions for this interface are available on the official Intel The LEDs on the front panel can be useful in debugging hardware and software issues (see \ref x3x0_hw_fpanel) +### Dual 10 Gigabit Ethernet + +In order to utilize the X-series USRP over dual 10 Gigabit Ethernet interfaces, ensure +either the XG image is installed (see \ref x3x0_load_fpga_imgs_fpga_flavours). +In addition to burning the prerequisite FPGA image, it may also be necessary +to tune the network interface card (NIC) to eliminate drops (Ds) and reduce overflows (Os). +This is done by increasing the number of RX descriptors (see \ref transport_udp_linux). + +The benchmark_rate tool can be used to test this capability. +Run the following commands to test the X-series USRP over both 10 Gigabit +Ethernet interfaces with the maximum rate of 200 Msps per channel: + + cd <install-path>/lib/uhd/examples + ./benchmark_rate --args="type=x300,addr=<Primary IP>,second_addr=<secondary IP>" --channels="0,1" --rx_rate 200e6 + +The second interface is specified by the extra argument <b>second_addr</b>. + \subsection x3x0_hw_pcie PCI Express (Desktop) <b>Important Note: The USRP X-Series provides PCIe connectivity over MXI cable. @@ -249,8 +266,12 @@ behavior of the above interfaces. | FPGA Image Flavor | SFP+ Port 0 Interface | SFP+ Port 1 Interface | |---------------------|------------------------|------------------------| -| HGS (Default) | 1 Gigabit Ethernet | 10 Gigabit Ethernet | -| XGS | 10 Gigabit Ethernet | 10 Gigabit Ethernet | +| HG (Default) | 1 Gigabit Ethernet | 10 Gigabit Ethernet | +| XG | 10 Gigabit Ethernet | 10 Gigabit Ethernet | +| HA | 1 Gigabit Ethernet | Aurora | +| XA | 10 Gigabit Ethernet | Aurora | + +Note: The Aurora images need to be built manually from the FPGA source code. FPGA images are shipped in 2 formats: @@ -259,7 +280,7 @@ FPGA images are shipped in 2 formats: To get the latest images, simply use the uhd_images_downloader script. On Unix systems, use this command: - sudo uhd_images_downloader + $ [sudo] uhd_images_downloader On Windows, use: @@ -313,7 +334,7 @@ images. uhd_image_loader --args="type=x300,addr=<IP address>" Automatic FPGA path, select image type: - uhd_image_loader --args="type=x300,addr=<IP address>,fpga=<HGS or XGS>" + uhd_image_loader --args="type=x300,addr=<IP address>,fpga=<HG or XG>" Manual FPGA path: uhd_image_loader --args="type=x300,addr=<IP address>" --fpga-path="<path to FPGA image>" @@ -324,7 +345,7 @@ images. uhd_image_loader --args="type=x300,resource=<NI-RIO resource>" Automatic FPGA path, select image type: - uhd_image_loader --args="type=x300,resource=<NI-RIO resource>,fpga=<HGS or XGS>" + uhd_image_loader --args="type=x300,resource=<NI-RIO resource>,fpga=<HG or XG>" Manual FPGA path: uhd_image_loader --args="type=x300,resource=<NI-RIO resource>" --fpga-path="<path to FPGA image>" @@ -354,9 +375,9 @@ 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 ---------------------|-------------------------|--------------------------|-------------------------|-------------------------|------------------- - Gigabit | Port 0 (HGS Image) | 192.168.10.2 | 192.168.10.1 | 255.255.255.0 | `ip-addr0` - Ten Gigabit | Port 0 (XGS Image) | 192.168.30.2 | 192.168.30.1 | 255.255.255.0 | `ip-addr2` - Ten Gigabit | Port 1 (HGS/XGS Image) | 192.168.40.2 | 192.168.40.1 | 255.255.255.0 | `ip-addr3` + Gigabit | Port 0 (HG Image) | 192.168.10.2 | 192.168.10.1 | 255.255.255.0 | `ip-addr0` + Ten Gigabit | Port 0 (XG Image) | 192.168.30.2 | 192.168.30.1 | 255.255.255.0 | `ip-addr2` + Ten Gigabit | Port 1 (HG/XG Image) | 192.168.40.2 | 192.168.40.1 | 255.255.255.0 | `ip-addr3` As you can see, the X300/X310 actually stores different IP addresses, which all address the device differently: Each combination of Ethernet port and interface type (i.e., Gigabit or Ten Gigabit) has its own IP address. As an example, when addressing the device through 1 Gigabit Ethernet on its first port (Port 0), the relevant IP address is the one stored in the EEPROM with key `ip-addr0`, or 192.168.10.2 by default. @@ -530,6 +551,18 @@ When there is network traffic arriving at the Ethernet port, LEDs will light up. You can use this to make sure the network connection is correctly set up, e.g. by pinging the USRP and making sure the LEDs start to blink. +\section x3x0_usage_problems Usage Problems + +\subsection x3x0_corrupt_eeprom Corrupt EEPROM + +This is a rare bug in which the X-Series device's on-board EEPROM becomes corrupt and reports an incorrect +firmware and FPGA version. In this situation, UHD cannot properly use the device. To fix this bug, use +the **usrp_burn_mb_eeprom** utility as follows: + + usrp_burn_mb_eeprom --args="type=x300,recover_mb_eeprom,disable_adc_self_test" --values="revision=(NUM HERE)" + +Afterward, power-cycle your X-Series device for the changes to take effect. + \section x3x0_hw_notes Hardware Notes \subsection x3x0_hw_fpanel Front Panel diff --git a/host/docs/usrp_x3xx_fpga_burner.1 b/host/docs/usrp_x3xx_fpga_burner.1 index f07e52401..6b4e8c322 100644 --- a/host/docs/usrp_x3xx_fpga_burner.1 +++ b/host/docs/usrp_x3xx_fpga_burner.1 @@ -16,7 +16,7 @@ of that type and model, or a custom FPGA image path. --resource=\fI"Resource"\fR . IP "RPC Port:" --rpc-port=\fI"Port"\fR (default=5444) -. IP "Image Type (1G, HGS, or XGS):" +. IP "Image Type (1G, HG, or XG):" --type=\fI"Type"\fR . IP "Custom FPGA path:" --fpga-path=\fI"Path"\fR @@ -33,7 +33,7 @@ of that type and model, or a custom FPGA image path. .sp usrp_x3xx_fpga_burner --addr=192.168.10.2 --type=1G .SS Burning a Hybrid image over PCIe -usrp_x3xx_fpga_burner --resource=RIO0 --type=HGS +usrp_x3xx_fpga_burner --resource=RIO0 --type=HG .SS Burning a custom FPGA image over Ethernet usrp_x3xx_fpga_burner --addr=192.168.10.2 --fpga=path="custom_image.bit" .ft |