[PATCH doc] Emphasize that failed atomic operations give no ordering

[PATCH doc] Emphasize that failed atomic operations give no ordering

[Paul E. McKenney]

The ORDERING section of Documentation/atomic_t.txt can easily be read as
saying that conditional atomic RMW operations that fail are ordered when
those operations have the _acquire() or _release() prefixes.  This is
not the case, therefore update this section to make it clear that failed
conditional atomic RMW operations provide no ordering.

Reported-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Cc: Alan Stern <stern@rowland.harvard.edu>
Cc: Andrea Parri <parri.andrea@gmail.com>
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>

diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt
index d7adc6d543db4..bee3b1bca9a7b 100644
--- a/Documentation/atomic_t.txt
+++ b/Documentation/atomic_t.txt
@@ -171,14 +171,14 @@ The rule of thumb:
  - RMW operations that are conditional are unordered on FAILURE,
    otherwise the above rules apply.
 
-Except of course when an operation has an explicit ordering like:
+Except of course when a successful operation has an explicit ordering like:
 
  {}_relaxed: unordered
  {}_acquire: the R of the RMW (or atomic_read) is an ACQUIRE
  {}_release: the W of the RMW (or atomic_set)  is a  RELEASE
 
 Where 'unordered' is against other memory locations. Address dependencies are
-not defeated.
+not defeated.  Conditional operations are still unordered on FAILURE.
 
 Fully ordered primitives are ordered against everything prior and everything
 subsequent. Therefore a fully ordered primitive is like having an smp_mb()

Re: [PATCH doc] Emphasize that failed atomic operations give no ordering

[Andrea Parri]

On Tue, Jan 30, 2024 at 06:53:38AM -0800, Paul E. McKenney wrote:
> The ORDERING section of Documentation/atomic_t.txt can easily be read as
> saying that conditional atomic RMW operations that fail are ordered when
> those operations have the _acquire() or _release() prefixes.  This is

s/prefixes/suffixes


> not the case, therefore update this section to make it clear that failed
> conditional atomic RMW operations provide no ordering.
> 
> Reported-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

You may want to add a "subsystem" to the subject line, git-log suggests
"Documentation/atomic_t".  Anyway,

Acked-by: Andrea Parri <parri.andrea@gmail.com>

  Andrea

Re: [PATCH doc] Emphasize that failed atomic operations give no ordering

[Paul E. McKenney]

On Tue, Jan 30, 2024 at 05:02:49PM +0100, Andrea Parri wrote:
> On Tue, Jan 30, 2024 at 06:53:38AM -0800, Paul E. McKenney wrote:
> > The ORDERING section of Documentation/atomic_t.txt can easily be read as
> > saying that conditional atomic RMW operations that fail are ordered when
> > those operations have the _acquire() or _release() prefixes.  This is
> 
> s/prefixes/suffixes

Good catch, fixed.

> > not the case, therefore update this section to make it clear that failed
> > conditional atomic RMW operations provide no ordering.
> > 
> > Reported-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
> > Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> 
> You may want to add a "subsystem" to the subject line, git-log suggests
> "Documentation/atomic_t".  Anyway,

Good point, done.

> Acked-by: Andrea Parri <parri.andrea@gmail.com>

Thank you!

							Thanx, Paul

Re: [PATCH doc] Emphasize that failed atomic operations give no ordering

[Mark Rutland]

On Tue, Jan 30, 2024 at 06:53:38AM -0800, Paul E. McKenney wrote:
> The ORDERING section of Documentation/atomic_t.txt can easily be read as
> saying that conditional atomic RMW operations that fail are ordered when
> those operations have the _acquire() or _release() prefixes.  This is
> not the case, therefore update this section to make it clear that failed
> conditional atomic RMW operations provide no ordering.
> 
> Reported-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> Cc: Alan Stern <stern@rowland.harvard.edu>
> Cc: Andrea Parri <parri.andrea@gmail.com>
> 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>
> 
> diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt
> index d7adc6d543db4..bee3b1bca9a7b 100644
> --- a/Documentation/atomic_t.txt
> +++ b/Documentation/atomic_t.txt
> @@ -171,14 +171,14 @@ The rule of thumb:
>   - RMW operations that are conditional are unordered on FAILURE,
>     otherwise the above rules apply.
>  
> -Except of course when an operation has an explicit ordering like:
> +Except of course when a successful operation has an explicit ordering like:
>  
>   {}_relaxed: unordered
>   {}_acquire: the R of the RMW (or atomic_read) is an ACQUIRE
>   {}_release: the W of the RMW (or atomic_set)  is a  RELEASE
>  
>  Where 'unordered' is against other memory locations. Address dependencies are
> -not defeated.
> +not defeated.  Conditional operations are still unordered on FAILURE.
>  
>  Fully ordered primitives are ordered against everything prior and everything
>  subsequent. Therefore a fully ordered primitive is like having an smp_mb()
> 

FWIW:

Acked-by: Mark Rutland <mark.rutland@arm.com>

Mark.

Re: [PATCH doc] Emphasize that failed atomic operations give no ordering

[Paul E. McKenney]

On Tue, Jan 30, 2024 at 05:12:23PM +0000, Mark Rutland wrote:
> On Tue, Jan 30, 2024 at 06:53:38AM -0800, Paul E. McKenney wrote:
> > The ORDERING section of Documentation/atomic_t.txt can easily be read as
> > saying that conditional atomic RMW operations that fail are ordered when
> > those operations have the _acquire() or _release() prefixes.  This is
> > not the case, therefore update this section to make it clear that failed
> > conditional atomic RMW operations provide no ordering.
> > 
> > Reported-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
> > Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> > Cc: Alan Stern <stern@rowland.harvard.edu>
> > Cc: Andrea Parri <parri.andrea@gmail.com>
> > 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>
> > 
> > diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt
> > index d7adc6d543db4..bee3b1bca9a7b 100644
> > --- a/Documentation/atomic_t.txt
> > +++ b/Documentation/atomic_t.txt
> > @@ -171,14 +171,14 @@ The rule of thumb:
> >   - RMW operations that are conditional are unordered on FAILURE,
> >     otherwise the above rules apply.
> >  
> > -Except of course when an operation has an explicit ordering like:
> > +Except of course when a successful operation has an explicit ordering like:
> >  
> >   {}_relaxed: unordered
> >   {}_acquire: the R of the RMW (or atomic_read) is an ACQUIRE
> >   {}_release: the W of the RMW (or atomic_set)  is a  RELEASE
> >  
> >  Where 'unordered' is against other memory locations. Address dependencies are
> > -not defeated.
> > +not defeated.  Conditional operations are still unordered on FAILURE.
> >  
> >  Fully ordered primitives are ordered against everything prior and everything
> >  subsequent. Therefore a fully ordered primitive is like having an smp_mb()
> > 
> 
> FWIW:
> 
> Acked-by: Mark Rutland <mark.rutland@arm.com>

Applied, thank you!

							Thanx, Paul