Re: [RFC PATCH] Documentation/rv: Explain epoll and aborted sleeps

[Gabriele Monaco <gmonaco@redhat.com>]

On Wed, 2026-07-22 at 12:57 +0800, Chao Liu wrote:
> The rtapp sleep monitor accepts epoll_wait() as a valid sleeping
> reason, but the prose only discusses clock_nanosleep and futexes. Add
> epoll_wait to the list of valid sleeping reasons.
> 
> ABORT_SLEEP represents a task restoring TASK_RUNNING before entering
> the scheduler, but its meaning is not described. Explain why the
> aborted sleep attempt is valid.
> 
> This RFC is based on Nam Cao's pending "rv: rtapp monitor update" v2
> series:
> 
> https://lore.kernel.org/r/cover.1781852967.git.namcao@linutronix.de
> 
> Signed-off-by: Chao Liu <chao.liu@processmission.com>
> ---

Thanks for the contribution! I have a couple of comments, we want to be
assertive in this docs: in general, let's not say something like "this is valid
because the monitor thinks it's valid" but "this is valid because it is rt-safe
for reason X".

>  Documentation/trace/rv/monitor_rtapp.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/trace/rv/monitor_rtapp.rst
> b/Documentation/trace/rv/monitor_rtapp.rst
> index 238b59395ff5..234ed4d581ac 100644
> --- a/Documentation/trace/rv/monitor_rtapp.rst
> +++ b/Documentation/trace/rv/monitor_rtapp.rst
> @@ -67,6 +67,8 @@ thread to sleep for one of the following reasons:
>      variables as safe for real-time. As an alternative, the librtpi library
>      exists to provide a conditional variable implementation that is correct
> for
>      real-time applications in Linux.
> +  - Real-time thread waiting for events using `epoll_wait`,

> + which the monitor accepts as a valid sleeping reason for real-time tasks.

Not adding much value, try:

 which is a real-time-safe syscall for sleeping as it uses PI-aware locking.

>  
>  Beside the reason for sleeping, the eventual waker should also be
>  real-time-safe. Namely, one of:
> @@ -114,6 +116,10 @@ The monitor's specification is::
>    ALLOWLIST = BLOCK_ON_RT_MUTEX
>             or FUTEX_LOCK_PI
>  
> +`ABORT_SLEEP` represents a task restoring its state to `TASK_RUNNING` before
> +entering the scheduler. In this case, the task does not actually block,


> + so the monitor treats the aborted sleep attempt as valid.

This sentence is a bit vague. Indeed an /aborted/ sleep is a valid wakeup, as if
the task woke up itself without even sleeping, saying "the monitor treats the
attempt as valid" adds no value.

You could rephrase it to (full paragraph for clarity):

`ABORT_SLEEP` represents a task restoring its state to `TASK_RUNNING` before
entering the scheduler. In this case, the task does not actually block, so it is
back to runnable without any wakeup sequence unsafe for real-time.

What do you think?

Thanks,
Gabriele