| .. SPDX-License-Identifier: GPL-2.0 | |
| ========== | |
| spu_create | |
| ========== | |
| Name | |
| ==== | |
| spu_create - create a new spu context | |
| Synopsis | |
| ======== | |
| :: | |
| #include <sys/types.h> | |
| #include <sys/spu.h> | |
| int spu_create(const char *pathname, int flags, mode_t mode); | |
| Description | |
| =========== | |
| The 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 | |
| pathname and returns a handle to associated with it. pathname must | |
| point to a non-existing directory in the mount point of the SPU file | |
| system (spufs). When spu_create is successful, a directory gets cre- | |
| ated on pathname and it is populated with files. | |
| The returned file handle can only be passed to spu_run(2) or closed, | |
| other operations are not defined on it. When it is closed, all associ- | |
| ated directory entries in spufs are removed. When the last file handle | |
| pointing either inside of the context directory or to this file | |
| descriptor is closed, the logical SPU context is destroyed. | |
| The parameter flags can be zero or any bitwise or'd combination of the | |
| following constants: | |
| SPU_RAWIO | |
| Allow mapping of some of the hardware registers of the SPU into | |
| user space. This flag requires the CAP_SYS_RAWIO capability, see | |
| capabilities(7). | |
| The mode parameter specifies the permissions used for creating the new | |
| directory in spufs. mode is modified with the user's umask(2) value | |
| and then used for both the directory and the files contained in it. The | |
| file permissions mask out some more bits of mode because they typically | |
| support only read or write access. See stat(2) for a full list of the | |
| possible mode values. | |
| Return Value | |
| ============ | |
| spu_create returns a new file descriptor. It may return -1 to indicate | |
| an error condition and set errno to one of the error codes listed | |
| below. | |
| Errors | |
| ====== | |
| EACCES | |
| The current user does not have write access on the spufs mount | |
| point. | |
| EEXIST An SPU context already exists at the given path name. | |
| EFAULT pathname is not a valid string pointer in the current address | |
| space. | |
| EINVAL pathname is not a directory in the spufs mount point. | |
| ELOOP Too many symlinks were found while resolving pathname. | |
| EMFILE The process has reached its maximum open file limit. | |
| ENAMETOOLONG | |
| pathname was too long. | |
| ENFILE The system has reached the global open file limit. | |
| ENOENT Part of pathname could not be resolved. | |
| ENOMEM The kernel could not allocate all resources required. | |
| ENOSPC There are not enough SPU resources available to create a new | |
| context or the user specific limit for the number of SPU con- | |
| texts has been reached. | |
| 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. | |
| ENOTDIR | |
| A part of pathname is not a directory. | |
| Notes | |
| ===== | |
| 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 http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec- | |
| ommended libraries. | |
| Files | |
| ===== | |
| pathname must point to a location beneath the mount point of spufs. By | |
| convention, it gets mounted in /spu. | |
| Conforming to | |
| ============= | |
| This call is Linux specific and only implemented by the ppc64 architec- | |
| ture. Programs using this system call are not portable. | |
| Bugs | |
| ==== | |
| The code does not yet fully implement all features lined out here. | |
| Author | |
| ====== | |
| Arnd Bergmann <arndb@de.ibm.com> | |
| See Also | |
| ======== | |
| capabilities(7), close(2), spu_run(2), spufs(7) |