Re: [PATCH] man2 : syscall.2 : document syscall calling conventions

[Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>]

[-- Attachment #1: Type: Text/Plain, Size: 3144 bytes --]

On Sunday 07 April 2013 06:00:50 Michael Kerrisk (man-pages) wrote:
> On Wed, Apr 3, 2013 at 1:17 AM, Mike Frysinger wrote:
> > On Tuesday 02 April 2013 02:54:39 Michael Kerrisk (man-pages) wrote:
> >> On Mon, Apr 1, 2013 at 12:32 PM, Mike Frysinger wrote:
> >> > On Monday 01 April 2013 05:29:11 Michael Kerrisk (man-pages) wrote:
> >> >> On Mon, Apr 1, 2013 at 10:29 AM, Mike Frysinger wrote:
> >> >> > on a related topic, would it be useful to document the exact
> >> >> > calling convention for architecture system calls ?  from time to
> >> >> > time, i need to reference this, and i inevitably turn to a variety
> >> >> > of sources to dig up the answer (the kernel itself, or strace, or
> >> >> > qemu, or glibc, or uClibc, or lss, or other random places).  i
> >> >> > would find it handy to have all of these in a single location.
> >> >> 
> >> >> Sounds like it would be useful to have that documented. Would you
> >> >> have a chance to write patches for that?
> >> > 
> >> > should we do it in syscall(2) ?  or a dedicated man page ?
> >> 
> >> It's a little hard to say until I see the shape of what comes. Can you
> >> provide a rough per-syscall example or two of what you expect to
> >> document? (Don't write too concrete a patch yet, until I can get a
> >> handle on what you intend.)
> > 
> > this renders nicely i think.  it shows most of the stuff i'm interested
> > in. might be useful to add a dedicated section covering the clobbers in
> > the future.
> 
> Thanks for that. It looks good to me, and I have applied. But it
> renders too wide (wherever possible, I try to ensure that everything
> renders inside 80 columns), so I have split into tables, one with
> "instruction, NR, ret" and another with the arguments (arg1 to arg7).
> 
> Now, just to make 100% sure of your intention, the NR column would be
> better named "syscall #" (or similar), right? (I've made that change.)

i called it "nr" because that's the common convention (__NR_xxx/etc...) in 
code bases, and because it does a nice job of not pushing the table too wide.

if you've split up the table though, that should no longer be a problem.

> > --- a/man2/syscall.2
> > +++ b/man2/syscall.2
> > @@ -79,6 +79,35 @@ and an error code is stored in
> >  .BR syscall ()
> >  first appeared in
> >  4BSD.
> > +.SS Architecture calling conventions
> > +Every architecture has its own way of invoking & passing arguments to
> > the +kernel.
> > +Note that the instruction listed below might not be the fastest or best
> > way to +transition to the kernel, so you might have to refer to the
> > VDSO.
> 
> Mike, any chance that I could interest you in writing a vdso(7) man
> page? I've felt the lack of such a page for a while (it need not be
> too long), but am not deep enough into the details to write it easily
> (I am not sure if you are).

i might take a stab at it.  it's annoying to constantly have to refer to the 
kernel source when looking something up.

in order to be useful, i think there will have to be arch-specific sections 
which document the funcs each port provides.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]