From: Will Deacon <will@kernel.org>
To: Dave Martin <Dave.Martin@arm.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>,
Catalin Marinas <catalin.marinas@arm.com>,
Vincenzo Frascino <vincenzo.frascino@arm.com>,
linux-man@vger.kernel.org, linux-arch@vger.kernel.org,
linux-arm-kernel@lists.infradead.org
Subject: Re: RFC: Adding arch-specific user ABI documentation in linux-man
Date: Tue, 5 May 2020 13:14:28 +0100 [thread overview]
Message-ID: <20200505121428.GJ19710@willie-the-truck> (raw)
In-Reply-To: <20200505110519.GM30377@arm.com>
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
next prev parent reply other threads:[~2020-05-05 12:14 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-04 15:32 RFC: Adding arch-specific user ABI documentation in linux-man Dave Martin
2020-05-05 7:45 ` AW: " Walter Harms
2020-05-05 10:55 ` Dave Martin
2020-05-05 10:44 ` RFC: " Will Deacon
2020-05-05 11:05 ` Dave Martin
2020-05-05 12:14 ` Will Deacon [this message]
2020-05-06 10:47 ` Michael Kerrisk (man-pages)
2020-05-05 12:43 ` Russell King - ARM Linux admin
2020-05-05 13:06 ` Will Deacon
2020-05-05 13:16 ` Russell King - ARM Linux admin
2020-05-06 10:47 ` Michael Kerrisk (man-pages)
2020-05-06 10:47 ` Michael Kerrisk (man-pages)
2020-05-06 10:47 ` Michael Kerrisk (man-pages)
2020-05-06 14:29 ` Dave Martin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200505121428.GJ19710@willie-the-truck \
--to=will@kernel.org \
--cc=Dave.Martin@arm.com \
--cc=catalin.marinas@arm.com \
--cc=linux-arch@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
--cc=vincenzo.frascino@arm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).