Documentation/core-api/entry.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/entry.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/entry.rst
Extension
.rst
Size
9694 bytes
Lines
280
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

Entry/exit handling for exceptions, interrupts, syscalls and KVM
================================================================

All transitions between execution domains require state updates which are
subject to strict ordering constraints. State updates are required for the
following:

  * Lockdep
  * RCU / Context tracking
  * Preemption counter
  * Tracing
  * Time accounting

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`_.

Non-instrumentable code - noinstr
---------------------------------

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.

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:

.. code-block:: c

  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'
  }

This allows verification of the 'noinstr' restrictions via objtool on
supported architectures.

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.

All non-instrumentable entry/exit code sections before and after the RCU
state transitions must run with interrupts disabled.

Syscalls
--------

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. A typical syscall handling function
invoked from low-level assembly code looks like this:

.. code-block:: c

  noinstr void syscall(struct pt_regs *regs, int nr)
  {
	arch_syscall_enter(regs);

Annotation

Implementation Notes