From: Russell King - ARM Linux admin <linux@armlinux.org.uk>
To: Will Deacon <will@kernel.org>
Cc: Dave Martin <Dave.Martin@arm.com>,
linux-arch@vger.kernel.org, linux-man@vger.kernel.org,
Catalin Marinas <catalin.marinas@arm.com>,
Michael Kerrisk <mtk.manpages@gmail.com>,
Vincenzo Frascino <vincenzo.frascino@arm.com>,
linux-arm-kernel@lists.infradead.org
Subject: Re: RFC: Adding arch-specific user ABI documentation in linux-man
Date: Tue, 5 May 2020 14:16:19 +0100 [thread overview]
Message-ID: <20200505131619.GG1551@shell.armlinux.org.uk> (raw)
In-Reply-To: <20200505130629.GK19710@willie-the-truck>
On Tue, May 05, 2020 at 02:06:30PM +0100, Will Deacon wrote:
> On Tue, May 05, 2020 at 01:43:51PM +0100, Russell King - ARM Linux admin wrote:
> > On Tue, May 05, 2020 at 11:44:55AM +0100, Will Deacon wrote:
> > > 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.
> >
> > Stuffing random things into the kernel tree is painful for some people.
> >
> > For example, if you cross-build your kernel, then the stuff in the
> > tools/ subdirectory is totally useless (I think everything except
> > perf) because you can't build it.
> >
> > Let's stop making the mistake of constantly shoving stuff into the
> > kernel source tree.
>
> For userspace tools, I'm inclined to agree, but this is just documentation
> so it shouldn't cause any issues with cross building. But to be clear: I'd
> still prefer it to be part of the man-pages project, and would only consider
> it for inclusion in the kernel tree if it was rejected for being too
> CPU-specific.
I don't think that should be a concern; the man-pages project already
contains documentation that is specific to kernel versions, including
documentation for interfaces that are architecture specific (such as
prctl is a big one, ptrace to a lesser extent.) syscall(2) contains
a whole bunch of architecture stuff about the calling convention for
syscalls.
Interestingly, I notice that syscall(2) is wrong for arm/OABI. I am
not surprised, because that documentation never came my way, and I am
the author of the kernel's OABI syscall interface.
It claims:
arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 Notes
──────────────────────────────────────────────────────────────
arm/OABI a1 a2 a3 a4 v1 v2 v3
whereas, at the time I invented it, I decided that it shall pass
arguments in r0 to r6. That's r0 to r6. Not the APCS register
names that this document claims. Not everything in OABI is APCS,
as illustrated here - APCS passes the first four arguments in a1
to a4, and then the rest on the stack. The OABI syscall interface
doesn't do that.
I guess that's what happens when someone else writes interface
documentation and doesn't bother to get it reviewed by those who
created the interface in the first place.
--
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up
next prev parent reply other threads:[~2020-05-05 13:16 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
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 [this message]
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=20200505131619.GG1551@shell.armlinux.org.uk \
--to=linux@armlinux.org.uk \
--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 \
--cc=will@kernel.org \
/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).