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

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

[Chao Liu]

epoll_wait() is a valid sleeping reason for real-time tasks because it
uses PI-aware locking, but the rtapp sleep monitor documentation only
discusses clock_nanosleep() and futexes. Document it.

ABORT_SLEEP represents a task restoring TASK_RUNNING before entering
the scheduler. Since the task does not actually block, it becomes
runnable again without a wakeup sequence unsafe for real-time. Document
this behavior.

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>
---
Changes in v2:
- Explain why epoll_wait() is RT-safe in terms of PI-aware locking.
- Explain that ABORT_SLEEP does not require an RT-unsafe wakeup sequence.
- Update the commit message accordingly.

Link to v1:
https://lore.kernel.org/linux-trace-kernel/20260722045706.85633-1-chao.liu@processmission.com/

 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..b95994ade14a 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 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
+task is back to runnable without any wakeup sequence unsafe for real-time.
+
 Beside the scenarios described above, this specification also defines an allow list
 to handle some special cases:
 

base-commit: 248951ddc14de84de3910f9b13f51491a8cd91df
prerequisite-patch-id: d8b6c952a954662852e6b0684e0a3386eaab7f41
prerequisite-patch-id: 940f7637aeabe4ba15a09c048c6f48138406f332
prerequisite-patch-id: b99812692691f76d825778e01a2e771e058febd6
prerequisite-patch-id: 512c300dce2cb74ac9cc007f9234aa507ef5c008
-- 
2.54.0