Commit b33eb50a authored by Mark Rutland's avatar Mark Rutland Committed by Peter Zijlstra
Browse files

locking/atomic: scripts: fix ${atomic}_dec_if_positive() kerneldoc 



The ${atomic}_dec_if_positive() ops are unlike all the other conditional
atomic ops. Rather than returning a boolean success value, these return
the value that the atomic variable would be updated to, even when no
update is performed.

We missed this when adding kerneldoc comments, and the documentation for
${atomic}_dec_if_positive() erroneously states:

| Return: @true if @v was updated, @false otherwise.

Ideally we'd clean this up by aligning ${atomic}_dec_if_positive() with
the usual atomic op conventions: with ${atomic}_fetch_dec_if_positive()
for those who care about the value of the varaible, and
${atomic}_dec_if_positive() returning a boolean success value.

In the mean time, align the documentation with the current reality.

Fixes: ad811070 ("locking/atomic: scripts: generate kerneldoc comments")
Signed-off-by: default avatarMark Rutland <mark.rutland@arm.com>
Signed-off-by: default avatarPeter Zijlstra (Intel) <peterz@infradead.org>
Reviewed-by: default avatarPaul E. McKenney <paulmck@kernel.org>
Link: https://lore.kernel.org/r/20230615132734.1119765-1-mark.rutland@arm.com
parent 093d9b24

include/linux/atomic/atomic-arch-fallback.h

+3 −3
Original line number Diff line number Diff line
@@ -2520,7 +2520,7 @@ raw_atomic_dec_unless_positive(atomic_t *v) 
 *

 * Safe to use in noinstr code; prefer atomic_dec_if_positive() elsewhere.

 *

 * Return: @true if @v was updated, @false otherwise.

 * Return: The old value of (@v - 1), regardless of whether @v was updated.

 */

static __always_inline int

raw_atomic_dec_if_positive(atomic_t *v)
@@ -4636,7 +4636,7 @@ raw_atomic64_dec_unless_positive(atomic64_t *v) 
 *

 * Safe to use in noinstr code; prefer atomic64_dec_if_positive() elsewhere.

 *

 * Return: @true if @v was updated, @false otherwise.

 * Return: The old value of (@v - 1), regardless of whether @v was updated.

 */

static __always_inline s64

raw_atomic64_dec_if_positive(atomic64_t *v)
@@ -4657,4 +4657,4 @@ raw_atomic64_dec_if_positive(atomic64_t *v) 
}



#endif /* _LINUX_ATOMIC_FALLBACK_H */

// 3916f02c038baa3f5190d275f68b9211667fcc9d
 
// 202b45c7db600ce36198eb1f1fc2c2d5268ace2d

include/linux/atomic/atomic-instrumented.h

+4 −4
Original line number Diff line number Diff line
@@ -1570,7 +1570,7 @@ atomic_dec_unless_positive(atomic_t *v) 
 *

 * Unsafe to use in noinstr code; use raw_atomic_dec_if_positive() there.

 *

 * Return: @true if @v was updated, @false otherwise.

 * Return: The old value of (@v - 1), regardless of whether @v was updated.

 */

static __always_inline int

atomic_dec_if_positive(atomic_t *v)
@@ -3134,7 +3134,7 @@ atomic64_dec_unless_positive(atomic64_t *v) 
 *

 * Unsafe to use in noinstr code; use raw_atomic64_dec_if_positive() there.

 *

 * Return: @true if @v was updated, @false otherwise.

 * Return: The old value of (@v - 1), regardless of whether @v was updated.

 */

static __always_inline s64

atomic64_dec_if_positive(atomic64_t *v)
@@ -4698,7 +4698,7 @@ atomic_long_dec_unless_positive(atomic_long_t *v) 
 *

 * Unsafe to use in noinstr code; use raw_atomic_long_dec_if_positive() there.

 *

 * Return: @true if @v was updated, @false otherwise.

 * Return: The old value of (@v - 1), regardless of whether @v was updated.

 */

static __always_inline long

atomic_long_dec_if_positive(atomic_long_t *v)
@@ -5000,4 +5000,4 @@ atomic_long_dec_if_positive(atomic_long_t *v) 




#endif /* _LINUX_ATOMIC_INSTRUMENTED_H */

// 06cec02e676a484857aee38b0071a1d846ec9457
 
// 1568f875fef72097413caab8339120c065a39aa4

include/linux/atomic/atomic-long.h

+2 −2
Original line number Diff line number Diff line
@@ -1782,7 +1782,7 @@ raw_atomic_long_dec_unless_positive(atomic_long_t *v) 
 *

 * Safe to use in noinstr code; prefer atomic_long_dec_if_positive() elsewhere.

 *

 * Return: @true if @v was updated, @false otherwise.

 * Return: The old value of (@v - 1), regardless of whether @v was updated.

 */

static __always_inline long

raw_atomic_long_dec_if_positive(atomic_long_t *v)
@@ -1795,4 +1795,4 @@ raw_atomic_long_dec_if_positive(atomic_long_t *v) 
}



#endif /* _LINUX_ATOMIC_LONG_H */

// 029d2e3a493086671e874a4c2e0e42084be42403
 
// 4ef23f98c73cff96d239896175fd26b10b88899e

scripts/atomic/kerneldoc/dec_if_positive

+1 −1
Original line number Diff line number Diff line
@@ -7,6 +7,6 @@ cat <<EOF 
 *

 * ${desc_noinstr}

 *

 * Return: @true if @v was updated, @false otherwise.

 * Return: The old value of (@v - 1), regardless of whether @v was updated.

 */

EOF