Kernel/linux
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-01-01 02:33:57 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

kcsan: Add __data_racy documentation and module description

Browse Source 
This series contains on commit that improves the documentation for the
 new __data_racy type qualifier to the data_race() macro's kernel-doc
 header and to the LKMM's access-marking documentation.
 -----BEGIN PGP SIGNATURE-----
 
 iQJHBAABCgAxFiEEbK7UrM+RBIrCoViJnr8S83LZ+4wFAmaRubITHHBhdWxtY2tA
 a2VybmVsLm9yZwAKCRCevxLzctn7jLWlD/99wMLUIfPh1cvWVVyhv8tytWuLJn6y
 olwukg9pOCz6WGucECfjAC2kFivSQYxS3b54K697tF4hnABEtpsx7ozkv11kgyR8
 niHNv4P+L+0J7CnM/g7gkLrAGosdo+PF7rUhX3u3kpeasVjJ5NyK379jUeTjrDrc
 ia34vjbVVNdJ5v0c4ITxbbV/NKecbsadRSqDLzjtNrFPkwo/yfFCrz8ddztadsTd
 4jftt/L4Up51QQ8NAgiHsHdp+iY/FRjwd/QtvEXSVUZ38sGseH+eNqn4hMuyTnka
 cjnHwAlTbEfAuR3Mdcz25ToiaI6qNxptvvM7E9+LtHuBhI+h6vEvdvPMmSFo48Rv
 kzdPix39O5dqpu49nz/Qsmmr/AWn9i3M5oht62YMJ5twoutDFAcc5MMppPT6sNsX
 Kq3fn8fjRvdHqgE3jBYOgDDWEZuTxdtcdv8wKfplID/SgyjXL48fghMEl62b2O1d
 X6PrHhKARk7RKMndAPk0UNz4m8T5oDmKu9Z9mF8UidjeZjYU0tVYPAoN1H/9lVdH
 Kn2DoTW5Oz2A21z37r5SGAro0QBE50ZMYA+xH+Ab3fyfFcd4l4ia/wu06c3AVJFc
 DqgKJ7f3YQ7tHGLf0AEpO6o/nNZGxwDHJ5Pjbteu2RwbCcUHmUtKxrM+McPXTvuv
 MjW/IAvvPdMxCw==
 =r0/X
 -----END PGP SIGNATURE-----

Merge tag 'kcsan.2024.07.12a' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu

Pull KCSAN updates from Paul McKenney:

 - improve the documentation for the new __data_racy type qualifier
   to the data_race() macro's kernel-doc header and to the LKMM's
   access-marking documentation

 - add missing MODULE_DESCRIPTION

* tag 'kcsan.2024.07.12a' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu:
  kcsan: Add missing MODULE_DESCRIPTION() macro
  kcsan: Add example to data_race() kerneldoc header
This commit is contained in:
Linus Torvalds 2024-07-15 15:44:40 -07:00
commit e4b2b0b1e4
3 changed files with 33 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
include/linux/compiler.h
View File

@ -194,9 +194,17 @@ void ftrace_likely_update(struct ftrace_likely_data *f, int val,
* This data_race() macro is useful for situations in which data races
* should be forgiven. One example is diagnostic code that accesses
* shared variables but is not a part of the core synchronization design.
* For example, if accesses to a given variable are protected by a lock,
* except for diagnostic code, then the accesses under the lock should
* be plain C-language accesses and those in the diagnostic code should
* use data_race(). This way, KCSAN will complain if buggy lockless
* accesses to that variable are introduced, even if the buggy accesses
* are protected by READ_ONCE() or WRITE_ONCE().
*
* This macro *does not* affect normal code generation, but is a hint
* to tooling that data races here are to be ignored.
* to tooling that data races here are to be ignored. If the access must
* be atomic *and* KCSAN should ignore the access, use both data_race()
* and READ_ONCE(), for example, data_race(READ_ONCE(x)).
*/
#define data_race(expr) \
({ \

1
kernel/kcsan/kcsan_test.c
View File

@ -1620,5 +1620,6 @@ static struct kunit_suite kcsan_test_suite = {
kunit_test_suites(&kcsan_test_suite);
MODULE_DESCRIPTION("KCSAN test suite");
MODULE_LICENSE("GPL v2");
MODULE_AUTHOR("Marco Elver <elver@google.com>");

24
tools/memory-model/Documentation/access-marking.txt
View File

@ -25,6 +25,11 @@ The Linux kernel provides the following access-marking options:
4. WRITE_ONCE(), for example, "WRITE_ONCE(a, b);"
The various forms of atomic_set() also fit in here.
5. __data_racy, for example "int __data_racy a;"
6. KCSAN's negative-marking assertions, ASSERT_EXCLUSIVE_ACCESS()
and ASSERT_EXCLUSIVE_WRITER(), are described in the
"ACCESS-DOCUMENTATION OPTIONS" section below.
These may be used in combination, as shown in this admittedly improbable
example:
@ -206,6 +211,23 @@ because doing otherwise prevents KCSAN from detecting violations of your
code's synchronization rules.
Use of __data_racy
------------------
Adding the __data_racy type qualifier to the declaration of a variable
causes KCSAN to treat all accesses to that variable as if they were
enclosed by data_race(). However, __data_racy does not affect the
compiler, though one could imagine hardened kernel builds treating the
__data_racy type qualifier as if it was the volatile keyword.
Note well that __data_racy is subject to the same pointer-declaration
rules as are other type qualifiers such as const and volatile.
For example:
int __data_racy *p; // Pointer to data-racy data.
int *__data_racy p; // Data-racy pointer to non-data-racy data.
ACCESS-DOCUMENTATION OPTIONS
============================
@ -343,7 +365,7 @@ as follows:
Because foo is read locklessly, all accesses are marked. The purpose
of the ASSERT_EXCLUSIVE_WRITER() is to allow KCSAN to check for a buggy
concurrent lockless write.
concurrent write, whether marked or not.
Lock-Protected Writes With Heuristic Lockless Reads