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.

Signed-off-by: Liang Hao <haohlliang@gmail.com>
---
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(+)

diff --git a/Documentation/timers/hrtimers.rst b/Documentation/timers/hrtimers.rst
index f88ff8bae89c..fae191550c5d 100644
--- a/Documentation/timers/hrtimers.rst
+++ b/Documentation/timers/hrtimers.rst
@@ -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.
-- 
2.50.1 (Apple Git-155)

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 <haohlliang@gmail.com>

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.

> diff --git a/Documentation/timers/hrtimers.rst b/Documentation/timers/hrtimers.rst
> --- a/Documentation/timers/hrtimers.rst
> +++ b/Documentation/timers/hrtimers.rst

[ ... ]

> +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().

> +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.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260812145440.23528-1-haohlliang@gmail.com?part=1

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.

Signed-off-by: Liang Hao <haohlliang@gmail.com>
---
v2 -> v3:
- use hrtimer_setup_sleeper_on_stack(); there is no hrtimer_setup_sleeper()

 Documentation/timers/hrtimers.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/Documentation/timers/hrtimers.rst b/Documentation/timers/hrtimers.rst
index f88ff8bae89c..b81785e0310e 100644
--- a/Documentation/timers/hrtimers.rst
+++ b/Documentation/timers/hrtimers.rst
@@ -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.
-- 
2.50.1 (Apple Git-155)

On 2026-08-13 22:57:46 [+0800], Liang Hao wrote:
> --- a/Documentation/timers/hrtimers.rst
> +++ b/Documentation/timers/hrtimers.rst
> @@ -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.

Interesting to say.

> +The per-CPU ``ktimers/%u`` thread (referred to as ktimersd in that

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

> +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?

> +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?

> +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.

> -- 
> 2.50.1 (Apple Git-155)

Sebastian

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.

Signed-off-by: Liang Hao <haohlliang@gmail.com>
---
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(-)

diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst
index a129570dab5a..c8acfba051eb 100644
--- a/Documentation/core-api/real-time/differences.rst
+++ b/Documentation/core-api/real-time/differences.rst
@@ -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
 -----------------
 
-- 
2.50.1 (Apple Git-155)

On 2026-08-15 00:12:40 [+0800], Liang Hao wrote:
> 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.
> 
> Signed-off-by: Liang Hao <haohlliang@gmail.com>
> ---
> 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(-)
> 
> diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst
> index a129570dab5a..c8acfba051eb 100644
> --- a/Documentation/core-api/real-time/differences.rst
> +++ b/Documentation/core-api/real-time/differences.rst
> @@ -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.

> +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.

>  Memory allocation
>  -----------------
>  

Sebastian

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.

Signed-off-by: Liang Hao <haohlliang@gmail.com>
---
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(-)

diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst
index a129570dab5a..04be5789b5fc 100644
--- a/Documentation/core-api/real-time/differences.rst
+++ b/Documentation/core-api/real-time/differences.rst
@@ -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
 -----------------
 
-- 
2.50.1 (Apple Git-155)

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 <haohlliang@gmail.com>
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.

> diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst
> index a129570dab5a3..04be5789b5fcc 100644
> --- a/Documentation/core-api/real-time/differences.rst
> +++ b/Documentation/core-api/real-time/differences.rst

[ ... ]

> @@ -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

[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?

> +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
>  -----------------

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260820144655.22492-1-haohlliang@gmail.com?part=1

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.

Signed-off-by: Liang Hao <haohlliang@gmail.com>
---
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(-)

diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst
index a129570dab5a..6f5be9f0da2e 100644
--- a/Documentation/core-api/real-time/differences.rst
+++ b/Documentation/core-api/real-time/differences.rst
@@ -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
 -----------------
 
-- 
2.50.1 (Apple Git-155)

Liang Hao <haohlliang@gmail.com> writes:

> 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.
>
> Signed-off-by: Liang Hao <haohlliang@gmail.com>
> ---
> 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(-)
>
> diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst
> index a129570dab5a..6f5be9f0da2e 100644
> --- a/Documentation/core-api/real-time/differences.rst
> +++ b/Documentation/core-api/real-time/differences.rst
> @@ -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
>  -----------------

Applied, thanks.

jon

On 2026-08-21 00:38:58 [+0800], Liang Hao wrote:
> 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.
> 
> Signed-off-by: Liang Hao <haohlliang@gmail.com>

Reviewed-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

Sebastian