fe24b58627bdde8f6a5d0b331436408f1d43d3ea
[linux-3.10.git] / Documentation / RCU / lockdep.txt
1 RCU and lockdep checking
2
3 All flavors of RCU have lockdep checking available, so that lockdep is
4 aware of when each task enters and leaves any flavor of RCU read-side
5 critical section.  Each flavor of RCU is tracked separately (but note
6 that this is not the case in 2.6.32 and earlier).  This allows lockdep's
7 tracking to include RCU state, which can sometimes help when debugging
8 deadlocks and the like.
9
10 In addition, RCU provides the following primitives that check lockdep's
11 state:
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
18 These functions are conservative, and will therefore return 1 if they
19 aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set).
20 This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false
21 positives when lockdep is disabled.
22
23 In addition, a separate kernel config parameter CONFIG_PROVE_RCU enables
24 checking 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):
35                 Use explicit check expression "c".
36         rcu_dereference_raw(p)
37                 Don't check.  (Use sparingly, if at all.)
38
39 The rcu_dereference_check() check expression can be any boolean
40 expression, but would normally include one of the rcu_read_lock_held()
41 family of functions and a lockdep expression.  However, any boolean
42 expression can be used.  For a moderately ornate example, consider
43 the following:
44
45         file = rcu_dereference_check(fdt->fd[fd],
46                                      rcu_read_lock_held() ||
47                                      lockdep_is_held(&files->file_lock) ||
48                                      atomic_read(&files->count) == 1);
49
50 This expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner,
51 and, if CONFIG_PROVE_RCU is configured, verifies that this expression
52 is used in:
53
54 1.      An RCU read-side critical section, or
55 2.      with files->file_lock held, or
56 3.      on an unshared files_struct.
57
58 In case (1), the pointer is picked up in an RCU-safe manner for vanilla
59 RCU read-side critical sections, in case (2) the ->file_lock prevents
60 any change from taking place, and finally, in case (3) the current task
61 is the only task accessing the file_struct, again preventing any change
62 from taking place.
63
64 There are currently only "universal" versions of the rcu_assign_pointer()
65 and RCU list-/tree-traversal primitives, which do not (yet) check for
66 being in an RCU read-side critical section.  In the future, separate
67 versions of these primitives might be created.