EPICSWIKI - User contributions [en]

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:35:44Z

TillStraumann: /* Work-around */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 (<tt>nice(1)</tt> modifies a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see the manpage for <tt>limits.conf(5)</tt>.

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents (it may be necessary for a user to log out
and log back on in order to obtain the new privileges):

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process to enable it to actually make use of the privilege. This step is required because it is usually a bad idea to run ''all'' processes created by a given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence [https://bugs.launchpad.net/epics-base/+bug/835138 (see bug #835138)] that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the [https://bugs.launchpad.net/epics-base/+bug/835138 bugfix] (AFAIK the problem is still present in 3.14.12.1, may be fixed thereafter)
* or make sure the RTPRIO limits are set to the maximally possible value (99)

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:34:54Z

TillStraumann: /* Summary */

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:28:44Z

TillStraumann: /* How can I let epicsThreads use the SCHED_FIFO policy? */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 (<tt>nice(1)</tt> modifies a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see the manpage for <tt>limits.conf(5)</tt>.

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents (it may be necessary for a user to log out
and log back on in order to obtain the new privileges):

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use
SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process
to enable it to actually make use of the privilege. This step is required
because it is usually a bad idea to run ''all'' processes created by a
given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence [https://bugs.launchpad.net/epics-base/+bug/835138 (see bug #835138)] that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the [https://bugs.launchpad.net/epics-base/+bug/835138 bugfix] (AFAIK the problem is still present in 3.14.12.1, may be fixed thereafter)
* or make sure the RTPRIO limit is set to the maximally possible value (99)

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:26:38Z

TillStraumann: /* How can I let epicsThreads use the SCHED_FIFO policy? */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 (<tt>nice(1)</tt> modifies a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see the manpage for <tt>limits.conf(5)</tt>.

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents:

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use
SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process
to enable it to actually make use of the privilege. This step is required
because it is usually a bad idea to run ''all'' processes created by a
given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence [https://bugs.launchpad.net/epics-base/+bug/835138 (see bug #835138)] that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the [https://bugs.launchpad.net/epics-base/+bug/835138 bugfix] (AFAIK the problem is still present in 3.14.12.1, may be fixed thereafter)
* or make sure the RTPRIO limit is set to the maximally possible value (99)

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:25:48Z

TillStraumann: /* How can I let epicsThreads use the SCHED_FIFO policy? */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 (<tt>nice(1)</tt> modifies a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see the manpage for <tt>limits.conf(5)</tt>.

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents:

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

Then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use
SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process
to enable it to actually make use of the privilege. This step is required
because it is usually a bad idea to run ''all'' processes created by a
given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence [https://bugs.launchpad.net/epics-base/+bug/835138 (see bug #835138)] that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the [https://bugs.launchpad.net/epics-base/+bug/835138 bugfix] (AFAIK the problem is still present in 3.14.12.1, may be fixed thereafter)
* or make sure the RTPRIO limit is set to the maximally possible value (99)

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:23:52Z

TillStraumann: /* What is this about? */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 (<tt>nice(1)</tt> modifies a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see man limits.conf(5).

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents:

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

Then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use
SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process
to enable it to actually make use of the privilege. This step is required
because it is usually a bad idea to run ''all'' processes created by a
given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence [https://bugs.launchpad.net/epics-base/+bug/835138 (see bug #835138)] that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the [https://bugs.launchpad.net/epics-base/+bug/835138 bugfix] (AFAIK the problem is still present in 3.14.12.1, may be fixed thereafter)
* or make sure the RTPRIO limit is set to the maximally possible value (99)

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:22:40Z

TillStraumann: /* What is this about? */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 ("nice" modifies a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see man limits.conf(5).

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents:

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

Then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use
SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process
to enable it to actually make use of the privilege. This step is required
because it is usually a bad idea to run ''all'' processes created by a
given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence [https://bugs.launchpad.net/epics-base/+bug/835138 (see bug #835138)] that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the [https://bugs.launchpad.net/epics-base/+bug/835138 bugfix] (AFAIK the problem is still present in 3.14.12.1, may be fixed thereafter)
* or make sure the RTPRIO limit is set to the maximally possible value (99)

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:21:27Z

TillStraumann: /* End of the story? */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 ("nice" affects a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see man limits.conf(5).

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents:

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

Then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use
SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process
to enable it to actually make use of the privilege. This step is required
because it is usually a bad idea to run ''all'' processes created by a
given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence [https://bugs.launchpad.net/epics-base/+bug/835138 (see bug #835138)] that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the [https://bugs.launchpad.net/epics-base/+bug/835138 bugfix] (AFAIK the problem is still present in 3.14.12.1, may be fixed thereafter)
* or make sure the RTPRIO limit is set to the maximally possible value (99)

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:09:41Z

TillStraumann: /* Work-around */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 ("nice" affects a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see man limits.conf(5).

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents:

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

Then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use
SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process
to enable it to actually make use of the privilege. This step is required
because it is usually a bad idea to run ''all'' processes created by a
given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the bugfix
* or make sure the RTPRIO limit is set to the maximally possible value (99)

How To Use Posix Thread Priority Scheduling under Linux

2011-08-31T03:08:47Z

TillStraumann: /* How can I let epicsThreads use the SCHED_FIFO policy? */

== What is this about? ==

The linux scheduler supports the
SCHED_FIFO scheduling policy defined by POSIX.1-2001. Threads scheduled with this "real-time" policy can be assigned a priority (under linux) in the range 1..99 with 99 representing the highest priority. Since ordinary, "non-real time" processes execute at priority 0 ("nice" affects a "dynamic priority" which only affects processes with real-time priority 0 and implements fair timesharing among such processes) SCHED_FIFO threads are always capable to preempt "ordinary processes" (these use the policy SCHED_OTHER).

Note, however, that unless the linux kernel is built with the RT_PREEMPT patch
and measures are taken to lock the EPICS process in memory etc.,
no strictly deterministic latencies can be expected even under the
SCHED_FIFO policy which thus is to be considered ''soft-real time''.

== How can I let epicsThreads use the SCHED_FIFO policy? ==

In order to let EPICS use the SCHED_FIFO real-time policy you first need to check that the following option is set to "YES" in <tt>epics-base/configure/CONFIG_SITE</tt>

<pre><nowiki>
# Use POSIX thread priority scheduling (YES or NO)
USE_POSIX_THREAD_PRIORITY_SCHEDULING = YES
</nowiki></pre>

If you find that the current setting is "NO" then you need to ''rebuild'' EPICS base (<tt>make clean uninstall; make</tt>) after changing to 'YES'.

Since engaging the SCHED_FIFO policy gives any thread created under that policy
a higher priority than any normal process'es using SCHED_FIFO requires special
''privileges''. Under a reasonably recent linux equipped with the
<tt>pam_security</tt> module it is not necessary to execute EPICS as ''root''.
The system administrator can define the maximum priority that may be used
by specific users and/or groups in a file under <tt>/etc/security/limits.d/</tt>, see man limits.conf(5).

E.g., if a file <tt>/etc/security.limits.d/epics.conf</tt> is created with
the following contents:

<pre><nowiki>
someuser hard rtprio 20
someuser soft rtprio 0
</nowiki></pre>

Then processes created by 'someuser' still have priority 0 by default (this is
the 'soft' value) but 'someuser' may increase the resource limit up to 20
either from a running program (using the system call <tt>setrlimit(2)</tt>)
or within a shell e.g., with <tt>bash</tt>'s <tt>ulimit -r</tt> utility.

Note that a user process may set and/or lower its hard limit but ''never increase'' it. RTM.

=== Summary ===
You need to do three things:
* Build EPICS base with <tt>USE_POSIX_THREAD_PRIORITY_SCHEDULING=YES</tt>
* Make sure your EPICS application process has sufficient privileges to use
SCHED_FIFO and the desired priority range.
* Set the soft and hard RTPRIO limits for your EPICS application process
to enable it to actually make use of the privilege. This step is required
because it is usually a bad idea to run ''all'' processes created by a
given user or group at real-time priorities.

== End of the story? ==
Unfortunately, this is not the end of the story. Linux' <tt>sched_get_priority_max(2)</tt> system call which is used
by EPICS to map EPICS priorities from/to linux/pthread priorities
always reports the maximal supported priority (99) without
considering any limits that the system enforces (as discussed above).
This has the consequence that threads which are created with
a desired priority that is greater than the resource limit
eventually end up with the ''lowest'' priority 0.

=== Work-around ===
* Either apply the bugfix
* or make sure the RTPRIO limit is set to the maximally possible value

How To Use Posix Thread Priority Scheduling under Linux

2011-08-30T20:44:56Z

TillStraumann:

HowTo Documents

2011-08-30T17:12:00Z

TillStraumann:

This is a directory of various How-To documents written by members of the EPICS collaboration. Contributions to this page are most welcome!

=== EPICS Base on Different Architectures and Operating Systems ===

* [http://www.aps.anl.gov/epics/base/RTEMS/tutorial/ Getting Started with EPICS on RTEMS]
* [[HowToPC104|Getting Started with R3.14.7 on a PC104 running Linux]]
* [[How To Port EPICS to a new OS/Architecture]]
* [[How To Use Posix Thread Priority Scheduling under Linux]]

=== Drivers and Device Support ===

* [http://www.aps.anl.gov/epics/modules/soft/asyn/HowToDoSerial_StreamDevice.html How To Do Serial (using Asyn Driver and StreamDevice)]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-15/HowToDoSerial/tutorial.pdf How To Do Serial (using Asyn Driver and devGPIB)]
* [http://www.aps.anl.gov/epics/modules/soft/asyn/BeginnerGuideToASYN-VXI11.pdf Beginners Guide to using VXI-11 (with Asyn Driver)]
* [[How to make your EPICS driver operating system independent]]
* [[How To Write Device Support that uses Asyn Driver]] ''(Incomplete!)''
* [[How to use GPIB ports with linux-gpib and StreamDevice]]

=== Applications ===

* [[Common Database patterns]]
* [[How To Install Channel Archiver On Scientific Linux]]
* [[What PV Save and Restore Tools are available]]
* [[How to Add a New Breakpoint Table]]
* [["Best Practice" Guidelines]]

=== Infrastructure and Other Stuff ===

* [[How To Set Up a Linux Box as an IOC Boot Server]]
* [[How To Set Up a Mirror of the EPICS Web Site]]
* [[How to Set Up a Soft IOC Framework on Linux]]
* [[How to Set Up Console Access and Logging for VME and Soft IOCs]]
* [[How to Set Up NAL (Nagios Alarm Handler) to monitor an EPICS network]]

=== Collaboration Stuff ===

* [[How to run an EPICS Collaboration Meeting]]