Skip to contentSkip to conversation

docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT

PATCH Superseded Liang Hao 4 participants 12 messages Aug 7 – Aug 31

Subsystems (3)
lore
Share & tools
lore

Liang Hao

author
#0 lore raw

PATCH 1/1 docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT

Documentation/timers/hrtimers.rst described the high-resolution timer subsystem but did not cover the PREEMPT_RT expiry-mode semantics. On a PREEMPT_RT kernel a timer that is not explicitly marked HRTIMER_MODE_HARD is forced into softirq expiry and its callback runs on the per-CPU ktimers/%u thread at SCHED_FIFO priority 1, regardless of the priority of the task that armed it -- a SCHED_FIFO task's priority does not extend into its timer callback. This is a recurring source of hard-to-diagnose latency for RT/DL authors who assume the opposite.

Add a dedicated "Expiry modes and PREEMPT_RT" section that documents:

- the distinction between HRTIMER_MODE_HARD and HRTIMER_MODE_SOFT;
- the fact that unmarked timers are forced into softirq expiry on PREEMPT_RT (__hrtimer_setup());
- the role of the per-CPU ktimers/%u thread and its fixed SCHED_FIFO priority 1 (sched_set_fifo_low());
- the absence of priority inheritance between the arming task and the timer callback on RT;
- the sleeper exception, where hrtimer_setup_sleeper() automatically marks RT/DL-armed timers HRTIMER_MODE_HARD (__hrtimer_setup_sleeper());
- the critical distinction between the *requested* expiry mode (passed by the caller) and the *effective* execution context (chosen by the kernel and stored in timer->is_soft).

The hrtimer_start tracepoint logs the *requested* mode, not the effective one. On PREEMPT_RT a timer armed with the default mode (e.g. ABS or REL without HARD/SOFT flags) is implicitly forced into softirq expiry, so the effective soft nature must be inferred from the *absence* of explicit mode flags in the trace rather than read directly.

Documentation only; no code or behaviour change.

---
 Documentation/timers/hrtimers.rst | 66 +++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
Documentation/timers/hrtimers.rst +66 -0
index f88ff8bae89c..ff42377668c1 100644
@@ -171,3 +171,69 @@ hrtimers-based high-resolution clock implementation, so the hrtimers
 code got a healthy amount of testing and use in practice.
 
 	Thomas Gleixner, Ingo Molnar
