Quick fix for syscall man page

Quick fix for syscall man page

[Florin Blanaru]

http://man7.org/linux/man-pages/man2/syscall.2.html

In the first table, for the riscv Arch/ABI, the instruction should be
ecall instead of scall.

According the official manual, the instruction has been renamed.
https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf

"The SCALL and SBREAK instructions have been renamed to ECALL and
EBREAK, re-spectively. Their encoding and functionality are
unchanged."

Re: Quick fix for syscall man page

[Michael Kerrisk (man-pages)]

[Adding Adam Borowski in CC, since he wrote the riscv text back at the
start of 2018, andand he may have a comment.]

On Thu, 5 Sep 2019 at 18:35, Florin Blanaru <florin.blanaru96@gmail.com> wrote:
>
> http://man7.org/linux/man-pages/man2/syscall.2.html
>
> In the first table, for the riscv Arch/ABI, the instruction should be
> ecall instead of scall.
>
> According the official manual, the instruction has been renamed.
> https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf
>
> "The SCALL and SBREAK instructions have been renamed to ECALL and
> EBREAK, re-spectively. Their encoding and functionality are
> unchanged."

Thanks for all of the details. I've applied the patch below.

Cheers,

Michael

diff --git a/man2/syscall.2 b/man2/syscall.2
index 77e6bccdd..33e5ea655 100644
--- a/man2/syscall.2
+++ b/man2/syscall.2
@@ -196,7 +196,7 @@ mips        syscall v0      v0      v1      a3      1, 6
 nios2  trap    r2      r2      -       r7
 parisc ble 0x100(%sr2, %r0)    r20     r28     -       -
 powerpc        sc      r0      r3      -       r0      1
-riscv  scall   a7      a0      a1      -
+riscv  ecall   a7      a0      a1      -
 s390   svc 0   r1      r2      r3      -       3
 s390x  svc 0   r1      r2      r3      -       3
 superh trap #0x17      r3      r0      r1      -       4, 6

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: Quick fix for syscall man page

[walter harms]

Am 09.09.2019 10:52, schrieb Michael Kerrisk (man-pages):
> [Adding Adam Borowski in CC, since he wrote the riscv text back at the
> start of 2018, andand he may have a comment.]
> 
> On Thu, 5 Sep 2019 at 18:35, Florin Blanaru <florin.blanaru96@gmail.com> wrote:
>>
>> http://man7.org/linux/man-pages/man2/syscall.2.html
>>
>> In the first table, for the riscv Arch/ABI, the instruction should be
>> ecall instead of scall.
>>
>> According the official manual, the instruction has been renamed.
>> https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf
>>
>> "The SCALL and SBREAK instructions have been renamed to ECALL and
>> EBREAK, re-spectively. Their encoding and functionality are
>> unchanged."
> 

Maybe it would be helpful to add a "footnote" that this is a rename only.
Otherwise people may get confused.

jm2c
wh

> Thanks for all of the details. I've applied the patch below.
> 
> Cheers,
> 
> Michael
> 
> diff --git a/man2/syscall.2 b/man2/syscall.2
> index 77e6bccdd..33e5ea655 100644
> --- a/man2/syscall.2
> +++ b/man2/syscall.2
> @@ -196,7 +196,7 @@ mips        syscall v0      v0      v1      a3      1, 6
>  nios2  trap    r2      r2      -       r7
>  parisc ble 0x100(%sr2, %r0)    r20     r28     -       -
>  powerpc        sc      r0      r3      -       r0      1
> -riscv  scall   a7      a0      a1      -
> +riscv  ecall   a7      a0      a1      -
>  s390   svc 0   r1      r2      r3      -       3
>  s390x  svc 0   r1      r2      r3      -       3
>  superh trap #0x17      r3      r0      r1      -       4, 6
> 

Re: Quick fix for syscall man page

[Michael Kerrisk (man-pages)]

Hello Walter,

On Mon, 9 Sep 2019 at 11:08, walter harms <wharms@bfs.de> wrote:
>
>
>
> Am 09.09.2019 10:52, schrieb Michael Kerrisk (man-pages):
> > [Adding Adam Borowski in CC, since he wrote the riscv text back at the
> > start of 2018, andand he may have a comment.]
> >
> > On Thu, 5 Sep 2019 at 18:35, Florin Blanaru <florin.blanaru96@gmail.com> wrote:
> >>
> >> http://man7.org/linux/man-pages/man2/syscall.2.html
> >>
> >> In the first table, for the riscv Arch/ABI, the instruction should be
> >> ecall instead of scall.
> >>
> >> According the official manual, the instruction has been renamed.
> >> https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf
> >>
> >> "The SCALL and SBREAK instructions have been renamed to ECALL and
> >> EBREAK, re-spectively. Their encoding and functionality are
> >> unchanged."
> >
>
> Maybe it would be helpful to add a "footnote" that this is a rename only.
> Otherwise people may get confused.

