kernel.git/tools/memory-model/Documentation/access-marking.txt, branch master

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

2024-07-15T22:44:40Z

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

tools/memory-model: Add KCSAN LF mentorship session citation

2024-06-06T18:23:35Z

Add a citation to Marco's LF mentorship session presentation entitled "The Kernel Concurrency Sanitizer" [ paulmck: Apply Marco Elver feedback. ] Reported-by: Marco Elver Signed-off-by: Paul E. McKenney Acked-by: Andrea Parri Reviewed-by: Akira Yokosawa Acked-by: Marco Elver Cc: Alan Stern Cc: Will Deacon Cc: Peter Zijlstra Cc: Boqun Feng Cc: Nicholas Piggin Cc: David Howells Cc: Jade Alglave Cc: Luc Maranget Cc: Daniel Lustig Cc: Joel Fernandes Cc:

kcsan: Add example to data_race() kerneldoc header

2024-05-30T22:06:26Z

Although the data_race() kerneldoc header accurately states what it does, some of the implications and usage patterns are non-obvious. Therefore, add a brief locking example and also state how to have KCSAN ignore accesses while also preventing the compiler from folding, spindling, or otherwise mutilating the access. [ paulmck: Apply Bart Van Assche feedback. ] [ paulmck: Apply feedback from Marco Elver. ] Reported-by: Bart Van Assche Signed-off-by: Paul E. McKenney Cc: Marco Elver Cc: Breno Leitao Cc: Jens Axboe

tools/memory-model: Document data_race(READ_ONCE())

2021-07-27T18:48:55Z

It is possible to cause KCSAN to ignore marked accesses by applying __no_kcsan to the function or applying data_race() to the marked accesses. These approaches allow the developer to restrict compiler optimizations while also causing KCSAN to ignore diagnostic accesses. This commit therefore updates the documentation accordingly. Signed-off-by: Paul E. McKenney

tools/memory-model: Heuristics using data_race() must handle all values

2021-07-27T18:48:55Z

Data loaded for use by some sorts of heuristics can tolerate the occasional erroneous value. In this case the loads may use data_race() to give the compiler full freedom to optimize while also informing KCSAN of the intent. However, for this to work, the heuristic needs to be able to tolerate any erroneous value that could possibly arise. This commit therefore adds a paragraph spelling this out. Signed-off-by: Manfred Spraul Signed-off-by: Paul E. McKenney

tools/memory-model: Add example for heuristic lockless reads

2021-07-27T18:47:34Z

This commit adds example code for heuristic lockless reads, based loosely on the sem_lock() and sem_unlock() functions. [ paulmck: Apply Alan Stern and Manfred Spraul feedback. ] Reported-by: Manfred Spraul [ paulmck: Update per Manfred Spraul and Hillf Danton feedback. ] Signed-off-by: Paul E. McKenney

tools/memory-model: Make read_foo_diagnostic() more clearly diagnostic

2021-07-20T20:52:03Z

The current definition of read_foo_diagnostic() in the "Lock Protection With Lockless Diagnostic Access" section returns a value, which could be use for any purpose. This could mislead people into incorrectly using data_race() in cases where READ_ONCE() is required. This commit therefore makes read_foo_diagnostic() simply print the value read. Reported-by: Manfred Spraul Signed-off-by: Paul E. McKenney

tools/memory-model: Add access-marking documentation

2021-03-15T20:59:47Z

This commit adapts the "Concurrency bugs should fear the big bad data-race detector (part 2)" LWN article (https://lwn.net/Articles/816854/) to kernel-documentation form. This allows more easily updating the material as needed. Suggested-by: Thomas Gleixner [ paulmck: Apply Marco Elver feedback. ] [ paulmck: Update per Akira Yokosawa feedback. ] Reviewed-by: Marco Elver Signed-off-by: Paul E. McKenney