Re: [PATCH] spu_create.2: Clarify that one of the prototypes is the current one
Hi Michael, On 11/27/20 11:43 AM, Michael Kerrisk (man-pages) wrote: > Hi ALex, > > On 11/26/20 7:32 PM, Alejandro Colomar wrote: >> The current Linux kernel only provides a definition of 'spu_create()'. >> It has 4 parameters, the last being 'int neighbor_fd'. >> >> Before Linux 2.6.23, there was an older prototype, >> which didn't have this last parameter. >> >> Move that old prototype to VERSIONS, >> and keep the current one in SYNOPSIS. >> >> .. >> >> $ grep -rn "SYSCALL_DEFINE.(spu_create" >> arch/powerpc/platforms/cell/spu_syscalls.c:56: >> SYSCALL_DEFINE4(spu_create, const char __user *, name, unsigned int, flags, >> >> $ sed -n 56,/^}/p arch/powerpc/platforms/cell/spu_syscalls.c >> SYSCALL_DEFINE4(spu_create, const char __user *, name, unsigned int, flags, >> umode_t, mode, int, neighbor_fd) >> { >> long ret; >> struct spufs_calls *calls; >> >> calls = spufs_calls_get(); >> if (!calls) >> return -ENOSYS; >> >> if (flags & SPU_CREATE_AFFINITY_SPU) { >> struct fd neighbor = fdget(neighbor_fd); >> ret = -EBADF; >> if (neighbor.file) { >> ret = calls->create_thread(name, flags, mode, >> neighbor.file); >> fdput(neighbor); >> } >> } else >> ret = calls->create_thread(name, flags, mode, NULL); >> >> spufs_calls_put(calls); >> return ret; >> } >> >> $ git blame arch/powerpc/platforms/cell/spu_syscalls.c -L 56,/\)/ >> 1bc94226d5c64 (Al Viro 2011-07-26 16:50:23 -0400 56) >> SYSCALL_DEFINE4(spu_create, const char __user *, name, unsigned int, flags, >> 1bc94226d5c64 (Al Viro 2011-07-26 16:50:23 -0400 57) >>umode_t, mode, int, neighbor_fd) >> >> $ git checkout 1bc94226d5c64~1 >> $ git blame arch/powerpc/platforms/cell/spu_syscalls.c -L /spu_create/,/\)/ >> 67207b9664a8d (Arnd Bergmann 2005-11-15 15:53:48 -0500 68) >> asmlinkage long sys_spu_create(const char __user *name, >> 8e68e2f248332 (Arnd Bergmann 2007-07-20 21:39:47 +0200 69) >> unsigned int flags, mode_t mode, int neighbor_fd) >> >> $ git checkout 8e68e2f248332~1 >> $ git blame arch/powerpc/platforms/cell/spu_syscalls.c -L /spu_create/,/\)/ >> 67207b9664a8d (Arnd Bergmann 2005-11-15 15:53:48 -0500 36) >> asmlinkage long sys_spu_create(const char __user *name, >> 67207b9664a8d (Arnd Bergmann 2005-11-15 15:53:48 -0500 37) >> unsigned int flags, mode_t mode) >> >> $ git describe --contains 8e68e2f248332 >> v2.6.23-rc1~195^2~7 >> >> Signed-off-by: Alejandro Colomar >> --- >> man2/spu_create.2 | 16 +--- >> 1 file changed, 13 insertions(+), 3 deletions(-) >> >> diff --git a/man2/spu_create.2 b/man2/spu_create.2 >> index 4e6f5d730..3eeafee56 100644 >> --- a/man2/spu_create.2 >> +++ b/man2/spu_create.2 >> @@ -30,9 +30,8 @@ spu_create \- create a new spu context >> .B #include >> .B #include >> .PP >> -.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode >> ");" >> -.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode >> "," >> -.BI " int " neighbor_fd ");" >> +.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode , >> +.BI " int " neighbor_fd ); >> .fi >> .PP >> .IR Note : >> @@ -247,6 +246,17 @@ By convention, it gets mounted in >> The >> .BR spu_create () >> system call was added to Linux in kernel 2.6.16. >> +.PP >> +.\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c >> +Before Linux 2.6.23, the prototype for >> +.BR spu_create () >> +was: >> +.PP >> +.in +4n >> +.EX >> +.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode >> ); >> +.EE >> +.in >> .SH CONFORMING TO >> This call is Linux-specific and implemented only on the PowerPC >> architecture. > > Thanks for the detailed research. You're welcome! :) > The page was indeed a bit messy > in explaining some details. I've instead opted for a different change; > see below. Looks good! Cheers, Alex > > Thanks, > > Michael > > diff --git a/man2/spu_create.2 b/man2/spu_create.2 > index 92f5fc304..f09d498ed 100644 > --- a/man2/spu_create.2 > +++ b/man2/spu_create.2 > @@ -30,7 +30,6 @@ spu_create \- create a new spu context > .B #include > .B #include > .PP > -.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode > ");" > .BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode > "," > .BI " int " neighbor_fd ");" > .fi > @@ -89,6 +88,12 @@ for a full list of the possible > values. > .PP > The > +.I neighbor_fd > +is used only when the > +.B SPU_CREATE_AFFINITY_SPU > +flag is specified; see below. > +.PP > +The > .I flags > argument can be zero or any bitwise OR-ed > combination of the following constants: > @@ -264,6 +269,14 @@ See > .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ > .UE > for the recommended libraries. > +.PP > +Prior to the addition of the > +.B
Re: [PATCH] spu_create.2: Clarify that one of the prototypes is the current one
Hi ALex, On 11/26/20 7:32 PM, Alejandro Colomar wrote: > The current Linux kernel only provides a definition of 'spu_create()'. > It has 4 parameters, the last being 'int neighbor_fd'. > > Before Linux 2.6.23, there was an older prototype, > which didn't have this last parameter. > > Move that old prototype to VERSIONS, > and keep the current one in SYNOPSIS. > > .. > > $ grep -rn "SYSCALL_DEFINE.(spu_create" > arch/powerpc/platforms/cell/spu_syscalls.c:56: > SYSCALL_DEFINE4(spu_create, const char __user *, name, unsigned int, flags, > > $ sed -n 56,/^}/p arch/powerpc/platforms/cell/spu_syscalls.c > SYSCALL_DEFINE4(spu_create, const char __user *, name, unsigned int, flags, > umode_t, mode, int, neighbor_fd) > { > long ret; > struct spufs_calls *calls; > > calls = spufs_calls_get(); > if (!calls) > return -ENOSYS; > > if (flags & SPU_CREATE_AFFINITY_SPU) { > struct fd neighbor = fdget(neighbor_fd); > ret = -EBADF; > if (neighbor.file) { > ret = calls->create_thread(name, flags, mode, > neighbor.file); > fdput(neighbor); > } > } else > ret = calls->create_thread(name, flags, mode, NULL); > > spufs_calls_put(calls); > return ret; > } > > $ git blame arch/powerpc/platforms/cell/spu_syscalls.c -L 56,/\)/ > 1bc94226d5c64 (Al Viro 2011-07-26 16:50:23 -0400 56) > SYSCALL_DEFINE4(spu_create, const char __user *, name, unsigned int, flags, > 1bc94226d5c64 (Al Viro 2011-07-26 16:50:23 -0400 57) >umode_t, mode, int, neighbor_fd) > > $ git checkout 1bc94226d5c64~1 > $ git blame arch/powerpc/platforms/cell/spu_syscalls.c -L /spu_create/,/\)/ > 67207b9664a8d (Arnd Bergmann 2005-11-15 15:53:48 -0500 68) > asmlinkage long sys_spu_create(const char __user *name, > 8e68e2f248332 (Arnd Bergmann 2007-07-20 21:39:47 +0200 69) > unsigned int flags, mode_t mode, int neighbor_fd) > > $ git checkout 8e68e2f248332~1 > $ git blame arch/powerpc/platforms/cell/spu_syscalls.c -L /spu_create/,/\)/ > 67207b9664a8d (Arnd Bergmann 2005-11-15 15:53:48 -0500 36) > asmlinkage long sys_spu_create(const char __user *name, > 67207b9664a8d (Arnd Bergmann 2005-11-15 15:53:48 -0500 37) > unsigned int flags, mode_t mode) > > $ git describe --contains 8e68e2f248332 > v2.6.23-rc1~195^2~7 > > Signed-off-by: Alejandro Colomar > --- > man2/spu_create.2 | 16 +--- > 1 file changed, 13 insertions(+), 3 deletions(-) > > diff --git a/man2/spu_create.2 b/man2/spu_create.2 > index 4e6f5d730..3eeafee56 100644 > --- a/man2/spu_create.2 > +++ b/man2/spu_create.2 > @@ -30,9 +30,8 @@ spu_create \- create a new spu context > .B #include > .B #include > .PP > -.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode > ");" > -.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode > "," > -.BI " int " neighbor_fd ");" > +.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode , > +.BI " int " neighbor_fd ); > .fi > .PP > .IR Note : > @@ -247,6 +246,17 @@ By convention, it gets mounted in > The > .BR spu_create () > system call was added to Linux in kernel 2.6.16. > +.PP > +.\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c > +Before Linux 2.6.23, the prototype for > +.BR spu_create () > +was: > +.PP > +.in +4n > +.EX > +.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode ); > +.EE > +.in > .SH CONFORMING TO > This call is Linux-specific and implemented only on the PowerPC > architecture. Thanks for the detailed research. The page was indeed a bit messy in explaining some details. I've instead opted for a different change; see below. Thanks, Michael diff --git a/man2/spu_create.2 b/man2/spu_create.2 index 92f5fc304..f09d498ed 100644 --- a/man2/spu_create.2 +++ b/man2/spu_create.2 @@ -30,7 +30,6 @@ spu_create \- create a new spu context .B #include .B #include .PP -.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode ");" .BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode "," .BI " int " neighbor_fd ");" .fi @@ -89,6 +88,12 @@ for a full list of the possible values. .PP The +.I neighbor_fd +is used only when the +.B SPU_CREATE_AFFINITY_SPU +flag is specified; see below. +.PP +The .I flags argument can be zero or any bitwise OR-ed combination of the following constants: @@ -264,6 +269,14 @@ See .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ .UE for the recommended libraries. +.PP +Prior to the addition of the +.B SPU_CREATE_AFFINITY_SPU +flag in Linux 2.6.23, the +.BR spu_create () +system call took only three arguments (i.e., there was no +.I neighbor_fd +argument). .SH EXAMPLES See .BR spu_run (2) -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System