+
+
+Expiry modes and PREEMPT_RT
+---------------------------
+
+Each hrtimer carries an expiry mode that determines the execution context
+of its callback:
+
+  * ``HRTIMER_MODE_HARD`` -- the callback runs in hard interrupt context.
+    It must be hardirq-safe (no sleeping locks, no allocations, no
+    scheduling).
+  * ``HRTIMER_MODE_SOFT`` -- the callback runs in softirq context and may
+    use operations that are not hardirq-safe.
+  * Default (neither flag) -- the mode is selected by the subsystem or
+    the kernel configuration.
+
+On ``CONFIG_PREEMPT_RT`` the choice is not optional for most timers:
+any timer not explicitly marked ``HRTIMER_MODE_HARD`` is forced into
+softirq expiry (see ``__hrtimer_setup()``). Instead of executing in
+hardirq context or within the context of the task that armed it, the
+callback runs on the per-CPU ``ktimers/%u`` thread.
+
+The ``ktimersd`` thread operates at ``SCHED_FIFO`` priority 1 (established
+via ``sched_set_fifo_low()``). This priority is fixed and **does not
+inherit the priority of the task that armed the timer**. The effective
+execution context is determined internally by the hrtimer subsystem at
+setup time and is reflected in ``timer->is_soft``; it is not directly
+visible as a mode flag at arming time.
+
+Consequently, even if a timer is armed by a ``SCHED_FIFO`` task with
+priority 99, its callback will execute only when the ``ktimersd`` thread
+(priority 1) is selected to run.
+
+This design ensures that timer processing does not interfere with
+higher-priority real-time workloads, while still providing bounded
+latency relative to ``SCHED_OTHER`` tasks. However, it also means that
+latency-sensitive processing must not rely on implicit priority
+inheritance through the timer arming path.
+
+A notable exception is the sleeper path: a timer set up via
+``hrtimer_setup_sleeper()`` (used by ``clock_nanosleep()`` and similar)
+that is armed by an RT or DEADLINE task is automatically marked
+``HRTIMER_MODE_HARD``, so its wakeup runs in hardirq context and does
+not go through ``ktimersd`` (see ``__hrtimer_setup_sleeper()``).
+
+**Guidelines for RT authors:**
+
+- If the timer callback contains logic that must execute at the priority
+  of the owning RT task, the timer must be declared as
+  ``HRTIMER_MODE_HARD``. Ensure the callback adheres to hardirq context
+  constraints.
+- Alternatively, move the latency-sensitive logic out of the timer
+  callback and into a dedicated, properly prioritized kthread which is
+  woken by the timer.
+
+**Debugging context:** The ``hrtimer_start`` tracepoint logs the
+*requested* expiry mode passed by the caller (e.g. ``ABS``, ``REL``,
+``ABS|HARD``), not the effective mode chosen by the kernel. On
+PREEMPT_RT, any timer armed with the default mode (i.e. the trace shows
+``ABS`` or ``REL`` without ``|SOFT`` or ``|HARD``) is implicitly forced
+into softirq expiry. When such a timer is armed by an RT or DEADLINE
+task, the consequence -- the callback running at ``ktimersd`` priority
+rather than the arming task's -- is the case to watch. The effective
+soft nature of such timers is inferred from the *absence* of an explicit
+mode flag in the trace, combined with the ``CONFIG_PREEMPT_RT``
+configuration.
Signature · 1 line
2.50.1 (Apple Git-155)
author
#1 lore raw

PATCH v2 1/1 docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT

Documentation/timers/hrtimers.rst did not cover the PREEMPT_RT expiry-mode semantics. On a PREEMPT_RT kernel a timer that is not explicitly marked HRTIMER_MODE_HARD is forced into softirq expiry and its callback runs on the per-CPU ktimers/%u thread at the lowest SCHED_FIFO priority (sched_set_fifo_low), regardless of the priority of the task that armed it -- a SCHED_FIFO task running at priority 99 that starts an unmarked timer still expires on ktimers/%u (lowest SCHED_FIFO priority), not at priority 99.

Add an "Expiry modes and PREEMPT_RT" section that, rather than duplicating the default-context description in Documentation/core-api/real-time/differences.rst (Timers), cross-references it and focuses on what that document does not spell out:

- the callback does not inherit the arming task's priority, and priority inheritance on PREEMPT_RT is used for the cancel handshake, not the arming path (the "Spin until ready" section of the same document);
- the sleeper exception: hrtimer_setup_sleeper() marks RT/DL-armed timers HRTIMER_MODE_HARD, so their wakeups do not go through ktimers/%u.

Documentation only; no code or behaviour change.

---
v1 -> v2:
- shorten the RT overview; link to real-time/differences
- state the arming-path priority consequence (priority not inherited; PI is for the cancel handshake)
- drop the hrtimer_start trace debugging section
- use the ktimers/%u thread name, with ktimersd as its doc alias

 Documentation/timers/hrtimers.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
Documentation/timers/hrtimers.rst +28 -0
index f88ff8bae89c..fae191550c5d 100644
@@ -171,3 +171,31 @@ hrtimers-based high-resolution clock implementation, so the hrtimers
 code got a healthy amount of testing and use in practice.
 
 	Thomas Gleixner, Ingo Molnar
