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

[Sebastian Andrzej Siewior <bigeasy@linutronix.de>]

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