[PATCH v2 24/34] compiler-capability-analysis: Introduce header suppressions

Marco Elver
2025-03-04T09:26:15Z

While we can opt in individual subsystems which add the required
annotations, such subsystems inevitably include headers from other
subsystems which may not yet have the right annotations, which then
result in false positive warnings.

Making compatible by adding annotations across all common headers
currently requires an excessive number of __no_capability_analysis
annotations, or carefully analyzing non-trivial cases to add the correct
annotations. While this is desirable long-term, providing an incremental
path causes less churn and headaches for maintainers not yet interested
in dealing with such warnings.

Rather than clutter headers unnecessary and mandate all subsystem
maintainers to keep their headers working with capability analysis,
suppress all -Wthread-safety warnings in headers. Explicitly opt in
headers with capability-enabled primitives.

This bumps the required Clang version to version 20+.

With this in place, we can start enabling the analysis on more complex
subsystems in subsequent changes.

Signed-off-by: Marco Elver <elver@google.com>
---
.../dev-tools/capability-analysis.rst | 2 ++
lib/Kconfig.debug | 4 ++-
scripts/Makefile.capability-analysis | 4 +++
scripts/capability-analysis-suppression.txt | 32 +++++++++++++++++++
4 files changed, 41 insertions(+), 1 deletion(-)
create mode 100644 scripts/capability-analysis-suppression.txt

diff --git a/Documentation/dev-tools/capability-analysis.rst b/Documentation/dev-tools/capability-analysis.rst
index d11e88ab9882..5c87d7659995 100644
--- a/Documentation/dev-tools/capability-analysis.rst
+++ b/Documentation/dev-tools/capability-analysis.rst
@@ -17,6 +17,8 @@ features. To enable for Clang, configure the kernel with::

CONFIG_WARN_CAPABILITY_ANALYSIS=y

+The feature requires Clang 20 or later.
+
The analysis is *opt-in by default*, and requires declaring which modules and
subsystems should be analyzed in the respective `Makefile`::

diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index 8abaf7dab3f8..8b13353517a9 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -605,7 +605,7 @@ config DEBUG_FORCE_WEAK_PER_CPU

config WARN_CAPABILITY_ANALYSIS
bool "Compiler capability-analysis warnings"
- depends on CC_IS_CLANG && $(cc-option,-Wthread-safety -fexperimental-late-parse-attributes)
+ depends on CC_IS_CLANG && $(cc-option,-Wthread-safety -fexperimental-late-parse-attributes --warning-suppression-mappings=/dev/null)
# Branch profiling re-defines "if", which messes with the compiler's
# ability to analyze __cond_acquires(..), resulting in false positives.
depends on !TRACE_BRANCH_PROFILING
@@ -619,6 +619,8 @@ config WARN_CAPABILITY_ANALYSIS
the original name of the feature; it was later expanded to be a
generic "Capability Analysis" framework.

+ Requires Clang 20 or later.
+
Produces warnings by default. Select CONFIG_WERROR if you wish to
turn these warnings into errors.

diff --git a/scripts/Makefile.capability-analysis b/scripts/Makefile.capability-analysis
index b7b36cca47f4..2a3e493a9d06 100644
--- a/scripts/Makefile.capability-analysis
+++ b/scripts/Makefile.capability-analysis
@@ -4,4 +4,8 @@ capability-analysis-cflags := -DWARN_CAPABILITY_ANALYSIS \
-fexperimental-late-parse-attributes -Wthread-safety \
$(call cc-option,-Wthread-safety-pointer)

+ifndef CONFIG_WARN_CAPABILITY_ANALYSIS_ALL
+capability-analysis-cflags += --warning-suppression-mappings=$(srctree)/scripts/capability-analysis-suppression.txt
+endif
+
export CFLAGS_CAPABILITY_ANALYSIS := $(capability-analysis-cflags)
diff --git a/scripts/capability-analysis-suppression.txt b/scripts/capability-analysis-suppression.txt
new file mode 100644
index 000000000000..0a5392fee710
--- /dev/null
+++ b/scripts/capability-analysis-suppression.txt
@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# The suppressions file should only match common paths such as header files.
+# For individual subsytems use Makefile directive CAPABILITY_ANALYSIS := [yn].
+#
+# The suppressions are ignored when CONFIG_WARN_CAPABILITY_ANALYSIS_ALL is
+# selected.
+
+[thread-safety]
+src:*arch/*/include/*
+src:*include/acpi/*
+src:*include/asm-generic/*
+src:*include/linux/*
+src:*include/net/*
+
+# Opt-in headers:
+src:*include/linux/bit_spinlock.h=emit
+src:*include/linux/cleanup.h=emit
+src:*include/linux/kref.h=emit
+src:*include/linux/list*.h=emit
+src:*include/linux/local_lock*.h=emit
+src:*include/linux/lockdep.h=emit
+src:*include/linux/mutex*.h=emit
+src:*include/linux/rcupdate.h=emit
+src:*include/linux/refcount.h=emit
+src:*include/linux/rhashtable.h=emit
+src:*include/linux/rwlock*.h=emit
+src:*include/linux/rwsem.h=emit
+src:*include/linux/seqlock*.h=emit
+src:*include/linux/spinlock*.h=emit
+src:*include/linux/srcu.h=emit
+src:*include/linux/ww_mutex.h=emit