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