+
+
+Expiry modes and PREEMPT_RT
+---------------------------
+
+The default expiry context on PREEMPT_RT and the role of the ktimersd
+thread are documented in :doc:`/core-api/real-time/differences`
+(Timers).  Those details are not repeated here.
+
+The per-CPU ``ktimers/%u`` thread (referred to as ktimersd in that
+document) runs at the lowest ``SCHED_FIFO`` priority via
+``sched_set_fifo_low()``.  That priority is fixed: the callback does
+not inherit the priority of the task that armed the timer.  A
+``SCHED_FIFO`` task running at priority 99 that starts an unmarked
+timer still expires on ``ktimers/%u`` (lowest ``SCHED_FIFO`` priority),
+not at priority 99.
+Priority inheritance on PREEMPT_RT is used for the cancel handshake,
+not for the arming path; see the "Spin until ready" section of the same
+document.
+
+``hrtimer_setup_sleeper()`` (used by ``clock_nanosleep()`` and similar)
+is an exception: when armed by an RT or DEADLINE task it is marked
+``HRTIMER_MODE_HARD``, so the wakeup runs in hardirq context and does
+not go through ``ktimers/%u``.
+
+If callback work must run at the owning task's RT priority, either
+mark the timer ``HRTIMER_MODE_HARD`` (and keep the callback
+hardirq-safe) or wake a dedicated kthread from the callback.
Signature · 1 line
2.50.1 (Apple Git-155)
#2 lore raw
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [Low] Reference to non-existent API `hrtimer_setup_sleeper()` in documentation. --

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Reference to non-existent API hrtimer_setup_sleeper() in documentation. --

--- Patch [1]: [PATCH v2] docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT --- commit 2dc8d2cd0774356027c94f2b3b606b15bca92ef3
Author: Liang Hao <[email protected]>

docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT

This commit documents the PREEMPT_RT expiry-mode semantics for timers not explicitly marked HRTIMER_MODE_HARD, explaining how they default to softirq expiry on the ktimers thread. It also clarifies priority inheritance rules and sleeper exceptions for RT/DL-armed timers.

Quoted 3 lines
Documentation/timers/hrtimers.rst +0 -0

[ ... ]

Documentation/timers/hrtimers.rst hrtimers-based high-resolution clock implementation, so the hrtimers · line 194

Quoted 5 lines
Documentation/timers/hrtimers.rst +5 -0
+Priority inheritance on PREEMPT_RT is used for the cancel handshake,
+not for the arming path; see the "Spin until ready" section of the same
+document.
+
+``hrtimer_setup_sleeper()`` (used by ``clock_nanosleep()`` and similar)

[Severity: Low]
This isn't a bug, but should this refer to hrtimer_setup_sleeper_on_stack() instead? The hrtimer_setup_sleeper() API does not appear to exist in the source tree, as the exported API for this functionality is hrtimer_setup_sleeper_on_stack(), which internally calls __hrtimer_setup_sleeper().

Quoted 7 lines
Documentation/timers/hrtimers.rst +7 -0
+is an exception: when armed by an RT or DEADLINE task it is marked
+``HRTIMER_MODE_HARD``, so the wakeup runs in hardirq context and does
+not go through ``ktimers/%u``.
+
+If callback work must run at the owning task's RT priority, either
+mark the timer ``HRTIMER_MODE_HARD`` (and keep the callback
+hardirq-safe) or wake a dedicated kthread from the callback.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
author
#3 lore raw

PATCH v3 1/1 docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT

In reply to Liang Hao

Documentation/timers/hrtimers.rst did not cover the PREEMPT_RT expiry-mode semantics. On a PREEMPT_RT kernel a timer that is not explicitly marked HRTIMER_MODE_HARD is forced into softirq expiry and its callback runs on the per-CPU ktimers/%u thread at the lowest SCHED_FIFO priority (sched_set_fifo_low), regardless of the priority of the task that armed it -- a SCHED_FIFO task running at priority 99 that starts an unmarked timer still expires on ktimers/%u (lowest SCHED_FIFO priority), not at priority 99.

Add an "Expiry modes and PREEMPT_RT" section that, rather than duplicating the default-context description in Documentation/core-api/real-time/differences.rst (Timers), cross-references it and focuses on what that document does not spell out:

