syscall(2)

syscall(2)

[Victor Khimenko]

syscall(2) example includes the following snippet which explains how to
call readahead on ARM:

       syscall(SYS_readahead, fd, 0,
                   (unsigned int) (offset >> 32),
                   (unsigned int) (offset & 0xFFFFFFFF),
                   count);

But ARM EABI specifies that "A double-word sized type is passed in two
consecutive registers (e.g., r0 and r1, or r2 and r3). The content of
the registers is as if the value had been loaded from memory representation
with a single LDM instruction."

This would imply that arguments are swapped around in the man page, no?

I've tried to experiement and with ftruncate, at least, it works like
this...
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: syscall(2)

[Michael Kerrisk (man-pages)]

[Extending the CC for some other input. Changhee Han added the text
that you are asking about; Mike F has done a lot of other work on the
page. Perhaps they can comment.]

On 5 March 2017 at 09:08, Victor Khimenko <khim-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org> wrote:
> syscall(2) example includes the following snippet which explains how to
> call readahead on ARM:
>
>        syscall(SYS_readahead, fd, 0,
>                    (unsigned int) (offset >> 32),
>                    (unsigned int) (offset & 0xFFFFFFFF),
>                    count);
>
> But ARM EABI specifies that "A double-word sized type is passed in two
> consecutive registers (e.g., r0 and r1, or r2 and r3). The content of
> the registers is as if the value had been loaded from memory representation
> with a single LDM instruction."
>
> This would imply that arguments are swapped around in the man page, no?

So, I'm taking it that you mean the call should look like this:

       syscall(SYS_readahead, fd, 0,
                   (unsigned int) (offset & 0xFFFFFFFF),
                   (unsigned int) (offset >> 32),
                  count);

Is that what you mean?

> I've tried to experiement and with ftruncate, at least, it works like
> this...

Sounds plausible. I'm hoping that Mike or Changhee Han might comment.

Cheers,

Michael

> --
> To unsubscribe from this list: send the line "unsubscribe linux-man" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: syscall(2)

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1639 bytes --]

On 06 Mar 2017 12:01, Michael Kerrisk (man-pages) wrote:
> [Extending the CC for some other input. Changhee Han added the text
> that you are asking about; Mike F has done a lot of other work on the
> page. Perhaps they can comment.]
> 
> On 5 March 2017 at 09:08, Victor Khimenko <khim-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org> wrote:
> > syscall(2) example includes the following snippet which explains how to
> > call readahead on ARM:
> >
> >        syscall(SYS_readahead, fd, 0,
> >                    (unsigned int) (offset >> 32),
> >                    (unsigned int) (offset & 0xFFFFFFFF),
> >                    count);
> >
> > But ARM EABI specifies that "A double-word sized type is passed in two
> > consecutive registers (e.g., r0 and r1, or r2 and r3). The content of
> > the registers is as if the value had been loaded from memory representation
> > with a single LDM instruction."
> >
> > This would imply that arguments are swapped around in the man page, no?
> 
> So, I'm taking it that you mean the call should look like this:
> 
>        syscall(SYS_readahead, fd, 0,
>                    (unsigned int) (offset & 0xFFFFFFFF),
>                    (unsigned int) (offset >> 32),
>                   count);
> 
> Is that what you mean?
> 
> > I've tried to experiement and with ftruncate, at least, it works like
> > this...
> 
> Sounds plausible. I'm hoping that Mike or Changhee Han might comment.

it depends on the endianness.  the man page shows BE, and Victor's
suggestion changes it to LE.  we probably need to explain that and
not just swap the args in the example.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: syscall(2)

[walter harms]

