2020-11-26 18:39:32

by Alejandro Colomar

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

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 <[email protected]>
---
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.
--
2.29.2

2020-11-27 10:47:16

by Michael Kerrisk (man-pages)

Subject: 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 <[email protected]>
> ---
> 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/

2020-11-27 10:58:08

by Alejandro Colomar

Subject: 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 <[email protected]>
>> ---
>> 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)
>
>