1 files changed, 81 insertions, 0 deletions
diff --git a/manual/threads.texi b/manual/threads.texi
index 06b6b277a1..ab44a92ca0 100644
--- a/manual/threads.texi
+++ b/manual/threads.texi
@@ -629,6 +629,8 @@ the standard.
 * Waiting with Explicit Clocks::          Functions for waiting with an
                                           explicit clock specification.
 * Single-Threaded::                       Detecting single-threaded execution.
+* Restartable Sequences::                 Linux-specific restartable sequences
+                                          integration.
 @end menu
 
 @node Default Thread Attributes
@@ -958,6 +960,85 @@ application-created thread because future versions of @theglibc{} may
 create background threads after the first thread has been created, and
 the application has no way of knowning that these threads are present.
 
+@node Restartable Sequences
+@subsubsection Restartable Sequences
+
+This section describes restartable sequences integration for
+@theglibc{}.  This functionality is only available on Linux.
+
+@deftp {Data Type} {struct rseq}
+@standards{Linux, sys/rseq.h}
+The type of the restartable sequences area.  Future versions
+of Linux may add additional fields to the end of this structure.
+
+
+Users need to obtain the address of the restartable sequences area using
+the thread pointer and the @code{__rseq_offset} variable, described
+below.
+
+One use of the restartable sequences area is to read the current CPU
+number from its @code{cpu_id} field, as an inline version of
+@code{sched_getcpu}.  @Theglibc{} sets the @code{cpu_id} field to
+@code{RSEQ_CPU_ID_REGISTRATION_FAILED} if registration failed or was
+explicitly disabled.
+
+Furthermore, users can store the address of a @code{struct rseq_cs}
+object into the @code{rseq_cs} field of @code{struct rseq}, thus
+informing the kernel that the thread enters a restartable sequence
+critical section.  This pointer and the code areas it itself points to
+must not be left pointing to memory areas which are freed or re-used.
+Several approaches can guarantee this.  If the application or library
+can guarantee that the memory used to hold the @code{struct rseq_cs} and
+the code areas it refers to are never freed or re-used, no special
+action must be taken.  Else, before that memory is re-used of freed, the
+application is responsible for setting the @code{rseq_cs} field to
+@code{NULL} in each thread's restartable sequence area to guarantee that
+it does not leak dangling references.  Because the application does not
+typically have knowledge of libraries' use of restartable sequences, it
+is recommended that libraries using restartable sequences which may end
+up freeing or re-using their memory set the @code{rseq_cs} field to
+@code{NULL} before returning from library functions which use
+restartable sequences.
+
+The manual for the @code{rseq} system call can be found
+at @uref{https://git.kernel.org/pub/scm/libs/librseq/librseq.git/tree/doc/man/rseq.2}.
+@end deftp
+
+@deftypevar {int} __rseq_offset
+@standards{Linux, sys/rseq.h}
+This variable contains the offset between the thread pointer (as defined
+by @code{__builtin_thread_pointer} or the thread pointer register for
+the architecture) and the restartable sequences area.  This value is the
+same for all threads in the process.  If the restartable sequences area
+is located at a lower address than the location to which the thread
+pointer points, the value is negative.
+@end deftypevar
+
+@deftypevar {unsigned int} __rseq_size
+@standards{Linux, sys/rseq.h}
+This variable is either zero (if restartable sequence registration
+failed or has been disabled) or the size of the restartable sequence
+registration.  This can be different from the size of @code{struct rseq}
+if the kernel has extended the size of the registration.  If
+registration is successful, @code{__rseq_size} is at least 32 (the
+initial size of @code{struct rseq}).
+@end deftypevar
+
+@deftypevar {unsigned int} __rseq_flags
+@standards{Linux, sys/rseq.h}
+The flags used during restartable sequence registration with the kernel.
+Currently zero.
+@end deftypevar
+
+@deftypevr Macro int RSEQ_SIG
+@standards{Linux, sys/rseq.h}
+Each supported architecture provides a @code{RSEQ_SIG} macro in
+@file{sys/rseq.h} which contains a signature.  That signature is
+expected to be present in the code before each restartable sequences
+abort handler.  Failure to provide the expected signature may terminate
+the process with a segmentation fault.
+@end deftypevr
+
 @c FIXME these are undocumented:
 @c pthread_atfork
 @c pthread_attr_destroy