€•Ñ|      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ*/translations/zh_CN/trace/rv/monitor_rtapp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/zh_TW/trace/rv/monitor_rtapp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/it_IT/trace/rv/monitor_rtapp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/ja_JP/trace/rv/monitor_rtapp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/ko_KR/trace/rv/monitor_rtapp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/pt_BR/trace/rv/monitor_rtapp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/sp_SP/trace/rv/monitor_rtapp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒReal-time application monitors”h]”hŒReal-time application monitors”…””}”(hh¼h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhh·h²hh³ŒD/var/lib/git/docbuild/linux/Documentation/trace/rv/monitor_rtapp.rst”h´KubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒName: rtapp”h]”hŒ	paragraph”“”)”}”(hhÔh]”hŒName: rtapp”…””}”(hhØh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KhhÒubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhhÍh²hh³hÊh´NubhÑ)”}”(hŒ%Type: container for multiple monitors”h]”h×)”}”(hhíh]”hŒ%Type: container for multiple monitors”…””}”(hhïh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Khhëubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhhÍh²hh³hÊh´NubhÑ)”}”(hŒ'Author: Nam Cao <namcao@linutronix.de>
”h]”h×)”}”(hŒ&Author: Nam Cao <namcao@linutronix.de>”h]”(hŒAuthor: Nam Cao <”…””}”(hj  h²hh³Nh´NubhŒ	reference”“”)”}”(hŒnamcao@linutronix.de”h]”hŒnamcao@linutronix.de”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:namcao@linutronix.de”uh1j  hj  ubhŒ>”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhhÍh²hh³hÊh´Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1hËh³hÊh´Khh·h²hubh¶)”}”(hhh]”(h»)”}”(hŒDescription”h]”hŒDescription”…””}”(hj;  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj8  h²hh³hÊh´K	ubh×)”}”(hŒ­Real-time applications may have design flaws such that they experience
unexpected latency and fail to meet their time requirements. Often, these flaws
follow a few patterns:”h]”hŒ­Real-time applications may have design flaws such that they experience
unexpected latency and fail to meet their time requirements. Often, these flaws
follow a few patterns:”…””}”(hjI  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Khj8  h²hubhŒblock_quote”“”)”}”(hX—  - Page faults: A real-time thread may access memory that does not have a
  mapped physical backing or must first be copied (such as for copy-on-write).
  Thus a page fault is raised and the kernel must first perform the expensive
  action. This causes significant delays to the real-time thread
- Priority inversion: A real-time thread blocks waiting for a lower-priority
  thread. This causes the real-time thread to effectively take on the
  scheduling priority of the lower-priority thread. For example, the real-time
  thread needs to access a shared resource that is protected by a
  non-pi-mutex, but the mutex is currently owned by a non-real-time thread.
”h]”hÌ)”}”(hhh]”(hÑ)”}”(hX  Page faults: A real-time thread may access memory that does not have a
mapped physical backing or must first be copied (such as for copy-on-write).
Thus a page fault is raised and the kernel must first perform the expensive
action. This causes significant delays to the real-time thread”h]”h×)”}”(hX  Page faults: A real-time thread may access memory that does not have a
mapped physical backing or must first be copied (such as for copy-on-write).
Thus a page fault is raised and the kernel must first perform the expensive
action. This causes significant delays to the real-time thread”h]”hX  Page faults: A real-time thread may access memory that does not have a
mapped physical backing or must first be copied (such as for copy-on-write).
Thus a page fault is raised and the kernel must first perform the expensive
action. This causes significant delays to the real-time thread”…””}”(hjd  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Khj`  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj]  ubhÑ)”}”(hXf  Priority inversion: A real-time thread blocks waiting for a lower-priority
thread. This causes the real-time thread to effectively take on the
scheduling priority of the lower-priority thread. For example, the real-time
thread needs to access a shared resource that is protected by a
non-pi-mutex, but the mutex is currently owned by a non-real-time thread.
”h]”h×)”}”(hXe  Priority inversion: A real-time thread blocks waiting for a lower-priority
thread. This causes the real-time thread to effectively take on the
scheduling priority of the lower-priority thread. For example, the real-time
thread needs to access a shared resource that is protected by a
non-pi-mutex, but the mutex is currently owned by a non-real-time thread.”h]”hXe  Priority inversion: A real-time thread blocks waiting for a lower-priority
thread. This causes the real-time thread to effectively take on the
scheduling priority of the lower-priority thread. For example, the real-time
thread needs to access a shared resource that is protected by a
non-pi-mutex, but the mutex is currently owned by a non-real-time thread.”…””}”(hj|  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Khjx  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj]  ubeh}”(h]”h ]”h"]”h$]”h&]”j6  j7  uh1hËh³hÊh´KhjY  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  h³hÊh´Khj8  h²hubh×)”}”(hŒÖThe `rtapp` monitor detects these patterns. It aids developers to identify
reasons for unexpected latency with real-time applications. It is a container of
multiple sub-monitors described in the following sections.”h]”(hŒThe ”…””}”(hjœ  h²hh³Nh´NubhŒtitle_reference”“”)”}”(hŒ`rtapp`”h]”hŒrtapp”…””}”(hj¦  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hjœ  ubhŒË monitor detects these patterns. It aids developers to identify
reasons for unexpected latency with real-time applications. It is a container of
multiple sub-monitors described in the following sections.”…””}”(hjœ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Khj8  h²hubh¶)”}”(hhh]”(h»)”}”(hŒMonitor pagefault”h]”hŒMonitor pagefault”…””}”(hjÁ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj¾  h²hh³hÊh´Kubh×)”}”(hŒ[The `pagefault` monitor reports real-time tasks raising page faults. Its
specification is::”h]”(hŒThe ”…””}”(hjÏ  h²hh³Nh´Nubj¥  )”}”(hŒ`pagefault`”h]”hŒ	pagefault”…””}”(hj×  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hjÏ  ubhŒK monitor reports real-time tasks raising page faults. Its
specification is:”…””}”(hjÏ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K hj¾  h²hubhŒliteral_block”“”)”}”(hŒ&RULE = always (RT imply not PAGEFAULT)”h]”hŒ&RULE = always (RT imply not PAGEFAULT)”…””}”hjñ  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jï  h³hÊh´K#hj¾  h²hubh×)”}”(hŒvTo fix warnings reported by this monitor, `mlockall()` or `mlock()` can be used
to ensure physical backing for memory.”h]”(hŒ*To fix warnings reported by this monitor, ”…””}”(hj  h²hh³Nh´Nubj¥  )”}”(hŒ`mlockall()`”h]”hŒ
mlockall()”…””}”(hj	  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒ or ”…””}”(hj  h²hh³Nh´Nubj¥  )”}”(hŒ	`mlock()`”h]”hŒmlock()”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒ3 can be used
to ensure physical backing for memory.”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K%hj¾  h²hubh×)”}”(hX£  This monitor may have false negatives because the pages used by the real-time
threads may just happen to be directly available during testing.  To minimize
this, the system can be put under memory pressure (e.g.  invoking the OOM killer
using a program that does `ptr = malloc(SIZE_OF_RAM); memset(ptr, 0,
SIZE_OF_RAM);`) so that the kernel executes aggressive strategies to recycle as
much physical memory as possible.”h]”(hX  This monitor may have false negatives because the pages used by the real-time
threads may just happen to be directly available during testing.  To minimize
this, the system can be put under memory pressure (e.g.  invoking the OOM killer
using a program that does ”…””}”(hj3  h²hh³Nh´Nubj¥  )”}”(hŒ9`ptr = malloc(SIZE_OF_RAM); memset(ptr, 0,
SIZE_OF_RAM);`”h]”hŒ7ptr = malloc(SIZE_OF_RAM); memset(ptr, 0,
SIZE_OF_RAM);”…””}”(hj;  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj3  ubhŒc) so that the kernel executes aggressive strategies to recycle as
much physical memory as possible.”…””}”(hj3  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K(hj¾  h²hubeh}”(h]”Œmonitor-pagefault”ah ]”h"]”Œmonitor pagefault”ah$]”h&]”uh1hµhj8  h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒMonitor sleep”h]”hŒMonitor sleep”…””}”(hj^  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj[  h²hh³hÊh´K0ubh×)”}”(hŒËThe `sleep` monitor reports real-time threads sleeping in a manner that may
cause undesirable latency. Real-time applications should only put a real-time
thread to sleep for one of the following reasons:”h]”(hŒThe ”…””}”(hjl  h²hh³Nh´Nubj¥  )”}”(hŒ`sleep`”h]”hŒsleep”…””}”(hjt  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hjl  ubhŒÀ monitor reports real-time threads sleeping in a manner that may
cause undesirable latency. Real-time applications should only put a real-time
thread to sleep for one of the following reasons:”…””}”(hjl  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K2hj[  h²hubjX  )”}”(hX¡  - Cyclic work: real-time thread sleeps waiting for the next
  cycle. For this case, only the `clock_nanosleep` syscall should be
  used with `TIMER_ABSTIME` (to avoid time drift). Additionally,
  `CLOCK_REALTIME` should not be used (to avoid the clock being
  changed). No other method is safe for real-time. For example,
  threads waiting for timerfd can be woken by softirq which provides
  no real-time guarantee.
- Real-time thread waiting for something to happen (e.g. another thread
  releasing shared resources, or a completion signal from another thread). In
  this case, only futexes (FUTEX_LOCK_PI, FUTEX_LOCK_PI2 or one of
  FUTEX_WAIT_*) should be used.  Applications usually do not use futexes
  directly, but use PI mutexes and PI condition variables which are built on
  top of futexes. Be aware that the C library might not implement conditional
  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.
”h]”hÌ)”}”(hhh]”(hÑ)”}”(hX’  Cyclic work: real-time thread sleeps waiting for the next
cycle. For this case, only the `clock_nanosleep` syscall should be
used with `TIMER_ABSTIME` (to avoid time drift). Additionally,
`CLOCK_REALTIME` should not be used (to avoid the clock being
changed). No other method is safe for real-time. For example,
threads waiting for timerfd can be woken by softirq which provides
no real-time guarantee.”h]”h×)”}”(hX’  Cyclic work: real-time thread sleeps waiting for the next
cycle. For this case, only the `clock_nanosleep` syscall should be
used with `TIMER_ABSTIME` (to avoid time drift). Additionally,
`CLOCK_REALTIME` should not be used (to avoid the clock being
changed). No other method is safe for real-time. For example,
threads waiting for timerfd can be woken by softirq which provides
no real-time guarantee.”h]”(hŒYCyclic work: real-time thread sleeps waiting for the next
cycle. For this case, only the ”…””}”(hj—  h²hh³Nh´Nubj¥  )”}”(hŒ`clock_nanosleep`”h]”hŒclock_nanosleep”…””}”(hjŸ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj—  ubhŒ syscall should be
used with ”…””}”(hj—  h²hh³Nh´Nubj¥  )”}”(hŒ`TIMER_ABSTIME`”h]”hŒTIMER_ABSTIME”…””}”(hj±  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj—  ubhŒ& (to avoid time drift). Additionally,
”…””}”(hj—  h²hh³Nh´Nubj¥  )”}”(hŒ`CLOCK_REALTIME`”h]”hŒCLOCK_REALTIME”…””}”(hjÃ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj—  ubhŒÆ should not be used (to avoid the clock being
changed). No other method is safe for real-time. For example,
threads waiting for timerfd can be woken by softirq which provides
no real-time guarantee.”…””}”(hj—  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K6hj“  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj  ubhÑ)”}”(hXe  Real-time thread waiting for something to happen (e.g. another thread
releasing shared resources, or a completion signal from another thread). In
this case, only futexes (FUTEX_LOCK_PI, FUTEX_LOCK_PI2 or one of
FUTEX_WAIT_*) should be used.  Applications usually do not use futexes
directly, but use PI mutexes and PI condition variables which are built on
top of futexes. Be aware that the C library might not implement conditional
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.”h]”h×)”}”(hXe  Real-time thread waiting for something to happen (e.g. another thread
releasing shared resources, or a completion signal from another thread). In
this case, only futexes (FUTEX_LOCK_PI, FUTEX_LOCK_PI2 or one of
FUTEX_WAIT_*) should be used.  Applications usually do not use futexes
directly, but use PI mutexes and PI condition variables which are built on
top of futexes. Be aware that the C library might not implement conditional
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.”h]”hXe  Real-time thread waiting for something to happen (e.g. another thread
releasing shared resources, or a completion signal from another thread). In
this case, only futexes (FUTEX_LOCK_PI, FUTEX_LOCK_PI2 or one of
FUTEX_WAIT_*) should be used.  Applications usually do not use futexes
directly, but use PI mutexes and PI condition variables which are built on
top of futexes. Be aware that the C library might not implement conditional
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.”…””}”(hjå  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K=hjá  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj  ubhÑ)”}”(hŒ„Real-time thread waiting for events using `epoll_wait`, which is a
real-time-safe syscall for sleeping as it uses PI-aware locking.
”h]”h×)”}”(hŒƒReal-time thread waiting for events using `epoll_wait`, which is a
real-time-safe syscall for sleeping as it uses PI-aware locking.”h]”(hŒ*Real-time thread waiting for events using ”…””}”(hjý  h²hh³Nh´Nubj¥  )”}”(hŒ`epoll_wait`”h]”hŒ
epoll_wait”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hjý  ubhŒM, which is a
real-time-safe syscall for sleeping as it uses PI-aware locking.”…””}”(hjý  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KFhjù  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj  ubeh}”(h]”h ]”h"]”h$]”h&]”j6  j7  uh1hËh³hÊh´K6hjŒ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  h³hÊh´K6hj[  h²hubh×)”}”(hŒaBeside the reason for sleeping, the eventual waker should also be
real-time-safe. Namely, one of:”h]”hŒaBeside the reason for sleeping, the eventual waker should also be
real-time-safe. Namely, one of:”…””}”(hj/  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KIhj[  h²hubjX  )”}”(hŒ_- An equal-or-higher-priority thread
- Hard interrupt handler
- Non-maskable interrupt handler
”h]”hÌ)”}”(hhh]”(hÑ)”}”(hŒ"An equal-or-higher-priority thread”h]”h×)”}”(hjF  h]”hŒ"An equal-or-higher-priority thread”…””}”(hjH  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KLhjD  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhjA  ubhÑ)”}”(hŒHard interrupt handler”h]”h×)”}”(hj]  h]”hŒHard interrupt handler”…””}”(hj_  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KMhj[  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhjA  ubhÑ)”}”(hŒNon-maskable interrupt handler
”h]”h×)”}”(hŒNon-maskable interrupt handler”h]”hŒNon-maskable interrupt handler”…””}”(hjv  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KNhjr  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhjA  ubeh}”(h]”h ]”h"]”h$]”h&]”j6  j7  uh1hËh³hÊh´KLhj=  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  h³hÊh´KLhj[  h²hubh×)”}”(hŒ:This monitor's warning usually means one of the following:”h]”hŒ<This monitorâ€™s warning usually means one of the following:”…””}”(hj–  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KPhj[  h²hubjX  )”}”(hXß  - Real-time thread is blocked by a non-real-time thread (e.g. due to
  contention on a mutex without priority inheritance). This is priority
  inversion.
- Time-critical work waits for something which is not safe for real-time (e.g.
  timerfd).
- The work executed by the real-time thread does not need to run at real-time
  priority at all.  This is not a problem for the real-time thread itself, but
  it is potentially taking the CPU away from other important real-time work.
”h]”hÌ)”}”(hhh]”(hÑ)”}”(hŒ“Real-time thread is blocked by a non-real-time thread (e.g. due to
contention on a mutex without priority inheritance). This is priority
inversion.”h]”h×)”}”(hŒ“Real-time thread is blocked by a non-real-time thread (e.g. due to
contention on a mutex without priority inheritance). This is priority
inversion.”h]”hŒ“Real-time thread is blocked by a non-real-time thread (e.g. due to
contention on a mutex without priority inheritance). This is priority
inversion.”…””}”(hj¯  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KRhj«  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj¨  ubhÑ)”}”(hŒVTime-critical work waits for something which is not safe for real-time (e.g.
timerfd).”h]”h×)”}”(hŒVTime-critical work waits for something which is not safe for real-time (e.g.
timerfd).”h]”hŒVTime-critical work waits for something which is not safe for real-time (e.g.
timerfd).”…””}”(hjÇ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KUhjÃ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj¨  ubhÑ)”}”(hŒäThe work executed by the real-time thread does not need to run at real-time
priority at all.  This is not a problem for the real-time thread itself, but
it is potentially taking the CPU away from other important real-time work.
”h]”h×)”}”(hŒãThe work executed by the real-time thread does not need to run at real-time
priority at all.  This is not a problem for the real-time thread itself, but
it is potentially taking the CPU away from other important real-time work.”h]”hŒãThe work executed by the real-time thread does not need to run at real-time
priority at all.  This is not a problem for the real-time thread itself, but
it is potentially taking the CPU away from other important real-time work.”…””}”(hjß  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KWhjÛ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj¨  ubeh}”(h]”h ]”h"]”h$]”h&]”j6  j7  uh1hËh³hÊh´KRhj¤  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  h³hÊh´KRhj[  h²hubh×)”}”(hŒ÷Application developers may purposely choose to have their real-time application
sleep in a way that is not safe for real-time. It is debatable whether that is a
problem. Application developers must analyze the warnings to make a proper
assessment.”h]”hŒ÷Application developers may purposely choose to have their real-time application
sleep in a way that is not safe for real-time. It is debatable whether that is a
problem. Application developers must analyze the warnings to make a proper
assessment.”…””}”(hjÿ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K[hj[  h²hubh×)”}”(hŒ The monitor's specification is::”h]”hŒ!The monitorâ€™s specification is:”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K`hj[  h²hubjð  )”}”(hX  RULE = always ((RT and SLEEP and USER_THREAD) imply (RT_FRIENDLY_SLEEP or ALLOWLIST))

RT_FRIENDLY_SLEEP = RT_VALID_SLEEP_REASON
                and ((not SCHEDULE_IN) until RT_FRIENDLY_WAKE)

RT_VALID_SLEEP_REASON = FUTEX_WAIT
                     or RT_FRIENDLY_NANOSLEEP
                     or EPOLL_WAIT

RT_FRIENDLY_NANOSLEEP = CLOCK_NANOSLEEP
                    and NANOSLEEP_TIMER_ABSTIME
                    and not NANOSLEEP_CLOCK_REALTIME

RT_FRIENDLY_WAKE = WOKEN_BY_EQUAL_OR_HIGHER_PRIO
                or WOKEN_BY_HARDIRQ
                or WOKEN_BY_NMI
                or ABORT_SLEEP

ALLOWLIST = BLOCK_ON_RT_MUTEX
         or FUTEX_LOCK_PI”h]”hX  RULE = always ((RT and SLEEP and USER_THREAD) imply (RT_FRIENDLY_SLEEP or ALLOWLIST))