Am 06.03.2017 20:08, schrieb Mike Frysinger:
> On 06 Mar 2017 12:01, Michael Kerrisk (man-pages) wrote:
>> [Extending the CC for some other input. Changhee Han added the text
>> that you are asking about; Mike F has done a lot of other work on the
>> page. Perhaps they can comment.]
>>
>> On 5 March 2017 at 09:08, Victor Khimenko <khim-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org> wrote:
>>> syscall(2) example includes the following snippet which explains how to
>>> call readahead on ARM:
>>>
>>>        syscall(SYS_readahead, fd, 0,
>>>                    (unsigned int) (offset >> 32),
>>>                    (unsigned int) (offset & 0xFFFFFFFF),
>>>                    count);
>>>
>>> But ARM EABI specifies that "A double-word sized type is passed in two
>>> consecutive registers (e.g., r0 and r1, or r2 and r3). The content of
>>> the registers is as if the value had been loaded from memory representation
>>> with a single LDM instruction."
>>>
>>> This would imply that arguments are swapped around in the man page, no?
>>
>> So, I'm taking it that you mean the call should look like this:
>>
>>        syscall(SYS_readahead, fd, 0,
>>                    (unsigned int) (offset & 0xFFFFFFFF),
>>                    (unsigned int) (offset >> 32),
>>                   count);
>>
>> Is that what you mean?
>>
>>> I've tried to experiement and with ftruncate, at least, it works like
>>> this...
>>
>> Sounds plausible. I'm hoping that Mike or Changhee Han might comment.
> 
> it depends on the endianness.  the man page shows BE, and Victor's
> suggestion changes it to LE.  we probably need to explain that and
> not just swap the args in the example.
> -mike


I think that the point is: "invokes the system call whose assembly language interface"

And a lot of new programmes have no experience with assembler these days. So the example
should go into more details an explain how this is mapped into registers.
e.g. ARM/EABI
          syscall(SYS_readahead,                    // r7
		   fd,                              // r0
	            0,                              // r1
                   (unsigned int) (offset >> 32),   // r2
                   (unsigned int) (offset & 0xFFFFFFFF), // r3
                   count);                         //r4

Then the next lines make more sense for the reader:
"       Since  the  offset  argument is 64 bits, and the first argument (fd) is
       passed in r0, the caller must manually split and align the 64-bit value
       so  that it is passed in the r2/r3 register pair.  That means inserting
       a dummy value into r1 (the second argument of 0)."

then adding something like pitfalls:
The programmer needs to be aware of the endianess of is cpu. Big Endian CPU will
need to swap arguments.

@khim-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org
what do you think ?

re,
 wh

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: syscall(2)

[Victor Khimenko]

On Tue, Mar 7, 2017 at 1:05 PM, walter harms <wharms-fPG8STNUNVg@public.gmane.org> wrote:
>
>
> Am 06.03.2017 20:08, schrieb Mike Frysinger:
>> On 06 Mar 2017 12:01, Michael Kerrisk (man-pages) wrote:
>>> [Extending the CC for some other input. Changhee Han added the text
>>> that you are asking about; Mike F has done a lot of other work on the
>>> page. Perhaps they can comment.]
>>>
>>> On 5 March 2017 at 09:08, Victor Khimenko <khim-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org> wrote:
>>>> syscall(2) example includes the following snippet which explains how to
>>>> call readahead on ARM:
>>>>
>>>>        syscall(SYS_readahead, fd, 0,
>>>>                    (unsigned int) (offset >> 32),
>>>>                    (unsigned int) (offset & 0xFFFFFFFF),
>>>>                    count);
>>>>
>>>> But ARM EABI specifies that "A double-word sized type is passed in two
>>>> consecutive registers (e.g., r0 and r1, or r2 and r3). The content of
>>>> the registers is as if the value had been loaded from memory representation
>>>> with a single LDM instruction."
>>>>
>>>> This would imply that arguments are swapped around in the man page, no?
>>>
>>> So, I'm taking it that you mean the call should look like this:
>>>
>>>        syscall(SYS_readahead, fd, 0,
>>>                    (unsigned int) (offset & 0xFFFFFFFF),
>>>                    (unsigned int) (offset >> 32),
>>>                   count);
>>>
>>> Is that what you mean?
>>>
>>>> I've tried to experiement and with ftruncate, at least, it works like
>>>> this...
>>>
>>> Sounds plausible. I'm hoping that Mike or Changhee Han might comment.
>>
>> it depends on the endianness.  the man page shows BE, and Victor's
>> suggestion changes it to LE.  we probably need to explain that and
>> not just swap the args in the example.
>> -mike
>
>
> I think that the point is: "invokes the system call whose assembly language interface"
>
> And a lot of new programmes have no experience with assembler these days. So the example
> should go into more details an explain how this is mapped into registers.
> e.g. ARM/EABI
>           syscall(SYS_readahead,                    // r7
>                    fd,                              // r0
>                     0,                              // r1
>                    (unsigned int) (offset >> 32),   // r2
>                    (unsigned int) (offset & 0xFFFFFFFF), // r3
>                    count);                         //r4
>
> Then the next lines make more sense for the reader:
> "       Since  the  offset  argument is 64 bits, and the first argument (fd) is
>        passed in r0, the caller must manually split and align the 64-bit value
>        so  that it is passed in the r2/r3 register pair.  That means inserting
>        a dummy value into r1 (the second argument of 0)."
>
> then adding something like pitfalls:
> The programmer needs to be aware of the endianess of is cpu. Big Endian CPU will
> need to swap arguments.
>
> @khim-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org
> what do you think ?
>
Well, as long as explanation is correct - I'm happy. Would probably
good idea to convert example to Little Endian and mention that "Big
Endian CPU would swap r2 and r3 arguments".

