From d2494b0313399b141913ad332315fefbba012e94 Mon Sep 17 00:00:00 2001 From: Josh Blum Date: Tue, 5 Oct 2010 12:50:53 -0700 Subject: uhd: transport docs for UDP and USB (moved from usrp docs) --- host/docs/transport.rst | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 host/docs/transport.rst (limited to 'host/docs/transport.rst') 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= + sudo sysctl -w net.core.wmem_max= + +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 -- cgit v1.2.3 From 0fc641042ef81731fa84f796fd983a5a602e260c Mon Sep 17 00:00:00 2001 From: Josh Blum Date: Tue, 5 Oct 2010 15:47:58 -0700 Subject: usb: moved event handler thread into the zero copy interface --- host/docs/transport.rst | 1 + host/lib/transport/libusb1_base.cpp | 18 ------------------ host/lib/transport/libusb1_zero_copy.cpp | 28 ++++++++++++++++++++++++++++ 3 files changed, 29 insertions(+), 18 deletions(-) (limited to 'host/docs/transport.rst') diff --git a/host/docs/transport.rst b/host/docs/transport.rst index d6a146c67..30fc1d78f 100644 --- a/host/docs/transport.rst +++ b/host/docs/transport.rst @@ -79,3 +79,4 @@ The following parameters can be used to alter the transport's default behavior: * **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 diff --git a/host/lib/transport/libusb1_base.cpp b/host/lib/transport/libusb1_base.cpp index 910b04fc8..cfa77d9ca 100644 --- a/host/lib/transport/libusb1_base.cpp +++ b/host/lib/transport/libusb1_base.cpp @@ -16,12 +16,10 @@ // #include "libusb1_base.hpp" -#include #include #include #include #include -#include #include using namespace uhd; @@ -35,12 +33,9 @@ public: libusb_session_impl(void){ UHD_ASSERT_THROW(libusb_init(&_context) == 0); libusb_set_debug(_context, debug_level); - _thread_group.create_thread(boost::bind(&libusb_session_impl::run_event_loop, this)); } ~libusb_session_impl(void){ - _running = false; - _thread_group.join_all(); libusb_exit(_context); } @@ -50,19 +45,6 @@ public: private: libusb_context *_context; - boost::thread_group _thread_group; - bool _running; - - void run_event_loop(void){ - set_thread_priority_safe(); - _running = true; - timeval tv; - while(_running){ - tv.tv_sec = 0; - tv.tv_usec = 100000; //100ms - libusb_handle_events_timeout(this->get_context(), &tv); - } - } }; libusb::session::sptr libusb::session::get_global_session(void){ diff --git a/host/lib/transport/libusb1_zero_copy.cpp b/host/lib/transport/libusb1_zero_copy.cpp index df6db1eb9..f589d7c77 100644 --- a/host/lib/transport/libusb1_zero_copy.cpp +++ b/host/lib/transport/libusb1_zero_copy.cpp @@ -18,6 +18,7 @@ #include "libusb1_base.hpp" #include #include +#include #include #include #include @@ -290,6 +291,11 @@ public: const device_addr_t &hints ); + ~libusb_zero_copy_impl(void){ + _threads_running = false; + _thread_group.join_all(); + } + managed_recv_buffer::sptr get_recv_buff(double); managed_send_buffer::sptr get_send_buff(double); @@ -318,6 +324,22 @@ private: const size_t _recv_frame_size, _num_recv_frames; const size_t _send_frame_size, _num_send_frames; usb_endpoint::sptr _recv_ep, _send_ep; + + //event handler threads + boost::thread_group _thread_group; + bool _threads_running; + + void run_event_loop(void){ + set_thread_priority_safe(); + libusb::session::sptr session = libusb::session::get_global_session(); + _threads_running = true; + while(_threads_running){ + timeval tv; + tv.tv_sec = 0; + tv.tv_usec = 100000; //100ms + libusb_handle_events_timeout(session->get_context(), &tv); + } + } }; /* @@ -355,6 +377,12 @@ libusb_zero_copy_impl::libusb_zero_copy_impl( this->get_send_frame_size(), // buffer size per transfer this->get_num_send_frames() // number of libusb transfers )); + + //spawn the event handler threads + size_t concurrency = hints.cast("concurrency_hint", 1); + for (size_t i = 0; i < concurrency; i++) _thread_group.create_thread( + boost::bind(&libusb_zero_copy_impl::run_event_loop, this) + ); } /* -- cgit v1.2.3 From d6e6d8bffc1663fe82ba57e4dcf1ecbcec59c53e Mon Sep 17 00:00:00 2001 From: Josh Blum Date: Thu, 7 Oct 2010 11:22:19 -0700 Subject: uhd: tweaked docs/notes on transports --- host/docs/transport.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'host/docs/transport.rst') diff --git a/host/docs/transport.rst b/host/docs/transport.rst index 30fc1d78f..f247e9e34 100644 --- a/host/docs/transport.rst +++ b/host/docs/transport.rst @@ -4,6 +4,10 @@ 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, @@ -67,8 +71,7 @@ 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. +Event handler threads run in the background to process these requests. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Transport parameters -- cgit v1.2.3 From 83fd99cc7badb91a2e8c97048eb9ea694aba22eb Mon Sep 17 00:00:00 2001 From: Josh Blum Date: Fri, 8 Oct 2010 13:50:37 -0700 Subject: udp: add docs note about the udp transport --- host/docs/transport.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'host/docs/transport.rst') diff --git a/host/docs/transport.rst b/host/docs/transport.rst index f247e9e34..432db4bb5 100644 --- a/host/docs/transport.rst +++ b/host/docs/transport.rst @@ -36,6 +36,9 @@ The following parameters can be used to alter the transport's default behavior: * **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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.2.3