1.. SPDX-License-Identifier: GPL-2.0
2
3========================
4RCU and lockdep checking
5========================
6
7All flavors of RCU have lockdep checking available, so that lockdep is
8aware of when each task enters and leaves any flavor of RCU read-side
9critical section.  Each flavor of RCU is tracked separately (but note
10that this is not the case in 2.6.32 and earlier).  This allows lockdep's
11tracking to include RCU state, which can sometimes help when debugging
12deadlocks and the like.
13
14In addition, RCU provides the following primitives that check lockdep's
15state::
16
17	rcu_read_lock_held() for normal RCU.
18	rcu_read_lock_bh_held() for RCU-bh.
19	rcu_read_lock_sched_held() for RCU-sched.
20	srcu_read_lock_held() for SRCU.
21
22These functions are conservative, and will therefore return 1 if they
23aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set).
24This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false
25positives when lockdep is disabled.
26
27In addition, a separate kernel config parameter CONFIG_PROVE_RCU enables
28checking of rcu_dereference() primitives:
29
30	rcu_dereference(p):
31		Check for RCU read-side critical section.
32	rcu_dereference_bh(p):
33		Check for RCU-bh read-side critical section.
34	rcu_dereference_sched(p):
35		Check for RCU-sched read-side critical section.
36	srcu_dereference(p, sp):
37		Check for SRCU read-side critical section.
38	rcu_dereference_check(p, c):
39		Use explicit check expression "c" along with
40		rcu_read_lock_held().  This is useful in code that is
41		invoked by both RCU readers and updaters.
42	rcu_dereference_bh_check(p, c):
43		Use explicit check expression "c" along with
44		rcu_read_lock_bh_held().  This is useful in code that
45		is invoked by both RCU-bh readers and updaters.
46	rcu_dereference_sched_check(p, c):
47		Use explicit check expression "c" along with
48		rcu_read_lock_sched_held().  This is useful in code that
49		is invoked by both RCU-sched readers and updaters.
50	srcu_dereference_check(p, c):
51		Use explicit check expression "c" along with
52		srcu_read_lock_held().  This is useful in code that
53		is invoked by both SRCU readers and updaters.
54	rcu_dereference_raw(p):
55		Don't check.  (Use sparingly, if at all.)
56	rcu_dereference_protected(p, c):
57		Use explicit check expression "c", and omit all barriers
58		and compiler constraints.  This is useful when the data
59		structure cannot change, for example, in code that is
60		invoked only by updaters.
61	rcu_access_pointer(p):
62		Return the value of the pointer and omit all barriers,
63		but retain the compiler constraints that prevent duplicating
64		or coalescsing.  This is useful when testing the
65		value of the pointer itself, for example, against NULL.
66
67The rcu_dereference_check() check expression can be any boolean
68expression, but would normally include a lockdep expression.  However,
69any boolean expression can be used.  For a moderately ornate example,
70consider the following::
71
72	file = rcu_dereference_check(fdt->fd[fd],
73				     lockdep_is_held(&files->file_lock) ||
74				     atomic_read(&files->count) == 1);
75
76This expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner,
77and, if CONFIG_PROVE_RCU is configured, verifies that this expression
78is used in:
79
801.	An RCU read-side critical section (implicit), or
812.	with files->file_lock held, or
823.	on an unshared files_struct.
83
84In case (1), the pointer is picked up in an RCU-safe manner for vanilla
85RCU read-side critical sections, in case (2) the ->file_lock prevents
86any change from taking place, and finally, in case (3) the current task
87is the only task accessing the file_struct, again preventing any change
88from taking place.  If the above statement was invoked only from updater
89code, it could instead be written as follows::
90
91	file = rcu_dereference_protected(fdt->fd[fd],
92					 lockdep_is_held(&files->file_lock) ||
93					 atomic_read(&files->count) == 1);
94
95This would verify cases #2 and #3 above, and furthermore lockdep would
96complain if this was used in an RCU read-side critical section unless one
97of these two cases held.  Because rcu_dereference_protected() omits all
98barriers and compiler constraints, it generates better code than do the
99other flavors of rcu_dereference().  On the other hand, it is illegal
100to use rcu_dereference_protected() if either the RCU-protected pointer
101or the RCU-protected data that it points to can change concurrently.
102
103Like rcu_dereference(), when lockdep is enabled, RCU list and hlist
104traversal primitives check for being called from within an RCU read-side
105critical section.  However, a lockdep expression can be passed to them
106as a additional optional argument.  With this lockdep expression, these
107traversal primitives will complain only if the lockdep expression is
108false and they are called from outside any RCU read-side critical section.
109
110For example, the workqueue for_each_pwq() macro is intended to be used
111either within an RCU read-side critical section or with wq->mutex held.
112It is thus implemented as follows::
113
114	#define for_each_pwq(pwq, wq)
115		list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
116					lock_is_held(&(wq->mutex).dep_map))
117