Nowadays most platforms (including most ARM platforms) are Little
Endian thus it looks a bit weird to have Big Endian ARM as canonical
example!

Heck, preadv/pwritev use low/high even on Big Endian platform!

See https://lwn.net/Articles/311630/

That's how I become involved with all that mess: I've tried to
understand the difference between __llseek, pread64 and preadv
syscalls. __llseek uses "hi, lo" arguments order, preadv uses "lo, hi"
and pread64... that's where I've started trying to decypher syscall(2)
man page...
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: syscall(2)

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 4846 bytes --]

On 07 Mar 2017 22:51, Victor Khimenko wrote:
> On Tue, Mar 7, 2017 at 1:05 PM, walter harms <wharms-fPG8STNUNVg@public.gmane.org> wrote:
> > Am 06.03.2017 20:08, schrieb Mike Frysinger:
> >> On 06 Mar 2017 12:01, Michael Kerrisk (man-pages) wrote:
> >>> [Extending the CC for some other input. Changhee Han added the text
> >>> that you are asking about; Mike F has done a lot of other work on the
> >>> page. Perhaps they can comment.]
> >>>
> >>> On 5 March 2017 at 09:08, Victor Khimenko <khim-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org> wrote:
> >>>> syscall(2) example includes the following snippet which explains how to
> >>>> call readahead on ARM:
> >>>>
> >>>>        syscall(SYS_readahead, fd, 0,
> >>>>                    (unsigned int) (offset >> 32),
> >>>>                    (unsigned int) (offset & 0xFFFFFFFF),
> >>>>                    count);
> >>>>
> >>>> But ARM EABI specifies that "A double-word sized type is passed in two
> >>>> consecutive registers (e.g., r0 and r1, or r2 and r3). The content of
> >>>> the registers is as if the value had been loaded from memory representation
> >>>> with a single LDM instruction."
> >>>>
> >>>> This would imply that arguments are swapped around in the man page, no?
> >>>
> >>> So, I'm taking it that you mean the call should look like this:
> >>>
> >>>        syscall(SYS_readahead, fd, 0,
> >>>                    (unsigned int) (offset & 0xFFFFFFFF),
> >>>                    (unsigned int) (offset >> 32),
> >>>                   count);
> >>>
> >>> Is that what you mean?
> >>>
> >>>> I've tried to experiement and with ftruncate, at least, it works like
> >>>> this...
> >>>
> >>> Sounds plausible. I'm hoping that Mike or Changhee Han might comment.
> >>
> >> it depends on the endianness.  the man page shows BE, and Victor's
> >> suggestion changes it to LE.  we probably need to explain that and
> >> not just swap the args in the example.
> >> -mike
> >
> >
> > I think that the point is: "invokes the system call whose assembly language interface"
> >
> > And a lot of new programmes have no experience with assembler these days. So the example
> > should go into more details an explain how this is mapped into registers.
> > e.g. ARM/EABI
> >           syscall(SYS_readahead,                    // r7
> >                    fd,                              // r0
> >                     0,                              // r1
> >                    (unsigned int) (offset >> 32),   // r2
> >                    (unsigned int) (offset & 0xFFFFFFFF), // r3
> >                    count);                         //r4
> >
> > Then the next lines make more sense for the reader:
> > "       Since  the  offset  argument is 64 bits, and the first argument (fd) is
> >        passed in r0, the caller must manually split and align the 64-bit value
> >        so  that it is passed in the r2/r3 register pair.  That means inserting
> >        a dummy value into r1 (the second argument of 0)."
> >
> > then adding something like pitfalls:
> > The programmer needs to be aware of the endianess of is cpu. Big Endian CPU will
> > need to swap arguments.
> >
> > @khim-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org
> > what do you think ?
> 
> Well, as long as explanation is correct - I'm happy. Would probably
> good idea to convert example to Little Endian and mention that "Big
> Endian CPU would swap r2 and r3 arguments".
> 
> Nowadays most platforms (including most ARM platforms) are Little
> Endian thus it looks a bit weird to have Big Endian ARM as canonical
> example!
> 
> Heck, preadv/pwritev use low/high even on Big Endian platform!
> 
> See https://lwn.net/Articles/311630/
> 
> That's how I become involved with all that mess: I've tried to
> understand the difference between __llseek, pread64 and preadv
> syscalls. __llseek uses "hi, lo" arguments order, preadv uses "lo, hi"
> and pread64... that's where I've started trying to decypher syscall(2)
> man page...

