uhd: transport docs for UDP and USB (moved from usrp docs)

6 files changed, 91 insertions, 69 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index bbb8812b0..65db3befc 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -25,6 +25,7 @@ SET(manual_sources
     dboards.rst
     general.rst
     images.rst
+    transport.rst
     usrp1.rst
     usrp2.rst
 )
diff --git a/host/docs/index.rst b/host/docs/index.rst
index bd55edc0b..7f8129e2d 100644
--- a/host/docs/index.rst
+++ b/host/docs/index.rst
@@ -20,11 +20,12 @@ Building the UHD
 ^^^^^^^^^^^^^^^^^^^^^
 Application Notes
 ^^^^^^^^^^^^^^^^^^^^^
-* `General App Notes <./general.html>`_
+* `General Application Notes <./general.html>`_
 * `Firmware and FPGA Image Notes <./images.html>`_
-* `USRP1 App Notes <./usrp1.html>`_
-* `USRP2 App Notes <./usrp2.html>`_
-* `Daughterboard App Notes <./dboards.html>`_
+* `USRP1 Application Notes <./usrp1.html>`_
+* `USRP2 Application Notes <./usrp2.html>`_
+* `Daughterboard Application Notes <./dboards.html>`_
+* `Transport Application Notes <./transport.html>`_
 
 ^^^^^^^^^^^^^^^^^^^^^
 API Documentation
diff --git a/host/docs/transport.rst b/host/docs/transport.rst
new file mode 100644
index 000000000..d6a146c67
--- /dev/null
+++ b/host/docs/transport.rst
@@ -0,0 +1,81 @@
+========================================================================
+UHD - Transport Application Notes
+========================================================================
+
+.. contents:: Table of Contents
+
+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
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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.
+A single thread runs in the background
+and executes the libusb event handler 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
diff --git a/host/docs/usrp1.rst b/host/docs/usrp1.rst
index 0baa93a45..3443fd871 100644
--- a/host/docs/usrp1.rst
+++ b/host/docs/usrp1.rst
@@ -60,29 +60,6 @@ Example device address string representations to specify non-standard firmware a
 
     fpga=usrp1_fpga_4rx.rbf, fw=usrp1_fw_custom.ihx
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Change USB transfer parameters
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The advanced user may manipulate parameters of the usb bulk transfers
-for various reasons, such as lowering latency or increasing buffer size.
-By default, the UHD will use values for these parameters
-that are known to perform well on a variety of systems.
-The following device address parameters can be used to manipulate USB bulk transfers:
-
-* **recv_xfer_size:** the size of each receive bulk transfer in bytes
-* **recv_num_xfers:** the number of simultaneous receive bulk transfers
-* **send_xfer_size:** the size of each send bulk transfer in bytes
-* **send_num_xfers:** the number of simultaneous send bulk transfers
-
-Example usage, set the device address markup string to the following:
-::
-
-    serial=12345678, recv_num_xfers=16
-
-   -- OR --
-
-    serial=12345678, recv_xfer_size=2048, recv_num_xfers=16
-
 ------------------------------------------------------------------------
 Specifying the subdevice to use
 ------------------------------------------------------------------------
diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst
index 70e5ea28b..1ebab388a 100644
--- a/host/docs/usrp2.rst
+++ b/host/docs/usrp2.rst
@@ -166,47 +166,6 @@ The device address string representation for 2 USRP2s with IPv4 addresses 192.16
     addr=192.168.10.2 192.168.20.2
 
 ------------------------------------------------------------------------
-Resize the send and receive 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 you application cannot process samples fast enough,
-no amount of buffering can save you.
-
-By default, the UHD will try to resize both the send and receive buffer for optimum performance.
-A warning will be printed on instantiation if the actual buffer size is insufficient.
-See the OS specific notes below:
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-OS 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*
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Device address params
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To manually set the size of the buffers,
-the usrp2 will accept two optional parameters in the device address.
-Each parameter will accept a numeric value for the number of bytes.
-
-* recv_buff_size
-* send_buff_size
-
-Example usage, set the device address markup string to the following:
-::
-
-    addr=192.168.10.2, recv_buff_size=100e6
-
-------------------------------------------------------------------------
 Hardware setup notes
 ------------------------------------------------------------------------
 
diff --git a/host/lib/transport/udp_zero_copy_asio.cpp b/host/lib/transport/udp_zero_copy_asio.cpp
index ada282e07..a87f17a91 100644
--- a/host/lib/transport/udp_zero_copy_asio.cpp
+++ b/host/lib/transport/udp_zero_copy_asio.cpp
@@ -248,7 +248,10 @@ template<typename Opt> static void resize_buff_helper(
         if (actual_size < target_size) uhd::print_warning(str(boost::format(
             "The %s buffer is smaller than the requested size.\n"
             "The minimum recommended buffer size is %d bytes.\n"
-            "See the USRP2 application notes on buffer resizing.\n"
+            "See the transport application notes on buffer resizing.\n"
+            #if defined(UHD_PLATFORM_LINUX)
+            "On Linux: sudo sysctl -w net.core.rmem_max=%2%\n"
+            #endif /*defined(UHD_PLATFORM_LINUX)*/
         ) % name % min_sock_buff_size));
     }