[PATCH rcu 0/5] Documentation updates for v6.8

[PATCH rcu 0/5] Documentation updates for v6.8

[Neeraj Upadhyay (AMD)]

Hello,

This series contains documentation updates:

1.      Documentation: RCU: Remove repeated word in comments, courtesy
        of Charles Han.

2.      rculist.h: docs: Fix wrong function summary, courtesy of Philipp
        Stanner.

3.      Clarify RCU Tasks reader/updater checklist.

4.      Mention address and data dependencies in rcu_dereference.rst.

5.      Clarify historical disclaimers in memory-barriers.txt.


Thanks
Neeraj

------------------------------------------------------------------------

 Documentation/RCU/checklist.rst       |   25 ++++++++++++++++---------
 Documentation/RCU/rcu_dereference.rst |   27 ++++++++++++++++++++-------
 Documentation/RCU/torture.rst         |    2 +-
 Documentation/memory-barriers.txt     |   17 ++++++++++-------
 include/linux/rculist.h               |    2 +-
 5 files changed, 48 insertions(+), 25 deletions(-)

[PATCH rcu 1/5] Documentation: RCU: Remove repeated word in comments

[Neeraj Upadhyay (AMD)]

From: Charles Han <hanchunchao@inspur.com>

Remove the repeated word "of" in comments.

Signed-off-by: Charles Han <hanchunchao@inspur.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>
---
 Documentation/RCU/torture.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/RCU/torture.rst b/Documentation/RCU/torture.rst
index b3b6dfa85248..49e7beea6ae1 100644
--- a/Documentation/RCU/torture.rst
+++ b/Documentation/RCU/torture.rst
@@ -185,7 +185,7 @@ argument.
 Not all changes require that all scenarios be run.  For example, a change
 to Tree SRCU might run only the SRCU-N and SRCU-P scenarios using the
 --configs argument to kvm.sh as follows:  "--configs 'SRCU-N SRCU-P'".
-Large systems can run multiple copies of of the full set of scenarios,
+Large systems can run multiple copies of the full set of scenarios,
 for example, a system with 448 hardware threads can run five instances
 of the full set concurrently.  To make this happen::
 
-- 
2.40.1

[PATCH rcu 2/5] rculist.h: docs: Fix wrong function summary

[Neeraj Upadhyay (AMD)]

From: Philipp Stanner <pstanner@redhat.com>

The brief summary in the docstring for function list_next_or_null_rcu()
states that the function is supposed to provide the "first" member of a
list, whereas in truth it returns the next member.

Change the docstring so it describes what the function actually does.

Signed-off-by: Philipp Stanner <pstanner@redhat.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>
---
 include/linux/rculist.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/rculist.h b/include/linux/rculist.h
