From de15fecae44df8254fa597bad7eb3680a8b1c10c Mon Sep 17 00:00:00 2001 From: Marco Elver Date: Fri, 19 Dec 2025 16:39:50 +0100 Subject: compiler_types: Move lock checking attributes to compiler-context-analysis.h The conditional definition of lock checking macros and attributes is about to become more complex. Factor them out into their own header for better readability, and to make it obvious which features are supported by which mode (currently only Sparse). This is the first step towards generalizing towards "context analysis". No functional change intended. Signed-off-by: Marco Elver Signed-off-by: Peter Zijlstra (Intel) Reviewed-by: Bart Van Assche Link: https://patch.msgid.link/20251219154418.3592607-2-elver@google.com --- include/linux/compiler-context-analysis.h | 32 +++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 include/linux/compiler-context-analysis.h (limited to 'include/linux/compiler-context-analysis.h') diff --git a/include/linux/compiler-context-analysis.h b/include/linux/compiler-context-analysis.h new file mode 100644 index 000000000000..f8af63045281 --- /dev/null +++ b/include/linux/compiler-context-analysis.h @@ -0,0 +1,32 @@ +/* SPDX-License-Identifier: GPL-2.0 */ +/* + * Macros and attributes for compiler-based static context analysis. + */ + +#ifndef _LINUX_COMPILER_CONTEXT_ANALYSIS_H +#define _LINUX_COMPILER_CONTEXT_ANALYSIS_H + +#ifdef __CHECKER__ + +/* Sparse context/lock checking support. */ +# define __must_hold(x) __attribute__((context(x,1,1))) +# define __acquires(x) __attribute__((context(x,0,1))) +# define __cond_acquires(x) __attribute__((context(x,0,-1))) +# define __releases(x) __attribute__((context(x,1,0))) +# define __acquire(x) __context__(x,1) +# define __release(x) __context__(x,-1) +# define __cond_lock(x, c) ((c) ? ({ __acquire(x); 1; }) : 0) + +#else /* !__CHECKER__ */ + +# define __must_hold(x) +# define __acquires(x) +# define __cond_acquires(x) +# define __releases(x) +# define __acquire(x) (void)0 +# define __release(x) (void)0 +# define __cond_lock(x, c) (c) + +#endif /* __CHECKER__ */ + +#endif /* _LINUX_COMPILER_CONTEXT_ANALYSIS_H */ -- cgit v1.2.3 From 3269701cb25662ae8a9771a864201116626adb50 Mon Sep 17 00:00:00 2001 From: Marco Elver Date: Fri, 19 Dec 2025 16:39:51 +0100 Subject: compiler-context-analysis: Add infrastructure for Context Analysis with Clang Context Analysis is a language extension, which enables statically checking that required contexts are active (or inactive), by acquiring and releasing user-definable "context locks". An obvious application is lock-safety checking for the kernel's various synchronization primitives (each of which represents a "context lock"), and checking that locking rules are not violated. Clang originally called the feature "Thread Safety Analysis" [1]. This was later changed and the feature became more flexible, gaining the ability to define custom "capabilities". Its foundations can be found in "Capability Systems" [2], used to specify the permissibility of operations to depend on some "capability" being held (or not held). Because the feature is not just able to express "capabilities" related to synchronization primitives, and "capability" is already overloaded in the kernel, the naming chosen for the kernel departs from Clang's "Thread Safety" and "capability" nomenclature; we refer to the feature as "Context Analysis" to avoid confusion. The internal implementation still makes references to Clang's terminology in a few places, such as `-Wthread-safety` being the warning option that also still appears in diagnostic messages. [1] https://clang.llvm.org/docs/ThreadSafetyAnalysis.html [2] https://www.cs.cornell.edu/talc/papers/capabilities.pdf See more details in the kernel-doc documentation added in this and subsequent changes. Clang version 22+ is required. [peterz: disable the thing for __CHECKER__ builds] Signed-off-by: Marco Elver Signed-off-by: Peter Zijlstra (Intel) Link: https://patch.msgid.link/20251219154418.3592607-3-elver@google.com --- include/linux/compiler-context-analysis.h | 464 +++++++++++++++++++++++++++++- 1 file changed, 457 insertions(+), 7 deletions(-) (limited to 'include/linux/compiler-context-analysis.h') diff --git a/include/linux/compiler-context-analysis.h b/include/linux/compiler-context-analysis.h index f8af63045281..d0b3cf0ebfe9 100644 --- a/include/linux/compiler-context-analysis.h +++ b/include/linux/compiler-context-analysis.h @@ -6,27 +6,477 @@ #ifndef _LINUX_COMPILER_CONTEXT_ANALYSIS_H #define _LINUX_COMPILER_CONTEXT_ANALYSIS_H +#if defined(WARN_CONTEXT_ANALYSIS) && !defined(__CHECKER__) + +/* + * These attributes define new context lock (Clang: capability) types. + * Internal only. + */ +# define __ctx_lock_type(name) __attribute__((capability(#name))) +# define __reentrant_ctx_lock __attribute__((reentrant_capability)) +# define __acquires_ctx_lock(...) __attribute__((acquire_capability(__VA_ARGS__))) +# define __acquires_shared_ctx_lock(...) __attribute__((acquire_shared_capability(__VA_ARGS__))) +# define __try_acquires_ctx_lock(ret, var) __attribute__((try_acquire_capability(ret, var))) +# define __try_acquires_shared_ctx_lock(ret, var) __attribute__((try_acquire_shared_capability(ret, var))) +# define __releases_ctx_lock(...) __attribute__((release_capability(__VA_ARGS__))) +# define __releases_shared_ctx_lock(...) __attribute__((release_shared_capability(__VA_ARGS__))) +# define __returns_ctx_lock(var) __attribute__((lock_returned(var))) + +/* + * The below are used to annotate code being checked. Internal only. + */ +# define __excludes_ctx_lock(...) __attribute__((locks_excluded(__VA_ARGS__))) +# define __requires_ctx_lock(...) __attribute__((requires_capability(__VA_ARGS__))) +# define __requires_shared_ctx_lock(...) __attribute__((requires_shared_capability(__VA_ARGS__))) + +/* + * The "assert_capability" attribute is a bit confusingly named. It does not + * generate a check. Instead, it tells the analysis to *assume* the capability + * is held. This is used for: + * + * 1. Augmenting runtime assertions, that can then help with patterns beyond the + * compiler's static reasoning abilities. + * + * 2. Initialization of context locks, so we can access guarded variables right + * after initialization (nothing else should access the same object yet). + */ +# define __assumes_ctx_lock(...) __attribute__((assert_capability(__VA_ARGS__))) +# define __assumes_shared_ctx_lock(...) __attribute__((assert_shared_capability(__VA_ARGS__))) + +/** + * __guarded_by - struct member and globals attribute, declares variable + * only accessible within active context + * + * Declares that the struct member or global variable is only accessible within + * the context entered by the given context lock. Read operations on the data + * require shared access, while write operations require exclusive access. + * + * .. code-block:: c + * + * struct some_state { + * spinlock_t lock; + * long counter __guarded_by(&lock); + * }; + */ +# define __guarded_by(...) __attribute__((guarded_by(__VA_ARGS__))) + +/** + * __pt_guarded_by - struct member and globals attribute, declares pointed-to + * data only accessible within active context + * + * Declares that the data pointed to by the struct member pointer or global + * pointer is only accessible within the context entered by the given context + * lock. Read operations on the data require shared access, while write + * operations require exclusive access. + * + * .. code-block:: c + * + * struct some_state { + * spinlock_t lock; + * long *counter __pt_guarded_by(&lock); + * }; + */ +# define __pt_guarded_by(...) __attribute__((pt_guarded_by(__VA_ARGS__))) + +/** + * context_lock_struct() - declare or define a context lock struct + * @name: struct name + * + * Helper to declare or define a struct type that is also a context lock. + * + * .. code-block:: c + * + * context_lock_struct(my_handle) { + * int foo; + * long bar; + * }; + * + * struct some_state { + * ... + * }; + * // ... declared elsewhere ... + * context_lock_struct(some_state); + * + * Note: The implementation defines several helper functions that can acquire + * and release the context lock. + */ +# define context_lock_struct(name, ...) \ + struct __ctx_lock_type(name) __VA_ARGS__ name; \ + static __always_inline void __acquire_ctx_lock(const struct name *var) \ + __attribute__((overloadable)) __no_context_analysis __acquires_ctx_lock(var) { } \ + static __always_inline void __acquire_shared_ctx_lock(const struct name *var) \ + __attribute__((overloadable)) __no_context_analysis __acquires_shared_ctx_lock(var) { } \ + static __always_inline bool __try_acquire_ctx_lock(const struct name *var, bool ret) \ + __attribute__((overloadable)) __no_context_analysis __try_acquires_ctx_lock(1, var) \ + { return ret; } \ + static __always_inline bool __try_acquire_shared_ctx_lock(const struct name *var, bool ret) \ + __attribute__((overloadable)) __no_context_analysis __try_acquires_shared_ctx_lock(1, var) \ + { return ret; } \ + static __always_inline void __release_ctx_lock(const struct name *var) \ + __attribute__((overloadable)) __no_context_analysis __releases_ctx_lock(var) { } \ + static __always_inline void __release_shared_ctx_lock(const struct name *var) \ + __attribute__((overloadable)) __no_context_analysis __releases_shared_ctx_lock(var) { } \ + static __always_inline void __assume_ctx_lock(const struct name *var) \ + __attribute__((overloadable)) __assumes_ctx_lock(var) { } \ + static __always_inline void __assume_shared_ctx_lock(const struct name *var) \ + __attribute__((overloadable)) __assumes_shared_ctx_lock(var) { } \ + struct name + +/** + * disable_context_analysis() - disables context analysis + * + * Disables context analysis. Must be paired with a later + * enable_context_analysis(). + */ +# define disable_context_analysis() \ + __diag_push(); \ + __diag_ignore_all("-Wunknown-warning-option", "") \ + __diag_ignore_all("-Wthread-safety", "") \ + __diag_ignore_all("-Wthread-safety-pointer", "") + +/** + * enable_context_analysis() - re-enables context analysis + * + * Re-enables context analysis. Must be paired with a prior + * disable_context_analysis(). + */ +# define enable_context_analysis() __diag_pop() + +/** + * __no_context_analysis - function attribute, disables context analysis + * + * Function attribute denoting that context analysis is disabled for the + * whole function. Prefer use of `context_unsafe()` where possible. + */ +# define __no_context_analysis __attribute__((no_thread_safety_analysis)) + +#else /* !WARN_CONTEXT_ANALYSIS */ + +# define __ctx_lock_type(name) +# define __reentrant_ctx_lock +# define __acquires_ctx_lock(...) +# define __acquires_shared_ctx_lock(...) +# define __try_acquires_ctx_lock(ret, var) +# define __try_acquires_shared_ctx_lock(ret, var) +# define __releases_ctx_lock(...) +# define __releases_shared_ctx_lock(...) +# define __assumes_ctx_lock(...) +# define __assumes_shared_ctx_lock(...) +# define __returns_ctx_lock(var) +# define __guarded_by(...) +# define __pt_guarded_by(...) +# define __excludes_ctx_lock(...) +# define __requires_ctx_lock(...) +# define __requires_shared_ctx_lock(...) +# define __acquire_ctx_lock(var) do { } while (0) +# define __acquire_shared_ctx_lock(var) do { } while (0) +# define __try_acquire_ctx_lock(var, ret) (ret) +# define __try_acquire_shared_ctx_lock(var, ret) (ret) +# define __release_ctx_lock(var) do { } while (0) +# define __release_shared_ctx_lock(var) do { } while (0) +# define __assume_ctx_lock(var) do { (void)(var); } while (0) +# define __assume_shared_ctx_lock(var) do { (void)(var); } while (0) +# define context_lock_struct(name, ...) struct __VA_ARGS__ name +# define disable_context_analysis() +# define enable_context_analysis() +# define __no_context_analysis + +#endif /* WARN_CONTEXT_ANALYSIS */ + +/** + * context_unsafe() - disable context checking for contained code + * + * Disables context checking for contained statements or expression. + * + * .. code-block:: c + * + * struct some_data { + * spinlock_t lock; + * int counter __guarded_by(&lock); + * }; + * + * int foo(struct some_data *d) + * { + * // ... + * // other code that is still checked ... + * // ... + * return context_unsafe(d->counter); + * } + */ +#define context_unsafe(...) \ +({ \ + disable_context_analysis(); \ + __VA_ARGS__; \ + enable_context_analysis() \ +}) + +/** + * __context_unsafe() - function attribute, disable context checking + * @comment: comment explaining why opt-out is safe + * + * Function attribute denoting that context analysis is disabled for the + * whole function. Forces adding an inline comment as argument. + */ +#define __context_unsafe(comment) __no_context_analysis + +/** + * context_unsafe_alias() - helper to insert a context lock "alias barrier" + * @p: pointer aliasing a context lock or object containing context locks + * + * No-op function that acts as a "context lock alias barrier", where the + * analysis rightfully detects that we're switching aliases, but the switch is + * considered safe but beyond the analysis reasoning abilities. + * + * This should be inserted before the first use of such an alias. + * + * Implementation Note: The compiler ignores aliases that may be reassigned but + * their value cannot be determined (e.g. when passing a non-const pointer to an + * alias as a function argument). + */ +#define context_unsafe_alias(p) _context_unsafe_alias((void **)&(p)) +static inline void _context_unsafe_alias(void **p) { } + +/** + * token_context_lock() - declare an abstract global context lock instance + * @name: token context lock name + * + * Helper that declares an abstract global context lock instance @name, but not + * backed by a real data structure (linker error if accidentally referenced). + * The type name is `__ctx_lock_@name`. + */ +#define token_context_lock(name, ...) \ + context_lock_struct(__ctx_lock_##name, ##__VA_ARGS__) {}; \ + extern const struct __ctx_lock_##name *name + +/** + * token_context_lock_instance() - declare another instance of a global context lock + * @ctx: token context lock previously declared with token_context_lock() + * @name: name of additional global context lock instance + * + * Helper that declares an additional instance @name of the same token context + * lock class @ctx. This is helpful where multiple related token contexts are + * declared, to allow using the same underlying type (`__ctx_lock_@ctx`) as + * function arguments. + */ +#define token_context_lock_instance(ctx, name) \ + extern const struct __ctx_lock_##ctx *name + +/* + * Common keywords for static context analysis. Both Clang's "capability + * analysis" and Sparse's "context tracking" are currently supported. + */ #ifdef __CHECKER__ /* Sparse context/lock checking support. */ # define __must_hold(x) __attribute__((context(x,1,1))) +# define __must_not_hold(x) # define __acquires(x) __attribute__((context(x,0,1))) # define __cond_acquires(x) __attribute__((context(x,0,-1))) # define __releases(x) __attribute__((context(x,1,0))) # define __acquire(x) __context__(x,1) # define __release(x) __context__(x,-1) # define __cond_lock(x, c) ((c) ? ({ __acquire(x); 1; }) : 0) +/* For Sparse, there's no distinction between exclusive and shared locks. */ +# define __must_hold_shared __must_hold +# define __acquires_shared __acquires +# define __cond_acquires_shared __cond_acquires +# define __releases_shared __releases +# define __acquire_shared __acquire +# define __release_shared __release +# define __cond_lock_shared __cond_acquire #else /* !__CHECKER__ */ -# define __must_hold(x) -# define __acquires(x) -# define __cond_acquires(x) -# define __releases(x) -# define __acquire(x) (void)0 -# define __release(x) (void)0 -# define __cond_lock(x, c) (c) +/** + * __must_hold() - function attribute, caller must hold exclusive context lock + * @x: context lock instance pointer + * + * Function attribute declaring that the caller must hold the given context + * lock instance @x exclusively. + */ +# define __must_hold(x) __requires_ctx_lock(x) + +/** + * __must_not_hold() - function attribute, caller must not hold context lock + * @x: context lock instance pointer + * + * Function attribute declaring that the caller must not hold the given context + * lock instance @x. + */ +# define __must_not_hold(x) __excludes_ctx_lock(x) + +/** + * __acquires() - function attribute, function acquires context lock exclusively + * @x: context lock instance pointer + * + * Function attribute declaring that the function acquires the given context + * lock instance @x exclusively, but does not release it. + */ +# define __acquires(x) __acquires_ctx_lock(x) + +/** + * __cond_acquires() - function attribute, function conditionally + * acquires a context lock exclusively + * @x: context lock instance pointer + * + * Function attribute declaring that the function conditionally acquires the + * given context lock instance @x exclusively, but does not release it. + */ +# define __cond_acquires(x) __try_acquires_ctx_lock(1, x) + +/** + * __releases() - function attribute, function releases a context lock exclusively + * @x: context lock instance pointer + * + * Function attribute declaring that the function releases the given context + * lock instance @x exclusively. The associated context must be active on + * entry. + */ +# define __releases(x) __releases_ctx_lock(x) + +/** + * __acquire() - function to acquire context lock exclusively + * @x: context lock instance pointer + * + * No-op function that acquires the given context lock instance @x exclusively. + */ +# define __acquire(x) __acquire_ctx_lock(x) + +/** + * __release() - function to release context lock exclusively + * @x: context lock instance pointer + * + * No-op function that releases the given context lock instance @x. + */ +# define __release(x) __release_ctx_lock(x) + +/** + * __cond_lock() - function that conditionally acquires a context lock + * exclusively + * @x: context lock instance pinter + * @c: boolean expression + * + * Return: result of @c + * + * No-op function that conditionally acquires context lock instance @x + * exclusively, if the boolean expression @c is true. The result of @c is the + * return value; for example: + * + * .. code-block:: c + * + * #define spin_trylock(l) __cond_lock(&lock, _spin_trylock(&lock)) + */ +# define __cond_lock(x, c) __try_acquire_ctx_lock(x, c) + +/** + * __must_hold_shared() - function attribute, caller must hold shared context lock + * @x: context lock instance pointer + * + * Function attribute declaring that the caller must hold the given context + * lock instance @x with shared access. + */ +# define __must_hold_shared(x) __requires_shared_ctx_lock(x) + +/** + * __acquires_shared() - function attribute, function acquires context lock shared + * @x: context lock instance pointer + * + * Function attribute declaring that the function acquires the given + * context lock instance @x with shared access, but does not release it. + */ +# define __acquires_shared(x) __acquires_shared_ctx_lock(x) + +/** + * __cond_acquires_shared() - function attribute, function conditionally + * acquires a context lock shared + * @x: context lock instance pointer + * + * Function attribute declaring that the function conditionally acquires the + * given context lock instance @x with shared access, but does not release it. + */ +# define __cond_acquires_shared(x) __try_acquires_shared_ctx_lock(1, x) + +/** + * __releases_shared() - function attribute, function releases a + * context lock shared + * @x: context lock instance pointer + * + * Function attribute declaring that the function releases the given context + * lock instance @x with shared access. The associated context must be active + * on entry. + */ +# define __releases_shared(x) __releases_shared_ctx_lock(x) + +/** + * __acquire_shared() - function to acquire context lock shared + * @x: context lock instance pointer + * + * No-op function that acquires the given context lock instance @x with shared + * access. + */ +# define __acquire_shared(x) __acquire_shared_ctx_lock(x) + +/** + * __release_shared() - function to release context lock shared + * @x: context lock instance pointer + * + * No-op function that releases the given context lock instance @x with shared + * access. + */ +# define __release_shared(x) __release_shared_ctx_lock(x) + +/** + * __cond_lock_shared() - function that conditionally acquires a context lock shared + * @x: context lock instance pinter + * @c: boolean expression + * + * Return: result of @c + * + * No-op function that conditionally acquires context lock instance @x with + * shared access, if the boolean expression @c is true. The result of @c is the + * return value. + */ +# define __cond_lock_shared(x, c) __try_acquire_shared_ctx_lock(x, c) #endif /* __CHECKER__ */ +/** + * __acquire_ret() - helper to acquire context lock of return value + * @call: call expression + * @ret_expr: acquire expression that uses __ret + */ +#define __acquire_ret(call, ret_expr) \ + ({ \ + __auto_type __ret = call; \ + __acquire(ret_expr); \ + __ret; \ + }) + +/** + * __acquire_shared_ret() - helper to acquire context lock shared of return value + * @call: call expression + * @ret_expr: acquire shared expression that uses __ret + */ +#define __acquire_shared_ret(call, ret_expr) \ + ({ \ + __auto_type __ret = call; \ + __acquire_shared(ret_expr); \ + __ret; \ + }) + +/* + * Attributes to mark functions returning acquired context locks. + * + * This is purely cosmetic to help readability, and should be used with the + * above macros as follows: + * + * struct foo { spinlock_t lock; ... }; + * ... + * #define myfunc(...) __acquire_ret(_myfunc(__VA_ARGS__), &__ret->lock) + * struct foo *_myfunc(int bar) __acquires_ret; + * ... + */ +#define __acquires_ret __no_context_analysis +#define __acquires_shared_ret __no_context_analysis + #endif /* _LINUX_COMPILER_CONTEXT_ANALYSIS_H */ -- cgit v1.2.3 From 38f1311a2219220a3962fae464ca6300ef60b4c1 Mon Sep 17 00:00:00 2001 From: Marco Elver Date: Fri, 19 Dec 2025 16:39:58 +0100 Subject: compiler-context-analysis: Change __cond_acquires to take return value While Sparse is oblivious to the return value of conditional acquire functions, Clang's context analysis needs to know the return value which indicates successful acquisition. Add the additional argument, and convert existing uses. Notably, Clang's interpretation of the value merely relates to the use in a later conditional branch, i.e. 1 ==> context lock acquired in branch taken if condition non-zero, and 0 ==> context lock acquired in branch taken if condition is zero. Given the precise value does not matter, introduce symbolic variants to use instead of either 0 or 1, which should be more intuitive. No functional change intended. Signed-off-by: Marco Elver Signed-off-by: Peter Zijlstra (Intel) Link: https://patch.msgid.link/20251219154418.3592607-10-elver@google.com --- include/linux/compiler-context-analysis.h | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) (limited to 'include/linux/compiler-context-analysis.h') diff --git a/include/linux/compiler-context-analysis.h b/include/linux/compiler-context-analysis.h index d0b3cf0ebfe9..a6a34985dbb2 100644 --- a/include/linux/compiler-context-analysis.h +++ b/include/linux/compiler-context-analysis.h @@ -271,7 +271,7 @@ static inline void _context_unsafe_alias(void **p) { } # define __must_hold(x) __attribute__((context(x,1,1))) # define __must_not_hold(x) # define __acquires(x) __attribute__((context(x,0,1))) -# define __cond_acquires(x) __attribute__((context(x,0,-1))) +# define __cond_acquires(ret, x) __attribute__((context(x,0,-1))) # define __releases(x) __attribute__((context(x,1,0))) # define __acquire(x) __context__(x,1) # define __release(x) __context__(x,-1) @@ -314,15 +314,32 @@ static inline void _context_unsafe_alias(void **p) { } */ # define __acquires(x) __acquires_ctx_lock(x) +/* + * Clang's analysis does not care precisely about the value, only that it is + * either zero or non-zero. So the __cond_acquires() interface might be + * misleading if we say that @ret is the value returned if acquired. Instead, + * provide symbolic variants which we translate. + */ +#define __cond_acquires_impl_true(x, ...) __try_acquires##__VA_ARGS__##_ctx_lock(1, x) +#define __cond_acquires_impl_false(x, ...) __try_acquires##__VA_ARGS__##_ctx_lock(0, x) +#define __cond_acquires_impl_nonzero(x, ...) __try_acquires##__VA_ARGS__##_ctx_lock(1, x) +#define __cond_acquires_impl_0(x, ...) __try_acquires##__VA_ARGS__##_ctx_lock(0, x) +#define __cond_acquires_impl_nonnull(x, ...) __try_acquires##__VA_ARGS__##_ctx_lock(1, x) +#define __cond_acquires_impl_NULL(x, ...) __try_acquires##__VA_ARGS__##_ctx_lock(0, x) + /** * __cond_acquires() - function attribute, function conditionally * acquires a context lock exclusively + * @ret: abstract value returned by function if context lock acquired * @x: context lock instance pointer * * Function attribute declaring that the function conditionally acquires the - * given context lock instance @x exclusively, but does not release it. + * given context lock instance @x exclusively, but does not release it. The + * function return value @ret denotes when the context lock is acquired. + * + * @ret may be one of: true, false, nonzero, 0, nonnull, NULL. */ -# define __cond_acquires(x) __try_acquires_ctx_lock(1, x) +# define __cond_acquires(ret, x) __cond_acquires_impl_##ret(x) /** * __releases() - function attribute, function releases a context lock exclusively @@ -389,12 +406,16 @@ static inline void _context_unsafe_alias(void **p) { } /** * __cond_acquires_shared() - function attribute, function conditionally * acquires a context lock shared + * @ret: abstract value returned by function if context lock acquired * @x: context lock instance pointer * * Function attribute declaring that the function conditionally acquires the - * given context lock instance @x with shared access, but does not release it. + * given context lock instance @x with shared access, but does not release it. The + * function return value @ret denotes when the context lock is acquired. + * + * @ret may be one of: true, false, nonzero, 0, nonnull, NULL. */ -# define __cond_acquires_shared(x) __try_acquires_shared_ctx_lock(1, x) +# define __cond_acquires_shared(ret, x) __cond_acquires_impl_##ret(x, _shared) /** * __releases_shared() - function attribute, function releases a -- cgit v1.2.3 From 5b63d0ae94ccfd64dcbdb693d88eb3650eb3c64c Mon Sep 17 00:00:00 2001 From: Marco Elver Date: Fri, 19 Dec 2025 16:40:12 +0100 Subject: compiler-context-analysis: Remove Sparse support Remove Sparse support as discussed at [1]. The kernel codebase is still scattered with numerous places that try to appease Sparse's context tracking ("annotation for sparse", "fake out sparse", "work around sparse", etc.). Eventually, as more subsystems enable Clang's context analysis, these places will show up and need adjustment or removal of the workarounds altogether. Signed-off-by: Marco Elver Signed-off-by: Peter Zijlstra (Intel) Link: https://lore.kernel.org/all/20250207083335.GW7145@noisy.programming.kicks-ass.net/ [1] Link: https://lore.kernel.org/all/Z6XTKTo_LMj9KmbY@elver.google.com/ [2] Link: https://patch.msgid.link/20251219154418.3592607-24-elver@google.com --- include/linux/compiler-context-analysis.h | 85 ++++++++++--------------------- 1 file changed, 27 insertions(+), 58 deletions(-) (limited to 'include/linux/compiler-context-analysis.h') diff --git a/include/linux/compiler-context-analysis.h b/include/linux/compiler-context-analysis.h index a6a34985dbb2..cb728822343f 100644 --- a/include/linux/compiler-context-analysis.h +++ b/include/linux/compiler-context-analysis.h @@ -262,57 +262,32 @@ static inline void _context_unsafe_alias(void **p) { } extern const struct __ctx_lock_##ctx *name /* - * Common keywords for static context analysis. Both Clang's "capability - * analysis" and Sparse's "context tracking" are currently supported. - */ -#ifdef __CHECKER__ - -/* Sparse context/lock checking support. */ -# define __must_hold(x) __attribute__((context(x,1,1))) -# define __must_not_hold(x) -# define __acquires(x) __attribute__((context(x,0,1))) -# define __cond_acquires(ret, x) __attribute__((context(x,0,-1))) -# define __releases(x) __attribute__((context(x,1,0))) -# define __acquire(x) __context__(x,1) -# define __release(x) __context__(x,-1) -# define __cond_lock(x, c) ((c) ? ({ __acquire(x); 1; }) : 0) -/* For Sparse, there's no distinction between exclusive and shared locks. */ -# define __must_hold_shared __must_hold -# define __acquires_shared __acquires -# define __cond_acquires_shared __cond_acquires -# define __releases_shared __releases -# define __acquire_shared __acquire -# define __release_shared __release -# define __cond_lock_shared __cond_acquire - -#else /* !__CHECKER__ */ + * Common keywords for static context analysis. + */ /** * __must_hold() - function attribute, caller must hold exclusive context lock - * @x: context lock instance pointer * * Function attribute declaring that the caller must hold the given context - * lock instance @x exclusively. + * lock instance(s) exclusively. */ -# define __must_hold(x) __requires_ctx_lock(x) +#define __must_hold(...) __requires_ctx_lock(__VA_ARGS__) /** * __must_not_hold() - function attribute, caller must not hold context lock - * @x: context lock instance pointer * * Function attribute declaring that the caller must not hold the given context - * lock instance @x. + * lock instance(s). */ -# define __must_not_hold(x) __excludes_ctx_lock(x) +#define __must_not_hold(...) __excludes_ctx_lock(__VA_ARGS__) /** * __acquires() - function attribute, function acquires context lock exclusively - * @x: context lock instance pointer * * Function attribute declaring that the function acquires the given context - * lock instance @x exclusively, but does not release it. + * lock instance(s) exclusively, but does not release them. */ -# define __acquires(x) __acquires_ctx_lock(x) +#define __acquires(...) __acquires_ctx_lock(__VA_ARGS__) /* * Clang's analysis does not care precisely about the value, only that it is @@ -339,17 +314,16 @@ static inline void _context_unsafe_alias(void **p) { } * * @ret may be one of: true, false, nonzero, 0, nonnull, NULL. */ -# define __cond_acquires(ret, x) __cond_acquires_impl_##ret(x) +#define __cond_acquires(ret, x) __cond_acquires_impl_##ret(x) /** * __releases() - function attribute, function releases a context lock exclusively - * @x: context lock instance pointer * * Function attribute declaring that the function releases the given context - * lock instance @x exclusively. The associated context must be active on + * lock instance(s) exclusively. The associated context(s) must be active on * entry. */ -# define __releases(x) __releases_ctx_lock(x) +#define __releases(...) __releases_ctx_lock(__VA_ARGS__) /** * __acquire() - function to acquire context lock exclusively @@ -357,7 +331,7 @@ static inline void _context_unsafe_alias(void **p) { } * * No-op function that acquires the given context lock instance @x exclusively. */ -# define __acquire(x) __acquire_ctx_lock(x) +#define __acquire(x) __acquire_ctx_lock(x) /** * __release() - function to release context lock exclusively @@ -365,7 +339,7 @@ static inline void _context_unsafe_alias(void **p) { } * * No-op function that releases the given context lock instance @x. */ -# define __release(x) __release_ctx_lock(x) +#define __release(x) __release_ctx_lock(x) /** * __cond_lock() - function that conditionally acquires a context lock @@ -383,25 +357,23 @@ static inline void _context_unsafe_alias(void **p) { } * * #define spin_trylock(l) __cond_lock(&lock, _spin_trylock(&lock)) */ -# define __cond_lock(x, c) __try_acquire_ctx_lock(x, c) +#define __cond_lock(x, c) __try_acquire_ctx_lock(x, c) /** * __must_hold_shared() - function attribute, caller must hold shared context lock - * @x: context lock instance pointer * * Function attribute declaring that the caller must hold the given context - * lock instance @x with shared access. + * lock instance(s) with shared access. */ -# define __must_hold_shared(x) __requires_shared_ctx_lock(x) +#define __must_hold_shared(...) __requires_shared_ctx_lock(__VA_ARGS__) /** * __acquires_shared() - function attribute, function acquires context lock shared - * @x: context lock instance pointer * * Function attribute declaring that the function acquires the given - * context lock instance @x with shared access, but does not release it. + * context lock instance(s) with shared access, but does not release them. */ -# define __acquires_shared(x) __acquires_shared_ctx_lock(x) +#define __acquires_shared(...) __acquires_shared_ctx_lock(__VA_ARGS__) /** * __cond_acquires_shared() - function attribute, function conditionally @@ -410,23 +382,22 @@ static inline void _context_unsafe_alias(void **p) { } * @x: context lock instance pointer * * Function attribute declaring that the function conditionally acquires the - * given context lock instance @x with shared access, but does not release it. The - * function return value @ret denotes when the context lock is acquired. + * given context lock instance @x with shared access, but does not release it. + * The function return value @ret denotes when the context lock is acquired. * * @ret may be one of: true, false, nonzero, 0, nonnull, NULL. */ -# define __cond_acquires_shared(ret, x) __cond_acquires_impl_##ret(x, _shared) +#define __cond_acquires_shared(ret, x) __cond_acquires_impl_##ret(x, _shared) /** * __releases_shared() - function attribute, function releases a * context lock shared - * @x: context lock instance pointer * * Function attribute declaring that the function releases the given context - * lock instance @x with shared access. The associated context must be active - * on entry. + * lock instance(s) with shared access. The associated context(s) must be + * active on entry. */ -# define __releases_shared(x) __releases_shared_ctx_lock(x) +#define __releases_shared(...) __releases_shared_ctx_lock(__VA_ARGS__) /** * __acquire_shared() - function to acquire context lock shared @@ -435,7 +406,7 @@ static inline void _context_unsafe_alias(void **p) { } * No-op function that acquires the given context lock instance @x with shared * access. */ -# define __acquire_shared(x) __acquire_shared_ctx_lock(x) +#define __acquire_shared(x) __acquire_shared_ctx_lock(x) /** * __release_shared() - function to release context lock shared @@ -444,7 +415,7 @@ static inline void _context_unsafe_alias(void **p) { } * No-op function that releases the given context lock instance @x with shared * access. */ -# define __release_shared(x) __release_shared_ctx_lock(x) +#define __release_shared(x) __release_shared_ctx_lock(x) /** * __cond_lock_shared() - function that conditionally acquires a context lock shared @@ -457,9 +428,7 @@ static inline void _context_unsafe_alias(void **p) { } * shared access, if the boolean expression @c is true. The result of @c is the * return value. */ -# define __cond_lock_shared(x, c) __try_acquire_shared_ctx_lock(x, c) - -#endif /* __CHECKER__ */ +#define __cond_lock_shared(x, c) __try_acquire_shared_ctx_lock(x, c) /** * __acquire_ret() - helper to acquire context lock of return value -- cgit v1.2.3 From e4588c25c9d122b5847b88e18b184404b6959160 Mon Sep 17 00:00:00 2001 From: Marco Elver Date: Fri, 19 Dec 2025 16:40:13 +0100 Subject: compiler-context-analysis: Remove __cond_lock() function-like helper As discussed in [1], removing __cond_lock() will improve the readability of trylock code. Now that Sparse context tracking support has been removed, we can also remove __cond_lock(). Change existing APIs to either drop __cond_lock() completely, or make use of the __cond_acquires() function attribute instead. In particular, spinlock and rwlock implementations required switching over to inline helpers rather than statement-expressions for their trylock_* variants. Suggested-by: Peter Zijlstra Signed-off-by: Marco Elver Signed-off-by: Peter Zijlstra (Intel) Link: https://lore.kernel.org/all/20250207082832.GU7145@noisy.programming.kicks-ass.net/ [1] Link: https://patch.msgid.link/20251219154418.3592607-25-elver@google.com --- include/linux/compiler-context-analysis.h | 31 ------------------------------- 1 file changed, 31 deletions(-) (limited to 'include/linux/compiler-context-analysis.h') diff --git a/include/linux/compiler-context-analysis.h b/include/linux/compiler-context-analysis.h index cb728822343f..4f7559d7ae91 100644 --- a/include/linux/compiler-context-analysis.h +++ b/include/linux/compiler-context-analysis.h @@ -341,24 +341,6 @@ static inline void _context_unsafe_alias(void **p) { } */ #define __release(x) __release_ctx_lock(x) -/** - * __cond_lock() - function that conditionally acquires a context lock - * exclusively - * @x: context lock instance pinter - * @c: boolean expression - * - * Return: result of @c - * - * No-op function that conditionally acquires context lock instance @x - * exclusively, if the boolean expression @c is true. The result of @c is the - * return value; for example: - * - * .. code-block:: c - * - * #define spin_trylock(l) __cond_lock(&lock, _spin_trylock(&lock)) - */ -#define __cond_lock(x, c) __try_acquire_ctx_lock(x, c) - /** * __must_hold_shared() - function attribute, caller must hold shared context lock * @@ -417,19 +399,6 @@ static inline void _context_unsafe_alias(void **p) { } */ #define __release_shared(x) __release_shared_ctx_lock(x) -/** - * __cond_lock_shared() - function that conditionally acquires a context lock shared - * @x: context lock instance pinter - * @c: boolean expression - * - * Return: result of @c - * - * No-op function that conditionally acquires context lock instance @x with - * shared access, if the boolean expression @c is true. The result of @c is the - * return value. - */ -#define __cond_lock_shared(x, c) __try_acquire_shared_ctx_lock(x, c) - /** * __acquire_ret() - helper to acquire context lock of return value * @call: call expression -- cgit v1.2.3 From 4d26d4a158f37cb53b22a23b4dc6c4e5bfa1369e Mon Sep 17 00:00:00 2001 From: Marco Elver Date: Wed, 7 Jan 2026 23:35:49 +0100 Subject: compiler-context-analysys: Fix CONFIG_MODVERSION The robot reported CONFIG_MODVERSION fails; which Nathan described as so: > Something about the context analysis makes genksyms fall over, running > it manually on kernel/sched/core.i with '-w' to show warnings reveals > many new "syntax error" instances. I don't see any warnings when using > gendwarfksyms. Maybe it is context_lock_struct, as that is the first > error I see in the list: > > include/linux/spinlock_types_raw.h:14: syntax error Reported-by: kernel test robot Debugged-by: Nathan Chancellor Closes: https://lore.kernel.org/oe-kbuild-all/202512222219.F6EkVNmQ-lkp@intel.com/ Signed-off-by: Marco Elver Signed-off-by: Peter Zijlstra (Intel) Link: https://patch.msgid.link/aV7fxXjaOBtHhI9X@elver.google.com --- include/linux/compiler-context-analysis.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/linux/compiler-context-analysis.h') diff --git a/include/linux/compiler-context-analysis.h b/include/linux/compiler-context-analysis.h index 4f7559d7ae91..e86b8a3c2f89 100644 --- a/include/linux/compiler-context-analysis.h +++ b/include/linux/compiler-context-analysis.h @@ -6,7 +6,7 @@ #ifndef _LINUX_COMPILER_CONTEXT_ANALYSIS_H #define _LINUX_COMPILER_CONTEXT_ANALYSIS_H -#if defined(WARN_CONTEXT_ANALYSIS) && !defined(__CHECKER__) +#if defined(WARN_CONTEXT_ANALYSIS) && !defined(__CHECKER__) && !defined(__GENKSYMS__) /* * These attributes define new context lock (Clang: capability) types. -- cgit v1.2.3 From d084a73714f818ce509022e1aa9483cabf797c16 Mon Sep 17 00:00:00 2001 From: Marco Elver Date: Mon, 19 Jan 2026 10:05:52 +0100 Subject: compiler-context-analysis: Introduce scoped init guards Add scoped init guard definitions for common synchronization primitives supported by context analysis. The scoped init guards treat the context as active within initialization scope of the underlying context lock, given initialization implies exclusive access to the underlying object. This allows initialization of guarded members without disabling context analysis, while documenting initialization from subsequent usage. The documentation is updated with the new recommendation. Where scoped init guards are not provided or cannot be implemented (ww_mutex omitted for lack of multi-arg guard initializers), the alternative is to just disable context analysis where guarded members are initialized. Suggested-by: Peter Zijlstra Signed-off-by: Marco Elver Signed-off-by: Peter Zijlstra (Intel) Link: https://lore.kernel.org/all/20251212095943.GM3911114@noisy.programming.kicks-ass.net/ Link: https://patch.msgid.link/20260119094029.1344361-3-elver@google.com --- include/linux/compiler-context-analysis.h | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) (limited to 'include/linux/compiler-context-analysis.h') diff --git a/include/linux/compiler-context-analysis.h b/include/linux/compiler-context-analysis.h index e86b8a3c2f89..00c074a2ccb0 100644 --- a/include/linux/compiler-context-analysis.h +++ b/include/linux/compiler-context-analysis.h @@ -32,13 +32,8 @@ /* * The "assert_capability" attribute is a bit confusingly named. It does not * generate a check. Instead, it tells the analysis to *assume* the capability - * is held. This is used for: - * - * 1. Augmenting runtime assertions, that can then help with patterns beyond the - * compiler's static reasoning abilities. - * - * 2. Initialization of context locks, so we can access guarded variables right - * after initialization (nothing else should access the same object yet). + * is held. This is used for augmenting runtime assertions, that can then help + * with patterns beyond the compiler's static reasoning abilities. */ # define __assumes_ctx_lock(...) __attribute__((assert_capability(__VA_ARGS__))) # define __assumes_shared_ctx_lock(...) __attribute__((assert_shared_capability(__VA_ARGS__))) -- cgit v1.2.3