include/linux/srcu.h

1 /* SPDX-License-Identifier: GPL-2.0+ */
3  * Sleepable Read-Copy Update mechanism for mutual exclusion
11  * For detailed explanation of Read-Copy Update mechanism see -
46 /* Values for SRCU Tree srcu_data ->srcu_reader_flavor, but also used by rcutorture. */
74  * get_completed_synchronize_srcu - Return a pre-completed polled state cookie
76  * Returns a value that poll_state_synchronize_srcu() will always treat
77  * as a cookie whose grace period has already completed.
89 // not-yet-completed SRCU grace periods.
93  * same_state_synchronize_srcu - Are two old-state values identical?
94  * @oldstate1: First old-state value.
95  * @oldstate2: Second old-state value.
97  * The two old-state values must have been obtained from either
101  * are tracked by old-state values to push these values to a list header,
128  * srcu_read_lock_held - might we be in SRCU read-side critical section?
132  * read-side critical section.  In absence of CONFIG_DEBUG_LOCK_ALLOC,
133  * this assumes we are in an SRCU read-side critical section unless it can
147 	return lock_is_held(&ssp->dep_map);  in srcu_read_lock_held()
154  * srcu_lock_sync(), which is basically an empty *write*-side critical section,
158 /* Annotates a srcu_read_lock() */
164 /* Annotates a srcu_read_lock() */
170 /* Annotates a synchronize_srcu() */
191  * srcu_dereference_check - fetch SRCU-protected pointer for later dereferencing
194  *	really are in an SRCU read-side critical section.
195  * @c: condition to check for update-side use
197  * If PROVE_RCU is enabled, invoking this outside of an RCU read-side
198  * critical section will result in an RCU-lockdep splat, unless @c evaluates
199  * to 1.  The @c argument will normally be a logical expression containing
207  * srcu_dereference - fetch SRCU-protected pointer for later dereferencing
210  *	really are in an SRCU read-side critical section.
213  * is enabled, invoking this outside of an RCU read-side critical
214  * section will result in an RCU-lockdep splat.
219  * srcu_dereference_notrace - no tracing and no lockdep calls from here
222  *	really are in an SRCU read-side critical section.
227  * srcu_read_lock - register a new reader for an SRCU-protected structure.
230  * Enter an SRCU read-side critical section.  Note that SRCU read-side
235  * a mutex that is held elsewhere while calling synchronize_srcu() or
239  * non-negative.  This value must be passed unaltered to the matching
253 	srcu_lock_acquire(&ssp->dep_map);  in srcu_read_lock()
258  * srcu_read_lock_fast - register a new reader for an SRCU-protected structure.
261  * Enter an SRCU read-side critical section, but for a light-weight
262  * smp_mb()-free reader.  See srcu_read_lock() for more information.
266  * or after.  Note that grace-period auto-expediting is disabled for _fast
267  * srcu_struct structures because auto-expedited grace periods invoke
280 	rcu_try_lock_acquire(&ssp->dep_map);  in srcu_read_lock_fast()
285  * srcu_down_read_fast - register a new reader for an SRCU-protected structure.
288  * Enter a semaphore-like SRCU read-side critical section, but for
289  * a light-weight smp_mb()-free reader.  See srcu_read_lock_fast() and
303  * srcu_read_lock_lite - register a new reader for an SRCU-protected structure.
306  * Enter an SRCU read-side critical section, but for a light-weight
307  * smp_mb()-free reader.  See srcu_read_lock() for more information.
311  * or after.  Note that grace-period auto-expediting is disabled for _lite
312  * srcu_struct structures because auto-expedited grace periods invoke
325 	rcu_try_lock_acquire(&ssp->dep_map);  in srcu_read_lock_lite()
330  * srcu_read_lock_nmisafe - register a new reader for an SRCU-protected structure.
333  * Enter an SRCU read-side critical section, but in an NMI-safe manner.
346 	rcu_try_lock_acquire(&ssp->dep_map);  in srcu_read_lock_nmisafe()
362  * srcu_down_read - register a new reader for an SRCU-protected structure.
365  * Enter a semaphore-like SRCU read-side critical section.  Note that
366  * SRCU read-side critical sections may be nested.  However, it is
370  * a mutex that is held elsewhere while calling synchronize_srcu() or
374  * The semaphore-like nature of srcu_down_read() means that the matching
391  * srcu_read_unlock - unregister a old reader from an SRCU-protected structure.
395  * Exit an SRCU read-side critical section.
402 	srcu_lock_release(&ssp->dep_map);  in srcu_read_unlock()
407  * srcu_read_unlock_fast - unregister a old reader from an SRCU-protected structure.
411  * Exit a light-weight SRCU read-side critical section.
417 	srcu_lock_release(&ssp->dep_map);  in srcu_read_unlock_fast()
422  * srcu_up_read_fast - unregister a old reader from an SRCU-protected structure.
426  * Exit an SRCU read-side critical section, but not necessarily from
438  * srcu_read_unlock_lite - unregister a old reader from an SRCU-protected structure.
442  * Exit a light-weight SRCU read-side critical section.
449 	srcu_lock_release(&ssp->dep_map);  in srcu_read_unlock_lite()
454  * srcu_read_unlock_nmisafe - unregister a old reader from an SRCU-protected structure.
458  * Exit an SRCU read-side critical section, but in an NMI-safe manner.
465 	rcu_lock_release(&ssp->dep_map);  in srcu_read_unlock_nmisafe()
478  * srcu_up_read - unregister a old reader from an SRCU-protected structure.
482  * Exit an SRCU read-side critical section, but not necessarily from
495  * smp_mb__after_srcu_read_unlock - ensure full ordering after srcu_read_unlock
497  * Converts the preceding srcu_read_unlock into a two-way memory barrier.
509  * smp_mb__after_srcu_read_lock - ensure full ordering after srcu_read_lock
511  * Converts the preceding srcu_read_lock into a two-way memory barrier.
523 		    _T->idx = srcu_read_lock(_T->lock),
524 		    srcu_read_unlock(_T->lock, _T->idx),