Describe the KCSAN debugfs target interface, including address and kallsyms symbol forms, module symbols, disabling the target, and how it relates to report filters. Clarify CONFIG_KALLSYMS_ALL requirements and that a symbol target selects only the symbol start address. Warn about hot-target overhead and clear the target before unloading a module that owns the address.
Signed-off-by: Hui Su <[email protected]> --- Documentation/dev-tools/kcsan.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 8575178aa87f..53cc3e5bc1f0 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -169,6 +169,23 @@ The file ``/sys/kernel/debug/kcsan`` provides the following interface: can be used to silence frequently occurring data races; the whitelist feature can help with reproduction and testing of fixes. +* Writing ``target=<address>`` or ``target=<symbol>`` to + ``/sys/kernel/debug/kcsan`` enables targeted watchpoint sampling for one + address. An instrumented access is eligible for watchpoint setup when its + byte range contains the selected address. While targeted sampling is active, + non-target accesses do not consume the per-CPU ``kcsan.skip_watch`` interval. + Symbol targets are resolved using kallsyms. Naming vmlinux data symbols + requires ``CONFIG_KALLSYMS_ALL``, and module symbols use ``module:symbol``. + A symbol target selects the symbol's start address, not the full object. + Marked atomic accesses remain ineligible for watchpoint setup. This controls + watchpoint setup and is independent of report whitelist/blacklist filtering. + Write ``target=off`` to restore normal sampling. + Matching accesses bypass the normal skip interval, so targeting a hot + address can significantly increase KCSAN overhead. Use targeted sampling to + focus debugging on a known suspicious location. + The target does not hold a module reference; clear it before unloading a + module that owns the selected address. + Tuning performance ~~~~~~~~~~~~~~~~~~ -- 2.55.0
