0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ========================
0004 RCU and lockdep checking
0005 ========================
0006
0007 All flavors of RCU have lockdep checking available, so that lockdep is
0008 aware of when each task enters and leaves any flavor of RCU read-side
0009 critical section. Each flavor of RCU is tracked separately (but note
0010 that this is not the case in 2.6.32 and earlier). This allows lockdep's
0011 tracking to include RCU state, which can sometimes help when debugging
0012 deadlocks and the like.
0013
0014 In addition, RCU provides the following primitives that check lockdep's
0015 state::
0016
0017 rcu_read_lock_held() for normal RCU.
0018 rcu_read_lock_bh_held() for RCU-bh.
0019 rcu_read_lock_sched_held() for RCU-sched.
0020 srcu_read_lock_held() for SRCU.
0021
0022 These functions are conservative, and will therefore return 1 if they
0023 aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set).
0024 This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false
0025 positives when lockdep is disabled.
0026
0027 In addition, a separate kernel config parameter CONFIG_PROVE_RCU enables
0028 checking of rcu_dereference() primitives:
0029
0030 rcu_dereference(p):
0031 Check for RCU read-side critical section.
0032 rcu_dereference_bh(p):
0033 Check for RCU-bh read-side critical section.
0034 rcu_dereference_sched(p):
0035 Check for RCU-sched read-side critical section.
0036 srcu_dereference(p, sp):
0037 Check for SRCU read-side critical section.
0038 rcu_dereference_check(p, c):
0039 Use explicit check expression "c" along with
0040 rcu_read_lock_held(). This is useful in code that is
0041 invoked by both RCU readers and updaters.
0042 rcu_dereference_bh_check(p, c):
0043 Use explicit check expression "c" along with
0044 rcu_read_lock_bh_held(). This is useful in code that
0045 is invoked by both RCU-bh readers and updaters.
0046 rcu_dereference_sched_check(p, c):
0047 Use explicit check expression "c" along with
0048 rcu_read_lock_sched_held(). This is useful in code that
0049 is invoked by both RCU-sched readers and updaters.
0050 srcu_dereference_check(p, c):
0051 Use explicit check expression "c" along with
0052 srcu_read_lock_held(). This is useful in code that
0053 is invoked by both SRCU readers and updaters.
0054 rcu_dereference_raw(p):
0055 Don't check. (Use sparingly, if at all.)
0056 rcu_dereference_protected(p, c):
0057 Use explicit check expression "c", and omit all barriers
0058 and compiler constraints. This is useful when the data
0059 structure cannot change, for example, in code that is
0060 invoked only by updaters.
0061 rcu_access_pointer(p):
0062 Return the value of the pointer and omit all barriers,
0063 but retain the compiler constraints that prevent duplicating
0064 or coalescsing. This is useful when when testing the
0065 value of the pointer itself, for example, against NULL.
0066
0067 The rcu_dereference_check() check expression can be any boolean
0068 expression, but would normally include a lockdep expression. However,
0069 any boolean expression can be used. For a moderately ornate example,
0070 consider the following::
0071
0072 file = rcu_dereference_check(fdt->fd[fd],
0073 lockdep_is_held(&files->file_lock) ||
0074 atomic_read(&files->count) == 1);
0075
0076 This expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner,
0077 and, if CONFIG_PROVE_RCU is configured, verifies that this expression
0078 is used in:
0079
0080 1. An RCU read-side critical section (implicit), or
0081 2. with files->file_lock held, or
0082 3. on an unshared files_struct.
0083
0084 In case (1), the pointer is picked up in an RCU-safe manner for vanilla
0085 RCU read-side critical sections, in case (2) the ->file_lock prevents
0086 any change from taking place, and finally, in case (3) the current task
0087 is the only task accessing the file_struct, again preventing any change
0088 from taking place. If the above statement was invoked only from updater
0089 code, it could instead be written as follows::
0090
0091 file = rcu_dereference_protected(fdt->fd[fd],
0092 lockdep_is_held(&files->file_lock) ||
0093 atomic_read(&files->count) == 1);
0094
0095 This would verify cases #2 and #3 above, and furthermore lockdep would
0096 complain if this was used in an RCU read-side critical section unless one
0097 of these two cases held. Because rcu_dereference_protected() omits all
0098 barriers and compiler constraints, it generates better code than do the
0099 other flavors of rcu_dereference(). On the other hand, it is illegal
0100 to use rcu_dereference_protected() if either the RCU-protected pointer
0101 or the RCU-protected data that it points to can change concurrently.
0102
0103 Like rcu_dereference(), when lockdep is enabled, RCU list and hlist
0104 traversal primitives check for being called from within an RCU read-side
0105 critical section. However, a lockdep expression can be passed to them
0106 as a additional optional argument. With this lockdep expression, these
0107 traversal primitives will complain only if the lockdep expression is
0108 false and they are called from outside any RCU read-side critical section.
0109
0110 For example, the workqueue for_each_pwq() macro is intended to be used
0111 either within an RCU read-side critical section or with wq->mutex held.
0112 It is thus implemented as follows::
0113
0114 #define for_each_pwq(pwq, wq)
0115 list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
0116 lock_is_held(&(wq->mutex).dep_map))
