0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==========
0004 spu_create
0005 ==========
0006
0007 Name
0008 ====
0009 spu_create - create a new spu context
0010
0011
0012 Synopsis
0013 ========
0014
0015 ::
0016
0017 #include <sys/types.h>
0018 #include <sys/spu.h>
0019
0020 int spu_create(const char *pathname, int flags, mode_t mode);
0021
0022 Description
0023 ===========
0024 The spu_create system call is used on PowerPC machines that implement
0025 the Cell Broadband Engine Architecture in order to access Synergistic
0026 Processor Units (SPUs). It creates a new logical context for an SPU in
0027 pathname and returns a handle to associated with it. pathname must
0028 point to a non-existing directory in the mount point of the SPU file
0029 system (spufs). When spu_create is successful, a directory gets cre-
0030 ated on pathname and it is populated with files.
0031
0032 The returned file handle can only be passed to spu_run(2) or closed,
0033 other operations are not defined on it. When it is closed, all associ-
0034 ated directory entries in spufs are removed. When the last file handle
0035 pointing either inside of the context directory or to this file
0036 descriptor is closed, the logical SPU context is destroyed.
0037
0038 The parameter flags can be zero or any bitwise or'd combination of the
0039 following constants:
0040
0041 SPU_RAWIO
0042 Allow mapping of some of the hardware registers of the SPU into
0043 user space. This flag requires the CAP_SYS_RAWIO capability, see
0044 capabilities(7).
0045
0046 The mode parameter specifies the permissions used for creating the new
0047 directory in spufs. mode is modified with the user's umask(2) value
0048 and then used for both the directory and the files contained in it. The
0049 file permissions mask out some more bits of mode because they typically
0050 support only read or write access. See stat(2) for a full list of the
0051 possible mode values.
0052
0053
0054 Return Value
0055 ============
0056 spu_create returns a new file descriptor. It may return -1 to indicate
0057 an error condition and set errno to one of the error codes listed
0058 below.
0059
0060
0061 Errors
0062 ======
0063 EACCES
0064 The current user does not have write access on the spufs mount
0065 point.
0066
0067 EEXIST An SPU context already exists at the given path name.
0068
0069 EFAULT pathname is not a valid string pointer in the current address
0070 space.
0071
0072 EINVAL pathname is not a directory in the spufs mount point.
0073
0074 ELOOP Too many symlinks were found while resolving pathname.
0075
0076 EMFILE The process has reached its maximum open file limit.
0077
0078 ENAMETOOLONG
0079 pathname was too long.
0080
0081 ENFILE The system has reached the global open file limit.
0082
0083 ENOENT Part of pathname could not be resolved.
0084
0085 ENOMEM The kernel could not allocate all resources required.
0086
0087 ENOSPC There are not enough SPU resources available to create a new
0088 context or the user specific limit for the number of SPU con-
0089 texts has been reached.
0090
0091 ENOSYS the functionality is not provided by the current system, because
0092 either the hardware does not provide SPUs or the spufs module is
0093 not loaded.
0094
0095 ENOTDIR
0096 A part of pathname is not a directory.
0097
0098
0099
0100 Notes
0101 =====
0102 spu_create is meant to be used from libraries that implement a more
0103 abstract interface to SPUs, not to be used from regular applications.
0104 See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
0105 ommended libraries.
0106
0107
0108 Files
0109 =====
0110 pathname must point to a location beneath the mount point of spufs. By
0111 convention, it gets mounted in /spu.
0112
0113
0114 Conforming to
0115 =============
0116 This call is Linux specific and only implemented by the ppc64 architec-
0117 ture. Programs using this system call are not portable.
0118
0119
0120 Bugs
0121 ====
0122 The code does not yet fully implement all features lined out here.
0123
0124
0125 Author
0126 ======
0127 Arnd Bergmann <arndb@de.ibm.com>
0128
0129 See Also
0130 ========
0131 capabilities(7), close(2), spu_run(2), spufs(7)
