[PATCH 0/4] tools/memory-model: Documentation updates and fixes

[PATCH 0/4] tools/memory-model: Documentation updates and fixes

[Akira Yokosawa]

Hi,

While re-reading LKMM documents, I noticed minor issues here and there.

This patch set is a collection of updates and fixes resolving them.

Patch 1/4 clarifies the relation of locking.txt and recipes.txt.
Patches 2/4 and 3/4 are trivial fixes of typos.
Patch 4/4 removes a link of MIPS doc which does not work.

        Thanks, Akira
--
Akira Yokosawa (4):
  tools/memory-model: docs/README: Update introduction of locking.txt
  tools/memory-model: docs/simple.txt: Fix trivial typos
  tools/memory-model: docs/ordering: Fix trivial typos
  tools/memory-model: docs/references: Remove broken link to imgtec.com

 tools/memory-model/Documentation/README       |  7 +++++--
 tools/memory-model/Documentation/locking.txt  |  5 +++++
 tools/memory-model/Documentation/ordering.txt | 20 +++++++++----------
 tools/memory-model/Documentation/recipes.txt  |  4 ++++
 .../memory-model/Documentation/references.txt |  3 +--
 tools/memory-model/Documentation/simple.txt   |  4 ++--
 6 files changed, 27 insertions(+), 16 deletions(-)


base-commit: 87d07e135725dd8976a5ddbc7dfa968198d9ae91
-- 
2.34.1

[PATCH 1/4] tools/memory-model: docs/README: Update introduction of locking.txt

[Akira Yokosawa]

Commit 9bc931e9e161 ("tools/memory-model: Add locking.txt and
glossary.txt to README") failed to mention the relation of the "Locking"
section in recipes.txt and locking.txt. 

The latter is a detailed version of the former intended to be read on
its own.

Reword the description in README and add notes in locking.txt and
recipes.txt to clarify their relationship.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 tools/memory-model/Documentation/README      | 7 +++++--
 tools/memory-model/Documentation/locking.txt | 5 +++++
 tools/memory-model/Documentation/recipes.txt | 4 ++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README
index 9999c1effdb6..43602f7822ec 100644
--- a/tools/memory-model/Documentation/README
+++ b/tools/memory-model/Documentation/README
@@ -23,8 +23,11 @@ o	You are familiar with the Linux-kernel concurrency primitives
 	that you need, and just want to get started with LKMM litmus
 	tests:  litmus-tests.txt
 
-o	You would like to access lock-protected shared variables without
-	having their corresponding locks held:  locking.txt
+o	Your immediate concern is to access lock-protected shared variables
+	without holding their corresponding locks:  locking.txt
+
+	While it is an expanded version of section "Locking" in recipes.txt,
+	it is supposed to be readable on its own.
 
 o	You are familiar with Linux-kernel concurrency, and would
 	like a detailed intuitive understanding of LKMM, including
diff --git a/tools/memory-model/Documentation/locking.txt b/tools/memory-model/Documentation/locking.txt
index 65c898c64a93..b29b3a978df3 100644
--- a/tools/memory-model/Documentation/locking.txt
+++ b/tools/memory-model/Documentation/locking.txt
@@ -1,3 +1,8 @@
+[!] Note:
+	This is an expanded version of section "Locking" in recipes.txt
+	focusing on accessing lock-protected shared variables without
+	holding their corresponding locks.
+
 Locking
 =======
 
diff --git a/tools/memory-model/Documentation/recipes.txt b/tools/memory-model/Documentation/recipes.txt
index 03f58b11c252..ce531767adfd 100644
--- a/tools/memory-model/Documentation/recipes.txt
+++ b/tools/memory-model/Documentation/recipes.txt
@@ -61,6 +61,10 @@ usual) some things to be careful of:
 Locking
 -------
 
+[!] Note:
+	locking.txt expands on this section, focusing on accessing lock-
+	protected shared variables without holding their corresponding locks.
+
 Locking is well-known and straightforward, at least if you don't think
 about it too hard.  And the basic rule is indeed quite simple: Any CPU that
 has acquired a given lock sees any changes previously seen or made by any
-- 
2.34.1

[PATCH 2/4] tools/memory-model: docs/simple.txt: Fix trivial typos

[Akira Yokosawa]

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 tools/memory-model/Documentation/simple.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/memory-model/Documentation/simple.txt b/tools/memory-model/Documentation/simple.txt
index 21f06c1d1b70..2df148630cdc 100644
--- a/tools/memory-model/Documentation/simple.txt
+++ b/tools/memory-model/Documentation/simple.txt
@@ -134,7 +134,7 @@ Packaged primitives: Sequence locking
 Lockless programming is considered by many to be more difficult than
 lock-based programming, but there are a few lockless design patterns that
 have been built out into an API.  One of these APIs is sequence locking.
