diff options
author | Paul E. McKenney <paulmck@kernel.org> | 2024-05-10 15:36:57 -0700 |
---|---|---|
committer | Paul E. McKenney <paulmck@kernel.org> | 2024-05-30 15:06:26 -0700 |
commit | 020e6c22bd6e67592f38b47d0f1926a831482560 (patch) | |
tree | b0bd5f516f5ef060840275221286e0881f426c01 /include | |
parent | 1613e604df0cd359cf2a7fbd9be7a0bcfacfabd0 (diff) | |
download | lwn-020e6c22bd6e67592f38b47d0f1926a831482560.tar.gz lwn-020e6c22bd6e67592f38b47d0f1926a831482560.zip |
kcsan: Add example to data_race() kerneldoc header
Although the data_race() kerneldoc header accurately states what it does,
some of the implications and usage patterns are non-obvious. Therefore,
add a brief locking example and also state how to have KCSAN ignore
accesses while also preventing the compiler from folding, spindling,
or otherwise mutilating the access.
[ paulmck: Apply Bart Van Assche feedback. ]
[ paulmck: Apply feedback from Marco Elver. ]
Reported-by: Bart Van Assche <bvanassche@acm.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Cc: Marco Elver <elver@google.com>
Cc: Breno Leitao <leitao@debian.org>
Cc: Jens Axboe <axboe@kernel.dk>
Diffstat (limited to 'include')
-rw-r--r-- | include/linux/compiler.h | 10 |
1 files changed, 9 insertions, 1 deletions
diff --git a/include/linux/compiler.h b/include/linux/compiler.h index 8c252e073bd8..68a24a3a6979 100644 --- a/include/linux/compiler.h +++ b/include/linux/compiler.h @@ -194,9 +194,17 @@ void ftrace_likely_update(struct ftrace_likely_data *f, int val, * This data_race() macro is useful for situations in which data races * should be forgiven. One example is diagnostic code that accesses * shared variables but is not a part of the core synchronization design. + * For example, if accesses to a given variable are protected by a lock, + * except for diagnostic code, then the accesses under the lock should + * be plain C-language accesses and those in the diagnostic code should + * use data_race(). This way, KCSAN will complain if buggy lockless + * accesses to that variable are introduced, even if the buggy accesses + * are protected by READ_ONCE() or WRITE_ONCE(). * * This macro *does not* affect normal code generation, but is a hint - * to tooling that data races here are to be ignored. + * to tooling that data races here are to be ignored. If the access must + * be atomic *and* KCSAN should ignore the access, use both data_race() + * and READ_ONCE(), for example, data_race(READ_ONCE(x)). */ #define data_race(expr) \ ({ \ |