summaryrefslogtreecommitdiffstats
path: root/man2/spu_create.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/spu_create.2')
-rw-r--r--man2/spu_create.2276
1 files changed, 0 insertions, 276 deletions
diff --git a/man2/spu_create.2 b/man2/spu_create.2
deleted file mode 100644
index 38efa2c..0000000
--- a/man2/spu_create.2
+++ /dev/null
@@ -1,276 +0,0 @@
-.\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)