/*! \page page_transport Transport Notes \tableofcontents \section transport_intro Introduction A transport is the layer between the packet interface and a device IO interface. The advanced user can pass optional parameters into the underlying transport layer through the device address. These optional parameters control how the transport object allocates memory, resizes kernel buffers, spawns threads, etc. When not specified, the transport layer will use values for these parameters that are known to perform well on a variety of systems. The transport parameters are defined below for the various transports in the UHD software. \subsection transport_param_overrides Overriding transport parameters On MPMD-based and X300 devices, applications may wish to further modify certain transport parameters beyond the default values chosen by the UHD software or those supplied via the device address. For the following transport parameters, if a value is specified in the device arguments, that value is used to configure the transport, overriding the default value chosen by UHD. Additionally, if a value is specified in the stream arguments, that value takes priority over the value specified in the device arguments for the transport associated with the stream. Note: These default values apply to UDP transports. - `num_send_frames` and `num_recv_frames` - Default value: 32 - Note: Value is only applied to TX and RX links, not control links - `send_frame_size` - Default value (X3x0): 1472 (if link rate is GigE) or 4000 (if link rate is 10GigE) - Default value (MPMD): 1472 (if link rate is GigE); 8000 (if link rate is 10GigE); TX MTU (other link rates) - Note: Value will be capped at the link's send MTU - `recv_frame_size` - Default value (X3x0 and MPMD): 1472 (if link rate is GigE); 8000 (if link rate is 10GigE); RX MTU (other link rates) - Note: Value will be capped at the link's receive MTU - `send_buff_size` - Default value (X3x0 and MPMD): 20 ms of data at the link rate (2.5 MB for 1GigE, 25 MB for 10GigE) - `recv_buff_size` - Default value (X3x0 and MPMD): 20 ms of data at the link rate (X3x0: OR 64 1472-byte packets, whichever is larger) Note: Be aware that values may be further limited due to platform- specific restrictions. See the platform-specific notes below for more details. \section transport_udp UDP Transport (Sockets) The UDP transport is implemented with user-space sockets. This means standard Berkeley sockets API using `send()`/`recv()`. \subsection transport_udp_params Transport parameters The following parameters can be used to alter the transport's default behavior. These options can be passed to a USRP device as arguments at initialization time (see \ref config_devaddr). For MPMD-based and X3x0 devices, some of these parameters may also be passed via stream arguments (see \ref config_stream_args), in which case the values passed as device arguments are overridden. See \ref transport_param_overrides for more details on default values and the priority of device argument and stream argument overrides. - `recv_frame_size:` The size of a single receive buffer in bytes - `num_recv_frames:` The number of receive buffers to allocate - `send_frame_size:` The size of a single send buffer in bytes - `num_send_frames:` The number of send buffers to allocate - `recv_buff_fullness:` The targeted fullness factor of the the buffer (typically around 90%) - `ups_per_sec`: USRP2 only. Flow control ACKs per second on TX. - `ups_per_fifo`: USRP2 only. Flow control ACKs per total buffer size (in packets) on TX. Notes: - `num_recv_frames` does not affect performance. - `num_send_frames` does not affect performance. - `recv_frame_size` and `send_frame_size` can be used to increase or decrease the maximum number of samples per packet. The frame sizes default to an MTU of 1472 bytes per IP/UDP packet and may be increased if permitted by your network hardware. \subsection transport_udp_flow Flow control parameters The host-based flow control expects periodic update packets from the device. These update packets inform the host of the last packet consumed by the device, which allows the host to determine throttling conditions for the transmission of packets. The following mechanisms affect the transmission of periodic update packets: - `ups_per_fifo:` The number of update packets for each FIFO's worth of bytes sent into the device - `ups_per_sec:` The number of update packets per second (defaults to 20 updates per second) \subsection transport_udp_sockbufs Resize socket buffers It may be useful to increase the size of the socket buffers to move the burden of buffering samples into the kernel or to buffer incoming samples faster than they can be processed. However, if your application cannot process samples fast enough, no amount of buffering can save you. The following parameters can be used to alter socket's buffer sizes: - `recv_buff_size:` The desired size of the receive buffer in bytes - `send_buff_size:` The desired size of the send buffer in bytes Note: Large send buffers tend to decrease transmit performance. \subsection transport_udp_latency Latency Optimization Latency is a measurement of the time it takes a sample to travel between the host and device. Most computer hardware and software is bandwidth optimized, which may negatively affect latency. If your application has strict latency requirements, please consider the following notes: Note1: The time taken by the device to populate a packet is proportional to the sample rate. Therefore, to improve receive latency, configure the transport for a smaller frame size. Note2: For overall latency improvements, look for "Interrupt Coalescing" settings for your OS and Ethernet chipset. It seems the Intel Ethernet chipsets offer fine-grained control in Linux. Also, consult: - \subsection transport_udp_linux Linux specific notes On Linux, the maximum buffer sizes are capped by the sysctl values `net.core.rmem_max` and `net.core.wmem_max`. To change the maximum values, run the following commands: : sudo sysctl -w net.core.rmem_max= sudo sysctl -w net.core.wmem_max= 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 tx rx One can query the maximums and current settings with the following command: ethtool -g \subsection transport_udp_windows Windows specific notes UDP send fast-path: It is important to change the default UDP behavior such that 1500 byte packets still travel through the fast path of the sockets stack. This can be adjusted with the `FastSendDatagramThreshold` registry key: - `FastSendDatagramThreshold` registry key documented here: - - Double click and run `/share/uhd/FastSendDatagramThreshold.reg` - A system reboot is recommended after the registry key change. Power profile: The Windows power profile can seriously impact instantaneous bandwidth. Application can take time to ramp-up to full performance capability. It is recommended that users set the power profile to "high performance". \subsection transport_udp_osx Mac OS X specific notes OS X restricts the value of the `send_buff_size` and `recv_buff_size` transport parameters to a maximum value of 1 MiB (1048576 bytes). \section transport_usb USB Transport (LibUSB) The USB transport is implemented with LibUSB. LibUSB provides an asynchronous API for USB bulk transfers. \subsection transport_usb_params Transport parameters The following parameters can be used to alter the transport's default behavior: - `recv_frame_size:` The size of a single receive transfers in bytes - `num_recv_frames:` The number of simultaneous receive transfers - `send_frame_size:` The size of a single send transfers in bytes - `num_send_frames:` The number of simultaneous send transfers \subsection transport_usb_udev Setup Udev for USB (Linux) On Linux, Udev handles USB plug and unplug events. The following commands install a Udev rule so that non-root users may access the device: cd /lib/uhd/utils sudo cp uhd-usrp.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger \subsection transport_usb_installwin Install USB driver (Windows) A driver package must be installed to use a USB-based product with UHD software: - Download the driver from the UHD wiki page here. - Unzip the file into a known location. We will refer to this as the ``. - Open the device manager and plug in the USRP device. You will see an unrecognized USB device in the device manager. - Right click on the unrecognized USB device and select update/install driver software (may vary for your OS). - In the driver installation wizard, select "browse for driver", browse to the ``, and select the `.inf` file. - Continue through the installation wizard until the driver is installed. \section transport_pcie PCIe Transport (NI-RIO) The NI-RIO-based PCIe transport is only used with the X300/X310. It uses a separate driver stack (NI-RIO) which must be installed separately (see also \ref page_ni_rio_kernel). More information on how to set it up can be found here: \ref x3x0_hw_pcie. The X3x0 PCIe transport has 6 separate bidirectional DMA channels, and UHD will use two of those for command, control, and asynchronous messages. That means a total of four DMA channels can be used for streaming (either 4xRX, for TwinRX operations, or 2xRX + 2xTX for full-duplex operation). \subsection transport_pcie_params Transport parameters The following parameters can be used to alter the transport's default behavior: - `recv_frame_size:` The size of a single receive transfers in bytes - `num_recv_frames:` The number of simultaneous receive transfers - `recv_buff_size:` The socket buffer size. Must be a multiple of pages - `send_frame_size:` The size of a single send transfers in bytes - `num_send_frames:` The number of simultaneous send transfers - `send_buff_size:` The socket buffer size. Must be a multiple of pages */ // vim:ft=doxygen: