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`bit_spinlock`. 84 85For context locks with an initialization function (e.g., `spin_lock_init()`), 86calling this function before initializing any guarded members or globals 87prevents the compiler from issuing warnings about unguarded initialization. 88 89Lockdep assertions, such as `lockdep_assert_held()`, inform the compiler's 90context analysis that the associated synchronization primitive is held after 91the assertion. This avoids false positives in complex control-flow scenarios 92and encourages the use of Lockdep where static analysis is limited. For 93example, this is useful when a function doesn't *always* require a lock, making 94`__must_hold()` inappropriate. 95 96Keywords 97~~~~~~~~ 98 99.. kernel-doc:: include/linux/compiler-context-analysis.h 100 :identifiers: context_lock_struct 101 token_context_lock token_context_lock_instance 102 __guarded_by __pt_guarded_by 103 __must_hold 104 __must_not_hold 105 __acquires 106 __cond_acquires 107 __releases 108 __must_hold_shared 109 __acquires_shared 110 __cond_acquires_shared 111 __releases_shared 112 __acquire 113 __release 114 __cond_lock 115 __acquire_shared 116 __release_shared 117 __cond_lock_shared 118 __acquire_ret 119 __acquire_shared_ret 120 context_unsafe 121 __context_unsafe 122 disable_context_analysis enable_context_analysis 123 124.. note:: 125 The function attribute `__no_context_analysis` is reserved for internal 126 implementation of context lock types, and should be avoided in normal code. 127 128Background 129---------- 130 131Clang originally called the feature `Thread Safety Analysis 132<https://clang.llvm.org/docs/ThreadSafetyAnalysis.html>`_, with some keywords 133and documentation still using the thread-safety-analysis-only terminology. This 134was later changed and the feature became more flexible, gaining the ability to 135define custom "capabilities". Its foundations can be found in `Capability 136Systems <https://www.cs.cornell.edu/talc/papers/capabilities.pdf>`_, used to 137specify the permissibility of operations to depend on some "capability" being 138held (or not held). 139 140Because the feature is not just able to express capabilities related to 141synchronization primitives, and "capability" is already overloaded in the 142kernel, the naming chosen for the kernel departs from Clang's initial "Thread 143Safety" and "capability" nomenclature; we refer to the feature as "Context 144Analysis" to avoid confusion. The internal implementation still makes 145references to Clang's terminology in a few places, such as `-Wthread-safety` 146being the warning option that also still appears in diagnostic messages. 147