linux-stable.git/tools/memory-model/Documentation, branch v5.13.2 Linux kernel stable tree tools/memory-model: Add access-marking documentation 2021-03-15T20:59:47+00:00 Paul E. McKenney paulmck@kernel.org 2021-02-11T23:40:05+00:00 49ab51b01ec6fd837ae3efe2e0cdb41fcf5cf048 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 <tglx@linutronix.de> [ paulmck: Apply Marco Elver feedback. ] [ paulmck: Update per Akira Yokosawa feedback. ] Reviewed-by: Marco Elver <elver@google.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
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 <tglx@linutronix.de>
[ paulmck: Apply Marco Elver feedback. ]
[ paulmck: Update per Akira Yokosawa feedback. ]
Reviewed-by: Marco Elver <elver@google.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
tools/memory-model: Remove reference to atomic_ops.rst 2021-03-08T22:29:22+00:00 Akira Yokosawa akiyks@gmail.com 2021-01-14T14:09:07+00:00 9146658cc49a1dbed5ece140f658be884e189ade atomic_ops.rst was removed by commit f0400a77ebdc ("atomic: Delete obsolete documentation"). Remove the broken link in tools/memory-model/Documentation/simple.txt. Cc: Peter Zijlstra <peterz@infradead.org> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
atomic_ops.rst was removed by commit f0400a77ebdc ("atomic: Delete
obsolete documentation").
Remove the broken link in tools/memory-model/Documentation/simple.txt.

Cc: Peter Zijlstra <peterz@infradead.org>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
doc: Update rcu_dereference.rst reference 2021-03-08T22:29:22+00:00 Mauro Carvalho Chehab mchehab+huawei@kernel.org 2021-01-13T10:59:20+00:00 ba46b21bbdf8c1e8f054f44e7db7d6684720ef78 Changeset b00aedf978aa ("doc: Convert to rcu_dereference.txt to rcu_dereference.rst") renamed: Documentation/RCU/rcu_dereference.txt to: Documentation/RCU/rcu_dereference.rst. Update its cross-reference accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
Changeset b00aedf978aa ("doc: Convert to rcu_dereference.txt to rcu_dereference.rst")
renamed: Documentation/RCU/rcu_dereference.txt
to: Documentation/RCU/rcu_dereference.rst.

Update its cross-reference accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
tools/memory-model: Tie acquire loads to reads-from 2021-01-04T22:40:49+00:00 Paul E. McKenney paulmck@kernel.org 2020-11-06T17:58:01+00:00 8881e7a774a8d14088d6c6fde8730660f74a3642 This commit explicitly makes the connection between acquire loads and the reads-from relation. It also adds an entry for happens-before, and refers to the corresponding section of explanation.txt. Reported-by: Boqun Feng <boqun.feng@gmail.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
This commit explicitly makes the connection between acquire loads and
the reads-from relation.  It also adds an entry for happens-before,
and refers to the corresponding section of explanation.txt.

Reported-by: Boqun Feng <boqun.feng@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
tools/memory-model: Add a glossary of LKMM terms 2020-11-07T01:24:53+00:00 Paul E. McKenney paulmck@kernel.org 2020-10-22T22:16:08+00:00 0a27ce6b6968866fa8e3bd70371d67752db7718f [ paulmck: Apply Alan Stern feedback. ] Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
[ paulmck: Apply Alan Stern feedback. ]
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
tools/memory-model: Document categories of ordering primitives 2020-11-07T01:24:50+00:00 Paul E. McKenney paulmck@kernel.org 2020-08-11T18:27:33+00:00 ebb477cb2fb7a44ff600e0a7393bad906a0ecd80 The Linux kernel has a number of categories of ordering primitives, which are recorded in the LKMM implementation and hinted at by cheatsheet.txt. But there is no overview of these categories, and such an overview is needed in order to understand multithreaded LKMM litmus tests. This commit therefore adds an ordering.txt as well as extracting a control-dependencies.txt from memory-barriers.txt. It also updates the README file. [ paulmck: Apply Akira Yokosawa file-placement feedback. ] [ paulmck: Apply Alan Stern feedback. ] [ paulmck: Apply self-review feedback. ] Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
The Linux kernel has a number of categories of ordering primitives, which
are recorded in the LKMM implementation and hinted at by cheatsheet.txt.
But there is no overview of these categories, and such an overview
is needed in order to understand multithreaded LKMM litmus tests.
This commit therefore adds an ordering.txt as well as extracting a
control-dependencies.txt from memory-barriers.txt.  It also updates the
README file.

[ paulmck:  Apply Akira Yokosawa file-placement feedback. ]
[ paulmck:  Apply Alan Stern feedback. ]
[ paulmck:  Apply self-review feedback. ]
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
tools/memory-model: Move Documentation description to Documentation/README 2020-10-26T23:18:53+00:00 Paul E. McKenney paulmck@kernel.org 2020-08-04T21:00:17+00:00 ab8bcad67bee82e4be290b32f0faaf582d7c3edc This commit moves the descriptions of the files residing in tools/memory-model/Documentation to a README file in that directory, leaving behind the description of tools/memory-model/Documentation/README itself. After this change, tools/memory-model/Documentation/README provides a guide to the files in the tools/memory-model/Documentation directory, guiding people with different skills and needs to the most appropriate starting point. Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
This commit moves the descriptions of the files residing in
tools/memory-model/Documentation to a README file in that directory,
leaving behind the description of tools/memory-model/Documentation/README
itself.  After this change, tools/memory-model/Documentation/README
provides a guide to the files in the tools/memory-model/Documentation
directory, guiding people with different skills and needs to the most
appropriate starting point.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
tools: memory-model: Document that the LKMM can easily miss control dependencies 2020-10-26T23:18:53+00:00 Alan Stern stern@rowland.harvard.edu 2020-10-04T01:40:22+00:00 9270e1a744f8ed953009b0e94b26ed0912d9ec1c Add a small section to the litmus-tests.txt documentation file for the Linux Kernel Memory Model explaining that the memory model often fails to recognize certain control dependencies. Suggested-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Alan Stern <stern@rowland.harvard.edu> Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
Add a small section to the litmus-tests.txt documentation file for
the Linux Kernel Memory Model explaining that the memory model often
fails to recognize certain control dependencies.

Suggested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
tools/memory-model: Expand the cheatsheet.txt notion of relaxed 2020-09-04T18:58:15+00:00 Paul E. McKenney paulmck@kernel.org 2020-08-04T18:35:56+00:00 0ce0c78eff7d22c8a261de6c4305a5abb638c200 This commit adds a key entry enumerating the various types of relaxed operations. While in the area, it also renames the relaxed rows. [ paulmck: Apply Boqun Feng feedback. ] Acked-by: Boqun Feng <boqun.feng@gmail.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
This commit adds a key entry enumerating the various types of relaxed
operations.  While in the area, it also renames the relaxed rows.

[ paulmck: Apply Boqun Feng feedback. ]
Acked-by: Boqun Feng <boqun.feng@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
tools/memory-model: Add a simple entry point document 2020-09-03T16:51:01+00:00 Paul E. McKenney paulmck@kernel.org 2020-08-04T17:58:55+00:00 0b8c06b75ea143f3c68aa419c36e82d9ab7454f8 Current LKMM documentation assumes that the reader already understands concurrency in the Linux kernel, which won't necessarily always be the case. This commit supplies a simple.txt file that provides a starting point for someone who is new to concurrency in the Linux kernel. That said, this file might also useful as a reminder to experienced developers of simpler approaches to dealing with concurrency. Link: Link: https://lwn.net/Articles/827180/ [ paulmck: Apply feedback from Joel Fernandes. ] Co-developed-by: Dave Chinner <dchinner@redhat.com> Signed-off-by: Dave Chinner <dchinner@redhat.com> Co-developed-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org> 
Current LKMM documentation assumes that the reader already understands
concurrency in the Linux kernel, which won't necessarily always be the
case.  This commit supplies a simple.txt file that provides a starting
point for someone who is new to concurrency in the Linux kernel.
That said, this file might also useful as a reminder to experienced
developers of simpler approaches to dealing with concurrency.

Link: Link: https://lwn.net/Articles/827180/
[ paulmck: Apply feedback from Joel Fernandes. ]
Co-developed-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Dave Chinner <dchinner@redhat.com>
Co-developed-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>