diff options
Diffstat (limited to 'host/docs/usrp_x3x0_config.rst')
| -rw-r--r-- | host/docs/usrp_x3x0_config.rst | 319 |
1 files changed, 0 insertions, 319 deletions
diff --git a/host/docs/usrp_x3x0_config.rst b/host/docs/usrp_x3x0_config.rst deleted file mode 100644 index 4be247b04..000000000 --- a/host/docs/usrp_x3x0_config.rst +++ /dev/null @@ -1,319 +0,0 @@ -======================================================================== -UHD - System Configuration for USRP X3x0 Series -======================================================================== - -.. contents:: Table of Contents - ------------------------------------------------------------------------- -Configuring your Host PC ------------------------------------------------------------------------- - -The USRP X3x0 is capable of delivering very fast sample rates to the host PC, -and even high-powered desktops can have trouble keeping up at the higher rates. -You can improve the performance of your host by configuring a number of -settings that affect the performance of your computer. - -These are: - - * Kernel Version - * Network Configuration - * Power Management Configuration - * Real-Time & Priority Scheduling - * Building with ORC & Volk - -These items are covered in more detail, below. - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Kernel Version -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Performance issues may be encountered with Linux kernels earlier than 3.11. -Ettus Research strongly recommends using kernel version 3.11 or higher for high -sample rates. - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Network Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When using Ethernet interfaces to communicate with the device, it is necessary -to configure a number of facets regarding your network connection. - -Configuring NetworkManager -------------------------------------- -Fedora and Ubuntu both use NetworkManager to manage network connections. -Unfortunately, NetworkManager often tries to take control of a connection and -will disconnect the interface. - -You should open your NetworkManager configuration and tell it to ignore the -network interface you are using. **This is not the same as simply setting -a static IP address.** You *must* tell NetworkManager to ignore the interface. - -Changing the host's IP address -------------------------------------- - -On a Linux system, you can add a static IP address very easily by using the -'ip' command: - -:: - - sudo ip addr add 192.168.10.1/24 dev <interface> - -Note that **<interface>** is usually something like **eth0**. You can discover the -names of the network interfaces in your computer by running: - -:: - - ip addr show - -Configuring the Socket Buffers -------------------------------------- -It is necessary to increase the maximum size of the socket buffers to avoid -potential overflows and underruns at high sample rates. Add the following -entries into /etc/sysctl.conf (root privileges required): - -:: - - net.core.rmem_max=33554432 - net.core.wmem_max=33554432 - -Either restart the system or issue the following commands: - -:: - - sudo sysctl -w net.core.rmem_max=33554432 - sudo sysctl -w net.core.wmem_max=33554432 - - -Configuring the MTU -------------------------------------- -In order to achieve maximum performance, we recommend setting the MTU size to -9000 for 10 GigE and 1500 for 1 GigE. It is possible to use smaller MTUs, but this -can affect performance. With some NICs, setting the MTU too high can also cause issues. -To set the MTU to 9000, you can use the following command: - -:: - - sudo ifconfig <interface> mtu 9000 # For 10 GigE - sudo ifconfig <interface> mtu 1500 # For 1 GigE - -Using these MTUs will set the frame sizes for UHD communication to 8000 and 1472, -respectively. - -In some cases, specifying the frame size manually by adding the argument -"<send/recv>_frame_size=1472" can solve issues. Note that a frame size of 1472 will limit -the available sampling rate, although this is not a problem on 1 GigE. - - -Configuring the Firewall -------------------------------------- -Many Linux distributions come installed with a Firewall, by default. The -Firewall will often interfere with your ability to communicate with your USRP. -You should configure your firewall to "trust" the interface you are using. -Setting this properly depends on your OS and firewall configuration method. - -When using UHD software, if an IP address for the USRP-X Series device is not specified, -the software will use UDP broadcast packets to locate the USRP-X Series device. -On some systems, the firewall will block UDP broadcast packets. -It is therefore recommended that you change or disable your firewall settings. - -Interface Configuration File (Fedora) -------------------------------------- -On Fedora systems, you can configure the network interface mostly from one -place (with the exception of the socket buffers). Each interface on your system -should have a file in: - -:: - - /etc/sysconfig/network-scripts/ - -As an example, if your 1GigE interface is "em1", your "ifcfg-em1" configuration -file should look something like this, when configured for use with a USRP X3xx: - -:: - - TYPE="Ethernet" - BOOTPROTO="none" - IPADDR0="192.168.10.1" - DEFROUTE="yes" - IPV4_FAILURE_FATAL="no" - IPV6INIT="no" - IPV6_FAILURE_FATAL="no" - NAME="em1" - UUID="<specific to your device>" - ONBOOT="no" - HWADDR"<specific to your device>" - PEERDNS="yes" - PEERROUTES="yes" - ZONE="trusted" - MTU="9000" - NM_MANAGED="no" - -The above file was generated and modified on a "Fedora 20" system. - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Power Management -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Power management on the host system attempts to save power by reducing clock -frequencies or even powering off devices while not in use. This can lead to -significant performance issues when trying to operate at high sample rates. -Ettus Research strongly recommends disabling all power management. - - -Setting the CPU Governors -------------------------------------- -In Linux, the CPU governors dictate the frequency at which the CPU operates and -attempt to reduce the CPU frequencies at certain times to save power. When -running at high sample rates, reduction of CPU frequencies can cause -significant performance issues. To prevent those issues, set the governor to -"performance". - -**Ubuntu:** -1. 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 - -3. Restart cpufrequtils: - -:: - - sudo /etc/init.d/cpufrequtils restart - -**Fedora:** - -:: - - sudo cpupower frequency-set -g performance - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Real-Time & Priority Scheduling -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Enabling real-time and priority scheduling can improve the total processing -throughput of your application. Priority scheduling should be enabled for UHD, -and real-time scheduling can be enabled by your application. - -Thread Priority Scheduling with UHD -------------------------------------- -For information regarding how to enable priority scheduling for UHD on your -system, please see the `General UHD Notes <./general.html#threading-notes>`_. - -Real-Time Scheduling in your Application ----------------------------------------- -Please note that turning on real-time scheduling in your application **may lock -up your computer** if the processor cannot keep up with the application. You -should generally avoid using real-time scheduling unless you need to. - -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. - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Building with ORC & Volk -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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. - -Compiling UHD with ORC -------------------------------------- -ORC, the `Oil Runtime Compiler <http://code.entropywave.com/orc/>`_, 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 - -Compiling GNURadio with Volk -------------------------------------- -If you are using GNURadio to build applications, you should compile GNURadio -with Volk. For instructions on how to do this, `refer to the GNURadio wiki -<http://gnuradio.org/redmine/projects/gnuradio/wiki/Volk>`_. - - ------------------------------------------------------------------------- -Host PC Hardware Selection ------------------------------------------------------------------------- -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Motherboard -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Testing has shown that some motherboards do not provide enough PCIe bus -bandwidth to support higher sample rates. Motherboards with PCIe 3.0 are -required and the PCIe architecture of the motherboard should be carefully -considered. Slots with dedicated PCIe lanes should be used for PCIe or 10GbE -cards that will be connected to the X3x0 device. - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -10GbE NIC -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Intel or Myricom 10GbE NICs are recommended. Mellanox, SolarFlare, and Chelsio -10GbE NICs are not currently recommended. The Ethernet card should be plugged -into the slot that has the most direct connection with the CPU (PCIe lanes are -not shared with another slot). Refer to the motherboard manual for more -information on PCIe architecture. - ------------------------------------------------------------------------- -Troubleshooting Performance Issues ------------------------------------------------------------------------- -The output on the host console provides indicators of performance issues in the -form of single upper-case letters. The following table lists the letters, -their meanings, and possible causes: - -========= ====================== ==================================================================== -Indicator Meaning Possible Causes -========= ====================== ==================================================================== -O Overflow on RX - Data is not being consumed by user's application fast enough. - - CPU governor or other power management not configured correctly. -D Dropped packet on RX - Network hardware failure. (Check host NIC, cable, switch, etc...) - - PCIe bus on host cannot sustain throughput. (Check ethtool -S <interface>). - - CPU governor or other power management not configured correctly. - - Frame size might not work with the current NIC's MTU. -U Underflow on TX - Samples are not being produced by user's application fast enough. - - CPU governor or other power management not configured correctly. -L Late packet - Samples are not being produced by user's application fast enough. - (usually on MIMO TX) - CPU governor or other power management not configured correctly. - - Incorrect/invalid time_spec provided. -S Sequence error on TX - Network hardware failure. (Check host NIC, cable, switch, etc...) - - Frame size might not work with the current NIC's MTU. -========= ====================== ==================================================================== - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Troubleshooting Ethernet Issues -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. First, check 'ifconfig <interface>' to see if there are any errors reported - on the interface. If there are errors, it is most likely a network hardware - problem. -2. Next, check the output of 'ethtool -S <interface>'. The output is - driver-specific, but may give important clues as to what may be happening. - For example, a high value on rx_missed_errors for an Intel NIC indicates - that the bus (i.e. PCIe) is not keeping up. -3. Finally, Wireshark can be used to validate the traffic between the host and - device and make sure there is no unwanted traffic on the interface. - |