€•Ds      Œ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) and `CLOCK_MONOTONIC` (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.
”h]”hÌ)”}”(hhh]”(hÑ)”}”(hXu  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) and `CLOCK_MONOTONIC` (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Xu  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) and `CLOCK_MONOTONIC` (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) and ”…””}”(hj—  h²hh³Nh´Nubj¥  )”}”(hŒ`CLOCK_MONOTONIC`”h]”hŒCLOCK_MONOTONIC”…””}”(hjÃ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj—  ubhŒ³ (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Xf  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  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´KFh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j  h]”hŒ"An equal-or-higher-priority thread”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KIhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj  ubhÑ)”}”(hŒHard interrupt handler”h]”h×)”}”(hj3  h]”hŒHard interrupt handler”…””}”(hj5  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KJhj1  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj  ubhÑ)”}”(hŒNon-maskable interrupt handler
”h]”h×)”}”(hŒNon-maskable interrupt handler”h]”hŒNon-maskable interrupt handler”…””}”(hjL  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KKhjH  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj  ubeh}”(h]”h ]”h"]”h$]”h&]”j6  j7  uh1hËh³hÊh´KIhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  h³hÊh´KIh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jl  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´KMh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´KOh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´KRh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´KThj±  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj~  ubeh}”(h]”h ]”h"]”h$]”h&]”j6  j7  uh1hËh³hÊh´KOhjz  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  h³hÊh´KOh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´KXh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) imply (RT_FRIENDLY_SLEEP or ALLOWLIST))

RT_FRIENDLY_SLEEP = (RT_VALID_SLEEP_REASON or KERNEL_THREAD)
                and ((not WAKE) until RT_FRIENDLY_WAKE)

RT_VALID_SLEEP_REASON = FUTEX_WAIT
                     or RT_FRIENDLY_NANOSLEEP

RT_FRIENDLY_NANOSLEEP = CLOCK_NANOSLEEP
                    and NANOSLEEP_TIMER_ABSTIME
                    and NANOSLEEP_CLOCK_MONOTONIC

RT_FRIENDLY_WAKE = WOKEN_BY_EQUAL_OR_HIGHER_PRIO
                or WOKEN_BY_HARDIRQ
                or WOKEN_BY_NMI
                or KTHREAD_SHOULD_STOP

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

RT_FRIENDLY_SLEEP = (RT_VALID_SLEEP_REASON or KERNEL_THREAD)
                and ((not WAKE) until RT_FRIENDLY_WAKE)

RT_VALID_SLEEP_REASON = FUTEX_WAIT
                     or RT_FRIENDLY_NANOSLEEP

RT_FRIENDLY_NANOSLEEP = CLOCK_NANOSLEEP
                    and NANOSLEEP_TIMER_ABSTIME
                    and NANOSLEEP_CLOCK_MONOTONIC

RT_FRIENDLY_WAKE = WOKEN_BY_EQUAL_OR_HIGHER_PRIO
                or WOKEN_BY_HARDIRQ
                or WOKEN_BY_NMI
                or KTHREAD_SHOULD_STOP

ALLOWLIST = BLOCK_ON_RT_MUTEX
         or FUTEX_LOCK_PI
         or TASK_IS_RCU
         or TASK_IS_MIGRATION”…””}”hjñ  sbah}”(h]”h ]”h"]”h$]”h&]”jÿ  j   uh1jï  h³hÊh´K_hj[  h²hubh×)”}”(hŒXBeside the scenarios described above, this specification also handle some
special cases:”h]”hŒXBeside the scenarios described above, this specification also handle some
special cases:”…””}”(hjÿ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Kuhj[  h²hubjX  )”}”(hX|  - `KERNEL_THREAD`: kernel tasks do not have any pattern that can be recognized
  as valid real-time sleeping reasons. Therefore sleeping reason is not
  checked for kernel tasks.
- `KTHREAD_SHOULD_STOP`: a non-real-time thread may stop a real-time kernel
  thread by waking it and waiting for it to exit (`kthread_stop()`). This
  wakeup is safe for real-time.
- `ALLOWLIST`: to handle known false positives with the kernel.
- `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Œ¬`KERNEL_THREAD`: kernel tasks do not have any pattern that can be recognized
as valid real-time sleeping reasons. Therefore sleeping reason is not
checked for kernel tasks.”h]”h×)”}”(hŒ¬`KERNEL_THREAD`: kernel tasks do not have any pattern that can be recognized
as valid real-time sleeping reasons. Therefore sleeping reason is not
checked for kernel tasks.”h]”(j¥  )”}”(hŒ`KERNEL_THREAD`”h]”hŒKERNEL_THREAD”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj  ubhŒ: kernel tasks do not have any pattern that can be recognized
as valid real-time sleeping reasons. Therefore sleeping reason is not
checked for kernel tasks.”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´Kxhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj  ubhÑ)”}”(hŒ¯`KTHREAD_SHOULD_STOP`: a non-real-time thread may stop a real-time kernel
thread by waking it and waiting for it to exit (`kthread_stop()`). This
wakeup is safe for real-time.”h]”h×)”}”(hŒ¯`KTHREAD_SHOULD_STOP`: a non-real-time thread may stop a real-time kernel
thread by waking it and waiting for it to exit (`kthread_stop()`). This
wakeup is safe for real-time.”h]”(j¥  )”}”(hŒ`KTHREAD_SHOULD_STOP`”h]”hŒKTHREAD_SHOULD_STOP”…””}”(hjB  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj>  ubhŒe: a non-real-time thread may stop a real-time kernel
thread by waking it and waiting for it to exit (”…””}”(hj>  h²hh³Nh´Nubj¥  )”}”(hŒ`kthread_stop()`”h]”hŒkthread_stop()”…””}”(hjT  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj>  ubhŒ%). This
wakeup is safe for real-time.”…””}”(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j  ubhÑ)”}”(hŒ=`ALLOWLIST`: to handle known false positives with the kernel.”h]”h×)”}”(hjt  h]”(j¥  )”}”(hŒ`ALLOWLIST`”h]”hŒ	ALLOWLIST”…””}”(hjy  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hjv  ubhŒ2: to handle known false positives with the kernel.”…””}”(hjv  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÖh³hÊh´K~hjr  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÐhj  ubhÑ)”}”(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jŸ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j¤  hj›  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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j  ubhÑ)”}”(hŒX`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j  ubeh}”(h]”h ]”h"]”h$]”h&]”j6  j7  uh1hËh³hÊh´Kxhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  h³hÊh´Kxhj[  h²hubeh}”(h]”Œmonitor-sleep”ah ]”h"]”Œmonitor sleep”ah$]”h&]”uh1hµhj8  h²hh³hÊh´K0ubeh}”(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  uŒ	nametypes”}”(j  ‰j  ‰jX  ‰j  ‰uh}”(j  h·j  j8  jU  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.