- the callback does not inherit the arming task's priority, and priority inheritance on PREEMPT_RT is used for the cancel handshake, not the arming path (the "Spin until ready" section of the same document);
- the sleeper exception: hrtimer_setup_sleeper_on_stack() marks RT/DL-armed timers HRTIMER_MODE_HARD, so their wakeups do not go through ktimers/%u.

Documentation only; no code or behaviour change.

---
v2 -> v3:
- use hrtimer_setup_sleeper_on_stack(); there is no hrtimer_setup_sleeper()

 Documentation/timers/hrtimers.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
Documentation/timers/hrtimers.rst +28 -0
index f88ff8bae89c..b81785e0310e 100644
@@ -171,3 +171,31 @@ hrtimers-based high-resolution clock implementation, so the hrtimers
 code got a healthy amount of testing and use in practice.
 
 	Thomas Gleixner, Ingo Molnar
+
+
+Expiry modes and PREEMPT_RT
+---------------------------
+
+The default expiry context on PREEMPT_RT and the role of the ktimersd
+thread are documented in :doc:`/core-api/real-time/differences`
+(Timers).  Those details are not repeated here.
+
+The per-CPU ``ktimers/%u`` thread (referred to as ktimersd in that
+document) runs at the lowest ``SCHED_FIFO`` priority via
+``sched_set_fifo_low()``.  That priority is fixed: the callback does
+not inherit the priority of the task that armed the timer.  A
+``SCHED_FIFO`` task running at priority 99 that starts an unmarked
+timer still expires on ``ktimers/%u`` (lowest ``SCHED_FIFO`` priority),
+not at priority 99.
+Priority inheritance on PREEMPT_RT is used for the cancel handshake,
+not for the arming path; see the "Spin until ready" section of the same
+document.
+
+``hrtimer_setup_sleeper_on_stack()`` (used by ``clock_nanosleep()`` and similar)
+is an exception: when armed by an RT or DEADLINE task it is marked
+``HRTIMER_MODE_HARD``, so the wakeup runs in hardirq context and does
+not go through ``ktimers/%u``.
+
+If callback work must run at the owning task's RT priority, either
+mark the timer ``HRTIMER_MODE_HARD`` (and keep the callback
+hardirq-safe) or wake a dedicated kthread from the callback.
Signature · 1 line
2.50.1 (Apple Git-155)
#4 lore raw
Quoted 4 lines · Liang Hao
Documentation/timers/hrtimers.rst +0 -0
@@ -171,3 +171,31 @@ hrtimers-based high-resolution clock implementation, so the hrtimers
 code got a healthy amount of testing and use in practice.

Documentation/timers/hrtimers.rst hrtimers-based high-resolution clock implementation, so the hrtimers · line 181

Quoted 10 lines
Documentation/timers/hrtimers.rst +8 -0
 
 	Thomas Gleixner, Ingo Molnar
+
+
+Expiry modes and PREEMPT_RT
+---------------------------
+
+The default expiry context on PREEMPT_RT and the role of the ktimersd
+thread are documented in :doc:`/core-api/real-time/differences`
+(Timers).  Those details are not repeated here.

Interesting to say.

Documentation/timers/hrtimers.rst hrtimers-based high-resolution clock implementation, so the hrtimers · line 183

Quoted 1 line
Documentation/timers/hrtimers.rst +1 -0
+The per-CPU ``ktimers/%u`` thread (referred to as ktimersd in that

Maybe the other document could be updated so it ktimers everywhere.

Documentation/timers/hrtimers.rst hrtimers-based high-resolution clock implementation, so the hrtimers · line 189

Quoted 6 lines
Documentation/timers/hrtimers.rst +6 -0
+document) runs at the lowest ``SCHED_FIFO`` priority via
+``sched_set_fifo_low()``.  That priority is fixed: the callback does
+not inherit the priority of the task that armed the timer.  A
+``SCHED_FIFO`` task running at priority 99 that starts an unmarked
+timer still expires on ``ktimers/%u`` (lowest ``SCHED_FIFO`` priority),
+not at priority 99.

