€•\r      Œ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Œ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hòhžhhŸNh NubhŒ	reference”“”)”}”(hŒnamcao@linutronix.de”h]”hŒnamcao@linutronix.de”…””}”(hhühžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:namcao@linutronix.de”uh1húhhòubhŒ>”…””}”(hhòhžhhŸNh Nubeh}”(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 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j$  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j5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Khj$  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jP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KhjL  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h¼hjI  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jh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Khjd  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h¼hjI  ubeh}”(h]”h ]”h"]”h$]”h&]”j"  j#  uh1h·hŸh¶h KhjE  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jC  hŸh¶h Khj$  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j$  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j  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j  ubhŒc) so that the kernel executes aggressive strategies to recycle as
much physical memory as possible.”…””}”(hj  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j$  hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒMonitor sleep”h]”hŒMonitor sleep”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjG  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jX  hžhhŸNh Nubj‘  )”}”(hŒ`sleep`”h]”hŒsleep”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjX  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jX  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K2hjG  hžhubjD  )”}”(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&]”j"  j#  uh1h·hŸh¶h K6hjx  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jC  hŸh¶h K6hjG  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jG  hžhubjD  )”}”(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j  h]”hŒHard interrupt handler”…””}”(hj!  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KJhj  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j8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KKhj4  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h¼hj  ubeh}”(h]”h ]”h"]”h$]”h&]”j"  j#  uh1h·hŸh¶h KIhjÿ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jC  hŸh¶h KIhjG  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jX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KMhjG  hžhubjD  )”}”(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jq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KOhjm  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h¼hjj  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jj  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jj  ubeh}”(h]”h ]”h"]”h$]”h&]”j"  j#  uh1h·hŸh¶h KOhjf  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jC  hŸh¶h KOhjG  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jG  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jG  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jG  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jG  hžhubjD  )”}”(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j.  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j@  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j`  h]”(j‘  )”}”(hŒ`ALLOWLIST`”h]”hŒ	ALLOWLIST”…””}”(hje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjb  ubhŒ2: to handle known false positives with the kernel.”…””}”(hjb  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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&]”j"  j#  uh1h·hŸh¶h Kxhjù  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jC  hŸh¶h KxhjG  hžhubeh}”(h]”Œmonitor-sleep”ah ]”h"]”Œmonitor sleep”ah$]”h&]”uh1h¡hj$  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÷  jD  jA  jò  jï  uŒ	nametypes”}”(j  ‰jú  ‰jD  ‰jò  ‰uh}”(jÿ  h£j÷  j$  jA  jª  jï  jG  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.