On Thu, May 11, 2023 at 06:10:00PM +0100, Mark Rutland wrote: > Hi Paul > > On Wed, May 10, 2023 at 11:17:16AM -0700, Paul E. McKenney wrote: > > The gen-atomics.sh script currently generates 42 duplicate definitions: > > > > arch_atomic64_add_negative > > arch_atomic64_add_negative_acquire > > arch_atomic64_add_negative_release > > [...] > > > These duplicates are presumably to handle different architectures > > generating hand-coded definitions for different subsets of the atomic > > operations. > > Yup, for each FULL/ACQUIRE/RELEASE/RELAXED variant of each op, we allow the > archtiecture to choose between: > > * Providing the ordering variant directly > * Providing the FULL ordering variant only > * Providing the RELAXED ordering variant only > * Providing an equivalent op that we can build from > > > However, generating duplicate kernel-doc headers is undesirable. > > Understood -- I hadn't understood that duplication was a problem when this was > originally written. > > The way this is currently done is largely an artifact of our ifdeffery (and the > kerneldoc for fallbacks living inthe fallback templates), and I think we can > fix both of those. > > > Therefore, generate only the first kernel-doc definition in a group > > of duplicates. A comment indicates the name of the function and the > > fallback script that generated it. > > I'm not keen on this approach, especially with the chkdup.sh script -- it feels > like we're working around an underlying structural issue. > > I think that we can restructure the ifdeffery so that each ordering variant > gets its own ifdeffery, and then we could place the kerneldoc immediately above > that, e.g. > > /** > * arch_atomic_inc_return_release() > * > * [ full kerneldoc block here ] > */ > #if defined(arch_atomic_inc_return_release) > /* defined in arch code */ > #elif defined(arch_atomic_inc_return_relaxed) > [ define in terms of arch_atomic_inc_return_relaxed ] > #elif defined(arch_atomic_inc_return) > [ define in terms of arch_atomic_inc_return ] > #else > [ define in terms of arch_atomic_fetch_inc_release ] > #endif > > ... with similar for the mandatory ops that each arch must provide, e.g. > > /** > * arch_atomic_or() > * > * [ full kerneldoc block here ] > */ > /* arch_atomic_or() is mandatory -- architectures must define it! */ > > I had a go at that restructuring today, and while local build testing indicates > I haven't got it quite right, I think it's possible: > > https://git.kernel.org/pub/scm/linux/kernel/git/mark/linux.git/log/?h=atomics/fallback-rework > > Does that sound ok to you? If the end result is simpler scripts, sure. I'm not at all keen to complicate the scripts for something daft like kernel-doc. The last thing we need is documentation style weenies making an unholy mess of things.