Right. Why would one expect that to happen?

Documentation/timers/hrtimers.rst hrtimers-based high-resolution clock implementation, so the hrtimers · line 194

Quoted 5 lines
Documentation/timers/hrtimers.rst +5 -0
+Priority inheritance on PREEMPT_RT is used for the cancel handshake,
+not for the arming path; see the "Spin until ready" section of the same
+document.
+
+``hrtimer_setup_sleeper_on_stack()`` (used by ``clock_nanosleep()`` and similar)

I wouldn't say similar because what is similar? Does the timeout passed to select() count as similar? Any of the POSIX timers?

Documentation/timers/hrtimers.rst hrtimers-based high-resolution clock implementation, so the hrtimers · line 201

Quoted 7 lines
Documentation/timers/hrtimers.rst +7 -0
+is an exception: when armed by an RT or DEADLINE task it is marked
+``HRTIMER_MODE_HARD``, so the wakeup runs in hardirq context and does
+not go through ``ktimers/%u``.
+
+If callback work must run at the owning task's RT priority, either
+mark the timer ``HRTIMER_MODE_HARD`` (and keep the callback
+hardirq-safe) or wake a dedicated kthread from the callback.

I don't think this belongs here. Anything that general hrtimer related could be added here. The flags parameters such as HRTIMER_MODE_REL, HRTIMER_MODE_HARD, HRTIMER_MODE_SOFT are only documented in their kernel-doc of the hrtimer_mode.

This document does not cover where or in which context the timer expires. This is also true for timer_list timers. Those are not affected by this and expire always via ktimers/.

I would suggest that you extend the existing document that you refer to instead adding RT bits here and refer to the other document. If there is a need to mention the default context, hrtimer_mode would be the place.

Quoted 2 lines
Signature · 1 line
2.50.1 (Apple Git-155)

Sebastian

author
#5 lore raw

PATCH v4 1/1 docs: real-time: mention the hrtimer sleeper HARD path

The Timers section of Documentation/core-api/real-time/differences.rst describes the PREEMPT_RT default (softirq / ktimers) and HRTIMER_MODE_HARD, but not the sleeper helper: hrtimer_setup_sleeper_on_stack() marks the timer HRTIMER_MODE_HARD when the current task is RT or DEADLINE and HRTIMER_MODE_SOFT was not requested, so the wakeup runs in hard interrupt context.

Document that behaviour. Also rename "ktimersd" to "ktimers/%u" to match the per-CPU thread name.

No code or behaviour change.

---
v3 -> v4:
- drop the Documentation/timers/hrtimers.rst section; extend differences.rst instead, per review
- add only the sleeper HARD wording and the ktimers/%u rename
- do not restate lowest-priority / cancel-PI points already covered elsewhere
- avoid vague "and similar" caller lists

 Documentation/core-api/real-time/differences.rst | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)
Documentation/core-api/real-time/differences.rst +8 -3
index a129570dab5a..c8acfba051eb 100644
@@ -119,12 +119,17 @@ timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in
 softirq context.
 
 On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in
-softirq context by default, typically within the ktimersd thread. This thread
-runs at the lowest real-time priority, ensuring it executes before any
-SCHED_OTHER tasks but does not interfere with higher-priority real-time
+softirq context by default, typically within the per-CPU ktimers/%u thread.
+This thread runs at the lowest real-time priority, ensuring it executes before
+any SCHED_OTHER tasks but does not interfere with higher-priority real-time
 threads. To explicitly request execution in hard interrupt context on
 PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag.
 
+hrtimer_setup_sleeper_on_stack() marks the sleeper HRTIMER_MODE_HARD when the
+current task is in a real-time or deadline scheduling class and
+HRTIMER_MODE_SOFT was not requested, so the wakeup runs in hard interrupt
+context rather than on ktimers/%u.
+
 Memory allocation
 -----------------
 
