linux-kernel - Re: [PATCH 1/1] 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] [thread-next>] [day] [month] [year] [list]

Message-ID: <b83e9c1d-2623-4abf-8c63-1110a0b92d2e@redhat.com>
Date: Wed, 1 Oct 2025 14:21:11 -0400
From: Waiman Long <llong@...hat.com>
To: Oleg Nesterov <oleg@...hat.com>, Boqun Feng <boqun.feng@...il.com>,
 David Howells <dhowells@...hat.com>, Ingo Molnar <mingo@...hat.com>,
 Li RongQing <lirongqing@...du.com>,
 Linus Torvalds <torvalds@...ux-foundation.org>,
 Peter Zijlstra <peterz@...radead.org>, Will Deacon <will@...nel.org>
Cc: linux-kernel@...r.kernel.org
Subject: Re: [PATCH 1/1] documentation: seqlock: fix the wrong documentation
 of read_seqbegin_or_lock/need_seqretry

On 9/28/25 12:20 PM, Oleg Nesterov wrote:
> 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>
> ---
>   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 ec6411d02ac8..167d442d3c7f 100644
> --- a/Documentation/locking/seqlock.rst
> +++ b/Documentation/locking/seqlock.rst
> @@ -218,13 +218,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]] ... */

It is kind of odd to initialize the sequence to 1 and add an sequence 
increment inside the loop. Perhaps we can do something like:

diff --git a/include/linux/seqlock.h b/include/linux/seqlock.h
index 5ce48eab7a2a..0f607ef28d98 100644
--- a/include/linux/seqlock.h
+++ b/include/linux/seqlock.h
@@ -1126,6 +1126,9 @@ read_sequnlock_excl_irqrestore(seqlock_t *sl, 
unsigned long flags)
   */
  static inline void read_seqbegin_or_lock(seqlock_t *lock, int *seq)
  {
+       if (!(*seq & 1))        /* Reread sequence # if even */
+               *seq = seqprop_sequence(&lock->seqcount);
+
         if (!(*seq & 1))        /* Even */
                 *seq = read_seqbegin(lock);
         else                    /* Odd */
@@ -1144,6 +1147,15 @@ static inline int need_seqretry(seqlock_t *lock, 
int seq)
         return !(seq & 1) && read_seqretry(lock, seq);
  }

+static inline int need_seqretry_once(seqlock_t *lock, int *seq)
+{
+       int ret = !(*seq & 1) && read_seqretry(lock, *seq);
+
+       if (ret)
+               *seq = 1;       /* Enforce locking in next iteration */
+       return ret;
+}
+

With this, the current document should be good. Users have the option of 
using need_seqretry_once() to enforce at most 1 iteration. Of course, we 
still need to do similar change to the other read_seqbegin_or_lock_*() 
variants.

My 2 cents.

Cheers,
Longman