linux.git/tools/memory-model/README, branch v6.18.21

tools/memory-model/README: Fix typo

2025-02-25T18:22:34+00:00

Fix a trivial typo.

Signed-off-by: Akira Yokosawa 
Signed-off-by: Paul E. McKenney

tools/memory-model: Switch to softcoded herd7 tags

2025-02-25T18:16:57+00:00

A new version of herd7 provides a -lkmmv2 switch which overrides the old herd7
behavior of simply ignoring any softcoded tags in the .def and .bell files. We
port LKMM to this version of herd7 by providing the switch in linux-kernel.cfg
and reporting an error if the LKMM is used without this switch.

To preserve the semantics of LKMM, we also softcode the Noreturn tag on atomic
RMW which do not return a value and define atomic_add_unless with an Mb tag in
linux-kernel.def.

We update the herd-representation.txt accordingly and clarify some of the
resulting combinations.

Co-developed-by: Hernan Ponce de Leon 
Signed-off-by: Hernan Ponce de Leon 
Signed-off-by: Jonas Oberhauser 
Signed-off-by: Paul E. McKenney 
Reviewed-by: Boqun Feng 
Tested-by: Boqun Feng 
Tested-by: Akira Yokosawa  # herdtools7.7.58

tools/memory-model/README: Update klitmus7 compat table

2022-05-03T17:12:48+00:00

EXPORT_SYMBOL of do_exec() was removed in v5.17.  Unfortunately,
kernel modules from klitmus7 7.56 have do_exec() at the end of
each kthread.

herdtools7 7.56.1 has addressed the issue.

Update the compatibility table accordingly.

Signed-off-by: Akira Yokosawa 
Cc: Luc Maranget 
Cc: Jade Alglave 
Cc: stable@vger.kernel.org # v5.17+
Signed-off-by: Paul E. McKenney

tools/memory-model: doc: Describe the requirement of the litmus-tests directory

2021-12-01T01:47:08+00:00

It's better that we have some "standard" about which test should be put
in the litmus-tests directory because it helps future contributors
understand whether they should work on litmus-tests in kernel or Paul's
GitHub repo. Therefore explain a little bit on what a "representative"
litmus test is.

Signed-off-by: Boqun Feng 
Acked-by: Peter Zijlstra (Intel) 
Signed-off-by: Paul E. McKenney

tools/memory-model: Fix typo in klitmus7 compatibility table

2021-01-04T22:40:50+00:00

klitmus7 of herdtools7 7.48 or earlier depends on ACCESS_ONCE(),
which was removed in Linux v4.15.
Fix the obvious typo in the table.

Fixes: d075a78a5ab1 ("tools/memory-model/README: Expand dependency of klitmus7")
Signed-off-by: Akira Yokosawa 
Signed-off-by: Paul E. McKenney

tools/memory-model: Move Documentation description to Documentation/README

2020-10-26T23:18:53+00:00

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

tools/memory-model: Add a simple entry point document

2020-09-03T16:51:01+00:00

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 
Signed-off-by: Dave Chinner 
Co-developed-by: Paul E. McKenney 
Signed-off-by: Paul E. McKenney

tools/memory-model: Improve litmus-test documentation

2020-09-03T16:51:01+00:00

The current LKMM documentation says very little about litmus tests, and
worse yet directs people to the herd7 documentation for more information.
Now, the herd7 documentation is quite voluminous and educational,
but it is intended for people creating and modifying memory models,
not those attempting to use them.

This commit therefore updates README and creates a litmus-tests.txt
file that gives an overview of litmus-test format and describes ways of
modeling various special cases, illustrated with numerous examples.

[ paulmck: Add Alan Stern feedback. ]
[ paulmck: Apply Dave Chinner feedback. ]
[ paulmck: Apply Andrii Nakryiko feedback. ]
[ paulmck: Apply Johannes Weiner feedback. ]
Link: https://lwn.net/Articles/827180/
Reported-by: Dave Chinner 
Acked-by: Peter Zijlstra (Intel) 
Signed-off-by: Paul E. McKenney

tools/memory-model/README: Mention herdtools7 7.56 in compatibility table

2020-06-29T19:05:18+00:00

herdtools7 7.56 is going to be released in the week of 22 Jun 2020.
This commit therefore adds the exact version in the compatibility table.

Acked-by: Andrea Parri 
Signed-off-by: Akira Yokosawa 
Signed-off-by: Paul E. McKenney

tools/memory-model/README: Expand dependency of klitmus7

2020-06-29T19:05:18+00:00

klitmus7 is independent of the memory model but depends on the
build-target kernel release.
It occasionally lost compatibility due to kernel API changes [1, 2, 3].
It was remedied in a backwards-compatible manner respectively [4, 5, 6].

Reflect this fact in README.

[1]: b899a850431e ("compiler.h: Remove ACCESS_ONCE()")
[2]: 0bb95f80a38f ("Makefile: Globally enable VLA warning")
[3]: d56c0d45f0e2 ("proc: decouple proc from VFS with "struct proc_ops"")
[4]: https://github.com/herd/herdtools7/commit/e87d7f9287d1
     ("klitmus: Use WRITE_ONCE and READ_ONCE in place of deprecated ACCESS_ONCE")
[5]: https://github.com/herd/herdtools7/commit/a0cbb10d02be
     ("klitmus: Avoid variable length array")
[6]: https://github.com/herd/herdtools7/commit/46b9412d3a58
     ("klitmus: Linux kernel v5.6.x compat")

NOTE: [5] was ahead of herdtools7 7.53, which did not make an
official release.  Code generated by klitmus7 without [5] can still be
built targeting Linux 4.20--5.5 if you don't care VLA warnings.

Acked-by: Andrea Parri 
Signed-off-by: Akira Yokosawa 
Signed-off-by: Paul E. McKenney