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