Documentation updates for v6.8
Subsystems (5)
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(-)
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
@@ -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
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
@@ -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
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
@@ -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
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
@@ -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
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.
--- Documentation/memory-barriers.txt | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-)
Documentation/memory-barriers.txt +10 -7
@@ -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
Re: [PATCH rcu 3/5] doc: Clarify RCU Tasks reader/updater checklist
In reply to Neeraj Upadhyay (AMD)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.
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(-)Documentation/RCU/checklist.rst +0
-0@@ -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