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