linux-kernel - [tip: locking/core] documentation: seqlock: fix the wrong documentation of read_seqbegin_or_lock/need

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <176104292495.2601451.15194014939190830588.tip-bot2@tip-bot2>
Date: Tue, 21 Oct 2025 10:35:24 -0000
From: "tip-bot2 for Oleg Nesterov" <tip-bot2@...utronix.de>
To: linux-tip-commits@...r.kernel.org
Cc: Oleg Nesterov <oleg@...hat.com>,
 "Peter Zijlstra (Intel)" <peterz@...radead.org>, x86@...nel.org,
 linux-kernel@...r.kernel.org
Subject: [tip: locking/core] documentation: seqlock: fix the wrong
 documentation of read_seqbegin_or_lock/need_seqretry

The following commit has been merged into the locking/core branch of tip:

Commit-ID:     28a0ee311960baad97bf85e1e995aed4a71e22a2
Gitweb:        https://git.kernel.org/tip/28a0ee311960baad97bf85e1e995aed4a71e22a2
Author:        Oleg Nesterov <oleg@...hat.com>
AuthorDate:    Sun, 28 Sep 2025 18:20:29 +02:00
Committer:     Peter Zijlstra <peterz@...radead.org>
CommitterDate: Tue, 21 Oct 2025 12:31:56 +02:00

documentation: seqlock: fix the wrong documentation of read_seqbegin_or_lock/need_seqretry

The comments and pseudo code in Documentation/locking/seqlock.rst are wrong:

	int seq = 0;
	do {
		read_seqbegin_or_lock(&foo_seqlock, &seq);

		/* ... [[read-side critical section]] ... */

	} while (need_seqretry(&foo_seqlock, seq));

read_seqbegin_or_lock() always returns with an even "seq" and need_seqretry()
doesn't change this counter. This means that seq is always even and thus the
locking pass is simply impossible.

IOW, "_or_lock" has no effect and this code doesn't differ from

	do {
		seq = read_seqbegin(&foo_seqlock);

		/* ... [[read-side critical section]] ... */

	} while (read_seqretry(&foo_seqlock, seq));

Signed-off-by: Oleg Nesterov <oleg@...hat.com>
Signed-off-by: Peter Zijlstra (Intel) <peterz@...radead.org>
---
 Documentation/locking/seqlock.rst |  9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst
index 3fb7ea3..9899871 100644
--- a/Documentation/locking/seqlock.rst
+++ b/Documentation/locking/seqlock.rst
@@ -220,13 +220,14 @@ Read path, three categories:
    according to a passed marker. This is used to avoid lockless readers
    starvation (too much retry loops) in case of a sharp spike in write
    activity. First, a lockless read is tried (even marker passed). If
-   that trial fails (odd sequence counter is returned, which is used as
-   the next iteration marker), the lockless read is transformed to a
-   full locking read and no retry loop is necessary::
+   that trial fails (sequence counter doesn't match), make the marker
+   odd for the next iteration, the lockless read is transformed to a
+   full locking read and no retry loop is necessary, for example::
 
 	/* marker; even initialization */
-	int seq = 0;
+	int seq = 1;
 	do {
+		seq++; /* 2 on the 1st/lockless path, otherwise odd */
 		read_seqbegin_or_lock(&foo_seqlock, &seq);
 
 		/* ... [[read-side critical section]] ... */