Received-SPF: pass (google.com: domain of linux-kernel+bounces-132034-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
From: "Paul E. McKenney" <paulmck@kernel.org>
To: linux-kernel@vger.kernel.org,
	linux-arch@vger.kernel.org,
	kernel-team@meta.com,
	mingo@kernel.org
Cc: stern@rowland.harvard.edu,
	parri.andrea@gmail.com,
	will@kernel.org,
	peterz@infradead.org,
	boqun.feng@gmail.com,
	npiggin@gmail.com,
	dhowells@redhat.com,
	j.alglave@ucl.ac.uk,
	luc.maranget@inria.fr,
	akiyks@gmail.com,
	"Paul E. McKenney" <paulmck@kernel.org>,
	Daniel Lustig <dlustig@nvidia.com>,
	Joel Fernandes <joel@joelfernandes.org>,
	Mark Rutland <mark.rutland@arm.com>,
	Jonathan Corbet <corbet@lwn.net>,
	linux-doc@vger.kernel.org
Subject: [PATCH memory-model 1/3] Documentation/litmus-tests: Add locking tests to README
Date: Thu,  4 Apr 2024 12:26:47 -0700
Message-Id: <20240404192649.531112-1-paulmck@kernel.org>
In-Reply-To: <8550daf1-4bfd-4607-8325-bfb7c1e2d8c7@paulmck-laptop>
References: <8550daf1-4bfd-4607-8325-bfb7c1e2d8c7@paulmck-laptop>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

This commit documents the litmus tests in the "locking" directory.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Cc: Alan Stern <stern@rowland.harvard.edu>
Cc: Will Deacon <will@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Boqun Feng <boqun.feng@gmail.com>
Cc: Nicholas Piggin <npiggin@gmail.com>
Cc: David Howells <dhowells@redhat.com>
Cc: Jade Alglave <j.alglave@ucl.ac.uk>
Cc: Luc Maranget <luc.maranget@inria.fr>
Cc: "Paul E. McKenney" <paulmck@kernel.org>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: Daniel Lustig <dlustig@nvidia.com>
Cc: Joel Fernandes <joel@joelfernandes.org>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: <linux-arch@vger.kernel.org>
Cc: <linux-doc@vger.kernel.org>
---
 Documentation/litmus-tests/README | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/Documentation/litmus-tests/README b/Documentation/litmus-tests/README
index 658d37860d397..5c8915e6fb684 100644
--- a/Documentation/litmus-tests/README
+++ b/Documentation/litmus-tests/README
@@ -22,6 +22,35 @@ Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus
     NOTE: Require herd7 7.56 or later which supports "(void)expr".
 
 
+locking (/locking directory)
+----------------------------
+
+DCL-broken.litmus
+	Demonstrates that double-checked locking needs more than just
+	the obvious lock acquisitions and releases.
+
+DCL-fixed.litmus
+	Demonstrates corrected double-checked locking that uses
+	smp_store_release() and smp_load_acquire() in addition to the
+	obvious lock acquisitions and releases.
+
+RM-broken.litmus
+	Demonstrates problems with "roach motel" locking, where code is
+	freely moved into lock-based critical sections.  This example also
+	shows how to use the "filter" clause to discard executions that
+	would be excluded by other code not modeled in the litmus test.
+	Note also that this "roach motel" optimization is emulated by
+	physically moving P1()'s two reads from x under the lock.
+
+	What is a roach motel?	This is from an old advertisement for
+	a cockroach trap, much later featured in one of the "Men in
+	Black" movies.	"The roaches check in.	They don't check out."
+
+RM-fixed.litmus
+	The counterpart to RM-broken.litmus, showing P0()'s two loads from
+	x safely outside of the critical section.
+
+
 RCU (/rcu directory)
 --------------------
 
-- 
2.40.1