Yes, perhaps that would be helpful. I updated the patch to be as below.

Thanks!

Michael

diff --git a/man2/syscall.2 b/man2/syscall.2
index 77e6bccdd..53118c297 100644
--- a/man2/syscall.2
+++ b/man2/syscall.2
@@ -196,7 +196,7 @@ mips        syscall v0      v0      v1      a3      1, 6
 nios2  trap    r2      r2      -       r7
 parisc ble 0x100(%sr2, %r0)    r20     r28     -       -
 powerpc        sc      r0      r3      -       r0      1
-riscv  scall   a7      a0      a1      -
+riscv  ecall   a7      a0      a1      -       7
 s390   svc 0   r1      r2      r3      -       3
 s390x  svc 0   r1      r2      r3      -       3
 superh trap #0x17      r3      r0      r1      -       4, 6
@@ -298,6 +298,11 @@ in the system call interface, even if it is
defined in the System V ABI.
 .in
 .ft P
 \}
+.IP [7]
+On riscv, the
+.I ecall
+instruction was formerly named
+.IR scall .
 .PP
 The second table shows the registers used to pass the system call arguments.
 .if t \{\





-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: Quick fix for syscall man page

[Adam Borowski]

On Mon, Sep 09, 2019 at 11:08:34AM +0200, walter harms wrote:
> Am 09.09.2019 10:52, schrieb Michael Kerrisk (man-pages):
> > [Adding Adam Borowski in CC, since he wrote the riscv text back at the
> > start of 2018, andand he may have a comment.]

I don't know RISCV; I needed to learn how to issue syscalls to port
something -- so I've searched for relevant documentation, tested that it
indeed works, then submitted that line to make the man page complete.

> > On Thu, 5 Sep 2019 at 18:35, Florin Blanaru <florin.blanaru96@gmail.com> wrote:
> >> http://man7.org/linux/man-pages/man2/syscall.2.html
> >>
> >> In the first table, for the riscv Arch/ABI, the instruction should be
> >> ecall instead of scall.
> >>
> >> According the official manual, the instruction has been renamed.
> >> https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf

What matters for us, and the vast majority of programmers, is that the
rename predates merging into official releases of binutils.  Thus, there is
no reason to ever use the old name in actual code.

> Maybe it would be helpful to add a "footnote" that this is a rename only.
> Otherwise people may get confused.

I wonder, perhaps just a commit message would be enough?  The alias is
historic only; new documentation is supposed to use the new name.  Man pages
contain a lot of data that has been obsolete for decades -- it might be good
to avoid stuff that became obsolete before the official release.

But it's up to you -- you know better what's your policy about historical
information.

> > --- a/man2/syscall.2
> > +++ b/man2/syscall.2
> > @@ -196,7 +196,7 @@ mips        syscall v0      v0      v1      a3      1, 6
> > -riscv  scall   a7      a0      a1      -
> > +riscv  ecall   a7      a0      a1      -


Meow!
-- 
⢀⣴⠾⠻⢶⣦⠀ We domesticated dogs 36000 years ago; together we chased
⣾⠁⢰⠒⠀⣿⡁ animals, hung out and licked or scratched our private parts.
⢿⡄⠘⠷⠚⠋⠀ Cats domesticated us 9500 years ago, and immediately we got
⠈⠳⣄⠀⠀⠀⠀ agriculture, towns then cities.     -- whitroth on /.

Re: Quick fix for syscall man page

[Michael Kerrisk (man-pages)]

Hello Adam,

Thanks for jumping in.
On 9/9/19 8:27 PM, Adam Borowski wrote:
> On Mon, Sep 09, 2019 at 11:08:34AM +0200, walter harms wrote:
>> Am 09.09.2019 10:52, schrieb Michael Kerrisk (man-pages):
>>> [Adding Adam Borowski in CC, since he wrote the riscv text back at the
>>> start of 2018, andand he may have a comment.]
> 
> I don't know RISCV; I needed to learn how to issue syscalls to port
> something -- so I've searched for relevant documentation, tested that it
> indeed works, then submitted that line to make the man page complete.
> 
>>> On Thu, 5 Sep 2019 at 18:35, Florin Blanaru <florin.blanaru96@gmail.com> wrote:
>>>> http://man7.org/linux/man-pages/man2/syscall.2.html
>>>>
>>>> In the first table, for the riscv Arch/ABI, the instruction should be
>>>> ecall instead of scall.
>>>>
>>>> According the official manual, the instruction has been renamed.
>>>> https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf
> 
> What matters for us, and the vast majority of programmers, is that the
> rename predates merging into official releases of binutils.  Thus, there is
> no reason to ever use the old name in actual code.
> 
>> Maybe it would be helpful to add a "footnote" that this is a rename only.
>> Otherwise people may get confused.
> 
> I wonder, perhaps just a commit message would be enough?  The alias is
> historic only; new documentation is supposed to use the new name.  Man pages
> contain a lot of data that has been obsolete for decades -- it might be good
> to avoid stuff that became obsolete before the official release.
> 
> But it's up to you -- you know better what's your policy about historical
> information.

On reflection, I agree. I'll trim this back to a note in the commit
message only. (Nevertheless, thanks, Walter.)

Cheers,

Michael

>>> --- a/man2/syscall.2
>>> +++ b/man2/syscall.2
>>> @@ -196,7 +196,7 @@ mips        syscall v0      v0      v1      a3      1, 6
>>> -riscv  scall   a7      a0      a1      -
>>> +riscv  ecall   a7      a0      a1      -
> 
> 
> Meow!
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: Quick fix for syscall man page

[walter harms]

Am 10.09.2019 10:26, schrieb Michael Kerrisk (man-pages):
> Hello Adam,
> 
> Thanks for jumping in.
> On 9/9/19 8:27 PM, Adam Borowski wrote:
>> On Mon, Sep 09, 2019 at 11:08:34AM +0200, walter harms wrote:
>>> Am 09.09.2019 10:52, schrieb Michael Kerrisk (man-pages):
>>>> [Adding Adam Borowski in CC, since he wrote the riscv text back at the
>>>> start of 2018, andand he may have a comment.]
>>
>> I don't know RISCV; I needed to learn how to issue syscalls to port
>> something -- so I've searched for relevant documentation, tested that it
>> indeed works, then submitted that line to make the man page complete.
>>
>>>> On Thu, 5 Sep 2019 at 18:35, Florin Blanaru <florin.blanaru96@gmail.com> wrote:
>>>>> http://man7.org/linux/man-pages/man2/syscall.2.html
>>>>>
>>>>> In the first table, for the riscv Arch/ABI, the instruction should be
>>>>> ecall instead of scall.
>>>>>
>>>>> According the official manual, the instruction has been renamed.
>>>>> https://content.riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf
>>
>> What matters for us, and the vast majority of programmers, is that the
>> rename predates merging into official releases of binutils.  Thus, there is
>> no reason to ever use the old name in actual code.
>>
>>> Maybe it would be helpful to add a "footnote" that this is a rename only.
>>> Otherwise people may get confused.
>>
>> I wonder, perhaps just a commit message would be enough?  The alias is
>> historic only; new documentation is supposed to use the new name.  Man pages
>> contain a lot of data that has been obsolete for decades -- it might be good
>> to avoid stuff that became obsolete before the official release.
>>
>> But it's up to you -- you know better what's your policy about historical
>> information.
> 
> On reflection, I agree. I'll trim this back to a note in the commit
> message only. (Nevertheless, thanks, Walter.)
> 

Just my view on this:

most people that work on this level may know about that. NTL they also
tend to stick what worked last time. IMHO is the note important since
this is a naming only, you look at the man page not at the archive when
you are in doubt.

Something like: "In 2017 scall war renamed as ecall" is a harmless note.

note; i am not a risc programmer. it is just a general concern.

re,
 wh

> Cheers,
> 
> Michael
> 
>>>> --- a/man2/syscall.2
>>>> +++ b/man2/syscall.2
>>>> @@ -196,7 +196,7 @@ mips        syscall v0      v0      v1      a3      1, 6
>>>> -riscv  scall   a7      a0      a1      -
>>>> +riscv  ecall   a7      a0      a1      -
>>
>>
>> Meow!
>>
> 
>