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

[Alejandro Colomar (man-pages)]

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 <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.

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 <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)
> 
>