-Although this APIs can be used in extremely complex ways, there are simple
+Although this API can be used in extremely complex ways, there are simple
 and effective ways of using it that avoid the need to pay attention to
 memory ordering.
 
@@ -205,7 +205,7 @@ If you want to keep things simple, use the initialization and read-out
 operations from the previous section only when there are no racing
 accesses.  Otherwise, use only fully ordered operations when accessing
 or modifying the variable.  This approach guarantees that code prior
-to a given access to that variable will be seen by all CPUs has having
+to a given access to that variable will be seen by all CPUs as having
 happened before any code following any later access to that same variable.
 
 Please note that per-CPU functions are not atomic operations and
-- 
2.34.1

[PATCH 3/4] tools/memory-model: docs/ordering: Fix trivial typos

[Akira Yokosawa]

Fix trivial typos including:

  - Repeated "a call to"
  - Inconsistent forms of referencing functions of rcu_dereference()
    and rcu_assign_pointer()
  - Past tense used in describing normal behavior

and other minor ones.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 tools/memory-model/Documentation/ordering.txt | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt
index 9b0949d3f5ec..96587646d0cc 100644
--- a/tools/memory-model/Documentation/ordering.txt
+++ b/tools/memory-model/Documentation/ordering.txt
@@ -223,7 +223,7 @@ The Linux kernel's compiler barrier is barrier().  This primitive
 prohibits compiler code-motion optimizations that might move memory
 references across the point in the code containing the barrier(), but
 does not constrain hardware memory ordering.  For example, this can be
-used to prevent to compiler from moving code across an infinite loop:
+used to prevent the compiler from moving code across an infinite loop:
 
 	WRITE_ONCE(x, 1);
 	while (dontstop)
@@ -274,7 +274,7 @@ different pieces of the concurrent algorithm.  The variable stored to
 by the smp_store_release(), in this case "y", will normally be used in
 an acquire operation in other parts of the concurrent algorithm.
 
-To see the performance advantages, suppose that the above example read
+To see the performance advantages, suppose that the above example reads
 from "x" instead of writing to it.  Then an smp_wmb() could not guarantee
 ordering, and an smp_mb() would be needed instead:
 
@@ -394,17 +394,17 @@ from the value returned by the rcu_dereference() or srcu_dereference()
 to that subsequent memory access.
 
 A call to rcu_dereference() for a given RCU-protected pointer is
