* Quick fix for syscall man page @ 2019-09-05 16:34 Florin Blanaru 2019-09-09 8:52 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 7+ messages in thread From: Florin Blanaru @ 2019-09-05 16:34 UTC (permalink / raw) To: mtk.manpages; +Cc: linux-man 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." ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Quick fix for syscall man page 2019-09-05 16:34 Quick fix for syscall man page Florin Blanaru @ 2019-09-09 8:52 ` Michael Kerrisk (man-pages) 2019-09-09 9:08 ` walter harms 0 siblings, 1 reply; 7+ messages in thread From: Michael Kerrisk (man-pages) @ 2019-09-09 8:52 UTC (permalink / raw) To: Florin Blanaru; +Cc: linux-man, Adam Borowski [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/ ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: Quick fix for syscall man page 2019-09-09 8:52 ` Michael Kerrisk (man-pages) @ 2019-09-09 9:08 ` walter harms 2019-09-09 12:42 ` Michael Kerrisk (man-pages) 2019-09-09 18:27 ` Adam Borowski 0 siblings, 2 replies; 7+ messages in thread From: walter harms @ 2019-09-09 9:08 UTC (permalink / raw) To: mtk.manpages; +Cc: Florin Blanaru, linux-man, Adam Borowski 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 > ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Quick fix for syscall man page 2019-09-09 9:08 ` walter harms @ 2019-09-09 12:42 ` Michael Kerrisk (man-pages) 2019-09-09 18:27 ` Adam Borowski 1 sibling, 0 replies; 7+ messages in thread From: Michael Kerrisk (man-pages) @ 2019-09-09 12:42 UTC (permalink / raw) To: Walter Harms; +Cc: Florin Blanaru, linux-man, Adam Borowski 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/ ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: Quick fix for syscall man page 2019-09-09 9:08 ` walter harms 2019-09-09 12:42 ` Michael Kerrisk (man-pages) @ 2019-09-09 18:27 ` Adam Borowski 2019-09-10 8:26 ` Michael Kerrisk (man-pages) 1 sibling, 1 reply; 7+ messages in thread From: Adam Borowski @ 2019-09-09 18:27 UTC (permalink / raw) To: walter harms; +Cc: mtk.manpages, Florin Blanaru, linux-man 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 /. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Quick fix for syscall man page 2019-09-09 18:27 ` Adam Borowski @ 2019-09-10 8:26 ` Michael Kerrisk (man-pages) 2019-09-10 10:45 ` walter harms 0 siblings, 1 reply; 7+ messages in thread From: Michael Kerrisk (man-pages) @ 2019-09-10 8:26 UTC (permalink / raw) To: Adam Borowski, walter harms; +Cc: mtk.manpages, Florin Blanaru, linux-man 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/ ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Quick fix for syscall man page 2019-09-10 8:26 ` Michael Kerrisk (man-pages) @ 2019-09-10 10:45 ` walter harms 0 siblings, 0 replies; 7+ messages in thread From: walter harms @ 2019-09-10 10:45 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: Adam Borowski, Florin Blanaru, linux-man 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! >> > > ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2019-09-10 10:46 UTC | newest] Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2019-09-05 16:34 Quick fix for syscall man page Florin Blanaru 2019-09-09 8:52 ` Michael Kerrisk (man-pages) 2019-09-09 9:08 ` walter harms 2019-09-09 12:42 ` Michael Kerrisk (man-pages) 2019-09-09 18:27 ` Adam Borowski 2019-09-10 8:26 ` Michael Kerrisk (man-pages) 2019-09-10 10:45 ` walter harms
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).