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