1.. SPDX-License-Identifier: GPL-2.0 2.. Copyright (C) 2025, Google LLC. 3 4.. _context-analysis: 5 6Compiler-Based Context Analysis 7=============================== 8 9Context Analysis is a language extension, which enables statically checking 10that required contexts are active (or inactive) by acquiring and releasing 11user-definable "context locks". An obvious application is lock-safety checking 12for the kernel's various synchronization primitives (each of which represents a 13"context lock"), and checking that locking rules are not violated. 14 15The Clang compiler currently supports the full set of context analysis 16features. To enable for Clang, configure the kernel with:: 17 18 CONFIG_WARN_CONTEXT_ANALYSIS=y 19 20The feature requires Clang 22 or later. 21 22The analysis is *opt-in by default*, and requires declaring which modules and 23subsystems should be analyzed in the respective `Makefile`:: 24 25 CONTEXT_ANALYSIS_mymodule.o := y 26 27Or for all translation units in the directory:: 28 29 CONTEXT_ANALYSIS := y 30 31It is possible to enable the analysis tree-wide, however, which will result in 32numerous false positive warnings currently and is *not* generally recommended:: 33 34 CONFIG_WARN_CONTEXT_ANALYSIS_ALL=y 35 36Programming Model 37----------------- 38 39The below describes the programming model around using context lock types. 40 41.. note:: 42 Enabling context analysis can be seen as enabling a dialect of Linux C with 43 a Context System. Some valid patterns involving complex control-flow are 44 constrained (such as conditional acquisition and later conditional release 45 in the same function). 46 47Context analysis is a way to specify permissibility of operations to depend on 48context locks being held (or not held). Typically we are interested in 49protecting data and code in a critical section by requiring a specific context 50to be active, for example by holding a specific lock. The analysis ensures that 51callers cannot perform an operation without the required context being active. 52 53Context locks are associated with named structs, along with functions that 54operate on struct instances to acquire and release the associated context lock. 55 56Context locks can be held either exclusively or shared. This mechanism allows 57assigning more precise privileges when a context is active, typically to 58distinguish where a thread may only read (shared) or also write (exclusive) to 59data guarded within a context. 60 61The set of contexts that are actually active in a given thread at a given point 62in program execution is a run-time concept. The static analysis works by 63calculating an approximation of that set, called the context environment. The 64context environment is calculated for every program point, and describes the 65set of contexts that are statically known to be active, or inactive, at that 66particular point. This environment is a conservative approximation of the full 67set of contexts that will actually be active in a thread at run-time. 68 69More details are also documented `here 70<https://clang.llvm.org/docs/ThreadSafetyAnalysis.html>`_. 71 72.. note:: 73 Clang's analysis explicitly does not infer context locks acquired or 74 released by inline functions. It requires explicit annotations to (a) assert 75 that it's not a bug if a context lock is released or acquired, and (b) to 76 retain consistency between inline and non-inline function declarations. 77 78Supported Kernel Primitives 79~~~~~~~~~~~~~~~~~~~~~~~~~~~ 80 81Currently the following synchronization primitives are supported: 82`raw_spinlock_t`, `spinlock_t`, `rwlock_t`, `mutex`, `seqlock_t`. 83 84For context locks with an initialization function (e.g., `spin_lock_init()`), 85calling this function before initializing any guarded members or globals 86prevents the compiler from issuing warnings about unguarded initialization. 87 88Lockdep assertions, such as `lockdep_assert_held()`, inform the compiler's 89context analysis that the associated synchronization primitive is held after 90the assertion. This avoids false positives in complex control-flow scenarios 91and encourages the use of Lockdep where static analysis is limited. For 92example, this is useful when a function doesn't *always* require a lock, making 93`__must_hold()` inappropriate. 94 95Keywords 96~~~~~~~~ 97 98.. kernel-doc:: include/linux/compiler-context-analysis.h 99 :identifiers: context_lock_struct 100 token_context_lock token_context_lock_instance 101 __guarded_by __pt_guarded_by 102 __must_hold 103 __must_not_hold 104 __acquires 105 __cond_acquires 106 __releases 107 __must_hold_shared 108 __acquires_shared 109 __cond_acquires_shared 110 __releases_shared 111 __acquire 112 __release 113 __cond_lock 114 __acquire_shared 115 __release_shared 116 __cond_lock_shared 117 __acquire_ret 118 __acquire_shared_ret 119 context_unsafe 120 __context_unsafe 121 disable_context_analysis enable_context_analysis 122 123.. note:: 124 The function attribute `__no_context_analysis` is reserved for internal 125 implementation of context lock types, and should be avoided in normal code. 126 127Background 128---------- 129 130Clang originally called the feature `Thread Safety Analysis 131<https://clang.llvm.org/docs/ThreadSafetyAnalysis.html>`_, with some keywords 132and documentation still using the thread-safety-analysis-only terminology. This 133was later changed and the feature became more flexible, gaining the ability to 134define custom "capabilities". Its foundations can be found in `Capability 135Systems <https://www.cs.cornell.edu/talc/papers/capabilities.pdf>`_, used to 136specify the permissibility of operations to depend on some "capability" being 137held (or not held). 138 139Because the feature is not just able to express capabilities related to 140synchronization primitives, and "capability" is already overloaded in the 141kernel, the naming chosen for the kernel departs from Clang's initial "Thread 142Safety" and "capability" nomenclature; we refer to the feature as "Context 143Analysis" to avoid confusion. The internal implementation still makes 144references to Clang's terminology in a few places, such as `-Wthread-safety` 145being the warning option that also still appears in diagnostic messages. 146