1.. SPDX-License-Identifier: GPL-2.0 2 3========== 4spu_create 5========== 6 7Name 8==== 9 spu_create - create a new spu context 10 11 12Synopsis 13======== 14 15 :: 16 17 #include <sys/types.h> 18 #include <sys/spu.h> 19 20 int spu_create(const char *pathname, int flags, mode_t mode); 21 22Description 23=========== 24 The spu_create system call is used on PowerPC machines that implement 25 the Cell Broadband Engine Architecture in order to access Synergistic 26 Processor Units (SPUs). It creates a new logical context for an SPU in 27 pathname and returns a handle to associated with it. pathname must 28 point to a non-existing directory in the mount point of the SPU file 29 system (spufs). When spu_create is successful, a directory gets cre- 30 ated on pathname and it is populated with files. 31 32 The returned file handle can only be passed to spu_run(2) or closed, 33 other operations are not defined on it. When it is closed, all associ- 34 ated directory entries in spufs are removed. When the last file handle 35 pointing either inside of the context directory or to this file 36 descriptor is closed, the logical SPU context is destroyed. 37 38 The parameter flags can be zero or any bitwise or'd combination of the 39 following constants: 40 41 SPU_RAWIO 42 Allow mapping of some of the hardware registers of the SPU into 43 user space. This flag requires the CAP_SYS_RAWIO capability, see 44 capabilities(7). 45 46 The mode parameter specifies the permissions used for creating the new 47 directory in spufs. mode is modified with the user's umask(2) value 48 and then used for both the directory and the files contained in it. The 49 file permissions mask out some more bits of mode because they typically 50 support only read or write access. See stat(2) for a full list of the 51 possible mode values. 52 53 54Return Value 55============ 56 spu_create returns a new file descriptor. It may return -1 to indicate 57 an error condition and set errno to one of the error codes listed 58 below. 59 60 61Errors 62====== 63 EACCES 64 The current user does not have write access on the spufs mount 65 point. 66 67 EEXIST An SPU context already exists at the given path name. 68 69 EFAULT pathname is not a valid string pointer in the current address 70 space. 71 72 EINVAL pathname is not a directory in the spufs mount point. 73 74 ELOOP Too many symlinks were found while resolving pathname. 75 76 EMFILE The process has reached its maximum open file limit. 77 78 ENAMETOOLONG 79 pathname was too long. 80 81 ENFILE The system has reached the global open file limit. 82 83 ENOENT Part of pathname could not be resolved. 84 85 ENOMEM The kernel could not allocate all resources required. 86 87 ENOSPC There are not enough SPU resources available to create a new 88 context or the user specific limit for the number of SPU con- 89 texts has been reached. 90 91 ENOSYS the functionality is not provided by the current system, because 92 either the hardware does not provide SPUs or the spufs module is 93 not loaded. 94 95 ENOTDIR 96 A part of pathname is not a directory. 97 98 99 100Notes 101===== 102 spu_create is meant to be used from libraries that implement a more 103 abstract interface to SPUs, not to be used from regular applications. 104 See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec- 105 ommended libraries. 106 107 108Files 109===== 110 pathname must point to a location beneath the mount point of spufs. By 111 convention, it gets mounted in /spu. 112 113 114Conforming to 115============= 116 This call is Linux specific and only implemented by the ppc64 architec- 117 ture. Programs using this system call are not portable. 118 119 120Bugs 121==== 122 The code does not yet fully implement all features lined out here. 123 124 125Author 126====== 127 Arnd Bergmann <arndb@de.ibm.com> 128 129See Also 130======== 131 capabilities(7), close(2), spu_run(2), spufs(7) 132