Documentation/userspace-api/rseq.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/rseq.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/rseq.rst
Extension
.rst
Size
9300 bytes
Lines
233
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

=====================
Restartable Sequences
=====================

Restartable Sequences allow to register a per thread userspace memory area
to be used as an ABI between kernel and userspace for three purposes:

 * userspace restartable sequences

 * quick access to read the current CPU number, node ID from userspace

 * scheduler time slice extensions

Restartable sequences (per-cpu atomics)
---------------------------------------

Restartable sequences allow userspace to perform update operations on
per-cpu data without requiring heavyweight atomic operations. The actual
ABI is unfortunately only available in the code and selftests.

Quick access to CPU number, node ID
-----------------------------------

Allows to implement per CPU data efficiently. Documentation is in code and
selftests. :(

Optimized RSEQ V2
-----------------

On architectures which utilize the generic entry code and generic TIF bits
the kernel supports runtime optimizations for RSEQ, which also enable
enhanced features like scheduler time slice extensions.

To enable them a task has to register the RSEQ region with at least the
length advertised by getauxval(AT_RSEQ_FEATURE_SIZE).

If existing binaries register with RSEQ_ORIG_SIZE (32 bytes), the kernel
keeps the legacy low performance mode enabled to fulfil the expectations
of existing users regarding the original RSEQ implementation behaviour.

The following table documents the ABI and behavioral guarantees of the
legacy and the optimized V2 mode.

.. list-table:: RSEQ modes
   :header-rows: 1

   * - Nr
     - What

     - Legacy
     - Optimized V2

   * - 1
     - The cpu_id_start, cpu_id, node_id and mm_cid fields (User mode read
       only)
       .. Legacy
     - Updated by the kernel unconditionally after each context switch and
       before signal delivery
       .. Optimized V2
     - Updated by the kernel if and only if they change, i.e. if the task
       is migrated or mm_cid changes

   * - 2
     - The rseq_cs critical section field
       .. Legacy
     - Evaluated and handled unconditionally after each context switch and
       before signal delivery
       .. Optimized V2
     - Evaluated and handled conditionally only when user space was
       interrupted and was scheduled out or before delivering a signal in

Annotation

Implementation Notes