@@ -24,6 +24,97 @@ Quick access to CPU number, node ID
2424Allows to implement per CPU data efficiently. Documentation is in code and
2525selftests. :(
2626
27+ Optimized RSEQ V2
28+ -----------------
29+
30+ On architectures which utilize the generic entry code and generic TIF bits
31+ the kernel supports runtime optimizations for RSEQ, which also enable
32+ enhanced features like scheduler time slice extensions.
33+
34+ To enable them a task has to register the RSEQ region with at least the
35+ length advertised by getauxval(AT_RSEQ_FEATURE_SIZE).
36+
37+ If existing binaries register with RSEQ_ORIG_SIZE (32 bytes), the kernel
38+ keeps the legacy low performance mode enabled to fulfil the expectations
39+ of existing users regarding the original RSEQ implementation behaviour.
40+
41+ The following table documents the ABI and behavioral guarantees of the
42+ legacy and the optimized V2 mode.
43+
44+ .. list-table :: RSEQ modes
45+ :header-rows: 1
46+
47+ * - Nr
48+ - What
49+
50+ - Legacy
51+ - Optimized V2
52+
53+ * - 1
54+ - The cpu_id_start, cpu_id, node_id and mm_cid fields (User mode read
55+ only)
56+ .. Legacy
57+ - Updated by the kernel unconditionally after each context switch and
58+ before signal delivery
59+ .. Optimized V2
60+ - Updated by the kernel if and only if they change, i.e. if the task
61+ is migrated or mm_cid changes
62+
63+ * - 2
64+ - The rseq_cs critical section field
65+ .. Legacy
66+ - Evaluated and handled unconditionally after each context switch and
67+ before signal delivery
68+ .. Optimized V2
69+ - Evaluated and handled conditionally only when user space was
70+ interrupted and was scheduled out or before delivering a signal in
71+ the interrupted context.
72+
73+ * - 3
74+ - Read only fields
75+ .. Legacy
76+ - No strict enforcement except in debug mode
77+ .. Optimized V2
78+ - Strict enforcement
79+
80+ * - 4
81+ - membarrier(...RSEQ)
82+ .. Legacy
83+ - All running threads of the process are interrupted and the ID fields
84+ are rewritten and eventually active critical sections are aborted
85+ before they return to user space. All threads which are scheduled
86+ out whether voluntary or not are covered by #1/#2 above.
87+ .. Optimized V2
88+ - All running threads of the process are interrupted and eventually
89+ active critical sections are aborted before these threads return to
90+ user space. The ID fields are only updated if changed as a
91+ consequence of the interrupt. All threads which are scheduled out
92+ whether voluntary or not are covered by #1/#2 above.
93+
94+ * - 5
95+ - Time slice extensions
96+ .. Legacy
97+ - Not supported
98+ .. Optimized V2
99+ - Supported
100+
101+ The legacy mode is obviously less performant as it does unconditional
102+ updates and critical section checks even if not strictly required by the
103+ ABI contract. That can't be changed anymore as some users depend on that
104+ observed behavior, which in turn enables them to violate the ABI and
105+ overwrite the cpu_id_start field for their own purposes. This is obviously
106+ discouraged as it renders RSEQ incompatible with the intended usage and
107+ breaks the expectation of other libraries in the same application.
108+
109+ The ABI compliant optimized v2 mode, which respects the read only fields,
110+ does not require unconditional updates and therefore is way more
111+ performant. The kernel validates the read only fields for compliance. If
112+ user space modifies them, the process is killed. Compliant usage allows
113+ multiple libraries in the same application to benefit from the RSEQ
114+ functionality without disturbing each other. The ABI compliant optimized v2
115+ mode also enables extended RSEQ features like time slice extensions.
116+
117+
27118Scheduler time slice extensions
28119-------------------------------
29120
@@ -37,7 +128,8 @@ The prerequisites for this functionality are:
37128
38129 * Enabled at boot time (default is enabled)
39130
40- * A rseq userspace pointer has been registered for the thread
131+ * A rseq userspace pointer has been registered for the thread in
132+ optimized V2 mode
41133
42134The thread has to enable the functionality via prctl(2)::
43135
0 commit comments