i think your concerns boil down to "the Linux syscall ABI is ugly and
inconsistent".  it is.  some syscalls split 64-bit args naturally, but
some don't.

ARM EABI plumbs the readahead syscall directly to userspace.  that means
the 64-bit value is split according to its low level C ABI.  same for
pread and pread64.  ARM OABI didn't include the padding.

llseek on the other hand takes care of assembling the two 32-bit values
itself in C.

that's why the syscall(2) page contains this caveat:
	However, when using syscall() to make a system call, the caller
	might need to handle architecture-dependent details;
	^^^^^

we can mention the endian issue, but we don't want this page to grow
into details for every syscall.  that's a much larger project that we
discussed at the last LPC.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH] syscall(2): add endian details with 64-bit splitting

[Mike Frysinger]

Architectures that split 64-bit values across registers pairs usually do
so according to their C ABI calling convention (which means endianness).
Add some notes to that effect, and change the readahead example to show
a little endian example (since that is way more common than big endian).

Also start a new list of syscalls that this issue does not apply to.

Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
---
 man2/syscall.2 | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/man2/syscall.2 b/man2/syscall.2
index fcb0a7e21248..80f83fd1aaac 100644
--- a/man2/syscall.2
+++ b/man2/syscall.2
@@ -102,13 +102,14 @@ Thus, using
 instead of the wrapper provided by glibc,
 the
 .BR readahead ()
-system call would be invoked as follows on the ARM architecture with the EABI:
+system call would be invoked as follows on the ARM architecture with the EABI
+in little endian mode:
 
 .in +4n
 .nf
 syscall(SYS_readahead, fd, 0,
-        (unsigned int) (offset >> 32),
         (unsigned int) (offset & 0xFFFFFFFF),
+        (unsigned int) (offset >> 32),
         count);
 .fi
 .in
@@ -124,6 +125,8 @@ register pair.
 That means inserting a dummy value into
 .I r1
 (the second argument of 0).
+Care also must be taken so that the split follows endian conventions
+(according to the C ABI for the platform).
 
 Similar issues can occur on MIPS with the O32 ABI,
 on PowerPC with the 32-bit ABI, and on Xtensa.
@@ -140,6 +143,11 @@ The affected system calls are
 .BR sync_file_range (2),
 and
 .BR truncate64 (2).
+
+This does not affect syscalls that manually split and assemble 64-bit values
+such as
+.BR _llseek (2).
+Welcome to the wonderful world of historical baggage.
 .SS Architecture calling conventions
 Every architecture has its own way of invoking and passing arguments to the
 kernel.
-- 
2.12.0

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] syscall(2): add endian details with 64-bit splitting

[Victor Khimenko]

On Sat, Mar 11, 2017 at 4:16 AM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> Architectures that split 64-bit values across registers pairs usually do
> so according to their C ABI calling convention (which means endianness).
> Add some notes to that effect, and change the readahead example to show
> a little endian example (since that is way more common than big endian).
>
> Also start a new list of syscalls that this issue does not apply to.
>

Maybe add preadv/prwritev to that list?

The whole story which promted me to dig deep into syscall(2) page
started with pread/preadv story (thankfully pwrite acts as pread and
pwritev acts as preadv, no surprises there).

They have the following prototypes:

ssize_t pread(int fd, void *buf, size_t count, off_t offset);
ssize_t preadv(int fd, const struct iovec *iov, int iovcnt, off_t offset);

As you could see they are delightfully similar (interpreteation of
parameters are different, but types are almost the same) but my
attempts to handle them invariably broken one or other.

Eventually I've found article which explained what goes on:
https://lwn.net/Articles/311630/ - apparently preadv was made
different from pread to make life easier (not sure who's life that
made easier, though)!

> Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
> ---
>  man2/syscall.2 | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
>
> diff --git a/man2/syscall.2 b/man2/syscall.2
> index fcb0a7e21248..80f83fd1aaac 100644
> --- a/man2/syscall.2
> +++ b/man2/syscall.2
> @@ -102,13 +102,14 @@ Thus, using
>  instead of the wrapper provided by glibc,
>  the
>  .BR readahead ()
> -system call would be invoked as follows on the ARM architecture with the EABI:
> +system call would be invoked as follows on the ARM architecture with the EABI
> +in little endian mode:
>
>  .in +4n
>  .nf
>  syscall(SYS_readahead, fd, 0,
> -        (unsigned int) (offset >> 32),
>          (unsigned int) (offset & 0xFFFFFFFF),
> +        (unsigned int) (offset >> 32),
>          count);
>  .fi
>  .in
> @@ -124,6 +125,8 @@ register pair.
>  That means inserting a dummy value into
>  .I r1
>  (the second argument of 0).
> +Care also must be taken so that the split follows endian conventions
> +(according to the C ABI for the platform).
>
>  Similar issues can occur on MIPS with the O32 ABI,
>  on PowerPC with the 32-bit ABI, and on Xtensa.
> @@ -140,6 +143,11 @@ The affected system calls are
>  .BR sync_file_range (2),
>  and
>  .BR truncate64 (2).
> +
> +This does not affect syscalls that manually split and assemble 64-bit values
> +such as
> +.BR _llseek (2).
> +Welcome to the wonderful world of historical baggage.
>  .SS Architecture calling conventions
>  Every architecture has its own way of invoking and passing arguments to the
>  kernel.
> --
> 2.12.0
>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2] syscall(2): add endian details with 64-bit splitting

[Mike Frysinger]

Architectures that split 64-bit values across registers pairs usually do
so according to their C ABI calling convention (which means endianness).
Add some notes to that effect, and change the readahead example to show
a little endian example (since that is way more common than big endian).

Also start a new list of syscalls that this issue does not apply to.

Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
---
v2
	- add preadv/prwritev/preadv2/prwritev2 to the new list.

 man2/syscall.2 | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/man2/syscall.2 b/man2/syscall.2
index fcb0a7e21248..f8c89b84356d 100644
--- a/man2/syscall.2
+++ b/man2/syscall.2
@@ -102,13 +102,14 @@ Thus, using
 instead of the wrapper provided by glibc,
 the
 .BR readahead ()
-system call would be invoked as follows on the ARM architecture with the EABI:
+system call would be invoked as follows on the ARM architecture with the EABI
+in little endian mode:
 
 .in +4n
 .nf
 syscall(SYS_readahead, fd, 0,
-        (unsigned int) (offset >> 32),
         (unsigned int) (offset & 0xFFFFFFFF),
+        (unsigned int) (offset >> 32),
         count);
 .fi
 .in
@@ -124,6 +125,8 @@ register pair.
 That means inserting a dummy value into
 .I r1
 (the second argument of 0).
+Care also must be taken so that the split follows endian conventions
+(according to the C ABI for the platform).
 
 Similar issues can occur on MIPS with the O32 ABI,
 on PowerPC with the 32-bit ABI, and on Xtensa.
@@ -140,6 +143,21 @@ The affected system calls are
 .BR sync_file_range (2),
 and
 .BR truncate64 (2).
+
+.\" You need to look up the syscalls directly in the kernel source to see if
+.\" they should be in this list.  For example, look at fs/read_write.c and
+.\" the function signatures that do:
+.\" ..., unsigned long, pos_l, unsigned long, pos_h, ...
+.\" If they use off_t, then they most likely do not belong in this list.
+This does not affect syscalls that manually split and assemble 64-bit values
+such as
+.BR _llseek (2),
+.BR preadv (2),
+.BR preadv2 (2),
+.BR pwritev (2).
+and
+.BR pwritev2 (2).
+Welcome to the wonderful world of historical baggage.
 .SS Architecture calling conventions
 Every architecture has its own way of invoking and passing arguments to the
 kernel.
-- 
2.12.0

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] syscall(2): add endian details with 64-bit splitting

[Victor Khimenko]

On Sat, Mar 11, 2017 at 8:54 PM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> Architectures that split 64-bit values across registers pairs usually do
> so according to their C ABI calling convention (which means endianness).
> Add some notes to that effect, and change the readahead example to show
> a little endian example (since that is way more common than big endian).
>
> Also start a new list of syscalls that this issue does not apply to.
>

