Documentation changes for 3.16
Subsystems (2)
cover Documentation changes for 3.16
Hello!
This series provides a few documentation updates:
1. Update sysfs patch for rcu_cpu_stall_suppress, courtesy of
Kirill Tkhai.
2. Add a rcu_dereference.txt file documenting the proper care
and feeding of rcu_dereference() return values.
3. Update the list of RCU API members in whatisRCU.txt.
Thanx, Paul
------------------------------------------------------------------------
00-INDEX | 2 checklist.txt | 12 + rcu_dereference.txt | 365 ++++++++++++++++++++++++++++++++++++++++++++++++++++ stallwarn.txt | 2 whatisRCU.txt | 55 ++++++- 5 files changed, 420 insertions(+), 16 deletions(-)
PATCH 2/3 documentation: Record rcu_dereference() value mishandling
In reply to Paul E. McKenneyFrom: "Paul E. McKenney" <[email protected]>
Recent LKML discussings (see http://lwn.net/Articles/586838/ and
http://lwn.net/Articles/588300/ for the LWN writeups) brought out some ways of misusing the return value from rcu_dereference() that are not necessarily completely intuitive. This commit therefore documents what can and cannot safely be done with these values.
--- Documentation/RCU/00-INDEX | 2 + Documentation/RCU/checklist.txt | 12 +- Documentation/RCU/rcu_dereference.txt | 365 ++++++++++++++++++++++++++++++++++ 3 files changed, 375 insertions(+), 4 deletions(-) create mode 100644 Documentation/RCU/rcu_dereference.txt
Documentation/RCU/00-INDEX +2 -0
@@ -12,6 +12,8 @@ lockdep-splat.txt - RCU Lockdep splats explained. NMI-RCU.txt - Using RCU to Protect Dynamic NMI Handlers +rcu_dereference.txt + - Proper care and feeding of return values from rcu_dereference() rcubarrier.txt - RCU and Unloadable Modules rculist_nulls.txt
Documentation/RCU/checklist.txt +8 -4
@@ -114,12 +114,16 @@ over a rather long period of time, but improvements are always welcome! http://www.openvms.compaq.com/wizard/wiz_2637.html The rcu_dereference() primitive is also an excellent - documentation aid, letting the person reading the code - know exactly which pointers are protected by RCU. + documentation aid, letting the person reading the + code know exactly which pointers are protected by RCU. Please note that compilers can also reorder code, and they are becoming increasingly aggressive about doing - just that. The rcu_dereference() primitive therefore - also prevents destructive compiler optimizations. + just that. The rcu_dereference() primitive therefore also + prevents destructive compiler optimizations. However, + with a bit of devious creativity, it is possible to + mishandle the return value from rcu_dereference(). + Please see rcu_dereference.txt in this directory for + more information. The rcu_dereference() primitive is used by the various "_rcu()" list-traversal primitives, such
Documentation/RCU/rcu_dereference.txt new file +365 -0
365 lines not on this page · raw message
Signature · 1 line
1.8.1.5
PATCH 3/3 documentation: Update API documentation
In reply to Paul E. McKenneyFrom: "Paul E. McKenney" <[email protected]>
This commit updates the list of RCU API members in whatisRCU.txt.
--- Documentation/RCU/whatisRCU.txt | 55 ++++++++++++++++++++++++++++++++--------- 1 file changed, 44 insertions(+), 11 deletions(-)
Documentation/RCU/whatisRCU.txt +44 -11
@@ -326,11 +326,11 @@ used as follows: a. synchronize_rcu() rcu_read_lock() / rcu_read_unlock() call_rcu() rcu_dereference() -b. call_rcu_bh() rcu_read_lock_bh() / rcu_read_unlock_bh() - rcu_dereference_bh() +b. synchronize_rcu_bh() rcu_read_lock_bh() / rcu_read_unlock_bh() + call_rcu_bh() rcu_dereference_bh() c. synchronize_sched() rcu_read_lock_sched() / rcu_read_unlock_sched() - preempt_disable() / preempt_enable() + call_rcu_sched() preempt_disable() / preempt_enable() local_irq_save() / local_irq_restore() hardirq enter / hardirq exit NMI enter / NMI exit
@@ -794,10 +794,22 @@ in docbook. Here is the list, by category. RCU list traversal: + list_entry_rcu + list_first_entry_rcu + list_next_rcu list_for_each_entry_rcu + list_for_each_entry_continue_rcu + hlist_first_rcu + hlist_next_rcu + hlist_pprev_rcu hlist_for_each_entry_rcu + hlist_for_each_entry_rcu_bh + hlist_for_each_entry_continue_rcu + hlist_for_each_entry_continue_rcu_bh + hlist_nulls_first_rcu hlist_nulls_for_each_entry_rcu - list_for_each_entry_continue_rcu + hlist_bl_first_rcu + hlist_bl_for_each_entry_rcu RCU pointer/list update:
@@ -806,28 +818,38 @@ RCU pointer/list update: list_add_tail_rcu list_del_rcu list_replace_rcu - hlist_del_rcu hlist_add_after_rcu hlist_add_before_rcu hlist_add_head_rcu + hlist_del_rcu + hlist_del_init_rcu hlist_replace_rcu list_splice_init_rcu() + hlist_nulls_del_init_rcu + hlist_nulls_del_rcu + hlist_nulls_add_head_rcu + hlist_bl_add_head_rcu + hlist_bl_del_init_rcu + hlist_bl_del_rcu + hlist_bl_set_first_rcu RCU: Critical sections Grace period Barrier rcu_read_lock synchronize_net rcu_barrier rcu_read_unlock synchronize_rcu rcu_dereference synchronize_rcu_expedited - call_rcu - kfree_rcu - + rcu_read_lock_held call_rcu + rcu_dereference_check kfree_rcu + rcu_dereference_protected bh: Critical sections Grace period Barrier rcu_read_lock_bh call_rcu_bh rcu_barrier_bh rcu_read_unlock_bh synchronize_rcu_bh rcu_dereference_bh synchronize_rcu_bh_expedited - + rcu_dereference_bh_check + rcu_dereference_bh_protected + rcu_read_lock_bh_held sched: Critical sections Grace period Barrier
@@ -835,7 +857,12 @@ sched: Critical sections Grace period Barrier rcu_read_unlock_sched call_rcu_sched [preempt_disable] synchronize_sched_expedited [and friends] + rcu_read_lock_sched_notrace + rcu_read_unlock_sched_notrace rcu_dereference_sched + rcu_dereference_sched_check + rcu_dereference_sched_protected + rcu_read_lock_sched_held SRCU: Critical sections Grace period Barrier
@@ -843,6 +870,8 @@ SRCU: Critical sections Grace period Barrier srcu_read_lock synchronize_srcu srcu_barrier srcu_read_unlock call_srcu srcu_dereference synchronize_srcu_expedited + srcu_dereference_check + srcu_read_lock_held SRCU: Initialization/cleanup init_srcu_struct
@@ -850,9 +879,13 @@ SRCU: Initialization/cleanup All: lockdep-checked RCU-protected pointer access - rcu_dereference_check - rcu_dereference_protected + rcu_access_index rcu_access_pointer + rcu_dereference_index_check + rcu_dereference_raw + rcu_lockdep_assert + rcu_sleep_check + RCU_NONIDLE See the comment headers in the source code (or the docbook generated from them) for more information.
Signature · 1 line
1.8.1.5
PATCH 1/3 documentation: Update sysfs path for rcu_cpu_stall_suppress
In reply to Paul E. McKenneyFrom: "Paul E. McKenney" <[email protected]>
Commit 6bfc09e2327d (rcu: Provide RCU CPU stall warnings for tiny RCU) moved the rcu_cpu_stall_suppress module parameter from rcutree.c to rcupdate.c, but failed to update Documentation/RCU/stallwarn.txt. This commit therefore repairs this omission.
--- Documentation/RCU/stallwarn.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/stallwarn.txt +1 -1
@@ -24,7 +24,7 @@ CONFIG_RCU_CPU_STALL_TIMEOUT timing of the next warning for the current stall. Stall-warning messages may be enabled and disabled completely via - /sys/module/rcutree/parameters/rcu_cpu_stall_suppress. + /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress. CONFIG_RCU_CPU_STALL_VERBOSE
Signature · 1 line
1.8.1.5
Quoted 11 lines · Paul E. McKenney
Hello!
This series provides a few documentation updates:
1. Update sysfs patch for
rcu_cpu_stall_suppress, courtesy of
Kirill Tkhai.2. Add a rcu_dereference.txt file documenting the proper care
and feeding ofrcu_dereference()return values.3. Update the list of RCU API members in whatisRCU.txt.
For all three: