2019-11-14 11:02:54 -07:00
|
|
|
/* SPDX-License-Identifier: GPL-2.0 */
|
|
|
|
|
|
|
|
#ifndef _LINUX_KCSAN_CHECKS_H
|
|
|
|
#define _LINUX_KCSAN_CHECKS_H
|
|
|
|
|
|
|
|
#include <linux/types.h>
|
|
|
|
|
|
|
|
/*
|
kcsan: Introduce KCSAN_ACCESS_ASSERT access type
The KCSAN_ACCESS_ASSERT access type may be used to introduce dummy reads
and writes to assert certain properties of concurrent code, where bugs
could not be detected as normal data races.
For example, a variable that is only meant to be written by a single
CPU, but may be read (without locking) by other CPUs must still be
marked properly to avoid data races. However, concurrent writes,
regardless if WRITE_ONCE() or not, would be a bug. Using
kcsan_check_access(&x, sizeof(x), KCSAN_ACCESS_ASSERT) would allow
catching such bugs.
To support KCSAN_ACCESS_ASSERT the following notable changes were made:
* If an access is of type KCSAN_ASSERT_ACCESS, disable various filters
that only apply to data races, so that all races that KCSAN observes are
reported.
* Bug reports that involve an ASSERT access type will be reported as
"KCSAN: assert: race in ..." instead of "data-race"; this will help
more easily distinguish them.
* Update a few comments to just mention 'races' where we do not always
mean pure data races.
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2020-02-06 08:46:24 -07:00
|
|
|
* ACCESS TYPE MODIFIERS
|
|
|
|
*
|
|
|
|
* <none>: normal read access;
|
|
|
|
* WRITE : write access;
|
|
|
|
* ATOMIC: access is atomic;
|
|
|
|
* ASSERT: access is not a regular access, but an assertion;
|
2019-11-14 11:02:54 -07:00
|
|
|
*/
|
2019-11-20 02:41:43 -07:00
|
|
|
#define KCSAN_ACCESS_WRITE 0x1
|
2019-11-14 11:02:54 -07:00
|
|
|
#define KCSAN_ACCESS_ATOMIC 0x2
|
kcsan: Introduce KCSAN_ACCESS_ASSERT access type
The KCSAN_ACCESS_ASSERT access type may be used to introduce dummy reads
and writes to assert certain properties of concurrent code, where bugs
could not be detected as normal data races.
For example, a variable that is only meant to be written by a single
CPU, but may be read (without locking) by other CPUs must still be
marked properly to avoid data races. However, concurrent writes,
regardless if WRITE_ONCE() or not, would be a bug. Using
kcsan_check_access(&x, sizeof(x), KCSAN_ACCESS_ASSERT) would allow
catching such bugs.
To support KCSAN_ACCESS_ASSERT the following notable changes were made:
* If an access is of type KCSAN_ASSERT_ACCESS, disable various filters
that only apply to data races, so that all races that KCSAN observes are
reported.
* Bug reports that involve an ASSERT access type will be reported as
"KCSAN: assert: race in ..." instead of "data-race"; this will help
more easily distinguish them.
* Update a few comments to just mention 'races' where we do not always
mean pure data races.
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2020-02-06 08:46:24 -07:00
|
|
|
#define KCSAN_ACCESS_ASSERT 0x4
|
2019-11-14 11:02:54 -07:00
|
|
|
|
|
|
|
/*
|
2019-11-20 02:41:43 -07:00
|
|
|
* __kcsan_*: Always calls into the runtime when KCSAN is enabled. This may be used
|
2019-11-14 11:02:54 -07:00
|
|
|
* even in compilation units that selectively disable KCSAN, but must use KCSAN
|
2019-11-20 02:41:43 -07:00
|
|
|
* to validate access to an address. Never use these in header files!
|
2019-11-14 11:02:54 -07:00
|
|
|
*/
|
|
|
|
#ifdef CONFIG_KCSAN
|
|
|
|
/**
|
kcsan: Introduce KCSAN_ACCESS_ASSERT access type
The KCSAN_ACCESS_ASSERT access type may be used to introduce dummy reads
and writes to assert certain properties of concurrent code, where bugs
could not be detected as normal data races.
For example, a variable that is only meant to be written by a single
CPU, but may be read (without locking) by other CPUs must still be
marked properly to avoid data races. However, concurrent writes,
regardless if WRITE_ONCE() or not, would be a bug. Using
kcsan_check_access(&x, sizeof(x), KCSAN_ACCESS_ASSERT) would allow
catching such bugs.
To support KCSAN_ACCESS_ASSERT the following notable changes were made:
* If an access is of type KCSAN_ASSERT_ACCESS, disable various filters
that only apply to data races, so that all races that KCSAN observes are
reported.
* Bug reports that involve an ASSERT access type will be reported as
"KCSAN: assert: race in ..." instead of "data-race"; this will help
more easily distinguish them.
* Update a few comments to just mention 'races' where we do not always
mean pure data races.
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2020-02-06 08:46:24 -07:00
|
|
|
* __kcsan_check_access - check generic access for races
|
2019-11-14 11:02:54 -07:00
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* @ptr: address of access
|
|
|
|
* @size: size of access
|
|
|
|
* @type: access type modifier
|
2019-11-14 11:02:54 -07:00
|
|
|
*/
|
|
|
|
void __kcsan_check_access(const volatile void *ptr, size_t size, int type);
|
|
|
|
|
2020-02-11 09:04:19 -07:00
|
|
|
/**
|
|
|
|
* kcsan_nestable_atomic_begin - begin nestable atomic region
|
|
|
|
*
|
|
|
|
* Accesses within the atomic region may appear to race with other accesses but
|
|
|
|
* should be considered atomic.
|
|
|
|
*/
|
|
|
|
void kcsan_nestable_atomic_begin(void);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* kcsan_nestable_atomic_end - end nestable atomic region
|
|
|
|
*/
|
|
|
|
void kcsan_nestable_atomic_end(void);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* kcsan_flat_atomic_begin - begin flat atomic region
|
|
|
|
*
|
|
|
|
* Accesses within the atomic region may appear to race with other accesses but
|
|
|
|
* should be considered atomic.
|
|
|
|
*/
|
|
|
|
void kcsan_flat_atomic_begin(void);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* kcsan_flat_atomic_end - end flat atomic region
|
|
|
|
*/
|
|
|
|
void kcsan_flat_atomic_end(void);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* kcsan_atomic_next - consider following accesses as atomic
|
|
|
|
*
|
|
|
|
* Force treating the next n memory accesses for the current context as atomic
|
|
|
|
* operations.
|
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* @n: number of following memory accesses to treat as atomic.
|
2020-02-11 09:04:19 -07:00
|
|
|
*/
|
|
|
|
void kcsan_atomic_next(int n);
|
|
|
|
|
2020-02-11 09:04:22 -07:00
|
|
|
/**
|
|
|
|
* kcsan_set_access_mask - set access mask
|
|
|
|
*
|
|
|
|
* Set the access mask for all accesses for the current context if non-zero.
|
|
|
|
* Only value changes to bits set in the mask will be reported.
|
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* @mask: bitmask
|
2020-02-11 09:04:22 -07:00
|
|
|
*/
|
|
|
|
void kcsan_set_access_mask(unsigned long mask);
|
|
|
|
|
2020-02-11 09:04:19 -07:00
|
|
|
#else /* CONFIG_KCSAN */
|
|
|
|
|
2019-11-14 11:02:54 -07:00
|
|
|
static inline void __kcsan_check_access(const volatile void *ptr, size_t size,
|
|
|
|
int type) { }
|
2020-02-11 09:04:19 -07:00
|
|
|
|
|
|
|
static inline void kcsan_nestable_atomic_begin(void) { }
|
|
|
|
static inline void kcsan_nestable_atomic_end(void) { }
|
|
|
|
static inline void kcsan_flat_atomic_begin(void) { }
|
|
|
|
static inline void kcsan_flat_atomic_end(void) { }
|
|
|
|
static inline void kcsan_atomic_next(int n) { }
|
2020-02-11 09:04:22 -07:00
|
|
|
static inline void kcsan_set_access_mask(unsigned long mask) { }
|
2020-02-11 09:04:19 -07:00
|
|
|
|
|
|
|
#endif /* CONFIG_KCSAN */
|
2019-11-14 11:02:54 -07:00
|
|
|
|
|
|
|
/*
|
2019-11-20 02:41:43 -07:00
|
|
|
* kcsan_*: Only calls into the runtime when the particular compilation unit has
|
2019-11-14 11:02:54 -07:00
|
|
|
* KCSAN instrumentation enabled. May be used in header files.
|
|
|
|
*/
|
|
|
|
#ifdef __SANITIZE_THREAD__
|
|
|
|
#define kcsan_check_access __kcsan_check_access
|
|
|
|
#else
|
|
|
|
static inline void kcsan_check_access(const volatile void *ptr, size_t size,
|
|
|
|
int type) { }
|
|
|
|
#endif
|
|
|
|
|
|
|
|
/**
|
kcsan: Introduce KCSAN_ACCESS_ASSERT access type
The KCSAN_ACCESS_ASSERT access type may be used to introduce dummy reads
and writes to assert certain properties of concurrent code, where bugs
could not be detected as normal data races.
For example, a variable that is only meant to be written by a single
CPU, but may be read (without locking) by other CPUs must still be
marked properly to avoid data races. However, concurrent writes,
regardless if WRITE_ONCE() or not, would be a bug. Using
kcsan_check_access(&x, sizeof(x), KCSAN_ACCESS_ASSERT) would allow
catching such bugs.
To support KCSAN_ACCESS_ASSERT the following notable changes were made:
* If an access is of type KCSAN_ASSERT_ACCESS, disable various filters
that only apply to data races, so that all races that KCSAN observes are
reported.
* Bug reports that involve an ASSERT access type will be reported as
"KCSAN: assert: race in ..." instead of "data-race"; this will help
more easily distinguish them.
* Update a few comments to just mention 'races' where we do not always
mean pure data races.
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2020-02-06 08:46:24 -07:00
|
|
|
* __kcsan_check_read - check regular read access for races
|
2019-11-14 11:02:54 -07:00
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* @ptr: address of access
|
|
|
|
* @size: size of access
|
2019-11-14 11:02:54 -07:00
|
|
|
*/
|
|
|
|
#define __kcsan_check_read(ptr, size) __kcsan_check_access(ptr, size, 0)
|
|
|
|
|
|
|
|
/**
|
kcsan: Introduce KCSAN_ACCESS_ASSERT access type
The KCSAN_ACCESS_ASSERT access type may be used to introduce dummy reads
and writes to assert certain properties of concurrent code, where bugs
could not be detected as normal data races.
For example, a variable that is only meant to be written by a single
CPU, but may be read (without locking) by other CPUs must still be
marked properly to avoid data races. However, concurrent writes,
regardless if WRITE_ONCE() or not, would be a bug. Using
kcsan_check_access(&x, sizeof(x), KCSAN_ACCESS_ASSERT) would allow
catching such bugs.
To support KCSAN_ACCESS_ASSERT the following notable changes were made:
* If an access is of type KCSAN_ASSERT_ACCESS, disable various filters
that only apply to data races, so that all races that KCSAN observes are
reported.
* Bug reports that involve an ASSERT access type will be reported as
"KCSAN: assert: race in ..." instead of "data-race"; this will help
more easily distinguish them.
* Update a few comments to just mention 'races' where we do not always
mean pure data races.
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2020-02-06 08:46:24 -07:00
|
|
|
* __kcsan_check_write - check regular write access for races
|
2019-11-14 11:02:54 -07:00
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* @ptr: address of access
|
|
|
|
* @size: size of access
|
2019-11-14 11:02:54 -07:00
|
|
|
*/
|
|
|
|
#define __kcsan_check_write(ptr, size) \
|
|
|
|
__kcsan_check_access(ptr, size, KCSAN_ACCESS_WRITE)
|
|
|
|
|
|
|
|
/**
|
kcsan: Introduce KCSAN_ACCESS_ASSERT access type
The KCSAN_ACCESS_ASSERT access type may be used to introduce dummy reads
and writes to assert certain properties of concurrent code, where bugs
could not be detected as normal data races.
For example, a variable that is only meant to be written by a single
CPU, but may be read (without locking) by other CPUs must still be
marked properly to avoid data races. However, concurrent writes,
regardless if WRITE_ONCE() or not, would be a bug. Using
kcsan_check_access(&x, sizeof(x), KCSAN_ACCESS_ASSERT) would allow
catching such bugs.
To support KCSAN_ACCESS_ASSERT the following notable changes were made:
* If an access is of type KCSAN_ASSERT_ACCESS, disable various filters
that only apply to data races, so that all races that KCSAN observes are
reported.
* Bug reports that involve an ASSERT access type will be reported as
"KCSAN: assert: race in ..." instead of "data-race"; this will help
more easily distinguish them.
* Update a few comments to just mention 'races' where we do not always
mean pure data races.
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2020-02-06 08:46:24 -07:00
|
|
|
* kcsan_check_read - check regular read access for races
|
2019-11-14 11:02:54 -07:00
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* @ptr: address of access
|
|
|
|
* @size: size of access
|
2019-11-14 11:02:54 -07:00
|
|
|
*/
|
|
|
|
#define kcsan_check_read(ptr, size) kcsan_check_access(ptr, size, 0)
|
|
|
|
|
|
|
|
/**
|
kcsan: Introduce KCSAN_ACCESS_ASSERT access type
The KCSAN_ACCESS_ASSERT access type may be used to introduce dummy reads
and writes to assert certain properties of concurrent code, where bugs
could not be detected as normal data races.
For example, a variable that is only meant to be written by a single
CPU, but may be read (without locking) by other CPUs must still be
marked properly to avoid data races. However, concurrent writes,
regardless if WRITE_ONCE() or not, would be a bug. Using
kcsan_check_access(&x, sizeof(x), KCSAN_ACCESS_ASSERT) would allow
catching such bugs.
To support KCSAN_ACCESS_ASSERT the following notable changes were made:
* If an access is of type KCSAN_ASSERT_ACCESS, disable various filters
that only apply to data races, so that all races that KCSAN observes are
reported.
* Bug reports that involve an ASSERT access type will be reported as
"KCSAN: assert: race in ..." instead of "data-race"; this will help
more easily distinguish them.
* Update a few comments to just mention 'races' where we do not always
mean pure data races.
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2020-02-06 08:46:24 -07:00
|
|
|
* kcsan_check_write - check regular write access for races
|
2019-11-14 11:02:54 -07:00
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* @ptr: address of access
|
|
|
|
* @size: size of access
|
2019-11-14 11:02:54 -07:00
|
|
|
*/
|
|
|
|
#define kcsan_check_write(ptr, size) \
|
|
|
|
kcsan_check_access(ptr, size, KCSAN_ACCESS_WRITE)
|
|
|
|
|
|
|
|
/*
|
2019-11-20 02:41:43 -07:00
|
|
|
* Check for atomic accesses: if atomic accesses are not ignored, this simply
|
|
|
|
* aliases to kcsan_check_access(), otherwise becomes a no-op.
|
2019-11-14 11:02:54 -07:00
|
|
|
*/
|
|
|
|
#ifdef CONFIG_KCSAN_IGNORE_ATOMICS
|
2019-11-20 02:41:43 -07:00
|
|
|
#define kcsan_check_atomic_read(...) do { } while (0)
|
|
|
|
#define kcsan_check_atomic_write(...) do { } while (0)
|
2019-11-14 11:02:54 -07:00
|
|
|
#else
|
|
|
|
#define kcsan_check_atomic_read(ptr, size) \
|
|
|
|
kcsan_check_access(ptr, size, KCSAN_ACCESS_ATOMIC)
|
|
|
|
#define kcsan_check_atomic_write(ptr, size) \
|
|
|
|
kcsan_check_access(ptr, size, KCSAN_ACCESS_ATOMIC | KCSAN_ACCESS_WRITE)
|
|
|
|
#endif
|
|
|
|
|
2020-02-06 08:46:25 -07:00
|
|
|
/**
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
* ASSERT_EXCLUSIVE_WRITER - assert no concurrent writes to @var
|
2020-02-06 08:46:25 -07:00
|
|
|
*
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
* Assert that there are no concurrent writes to @var; other readers are
|
2020-02-06 08:46:25 -07:00
|
|
|
* allowed. This assertion can be used to specify properties of concurrent code,
|
|
|
|
* where violation cannot be detected as a normal data race.
|
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* For example, if we only have a single writer, but multiple concurrent
|
|
|
|
* readers, to avoid data races, all these accesses must be marked; even
|
|
|
|
* concurrent marked writes racing with the single writer are bugs.
|
|
|
|
* Unfortunately, due to being marked, they are no longer data races. For cases
|
|
|
|
* like these, we can use the macro as follows:
|
2020-02-06 08:46:25 -07:00
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* .. code-block:: c
|
|
|
|
*
|
|
|
|
* void writer(void) {
|
|
|
|
* spin_lock(&update_foo_lock);
|
|
|
|
* ASSERT_EXCLUSIVE_WRITER(shared_foo);
|
|
|
|
* WRITE_ONCE(shared_foo, ...);
|
|
|
|
* spin_unlock(&update_foo_lock);
|
|
|
|
* }
|
|
|
|
* void reader(void) {
|
|
|
|
* // update_foo_lock does not need to be held!
|
|
|
|
* ... = READ_ONCE(shared_foo);
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* @var: variable to assert on
|
2020-02-06 08:46:25 -07:00
|
|
|
*/
|
|
|
|
#define ASSERT_EXCLUSIVE_WRITER(var) \
|
|
|
|
__kcsan_check_access(&(var), sizeof(var), KCSAN_ACCESS_ASSERT)
|
|
|
|
|
|
|
|
/**
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
* ASSERT_EXCLUSIVE_ACCESS - assert no concurrent accesses to @var
|
2020-02-06 08:46:25 -07:00
|
|
|
*
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
* Assert that there are no concurrent accesses to @var (no readers nor
|
|
|
|
* writers). This assertion can be used to specify properties of concurrent
|
|
|
|
* code, where violation cannot be detected as a normal data race.
|
2020-02-06 08:46:25 -07:00
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* For example, where exclusive access is expected after determining no other
|
|
|
|
* users of an object are left, but the object is not actually freed. We can
|
|
|
|
* check that this property actually holds as follows:
|
|
|
|
*
|
|
|
|
* .. code-block:: c
|
2020-02-06 08:46:25 -07:00
|
|
|
*
|
|
|
|
* if (refcount_dec_and_test(&obj->refcnt)) {
|
|
|
|
* ASSERT_EXCLUSIVE_ACCESS(*obj);
|
2020-03-05 07:21:09 -07:00
|
|
|
* do_some_cleanup(obj);
|
|
|
|
* release_for_reuse(obj);
|
2020-02-06 08:46:25 -07:00
|
|
|
* }
|
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* Note: For cases where the object is freed, `KASAN <kasan.html>`_ is a better
|
|
|
|
* fit to detect use-after-free bugs.
|
|
|
|
*
|
|
|
|
* @var: variable to assert on
|
2020-02-06 08:46:25 -07:00
|
|
|
*/
|
|
|
|
#define ASSERT_EXCLUSIVE_ACCESS(var) \
|
|
|
|
__kcsan_check_access(&(var), sizeof(var), KCSAN_ACCESS_WRITE | KCSAN_ACCESS_ASSERT)
|
|
|
|
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
/**
|
|
|
|
* ASSERT_EXCLUSIVE_BITS - assert no concurrent writes to subset of bits in @var
|
|
|
|
*
|
|
|
|
* Bit-granular variant of ASSERT_EXCLUSIVE_WRITER(var).
|
|
|
|
*
|
|
|
|
* Assert that there are no concurrent writes to a subset of bits in @var;
|
|
|
|
* concurrent readers are permitted. This assertion captures more detailed
|
|
|
|
* bit-level properties, compared to the other (word granularity) assertions.
|
|
|
|
* Only the bits set in @mask are checked for concurrent modifications, while
|
2020-03-05 07:21:09 -07:00
|
|
|
* ignoring the remaining bits, i.e. concurrent writes (or reads) to ~mask bits
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
* are ignored.
|
|
|
|
*
|
|
|
|
* Use this for variables, where some bits must not be modified concurrently,
|
|
|
|
* yet other bits are expected to be modified concurrently.
|
|
|
|
*
|
|
|
|
* For example, variables where, after initialization, some bits are read-only,
|
|
|
|
* but other bits may still be modified concurrently. A reader may wish to
|
|
|
|
* assert that this is true as follows:
|
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* .. code-block:: c
|
|
|
|
*
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
* ASSERT_EXCLUSIVE_BITS(flags, READ_ONLY_MASK);
|
|
|
|
* foo = (READ_ONCE(flags) & READ_ONLY_MASK) >> READ_ONLY_SHIFT;
|
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* Note: The access that immediately follows ASSERT_EXCLUSIVE_BITS() is assumed
|
|
|
|
* to access the masked bits only, and KCSAN optimistically assumes it is
|
|
|
|
* therefore safe, even in the presence of data races, and marking it with
|
|
|
|
* READ_ONCE() is optional from KCSAN's point-of-view. We caution, however, that
|
|
|
|
* it may still be advisable to do so, since we cannot reason about all compiler
|
|
|
|
* optimizations when it comes to bit manipulations (on the reader and writer
|
|
|
|
* side). If you are sure nothing can go wrong, we can write the above simply
|
|
|
|
* as:
|
|
|
|
*
|
|
|
|
* .. code-block:: c
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
*
|
|
|
|
* ASSERT_EXCLUSIVE_BITS(flags, READ_ONLY_MASK);
|
|
|
|
* foo = (flags & READ_ONLY_MASK) >> READ_ONLY_SHIFT;
|
|
|
|
*
|
|
|
|
* Another example, where this may be used, is when certain bits of @var may
|
|
|
|
* only be modified when holding the appropriate lock, but other bits may still
|
|
|
|
* be modified concurrently. Writers, where other bits may change concurrently,
|
|
|
|
* could use the assertion as follows:
|
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* .. code-block:: c
|
|
|
|
*
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
* spin_lock(&foo_lock);
|
|
|
|
* ASSERT_EXCLUSIVE_BITS(flags, FOO_MASK);
|
2020-03-05 07:21:09 -07:00
|
|
|
* old_flags = flags;
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
* new_flags = (old_flags & ~FOO_MASK) | (new_foo << FOO_SHIFT);
|
|
|
|
* if (cmpxchg(&flags, old_flags, new_flags) != old_flags) { ... }
|
|
|
|
* spin_unlock(&foo_lock);
|
|
|
|
*
|
2020-03-05 07:21:09 -07:00
|
|
|
* @var: variable to assert on
|
|
|
|
* @mask: only check for modifications to bits set in @mask
|
kcsan: Introduce ASSERT_EXCLUSIVE_BITS(var, mask)
This introduces ASSERT_EXCLUSIVE_BITS(var, mask).
ASSERT_EXCLUSIVE_BITS(var, mask) will cause KCSAN to assume that the
following access is safe w.r.t. data races (however, please see the
docbook comment for disclaimer here).
For more context on why this was considered necessary, please see:
http://lkml.kernel.org/r/1580995070-25139-1-git-send-email-cai@lca.pw
In particular, before this patch, data races between reads (that use
@mask bits of an access that should not be modified concurrently) and
writes (that change ~@mask bits not used by the readers) would have been
annotated with "data_race()" (or "READ_ONCE()"). However, doing so would
then hide real problems: we would no longer be able to detect harmful
races between reads to @mask bits and writes to @mask bits.
Therefore, by using ASSERT_EXCLUSIVE_BITS(var, mask), we accomplish:
1. Avoid proliferation of specific macros at the call sites: by
including a single mask in the argument list, we can use the same
macro in a wide variety of call sites, regardless of how and which
bits in a field each call site actually accesses.
2. The existing code does not need to be modified (although READ_ONCE()
may still be advisable if we cannot prove that the data race is
always safe).
3. We catch bugs where the exclusive bits are modified concurrently.
4. We document properties of the current code.
Acked-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: David Hildenbrand <david@redhat.com>
Cc: Jan Kara <jack@suse.cz>
Cc: Qian Cai <cai@lca.pw>
2020-02-11 09:04:23 -07:00
|
|
|
*/
|
|
|
|
#define ASSERT_EXCLUSIVE_BITS(var, mask) \
|
|
|
|
do { \
|
|
|
|
kcsan_set_access_mask(mask); \
|
|
|
|
__kcsan_check_access(&(var), sizeof(var), KCSAN_ACCESS_ASSERT);\
|
|
|
|
kcsan_set_access_mask(0); \
|
|
|
|
kcsan_atomic_next(1); \
|
|
|
|
} while (0)
|
|
|
|
|
2019-11-14 11:02:54 -07:00
|
|
|
#endif /* _LINUX_KCSAN_CHECKS_H */
|