[RFC PATCH 0/4] kcsan: add targeted watchpoint sampling

[RFC PATCH 0/4] kcsan: add targeted watchpoint sampling

[Hui Su]

Hi,

While investigating a low-frequency scheduler access around `calc_load_idx` in
`kernel/sched/loadavg.c`, I found that KCSAN's per-CPU `kcsan.skip_watch`
interval can make focused reproduction difficult. Unrelated instrumented
accesses on the same CPUs may consume the interval before execution reaches a
known suspicious address. This is a limitation in focused-debugging control;
the proposal leaves the default sampling policy unchanged.

Setting `kcsan.skip_watch=0` removes the interval globally and can make
watchpoint setup much more frequent for all eligible accesses. The existing
debugfs whitelist and blacklist filter which reports are emitted after
watchpoint selection; they do not select which addresses may set up a
watchpoint. There is currently no runtime control to focus setup attempts on
one known address while leaving unrelated accesses out of that selection.

This RFC adds an optional single-address target to the KCSAN debugfs
interface. When enabled, a non-atomic access is eligible to set up a watchpoint
only when its byte range contains the target address. Matching accesses bypass
the normal `kcsan.skip_watch` interval; nonmatching accesses neither set up a
watchpoint nor consume that interval. The target can be specified as an address
or a kallsyms symbol, including `module:symbol`; `target=off` restores normal
sampling. A static key guards the disabled path.

Patch 1 adds single-address target matching and the static-key-guarded runtime
state. Patch 2 exposes address and symbol targets through debugfs, patch 3
tests the matching semantics, and patch 4 documents the interface and its
performance implications. The standalone integration module used for runtime
checks is local and is not included in the series.

Testing:
- x86_64 GCC and Clang `bzImage modules` builds completed, and the candidate's
  built-in KCSAN selftest passed 4/4. Runtime validation recorded setup
  activity for exact-address and `module:symbol` targets, none for a
  nonmatching target, and normal sampling after `target=off`.
- In a separate motivating loadavg run, targeting `calc_load_idx` produced a
  KCSAN report involving `calc_global_load()` and `calc_load_nohz_start()`. A
  separate upstream run with the default `skip_watch=4000` did not report
  those locations during its test window.
- Across 10 rounds of 1,000,000 accesses, medians were `24.549 ns/access`
  upstream, `24.654 ns/access` with targeting disabled, and `26.981 ns/access`
  with an enabled nonmatching target. The disabled-path results were
  indistinguishable at this measurement granularity. A separate 10-round,
  10,000-access hot-match run measured `81.1 us/access`: every matching
  access enters `kcsan_setup_watchpoint()`, so this includes setup slow-path
  work and represents focused debugging rather than normal use.

Questions for discussion:
1. Is address-targeted watchpoint sampling a useful primitive for focused
   KCSAN debugging?
2. Should matching accesses bypass the normal `kcsan.skip_watch` interval, as
   proposed here, or should targeted mode retain its own sampling interval?
3. Is the existing KCSAN debugfs file an appropriate interface for configuring
   a single target?

Hui Su (4):
  kcsan: add targeted watchpoint matching
  kcsan: add debugfs target control
  kcsan: add targeted watchpoint selftest
  docs: kcsan: document targeted watchpoint sampling

 Documentation/dev-tools/kcsan.rst | 17 ++++++++++++++
 kernel/kcsan/core.c               | 37 +++++++++++++++++++++++++++++++
 kernel/kcsan/debugfs.c            | 28 ++++++++++++++++++++++-
 kernel/kcsan/kcsan.h              | 10 +++++++++
 kernel/kcsan/selftest.c           | 29 ++++++++++++++++++++++++
 5 files changed, 120 insertions(+), 1 deletion(-)


base-commit: 4056b3c9d3c92ea45955641dbafeb9b960e146ef
-- 
2.55.0

Re: [RFC PATCH 0/4] kcsan: add targeted watchpoint sampling

[Hui Su]

