[PATCH v2 00/27] locking/atomic: restructuring + kerneldoc

Mark Rutland
2023-06-05T07:01:36Z

Hi all,

These patches restructure the generated atomic headers, and add
kerneldoc comments for all of the generic atomic{,64,_long}_t
operations.

The core headers now generate raw_atomic*() operations as the
fundamental instrumentation-safe atomics, with the arch_atomic*()
functions being an implementation detail that shouldn't be used
directly.

Each raw_atomic*() op is given a single definition with all related
ifdeffery inside, e.g.

| /**
| * raw_atomic_inc_return_acquire() - atomic increment with acquire ordering
| * @v: pointer to atomic_t
| *
| * Atomically updates @v to (@v + 1) with acquire ordering.
| *
| * Safe to use in noinstr code; prefer atomic_inc_return_acquire() elsewhere.
| *
| * Return: the updated value of @v.
| */
| static __always_inline int
| raw_atomic_inc_return_acquire(atomic_t *v)
| {
| #if defined(arch_atomic_inc_return_acquire)
| return arch_atomic_inc_return_acquire(v);
| #elif defined(arch_atomic_inc_return_relaxed)
| int ret = arch_atomic_inc_return_relaxed(v);
| __atomic_acquire_fence();
| return ret;
| #elif defined(arch_atomic_inc_return)
| return arch_atomic_inc_return(v);
| #else
| return raw_atomic_add_return_acquire(1, v);
| #endif
| }

Similarly, the regular atomic*() ops (which already have a single
definition) are given kerneldoc comments, e.g.

| /**
| * atomic_inc_return_acquire() - atomic increment with acquire ordering
| * @v: pointer to atomic_t
| *
| * Atomically updates @v to (@v + 1) with acquire ordering.
| *
| * Unsafe to use in noinstr code; use raw_atomic_inc_return_acquire() there.
| *
| * Return: the updated value of @v.
| */
| static __always_inline int
| atomic_inc_return_acquire(atomic_t *v)
| {
| instrument_atomic_read_write(v, sizeof(*v));
| return raw_atomic_inc_return_acquire(v);
| }

The kerneldoc comments themselves are built from templates as with the
fallbacks, which should allow them to be extended in future if necessary.

I've compile-tested this for a number of architectures and
configurations, but as usual this probably needs to see some testing by
build robots.

The patches are based on Peter Zijlstra's queued locking/core branch,
specifically commit:

bb6e9a06cba6b850 ("s390/cpum_sf: Convert to cmpxchg128()")

Which can be found in the git tree at:

https://git.kernel.org/pub/scm/linux/kernel/git/peterz/queue.git/

Since v1 [1]:
* Add kernel-doc handling of "~@v"
* Add atomic-instrumented.h to included documentation headers
* Fix typos and punctuation
* Clarify kerneldoc wording

[1] https://lore.kernel.org/lkml/20230522122429.1915021-1-mark.rutland@arm.com/

Thanks,
Mark.

Mark Rutland (26):
locking/atomic: arm: fix sync ops
locking/atomic: remove fallback comments
locking/atomic: hexagon: remove redundant arch_atomic_cmpxchg
locking/atomic: make atomic*_{cmp,}xchg optional
locking/atomic: arc: add preprocessor symbols
locking/atomic: arm: add preprocessor symbols
locking/atomic: hexagon: add preprocessor symbols
locking/atomic: m68k: add preprocessor symbols
locking/atomic: parisc: add preprocessor symbols
locking/atomic: sh: add preprocessor symbols
locking/atomic: sparc: add preprocessor symbols
locking/atomic: x86: add preprocessor symbols
locking/atomic: xtensa: add preprocessor symbols
locking/atomic: scripts: remove bogus order parameter
locking/atomic: scripts: remove leftover "${mult}"
locking/atomic: scripts: factor out order template generation
locking/atomic: scripts: add trivial raw_atomic*_<op>()
locking/atomic: treewide: use raw_atomic*_<op>()
locking/atomic: scripts: build raw_atomic_long*() directly
locking/atomic: scripts: restructure fallback ifdeffery
locking/atomic: scripts: split pfx/name/sfx/order
locking/atomic: scripts: simplify raw_atomic_long*() definitions
locking/atomic: scripts: simplify raw_atomic*() definitions
docs: scripts: kernel-doc: accept bitwise negation like ~@var
locking/atomic: scripts: generate kerneldoc comments
locking/atomic: treewide: delete arch_atomic_*() kerneldoc