Signature · 1 line
2.50.1 (Apple Git-155)
#6 lore raw

Re: [PATCH v4] docs: real-time: mention the hrtimer sleeper HARD path

Quoted 29 lines · Liang Hao

The Timers section of Documentation/core-api/real-time/differences.rst describes the PREEMPT_RT default (softirq / ktimers) and HRTIMER_MODE_HARD, but not the sleeper helper: hrtimer_setup_sleeper_on_stack() marks the timer HRTIMER_MODE_HARD when the current task is RT or DEADLINE and HRTIMER_MODE_SOFT was not requested, so the wakeup runs in hard interrupt context.

Document that behaviour. Also rename "ktimersd" to "ktimers/%u" to match the per-CPU thread name.

No code or behaviour change.

---
v3 -> v4:
- drop the Documentation/timers/hrtimers.rst section; extend differences.rst instead, per review
- add only the sleeper HARD wording and the ktimers/%u rename
- do not restate lowest-priority / cancel-PI points already covered elsewhere
- avoid vague "and similar" caller lists

 Documentation/core-api/real-time/differences.rst | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)
Documentation/core-api/real-time/differences.rst +0 -0
index a129570dab5a..c8acfba051eb 100644

Documentation/core-api/real-time/differences.rst timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in · line 122

Quoted 7 lines
Documentation/core-api/real-time/differences.rst +1 -3
@@ -119,12 +119,17 @@ timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in
 softirq context.
 
 On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in
-softirq context by default, typically within the ktimersd thread. This thread
-runs at the lowest real-time priority, ensuring it executes before any
-SCHED_OTHER tasks but does not interfere with higher-priority real-time
+softirq context by default, typically within the per-CPU ktimers/%u thread.

Please do ktimers instead ktimers/%u. I don't see any other reference to a per-CPU thread like that. This would also be in sync with ksoftirqd.

Documentation/core-api/real-time/differences.rst timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in · line 132

Quoted 10 lines
Documentation/core-api/real-time/differences.rst +7 -0
+This thread runs at the lowest real-time priority, ensuring it executes before
+any SCHED_OTHER tasks but does not interfere with higher-priority real-time
 threads. To explicitly request execution in hard interrupt context on
 PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag.
 
+hrtimer_setup_sleeper_on_stack() marks the sleeper HRTIMER_MODE_HARD when the
+current task is in a real-time or deadline scheduling class and
+HRTIMER_MODE_SOFT was not requested, so the wakeup runs in hard interrupt
+context rather than on ktimers/%u.
+

What about

Userland sleeper deploy usually a hrtimer to guarantee a precise wakeup time. The timer is initialized with hrtimer_setup_sleeper_on_stack() which distinguishes between real-time and regular tasks. The hrtimer of a task without a real-time priority is initialized with HRTIMER_MODE_SOFT but for real-time priorities HRTIMER_MODE_HARD is used. This ensures that real-time tasks are woken up as soon as possible while ordinary tasks can not block the CPU with a thundering herd of wake ups.

Documentation/core-api/real-time/differences.rst timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in · line 135

Quoted 3 lines
Documentation/core-api/real-time/differences.rst +0 -0
 Memory allocation
 -----------------
 

Sebastian

author
#7 lore raw

PATCH v5 1/1 docs: real-time: mention the hrtimer sleeper HARD path

The Timers section documents the PREEMPT_RT softirq default and HRTIMER_MODE_HARD, but not the sleeper helper used by userspace sleeps. Describe that path, and rename "ktimersd" to "ktimers" to match ksoftirqd naming in this document.

No code or behaviour change.

---
Thanks!

v4 -> v5:
- use "ktimers" instead of "ktimers/%u"
- replace the sleeper paragraph with wording suggested by Sebastian

 Documentation/core-api/real-time/differences.rst | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)
Documentation/core-api/real-time/differences.rst +9 -1
index a129570dab5a..04be5789b5fc 100644
@@ -119,12 +119,20 @@ timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in
 softirq context.
 
 On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in
