beef up README a bit

1 files changed, 91 insertions, 5 deletions

diff --git a/README b/README
index 9080b65..206773d 100644
--- a/README
+++ b/README
@@ -40,7 +40,9 @@ NOTES:
         also provides a-posteriori policy enforcement, i.e. it
         includes a canary-based watchdog that automatically demotes
         all real-time threads to SCHED_OTHER should the system
-        overload despite the logic pointed out above.
+        overload despite the logic pointed out above. For more
+        information regarding canary-based RT watchdogs, see the
+        Acknowledgments section below.
 
         In its duty to manage real-time scheduling *securely*
         RealtimeKit runs as unpriviliged user, and uses capabalities,
@@ -58,7 +60,7 @@ WHY:
 
         RealtimeKit hands out RT scheduling to specific threads that
         ask for it -- but only to those and due to SCHED_RESET_ON_FORK
-        it can be sure that this won't "leak".
+        it can be sure that this won't 'leak'.
 
         In contrast to RLIMIT_RTPRIO the RealtimeKit logic makes sure
         that only a certain number of threads can be made realtime,
@@ -78,7 +80,10 @@ CLIENTS:
 
         The thread IDs need to be passed as kernel tids as returned by
         gettid(), not a pthread_t! Only threads belonging to the
-        calling process can be made realtime.
+        calling process can be made realtime/high priority. (Please
+        note that gettid() is not available in glibc, you need to
+        implement that manually using syscall(). Consult the reference
+        client implementation for details.)
 
         A BSD-licensed reference implementation of the client is
         available in rtkit.[ch] as part of the package. You may copy
@@ -115,9 +120,90 @@ CLIENTS:
         falling back to plain SCHED_RR when SCHED_RESET_ON_FORK causes
         EINVAL migt be advisable).
 
+DAEMON:
+
+        The daemon is automatically started on first use via D-Bus
+        system bus activation.
+
+        Currently the daemon does not read on any configuration file,
+        however it can be configured with command line parameters. You
+        can edit
+
+        /usr/share/dbus-1/system-services/org.freedesktop.RealtimeKit1.service
+
+        to set those.
+
+        Run
+
+        /usr/libexec/rtkit-daemon --help
+
+        to get a quick overview on the supported parameters and their
+        defaults. Many of them should be obvious in their meaning. For
+        the remaining ones see below:
+
+        --max-realtime-priority= may be used to specify the maximum
+        realtime priority a client can acquire through
+        RealtimeKit. Please note that this value must be smaller than
+        the value passed to --our-realtime-priority=.
+
+        --our-realtime-priority= may be used to specify the realtime
+        priority of the daemon itself. Please note that this priority
+        is only used for a very short time while processing a client
+        request. Normally the daemon will not be running with a
+        realtime scheduling policy. The real-time priorities handed
+        out to the user must be lower than this value. (see above).
+
+        --min-nice-level= may be used to specify the minimum nice
+        level a client can acquire through RealtimeKit.
+
+        --our-nice-level= may be used to specify the nice level the
+        the daemon itself uses most of the time (except when
+        processing requests, see above). It is probably a good idea to
+        set this to a small positive value, to make sure that if the
+        system is overloaded already handing out further RT scheduling
+        will be delayed a bit.
+
+        --rttime-nsec-max= may be used to control which RLIMIT_RTTIME
+        value clients need to have chosen at minumum before they may
+        acquire RT scheduling through RealtimeKit.
+
+        --users-max= specifies how many users may acquire RT
+        scheduling at the same time for one or multiple of their
+        processes.
+
+        --processes-per-user-max= specifies how many processes per
+        user may acquire RT scheduling at the same time.
+
+        --threads-per-user-max= specifies how many threads per user
+        may acquire RT scheduling at the same time. Of course this
+        value should be set higher than --process-per-user-max=.
+
+        --actions-burst-sec= may be used to influence the rate
+        limiting logic in RealtimeKit. The daemon will only pass
+        realtime scheduling privileges to a maximum number of threads
+        within this timeframe (see below).
+
+        --actions-per-burst-max= may be used to influence the rate
+        limiting logic in RealtimeKit. The daemon will only pass
+        realtime scheduling privileges to this number of threads
+        within the time frame configured via
+        --actions-burst-sec=. When this limit is reached clients need
+        to wait until that time passes before requesting RT scheduling
+        again.
+
+        --canary-cheep-msec= may be used to control how often the
+        canary thread shall cheep.
+
+        --canary-watchdog-msec= may be used to control how quickly the
+        watchdog thread expects to receive a cheep from the canary
+        thread. This value must be chosen larger than
+        --canary-cheep-msec=. If the former is set 10s and the latter
+        to 7s, then the canary thread can trigger and deliver the
+        cheep with a maximum latency of 3s.
+
 ACKNOWLEDGMENTS:
-        The watchdog logic is inspired by previous work of Vernon
-        Mauery, Florian Schmidt, Kjetil Matheussen:
+        The canary watchdog logic is inspired by previous work of
+        Vernon Mauery, Florian Schmidt, Kjetil Matheussen:
 
         http://rt.wiki.kernel.org/index.php/RT_Watchdog