linux/scripts/atomic
Mark Rutland 6dfee110c6 locking/atomic: scripts: Clarify ordering of conditional atomics
Conditional atomic operations (e.g. cmpxchg()) only provide ordering
when the condition holds; when the condition does not hold, the location
is not modified and relaxed ordering is provided. Where ordering is
needed for failed conditional atomics, it is necessary to use
smp_mb__before_atomic() and/or smp_mb__after_atomic().

This is explained tersely in memory-barriers.txt, and is implied but not
explicitly stated in the kerneldoc comments for the conditional
operations. The lack of an explicit statement has lead to some off-list
queries about the ordering semantics of failing conditional operations,
so evidently this is confusing.

Update the kerneldoc comments to explicitly describe the lack of ordering
for failed conditional atomic operations.

For most conditional atomic operations, this is written as:

  | If (${condition}), atomically updates @v to (${new}) with ${desc_order} ordering.
  | Otherwise, @v is not modified and relaxed ordering is provided.

For the try_cmpxchg() operations, this is written as:

  | If (${condition}), atomically updates @v to @new with ${desc_order} ordering.
  | Otherwise, @v is not modified, @old is updated to the current value of @v,
  | and relaxed ordering is provided.

Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Reviewed-by: Paul E. McKenney <paulmck@kernel.org>
Reviewed-by: Nhat Pham <nphamcs@gmail.com>
Link: https://lore.kernel.org/r/20240209124010.2096198-1-mark.rutland@arm.com
2024-02-20 09:55:09 +01:00
..
fallbacks locking/atomic: scripts: simplify raw_atomic*() definitions 2023-06-05 09:57:22 +02:00
kerneldoc locking/atomic: scripts: Clarify ordering of conditional atomics 2024-02-20 09:55:09 +01:00
atomic-tbl.sh locking/atomic: scripts: generate kerneldoc comments 2023-06-05 09:57:23 +02:00
atomics.tbl locking/atomic: scripts: simplify raw_atomic*() definitions 2023-06-05 09:57:22 +02:00
gen-atomic-fallback.sh locking/atomic: Add generic support for sync_try_cmpxchg() and its fallback 2023-10-09 18:14:15 +02:00
gen-atomic-instrumented.sh locking/atomic: Add generic support for sync_try_cmpxchg() and its fallback 2023-10-09 18:14:15 +02:00
gen-atomic-long.sh locking/atomic: scripts: generate kerneldoc comments 2023-06-05 09:57:23 +02:00
gen-atomics.sh locking/atomic: scripts: restructure fallback ifdeffery 2023-06-05 09:57:21 +02:00