^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. _rcu_dereference_doc:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) ===============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Most of the time, you can use values from rcu_dereference() or one of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) the similar primitives without worries. Dereferencing (prefix "*"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) field selection ("->"), assignment ("="), address-of ("&"), addition and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) subtraction of constants, and casts all work quite naturally and safely.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) It is nevertheless possible to get into trouble with other operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Follow these rules to keep your RCU code working properly:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) - You must use one of the rcu_dereference() family of primitives
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) will complain. Worse yet, your code can see random memory-corruption
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) bugs due to games that compilers and DEC Alpha can play.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Without one of the rcu_dereference() primitives, compilers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) can reload the value, and won't your code have fun with two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) different values for a single pointer! Without rcu_dereference(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) DEC Alpha can load a pointer, dereference that pointer, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) return data preceding initialization that preceded the store of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) the pointer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) In addition, the volatile cast in rcu_dereference() prevents the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) compiler from deducing the resulting pointer value. Please see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) the section entitled "EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) for an example where the compiler can in fact deduce the exact
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) value of the pointer, and thus cause misordering.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) - You are only permitted to use rcu_dereference on pointer values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) The compiler simply knows too much about integral values to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) trust it to carry dependencies through integer operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) There are a very few exceptions, namely that you can temporarily
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) cast the pointer to uintptr_t in order to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) - Set bits and clear bits down in the must-be-zero low-order
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) bits of that pointer. This clearly means that the pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) must have alignment constraints, for example, this does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) -not- work in general for char* pointers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) - XOR bits to translate pointers, as is done in some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) classic buddy-allocator algorithms.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) It is important to cast the value back to pointer before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) doing much of anything else with it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) - Avoid cancellation when using the "+" and "-" infix arithmetic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) operators. For example, for a given variable "x", avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) "(x-(uintptr_t)x)" for char* pointers. The compiler is within its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) rights to substitute zero for this sort of expression, so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) subsequent accesses no longer depend on the rcu_dereference(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) again possibly resulting in bugs due to misordering.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) Of course, if "p" is a pointer from rcu_dereference(), and "a"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) and "b" are integers that happen to be equal, the expression
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) "p+a-b" is safe because its value still necessarily depends on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) the rcu_dereference(), thus maintaining proper ordering.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) - If you are using RCU to protect JITed functions, so that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) "()" function-invocation operator is applied to a value obtained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) (directly or indirectly) from rcu_dereference(), you may need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) interact directly with the hardware to flush instruction caches.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) This issue arises on some systems when a newly JITed function is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) using the same memory that was used by an earlier JITed function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) - Do not use the results from relational operators ("==", "!=",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) ">", ">=", "<", or "<=") when dereferencing. For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) the following (quite strange) code is buggy::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) int *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) int *q;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) p = rcu_dereference(gp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) q = &global_q;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) q += p > &oom_p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) r1 = *q; /* BUGGY!!! */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) As before, the reason this is buggy is that relational operators
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) are often compiled using branches. And as before, although
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) weak-memory machines such as ARM or PowerPC do order stores
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) after such branches, but can speculate loads, which can again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) result in misordering bugs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) - Be very careful about comparing pointers obtained from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) rcu_dereference() against non-NULL values. As Linus Torvalds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) explained, if the two pointers are equal, the compiler could
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) substitute the pointer you are comparing against for the pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) obtained from rcu_dereference(). For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) p = rcu_dereference(gp);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) if (p == &default_struct)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) do_default(p->a);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) Because the compiler now knows that the value of "p" is exactly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) the address of the variable "default_struct", it is free to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) transform this code into the following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) p = rcu_dereference(gp);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) if (p == &default_struct)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) do_default(default_struct.a);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) On ARM and Power hardware, the load from "default_struct.a"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) can now be speculated, such that it might happen before the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) rcu_dereference(). This could result in bugs due to misordering.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) However, comparisons are OK in the following cases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) - The comparison was against the NULL pointer. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) compiler knows that the pointer is NULL, you had better
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) not be dereferencing it anyway. If the comparison is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) non-equal, the compiler is none the wiser. Therefore,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) it is safe to compare pointers from rcu_dereference()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) against NULL pointers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) - The pointer is never dereferenced after being compared.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Since there are no subsequent dereferences, the compiler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) cannot use anything it learned from the comparison
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) to reorder the non-existent subsequent dereferences.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) This sort of comparison occurs frequently when scanning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) RCU-protected circular linked lists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) Note that if checks for being within an RCU read-side
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) critical section are not required and the pointer is never
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) dereferenced, rcu_access_pointer() should be used in place
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) of rcu_dereference().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - The comparison is against a pointer that references memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) that was initialized "a long time ago." The reason
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) this is safe is that even if misordering occurs, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) misordering will not affect the accesses that follow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) the comparison. So exactly how long ago is "a long
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) time ago"? Here are some possibilities:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) - Compile time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) - Boot time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) - Module-init time for module code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) - Prior to kthread creation for kthread code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) - During some prior acquisition of the lock that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) we now hold.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) - Before mod_timer() time for a timer handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) There are many other possibilities involving the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) kernel's wide array of primitives that cause code to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) be invoked at a later time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) - The pointer being compared against also came from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) rcu_dereference(). In this case, both pointers depend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) on one rcu_dereference() or another, so you get proper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) ordering either way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) That said, this situation can make certain RCU usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) bugs more likely to happen. Which can be a good thing,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) at least if they happen during testing. An example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) of such an RCU usage bug is shown in the section titled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) "EXAMPLE OF AMPLIFIED RCU-USAGE BUG".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) - All of the accesses following the comparison are stores,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) so that a control dependency preserves the needed ordering.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) That said, it is easy to get control dependencies wrong.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Please see the "CONTROL DEPENDENCIES" section of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) Documentation/memory-barriers.txt for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) - The pointers are not equal -and- the compiler does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) not have enough information to deduce the value of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) pointer. Note that the volatile cast in rcu_dereference()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) will normally prevent the compiler from knowing too much.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) However, please note that if the compiler knows that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) pointer takes on only one of two values, a not-equal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) comparison will provide exactly the information that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) compiler needs to deduce the value of the pointer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) - Disable any value-speculation optimizations that your compiler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) might provide, especially if you are making use of feedback-based
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) optimizations that take data collected from prior runs. Such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) value-speculation optimizations reorder operations by design.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) There is one exception to this rule: Value-speculation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) optimizations that leverage the branch-prediction hardware are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) safe on strongly ordered systems (such as x86), but not on weakly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) ordered systems (such as ARM or Power). Choose your compiler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) command-line options wisely!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) EXAMPLE OF AMPLIFIED RCU-USAGE BUG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Because updaters can run concurrently with RCU readers, RCU readers can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) see stale and/or inconsistent values. If RCU readers need fresh or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) consistent values, which they sometimes do, they need to take proper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) precautions. To see this, consider the following code fragment::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) struct foo {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) int a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) int b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) int c;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) struct foo *gp1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) struct foo *gp2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) void updater(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) struct foo *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) p = kmalloc(...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) if (p == NULL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) deal_with_it();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) p->a = 42; /* Each field in its own cache line. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) p->b = 43;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) p->c = 44;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) rcu_assign_pointer(gp1, p);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) p->b = 143;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) p->c = 144;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) rcu_assign_pointer(gp2, p);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) void reader(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) struct foo *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) struct foo *q;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) int r1, r2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) p = rcu_dereference(gp2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) if (p == NULL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) return;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) r1 = p->b; /* Guaranteed to get 143. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) q = rcu_dereference(gp1); /* Guaranteed non-NULL. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) if (p == q) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) /* The compiler decides that q->c is same as p->c. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) r2 = p->c; /* Could get 44 on weakly order system. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) do_something_with(r1, r2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) You might be surprised that the outcome (r1 == 143 && r2 == 44) is possible,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) but you should not be. After all, the updater might have been invoked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) a second time between the time reader() loaded into "r1" and the time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) that it loaded into "r2". The fact that this same result can occur due
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) to some reordering from the compiler and CPUs is beside the point.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) But suppose that the reader needs a consistent view?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) Then one approach is to use locking, for example, as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) struct foo {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) int a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) int b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) int c;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) spinlock_t lock;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) struct foo *gp1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) struct foo *gp2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) void updater(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) struct foo *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) p = kmalloc(...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) if (p == NULL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) deal_with_it();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) spin_lock(&p->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) p->a = 42; /* Each field in its own cache line. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) p->b = 43;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) p->c = 44;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) spin_unlock(&p->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) rcu_assign_pointer(gp1, p);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) spin_lock(&p->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) p->b = 143;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) p->c = 144;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) spin_unlock(&p->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) rcu_assign_pointer(gp2, p);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) void reader(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) struct foo *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) struct foo *q;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) int r1, r2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) p = rcu_dereference(gp2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) if (p == NULL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) return;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) spin_lock(&p->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) r1 = p->b; /* Guaranteed to get 143. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) q = rcu_dereference(gp1); /* Guaranteed non-NULL. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) if (p == q) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) /* The compiler decides that q->c is same as p->c. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) r2 = p->c; /* Locking guarantees r2 == 144. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) spin_unlock(&p->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) do_something_with(r1, r2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) As always, use the right tool for the job!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) If a pointer obtained from rcu_dereference() compares not-equal to some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) other pointer, the compiler normally has no clue what the value of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) first pointer might be. This lack of knowledge prevents the compiler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) from carrying out optimizations that otherwise might destroy the ordering
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) guarantees that RCU depends on. And the volatile cast in rcu_dereference()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) should prevent the compiler from guessing the value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) But without rcu_dereference(), the compiler knows more than you might
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) expect. Consider the following code fragment::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) struct foo {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) int a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) int b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) static struct foo variable1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) static struct foo variable2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) static struct foo *gp = &variable1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) void updater(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) initialize_foo(&variable2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) rcu_assign_pointer(gp, &variable2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) * The above is the only store to gp in this translation unit,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) * and the address of gp is not exported in any way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) int reader(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) struct foo *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) p = gp;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) barrier();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) if (p == &variable1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) return p->a; /* Must be variable1.a. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) return p->b; /* Must be variable2.b. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) Because the compiler can see all stores to "gp", it knows that the only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) possible values of "gp" are "variable1" on the one hand and "variable2"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) on the other. The comparison in reader() therefore tells the compiler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) the exact value of "p" even in the not-equals case. This allows the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) compiler to make the return values independent of the load from "gp",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) in turn destroying the ordering between this load and the loads of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) return values. This can result in "p->b" returning pre-initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) garbage values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) In short, rcu_dereference() is -not- optional when you are going to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) dereference the resulting pointer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) WHICH MEMBER OF THE rcu_dereference() FAMILY SHOULD YOU USE?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) ------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) First, please avoid using rcu_dereference_raw() and also please avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) using rcu_dereference_check() and rcu_dereference_protected() with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) second argument with a constant value of 1 (or true, for that matter).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) With that caution out of the way, here is some guidance for which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) member of the rcu_dereference() to use in various situations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) 1. If the access needs to be within an RCU read-side critical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) section, use rcu_dereference(). With the new consolidated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) RCU flavors, an RCU read-side critical section is entered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) using rcu_read_lock(), anything that disables bottom halves,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) anything that disables interrupts, or anything that disables
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) preemption.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) 2. If the access might be within an RCU read-side critical section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) on the one hand, or protected by (say) my_lock on the other,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) use rcu_dereference_check(), for example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) p1 = rcu_dereference_check(p->rcu_protected_pointer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) lockdep_is_held(&my_lock));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) 3. If the access might be within an RCU read-side critical section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) on the one hand, or protected by either my_lock or your_lock on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) the other, again use rcu_dereference_check(), for example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) p1 = rcu_dereference_check(p->rcu_protected_pointer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) lockdep_is_held(&my_lock) ||
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) lockdep_is_held(&your_lock));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) 4. If the access is on the update side, so that it is always protected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) by my_lock, use rcu_dereference_protected()::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) p1 = rcu_dereference_protected(p->rcu_protected_pointer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) lockdep_is_held(&my_lock));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) This can be extended to handle multiple locks as in #3 above,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) and both can be extended to check other conditions as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) 5. If the protection is supplied by the caller, and is thus unknown
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) to this code, that is the rare case when rcu_dereference_raw()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) is appropriate. In addition, rcu_dereference_raw() might be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) appropriate when the lockdep expression would be excessively
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) complex, except that a better approach in that case might be to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) take a long hard look at your synchronization design. Still,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) there are data-locking cases where any one of a very large number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) of locks or reference counters suffices to protect the pointer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) so rcu_dereference_raw() does have its place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) However, its place is probably quite a bit smaller than one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) might expect given the number of uses in the current kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) Ditto for its synonym, rcu_dereference_check( ... , 1), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) its close relative, rcu_dereference_protected(... , 1).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) SPARSE CHECKING OF RCU-PROTECTED POINTERS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) The sparse static-analysis tool checks for direct access to RCU-protected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) pointers, which can result in "interesting" bugs due to compiler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) optimizations involving invented loads and perhaps also load tearing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) For example, suppose someone mistakenly does something like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) p = q->rcu_protected_pointer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) do_something_with(p->a);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) do_something_else_with(p->b);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) If register pressure is high, the compiler might optimize "p" out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) of existence, transforming the code to something like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) do_something_with(q->rcu_protected_pointer->a);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) do_something_else_with(q->rcu_protected_pointer->b);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) This could fatally disappoint your code if q->rcu_protected_pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) changed in the meantime. Nor is this a theoretical problem: Exactly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) this sort of bug cost Paul E. McKenney (and several of his innocent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) colleagues) a three-day weekend back in the early 1990s.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) Load tearing could of course result in dereferencing a mashup of a pair
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) of pointers, which also might fatally disappoint your code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) These problems could have been avoided simply by making the code instead
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) read as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) p = rcu_dereference(q->rcu_protected_pointer);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) do_something_with(p->a);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) do_something_else_with(p->b);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) Unfortunately, these sorts of bugs can be extremely hard to spot during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) review. This is where the sparse tool comes into play, along with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) "__rcu" marker. If you mark a pointer declaration, whether in a structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) or as a formal parameter, with "__rcu", which tells sparse to complain if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) this pointer is accessed directly. It will also cause sparse to complain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) if a pointer not marked with "__rcu" is accessed using rcu_dereference()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) and friends. For example, ->rcu_protected_pointer might be declared as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) struct foo __rcu *rcu_protected_pointer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) Use of "__rcu" is opt-in. If you choose not to use it, then you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) ignore the sparse warnings.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags