2 files changed, 37 insertions, 34 deletions

diff --git a/include/uapi/linux/rseq.h b/include/uapi/linux/rseq.h
index 519ad6e176d1..bf4188c13bec 100644
--- a/include/uapi/linux/rseq.h
+++ b/include/uapi/linux/rseq.h
@@ -67,28 +67,30 @@ struct rseq_cs {
 struct rseq {
         /*
          * Restartable sequences cpu_id_start field. Updated by the
-         * kernel, and read by user-space with single-copy atomicity
-         * semantics. Aligned on 32-bit. Always contains a value in the
-         * range of possible CPUs, although the value may not be the
-         * actual current CPU (e.g. if rseq is not initialized). This
-         * CPU number value should always be compared against the value
-         * of the cpu_id field before performing a rseq commit or
-         * returning a value read from a data structure indexed using
-         * the cpu_id_start value.
+         * kernel. Read by user-space with single-copy atomicity
+         * semantics. This field should only be read by the thread which
+         * registered this data structure. Aligned on 32-bit. Always
+         * contains a value in the range of possible CPUs, although the
+         * value may not be the actual current CPU (e.g. if rseq is not
+         * initialized). This CPU number value should always be compared
+         * against the value of the cpu_id field before performing a rseq
+         * commit or returning a value read from a data structure indexed
+         * using the cpu_id_start value.
          */
         __u32 cpu_id_start;
         /*
-         * Restartable sequences cpu_id field. Updated by the kernel,
-         * and read by user-space with single-copy atomicity semantics.
-         * Aligned on 32-bit. Values RSEQ_CPU_ID_UNINITIALIZED and
-         * RSEQ_CPU_ID_REGISTRATION_FAILED have a special semantic: the
-         * former means "rseq uninitialized", and latter means "rseq
-         * initialization failed". This value is meant to be read within
-         * rseq critical sections and compared with the cpu_id_start
-         * value previously read, before performing the commit instruction,
-         * or read and compared with the cpu_id_start value before returning
-         * a value loaded from a data structure indexed using the
-         * cpu_id_start value.
+         * Restartable sequences cpu_id field. Updated by the kernel.
+         * Read by user-space with single-copy atomicity semantics. This
+         * field should only be read by the thread which registered this
+         * data structure. Aligned on 32-bit. Values
+         * RSEQ_CPU_ID_UNINITIALIZED and RSEQ_CPU_ID_REGISTRATION_FAILED
+         * have a special semantic: the former means "rseq uninitialized",
+         * and latter means "rseq initialization failed". This value is
+         * meant to be read within rseq critical sections and compared
+         * with the cpu_id_start value previously read, before performing
+         * the commit instruction, or read and compared with the
+         * cpu_id_start value before returning a value loaded from a data
+         * structure indexed using the cpu_id_start value.
          */
         __u32 cpu_id;
         /*
@@ -105,27 +107,28 @@ struct rseq {
          * targeted by the rseq_cs. Also needs to be set to NULL by user-space
          * before reclaiming memory that contains the targeted struct rseq_cs.
          *
-         * Read and set by the kernel with single-copy atomicity semantics.
-         * Set by user-space with single-copy atomicity semantics. Aligned
-         * on 64-bit.
+         * Read and set by the kernel. Set by user-space with single-copy
+         * atomicity semantics. This field should only be updated by the
+         * thread which registered this data structure. Aligned on 64-bit.
          */
         LINUX_FIELD_u32_u64(rseq_cs);
         /*
-         * - RSEQ_DISABLE flag:
+         * Restartable sequences flags field.
+         *
+         * This field should only be updated by the thread which
+         * registered this data structure. Read by the kernel.
+         * Mainly used for single-stepping through rseq critical sections
+         * with debuggers.
          *
-         * Fallback fast-track flag for single-stepping.
-         * Set by user-space if lack of progress is detected.
-         * Cleared by user-space after rseq finish.
-         * Read by the kernel.
          * - RSEQ_CS_FLAG_NO_RESTART_ON_PREEMPT
-         *     Inhibit instruction sequence block restart and event
-         *     counter increment on preemption for this thread.
+         *     Inhibit instruction sequence block restart on preemption
+         *     for this thread.
          * - RSEQ_CS_FLAG_NO_RESTART_ON_SIGNAL
-         *     Inhibit instruction sequence block restart and event
-         *     counter increment on signal delivery for this thread.
+         *     Inhibit instruction sequence block restart on signal
+         *     delivery for this thread.
          * - RSEQ_CS_FLAG_NO_RESTART_ON_MIGRATE
-         *     Inhibit instruction sequence block restart and event
-         *     counter increment on migration for this thread.
+         *     Inhibit instruction sequence block restart on migration for
+         *     this thread.
          */
         __u32 flags;
 } __attribute__((aligned(4 * sizeof(__u64))));
diff --git a/kernel/rseq.c b/kernel/rseq.c
index 2c8463acb50d..2a7748675be7 100644
--- a/kernel/rseq.c
+++ b/kernel/rseq.c
@@ -201,7 +201,7 @@ static int clear_rseq_cs(struct task_struct *t)
          * of code outside of the rseq assembly block. This performs
          * a lazy clear of the rseq_cs field.
          *
-         * Set rseq_cs to NULL with single-copy atomicity.
+         * Set rseq_cs to NULL.
          */
         return put_user(0UL, &t->rseq->rseq_cs);
 }