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(-)
From: Charles Han <[email protected]>
Remove the repeated word "of" in comments.
Signed-off-by: Charles Han <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
Signed-off-by: Neeraj Upadhyay (AMD) <[email protected]>
---
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
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.
Link: https://lore.kernel.org/all/[email protected]/
Reported-by: Steven Rostedt <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
Reviewed-by: Mathieu Desnoyers <[email protected]>
Reviewed-by: Steven Rostedt (Google) <[email protected]>
Signed-off-by: Neeraj Upadhyay (AMD) <[email protected]>
---
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
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.
Signed-off-by: Philipp Stanner <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
Signed-off-by: Neeraj Upadhyay (AMD) <[email protected]>
---
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
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.
Reported-by: Jonas Oberhauser <[email protected]>
Reported-by: Akira Yokosawa <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
Signed-off-by: Neeraj Upadhyay (AMD) <[email protected]>
---
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
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.
Suggested-by: Jonas Oberhauser <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
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]>
Cc: <[email protected]>
Cc: <[email protected]>
Signed-off-by: Neeraj Upadhyay (AMD) <[email protected]>
---
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
> On Dec 12, 2023, at 12:27 PM, Neeraj Upadhyay (AMD) <[email protected]> wrote:
>
> 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.
>
> Link: https://lore.kernel.org/all/[email protected]/
>
> Reported-by: Steven Rostedt <[email protected]>
> Signed-off-by: Paul E. McKenney <[email protected]>
> Reviewed-by: Mathieu Desnoyers <[email protected]>
> Reviewed-by: Steven Rostedt (Google) <[email protected]>
> Signed-off-by: Neeraj Upadhyay (AMD) <[email protected]>
> ---
> 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
>
>