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