€•ªŠ      Œ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/core-api/entry”Œ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/core-api/entry”Œ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/core-api/entry”Œ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/core-api/entry”Œ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/core-api/entry”Œ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/core-api/entry”Œ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/core-api/entry”Œ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Œ@Entry/exit handling for exceptions, interrupts, syscalls and KVM”h]”hŒ@Entry/exit handling for exceptions, interrupts, syscalls and KVM”…””}”(hh¼h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhh·h²hh³Œ</var/lib/git/docbuild/linux/Documentation/core-api/entry.rst”h´KubhŒ	paragraph”“”)”}”(hŒŸAll transitions between execution domains require state updates which are
subject to strict ordering constraints. State updates are required for the
following:”h]”hŒŸAll transitions between execution domains require state updates which are
subject to strict ordering constraints. State updates are required for the
following:”…””}”(hhÍh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khh·h²hubhŒblock_quote”“”)”}”(hŒT* Lockdep
* RCU / Context tracking
* Preemption counter
* Tracing
* Time accounting
”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒLockdep”h]”hÌ)”}”(hhêh]”hŒLockdep”…””}”(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ãubhç)”}”(hŒRCU / Context tracking”h]”hÌ)”}”(hj  h]”hŒRCU / Context tracking”…””}”(hj  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ãubhç)”}”(hŒPreemption counter”h]”hÌ)”}”(hj  h]”hŒPreemption counter”…””}”(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hãubhç)”}”(hŒTracing”h]”hÌ)”}”(hj/  h]”hŒTracing”…””}”(hj1  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khj-  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhhãubhç)”}”(hŒTime accounting
”h]”hÌ)”}”(hŒTime accounting”h]”hŒTime accounting”…””}”(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hãubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1háh³hÊh´KhhÝubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛh³hÊh´Khh·h²hubhÌ)”}”(hŒÂThe update order depends on the transition type and is explained below in
the transition type sections: `Syscalls`_, `KVM`_, `Interrupts and regular
exceptions`_, `NMI and NMI-like exceptions`_.”h]”(hŒhThe update order depends on the transition type and is explained below in
the transition type sections: ”…””}”(hjj  h²hh³Nh´NubhŒ	reference”“”)”}”(hŒ`Syscalls`_”h]”hŒSyscalls”…””}”(hjt  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”ŒSyscalls”Œrefid”Œsyscalls”uh1jr  hjj  Œresolved”KubhŒ, ”…””}”(hjj  h²hh³Nh´Nubjs  )”}”(hŒ`KVM`_”h]”hŒKVM”…””}”(hj‹  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”ŒKVM”j„  Œkvm”uh1jr  hjj  j†  KubhŒ, ”…””}”hjj  sbjs  )”}”(hŒ$`Interrupts and regular
exceptions`_”h]”hŒ!Interrupts and regular
exceptions”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”Œ!Interrupts and regular exceptions”j„  Œ!interrupts-and-regular-exceptions”uh1jr  hjj  j†  KubhŒ, ”…””}”hjj  sbjs  )”}”(hŒ`NMI and NMI-like exceptions`_”h]”hŒNMI and NMI-like exceptions”…””}”(hjµ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”ŒNMI and NMI-like exceptions”j„  Œnmi-and-nmi-like-exceptions”uh1jr  hjj  j†  KubhŒ.”…””}”(hjj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khh·h²hubh¶)”}”(hhh]”(h»)”}”(hŒ!Non-instrumentable code - noinstr”h]”hŒ!Non-instrumentable code - noinstr”…””}”(hjÓ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjÐ  h²hh³hÊh´KubhÌ)”}”(hXo  Most instrumentation facilities depend on RCU, so instrumentation is prohibited
for entry code before RCU starts watching and exit code after RCU stops
watching. In addition, many architectures must save and restore register state,
which means that (for example) a breakpoint in the breakpoint entry code would
overwrite the debug registers of the initial breakpoint.”h]”hXo  Most instrumentation facilities depend on RCU, so instrumentation is prohibited
for entry code before RCU starts watching and exit code after RCU stops
watching. In addition, many architectures must save and restore register state,
which means that (for example) a breakpoint in the breakpoint entry code would
overwrite the debug registers of the initial breakpoint.”…””}”(hjá  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KhjÐ  h²hubhÌ)”}”(hXR  Such code must be marked with the 'noinstr' attribute, placing that code into a
special section inaccessible to instrumentation and debug facilities. Some
functions are partially instrumentable, which is handled by marking them
noinstr and using instrumentation_begin() and instrumentation_end() to flag the
instrumentable ranges of code:”h]”hXV  Such code must be marked with the â€˜noinstrâ€™ attribute, placing that code into a
special section inaccessible to instrumentation and debug facilities. Some
functions are partially instrumentable, which is handled by marking them
noinstr and using instrumentation_begin() and instrumentation_end() to flag the
instrumentable ranges of code:”…””}”(hjï  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KhjÐ  h²hubhŒliteral_block”“”)”}”(hX3  noinstr void entry(void)
{
      handle_entry();     // <-- must be 'noinstr' or '__always_inline'
      ...

      instrumentation_begin();
      handle_context();   // <-- instrumentable code
      instrumentation_end();

      ...
      handle_exit();      // <-- must be 'noinstr' or '__always_inline'
}”h]”hX3  noinstr void entry(void)
{
      handle_entry();     // <-- must be 'noinstr' or '__always_inline'
      ...

      instrumentation_begin();
      handle_context();   // <-- instrumentable code
      instrumentation_end();

      ...
      handle_exit();      // <-- must be 'noinstr' or '__always_inline'
}”…””}”hjÿ  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”Œforce”‰Œlanguage”Œc”Œhighlight_args”}”uh1jý  h³hÊh´K!hjÐ  h²hubhÌ)”}”(hŒ^This allows verification of the 'noinstr' restrictions via objtool on
supported architectures.”h]”hŒbThis allows verification of the â€˜noinstrâ€™ restrictions via objtool on
supported architectures.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K0hjÐ  h²hubhÌ)”}”(hŒ²Invoking non-instrumentable functions from instrumentable context has no
restrictions and is useful to protect e.g. state switching which would
cause malfunction if instrumented.”h]”hŒ²Invoking non-instrumentable functions from instrumentable context has no
restrictions and is useful to protect e.g. state switching which would
cause malfunction if instrumented.”…””}”(hj"  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K3hjÐ  h²hubhÌ)”}”(hŒ}All non-instrumentable entry/exit code sections before and after the RCU
state transitions must run with interrupts disabled.”h]”hŒ}All non-instrumentable entry/exit code sections before and after the RCU
state transitions must run with interrupts disabled.”…””}”(hj0  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K7hjÐ  h²hubeh}”(h]”Œnon-instrumentable-code-noinstr”ah ]”h"]”Œ!non-instrumentable code - noinstr”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒSyscalls”h]”hŒSyscalls”…””}”(hjI  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjF  h²hh³hÊh´K;ubhÌ)”}”(hX)  Syscall-entry code starts in assembly code and calls out into low-level C
code after establishing low-level architecture-specific state and stack
frames. This low-level C code must not be instrumented. The recommended
syscall handling function invoked from low-level assembly code looks like
this:”h]”hX)  Syscall-entry code starts in assembly code and calls out into low-level C
code after establishing low-level architecture-specific state and stack
frames. This low-level C code must not be instrumented. The recommended
syscall handling function invoked from low-level assembly code looks like
this:”…””}”(hjW  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K=hjF  h²hubjþ  )”}”(hX˜  noinstr void syscall(struct pt_regs *regs, long nr)
{
      arch_syscall_enter(regs);
      result_reg(regs) = -ENOSYS;
      if (syscall_enter_from_user_mode_randomize_stack(regs, &nr)) {
              instrumentation_begin();
              if (valid(nr)
                      result_reg(regs) = invoke_syscall(regs, nr);
              instrumentation_end();
      }
      syscall_exit_to_user_mode(regs);
}”h]”hX˜  noinstr void syscall(struct pt_regs *regs, long nr)
{
      arch_syscall_enter(regs);
      result_reg(regs) = -ENOSYS;
      if (syscall_enter_from_user_mode_randomize_stack(regs, &nr)) {
              instrumentation_begin();
              if (valid(nr)
                      result_reg(regs) = invoke_syscall(regs, nr);
              instrumentation_end();
      }
      syscall_exit_to_user_mode(regs);
}”…””}”hje  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j  j  j  }”uh1jý  h³hÊh´KChjF  h²hubhÌ)”}”(hŒnThis is the most resilent variant as it has always a guaranteed valid
return code. The alternative variant is:”h]”hŒnThis is the most resilent variant as it has always a guaranteed valid
return code. The alternative variant is:”…””}”(hjt  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KRhjF  h²hubjþ  )”}”(hX»  noinstr void syscall(struct pt_regs *regs, long nr)
{
      arch_syscall_enter(regs);
      if (syscall_enter_from_user_mode_randomize_stack(regs, &nr)) {
              instrumentation_begin();
              if (valid(nr)
                      result_reg(regs) = invoke_syscall(regs, nr);
              else
                      result_reg(regs) = -ENOSYS;
              instrumentation_end();
      }
      syscall_exit_to_user_mode(regs);
}”h]”hX»  noinstr void syscall(struct pt_regs *regs, long nr)
{
      arch_syscall_enter(regs);
      if (syscall_enter_from_user_mode_randomize_stack(regs, &nr)) {
              instrumentation_begin();
              if (valid(nr)
                      result_reg(regs) = invoke_syscall(regs, nr);
              else
                      result_reg(regs) = -ENOSYS;
              instrumentation_end();
      }
      syscall_exit_to_user_mode(regs);
}”…””}”hj‚  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j  j  j  }”uh1jý  h³hÊh´KUhjF  h²hubhÌ)”}”(hŒòThat works for most situations except when a probe/BPF attached to the
syscall tracepoint sets an invalid syscall number e.g. -1 and also modifies
the result register. So this variant will obviously overwrite the modified
result with -ENOSYS.”h]”hŒòThat works for most situations except when a probe/BPF attached to the
syscall tracepoint sets an invalid syscall number e.g. -1 and also modifies
the result register. So this variant will obviously overwrite the modified
result with -ENOSYS.”…””}”(hj‘  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KehjF  h²hubhÌ)”}”(hŒ“syscall_enter_from_user_mode_randomize_stack() first invokes
enter_from_user_mode_randomize_stack() which establishes state in the
following order:”h]”hŒ“syscall_enter_from_user_mode_randomize_stack() first invokes
enter_from_user_mode_randomize_stack() which establishes state in the
following order:”…””}”(hjŸ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KjhjF  h²hubhÜ)”}”(hŒI* Lockdep
* RCU / Context tracking
* Tracing
* Apply stack randomization
”h]”hâ)”}”(hhh]”(hç)”}”(hŒLockdep”h]”hÌ)”}”(hj¶  h]”hŒLockdep”…””}”(hj¸  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Knhj´  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj±  ubhç)”}”(hŒRCU / Context tracking”h]”hÌ)”}”(hjÍ  h]”hŒRCU / Context tracking”…””}”(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ŒTracing”h]”hÌ)”}”(hjä  h]”hŒTracing”…””}”(hjæ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Kphjâ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj±  ubhç)”}”(hŒApply stack randomization
”h]”hÌ)”}”(hŒApply stack randomization”h]”hŒApply stack randomization”…””}”(hjý  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Kqhjù  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj±  ubeh}”(h]”h ]”h"]”h$]”h&]”jb  jc  uh1háh³hÊh´Knhj­  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛh³hÊh´KnhjF  h²hubhÌ)”}”(hX  and then invokes the various entry work functions like ptrace, seccomp, audit,
syscall tracing, etc. After all that is done, the instrumentable invoke_syscall
function can be invoked. The instrumentable code section then ends, after which
syscall_exit_to_user_mode() is invoked.”h]”hX  and then invokes the various entry work functions like ptrace, seccomp, audit,
syscall tracing, etc. After all that is done, the instrumentable invoke_syscall
function can be invoked. The instrumentable code section then ends, after which
syscall_exit_to_user_mode() is invoked.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KshjF  h²hubhÌ)”}”(hŒøsyscall_exit_to_user_mode() handles all work which needs to be done before
returning to user space like tracing, audit, signals, task work etc. After
that it invokes exit_to_user_mode() which again handles the state
transition in the reverse order:”h]”hŒøsyscall_exit_to_user_mode() handles all work which needs to be done before
returning to user space like tracing, audit, signals, task work etc. After
that it invokes exit_to_user_mode() which again handles the state
transition in the reverse order:”…””}”(hj+  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KxhjF  h²hubhÜ)”}”(hŒ-* Tracing
* RCU / Context tracking
* Lockdep
”h]”hâ)”}”(hhh]”(hç)”}”(hŒTracing”h]”hÌ)”}”(hjB  h]”hŒTracing”…””}”(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ŒRCU / Context tracking”h]”hÌ)”}”(hjY  h]”hŒRCU / Context tracking”…””}”(hj[  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K~hjW  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj=  ubhç)”}”(hŒLockdep
”h]”hÌ)”}”(hŒLockdep”h]”hŒLockdep”…””}”(hjr  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khjn  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj=  ubeh}”(h]”h ]”h"]”h$]”h&]”jb  jc  uh1háh³hÊh´K}hj9  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛh³hÊh´K}hjF  h²hubhÌ)”}”(hXg  syscall_enter_from_user_mode_randomize_stack() and
syscall_exit_to_user_mode() are also available as fine grained subfunctions
in cases where the architecture code has to do extra work between the
various steps. In such cases it has to ensure that
enter_from_user_mode_randomize_stack() is called first on entry and
exit_to_user_mode() is called last on exit.”h]”hXg  syscall_enter_from_user_mode_randomize_stack() and
syscall_exit_to_user_mode() are also available as fine grained subfunctions
in cases where the architecture code has to do extra work between the
various steps. In such cases it has to ensure that
enter_from_user_mode_randomize_stack() is called first on entry and
exit_to_user_mode() is called last on exit.”…””}”(hj’  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KhjF  h²hubhÌ)”}”(hŒ`Do not nest syscalls. Nested syscalls will cause RCU and/or context tracking
to print a warning.”h]”hŒ`Do not nest syscalls. Nested syscalls will cause RCU and/or context tracking
to print a warning.”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KˆhjF  h²hubeh}”(h]”j…  ah ]”h"]”Œsyscalls”ah$]”h&]”uh1hµhh·h²hh³hÊh´K;Œ
referenced”Kubh¶)”}”(hhh]”(h»)”}”(hŒKVM”h]”hŒKVM”…””}”(hj¹  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj¶  h²hh³hÊh´KŒubhÌ)”}”(hŒºEntering or exiting guest mode is very similar to syscalls. From the host
kernel point of view the CPU goes off into user space when entering the
guest and returns to the kernel on exit.”h]”hŒºEntering or exiting guest mode is very similar to syscalls. From the host
kernel point of view the CPU goes off into user space when entering the
guest and returns to the kernel on exit.”…””}”(hjÇ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KŽhj¶  h²hubhÌ)”}”(hŒÄguest_state_enter_irqoff() is a KVM-specific variant of exit_to_user_mode()
and guest_state_exit_irqoff() is the KVM variant of enter_from_user_mode().
The state operations have the same ordering.”h]”hŒÄguest_state_enter_irqoff() is a KVM-specific variant of exit_to_user_mode()
and guest_state_exit_irqoff() is the KVM variant of enter_from_user_mode().
The state operations have the same ordering.”…””}”(hjÕ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K’hj¶  h²hubhÌ)”}”(hŒºTask work handling is done separately for guest at the boundary of the
vcpu_run() loop via xfer_to_guest_mode_handle_work() which is a subset of
the work handled on return to user space.”h]”hŒºTask work handling is done separately for guest at the boundary of the
vcpu_run() loop via xfer_to_guest_mode_handle_work() which is a subset of
the work handled on return to user space.”…””}”(hjã  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K–hj¶  h²hubhÌ)”}”(hŒGDo not nest KVM entry/exit transitions because doing so is nonsensical.”h]”hŒGDo not nest KVM entry/exit transitions because doing so is nonsensical.”…””}”(hjñ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Kšhj¶  h²hubeh}”(h]”j›  ah ]”h"]”Œkvm”ah$]”h&]”uh1hµhh·h²hh³hÊh´KŒjµ  Kubh¶)”}”(hhh]”(h»)”}”(hŒ!Interrupts and regular exceptions”h]”hŒ!Interrupts and regular exceptions”…””}”(hj	  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj  h²hh³hÊh´KubhÌ)”}”(hŒ^Interrupts entry and exit handling is slightly more complex than syscalls
and KVM transitions.”h]”hŒ^Interrupts entry and exit handling is slightly more complex than syscalls
and KVM transitions.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KŸhj  h²hubhÌ)”}”(hŒ€If an interrupt is raised while the CPU executes in user space, the entry
and exit handling is exactly the same as for syscalls.”h]”hŒ€If an interrupt is raised while the CPU executes in user space, the entry
and exit handling is exactly the same as for syscalls.”…””}”(hj%  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K¢hj  h²hubhÌ)”}”(hX3  If the interrupt is raised while the CPU executes in kernel space the entry and
exit handling is slightly different. RCU state is only updated when the
interrupt is raised in the context of the CPU's idle task. Otherwise, RCU will
already be watching. Lockdep and tracing have to be updated unconditionally.”h]”hX5  If the interrupt is raised while the CPU executes in kernel space the entry and
exit handling is slightly different. RCU state is only updated when the
interrupt is raised in the context of the CPUâ€™s idle task. Otherwise, RCU will
already be watching. Lockdep and tracing have to be updated unconditionally.”…””}”(hj3  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K¥hj  h²hubhÌ)”}”(hŒIirqentry_enter() and irqentry_exit() provide the implementation for this.”h]”hŒIirqentry_enter() and irqentry_exit() provide the implementation for this.”…””}”(hjA  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Kªhj  h²hubhÌ)”}”(hŒAThe architecture-specific part looks similar to syscall handling:”h]”hŒAThe architecture-specific part looks similar to syscall handling:”…””}”(hjO  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K¬hj  h²hubjþ  )”}”(hX1  noinstr void interrupt(struct pt_regs *regs, int nr)
{
      arch_interrupt_enter(regs);
      state = irqentry_enter(regs);

      instrumentation_begin();

      irq_enter_rcu();
      invoke_irq_handler(regs, nr);
      irq_exit_rcu();

      instrumentation_end();

      irqentry_exit(regs, state);
}”h]”hX1  noinstr void interrupt(struct pt_regs *regs, int nr)
{
      arch_interrupt_enter(regs);
      state = irqentry_enter(regs);

      instrumentation_begin();

      irq_enter_rcu();
      invoke_irq_handler(regs, nr);
      irq_exit_rcu();

      instrumentation_end();

      irqentry_exit(regs, state);
}”…””}”hj]  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j  j  j  }”uh1jý  h³hÊh´K®hj  h²hubhÌ)”}”(hŒmNote that the invocation of the actual interrupt handler is within a
irq_enter_rcu() and irq_exit_rcu() pair.”h]”hŒmNote that the invocation of the actual interrupt handler is within a
irq_enter_rcu() and irq_exit_rcu() pair.”…””}”(hjl  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÀhj  h²hubhÌ)”}”(hŒæirq_enter_rcu() updates the preemption count which makes in_hardirq()
return true, handles NOHZ tick state and interrupt time accounting. This
means that up to the point where irq_enter_rcu() is invoked in_hardirq()
returns false.”h]”hŒæirq_enter_rcu() updates the preemption count which makes in_hardirq()
return true, handles NOHZ tick state and interrupt time accounting. This
means that up to the point where irq_enter_rcu() is invoked in_hardirq()
returns false.”…””}”(hjz  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÃhj  h²hubhÌ)”}”(hŒirq_exit_rcu() handles interrupt time accounting, undoes the preemption
count update and eventually handles soft interrupts and NOHZ tick state.”h]”hŒirq_exit_rcu() handles interrupt time accounting, undoes the preemption
count update and eventually handles soft interrupts and NOHZ tick state.”…””}”(hjˆ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÈhj  h²hubhÌ)”}”(hXÃ  In theory, the preemption count could be updated in irqentry_enter(). In
practice, deferring this update to irq_enter_rcu() allows the preemption-count
code to be traced, while also maintaining symmetry with irq_exit_rcu() and
irqentry_exit(), which are described in the next paragraph. The only downside
is that the early entry code up to irq_enter_rcu() must be aware that the
preemption count has not yet been updated with the HARDIRQ_OFFSET state.”h]”hXÃ  In theory, the preemption count could be updated in irqentry_enter(). In
practice, deferring this update to irq_enter_rcu() allows the preemption-count
code to be traced, while also maintaining symmetry with irq_exit_rcu() and
irqentry_exit(), which are described in the next paragraph. The only downside
is that the early entry code up to irq_enter_rcu() must be aware that the
preemption count has not yet been updated with the HARDIRQ_OFFSET state.”…””}”(hj–  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KËhj  h²hubhÌ)”}”(hX9  Note that irq_exit_rcu() must remove HARDIRQ_OFFSET from the preemption count
before it handles soft interrupts, whose handlers must run in BH context rather
than irq-disabled context. In addition, irqentry_exit() might schedule, which
also requires that HARDIRQ_OFFSET has been removed from the preemption count.”h]”hX9  Note that irq_exit_rcu() must remove HARDIRQ_OFFSET from the preemption count
before it handles soft interrupts, whose handlers must run in BH context rather
than irq-disabled context. In addition, irqentry_exit() might schedule, which
also requires that HARDIRQ_OFFSET has been removed from the preemption count.”…””}”(hj¤  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÒhj  h²hubhÌ)”}”(hXW  Even though interrupt handlers are expected to run with local interrupts
disabled, interrupt nesting is common from an entry/exit perspective. For
example, softirq handling happens within an irqentry_{enter,exit}() block with
local interrupts enabled. Also, although uncommon, nothing prevents an
interrupt handler from re-enabling interrupts.”h]”hXW  Even though interrupt handlers are expected to run with local interrupts
disabled, interrupt nesting is common from an entry/exit perspective. For
example, softirq handling happens within an irqentry_{enter,exit}() block with
local interrupts enabled. Also, although uncommon, nothing prevents an
interrupt handler from re-enabling interrupts.”…””}”(hj²  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K×hj  h²hubhÌ)”}”(hŒÇInterrupt entry/exit code doesn't strictly need to handle reentrancy, since it
runs with local interrupts disabled. But NMIs can happen anytime, and a lot of
the entry code is shared between the two.”h]”hŒÉInterrupt entry/exit code doesnâ€™t strictly need to handle reentrancy, since it
runs with local interrupts disabled. But NMIs can happen anytime, and a lot of
the entry code is shared between the two.”…””}”(hjÀ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÝhj  h²hubeh}”(h]”j°  ah ]”h"]”Œ!interrupts and regular exceptions”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kjµ  Kubh¶)”}”(hhh]”(h»)”}”(hŒNMI and NMI-like exceptions”h]”hŒNMI and NMI-like exceptions”…””}”(hjØ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjÕ  h²hh³hÊh´KâubhÌ)”}”(hŒ’NMIs and NMI-like exceptions (machine checks, double faults, debug
interrupts, etc.) can hit any context and must be extra careful with
the state.”h]”hŒ’NMIs and NMI-like exceptions (machine checks, double faults, debug
interrupts, etc.) can hit any context and must be extra careful with
the state.”…””}”(hjæ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KähjÕ  h²hubhÌ)”}”(hX  State changes for debug exceptions and machine-check exceptions depend on
whether these exceptions happened in user-space (breakpoints or watchpoints) or
in kernel mode (code patching). From user-space, they are treated like
interrupts, while from kernel mode they are treated like NMIs.”h]”hX  State changes for debug exceptions and machine-check exceptions depend on
whether these exceptions happened in user-space (breakpoints or watchpoints) or
in kernel mode (code patching). From user-space, they are treated like
interrupts, while from kernel mode they are treated like NMIs.”…””}”(hjô  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KèhjÕ  h²hubhÌ)”}”(hŒ|NMIs and other NMI-like exceptions handle state transitions without
distinguishing between user-mode and kernel-mode origin.”h]”hŒ|NMIs and other NMI-like exceptions handle state transitions without
distinguishing between user-mode and kernel-mode origin.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KíhjÕ  h²hubhÌ)”}”(hŒhThe state update on entry is handled in irqentry_nmi_enter() which updates
state in the following order:”h]”hŒhThe state update on entry is handled in irqentry_nmi_enter() which updates
state in the following order:”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KðhjÕ  h²hubhÜ)”}”(hŒB* Preemption counter
* Lockdep
* RCU / Context tracking
* Tracing
”h]”hâ)”}”(hhh]”(hç)”}”(hŒPreemption counter”h]”hÌ)”}”(hj'  h]”hŒPreemption counter”…””}”(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ŒLockdep”h]”hÌ)”}”(hj>  h]”hŒLockdep”…””}”(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ŒRCU / Context tracking”h]”hÌ)”}”(hjU  h]”hŒRCU / Context tracking”…””}”(hjW  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KõhjS  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj"  ubhç)”}”(hŒTracing
”h]”hÌ)”}”(hŒTracing”h]”hŒTracing”…””}”(hjn  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Köhjj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj"  ubeh}”(h]”h ]”h"]”h$]”h&]”jb  jc  uh1háh³hÊh´Kóhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛh³hÊh´KóhjÕ  h²hubhÌ)”}”(hŒYThe exit counterpart irqentry_nmi_exit() does the reverse operation in the
reverse order.”h]”hŒYThe exit counterpart irqentry_nmi_exit() does the reverse operation in the
reverse order.”…””}”(hjŽ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KøhjÕ  h²hubhÌ)”}”(hX  Note that the update of the preemption counter has to be the first
operation on enter and the last operation on exit. The reason is that both
lockdep and RCU rely on in_nmi() returning true in this case. The
preemption count modification in the NMI entry/exit case must not be
traced.”h]”hX  Note that the update of the preemption counter has to be the first
operation on enter and the last operation on exit. The reason is that both
lockdep and RCU rely on in_nmi() returning true in this case. The
preemption count modification in the NMI entry/exit case must not be
traced.”…””}”(hjœ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KûhjÕ  h²hubhÌ)”}”(hŒ+Architecture-specific code looks like this:”h]”hŒ+Architecture-specific code looks like this:”…””}”(hjª  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´MhjÕ  h²hubjþ  )”}”(hŒänoinstr void nmi(struct pt_regs *regs)
{
      arch_nmi_enter(regs);
      state = irqentry_nmi_enter(regs);

      instrumentation_begin();
      nmi_handler(regs);
      instrumentation_end();

      irqentry_nmi_exit(regs);
}”h]”hŒänoinstr void nmi(struct pt_regs *regs)
{
      arch_nmi_enter(regs);
      state = irqentry_nmi_enter(regs);

      instrumentation_begin();
      nmi_handler(regs);
      instrumentation_end();

      irqentry_nmi_exit(regs);
}”…””}”hj¸  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j  j  j  }”uh1jý  h³hÊh´MhjÕ  h²hubhÌ)”}”(hŒ5and for e.g. a debug exception it can look like this:”h]”hŒ5and for e.g. a debug exception it can look like this:”…””}”(hjÇ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´MhjÕ  h²hubjþ  )”}”(hXh  noinstr void debug(struct pt_regs *regs)
{
      arch_nmi_enter(regs);

      debug_regs = save_debug_regs();

      if (user_mode(regs)) {
              state = irqentry_enter(regs);

              instrumentation_begin();
              user_mode_debug_handler(regs, debug_regs);
              instrumentation_end();

              irqentry_exit(regs, state);
      } else {
              state = irqentry_nmi_enter(regs);

              instrumentation_begin();
              kernel_mode_debug_handler(regs, debug_regs);
              instrumentation_end();

              irqentry_nmi_exit(regs, state);
      }
}”h]”hXh  noinstr void debug(struct pt_regs *regs)
{
      arch_nmi_enter(regs);

      debug_regs = save_debug_regs();

      if (user_mode(regs)) {
              state = irqentry_enter(regs);

              instrumentation_begin();
              user_mode_debug_handler(regs, debug_regs);
              instrumentation_end();

              irqentry_exit(regs, state);
      } else {
              state = irqentry_nmi_enter(regs);

              instrumentation_begin();
              kernel_mode_debug_handler(regs, debug_regs);
              instrumentation_end();

              irqentry_nmi_exit(regs, state);
      }
}”…””}”hjÕ  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j  j  j  }”uh1jý  h³hÊh´MhjÕ  h²hubhÌ)”}”(hŒ}There is no combined irqentry_nmi_if_kernel() function available as the
above cannot be handled in an exception-agnostic way.”h]”hŒ}There is no combined irqentry_nmi_if_kernel() function available as the
above cannot be handled in an exception-agnostic way.”…””}”(hjä  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´M.hjÕ  h²hubhÌ)”}”(hŒ³NMIs can happen in any context. For example, an NMI-like exception triggered
while handling an NMI. So NMI entry code has to be reentrant and state updates
need to handle nesting.”h]”hŒ³NMIs can happen in any context. For example, an NMI-like exception triggered
while handling an NMI. So NMI entry code has to be reentrant and state updates
need to handle nesting.”…””}”(hjò  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´M1hjÕ  h²hubeh}”(h]”jÅ  ah ]”h"]”Œnmi and nmi-like exceptions”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kâjµ  Kubeh}”(h]”Œ>entry-exit-handling-for-exceptions-interrupts-syscalls-and-kvm”ah ]”h"]”Œ@entry/exit handling for exceptions, interrupts, syscalls and kvm”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”j2  Œ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”}”(Œsyscalls”]”jt  aŒkvm”]”j‹  aŒ!interrupts and regular exceptions”]”j   aŒnmi and nmi-like exceptions”]”jµ  auŒrefids”}”Œnameids”}”(j  j	  jC  j@  j²  j…  j  j›  jÒ  j°  j  jÅ  uŒ	nametypes”}”(j  ‰jC  ‰j²  ‰j  ‰jÒ  ‰j  ‰uh}”(j	  h·j@  jÐ  j…  jF  j›  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.