-softirq context by default, typically within the ktimersd thread. This thread
+softirq context by default, typically within the ktimers thread. This thread
 runs at the lowest real-time priority, ensuring it executes before any
 SCHED_OTHER tasks but does not interfere with higher-priority real-time
 threads. To explicitly request execution in hard interrupt context on
 PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag.
 
+Userland sleepers usually deploy a hrtimer to guarantee a precise wakeup
+time. The timer is initialized with hrtimer_setup_sleeper_on_stack(), which
+distinguishes between real-time and regular tasks. The hrtimer of a task
+without a real-time priority is initialized with HRTIMER_MODE_SOFT, but for
+real-time priorities HRTIMER_MODE_HARD is used. This ensures that real-time
+tasks are woken up as soon as possible while ordinary tasks cannot block the
+CPU with a thundering herd of wakeups.
+
 Memory allocation
 -----------------
 
Signature · 1 line
2.50.1 (Apple Git-155)
#8 lore raw

Re: [PATCH v5] docs: real-time: mention the hrtimer sleeper HARD path

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [Low] Documentation inaccurately claims non-real-time hrtimers are initialized with the HRTIMER_MODE_SOFT…

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Documentation inaccurately claims non-real-time hrtimers are initialized with the HRTIMER_MODE_SOFT flag. --

--- Patch [1]: [PATCH v5] docs: real-time: mention the hrtimer sleeper HARD path --- commit 9bd51b2daf474d1c00caf4e2ad8da8892d995928
Author: Liang Hao <[email protected]>
docs: real-time: mention the hrtimer sleeper HARD path

This commit updates the real-time differences documentation to describe the hrtimer sleeper path used by userspace sleeps. It also renames "ktimersd" to "ktimers" to match the ksoftirqd naming convention.

Quoted 4 lines
Documentation/core-api/real-time/differences.rst +0 -0
index a129570dab5a3..04be5789b5fcc 100644

[ ... ]

Quoted 5 lines
Documentation/core-api/real-time/differences.rst +0 -1
@@ -119,12 +119,20 @@ timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in
 softirq context.
 
 On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in
-softirq context by default, typically within the ktimersd thread. This thread

Documentation/core-api/real-time/differences.rst timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in · line 131

Quoted 10 lines
Documentation/core-api/real-time/differences.rst +5 -0
+softirq context by default, typically within the ktimers thread. This thread
 runs at the lowest real-time priority, ensuring it executes before any
 SCHED_OTHER tasks but does not interfere with higher-priority real-time
 threads. To explicitly request execution in hard interrupt context on
 PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag.
 
+Userland sleepers usually deploy a hrtimer to guarantee a precise wakeup
+time. The timer is initialized with hrtimer_setup_sleeper_on_stack(), which
+distinguishes between real-time and regular tasks. The hrtimer of a task
+without a real-time priority is initialized with HRTIMER_MODE_SOFT, but for

[Severity: Low]
Is this description completely accurate regarding how the mode is set?

Looking at the implementation of __hrtimer_setup_sleeper(), it appears to rely on the PREEMPT_RT core __hrtimer_setup() behavior to default to soft interrupt mode when the HRTIMER_MODE_HARD flag is omitted, rather than explicitly applying the HRTIMER_MODE_SOFT flag itself.

Could we reword this to clarify that it defaults to the soft interrupt mode rather than explicitly passing the HRTIMER_MODE_SOFT flag?

Quoted 6 lines
Documentation/core-api/real-time/differences.rst +4 -0
+real-time priorities HRTIMER_MODE_HARD is used. This ensures that real-time
+tasks are woken up as soon as possible while ordinary tasks cannot block the
+CPU with a thundering herd of wakeups.
+
 Memory allocation
 -----------------
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
author
#9 lore raw

PATCH v6 1/1 docs: real-time: mention the hrtimer sleeper HARD path

In reply to Liang Hao

