Re: RFC: Adding arch-specific user ABI documentation in linux-man

[Will Deacon <will@kernel.org>]

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