Perfect. Thanks. Now it gives all the required pointers for someone to
find out the needed information, Thanks.

> Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
> ---
> v2
>         - add preadv/prwritev/preadv2/prwritev2 to the new list.
>
>  man2/syscall.2 | 22 ++++++++++++++++++++--
>  1 file changed, 20 insertions(+), 2 deletions(-)
>
> diff --git a/man2/syscall.2 b/man2/syscall.2
> index fcb0a7e21248..f8c89b84356d 100644
> --- a/man2/syscall.2
> +++ b/man2/syscall.2
> @@ -102,13 +102,14 @@ Thus, using
>  instead of the wrapper provided by glibc,
>  the
>  .BR readahead ()
> -system call would be invoked as follows on the ARM architecture with the EABI:
> +system call would be invoked as follows on the ARM architecture with the EABI
> +in little endian mode:
>
>  .in +4n
>  .nf
>  syscall(SYS_readahead, fd, 0,
> -        (unsigned int) (offset >> 32),
>          (unsigned int) (offset & 0xFFFFFFFF),
> +        (unsigned int) (offset >> 32),
>          count);
>  .fi
>  .in
> @@ -124,6 +125,8 @@ register pair.
>  That means inserting a dummy value into
>  .I r1
>  (the second argument of 0).
> +Care also must be taken so that the split follows endian conventions
> +(according to the C ABI for the platform).
>
>  Similar issues can occur on MIPS with the O32 ABI,
>  on PowerPC with the 32-bit ABI, and on Xtensa.
> @@ -140,6 +143,21 @@ The affected system calls are
>  .BR sync_file_range (2),
>  and
>  .BR truncate64 (2).
> +
> +.\" You need to look up the syscalls directly in the kernel source to see if
> +.\" they should be in this list.  For example, look at fs/read_write.c and
> +.\" the function signatures that do:
> +.\" ..., unsigned long, pos_l, unsigned long, pos_h, ...
> +.\" If they use off_t, then they most likely do not belong in this list.
> +This does not affect syscalls that manually split and assemble 64-bit values
> +such as
> +.BR _llseek (2),
> +.BR preadv (2),
> +.BR preadv2 (2),
> +.BR pwritev (2).
> +and
> +.BR pwritev2 (2).
> +Welcome to the wonderful world of historical baggage.
>  .SS Architecture calling conventions
>  Every architecture has its own way of invoking and passing arguments to the
>  kernel.
> --
> 2.12.0
>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] syscall(2): add endian details with 64-bit splitting

[Michael Kerrisk (man-pages)]

Hi Mike,

On 03/11/2017 08:54 PM, Mike Frysinger wrote:
> Architectures that split 64-bit values across registers pairs usually do
> so according to their C ABI calling convention (which means endianness).
> Add some notes to that effect, and change the readahead example to show
> a little endian example (since that is way more common than big endian).

Thanks. You're a star. I was going to ask you if you might right a
patch, since I thought you'd do it better than me!

> Also start a new list of syscalls that this issue does not apply to.

And thanks also for adding that.

> Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
> ---
> v2
> 	- add preadv/prwritev/preadv2/prwritev2 to the new list.
> 
>  man2/syscall.2 | 22 ++++++++++++++++++++--
>  1 file changed, 20 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/syscall.2 b/man2/syscall.2
> index fcb0a7e21248..f8c89b84356d 100644
> --- a/man2/syscall.2
> +++ b/man2/syscall.2
> @@ -102,13 +102,14 @@ Thus, using
>  instead of the wrapper provided by glibc,
>  the
>  .BR readahead ()
> -system call would be invoked as follows on the ARM architecture with the EABI:
> +system call would be invoked as follows on the ARM architecture with the EABI
> +in little endian mode:
>  
>  .in +4n
>  .nf
>  syscall(SYS_readahead, fd, 0,
> -        (unsigned int) (offset >> 32),
>          (unsigned int) (offset & 0xFFFFFFFF),
> +        (unsigned int) (offset >> 32),
>          count);
>  .fi
>  .in
> @@ -124,6 +125,8 @@ register pair.
>  That means inserting a dummy value into
>  .I r1
>  (the second argument of 0).
> +Care also must be taken so that the split follows endian conventions
> +(according to the C ABI for the platform).
>  
>  Similar issues can occur on MIPS with the O32 ABI,
>  on PowerPC with the 32-bit ABI, and on Xtensa.
> @@ -140,6 +143,21 @@ The affected system calls are
>  .BR sync_file_range (2),
>  and
>  .BR truncate64 (2).
> +
> +.\" You need to look up the syscalls directly in the kernel source to see if
> +.\" they should be in this list.  For example, look at fs/read_write.c and
> +.\" the function signatures that do:
> +.\" ..., unsigned long, pos_l, unsigned long, pos_h, ...
> +.\" If they use off_t, then they most likely do not belong in this list.

