blob: cd83d2348fef8c4a3ff3bee57fc9904976b46390 [file] [log] [blame]
Paul E. McKenneyc598a072010-02-22 17:04:57 -08001RCU and lockdep checking
2
3All flavors of RCU have lockdep checking available, so that lockdep is
4aware of when each task enters and leaves any flavor of RCU read-side
5critical section. Each flavor of RCU is tracked separately (but note
6that this is not the case in 2.6.32 and earlier). This allows lockdep's
7tracking to include RCU state, which can sometimes help when debugging
8deadlocks and the like.
9
10In addition, RCU provides the following primitives that check lockdep's
11state:
12
13 rcu_read_lock_held() for normal RCU.
14 rcu_read_lock_bh_held() for RCU-bh.
15 rcu_read_lock_sched_held() for RCU-sched.
16 srcu_read_lock_held() for SRCU.
17
18These functions are conservative, and will therefore return 1 if they
19aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set).
20This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false
21positives when lockdep is disabled.
22
23In addition, a separate kernel config parameter CONFIG_PROVE_RCU enables
24checking of rcu_dereference() primitives:
25
26 rcu_dereference(p):
27 Check for RCU read-side critical section.
28 rcu_dereference_bh(p):
29 Check for RCU-bh read-side critical section.
30 rcu_dereference_sched(p):
31 Check for RCU-sched read-side critical section.
32 srcu_dereference(p, sp):
33 Check for SRCU read-side critical section.
34 rcu_dereference_check(p, c):
Paul E. McKenney8cd889c2011-07-08 09:07:35 -070035 Use explicit check expression "c" along with
36 rcu_read_lock_held(). This is useful in code that is
37 invoked by both RCU readers and updaters.
38 rcu_dereference_bh_check(p, c):
39 Use explicit check expression "c" along with
40 rcu_read_lock_bh_held(). This is useful in code that
41 is invoked by both RCU-bh readers and updaters.
42 rcu_dereference_sched_check(p, c):
43 Use explicit check expression "c" along with
44 rcu_read_lock_sched_held(). This is useful in code that
45 is invoked by both RCU-sched readers and updaters.
46 srcu_dereference_check(p, c):
47 Use explicit check expression "c" along with
48 srcu_read_lock_held()(). This is useful in code that
49 is invoked by both SRCU readers and updaters.
50 rcu_dereference_index_check(p, c):
51 Use explicit check expression "c", but the caller
52 must supply one of the rcu_read_lock_held() functions.
53 This is useful in code that uses RCU-protected arrays
54 that is invoked by both RCU readers and updaters.
55 rcu_dereference_raw(p):
Paul E. McKenneyc598a072010-02-22 17:04:57 -080056 Don't check. (Use sparingly, if at all.)
Paul E. McKenney50aec002010-04-09 15:39:12 -070057 rcu_dereference_protected(p, c):
58 Use explicit check expression "c", and omit all barriers
59 and compiler constraints. This is useful when the data
60 structure cannot change, for example, in code that is
61 invoked only by updaters.
62 rcu_access_pointer(p):
63 Return the value of the pointer and omit all barriers,
64 but retain the compiler constraints that prevent duplicating
65 or coalescsing. This is useful when when testing the
66 value of the pointer itself, for example, against NULL.
Paul E. McKenney3f944ad2013-03-04 17:55:49 -080067 rcu_access_index(idx):
68 Return the value of the index and omit all barriers, but
69 retain the compiler constraints that prevent duplicating
70 or coalescsing. This is useful when when testing the
71 value of the index itself, for example, against -1.
Paul E. McKenneyc598a072010-02-22 17:04:57 -080072
73The rcu_dereference_check() check expression can be any boolean
Michal Hockoe5177ec2011-07-08 08:48:24 -070074expression, but would normally include a lockdep expression. However,
75any boolean expression can be used. For a moderately ornate example,
76consider the following:
Paul E. McKenneyc598a072010-02-22 17:04:57 -080077
78 file = rcu_dereference_check(fdt->fd[fd],
Paul E. McKenneyc598a072010-02-22 17:04:57 -080079 lockdep_is_held(&files->file_lock) ||
80 atomic_read(&files->count) == 1);
81
82This expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner,
83and, if CONFIG_PROVE_RCU is configured, verifies that this expression
84is used in:
85
Michal Hockoe5177ec2011-07-08 08:48:24 -0700861. An RCU read-side critical section (implicit), or
Paul E. McKenneyc598a072010-02-22 17:04:57 -0800872. with files->file_lock held, or
883. on an unshared files_struct.
89
90In case (1), the pointer is picked up in an RCU-safe manner for vanilla
91RCU read-side critical sections, in case (2) the ->file_lock prevents
92any change from taking place, and finally, in case (3) the current task
93is the only task accessing the file_struct, again preventing any change
Paul E. McKenney50aec002010-04-09 15:39:12 -070094from taking place. If the above statement was invoked only from updater
95code, it could instead be written as follows:
96
97 file = rcu_dereference_protected(fdt->fd[fd],
98 lockdep_is_held(&files->file_lock) ||
99 atomic_read(&files->count) == 1);
100
101This would verify cases #2 and #3 above, and furthermore lockdep would
102complain if this was used in an RCU read-side critical section unless one
103of these two cases held. Because rcu_dereference_protected() omits all
104barriers and compiler constraints, it generates better code than do the
105other flavors of rcu_dereference(). On the other hand, it is illegal
106to use rcu_dereference_protected() if either the RCU-protected pointer
107or the RCU-protected data that it points to can change concurrently.
Paul E. McKenneyc598a072010-02-22 17:04:57 -0800108
109There are currently only "universal" versions of the rcu_assign_pointer()
110and RCU list-/tree-traversal primitives, which do not (yet) check for
111being in an RCU read-side critical section. In the future, separate
112versions of these primitives might be created.