<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>UHD - Transport Application Notes</title>
<style type="text/css">
body{
font-family:Arial, Helvetica, sans-serif;
font-size:11pt;
color:black;
background-color:white;
width:90%;
margin:0 auto 0 auto;
}
div.document div.contents{
border:1px solid #333333;
padding:10px 30px 10px 10px;
margin-left:50px;
color:inherit;
background-color:#FCFCFC;
display:inline-block;
}
div.document p.topic-title{
font-weight:bold;
}
div.document a:link, div.document a:visited{
color:#236B8E;
background-color:inherit;
text-decoration:none;
}
div.document a:hover{
color:#4985D6;
background-color:inherit;
text-decoration:none;
}
div.document h1.title{
font-size:150%;
border-left:1px solid #333333;
border-bottom:1px solid #333333;
text-align:left;
padding:10px 0px 10px 10px;
margin:10px 5px 20px 5px;
color:#333333;
background-color:inherit;
}
div.document h2.subtitle, div.section h1{
margin-top:50px;
border-bottom:1px solid #333333;
font-size:140%;
text-align:center;
padding:20px 0px 10px 0px;
color:#333333;
background-color:inherit;
}
div.section h2{
font-size:110%;
text-align:left;
padding:15px 0px 5px 0px;
text-decoration:underline;
color:#333333;
background-color:inherit;
}
div.document pre.literal-block{
border:1px inset #333333;
padding:5px;
margin:10px 5px 10px 5px;
color:inherit;
background-color:#FCFCFC;
font-size:90%;
}
div.document table{
padding:5px;
font-size:95%;
}
div.document th{
padding:3px 7px 3px 7px;
border:1px solid #333333;
text-align:center;
color:inherit;
background-color:#ECECEC;
}
div.document tr{
}
div.document td{
padding:3px 7px 3px 7px;
border:1px solid #333333;
text-align:center;
color:inherit;
background-color:#FCFCFC;
}
div.footer{
margin:50px auto 30px auto;
text-align:center;
font-size:85%;
}
</style>
</head>
<body>
<div class="document" id="uhd-transport-application-notes">
<h1 class="title">UHD - Transport Application Notes</h1>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
<li><a class="reference internal" href="#udp-transport-sockets" id="id3">UDP Transport (Sockets)</a><ul>
<li><a class="reference internal" href="#transport-parameters" id="id4">Transport parameters</a></li>
<li><a class="reference internal" href="#flow-control-parameters" id="id5">Flow control parameters</a></li>
<li><a class="reference internal" href="#resize-socket-buffers" id="id6">Resize socket buffers</a></li>
<li><a class="reference internal" href="#latency-optimization" id="id7">Latency Optimization</a></li>
<li><a class="reference internal" href="#linux-specific-notes" id="id8">Linux specific notes</a></li>
<li><a class="reference internal" href="#windows-specific-notes" id="id9">Windows specific notes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#usb-transport-libusb" id="id10">USB Transport (LibUSB)</a><ul>
<li><a class="reference internal" href="#id1" id="id11">Transport parameters</a></li>
<li><a class="reference internal" href="#setup-udev-for-usb-linux" id="id12">Setup Udev for USB (Linux)</a></li>
<li><a class="reference internal" href="#install-usb-driver-windows" id="id13">Install USB driver (Windows)</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1>Introduction</h1>
<p>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 spcified, 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:</p>
</div>
<div class="section" id="udp-transport-sockets">
<h1>UDP Transport (Sockets)</h1>
<p>The UDP transport is implemented with user-space sockets.
This means standard Berkeley sockets API using send()/recv().</p>
<div class="section" id="transport-parameters">
<h2>Transport parameters</h2>
<p>The following parameters can be used to alter the transport's default behavior:</p>
<ul class="simple">
<li><strong>recv_frame_size:</strong> The size of a single receive buffer in bytes</li>
<li><strong>num_recv_frames:</strong> The number of receive buffers to allocate</li>
<li><strong>send_frame_size:</strong> The size of a single send buffer in bytes</li>
<li><strong>num_send_frames:</strong> The number of send buffers to allocate</li>
</ul>
<p><strong>Note1:</strong>
<strong>num_recv_frames</strong> does not affect performance.</p>
<p><strong>Note2:</strong>
<strong>num_send_frames</strong> does not affect performance.</p>
<p><strong>Note3:</strong>
<strong>recv_frame_size</strong> and <strong>send_frame_size</strong> 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.</p>
</div>
<div class="section" id="flow-control-parameters">
<h2>Flow control parameters</h2>
<p>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:</p>
<ul class="simple">
<li><strong>ups_per_fifo:</strong> The number of update packets for each FIFO's worth of bytes sent into the device</li>
<li><strong>ups_per_sec:</strong> The number of update packets per second (defaults to 20 updates per second)</li>
</ul>
</div>
<div class="section" id="resize-socket-buffers">
<h2>Resize socket buffers</h2>
<p>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:</p>
<ul class="simple">
<li><strong>recv_buff_size:</strong> The desired size of the receive buffer in bytes</li>
<li><strong>send_buff_size:</strong> The desired size of the send buffer in bytes</li>
</ul>
<p><strong>Note:</strong> Large send buffers tend to decrease transmit performance.</p>
</div>
<div class="section" id="latency-optimization">
<h2>Latency Optimization</h2>
<p>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:</p>
<p><strong>Note1:</strong>
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.</p>
<p><strong>Note2:</strong>
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:</p>
<ul class="simple">
<li><a class="reference external" href="http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.prftungd/doc/prftungd/interrupt_coal.htm">http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.prftungd/doc/prftungd/interrupt_coal.htm</a></li>
</ul>
</div>
<div class="section" id="linux-specific-notes">
<h2>Linux specific notes</h2>
<p>On Linux, the maximum buffer sizes are capped by the sysctl values
<strong>net.core.rmem_max</strong> and <strong>net.core.wmem_max</strong>.
To change the maximum values, run the following commands:</p>
<pre class="literal-block">
sudo sysctl -w net.core.rmem_max=<new value>
sudo sysctl -w net.core.wmem_max=<new value>
</pre>
<p>Set the values permanently by editing <strong>/etc/sysctl.conf</strong>.</p>
</div>
<div class="section" id="windows-specific-notes">
<h2>Windows specific notes</h2>
<p><strong>UDP send fast-path:</strong>
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:</p>
<ul class="simple">
<li>FastSendDatagramThreshold registry key documented here:<ul>
<li><a class="reference external" href="http://www.microsoft.com/windows/windowsmedia/howto/articles/optimize_web.aspx#appendix_e">http://www.microsoft.com/windows/windowsmedia/howto/articles/optimize_web.aspx#appendix_e</a></li>
</ul>
</li>
<li>Double click and run <install-path>/share/uhd/FastSendDatagramThreshold.reg</li>
<li>A system reboot is recommended after the registry key change.</li>
</ul>
<p><strong>Power profile:</strong>
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".</p>
</div>
</div>
<div class="section" id="usb-transport-libusb">
<h1>USB Transport (LibUSB)</h1>
<p>The USB transport is implemented with LibUSB.
LibUSB provides an asynchronous API for USB bulk transfers.</p>
<div class="section" id="id1">
<h2>Transport parameters</h2>
<p>The following parameters can be used to alter the transport's default behavior:</p>
<ul class="simple">
<li><strong>recv_frame_size:</strong> The size of a single receive transfers in bytes</li>
<li><strong>num_recv_frames:</strong> The number of simultaneous receive transfers</li>
<li><strong>send_frame_size:</strong> The size of a single send transfers in bytes</li>
<li><strong>num_send_frames:</strong> The number of simultaneous send transfers</li>
</ul>
</div>
<div class="section" id="setup-udev-for-usb-linux">
<h2>Setup Udev for USB (Linux)</h2>
<p>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:</p>
<pre class="literal-block">
cd <install-path>/lib/uhd/utils
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
</pre>
</div>
<div class="section" id="install-usb-driver-windows">
<h2>Install USB driver (Windows)</h2>
<p>A driver package must be installed to use a USB-based product with UHD software:</p>
<ul class="simple">
<li>Download the driver from the UHD wiki page <a class="reference external" href="http://files.ettus.com/binaries/misc/erllc_uhd_winusb_driver.zip">here</a>.</li>
<li>Unzip the file into a known location. We will refer to this as the <strong><directory></strong>.</li>
<li>Open the device manager and plug in the USRP device. You will see an unrecognized USB device in the device manager.</li>
<li>Right click on the unrecognized USB device and select update/install driver software (may vary for your OS).</li>
<li>In the driver installation wizard, select "browse for driver", browse to the <strong><directory></strong>, and select the <strong>.inf</strong> file.</li>
<li>Continue through the installation wizard until the driver is installed.</li>
</ul>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2014-10-15 11:47 UTC.
</div>
</body>
</html>