RT_FRIENDLY_SLEEP = RT_VALID_SLEEP_REASON
                and ((not SCHEDULE_IN) until RT_FRIENDLY_WAKE)

RT_VALID_SLEEP_REASON = FUTEX_WAIT
                     or RT_FRIENDLY_NANOSLEEP
                     or EPOLL_WAIT

RT_FRIENDLY_NANOSLEEP = CLOCK_NANOSLEEP
                    and NANOSLEEP_TIMER_ABSTIME
                    and not NANOSLEEP_CLOCK_REALTIME

RT_FRIENDLY_WAKE = WOKEN_BY_EQUAL_OR_HIGHER_PRIO
                or WOKEN_BY_HARDIRQ
                or WOKEN_BY_NMI
                or ABORT_SLEEP

ALLOWLIST = BLOCK_ON_RT_MUTEX
         or FUTEX_LOCK_PI”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jÿ  j   uh1jï  h³hÊh´Kbhj[  h²hubh×)”}”(hŒæ`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.”h]”(j¥  )”}”(hŒ`ABORT_SLEEP`”h]”hŒABORT_SLEEP”…””}”(hj-  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj)  ubhŒ* represents a task restoring its state to ”…””}”(hj)  h²hh³Nh´Nubj¥  )”}”(hŒ`TASK_RUNNING`”h]”hŒTASK_RUNNING”…””}”(hj?  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj)  ubhŒ¡ 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.”…””}”(hj)  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Kwhj[  h²hubh×)”}”(hŒqBeside the scenarios described above, this specification also defines an allow list
to handle some special cases:”h]”hŒqBeside the scenarios described above, this specification also defines an allow list
to handle some special cases:”…””}”(hjW  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K{hj[  h²hubjX  )”}”(hXÔ  - `BLOCK_ON_RT_MUTEX` is included in the allowlist due to its implementation.
  In the release path of rt_mutex, a boosted task is de-boosted before waking
  the rt_mutex's waiter. Consequently, the monitor may see a real-time-unsafe
  wakeup (e.g. non-real-time task waking real-time task). This is actually
  real-time-safe because preemption is disabled for the duration.
- `FUTEX_LOCK_PI` is included in the allowlist for the same reason as
  `BLOCK_ON_RT_MUTEX`.
”h]”hÌ)”}”(hhh]”(hÑ)”}”(hXl  `BLOCK_ON_RT_MUTEX` is included in the allowlist due to its implementation.
In the release path of rt_mutex, a boosted task is de-boosted before waking
the rt_mutex's waiter. Consequently, the monitor may see a real-time-unsafe
wakeup (e.g. non-real-time task waking real-time task). This is actually
real-time-safe because preemption is disabled for the duration.”h]”h×)”}”(hXl  `BLOCK_ON_RT_MUTEX` is included in the allowlist due to its implementation.
In the release path of rt_mutex, a boosted task is de-boosted before waking
the rt_mutex's waiter. Consequently, the monitor may see a real-time-unsafe
wakeup (e.g. non-real-time task waking real-time task). This is actually
real-time-safe because preemption is disabled for the duration.”h]”(j¥  )”}”(hŒ`BLOCK_ON_RT_MUTEX`”h]”hŒBLOCK_ON_RT_MUTEX”…””}”(hjt  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hjp  ubhX[   is included in the allowlist due to its implementation.
In the release path of rt_mutex, a boosted task is de-boosted before waking
the rt_mutexâ€™s waiter. Consequently, the monitor may see a real-time-unsafe
wakeup (e.g. non-real-time task waking real-time task). This is actually
real-time-safe because preemption is disabled for the duration.”…””}”(hjp  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K~hjl  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhji  ubhÑ)”}”(hŒY`FUTEX_LOCK_PI` is included in the allowlist for the same reason as
`BLOCK_ON_RT_MUTEX`.
”h]”h×)”}”(hŒX`FUTEX_LOCK_PI` is included in the allowlist for the same reason as
`BLOCK_ON_RT_MUTEX`.”h]”(j¥  )”}”(hŒ`FUTEX_LOCK_PI`”h]”hŒFUTEX_LOCK_PI”…””}”(hjš  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj–  ubhŒ5 is included in the allowlist for the same reason as
”…””}”(hj–  h²hh³Nh´Nubj¥  )”}”(hŒ`BLOCK_ON_RT_MUTEX`”h]”hŒBLOCK_ON_RT_MUTEX”…””}”(hj¬  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj–  ubhŒ.”…””}”(hj–  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Kƒhj’  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhji  ubeh}”(h]”h ]”h"]”h$]”h&]”j6  j7  uh1hËh³hÊh´K~hje  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  h³hÊh´K~hj[  h²hubeh}”(h]”Œmonitor-sleep”ah ]”h"]”Œmonitor sleep”ah$]”h&]”uh1hµhj8  h²hh³hÊh´K0ubh¶)”}”(hhh]”(h»)”}”(hŒMonitor wakeup”h]”hŒMonitor wakeup”…””}”(hjá  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjÞ  h²hh³hÊh´K‡ubh×)”}”(hŒ“The `wakeup` monitor reports real-time threads being woken by lower-priority threads,
which is a hint of priority inversion. Its specification is::”h]”(hŒThe ”…””}”(hjï  h²hh³Nh´Nubj¥  )”}”(hŒ`wakeup`”h]”hŒwakeup”…””}”(hj÷  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hjï  ubhŒ† monitor reports real-time threads being woken by lower-priority threads,
which is a hint of priority inversion. Its specification is:”…””}”(hjï  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K‰hjÞ  h²hubjð  )”}”(hŒ°RULE = always (((RT and USER_THREAD) imply
              (not (WOKEN_BY_LOWER_PRIO or WOKEN_BY_SOFTIRQ)) or ALLOWLIST))

ALLOWLIST = BLOCK_ON_RT_MUTEX
         or FUTEX_LOCK_PI”h]”hŒ°RULE = always (((RT and USER_THREAD) imply
              (not (WOKEN_BY_LOWER_PRIO or WOKEN_BY_SOFTIRQ)) or ALLOWLIST))

ALLOWLIST = BLOCK_ON_RT_MUTEX
         or FUTEX_LOCK_PI”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jÿ  j   uh1jï  h³hÊh´KŒhjÞ  h²hubh×)”}”(hX  The `sleep` monitor already reports this type of problem. The difference is the
context in which the problem is reported. While the `sleep` monitor reports the problem
in the context of the wakee, this `wakeup` monitor reports the problem in the context of
the waker. This monitor complement the `sleep` monitor, giving user better
understanding of the issue. For instance, to debug a lower-priority task waking a
higher-priority task scenario, user can enable both `wakeup` monitor and `sleep`
monitor to get the stack traces of both tasks.”h]”(hŒThe ”…””}”(hj  h²hh³Nh´Nubj¥  )”}”(hŒ`sleep`”h]”hŒsleep”…””}”(hj%  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒy monitor already reports this type of problem. The difference is the
context in which the problem is reported. While the ”…””}”(hj  h²hh³Nh´Nubj¥  )”}”(hŒ`sleep`”h]”hŒsleep”…””}”(hj7  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒ? monitor reports the problem
in the context of the wakee, this ”…””}”(hj  h²hh³Nh´Nubj¥  )”}”(hŒ`wakeup`”h]”hŒwakeup”…””}”(hjI  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒV monitor reports the problem in the context of
the waker. This monitor complement the ”…””}”(hj  h²hh³Nh´Nubj¥  )”}”(hŒ`sleep`”h]”hŒsleep”…””}”(hj[  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒ£ monitor, giving user better
understanding of the issue. For instance, to debug a lower-priority task waking a
higher-priority task scenario, user can enable both ”…””}”(hj  h²hh³Nh´Nubj¥  )”}”(hŒ`wakeup`”h]”hŒwakeup”…””}”(hjm  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒ monitor and ”…””}”(hj  h²hh³Nh´Nubj¥  )”}”(hŒ`sleep`”h]”hŒsleep”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒ/
monitor to get the stack traces of both tasks.”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K’hjÞ  h²hubeh}”(h]”Œmonitor-wakeup”ah ]”h"]”Œmonitor wakeup”ah$]”h&]”uh1hµhj8  h²hh³hÊh´K‡ubeh}”(h]”Œdescription”ah ]”h"]”Œdescription”ah$]”h&]”uh1hµhh·h²hh³hÊh´K	ubeh}”(h]”Œreal-time-application-monitors”ah ]”h"]”Œreal-time application monitors”ah$]”h&]”uh1hµhhh²hh³hÊh´Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”hÊuh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hºNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jÒ  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”hÊŒ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j¬  j©  j¤  j¡  jX  jU  jÛ  jØ  jœ  j™  uŒ	nametypes”}”(j¬  ‰j¤  ‰jX  ‰jÛ  ‰jœ  ‰uh}”(j©  h·j¡  j8  jU  j¾  jØ  j[  j™  jÞ  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nh²hub.