-usually paired with a call to a call to rcu_assign_pointer() for that
-same pointer in much the same way that a call to smp_load_acquire() is
-paired with a call to smp_store_release().  Calls to rcu_dereference()
-and rcu_assign_pointer are often buried in other APIs, for example,
+usually paired with a call to rcu_assign_pointer() for that same pointer
+in much the same way that a call to smp_load_acquire() is paired with
+a call to smp_store_release().  Calls to rcu_dereference() and
+rcu_assign_pointer() are often buried in other APIs, for example,
 the RCU list API members defined in include/linux/rculist.h.  For more
 information, please see the docbook headers in that file, the most
 recent LWN article on the RCU API (https://lwn.net/Articles/777036/),
 and of course the material in Documentation/RCU.
 
 If the pointer value is manipulated between the rcu_dereference()
-that returned it and a later dereference(), please read
+that returned it and a later rcu_dereference(), please read
 Documentation/RCU/rcu_dereference.rst.  It can also be quite helpful to
 review uses in the Linux kernel.
 
@@ -457,7 +457,7 @@ described earlier in this document.
 These operations come in three categories:
 
 o	Marked writes, such as WRITE_ONCE() and atomic_set().  These
-	primitives required the compiler to emit the corresponding store
+	primitives requires the compiler to emit the corresponding store
 	instructions in the expected execution order, thus suppressing
 	a number of destructive optimizations.	However, they provide no
 	hardware ordering guarantees, and in fact many CPUs will happily
@@ -465,7 +465,7 @@ o	Marked writes, such as WRITE_ONCE() and atomic_set().  These
 	operations, unless these operations are to the same variable.
 
 o	Marked reads, such as READ_ONCE() and atomic_read().  These
-	primitives required the compiler to emit the corresponding load
+	primitives requires the compiler to emit the corresponding load
 	instructions in the expected execution order, thus suppressing
 	a number of destructive optimizations.	However, they provide no
 	hardware ordering guarantees, and in fact many CPUs will happily
@@ -506,7 +506,7 @@ of the old value and the new value.
 
 Unmarked C-language accesses are unordered, and are also subject to
 any number of compiler optimizations, many of which can break your
-concurrent code.  It is possible to used unmarked C-language accesses for
+concurrent code.  It is possible to use unmarked C-language accesses for
 shared variables that are subject to concurrent access, but great care
 is required on an ongoing basis.  The compiler-constraining barrier()
 primitive can be helpful, as can the various ordering primitives discussed
-- 
2.34.1

[PATCH 4/4] tools/memory-model: docs/references: Remove broken link to imgtec.com

[Akira Yokosawa]

MIPS documents are not provided at imgtec.com any more.
Get rid of useless link.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
Currently, a later version of the document is available at:
https://s3-eu-west-1.amazonaws.com/downloads-mips/documents/MD00087-2B-MIPS64BIS-AFP-6.06.pdf

It has a copyright notice of Wave Computing, Inc., but there is no info
on the entity who maintains it.
---
 tools/memory-model/Documentation/references.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/tools/memory-model/Documentation/references.txt b/tools/memory-model/Documentation/references.txt
index c5fdfd19df24..d691390620b3 100644
--- a/tools/memory-model/Documentation/references.txt
+++ b/tools/memory-model/Documentation/references.txt
@@ -46,8 +46,7 @@ o	ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
 
 o	Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
 	For Programmers, Volume II-A: The MIPS64(R) Instruction,
-	Set Reference Manual". Imagination Technologies,
-	LTD. https://imgtec.com/?do-download=4302.
+	Set Reference Manual". Imagination Technologies, LTD.
 
 o	Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
 	Sarkar, Ali Sezgin, Luc Maranget, Will Deacon, and Peter
-- 
2.34.1

Re: [PATCH 0/4] tools/memory-model: Documentation updates and fixes

[Paul E. McKenney]

On Fri, Mar 14, 2025 at 08:08:24PM +0900, Akira Yokosawa wrote:
> Hi,
> 
> While re-reading LKMM documents, I noticed minor issues here and there.
> 
> This patch set is a collection of updates and fixes resolving them.
> 
> Patch 1/4 clarifies the relation of locking.txt and recipes.txt.
> Patches 2/4 and 3/4 are trivial fixes of typos.
> Patch 4/4 removes a link of MIPS doc which does not work.

Queued and pushed, thank you!  I did a bit of wordsmithing and also
updated to the 2024 LWN API article, so could you please check to see
whether I messed anything up?

							Thanx, Paul

>         Thanks, Akira
> --
> Akira Yokosawa (4):
>   tools/memory-model: docs/README: Update introduction of locking.txt
>   tools/memory-model: docs/simple.txt: Fix trivial typos
>   tools/memory-model: docs/ordering: Fix trivial typos
>   tools/memory-model: docs/references: Remove broken link to imgtec.com
> 
>  tools/memory-model/Documentation/README       |  7 +++++--
>  tools/memory-model/Documentation/locking.txt  |  5 +++++
>  tools/memory-model/Documentation/ordering.txt | 20 +++++++++----------
>  tools/memory-model/Documentation/recipes.txt  |  4 ++++
>  .../memory-model/Documentation/references.txt |  3 +--
>  tools/memory-model/Documentation/simple.txt   |  4 ++--
>  6 files changed, 27 insertions(+), 16 deletions(-)
> 
> 
> base-commit: 87d07e135725dd8976a5ddbc7dfa968198d9ae91
> -- 
> 2.34.1
> 

Re: [PATCH 0/4] tools/memory-model: Documentation updates and fixes

[Akira Yokosawa]

On Mon, 17 Mar 2025 16:26:34 -0700, Paul E. McKenney wrote:
> On Fri, Mar 14, 2025 at 08:08:24PM +0900, Akira Yokosawa wrote:
>> Hi,
>>
>> While re-reading LKMM documents, I noticed minor issues here and there.
>>
>> This patch set is a collection of updates and fixes resolving them.
>>
>> Patch 1/4 clarifies the relation of locking.txt and recipes.txt.
>> Patches 2/4 and 3/4 are trivial fixes of typos.
>> Patch 4/4 removes a link of MIPS doc which does not work.
> 
> Queued and pushed, thank you!  I did a bit of wordsmithing and also
> updated to the 2024 LWN API article, so could you please check to see
> whether I messed anything up?

All look good to me!

Thanks, Akira