Paul E. McKenney (1):
locking/atomic: docs: Add atomic operations to the driver basic API
documentation

Documentation/driver-api/basics.rst | 8 +-
arch/alpha/include/asm/atomic.h | 35 -
arch/arc/include/asm/atomic-spinlock.h | 9 +
arch/arc/include/asm/atomic.h | 24 -
arch/arc/include/asm/atomic64-arcv2.h | 19 +-
arch/arm/include/asm/assembler.h | 17 +
arch/arm/include/asm/atomic.h | 15 +-
arch/arm/include/asm/sync_bitops.h | 29 +-
arch/arm/lib/bitops.h | 14 +-
arch/arm/lib/testchangebit.S | 4 +
arch/arm/lib/testclearbit.S | 4 +
arch/arm/lib/testsetbit.S | 4 +
arch/arm64/include/asm/atomic.h | 28 -
arch/csky/include/asm/atomic.h | 35 -
arch/hexagon/include/asm/atomic.h | 69 +-
arch/ia64/include/asm/atomic.h | 7 -
arch/loongarch/include/asm/atomic.h | 56 -
arch/m68k/include/asm/atomic.h | 18 +-
arch/mips/include/asm/atomic.h | 11 -
arch/openrisc/include/asm/atomic.h | 3 -
arch/parisc/include/asm/atomic.h | 27 +-
arch/powerpc/include/asm/atomic.h | 24 -
arch/powerpc/kernel/smp.c | 12 +-
arch/riscv/include/asm/atomic.h | 72 -
arch/sh/include/asm/atomic-grb.h | 9 +
arch/sh/include/asm/atomic-irq.h | 9 +
arch/sh/include/asm/atomic-llsc.h | 9 +
arch/sh/include/asm/atomic.h | 3 -
arch/sparc/include/asm/atomic_32.h | 18 +-
arch/sparc/include/asm/atomic_64.h | 29 +-
arch/x86/include/asm/atomic.h | 87 -
arch/x86/include/asm/atomic64_32.h | 76 -
arch/x86/include/asm/atomic64_64.h | 81 -
arch/x86/include/asm/cmpxchg_64.h | 4 +
arch/x86/kernel/alternative.c | 4 +-
arch/x86/kernel/cpu/mce/core.c | 16 +-
arch/x86/kernel/nmi.c | 2 +-
arch/x86/kernel/pvclock.c | 4 +-
arch/x86/kvm/x86.c | 2 +-
arch/xtensa/include/asm/atomic.h | 12 +-
include/asm-generic/atomic.h | 3 -
include/asm-generic/bitops/atomic.h | 12 +-
include/asm-generic/bitops/lock.h | 8 +-
include/linux/atomic/atomic-arch-fallback.h | 5200 ++++++++++++------
include/linux/atomic/atomic-instrumented.h | 3484 ++++++++++--
include/linux/atomic/atomic-long.h | 2122 ++++---
include/linux/context_tracking.h | 4 +-
include/linux/context_tracking_state.h | 2 +-
include/linux/cpumask.h | 2 +-
include/linux/jump_label.h | 2 +-
kernel/context_tracking.c | 12 +-
kernel/sched/clock.c | 2 +-
scripts/atomic/atomic-tbl.sh | 112 +-
scripts/atomic/atomics.tbl | 2 +-
scripts/atomic/fallbacks/acquire | 4 -
scripts/atomic/fallbacks/add_negative | 14 +-
scripts/atomic/fallbacks/add_unless | 15 +-
scripts/atomic/fallbacks/andnot | 6 +-
scripts/atomic/fallbacks/cmpxchg | 3 +
scripts/atomic/fallbacks/dec | 6 +-
scripts/atomic/fallbacks/dec_and_test | 14 +-
scripts/atomic/fallbacks/dec_if_positive | 8 +-
scripts/atomic/fallbacks/dec_unless_positive | 8 +-
scripts/atomic/fallbacks/fence | 4 -
scripts/atomic/fallbacks/fetch_add_unless | 17 +-
scripts/atomic/fallbacks/inc | 6 +-
scripts/atomic/fallbacks/inc_and_test | 14 +-
scripts/atomic/fallbacks/inc_not_zero | 13 +-
scripts/atomic/fallbacks/inc_unless_negative | 8 +-
scripts/atomic/fallbacks/read_acquire | 6 +-
scripts/atomic/fallbacks/release | 4 -
scripts/atomic/fallbacks/set_release | 6 +-
scripts/atomic/fallbacks/sub_and_test | 15 +-
scripts/atomic/fallbacks/try_cmpxchg | 6 +-
scripts/atomic/fallbacks/xchg | 3 +
scripts/atomic/gen-atomic-fallback.sh | 264 +-
scripts/atomic/gen-atomic-instrumented.sh | 23 +-
scripts/atomic/gen-atomic-long.sh | 38 +-
scripts/atomic/kerneldoc/add | 13 +
scripts/atomic/kerneldoc/add_negative | 13 +
scripts/atomic/kerneldoc/add_unless | 18 +
scripts/atomic/kerneldoc/and | 13 +
scripts/atomic/kerneldoc/andnot | 13 +
scripts/atomic/kerneldoc/cmpxchg | 14 +
scripts/atomic/kerneldoc/dec | 12 +
scripts/atomic/kerneldoc/dec_and_test | 12 +
scripts/atomic/kerneldoc/dec_if_positive | 12 +
scripts/atomic/kerneldoc/dec_unless_positive | 12 +
scripts/atomic/kerneldoc/inc | 12 +
scripts/atomic/kerneldoc/inc_and_test | 12 +
scripts/atomic/kerneldoc/inc_not_zero | 12 +
scripts/atomic/kerneldoc/inc_unless_negative | 12 +
scripts/atomic/kerneldoc/or | 13 +
scripts/atomic/kerneldoc/read | 12 +
scripts/atomic/kerneldoc/set | 13 +
scripts/atomic/kerneldoc/sub | 13 +
scripts/atomic/kerneldoc/sub_and_test | 13 +
scripts/atomic/kerneldoc/try_cmpxchg | 15 +
scripts/atomic/kerneldoc/xchg | 13 +
scripts/atomic/kerneldoc/xor | 13 +
scripts/kernel-doc | 2 +-
101 files changed, 8979 insertions(+), 3689 deletions(-)
create mode 100755 scripts/atomic/fallbacks/cmpxchg
create mode 100755 scripts/atomic/fallbacks/xchg
create mode 100644 scripts/atomic/kerneldoc/add
create mode 100644 scripts/atomic/kerneldoc/add_negative
create mode 100644 scripts/atomic/kerneldoc/add_unless
create mode 100644 scripts/atomic/kerneldoc/and
create mode 100644 scripts/atomic/kerneldoc/andnot
create mode 100644 scripts/atomic/kerneldoc/cmpxchg
create mode 100644 scripts/atomic/kerneldoc/dec
create mode 100644 scripts/atomic/kerneldoc/dec_and_test
create mode 100644 scripts/atomic/kerneldoc/dec_if_positive
create mode 100644 scripts/atomic/kerneldoc/dec_unless_positive
create mode 100644 scripts/atomic/kerneldoc/inc
create mode 100644 scripts/atomic/kerneldoc/inc_and_test
create mode 100644 scripts/atomic/kerneldoc/inc_not_zero
create mode 100644 scripts/atomic/kerneldoc/inc_unless_negative
create mode 100644 scripts/atomic/kerneldoc/or
create mode 100644 scripts/atomic/kerneldoc/read
create mode 100644 scripts/atomic/kerneldoc/set
create mode 100644 scripts/atomic/kerneldoc/sub
create mode 100644 scripts/atomic/kerneldoc/sub_and_test
create mode 100644 scripts/atomic/kerneldoc/try_cmpxchg
create mode 100644 scripts/atomic/kerneldoc/xchg
create mode 100644 scripts/atomic/kerneldoc/xor

--
2.30.2