index d29740be4833..3dc1e58865f7 100644
--- a/include/linux/rculist.h
+++ b/include/linux/rculist.h
@@ -355,7 +355,7 @@ static inline void list_splice_tail_init_rcu(struct list_head *list,
 })
 
 /**
- * list_next_or_null_rcu - get the first element from a list
+ * list_next_or_null_rcu - get the next element from a list
  * @head:	the head for the list.
  * @ptr:        the list head to take the next element from.
  * @type:       the type of the struct this is embedded in.
-- 
2.40.1

[PATCH rcu 3/5] doc: Clarify RCU Tasks reader/updater checklist

[Neeraj Upadhyay (AMD)]

From: "Paul E. McKenney" <paulmck@kernel.org>

Currently, the reader/updater compatibility rules for the three RCU
Tasks flavors are squished together in a single paragraph, which can
result in confusion.  This commit therefore splits them out into a list,
clearly showing the distinction between these flavors.

Link: https://lore.kernel.org/all/20231002211936.5948253e@gandalf.local.home/

Reported-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>
---
 Documentation/RCU/checklist.rst | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
index bd3c58c44bef..c432899aff22 100644
--- a/Documentation/RCU/checklist.rst
+++ b/Documentation/RCU/checklist.rst
@@ -241,15 +241,22 @@ over a rather long period of time, but improvements are always welcome!
 	srcu_struct.  The rules for the expedited RCU grace-period-wait
 	primitives are the same as for their non-expedited counterparts.
 
-	If the updater uses call_rcu_tasks() or synchronize_rcu_tasks(),
-	then the readers must refrain from executing voluntary
-	context switches, that is, from blocking.  If the updater uses
-	call_rcu_tasks_trace() or synchronize_rcu_tasks_trace(), then
-	the corresponding readers must use rcu_read_lock_trace() and
-	rcu_read_unlock_trace().  If an updater uses call_rcu_tasks_rude()
-	or synchronize_rcu_tasks_rude(), then the corresponding readers
-	must use anything that disables preemption, for example,
-	preempt_disable() and preempt_enable().
+	Similarly, it is necssary to correctly use the RCU Tasks flavors:
+
+	a.	If the updater uses synchronize_rcu_tasks() or
+		call_rcu_tasks(), then the readers must refrain from
+		executing voluntary context switches, that is, from
+		blocking.
+
+	b.	If the updater uses call_rcu_tasks_trace()
+		or synchronize_rcu_tasks_trace(), then the
+		corresponding readers must use rcu_read_lock_trace()
+		and rcu_read_unlock_trace().
+
+	c.	If an updater uses call_rcu_tasks_rude() or
+		synchronize_rcu_tasks_rude(), then the corresponding
+		readers must use anything that disables preemption,
+		for example, preempt_disable() and preempt_enable().
 
 	Mixing things up will result in confusion and broken kernels, and
 	has even resulted in an exploitable security issue.  Therefore,
-- 
2.40.1

Re: [PATCH rcu 3/5] doc: Clarify RCU Tasks reader/updater checklist

[Joel Fernandes]

> On Dec 12, 2023, at 12:27 PM, Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com> wrote:
> 
> From: "Paul E. McKenney" <paulmck@kernel.org>
> 
> Currently, the reader/updater compatibility rules for the three RCU
> Tasks flavors are squished together in a single paragraph, which can
> result in confusion.  This commit therefore splits them out into a list,
> clearly showing the distinction between these flavors.
> 
> Link: https://lore.kernel.org/all/20231002211936.5948253e@gandalf.local.home/
> 
> Reported-by: Steven Rostedt <rostedt@goodmis.org>
> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
> Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
> Signed-off-by: Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>
> ---
> Documentation/RCU/checklist.rst | 25 ++++++++++++++++---------
> 1 file changed, 16 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
> index bd3c58c44bef..c432899aff22 100644
> --- a/Documentation/RCU/checklist.rst
> +++ b/Documentation/RCU/checklist.rst
> @@ -241,15 +241,22 @@ over a rather long period of time, but improvements are always welcome!
>    srcu_struct.  The rules for the expedited RCU grace-period-wait
>    primitives are the same as for their non-expedited counterparts.
> 
> -    If the updater uses call_rcu_tasks() or synchronize_rcu_tasks(),
> -    then the readers must refrain from executing voluntary
> -    context switches, that is, from blocking.  If the updater uses
> -    call_rcu_tasks_trace() or synchronize_rcu_tasks_trace(), then
> -    the corresponding readers must use rcu_read_lock_trace() and
> -    rcu_read_unlock_trace().  If an updater uses call_rcu_tasks_rude()
> -    or synchronize_rcu_tasks_rude(), then the corresponding readers
> -    must use anything that disables preemption, for example,
> -    preempt_disable() and preempt_enable().
> +    Similarly, it is necssary to correctly use the RCU Tasks flavors:

Typo: necessary.

Probably no need to resend this one, just fix in the PR.

Thanks,

 - Joel




> +
> +    a.    If the updater uses synchronize_rcu_tasks() or
> +        call_rcu_tasks(), then the readers must refrain from
> +        executing voluntary context switches, that is, from
> +        blocking.
> +
> +    b.    If the updater uses call_rcu_tasks_trace()
> +        or synchronize_rcu_tasks_trace(), then the
> +        corresponding readers must use rcu_read_lock_trace()
> +        and rcu_read_unlock_trace().
> +
> +    c.    If an updater uses call_rcu_tasks_rude() or
> +        synchronize_rcu_tasks_rude(), then the corresponding
> +        readers must use anything that disables preemption,
> +        for example, preempt_disable() and preempt_enable().
> 
>    Mixing things up will result in confusion and broken kernels, and
>    has even resulted in an exploitable security issue.  Therefore,
> -- 
> 2.40.1
> 
> 

[PATCH rcu 4/5] doc: Mention address and data dependencies in rcu_dereference.rst

[Neeraj Upadhyay (AMD)]

From: "Paul E. McKenney" <paulmck@kernel.org>

This commit adds discussion of address and data dependencies to the
beginning of rcu_dereference.rst in order to enable readers to more
easily make the connection to the Linux-kernel memory model in general
and to memory-barriers.txt in particular.

Reported-by: Jonas Oberhauser <jonas.oberhauser@huaweicloud.com>
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>
---
 Documentation/RCU/rcu_dereference.rst | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
index 3b739f6243c8..659d5913784d 100644
--- a/Documentation/RCU/rcu_dereference.rst
+++ b/Documentation/RCU/rcu_dereference.rst
@@ -3,13 +3,26 @@
 PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()
 ===============================================================
 
-Most of the time, you can use values from rcu_dereference() or one of
-the similar primitives without worries.  Dereferencing (prefix "*"),
-field selection ("->"), assignment ("="), address-of ("&"), addition and
-subtraction of constants, and casts all work quite naturally and safely.
-
-It is nevertheless possible to get into trouble with other operations.
-Follow these rules to keep your RCU code working properly:
+Proper care and feeding of address and data dependencies is critically
+important to correct use of things like RCU.  To this end, the pointers
+returned from the rcu_dereference() family of primitives carry address and
+data dependencies.  These dependencies extend from the rcu_dereference()
+macro's load of the pointer to the later use of that pointer to compute
+either the address of a later memory access (representing an address
+dependency) or the value written by a later memory access (representing
+a data dependency).
+
+Most of the time, these dependencies are preserved, permitting you to
+freely use values from rcu_dereference().  For example, dereferencing
+(prefix "*"), field selection ("->"), assignment ("="), address-of
+("&"), casts, and addition or subtraction of constants all work quite
+naturally and safely.  However, because current compilers do not take
+either address or data dependencies into account it is still possible
+to get into trouble.
+
+Follow these rules to preserve the address and data dependencies emanating
+from your calls to rcu_dereference() and friends, thus keeping your RCU
+readers working properly:
 
 -	You must use one of the rcu_dereference() family of primitives
 	to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU
-- 
2.40.1

[PATCH rcu 5/5] doc: Clarify historical disclaimers in memory-barriers.txt

[Neeraj Upadhyay (AMD)]

From: "Paul E. McKenney" <paulmck@kernel.org>

This commit makes it clear that the reason that these sections are
historical is that smp_read_barrier_depends() is no more.  It also
removes the point about comparison operations, given that there are
other optimizations that can break address dependencies.

Suggested-by: Jonas Oberhauser <jonas.oberhauser@huaweicloud.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Cc: Alan Stern <stern@rowland.harvard.edu>
Cc: Andrea Parri <parri.andrea@gmail.com>
Cc: Will Deacon <will@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Boqun Feng <boqun.feng@gmail.com>
Cc: Nicholas Piggin <npiggin@gmail.com>
Cc: David Howells <dhowells@redhat.com>
Cc: Jade Alglave <j.alglave@ucl.ac.uk>
Cc: Luc Maranget <luc.maranget@inria.fr>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: Daniel Lustig <dlustig@nvidia.com>
Cc: Joel Fernandes <joel@joelfernandes.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: <linux-arch@vger.kernel.org>
Cc: <linux-doc@vger.kernel.org>
Signed-off-by: Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>
---
 Documentation/memory-barriers.txt | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index d414e145f912..4202174a6262 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -396,10 +396,11 @@ Memory barriers come in four basic varieties:
 
 
  (2) Address-dependency barriers (historical).
-     [!] This section is marked as HISTORICAL: For more up-to-date
-     information, including how compiler transformations related to pointer
-     comparisons can sometimes cause problems, see
-     Documentation/RCU/rcu_dereference.rst.
+     [!] This section is marked as HISTORICAL: it covers the long-obsolete
+     smp_read_barrier_depends() macro, the semantics of which are now
+     implicit in all marked accesses.  For more up-to-date information,
+     including how compiler transformations can sometimes break address
+     dependencies, see Documentation/RCU/rcu_dereference.rst.
 
      An address-dependency barrier is a weaker form of read barrier.  In the
      case where two loads are performed such that the second depends on the
@@ -560,9 +561,11 @@ There are certain things that the Linux kernel memory barriers do not guarantee:
 
 ADDRESS-DEPENDENCY BARRIERS (HISTORICAL)
 ----------------------------------------
-[!] This section is marked as HISTORICAL: For more up-to-date information,
-including how compiler transformations related to pointer comparisons can
-sometimes cause problems, see Documentation/RCU/rcu_dereference.rst.
+[!] This section is marked as HISTORICAL: it covers the long-obsolete
+smp_read_barrier_depends() macro, the semantics of which are now implicit
+in all marked accesses.  For more up-to-date information, including
+how compiler transformations can sometimes break address dependencies,
+see Documentation/RCU/rcu_dereference.rst.
 
 As of v4.15 of the Linux kernel, an smp_mb() was added to READ_ONCE() for
 DEC Alpha, which means that about the only people who need to pay attention
-- 
2.40.1