Merge branch 'sched'

5 files changed, 143 insertions, 1 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index 61eede8b7..d0041f71c 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -23,6 +23,7 @@ SET(manual_sources
     build.rst
     coding.rst
     dboards.rst
+    general.rst
     usrp2.rst
 )
 
diff --git a/host/docs/general.rst b/host/docs/general.rst
new file mode 100644
index 000000000..7d1f467a0
--- /dev/null
+++ b/host/docs/general.rst
@@ -0,0 +1,79 @@
+========================================================================
+UHD - General Application Notes
+========================================================================
+
+.. contents:: Table of Contents
+
+------------------------------------------------------------------------
+Finding devices
+------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Device addressing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Deviced are addressed through key/value string pairs.
+These string pairs can be used to narrow down the search for a specific device or group of devices.
+Most UHD utility applications and examples have a --args parameter that takes a device address;
+where the device address is expressed as a delimited string.
+
+* See the documentation in types/device_addr.hpp for reference.
+* See device-specific application notes for usage.
+
+**Example:**
+::
+
+    serial=0x1234, type=usrpx
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Device discovery
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Devices attached to your system can be discovered using the "uhd_find_devices" program.
+The find devices program scans your system for supported devices and prints
+out an enumerated list of discovered devices and their addresses.
+The list of discovered devices can be narrowed down by specifying device address args.
+
+**Usage:**
+::
+
+    uhd_find_devices
+
+    -- OR --
+
+    uhd_find_devices --args <device-specific-address-args>
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Device properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Properties of devices attached to your system can be probed with the "uhd_usrp_probe" program.
+The usrp probe program contructs an instance of the device and prints out its properties;
+properties such as detected daughter-boards, frequency range, gain ranges, etc...
+
+**Usage:**
+::
+
+    uhd_usrp_probe --args <device-specific-address-args>
+
+------------------------------------------------------------------------
+Misc notes
+------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Process scheduling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The UHD will try to automatically boost the process's scheduling priority.
+Currently, this is only supported on platforms with *sched.h*.
+
+When setting the priority fails, the UHD prints out an error.
+This error is harmless, it simply means that your process will have a normal scheduling priority.
+
+**Linux Notes:**
+
+Non-privileged users need special permission to change the scheduling priority.
+Add the following line to */etc/security/limits.conf*:
+::
+
+    @<my_group>    -    rtprio    99
+
+Replace <my_group> with a group to which your user belongs.
+Settings will not take effect until the user has logged in and out.
diff --git a/host/docs/index.rst b/host/docs/index.rst
index 3dc7a2d98..b31a3d0ac 100644
--- a/host/docs/index.rst
+++ b/host/docs/index.rst
@@ -18,8 +18,9 @@ Building the UHD
 * `Build Guide <./build.html>`_
 
 ^^^^^^^^^^^^^^^^^^^^^
-Supported Devices
+Application Notes
 ^^^^^^^^^^^^^^^^^^^^^
+* `General App Notes <./general.html>`_
 * `USRP2 App Notes <./usrp2.html>`_
 * `Daughterboard App Notes <./dboards.html>`_
 
diff --git a/host/lib/CMakeLists.txt b/host/lib/CMakeLists.txt
index 7b765b0d3..50787f6a2 100644
--- a/host/lib/CMakeLists.txt
+++ b/host/lib/CMakeLists.txt
@@ -74,6 +74,21 @@ INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/usrp/dboard/CMakeLists.txt)
 INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/usrp/usrp2/CMakeLists.txt)
 
 ########################################################################
+# Setup defines for process scheduling
+########################################################################
+MESSAGE(STATUS "Configuring process scheduling...")
+
+INCLUDE(CheckIncludeFileCXX)
+CHECK_INCLUDE_FILE_CXX(sched.h HAVE_SCHED_H)
+
+IF(HAVE_SCHED_H)
+    MESSAGE(STATUS "  Process scheduling supported through sched_setscheduler.")
+    ADD_DEFINITIONS(-DHAVE_SCHED_H)
+ELSE(HAVE_SCHED_H)
+    MESSAGE(STATUS "  Process scheduling not supported.")
+ENDIF(HAVE_SCHED_H)
+
+########################################################################
 # Setup defines for module loading
 ########################################################################
 MESSAGE(STATUS "Configuring module loading...")
@@ -99,6 +114,7 @@ LIBUHD_APPEND_SOURCES(
     ${CMAKE_CURRENT_SOURCE_DIR}/device.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/gain_handler.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/load_modules.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/sched.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/types.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/utils.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/wax.cpp
diff --git a/host/lib/sched.cpp b/host/lib/sched.cpp
new file mode 100644
index 000000000..712014c9c
--- /dev/null
+++ b/host/lib/sched.cpp
@@ -0,0 +1,45 @@
+//
+// Copyright 2010 Ettus Research LLC
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+#include <uhd/utils/static.hpp>
+#include <stdexcept>
+#include <iostream>
+
+#ifdef HAVE_SCHED_H
+#include <sched.h>
+
+/*
+ * # /etc/security/limits.conf
+#
+@usrp   -       rtprio  99
+*/
+
+UHD_STATIC_BLOCK(setup_process_sched){
+    try{
+        int policy = SCHED_RR;
+        int max_pri = sched_get_priority_max(policy);
+        if (max_pri == -1) throw std::runtime_error("sched_get_priority_max with SCHED_RR failed");
+        sched_param sp; sp.sched_priority = max_pri;
+        int ss_ret = sched_setscheduler(0, policy, &sp);
+        if (ss_ret == -1) throw std::runtime_error("sched_setscheduler with SCHED_RR failed");
+    }
+    catch(const std::exception &e){
+        std::cerr << "Process scheduling error: " << e.what() << std::endl;
+    }
+}
+
+#endif /* HAVE_SCHED_H */