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