On Thu, May 11, 2023 at 09:38:56PM +0200, Peter Zijlstra wrote: > 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. FWIW, regardless of the comments, I'd like to make this restructuring as it makes it easier to add some more fallback cases, and I find the generated ifdeffery a bit easier to follow when it's a chain of of-elif-elif-else-end rather than a few nested cases. > 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. Sure. I agree we don't want to bend over backwards for it at the cost of maintainability, but I think it can be made pretty simple and self-contained, and hopefully we can prove that with a v2 or v3. ;) If nothing else, handling this centrally means that we'll have *one* set of comments for this rather than a tonne of randomly managed copies in arch code, which seems like a win... Thanks, Mark.
