Hi Dave, On Mon, May 04, 2020 at 04:32:35PM +0100, Dave Martin wrote: > I considering trying to plug some gaps in the arch-specific ABI > documentation in the linux man-pages, specifically for arm64 (and > possibly arm, where compat means we have some overlap). > > For arm64, there are now significant new extensions (Pointer > authentication, SVE, MTE etc.) Currently there is some user-facing > documentation mixed in with the kernel-facing documentation in the > kernel tree, but this situation isn't ideal. > > Do you have an opinion on where in the man-pages documentation should be > added, and how to structure it? > > > Affected areas include: > > * exec interface > * aux vector, hwcaps > * arch-specific signals > * signal frame > * mmap/mprotect extensions > * prctl calls > * ptrace quirks and extensions > * coredump contents > > > Not everything has an obvious home in an existing page, and adding > specifics for every architecture could make some existing manpages very > unwieldy. > > I think for some arch features, we really need some "overview" pages > too: just documenting the low-level details is of limited value > without some guide as to how to use them together. > > > Does the following sketch look reasonable? > > * man7/arm64.7: new page: overview of arm64-specific ABI extensions > > * man7/sve.7 (or man7/arm64-sve.7 or man7/sve.7arm64): new page: > overview of arm64 SVE ABI > > * man2/arm64-ptrace.2 (or man2/ptrace.2arm64): new page: > arm64 ptrace extensions Michael has been nagging me on and off about that for, what, 10 years now? I would therefore be very much in favour of having our ptrace extensions documented! We could even put this stuff under Documentation/arm64/man/ if it's deemed too CPU-specific for the man-pages project, but my preference would still be for it to be hosted there alongside all the other man pages. Will