Apologies, the individual patches were accidentally sent as separate
top-level messages instead of being threaded under this cover letter.

I won't resend the series to avoid duplicates. For convenience, the
individual patches are:

[1/4] kcsan: add targeted watchpoint matching
https://lore.kernel.org/all/20261014095238.2132580-2-sh_def@163.com/

[2/4] kcsan: add debugfs target control
https://lore.kernel.org/all/20261014095238.2132580-3-sh_def@163.com/

[3/4] kcsan: add targeted watchpoint selftest
https://lore.kernel.org/all/20261014095238.2132580-4-sh_def@163.com/

[4/4] docs: kcsan: document targeted watchpoint sampling
https://lore.kernel.org/all/20261014095238.2132580-5-sh_def@163.com/

I'll make sure the next revision is properly threaded.

Re: [RFC PATCH 0/4] kcsan: add targeted watchpoint sampling

[Marco Elver]

On Wed, 14 Oct 2026 at 11:52, Hui Su <sh_def@163.com> wrote:
>
> Hi,
>
> While investigating a low-frequency scheduler access around `calc_load_idx` in
> `kernel/sched/loadavg.c`, I found that KCSAN's per-CPU `kcsan.skip_watch`
> interval can make focused reproduction difficult. Unrelated instrumented
> accesses on the same CPUs may consume the interval before execution reaches a
> known suspicious address. This is a limitation in focused-debugging control;
> the proposal leaves the default sampling policy unchanged.
>
> Setting `kcsan.skip_watch=0` removes the interval globally and can make
> watchpoint setup much more frequent for all eligible accesses. The existing
> debugfs whitelist and blacklist filter which reports are emitted after
> watchpoint selection; they do not select which addresses may set up a
> watchpoint. There is currently no runtime control to focus setup attempts on
> one known address while leaving unrelated accesses out of that selection.
>
> This RFC adds an optional single-address target to the KCSAN debugfs
> interface. When enabled, a non-atomic access is eligible to set up a watchpoint
> only when its byte range contains the target address. Matching accesses bypass
> the normal `kcsan.skip_watch` interval; nonmatching accesses neither set up a
> watchpoint nor consume that interval. The target can be specified as an address
> or a kallsyms symbol, including `module:symbol`; `target=off` restores normal
> sampling. A static key guards the disabled path.
>
> Patch 1 adds single-address target matching and the static-key-guarded runtime
> state. Patch 2 exposes address and symbol targets through debugfs, patch 3
> tests the matching semantics, and patch 4 documents the interface and its
> performance implications. The standalone integration module used for runtime
> checks is local and is not included in the series.
>
> Testing:
> - x86_64 GCC and Clang `bzImage modules` builds completed, and the candidate's
>   built-in KCSAN selftest passed 4/4. Runtime validation recorded setup
>   activity for exact-address and `module:symbol` targets, none for a
>   nonmatching target, and normal sampling after `target=off`.
> - In a separate motivating loadavg run, targeting `calc_load_idx` produced a
>   KCSAN report involving `calc_global_load()` and `calc_load_nohz_start()`. A
>   separate upstream run with the default `skip_watch=4000` did not report
>   those locations during its test window.
> - Across 10 rounds of 1,000,000 accesses, medians were `24.549 ns/access`
>   upstream, `24.654 ns/access` with targeting disabled, and `26.981 ns/access`
>   with an enabled nonmatching target. The disabled-path results were
>   indistinguishable at this measurement granularity. A separate 10-round,
>   10,000-access hot-match run measured `81.1 us/access`: every matching
>   access enters `kcsan_setup_watchpoint()`, so this includes setup slow-path
>   work and represents focused debugging rather than normal use.

You should compare fast path disasm before/after, just to make codegen
isn't adversely affected.

> Questions for discussion:
> 1. Is address-targeted watchpoint sampling a useful primitive for focused
>    KCSAN debugging?

On surface, it seems helpful.

