memory-model/Documentation/access-marking.txt

1 MARKING SHARED-MEMORY ACCESSES
6 not use read-modify-write atomic operations.  It also describes how to
12 ACCESS-MARKING OPTIONS
15 The Linux kernel provides the following access-marking options:
17 1.	Plain C-language accesses (unmarked), for example, "a = b;"
19 2.	Data-race marking, for example, "data_race(a = b);"
33 Neither plain C-language accesses nor data_race() (#1 and #2 above) place
36 compiler's use of code-motion and common-subexpression optimizations.
40 C-language accesses.  It is permissible to combine #2 and #3, for example,
45 C-language accesses, but marking all accesses involved in a given data
50 ill-considered additions of data_race(), READ_ONCE(), and WRITE_ONCE()
54 data_race() and even plain C-language accesses is preferable to
59 ----------------------------
64 1.	Data-racy loads from shared variables whose values are used only
67 2.	Data-racy reads whose values are checked against marked reload.
69 3.	Reads whose values feed into error-tolerant heuristics.
71 4.	Writes setting values that feed into error-tolerant heuristics.
74 Data-Racy Reads for Approximate Diagnostics
84 prevents any non-diagnostic reads from shared variable x from running
85 concurrently with updates to x.  Then using plain C-language writes
89 false-positive warnings about these diagnostic reads.
95 In theory, plain C-language loads can also be used for this use case.
101 Data-Racy Reads That Are Checked Against Marked Reload
119 In theory, plain C-language loads can also be used for this use case.
125 Reads Feeding Into Error-Tolerant Heuristics
140 In theory, plain C-language loads can also be used for this use case.
146 Writes Setting Values Feeding Into Error-Tolerant Heuristics
148 The values read into error-tolerant heuristics come from somewhere,
152 due to compiler-mangled reads, it can also tolerate the occasional
153 compiler-mangled write, at least assuming that the proper value is in
156 Plain C-language stores can also be used for this use case.  However,
163 Use of Plain C-Language Accesses
164 --------------------------------
166 Here are some example situations where plain C-language accesses should
172 2.	Initialization-time and cleanup-time accesses.	This covers a
174 	system boot, variables to be used by not-yet-spawned kthreads,
175 	structures not yet published to reference-counted or RCU-protected
178 3.	Per-CPU variables that are not accessed from other CPUs.
180 4.	Private per-task variables, including on-stack variables, some
181 	fields in the task_struct structure, and task-private heap data.
190 	by default, refraining from flagging plain C-language stores:
203 Note that it is important to use plain C-language accesses in these cases,
208 ACCESS-DOCUMENTATION OPTIONS
213 However, it is even more important to comment plain C-language accesses
244 -----------------------------------------------
247 reader-writer spinlock is read-held, written only while that same
248 spinlock is write-held, except that it is also read locklessly for
278 The reader-writer lock prevents the compiler from introducing concurrency
281 should) be plain C-language accesses.  One benefit of making them be
282 plain C-language accesses is that KCSAN can detect any erroneous lockless
309 running on the same CPU doing the legitimate lock-protected write, you
312 it is not necessarily a full replacement for hardware watchpoints.
313 On the other hand, neither are hardware watchpoints a full replacement
314 for KCSAN because it is not always easy to tell hardware watchpoint to
318 Lock-Protected Writes With Lockless Reads
319 -----------------------------------------
348 Lock-Protected Writes With Heuristic Lockless Reads
349 ---------------------------------------------------
352 a per-data-structure lock, but there are times when a global lock
372 			spin_lock(&fp->f_lock);
375 				spin_unlock(&fp->f_lock);
378 			spin_unlock(&fp->f_lock);
382 		spin_lock(&fp->f_lock);
386 		 * will wait for ->f_lock to be released.
389 		spin_unlock(&fp->f_lock);
400 			 * Wait for pre-existing local locks.  One at
403 			spin_lock(&fp->f_lock);
404 			spin_unlock(&fp->f_lock);
419 rechecked while holding ->f_lock, which, if global_flag is now false,
425 ->f_lock will prevent any call to begin_global() from returning, which
435 end_global() are carried out without holding that structure's ->f_lock.
442 -------------------------
467 flag any concurrent plain C-language reads from foo, and given
469 C-language writes to foo.
472 Lockless Reads and Writes, But With Single-Threaded Initialization
473 ------------------------------------------------------------------
476 single-threaded manner, but that a number of kthreads are then created
509 The initialize_foo() uses a plain C-language write to foo because there
517 Checking Stress-Test Race Coverage
518 ----------------------------------
583 If a given stress-test run does not result in KCSAN complaints from
586 on a regular basis, it would be wise to place the above instances of
594 [1] "Concurrency bugs should fear the big bad data-race detector (part 2)"