Skip to contentSkip to conversation

Documentation updates for v6.8

PATCH In review Neeraj Upadhyay (AMD) 2 participants 7 messages Dec 12, 2023

Subsystems (5)
lore
Share & tools
lore
#0 lore raw

cover Documentation updates for v6.8

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(-)
#1 lore raw

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

From: Charles Han <[email protected]>

Remove the repeated word "of" in comments.

---
 Documentation/RCU/torture.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/torture.rst +1 -1
index b3b6dfa85248..49e7beea6ae1 100644
@@ -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::
 
Signature · 1 line
2.40.1
#2 lore raw

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

In reply to Neeraj Upadhyay (AMD)

From: Philipp Stanner <[email protected]>

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.

---
 include/linux/rculist.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/rculist.h +1 -1
index d29740be4833..3dc1e58865f7 100644
@@ -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.
Signature · 1 line
2.40.1
#3 lore raw

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

In reply to Neeraj Upadhyay (AMD)

From: "Paul E. McKenney" <[email protected]>

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.

---
 Documentation/RCU/checklist.rst | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)
Documentation/RCU/checklist.rst +16 -9
index bd3c58c44bef..c432899aff22 100644
@@ -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,
Signature · 1 line
2.40.1
#4 lore raw

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

Quoted 30 lines · Neeraj Upadhyay (AMD)

From: "Paul E. McKenney" <[email protected]>

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.

---
Documentation/RCU/checklist.rst | 25 ++++++++++++++++---------

1 file changed, 16 insertions(+), 9 deletions(-)
Documentation/RCU/checklist.rst +0 -0
index bd3c58c44bef..c432899aff22 100644
@@ -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.
 

Documentation/RCU/checklist.rst over a rather long period of time, but improvements are always welcome! · line 244

Quoted 10 lines
Documentation/RCU/checklist.rst +1 -9
-    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

Quoted 22 lines
Documentation/RCU/checklist.rst +15 -0
+
+    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,
Signature · 1 line
2.40.1
#5 lore raw

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

In reply to Neeraj Upadhyay (AMD)

From: "Paul E. McKenney" <[email protected]>

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.

---
 Documentation/RCU/rcu_dereference.rst | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)
Documentation/RCU/rcu_dereference.rst +20 -7
index 3b739f6243c8..659d5913784d 100644
@@ -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
Signature · 1 line
2.40.1
#6 lore raw

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

In reply to Neeraj Upadhyay (AMD)

From: "Paul E. McKenney" <[email protected]>

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.

Cc Alan Stern <[email protected]>
Cc Andrea Parri <[email protected]>
Cc Will Deacon <[email protected]>
Cc Peter Zijlstra <[email protected]>
Cc Boqun Feng <[email protected]>
Cc Nicholas Piggin <[email protected]>
Cc David Howells <[email protected]>
Cc Jade Alglave <[email protected]>
Cc Luc Maranget <[email protected]>
Cc Akira Yokosawa <[email protected]>
Cc Daniel Lustig <[email protected]>
Cc Joel Fernandes <[email protected]>
Cc Jonathan Corbet <[email protected]>
---
 Documentation/memory-barriers.txt | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)
Documentation/memory-barriers.txt +10 -7
index d414e145f912..4202174a6262 100644
@@ -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
Signature · 1 line
2.40.1