From 0f1db42465567a490e84f98c312694b2082fcaa7 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 18 Jun 2009 19:46:58 +0200 Subject: beef up README a bit --- README | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 91 insertions(+), 5 deletions(-) (limited to 'README') 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 -- cgit