Thanks for adding the above comment in the source. That sort of stuff is
hugely helpful for me when I come to revisit this sometime in the future
when I've already forgotten this discussion.

> +This does not affect syscalls that manually split and assemble 64-bit values
> +such as
> +.BR _llseek (2),
> +.BR preadv (2),
> +.BR preadv2 (2),
> +.BR pwritev (2).
> +and
> +.BR pwritev2 (2).
> +Welcome to the wonderful world of historical baggage.
>  .SS Architecture calling conventions
>  Every architecture has its own way of invoking and passing arguments to the
>  kernel.

Patch applied. Thanks!

Cheers,

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] syscall(2): add endian details with 64-bit splitting

[Michael Kerrisk (man-pages)]

On 03/12/2017 05:31 AM, Victor Khimenko wrote:
> On Sat, Mar 11, 2017 at 8:54 PM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
>> Architectures that split 64-bit values across registers pairs usually do
>> so according to their C ABI calling convention (which means endianness).
>> Add some notes to that effect, and change the readahead example to show
>> a little endian example (since that is way more common than big endian).
>>
>> Also start a new list of syscalls that this issue does not apply to.
>>
> 
> Perfect. Thanks. Now it gives all the required pointers for someone to
> find out the needed information, Thanks.

Thanks, Victor, for your initial report and the input for this patch.

Cheers,

Michael


>> Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
>> ---
>> v2
>>         - add preadv/prwritev/preadv2/prwritev2 to the new list.
>>
>>  man2/syscall.2 | 22 ++++++++++++++++++++--
>>  1 file changed, 20 insertions(+), 2 deletions(-)
>>
>> diff --git a/man2/syscall.2 b/man2/syscall.2
>> index fcb0a7e21248..f8c89b84356d 100644
>> --- a/man2/syscall.2
>> +++ b/man2/syscall.2
>> @@ -102,13 +102,14 @@ Thus, using
>>  instead of the wrapper provided by glibc,
>>  the
>>  .BR readahead ()
>> -system call would be invoked as follows on the ARM architecture with the EABI:
>> +system call would be invoked as follows on the ARM architecture with the EABI
>> +in little endian mode:
>>
>>  .in +4n
>>  .nf
>>  syscall(SYS_readahead, fd, 0,
>> -        (unsigned int) (offset >> 32),
>>          (unsigned int) (offset & 0xFFFFFFFF),
>> +        (unsigned int) (offset >> 32),
>>          count);
>>  .fi
>>  .in
>> @@ -124,6 +125,8 @@ register pair.
>>  That means inserting a dummy value into
>>  .I r1
>>  (the second argument of 0).
>> +Care also must be taken so that the split follows endian conventions
>> +(according to the C ABI for the platform).
>>
>>  Similar issues can occur on MIPS with the O32 ABI,
>>  on PowerPC with the 32-bit ABI, and on Xtensa.
>> @@ -140,6 +143,21 @@ The affected system calls are
>>  .BR sync_file_range (2),
>>  and
>>  .BR truncate64 (2).
>> +
>> +.\" You need to look up the syscalls directly in the kernel source to see if
>> +.\" they should be in this list.  For example, look at fs/read_write.c and
>> +.\" the function signatures that do:
>> +.\" ..., unsigned long, pos_l, unsigned long, pos_h, ...
>> +.\" If they use off_t, then they most likely do not belong in this list.
>> +This does not affect syscalls that manually split and assemble 64-bit values
>> +such as
>> +.BR _llseek (2),
>> +.BR preadv (2),
>> +.BR preadv2 (2),
>> +.BR pwritev (2).
>> +and
>> +.BR pwritev2 (2).
>> +Welcome to the wonderful world of historical baggage.
>>  .SS Architecture calling conventions
>>  Every architecture has its own way of invoking and passing arguments to the
>>  kernel.
>> --
>> 2.12.0
>>
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html