1# SPDX-License-Identifier: GPL-2.0-only
2
3config HAVE_ARCH_KCSAN
4	bool
5
6config HAVE_KCSAN_COMPILER
7	def_bool (CC_IS_CLANG && $(cc-option,-fsanitize=thread -mllvm -tsan-distinguish-volatile=1)) || \
8		 (CC_IS_GCC && $(cc-option,-fsanitize=thread --param tsan-distinguish-volatile=1))
9	help
10	  For the list of compilers that support KCSAN, please see
11	  <file:Documentation/dev-tools/kcsan.rst>.
12
13menuconfig KCSAN
14	bool "KCSAN: dynamic data race detector"
15	depends on HAVE_ARCH_KCSAN && HAVE_KCSAN_COMPILER
16	depends on DEBUG_KERNEL && !KASAN
17	select CONSTRUCTORS
18	select STACKTRACE
19	help
20	  The Kernel Concurrency Sanitizer (KCSAN) is a dynamic
21	  data-race detector that relies on compile-time instrumentation.
22	  KCSAN uses a watchpoint-based sampling approach to detect races.
23
24	  While KCSAN's primary purpose is to detect data races, it
25	  also provides assertions to check data access constraints.
26	  These assertions can expose bugs that do not manifest as
27	  data races.
28
29	  See <file:Documentation/dev-tools/kcsan.rst> for more details.
30
31if KCSAN
32
33config CC_HAS_TSAN_COMPOUND_READ_BEFORE_WRITE
34	def_bool (CC_IS_CLANG && $(cc-option,-fsanitize=thread -mllvm -tsan-compound-read-before-write=1)) || \
35		 (CC_IS_GCC && $(cc-option,-fsanitize=thread --param tsan-compound-read-before-write=1))
36	help
37	  The compiler instruments plain compound read-write operations
38	  differently (++, --, +=, -=, |=, &=, etc.), which allows KCSAN to
39	  distinguish them from other plain accesses. This is currently
40	  supported by Clang 12 or later.
41
42config KCSAN_VERBOSE
43	bool "Show verbose reports with more information about system state"
44	depends on PROVE_LOCKING
45	help
46	  If enabled, reports show more information about the system state that
47	  may help better analyze and debug races. This includes held locks and
48	  IRQ trace events.
49
50	  While this option should generally be benign, we call into more
51	  external functions on report generation; if a race report is
52	  generated from any one of them, system stability may suffer due to
53	  deadlocks or recursion.  If in doubt, say N.
54
55config KCSAN_SELFTEST
56	bool "Perform short selftests on boot"
57	default y
58	help
59	  Run KCSAN selftests on boot. On test failure, causes the kernel to
60	  panic. Recommended to be enabled, ensuring critical functionality
61	  works as intended.
62
63config KCSAN_KUNIT_TEST
64	tristate "KCSAN test for integrated runtime behaviour" if !KUNIT_ALL_TESTS
65	default KUNIT_ALL_TESTS
66	depends on TRACEPOINTS && KUNIT
67	select TORTURE_TEST
68	help
69	  KCSAN test focusing on behaviour of the integrated runtime. Tests
70	  various race scenarios, and verifies the reports generated to
71	  console. Makes use of KUnit for test organization, and the Torture
72	  framework for test thread control.
73
74	  Each test case may run at least up to KCSAN_REPORT_ONCE_IN_MS
75	  milliseconds. Test run duration may be optimized by building the
76	  kernel and KCSAN test with KCSAN_REPORT_ONCE_IN_MS set to a lower
77	  than default value.
78
79	  Say Y here if you want the test to be built into the kernel and run
80	  during boot; say M if you want the test to build as a module; say N
81	  if you are unsure.
82
83config KCSAN_EARLY_ENABLE
84	bool "Early enable during boot"
85	default y
86	help
87	  If KCSAN should be enabled globally as soon as possible. KCSAN can
88	  later be enabled/disabled via debugfs.
89
90config KCSAN_NUM_WATCHPOINTS
91	int "Number of available watchpoints"
92	default 64
93	help
94	  Total number of available watchpoints. An address range maps into a
95	  specific watchpoint slot as specified in kernel/kcsan/encoding.h.
96	  Although larger number of watchpoints may not be usable due to
97	  limited number of CPUs, a larger value helps to improve performance
98	  due to reducing cache-line contention. The chosen default is a
99	  conservative value; we should almost never observe "no_capacity"
100	  events (see /sys/kernel/debug/kcsan).
101
102config KCSAN_UDELAY_TASK
103	int "Delay in microseconds (for tasks)"
104	default 80
105	help
106	  For tasks, the microsecond delay after setting up a watchpoint.
107
108config KCSAN_UDELAY_INTERRUPT
109	int "Delay in microseconds (for interrupts)"
110	default 20
111	help
112	  For interrupts, the microsecond delay after setting up a watchpoint.
113	  Interrupts have tighter latency requirements, and their delay should
114	  be lower than for tasks.
115
116config KCSAN_DELAY_RANDOMIZE
117	bool "Randomize above delays"
118	default y
119	help
120	  If delays should be randomized, where the maximum is KCSAN_UDELAY_*.
121	  If false, the chosen delays are always the KCSAN_UDELAY_* values
122	  as defined above.
123
124config KCSAN_SKIP_WATCH
125	int "Skip instructions before setting up watchpoint"
126	default 4000
127	help
128	  The number of per-CPU memory operations to skip, before another
129	  watchpoint is set up, i.e. one in KCSAN_SKIP_WATCH per-CPU
130	  memory operations are used to set up a watchpoint. A smaller value
131	  results in more aggressive race detection, whereas a larger value
132	  improves system performance at the cost of missing some races.
133
134config KCSAN_SKIP_WATCH_RANDOMIZE
135	bool "Randomize watchpoint instruction skip count"
136	default y
137	help
138	  If instruction skip count should be randomized, where the maximum is
139	  KCSAN_SKIP_WATCH. If false, the chosen value is always
140	  KCSAN_SKIP_WATCH.
141
142config KCSAN_INTERRUPT_WATCHER
143	bool "Interruptible watchers" if !KCSAN_STRICT
144	default KCSAN_STRICT
145	help
146	  If enabled, a task that set up a watchpoint may be interrupted while
147	  delayed. This option will allow KCSAN to detect races between
148	  interrupted tasks and other threads of execution on the same CPU.
149
150	  Currently disabled by default, because not all safe per-CPU access
151	  primitives and patterns may be accounted for, and therefore could
152	  result in false positives.
153
154config KCSAN_REPORT_ONCE_IN_MS
155	int "Duration in milliseconds, in which any given race is only reported once"
156	default 3000
157	help
158	  Any given race is only reported once in the defined time window.
159	  Different races may still generate reports within a duration that is
160	  smaller than the duration defined here. This allows rate limiting
161	  reporting to avoid flooding the console with reports.  Setting this
162	  to 0 disables rate limiting.
163
164# The main purpose of the below options is to control reported data races, and
165# are not expected to be switched frequently by non-testers or at runtime.
166# The defaults are chosen to be conservative, and can miss certain bugs.
167
168config KCSAN_REPORT_RACE_UNKNOWN_ORIGIN
169	bool "Report races of unknown origin"
170	default y
171	help
172	  If KCSAN should report races where only one access is known, and the
173	  conflicting access is of unknown origin. This type of race is
174	  reported if it was only possible to infer a race due to a data value
175	  change while an access is being delayed on a watchpoint.
176
177config KCSAN_STRICT
178	bool "Strict data-race checking"
179	help
180	  KCSAN will report data races with the strictest possible rules, which
181	  closely aligns with the rules defined by the Linux-kernel memory
182	  consistency model (LKMM).
183
184config KCSAN_WEAK_MEMORY
185	bool "Enable weak memory modeling to detect missing memory barriers"
186	default y
187	depends on KCSAN_STRICT
188	# We can either let objtool nop __tsan_func_{entry,exit}() and builtin
189	# atomics instrumentation in .noinstr.text, or use a compiler that can
190	# implement __no_kcsan to really remove all instrumentation.
191	depends on !ARCH_WANTS_NO_INSTR || HAVE_NOINSTR_HACK || \
192		   CC_IS_GCC || CLANG_VERSION >= 140000
193	select OBJTOOL if HAVE_NOINSTR_HACK
194	help
195	  Enable support for modeling a subset of weak memory, which allows
196	  detecting a subset of data races due to missing memory barriers.
197
198	  Depends on KCSAN_STRICT, because the options strengthening certain
199	  plain accesses by default (depending on !KCSAN_STRICT) reduce the
200	  ability to detect any data races invoving reordered accesses, in
201	  particular reordered writes.
202
203	  Weak memory modeling relies on additional instrumentation and may
204	  affect performance.
205
206config KCSAN_REPORT_VALUE_CHANGE_ONLY
207	bool "Only report races where watcher observed a data value change"
208	default y
209	depends on !KCSAN_STRICT
210	help
211	  If enabled and a conflicting write is observed via a watchpoint, but
212	  the data value of the memory location was observed to remain
213	  unchanged, do not report the data race.
214
215config KCSAN_ASSUME_PLAIN_WRITES_ATOMIC
216	bool "Assume that plain aligned writes up to word size are atomic"
217	default y
218	depends on !KCSAN_STRICT
219	help
220	  Assume that plain aligned writes up to word size are atomic by
221	  default, and also not subject to other unsafe compiler optimizations
222	  resulting in data races. This will cause KCSAN to not report data
223	  races due to conflicts where the only plain accesses are aligned
224	  writes up to word size: conflicts between marked reads and plain
225	  aligned writes up to word size will not be reported as data races;
226	  notice that data races between two conflicting plain aligned writes
227	  will also not be reported.
228
229config KCSAN_IGNORE_ATOMICS
230	bool "Do not instrument marked atomic accesses"
231	depends on !KCSAN_STRICT
232	help
233	  Never instrument marked atomic accesses. This option can be used for
234	  additional filtering. Conflicting marked atomic reads and plain
235	  writes will never be reported as a data race, however, will cause
236	  plain reads and marked writes to result in "unknown origin" reports.
237	  If combined with CONFIG_KCSAN_REPORT_RACE_UNKNOWN_ORIGIN=n, data
238	  races where at least one access is marked atomic will never be
239	  reported.
240
241	  Similar to KCSAN_ASSUME_PLAIN_WRITES_ATOMIC, but including unaligned
242	  accesses, conflicting marked atomic reads and plain writes will not
243	  be reported as data races; however, unlike that option, data races
244	  due to two conflicting plain writes will be reported (aligned and
245	  unaligned, if CONFIG_KCSAN_ASSUME_PLAIN_WRITES_ATOMIC=n).
246
247config KCSAN_PERMISSIVE
248	bool "Enable all additional permissive rules"
249	depends on KCSAN_REPORT_VALUE_CHANGE_ONLY
250	help
251	  Enable additional permissive rules to ignore certain classes of data
252	  races (also see kernel/kcsan/permissive.h). None of the permissive
253	  rules imply that such data races are generally safe, but can be used
254	  to further reduce reported data races due to data-racy patterns
255	  common across the kernel.
256
257endif # KCSAN
258