ASSERT_EXCLUSIVE_BITS(9)

📦 version 7.3.1, in nixpkgs unstable

💖 ASSERT_EXCLUSIVE_BITS(9) 💖

okay so bestie, welcome to the ASSERT_EXCLUSIVE_BITS(9) page from the Kernel API Manual — this one is all about checking a subset of bits in a variable and making sure nobody is out here writing to them concurrently. it's giving tiny-bit-level bodyguard energy 💅✨

✨ NAME ✨

ASSERT_EXCLUSIVE_BITS — assert no concurrent writes to subset of bits in @var 🎀

🦋 SYNOPSIS 🦋

ASSERT_EXCLUSIVE_BITS (var , mask );

🌸 ARGUMENTS 🌸

  • var — variable to assert on, bestie
  • mask — only check for modifications to bits set in mask

💜 DESCRIPTION 💜

This is the bit-granular variant of ASSERT_EXCLUSIVE_WRITER. slay.

It asserts 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 ignoring the remaining bits, i.e. concurrent writes (or reads) to ~mask bits are ignored. periodt.

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:

ASSERT_EXCLUSIVE_BITS(flags, READ_ONLY_MASK);
foo = (READ_ONCE(flags) & READ_ONLY_MASK) >> READ_ONLY_SHIFT;

🎀 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:

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:

spin_lock(foo_lock);
ASSERT_EXCLUSIVE_BITS(flags, FOO_MASK);
old_flags = flags;
new_flags = (old_flags & ~FOO_MASK) | (new_foo << FOO_SHIFT);
if (cmpxchg(flags, old_flags, new_flags) != old_flags) { ... }
spin_unlock(foo_lock);

🌈 SEE ALSO 🌈

Kernel file ./include/linux/kcsan-checks.h — and the whole KCSAN bestie lineup:

mwah 💋 this page is from ./include/linux, dated October 2026, and it's literally titled ASSERT_EXCLUSIVE_BITS(9) — catch you in the next page, bestie 🫶💖

📦 where this page comes from