Re: [PATCH] man2 : syscall.2 : add notes

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

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

On Monday 01 April 2013 03:36:40 Michael Kerrisk (man-pages) wrote:
> +glibc handles the details of copyiing arguments to the right registers

copying

> +the caller may need to handle architecture-dependent details.

may->might

> +For example, on the ARM architecture Embbeded ABI (EABI), a

Embedded

> +.I "long long"
> +argument is considered to be 8-byte aligned and to be split
> +into two 4-byte arguments.

i would rewrite to:
64 bit value (e.g. "long long") must be aligned to an even register pair.

> +.I offset
> +is 64 bit and should be 8-byte aligned.
> +Thus, a padding is inserted before
> +.I offset
> +and
> +.I offset
> +is split into two 32-bit arguments.

i would rewrite to:
Since the offset argument is 64 bits, and the first argument (fd) is passed in 
r0, we need to manually split & align the 64 bit value ourselves so that it is 
passed in the r2/r3 register pair.  That means inserting a dummy value into r1 
(the 2nd argument of 0).

> +Similar issues can occur on MIPS with the O32 ABI and
> +on PowerPC with the 32-bit ABI.
> +.BR fadvise64_64 (2)
> +.BR ftruncate64 (2)
> +.BR pread64 (2)
> +.BR pwrite64 (2)
> +.BR readahead (2)
> +and
> +.BR truncate64 (2).

the style here is messed up.  i'm guessing you meant to make a new paragraph 
starting at "Similar", and you meant to add some text before the function 
list.  also add to the list: sync_file_range and posix_fadvise.

not sure if it's worth mentioning, but this issue ends up forcing MIPS' O32 to 
take 7 arguments to syscall() :).  on ARM/PPC, they avoid this by reordering 
the arguments.

i see that the existing sync_file_range and posix_fadvise pages explicitly call 
out this issue.  i'd suggest updating those (as well as the other funcs that 
are affected) to point back to syscall(2) for more details rather than getting 
into too much detail.

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

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