Re: [PATCH v3] docs: timers: hrtimers: clarify expiry modes and ktimersd on PREEMPT_RT

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

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