uhd: thread safety notes and moved some docs to general

2 files changed, 28 insertions, 29 deletions

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 <prefix>/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
@@ -9,6 +9,25 @@ 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 <my_group> 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 <prefix>/share/uhd/modules directory,
+* or installed into /usr/share/uhd/modules directory (unix only).