But there's another angle: The need for reproduction arises because we
want to debug an issue, and the fix it with a code change; after the
code change and a recompile, are there new data races that were
introduced as a side-effect? Perhaps the original data race you were
hunting is gone, but new ones may have been introduced. So my approach
has never been to try and focus on a single data race, but look for
data races that may have appeared adjacent to code I touched
(filtering based on function name). The method of reproduction are
stress tests that more or less reliably trigger the original data
race, but should also trigger data races (if they exist) adjacent to
the code being scrutinized.

But perhaps what you're after is asking "are all accesses to this
variable data race free" only?

> 2. Should matching accesses bypass the normal `kcsan.skip_watch` interval, as
>    proposed here, or should targeted mode retain its own sampling interval?

It might become quite slow for frequently accessed data, but perhaps
that's intentional if we want maximum races detected for focused
testing.

> 3. Is the existing KCSAN debugfs file an appropriate interface for configuring
>    a single target?

This looks clean enough.

Re: [RFC PATCH 0/4] kcsan: add targeted watchpoint sampling

[Hui Su]

> You should compare fast path disasm before/after, just to make codegen
> isn't adversely affected.

I also checked the x86-64 fast-path code generation as suggested. In
paired GCC and Clang comparisons, I found no new calls, stack spills,
stack-frame adjustment, or callee-saved register saves on the disabled
path. The detailed `__tsan_read8` disassembly comparison is in my reply to
patch 1:

https://lore.kernel.org/lkml/179207802520.771660.5931695730876285158@163.com/

> Questions for discussion:
> 1. Is address-targeted watchpoint sampling a useful primitive for focused
>    KCSAN debugging?
>
> On surface, it seems helpful.
>
> But there's another angle: The need for reproduction arises because we
> want to debug an issue, and the fix it with a code change; after the
> code change and a recompile, are there new data races that were
> introduced as a side-effect? Perhaps the original data race you were
> hunting is gone, but new ones may have been introduced. So my approach
> has never been to try and focus on a single data race, but look for
> data races that may have appeared adjacent to code I touched
> (filtering based on function name). The method of reproduction are
> stress tests that more or less reliably trigger the original data
> race, but should also trigger data races (if they exist) adjacent to
> the code being scrutinized.
>
> But perhaps what you're after is asking "are all accesses to this
> variable data race free" only?

Not exactly. This interface is not intended to prove that all accesses
to a variable are race-free. The motivating use case is narrower: after
a reproducer or report points to a suspicious address, make accesses
overlapping that address eligible for watchpoint setup without unrelated
accesses consuming the skip interval.

I agree that function-scoped filtering and stress testing remain useful
for looking for races around code changed in a fix. Targeted mode is
complementary to that workflow when a known low-frequency location is
difficult to reproduce.

In the motivating loadavg run, targeting `calc_load_idx` produced a KCSAN
report involving `calc_global_load()` and `calc_load_nohz_start()`. A separate
upstream run with the default `kcsan.skip_watch=4000` did not report those
locations during its test window. This is evidence for that workload and
window, not proof that the accesses are race-free when no report appears.

> 2. Should matching accesses bypass the normal `kcsan.skip_watch` interval, as
>    proposed here, or should targeted mode retain its own sampling interval?
>
> It might become quite slow for frequently accessed data, but perhaps
> that's intentional if we want maximum races detected for focused
> testing.

Yes, bypassing the normal `kcsan.skip_watch` interval for matching
accesses is the intended tradeoff in this RFC. Nonmatching accesses
neither set up a watchpoint nor consume that interval. `target=off`
restores normal sampling. Targeted mode is intended for focused debugging,
not steady-state use.

The hot-target cost is therefore expected. In the RFC measurements an
enabled nonmatching target was 26.981 ns/access versus 24.549 ns/access
upstream, while a deliberately hot matching target measured 81.1 us/access
because every matching access entered `kcsan_setup_watchpoint()`.

> 3. Is the existing KCSAN debugfs file an appropriate interface for configuring
>    a single target?
>
> This looks clean enough.

Thanks. I'll keep the debugfs interface as proposed.