Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 276 insertions, 0 deletions

diff --git a/man/man2/spu_create.2 b/man/man2/spu_create.2
new file mode 100644
index 0000000..d9b6118
--- /dev/null
+++ b/man/man2/spu_create.2
@@ -0,0 +1,276 @@
+.\" Copyright (c) International Business Machines Corp., 2006
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" HISTORY:
+.\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
+.\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
+.\" 2007-07-10, some polishing by mtk
+.\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org>
+.\"
+.TH spu_create 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+spu_create \- create a new spu context
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <sys/spu.h>" "          /* Definition of " SPU_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_spu_create, const char *" pathname \
+", unsigned int " flags ,
+.BI "            mode_t " mode ", int " neighbor_fd );
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR spu_create (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+The
+.BR spu_create ()
+system call is used on PowerPC machines that implement the
+Cell Broadband Engine Architecture in order to access Synergistic
+Processor Units (SPUs).
+It creates a new logical context for an SPU in
+.I pathname
+and returns a file descriptor associated with it.
+.I pathname
+must refer to a nonexistent directory in the mount point of
+the SPU filesystem
+.RB ( spufs ).
+If
+.BR spu_create ()
+is successful, a directory is created at
+.I pathname
+and it is populated with the files described in
+.BR spufs (7).
+.P
+When a context is created,
+the returned file descriptor can only be passed to
+.BR spu_run (2),
+used as the
+.I dirfd
+argument to the
+.B *at
+family of system calls (e.g.,
+.BR openat (2)),
+or closed;
+other operations are not defined.
+A logical SPU
+context is destroyed (along with all files created within the context's
+.I pathname
+directory) once the last reference to the context has gone;
+this usually occurs when the file descriptor returned by
+.BR spu_create ()
+is closed.
+.P
+The
+.I mode
+argument (minus any bits set in the process's
+.BR umask (2))
+specifies the permissions used for creating the new directory in
+.BR spufs .
+See
+.BR stat (2)
+for a full list of the possible
+.I mode
+values.
+.P
+The
+.I neighbor_fd
+is used only when the
+.B SPU_CREATE_AFFINITY_SPU
+flag is specified; see below.
+.P
+The
+.I flags
+argument can be zero or any bitwise OR-ed
+combination of the following constants:
+.TP
+.B SPU_CREATE_EVENTS_ENABLED
+Rather than using signals for reporting DMA errors, use the
+.I event
+argument to
+.BR spu_run (2).
+.TP
+.B SPU_CREATE_GANG
+Create an SPU gang instead of a context.
+(A gang is a group of SPU contexts that are
+functionally related to each other and which share common scheduling
+parameters\[em]priority and policy.
+In the future, gang scheduling may be implemented causing
+the group to be switched in and out as a single unit.)
+.IP
+A new directory will be created at the location specified by the
+.I pathname
+argument.
+This gang may be used to hold other SPU contexts, by providing
+a pathname that is within the gang directory to further calls to
+.BR spu_create ().
+.TP
+.B SPU_CREATE_NOSCHED
+Create a context that is not affected by the SPU scheduler.
+Once the context is run,
+it will not be scheduled out until it is destroyed by
+the creating process.
+.IP
+Because the context cannot be removed from the SPU, some functionality
+is disabled for
+.B SPU_CREATE_NOSCHED
+contexts.
+Only a subset of the files will be
+available in this context directory in
+.BR spufs .
+Additionally,
+.B SPU_CREATE_NOSCHED
+contexts cannot dump a core file when crashing.
+.IP
+Creating
+.B SPU_CREATE_NOSCHED
+contexts requires the
+.B CAP_SYS_NICE
+capability.
+.TP
+.B SPU_CREATE_ISOLATE
+Create an isolated SPU context.
+Isolated contexts are protected from some
+PPE (PowerPC Processing Element)
+operations,
+such as access to the SPU local store and the NPC register.
+.IP
+Creating
+.B SPU_CREATE_ISOLATE
+contexts also requires the
+.B SPU_CREATE_NOSCHED
+flag.
+.TP
+.BR SPU_CREATE_AFFINITY_SPU " (since Linux 2.6.23)"
+.\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c
+Create a context with affinity to another SPU context.
+This affinity information is used within the SPU scheduling algorithm.
+Using this flag requires that a file descriptor referring to
+the other SPU context be passed in the
+.I neighbor_fd
+argument.
+.TP
+.BR SPU_CREATE_AFFINITY_MEM " (since Linux 2.6.23)"
+.\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c
+Create a context with affinity to system memory.
+This affinity information
+is used within the SPU scheduling algorithm.
+.SH RETURN VALUE
+On success,
+.BR spu_create ()
+returns a new file descriptor.
+On failure, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+The current user does not have write access to the
+.BR spufs (7)
+mount point.
+.TP
+.B EEXIST
+An SPU context already exists at the given pathname.
+.TP
+.B EFAULT
+.I pathname
+is not a valid string pointer in the
+calling process's address space.
+.TP
+.B EINVAL
+.I pathname
+is not a directory in the
+.BR spufs (7)
+mount point, or invalid flags have been provided.
+.TP
+.B ELOOP
+Too many symbolic links were found while resolving
+.IR pathname .
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B ENAMETOOLONG
+.I pathname
+is too long.
+.TP
+.B ENFILE
+The system-wide limit on the total number of open files has been reached.
+.TP
+.B ENODEV
+An isolated context was requested, but the hardware does not support
+SPU isolation.
+.TP
+.B ENOENT
+Part of
+.I pathname
+could not be resolved.
+.TP
+.B ENOMEM
+The kernel could not allocate all resources required.
+.TP
+.B ENOSPC
+There are not enough SPU resources available to create
+a new context or the user-specific limit for the number
+of SPU contexts has been reached.
+.TP
+.B ENOSYS
+The functionality is not provided by the current system, because
+either the hardware does not provide SPUs or the spufs module is not
+loaded.
+.TP
+.B ENOTDIR
+A part of
+.I pathname
+is not a directory.
+.TP
+.B EPERM
+The
+.B SPU_CREATE_NOSCHED
+flag has been given, but the user does not have the
+.B CAP_SYS_NICE
+capability.
+.SH FILES
+.I pathname
+must point to a location beneath the mount point of
+.BR spufs .
+By convention, it gets mounted in
+.IR /spu .
+.SH STANDARDS
+Linux on PowerPC.
+.SH HISTORY
+Linux 2.6.16.
+.P
+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 NOTES
+.BR spu_create ()
+is meant to be used from libraries that implement a more abstract
+interface to SPUs, not to be used from regular applications.
+See
+.UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
+.UE
+for the recommended libraries.
+.SH EXAMPLES
+See
+.BR spu_run (2)
+for an example of the use of
+.BR spu_create ()
+.SH SEE ALSO
+.BR close (2),
+.BR spu_run (2),
+.BR capabilities (7),
+.BR spufs (7)