On Tue, May 05, 2020 at 12:05:19PM +0100, Dave Martin wrote: > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote: > > 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. > > Heh, perhaps we could build that into the kernel and mount it somewhere. Argh, don't joke too loudly about things like that! > Seriously though, > > I guess I can start off with straightforward small things for which the > documentation has an obvious home (like prctls[*]) and then move on to > the bigger stuff like ptrace. > > If people start shouting about a page getting too big or messy I can try > to split it up. > > Make sense? Sure, works for me. Will
