diff options
Diffstat (limited to 'man2/spu_create.2')
| -rw-r--r-- | man2/spu_create.2 | 276 |
1 files changed, 0 insertions, 276 deletions
diff --git a/man2/spu_create.2 b/man2/spu_create.2 deleted file mode 100644 index 9f137a047..000000000 --- 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 (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) |