The Timers section documents the PREEMPT_RT softirq default and HRTIMER_MODE_HARD, but not the sleeper helper used by userspace sleeps. Describe that path, and rename "ktimersd" to "ktimers" to match ksoftirqd naming in this document.

No code or behaviour change.

---
v5 -> v6:
- clarify soft delivery for non-RT sleepers (softirq context, not HRTIMER_MODE_SOFT)

 Documentation/core-api/real-time/differences.rst | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)
Documentation/core-api/real-time/differences.rst +9 -1
index a129570dab5a..6f5be9f0da2e 100644
@@ -119,12 +119,20 @@ timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in
 softirq context.
 
 On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in
-softirq context by default, typically within the ktimersd thread. This thread
+softirq context by default, typically within the ktimers thread. This thread
 runs at the lowest real-time priority, ensuring it executes before any
 SCHED_OTHER tasks but does not interfere with higher-priority real-time
 threads. To explicitly request execution in hard interrupt context on
 PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag.
 
+Userland sleepers usually deploy a hrtimer to guarantee a precise wakeup
+time. The timer is initialized with hrtimer_setup_sleeper_on_stack(), which
+distinguishes between real-time and regular tasks. The hrtimer of a task
+without a real-time priority is handled in soft interrupt context, but for
+real-time priorities HRTIMER_MODE_HARD is used. This ensures that real-time
+tasks are woken up as soon as possible while ordinary tasks cannot block the
+CPU with a thundering herd of wakeups.
+
 Memory allocation
 -----------------
 
Signature · 1 line
2.50.1 (Apple Git-155)
maintainer Reviewed-by on v6 1/1
#10 lore raw

Re: [PATCH v6] docs: real-time: mention the hrtimer sleeper HARD path

Quoted 8 lines · Liang Hao

The Timers section documents the PREEMPT_RT softirq default and HRTIMER_MODE_HARD, but not the sleeper helper used by userspace sleeps. Describe that path, and rename "ktimersd" to "ktimers" to match ksoftirqd naming in this document.

No code or behaviour change.

Sebastian

maintainer Applied
#11 lore raw

Re: [PATCH v6] docs: real-time: mention the hrtimer sleeper HARD path

In reply to Liang Hao
Quoted 31 lines · Liang Hao

The Timers section documents the PREEMPT_RT softirq default and HRTIMER_MODE_HARD, but not the sleeper helper used by userspace sleeps. Describe that path, and rename "ktimersd" to "ktimers" to match ksoftirqd naming in this document.

No code or behaviour change.

---
v5 -> v6:
- clarify soft delivery for non-RT sleepers (softirq context, not HRTIMER_MODE_SOFT)

 Documentation/core-api/real-time/differences.rst | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)
Documentation/core-api/real-time/differences.rst +1 -1
index a129570dab5a..6f5be9f0da2e 100644
@@ -119,12 +119,20 @@ timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in
 softirq context.
 
 On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in
-softirq context by default, typically within the ktimersd thread. This thread
+softirq context by default, typically within the ktimers thread. This thread
 runs at the lowest real-time priority, ensuring it executes before any
 SCHED_OTHER tasks but does not interfere with higher-priority real-time
 threads. To explicitly request execution in hard interrupt context on
 PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag.
 

Documentation/core-api/real-time/differences.rst timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in · line 137

Quoted 10 lines
Documentation/core-api/real-time/differences.rst +8 -0
+Userland sleepers usually deploy a hrtimer to guarantee a precise wakeup
+time. The timer is initialized with hrtimer_setup_sleeper_on_stack(), which
+distinguishes between real-time and regular tasks. The hrtimer of a task
+without a real-time priority is handled in soft interrupt context, but for
+real-time priorities HRTIMER_MODE_HARD is used. This ensures that real-time
+tasks are woken up as soon as possible while ordinary tasks cannot block the
+CPU with a thundering herd of wakeups.
+
 Memory allocation
 -----------------

Applied, thanks.

jon