Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge tag 'kcsan.2024.07.12a' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu
Pull KCSAN updates from Paul McKenney:
- improve the documentation for the new __data_racy type qualifier
to the data_race() macro's kernel-doc header and to the LKMM's
access-marking documentation
- add missing MODULE_DESCRIPTION
* tag 'kcsan.2024.07.12a' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu:
kcsan: Add missing MODULE_DESCRIPTION() macro
kcsan: Add example to data_race() kerneldoc header
+33
-2
+9
-1
include/linux/compiler.h
+9
-1
include/linux/compiler.h
···
194
194
* This data_race() macro is useful for situations in which data races
195
195
* should be forgiven. One example is diagnostic code that accesses
196
196
* shared variables but is not a part of the core synchronization design.
197
+
* For example, if accesses to a given variable are protected by a lock,
198
+
* except for diagnostic code, then the accesses under the lock should
199
+
* be plain C-language accesses and those in the diagnostic code should
200
+
* use data_race(). This way, KCSAN will complain if buggy lockless
201
+
* accesses to that variable are introduced, even if the buggy accesses
202
+
* are protected by READ_ONCE() or WRITE_ONCE().
197
203
*
198
204
* This macro *does not* affect normal code generation, but is a hint
199
-
* to tooling that data races here are to be ignored.
205
+
* to tooling that data races here are to be ignored. If the access must
206
+
* be atomic *and* KCSAN should ignore the access, use both data_race()
207
+
* and READ_ONCE(), for example, data_race(READ_ONCE(x)).
200
208
*/
201
209
#define data_race(expr) \
202
210
({ \
+1
kernel/kcsan/kcsan_test.c
+1
kernel/kcsan/kcsan_test.c
+23
-1
tools/memory-model/Documentation/access-marking.txt
+23
-1
tools/memory-model/Documentation/access-marking.txt
···
25
25
4. WRITE_ONCE(), for example, "WRITE_ONCE(a, b);"
26
26
The various forms of atomic_set() also fit in here.
27
27
28
+
5. __data_racy, for example "int __data_racy a;"
29
+
30
+
6. KCSAN's negative-marking assertions, ASSERT_EXCLUSIVE_ACCESS()
31
+
and ASSERT_EXCLUSIVE_WRITER(), are described in the
32
+
"ACCESS-DOCUMENTATION OPTIONS" section below.
28
33
29
34
These may be used in combination, as shown in this admittedly improbable
30
35
example:
···
211
206
code's synchronization rules.
212
207
213
208
209
+
Use of __data_racy
210
+
------------------
211
+
212
+
Adding the __data_racy type qualifier to the declaration of a variable
213
+
causes KCSAN to treat all accesses to that variable as if they were
214
+
enclosed by data_race(). However, __data_racy does not affect the
215
+
compiler, though one could imagine hardened kernel builds treating the
216
+
__data_racy type qualifier as if it was the volatile keyword.
217
+
218
+
Note well that __data_racy is subject to the same pointer-declaration
219
+
rules as are other type qualifiers such as const and volatile.
220
+
For example:
221
+
222
+
int __data_racy *p; // Pointer to data-racy data.
223
+
int *__data_racy p; // Data-racy pointer to non-data-racy data.
224
+
225
+
214
226
ACCESS-DOCUMENTATION OPTIONS
215
227
============================
216
228
···
365
343
366
344
Because foo is read locklessly, all accesses are marked. The purpose
367
345
of the ASSERT_EXCLUSIVE_WRITER() is to allow KCSAN to check for a buggy
368
-
concurrent lockless write.
346
+
concurrent write, whether marked or not.
369
347
370
348
371
349
Lock-Protected Writes With Heuristic Lockless Reads