diff options
Diffstat (limited to 'man/man2/spu_create.2')
| -rw-r--r-- | man/man2/spu_create.2 | 276 |
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 000000000..9f137a047 --- /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 (date) "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) |