1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun======= 4*4882a593Smuzhiyunspu_run 5*4882a593Smuzhiyun======= 6*4882a593Smuzhiyun 7*4882a593Smuzhiyun 8*4882a593SmuzhiyunName 9*4882a593Smuzhiyun==== 10*4882a593Smuzhiyun spu_run - execute an spu context 11*4882a593Smuzhiyun 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunSynopsis 14*4882a593Smuzhiyun======== 15*4882a593Smuzhiyun 16*4882a593Smuzhiyun :: 17*4882a593Smuzhiyun 18*4882a593Smuzhiyun #include <sys/spu.h> 19*4882a593Smuzhiyun 20*4882a593Smuzhiyun int spu_run(int fd, unsigned int *npc, unsigned int *event); 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunDescription 23*4882a593Smuzhiyun=========== 24*4882a593Smuzhiyun The spu_run system call is used on PowerPC machines that implement the 25*4882a593Smuzhiyun Cell Broadband Engine Architecture in order to access Synergistic Pro- 26*4882a593Smuzhiyun cessor Units (SPUs). It uses the fd that was returned from spu_cre- 27*4882a593Smuzhiyun ate(2) to address a specific SPU context. When the context gets sched- 28*4882a593Smuzhiyun uled to a physical SPU, it starts execution at the instruction pointer 29*4882a593Smuzhiyun passed in npc. 30*4882a593Smuzhiyun 31*4882a593Smuzhiyun Execution of SPU code happens synchronously, meaning that spu_run does 32*4882a593Smuzhiyun not return while the SPU is still running. If there is a need to exe- 33*4882a593Smuzhiyun cute SPU code in parallel with other code on either the main CPU or 34*4882a593Smuzhiyun other SPUs, you need to create a new thread of execution first, e.g. 35*4882a593Smuzhiyun using the pthread_create(3) call. 36*4882a593Smuzhiyun 37*4882a593Smuzhiyun When spu_run returns, the current value of the SPU instruction pointer 38*4882a593Smuzhiyun is written back to npc, so you can call spu_run again without updating 39*4882a593Smuzhiyun the pointers. 40*4882a593Smuzhiyun 41*4882a593Smuzhiyun event can be a NULL pointer or point to an extended status code that 42*4882a593Smuzhiyun gets filled when spu_run returns. It can be one of the following con- 43*4882a593Smuzhiyun stants: 44*4882a593Smuzhiyun 45*4882a593Smuzhiyun SPE_EVENT_DMA_ALIGNMENT 46*4882a593Smuzhiyun A DMA alignment error 47*4882a593Smuzhiyun 48*4882a593Smuzhiyun SPE_EVENT_SPE_DATA_SEGMENT 49*4882a593Smuzhiyun A DMA segmentation error 50*4882a593Smuzhiyun 51*4882a593Smuzhiyun SPE_EVENT_SPE_DATA_STORAGE 52*4882a593Smuzhiyun A DMA storage error 53*4882a593Smuzhiyun 54*4882a593Smuzhiyun If NULL is passed as the event argument, these errors will result in a 55*4882a593Smuzhiyun signal delivered to the calling process. 56*4882a593Smuzhiyun 57*4882a593SmuzhiyunReturn Value 58*4882a593Smuzhiyun============ 59*4882a593Smuzhiyun spu_run returns the value of the spu_status register or -1 to indicate 60*4882a593Smuzhiyun an error and set errno to one of the error codes listed below. The 61*4882a593Smuzhiyun spu_status register value contains a bit mask of status codes and 62*4882a593Smuzhiyun optionally a 14 bit code returned from the stop-and-signal instruction 63*4882a593Smuzhiyun on the SPU. The bit masks for the status codes are: 64*4882a593Smuzhiyun 65*4882a593Smuzhiyun 0x02 66*4882a593Smuzhiyun SPU was stopped by stop-and-signal. 67*4882a593Smuzhiyun 68*4882a593Smuzhiyun 0x04 69*4882a593Smuzhiyun SPU was stopped by halt. 70*4882a593Smuzhiyun 71*4882a593Smuzhiyun 0x08 72*4882a593Smuzhiyun SPU is waiting for a channel. 73*4882a593Smuzhiyun 74*4882a593Smuzhiyun 0x10 75*4882a593Smuzhiyun SPU is in single-step mode. 76*4882a593Smuzhiyun 77*4882a593Smuzhiyun 0x20 78*4882a593Smuzhiyun SPU has tried to execute an invalid instruction. 79*4882a593Smuzhiyun 80*4882a593Smuzhiyun 0x40 81*4882a593Smuzhiyun SPU has tried to access an invalid channel. 82*4882a593Smuzhiyun 83*4882a593Smuzhiyun 0x3fff0000 84*4882a593Smuzhiyun The bits masked with this value contain the code returned from 85*4882a593Smuzhiyun stop-and-signal. 86*4882a593Smuzhiyun 87*4882a593Smuzhiyun There are always one or more of the lower eight bits set or an error 88*4882a593Smuzhiyun code is returned from spu_run. 89*4882a593Smuzhiyun 90*4882a593SmuzhiyunErrors 91*4882a593Smuzhiyun====== 92*4882a593Smuzhiyun EAGAIN or EWOULDBLOCK 93*4882a593Smuzhiyun fd is in non-blocking mode and spu_run would block. 94*4882a593Smuzhiyun 95*4882a593Smuzhiyun EBADF fd is not a valid file descriptor. 96*4882a593Smuzhiyun 97*4882a593Smuzhiyun EFAULT npc is not a valid pointer or status is neither NULL nor a valid 98*4882a593Smuzhiyun pointer. 99*4882a593Smuzhiyun 100*4882a593Smuzhiyun EINTR A signal occurred while spu_run was in progress. The npc value 101*4882a593Smuzhiyun has been updated to the new program counter value if necessary. 102*4882a593Smuzhiyun 103*4882a593Smuzhiyun EINVAL fd is not a file descriptor returned from spu_create(2). 104*4882a593Smuzhiyun 105*4882a593Smuzhiyun ENOMEM Insufficient memory was available to handle a page fault result- 106*4882a593Smuzhiyun ing from an MFC direct memory access. 107*4882a593Smuzhiyun 108*4882a593Smuzhiyun ENOSYS the functionality is not provided by the current system, because 109*4882a593Smuzhiyun either the hardware does not provide SPUs or the spufs module is 110*4882a593Smuzhiyun not loaded. 111*4882a593Smuzhiyun 112*4882a593Smuzhiyun 113*4882a593SmuzhiyunNotes 114*4882a593Smuzhiyun===== 115*4882a593Smuzhiyun spu_run is meant to be used from libraries that implement a more 116*4882a593Smuzhiyun abstract interface to SPUs, not to be used from regular applications. 117*4882a593Smuzhiyun See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec- 118*4882a593Smuzhiyun ommended libraries. 119*4882a593Smuzhiyun 120*4882a593Smuzhiyun 121*4882a593SmuzhiyunConforming to 122*4882a593Smuzhiyun============= 123*4882a593Smuzhiyun This call is Linux specific and only implemented by the ppc64 architec- 124*4882a593Smuzhiyun ture. Programs using this system call are not portable. 125*4882a593Smuzhiyun 126*4882a593Smuzhiyun 127*4882a593SmuzhiyunBugs 128*4882a593Smuzhiyun==== 129*4882a593Smuzhiyun The code does not yet fully implement all features lined out here. 130*4882a593Smuzhiyun 131*4882a593Smuzhiyun 132*4882a593SmuzhiyunAuthor 133*4882a593Smuzhiyun====== 134*4882a593Smuzhiyun Arnd Bergmann <arndb@de.ibm.com> 135*4882a593Smuzhiyun 136*4882a593SmuzhiyunSee Also 137*4882a593Smuzhiyun======== 138*4882a593Smuzhiyun capabilities(7), close(2), spu_create(2), spufs(7) 139