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.