Re: [PATCH] spu_create.2: Clarify that one of the prototypes is the current one

[Michael Kerrisk (man-pages)]

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 <alx.manpages@xxxxxxxxx>
> ---
>  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 <sys/types.h>
>  .B #include <sys/spu.h>
>  .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 <sys/types.h>
 .B #include <sys/spu.h>
 .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 Programming Training: http://man7.org/training/