docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT
Subsystems (3)
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
@@ -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)
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
@@ -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)
[email protected]
AI reviewThank 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
PATCH v3 1/1 docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT
In reply to Liang HaoDocumentation/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
@@ -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)
Sebastian Andrzej Siewior
maintainerQuoted 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
-0Thomas 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
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
@@ -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)
Sebastian Andrzej Siewior
maintainerRe: [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.rstdescribes thePREEMPT_RTdefault (softirq / ktimers) andHRTIMER_MODE_HARD, but not the sleeper helper:hrtimer_setup_sleeper_on_stack()marks the timerHRTIMER_MODE_HARDwhen the current task is RT or DEADLINE andHRTIMER_MODE_SOFTwas 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.
Signed-off-by Liang Hao <[email protected]>---
v3 -> v4:
- drop theDocumentation/timers/hrtimers.rstsection; extenddifferences.rstinstead, 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 listsDocumentation/core-api/real-time/differences.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-)Documentation/core-api/real-time/differences.rst +0
-0
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
-0Memory allocation -----------------
Sebastian
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
@@ -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)
[email protected]
AI reviewRe: [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
[ ... ]
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
PATCH v6 1/1 docs: real-time: mention the hrtimer sleeper HARD path
In reply to Liang HaoThe 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
@@ -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)
Re: [PATCH v6] docs: real-time: mention the hrtimer sleeper HARD path
Quoted 8 lines · Liang Hao
The Timers section documents the
PREEMPT_RTsoftirq default andHRTIMER_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.
Signed-off-by Liang Hao <[email protected]>
Sebastian
Re: [PATCH v6] docs: real-time: mention the hrtimer sleeper HARD path
In reply to Liang HaoQuoted 31 lines · Liang Hao
The Timers section documents the
PREEMPT_RTsoftirq default andHRTIMER_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.
Signed-off-by Liang Hao <[email protected]>---
v5 -> v6:
- clarify soft delivery for non-RT sleepers (softirq context, notHRTIMER_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@@ -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