Bring this file kicking and screaming into the year 2025!
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
---
Documentation/RCU/whatisRCU.rst | 150 +++++++++++++++++++++++++-------
1 file changed, 118 insertions(+), 32 deletions(-)
diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index be2eb6be16ece8..6c69c20086e147 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst
@@ -1021,32 +1021,41 @@ RCU list traversal::
list_entry_rcu
list_entry_lockless
list_first_entry_rcu
+ list_first_or_null_rcu
+ list_tail_rcu
list_next_rcu
+ list_next_or_null_rcu
list_for_each_entry_rcu
list_for_each_entry_continue_rcu
list_for_each_entry_from_rcu
- list_first_or_null_rcu
- list_next_or_null_rcu
+ list_for_each_entry_lockless
hlist_first_rcu
hlist_next_rcu
hlist_pprev_rcu
hlist_for_each_entry_rcu
+ hlist_for_each_entry_rcu_notrace
hlist_for_each_entry_rcu_bh
hlist_for_each_entry_from_rcu
hlist_for_each_entry_continue_rcu
hlist_for_each_entry_continue_rcu_bh
hlist_nulls_first_rcu
+ hlist_nulls_next_rcu
hlist_nulls_for_each_entry_rcu
+ hlist_nulls_for_each_entry_safe
hlist_bl_first_rcu
hlist_bl_for_each_entry_rcu
RCU pointer/list update::
rcu_assign_pointer
+ rcu_replace_pointer
+ INIT_LIST_HEAD_RCU
list_add_rcu
list_add_tail_rcu
list_del_rcu
list_replace_rcu
+ list_splice_init_rcu
+ list_splice_tail_init_rcu
hlist_add_behind_rcu
hlist_add_before_rcu
hlist_add_head_rcu
@@ -1054,34 +1063,53 @@ RCU pointer/list update::
hlist_del_rcu
hlist_del_init_rcu
hlist_replace_rcu
- list_splice_init_rcu
- list_splice_tail_init_rcu
hlist_nulls_del_init_rcu
hlist_nulls_del_rcu
hlist_nulls_add_head_rcu
+ hlist_nulls_add_tail_rcu
+ hlist_nulls_add_fake
+ hlists_swap_heads_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
- rcu_read_lock_held call_rcu
- rcu_dereference_check kfree_rcu
- rcu_dereference_protected
+ Critical sections Grace period Barrier
+
+ rcu_read_lock synchronize_net rcu_barrier
+ rcu_read_unlock synchronize_rcu
+ guard(rcu)() synchronize_rcu_expedited
+ scoped_guard(rcu) synchronize_rcu_mult
+ rcu_dereference call_rcu
+ rcu_dereference_check call_rcu_hurry
+ rcu_dereference_protected kfree_rcu
+ rcu_read_lock_held kvfree_rcu
+ rcu_read_lock_any_held kfree_rcu_mightsleep
+ rcu_pointer_handoff cond_synchronize_rcu
+ unrcu_pointer cond_synchronize_rcu_full
+ cond_synchronize_rcu_expedited
+ cond_synchronize_rcu_expedited_full
+ get_completed_synchronize_rcu
+ get_completed_synchronize_rcu_full
+ get_state_synchronize_rcu
+ get_state_synchronize_rcu_full
+ poll_state_synchronize_rcu
+ poll_state_synchronize_rcu_full
+ same_state_synchronize_rcu
+ same_state_synchronize_rcu_full
+ start_poll_synchronize_rcu
+ start_poll_synchronize_rcu_full
+ start_poll_synchronize_rcu_expedited
+ start_poll_synchronize_rcu_expedited_full
bh::
Critical sections Grace period Barrier
- rcu_read_lock_bh call_rcu rcu_barrier
- rcu_read_unlock_bh synchronize_rcu
- [local_bh_disable] synchronize_rcu_expedited
+ rcu_read_lock_bh [Same as RCU] [Same as RCU]
+ rcu_read_unlock_bh
+ [local_bh_disable]
[and friends]
rcu_dereference_bh
rcu_dereference_bh_check
@@ -1092,9 +1120,9 @@ sched::
Critical sections Grace period Barrier
- rcu_read_lock_sched call_rcu rcu_barrier
- rcu_read_unlock_sched synchronize_rcu
- [preempt_disable] synchronize_rcu_expedited
+ rcu_read_lock_sched [Same as RCU] [Same as RCU]
+ rcu_read_unlock_sched
+ [preempt_disable]
[and friends]
rcu_read_lock_sched_notrace
rcu_read_unlock_sched_notrace
@@ -1104,46 +1132,104 @@ sched::
rcu_read_lock_sched_held
+RCU: Initialization/cleanup/ordering::
+
+ RCU_INIT_POINTER
+ RCU_INITIALIZER
+ RCU_POINTER_INITIALIZER
+ init_rcu_head
+ destroy_rcu_head
+ init_rcu_head_on_stack
+ destroy_rcu_head_on_stack
+ SLAB_TYPESAFE_BY_RCU
+
+
+RCU: Quiescents states and control::
+
+ cond_resched_tasks_rcu_qs
+ rcu_all_qs
+ rcu_softirq_qs_periodic
+ rcu_end_inkernel_boot
+ rcu_expedite_gp
+ rcu_gp_is_expedited
+ rcu_unexpedite_gp
+ rcu_cpu_stall_reset
+ rcu_head_after_call_rcu
+ rcu_is_watching
+
+
+RCU-sync primitive:
+
+ rcu_sync_is_idle
+ rcu_sync_init
+ rcu_sync_enter
+ rcu_sync_exit
+ rcu_sync_dtor
+
+
RCU-Tasks::
- Critical sections Grace period Barrier
+ Critical sections Grace period Barrier
- N/A call_rcu_tasks rcu_barrier_tasks
+ N/A call_rcu_tasks rcu_barrier_tasks
synchronize_rcu_tasks
RCU-Tasks-Rude::
- Critical sections Grace period Barrier
+ Critical sections Grace period Barrier
- N/A N/A
- synchronize_rcu_tasks_rude
+ N/A synchronize_rcu_tasks_rude rcu_barrier_tasks_rude
+ call_rcu_tasks_rude
RCU-Tasks-Trace::
- Critical sections Grace period Barrier
+ Critical sections Grace period Barrier
- rcu_read_lock_trace call_rcu_tasks_trace rcu_barrier_tasks_trace
+ rcu_read_lock_trace call_rcu_tasks_trace rcu_barrier_tasks_trace
rcu_read_unlock_trace synchronize_rcu_tasks_trace
+ guard(rcu_tasks_trace)()
+ scoped_guard(rcu_tasks_trace)
-SRCU::
+SRCU list traversal::
+ list_for_each_entry_srcu
+ hlist_for_each_entry_srcu
- Critical sections Grace period Barrier
- srcu_read_lock call_srcu srcu_barrier
- srcu_read_unlock synchronize_srcu
- srcu_dereference synchronize_srcu_expedited
+SRCU::
+
+ Critical sections Grace period Barrier
+
+ srcu_read_lock call_srcu srcu_barrier
+ srcu_read_unlock synchronize_srcu
+ srcu_read_lock_fast synchronize_srcu_expedited
+ srcu_read_unlock_fast get_state_synchronize_srcu
+ srcu_read_lock_nmisafe start_poll_synchronize_srcu
+ srcu_read_unlock_nmisafe start_poll_synchronize_srcu_expedited
+ srcu_read_lock_notrace poll_state_synchronize_srcu
+ srcu_read_unlock_notrace
+ srcu_down_read
+ srcu_up_read
+ srcu_down_read_fast
+ srcu_up_read_fast
+ guard(srcu)()
+ scoped_guard(srcu)
+ srcu_read_lock_held
+ srcu_dereference
srcu_dereference_check
+ srcu_dereference_notrace
srcu_read_lock_held
-SRCU: Initialization/cleanup::
+
+SRCU: Initialization/cleanup/ordering::
DEFINE_SRCU
DEFINE_STATIC_SRCU
init_srcu_struct
cleanup_srcu_struct
+ smp_mb__after_srcu_read_unlock
All: lockdep-checked RCU utility APIs::
--
2.40.1On Fri, Aug 15, 2025 at 05:00:05PM -0700, Paul E. McKenney wrote: > +RCU: Initialization/cleanup/ordering:: > + > + RCU_INIT_POINTER > + RCU_INITIALIZER > + RCU_POINTER_INITIALIZER > + init_rcu_head > + destroy_rcu_head > + init_rcu_head_on_stack > + destroy_rcu_head_on_stack > + SLAB_TYPESAFE_BY_RCU > + > + > +RCU: Quiescents states and control:: > + > + cond_resched_tasks_rcu_qs > + rcu_all_qs > + rcu_softirq_qs_periodic > + rcu_end_inkernel_boot > + rcu_expedite_gp > + rcu_gp_is_expedited > + rcu_unexpedite_gp > + rcu_cpu_stall_reset > + rcu_head_after_call_rcu > + rcu_is_watching > + > + > +RCU-sync primitive: > + > + rcu_sync_is_idle > + rcu_sync_init > + rcu_sync_enter > + rcu_sync_exit > + rcu_sync_dtor Looks like inconsistent (normal paragraph instead of literal code block like the rest). Thanks. -- An old man doll... just what I always wanted! - Clara
On Sat, Aug 16, 2025 at 10:54:04AM +0700, Bagas Sanjaya wrote:
> On Fri, Aug 15, 2025 at 05:00:05PM -0700, Paul E. McKenney wrote:
> > +RCU: Initialization/cleanup/ordering::
> > +
> > + RCU_INIT_POINTER
> > + RCU_INITIALIZER
> > + RCU_POINTER_INITIALIZER
> > + init_rcu_head
> > + destroy_rcu_head
> > + init_rcu_head_on_stack
> > + destroy_rcu_head_on_stack
> > + SLAB_TYPESAFE_BY_RCU
> > +
> > +
> > +RCU: Quiescents states and control::
> > +
> > + cond_resched_tasks_rcu_qs
> > + rcu_all_qs
> > + rcu_softirq_qs_periodic
> > + rcu_end_inkernel_boot
> > + rcu_expedite_gp
> > + rcu_gp_is_expedited
> > + rcu_unexpedite_gp
> > + rcu_cpu_stall_reset
> > + rcu_head_after_call_rcu
> > + rcu_is_watching
> > +
> > +
> > +RCU-sync primitive:
> > +
> > + rcu_sync_is_idle
> > + rcu_sync_init
> > + rcu_sync_enter
> > + rcu_sync_exit
> > + rcu_sync_dtor
>
> Looks like inconsistent (normal paragraph instead of literal code block like
> the rest).
As in the "RCU-sync primitive:" needs another colon (":") at the end of
that line? If so, agreed, will fix on next rebase, and thank you!
Thanx, Paul
On Fri, Aug 15, 2025 at 09:54:57PM -0700, Paul E. McKenney wrote:
> On Sat, Aug 16, 2025 at 10:54:04AM +0700, Bagas Sanjaya wrote:
> > On Fri, Aug 15, 2025 at 05:00:05PM -0700, Paul E. McKenney wrote:
> > > +RCU: Initialization/cleanup/ordering::
> > > +
> > > + RCU_INIT_POINTER
> > > + RCU_INITIALIZER
> > > + RCU_POINTER_INITIALIZER
> > > + init_rcu_head
> > > + destroy_rcu_head
> > > + init_rcu_head_on_stack
> > > + destroy_rcu_head_on_stack
> > > + SLAB_TYPESAFE_BY_RCU
> > > +
> > > +
> > > +RCU: Quiescents states and control::
> > > +
> > > + cond_resched_tasks_rcu_qs
> > > + rcu_all_qs
> > > + rcu_softirq_qs_periodic
> > > + rcu_end_inkernel_boot
> > > + rcu_expedite_gp
> > > + rcu_gp_is_expedited
> > > + rcu_unexpedite_gp
> > > + rcu_cpu_stall_reset
> > > + rcu_head_after_call_rcu
> > > + rcu_is_watching
> > > +
> > > +
> > > +RCU-sync primitive:
> > > +
> > > + rcu_sync_is_idle
> > > + rcu_sync_init
> > > + rcu_sync_enter
> > > + rcu_sync_exit
> > > + rcu_sync_dtor
> >
> > Looks like inconsistent (normal paragraph instead of literal code block like
> > the rest).
>
> As in the "RCU-sync primitive:" needs another colon (":") at the end of
> that line? If so, agreed, will fix on next rebase, and thank you!
>
Yup, that's what I mean.
Thanks.
--
An old man doll... just what I always wanted! - Clara
On Sat, Aug 16, 2025 at 12:38:05PM +0700, Bagas Sanjaya wrote:
> On Fri, Aug 15, 2025 at 09:54:57PM -0700, Paul E. McKenney wrote:
> > On Sat, Aug 16, 2025 at 10:54:04AM +0700, Bagas Sanjaya wrote:
> > > On Fri, Aug 15, 2025 at 05:00:05PM -0700, Paul E. McKenney wrote:
> > > > +RCU: Initialization/cleanup/ordering::
> > > > +
> > > > + RCU_INIT_POINTER
> > > > + RCU_INITIALIZER
> > > > + RCU_POINTER_INITIALIZER
> > > > + init_rcu_head
> > > > + destroy_rcu_head
> > > > + init_rcu_head_on_stack
> > > > + destroy_rcu_head_on_stack
> > > > + SLAB_TYPESAFE_BY_RCU
> > > > +
> > > > +
> > > > +RCU: Quiescents states and control::
> > > > +
> > > > + cond_resched_tasks_rcu_qs
> > > > + rcu_all_qs
> > > > + rcu_softirq_qs_periodic
> > > > + rcu_end_inkernel_boot
> > > > + rcu_expedite_gp
> > > > + rcu_gp_is_expedited
> > > > + rcu_unexpedite_gp
> > > > + rcu_cpu_stall_reset
> > > > + rcu_head_after_call_rcu
> > > > + rcu_is_watching
> > > > +
> > > > +
> > > > +RCU-sync primitive:
> > > > +
> > > > + rcu_sync_is_idle
> > > > + rcu_sync_init
> > > > + rcu_sync_enter
> > > > + rcu_sync_exit
> > > > + rcu_sync_dtor
> > >
> > > Looks like inconsistent (normal paragraph instead of literal code block like
> > > the rest).
> >
> > As in the "RCU-sync primitive:" needs another colon (":") at the end of
> > that line? If so, agreed, will fix on next rebase, and thank you!
> >
>
> Yup, that's what I mean.
Got it, and again, thank you!
Thanx, Paul
© 2016 - 2025 Red Hat, Inc.