compiler-context-analysis.h

Go to the documentation of this file.

/* 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
 
#if defined(WARN_CONTEXT_ANALYSIS) && !defined(__CHECKER__) && !defined(__GENKSYMS__)
 
/*
 * 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 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__)))
 
# define __guarded_by(...)      __attribute__((guarded_by(__VA_ARGS__)))
 
# define __pt_guarded_by(...)       __attribute__((pt_guarded_by(__VA_ARGS__)))
 
# 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
 
# define disable_context_analysis()             \
    __diag_push();                      \
    __diag_ignore_all("-Wunknown-warning-option", "")   \
    __diag_ignore_all("-Wthread-safety", "")        \
    __diag_ignore_all("-Wthread-safety-pointer", "")
 
# define enable_context_analysis() __diag_pop()
 
# 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 */
 
#define context_unsafe(...)     \
({                  \
    disable_context_analysis(); \
    __VA_ARGS__;            \
    enable_context_analysis()   \
})
 
#define __context_unsafe(comment) __no_context_analysis
 
#define context_unsafe_alias(p) _context_unsafe_alias((void **)&(p))
static inline void _context_unsafe_alias(void **p) { }
 
#define token_context_lock(name, ...)                   \
    context_lock_struct(__ctx_lock_##name, ##__VA_ARGS__) {};   \
    extern const struct __ctx_lock_##name *name
 
#define token_context_lock_instance(ctx, name)      \
    extern const struct __ctx_lock_##ctx *name
 
/*
 * Common keywords for static context analysis.
 */
 
#define __must_hold(...)    __requires_ctx_lock(__VA_ARGS__)
 
#define __must_not_hold(...)    __excludes_ctx_lock(__VA_ARGS__)
 
#define __acquires(...)     __acquires_ctx_lock(__VA_ARGS__)
 
/*
 * 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)
 
#define __cond_acquires(ret, x) __cond_acquires_impl_##ret(x)
 
#define __releases(...)     __releases_ctx_lock(__VA_ARGS__)
 
/*
 * 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_not_true(x, ...)     __try_acquires##__VA_ARGS__##_ctx_lock(0, x)
#define __cond_acquires_impl_not_false(x, ...)    __try_acquires##__VA_ARGS__##_ctx_lock(1, x)
#define __cond_acquires_impl_not_nonzero(x, ...)  __try_acquires##__VA_ARGS__##_ctx_lock(0, x)
#define __cond_acquires_impl_not_0(x, ...)        __try_acquires##__VA_ARGS__##_ctx_lock(1, x)
#define __cond_acquires_impl_not_nonnull(x, ...)  __try_acquires##__VA_ARGS__##_ctx_lock(0, x)
#define __cond_acquires_impl_not_NULL(x, ...)     __try_acquires##__VA_ARGS__##_ctx_lock(1, x)
 
#define __cond_releases(ret, x) __releases(x) __cond_acquires_impl_not_##ret(x)
 
#define __acquire(x)        __acquire_ctx_lock(x)
 
#define __release(x)        __release_ctx_lock(x)
 
#define __must_hold_shared(...) __requires_shared_ctx_lock(__VA_ARGS__)
 
#define __acquires_shared(...)  __acquires_shared_ctx_lock(__VA_ARGS__)
 
#define __cond_acquires_shared(ret, x) __cond_acquires_impl_##ret(x, _shared)
 
#define __releases_shared(...)  __releases_shared_ctx_lock(__VA_ARGS__)
 
#define __acquire_shared(x) __acquire_shared_ctx_lock(x)
 
#define __release_shared(x) __release_shared_ctx_lock(x)
 
#define __acquire_ret(call, ret_expr)       \
    ({                  \
        __auto_type __ret = call;   \
        __acquire(ret_expr);        \
        __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 */