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

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

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

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.
-mike

--- 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.
+Also note that this doesn't cover the entire calling convention -- some
+architectures may indiscriminately clobber other registers not listed here.
+.if t \{\
+.ft CW
+\}
+.TS
+l l l l l l l l l l l.
+arch/ABI	insn	NR	ret	arg1	arg2	arg3	arg4	arg5	arg6	arg7
+_
+arm/OABI	swi NR;	-	a1	a1	a2	a3	a4	v1	v2	v3
+arm/EABI	swi 0x0;	r7	r1	r1	r2	r3	r4	r5	r6	r7
+bfin	excpt 0x0;	P0	R0	R0	R1	R2	R3	R4	R5	-
+i386	int $0x80;	eax	eax	ebx	ecx	edx	esi	edi	ebp	-
+ia64	break 0x100000;	r15	r10/r8	r11	r9	r10	r14	r15	r13	-
+.\" not sure about insn or NR
+.\" parisc	ble 0x100(%%sr2, %%r0);	-	r28	r26	r25	r24	r23	r22	r21	-
+sparc/32	t 0x10;	g1	o0	o0	o1	o2	o3	o4	o5	-
+sparc/64	t 0x6d;	g1	o0	o0	o1	o2	o3	o4	o5	-
+x86_64	syscall;	rax	rax	rdi	rsi	rdx	r10	r8	r9	-
+.TE
+.if t \{\
+.in
+.ft P
+\}
 .SS Architecture-specific requirements
 Each architecture ABI has its own requirements on how
 system call arguments are passed to the kernel.

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