From: Akira Yokosawa <akiyks@gmail.com>
To: "Paul E. McKenney" <paulmck@kernel.org>
Cc: lkmm@lists.linux.dev, Andrea Parri <parri.andrea@gmail.com>,
Boqun Feng <boqun.feng@gmail.com>,
Alan Stern <stern@rowland.harvard.edu>,
Akira Yokosawa <akiyks@gmail.com>
Subject: [PATCH 1/4] tools/memory-model: docs/README: Update introduction of locking.txt
Date: Fri, 14 Mar 2025 20:10:30 +0900 [thread overview]
Message-ID: <9981e802-d201-4030-9922-b48c71126904@gmail.com> (raw)
In-Reply-To: <c3f8f79d-b815-44ec-908a-7eea36f52b3f@gmail.com>
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
next prev parent reply other threads:[~2025-03-14 11:17 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-03-14 11:08 [PATCH 0/4] tools/memory-model: Documentation updates and fixes Akira Yokosawa
2025-03-14 11:10 ` Akira Yokosawa [this message]
2025-03-14 11:12 ` [PATCH 2/4] tools/memory-model: docs/simple.txt: Fix trivial typos Akira Yokosawa
2025-03-14 11:14 ` [PATCH 3/4] tools/memory-model: docs/ordering: " Akira Yokosawa
2025-03-14 11:15 ` [PATCH 4/4] tools/memory-model: docs/references: Remove broken link to imgtec.com Akira Yokosawa
2025-03-17 23:26 ` [PATCH 0/4] tools/memory-model: Documentation updates and fixes Paul E. McKenney
2025-03-18 2:10 ` Akira Yokosawa
-- strict thread matches above, loose matches on Subject: below --
2025-04-18 17:29 [PATCH 0/4] LKMM documentation updates for v6.16 Paul E. McKenney
2025-04-18 17:29 ` [PATCH 1/4] tools/memory-model: docs/README: Update introduction of locking.txt Paul E. McKenney
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=9981e802-d201-4030-9922-b48c71126904@gmail.com \
--to=akiyks@gmail.com \
--cc=boqun.feng@gmail.com \
--cc=lkmm@lists.linux.dev \
--cc=parri.andrea@gmail.com \
--cc=paulmck@kernel.org \
--cc=stern@rowland.harvard.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).