From ab6fc7345a0743543e62cd1b3d9681a78d72f8f1 Mon Sep 17 00:00:00 2001 From: Josh Blum Date: Tue, 8 Mar 2011 12:41:23 -0800 Subject: uhd: thread safety notes and moved some docs to general --- host/docs/coding.rst | 29 ----------------------------- host/docs/general.rst | 28 ++++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 29 deletions(-) (limited to 'host/docs') diff --git a/host/docs/coding.rst b/host/docs/coding.rst index ecca4e8b8..d5304c1c5 100644 --- a/host/docs/coding.rst +++ b/host/docs/coding.rst @@ -28,32 +28,3 @@ High-Level: The multi usrp The Multi-USRP class provides a FAT interface to a single USRP with one or more channels, or multiple USRPs in a homogeneous setup. See the documentation in *usrp/multi_usrp.hpp* for reference. - ------------------------------------------------------------------------- -Integrating custom hardware ------------------------------------------------------------------------- -Creators of custom hardware can create drivers that use the UHD API. -These drivers can be built as dynamically loadable modules that the UHD will load at runtime. - -For a module to be loaded at runtime, it must be: - -* found in the UHD_MODULE_PATH environment variable, -* installed into the /share/uhd/modules directory, -* or installed into /usr/share/uhd/modules directory (unix only). - -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Custom motherboard -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Create a new device driver when the driver in lib/usrp/ -cannot support your custom FPGA or hardware modifications. -Make a copy of the relevant driver code in lib/usrp/, make mods, and rename the class. -The new device code should register itself into the discovery and factory system. - -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Custom daughterboard -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Use code from an existing daughterboard in lib/usrp/dboard/* as an example. -Your daughterboard code should subclass an rx dboard, rx dboard, or xcvr dboard; -and it should respond to calls to get and set properties. -The new daughterboard code should register itself into the dboard manager -with a unique rx and/or tx 16 bit identification number. diff --git a/host/docs/general.rst b/host/docs/general.rst index 50ef24d6c..2894fbf88 100644 --- a/host/docs/general.rst +++ b/host/docs/general.rst @@ -8,6 +8,25 @@ UHD - General Application Notes Misc notes ------------------------------------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Thread safety notes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +For the most part, UHD is thread-safe. +Please observe the following limitations: + +**Fast-path thread requirements:** +It is safe to call send() and recv() simultaneously. However, +it is not safe to call recv() simultaneously from different thread contexts. +The same rule applies for recv(), send(), and recv_async_msg(). +One thread context per fast-path device method at a time. + +**Slow-path thread requirements:** +It is safe to change multiple settings simultaneously. However, +this could leave the settings for a device in an uncertain state. +The is because changing one setting could have an impact on how a call affects other settings. +Example: setting the channel mapping affects how the antennas are set. +It is recommended to use at most one thread context for manipulating device settings. + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Thread priority scheduling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -26,3 +45,12 @@ Add the following line to */etc/security/limits.conf*: Replace with a group to which your user belongs. Settings will not take effect until the user has logged in and out. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Support for dynamically loadable modules +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +For a module to be loaded at runtime, it must be: + +* found in the UHD_MODULE_PATH environment variable, +* installed into the /share/uhd/modules directory, +* or installed into /usr/share/uhd/modules directory (unix only). -- cgit v1.2.3