Skip to contentSkip to conversation

spu_create.2: Clarify that one of the prototypes is the current one

PATCH In review Alejandro Colomar 2 participants 3 messages Nov 26, 2020 – Nov 27, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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
---
 man2/spu_create.2 | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)
man2/spu_create.2 +13 -3
index 4e6f5d730..3eeafee56 100644
@@ -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.
Signature · 1 line
2.29.2
#1 lore raw

Hi ALex,

Quoted 92 lines · Alejandro Colomar

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
---
 man2/spu_create.2 | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)
man2/spu_create.2 +6 -3
index 4e6f5d730..3eeafee56 100644
@@ -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 ()

man2/spu_create.2 By convention, it gets mounted in · line 262

Quoted 10 lines
man2/spu_create.2 +7 -0
+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

man2/spu_create.2 +14 -1
index 92f5fc304..f09d498ed 100644
@@ -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)
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#2 lore raw

Hi Michael,

Quoted 99 lines · Michael Kerrisk (man-pages)

Hi ALex,

Quoted 96 lines · Alejandro Colomar

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
---
 man2/spu_create.2 | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)
man2/spu_create.2 +10 -3
index 4e6f5d730..3eeafee56 100644
@@ -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
Quoted 8 lines

man2/spu_create.2 By convention, it gets mounted in · line 262

Quoted 6 lines
man2/spu_create.2 +3 -0
+.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! :)

Quoted 3 lines

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

Quoted 47 lines

Thanks,

Michael

man2/spu_create.2 +14 -1
index 92f5fc304..f09d498ed 100644
@@ -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)