Merge branch 'usrp_e' of ettus.sourcerepo.com:ettus/uhdpriv into usrp_e

1 files changed, 88 insertions, 0 deletions

diff --git a/host/docs/transport.rst b/host/docs/transport.rst
new file mode 100644
index 000000000..432db4bb5
--- /dev/null
+++ b/host/docs/transport.rst
@@ -0,0 +1,88 @@
+========================================================================
+UHD - Transport Application Notes
+========================================================================
+
+.. contents:: Table of Contents
+
+------------------------------------------------------------------------
+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 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:
+
+------------------------------------------------------------------------
+UDP transport (ASIO)
+------------------------------------------------------------------------
+The UDP transport is implemented with Boost's ASIO library.
+ASIO provides an asynchronous API for user-space sockets.
+The transport implementation allocates a number of buffers
+and submits asynchronous requests for send and receive.
+IO service threads run in the background to process these requests.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Transport parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following parameters can be used to alter the transport's default behavior:
+
+* **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
+* **concurrency_hint:** The number of threads to run the IO service
+
+**Note:** num_send_frames and concurrency_hint will not have an effect
+as the asynchronous send implementation is currently disabled.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Resize socket buffers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+It may be useful 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.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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=<new value>
+    sudo sysctl -w net.core.wmem_max=<new value>
+
+Set the values permanently by editing */etc/sysctl.conf*
+
+------------------------------------------------------------------------
+USB transport (libusb)
+------------------------------------------------------------------------
+The USB transport is implemented with libusb.
+Libusb provides an asynchronous API for USB bulk transfers.
+The transport implementation allocates a number of buffers
+and submits asynchronous requests through libusb.
+Event handler threads run in the background to process these requests.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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
+* **concurrency_hint:** The number of threads to run the event handler