139 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=======4spu_run5=======6 7 8Name9====10 spu_run - execute an spu context11 12 13Synopsis14========15 16 ::17 18 #include <sys/spu.h>19 20 int spu_run(int fd, unsigned int *npc, unsigned int *event);21 22Description23===========24 The spu_run system call is used on PowerPC machines that implement the25 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 pointer29 passed in npc.30 31 Execution of SPU code happens synchronously, meaning that spu_run does32 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 or34 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 pointer38 is written back to npc, so you can call spu_run again without updating39 the pointers.40 41 event can be a NULL pointer or point to an extended status code that42 gets filled when spu_run returns. It can be one of the following con-43 stants:44 45 SPE_EVENT_DMA_ALIGNMENT46 A DMA alignment error47 48 SPE_EVENT_SPE_DATA_SEGMENT49 A DMA segmentation error50 51 SPE_EVENT_SPE_DATA_STORAGE52 A DMA storage error53 54 If NULL is passed as the event argument, these errors will result in a55 signal delivered to the calling process.56 57Return Value58============59 spu_run returns the value of the spu_status register or -1 to indicate60 an error and set errno to one of the error codes listed below. The61 spu_status register value contains a bit mask of status codes and62 optionally a 14 bit code returned from the stop-and-signal instruction63 on the SPU. The bit masks for the status codes are:64 65 0x0266 SPU was stopped by stop-and-signal.67 68 0x0469 SPU was stopped by halt.70 71 0x0872 SPU is waiting for a channel.73 74 0x1075 SPU is in single-step mode.76 77 0x2078 SPU has tried to execute an invalid instruction.79 80 0x4081 SPU has tried to access an invalid channel.82 83 0x3fff000084 The bits masked with this value contain the code returned from85 stop-and-signal.86 87 There are always one or more of the lower eight bits set or an error88 code is returned from spu_run.89 90Errors91======92 EAGAIN or EWOULDBLOCK93 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 valid98 pointer.99 100 EINTR A signal occurred while spu_run was in progress. The npc value101 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, because109 either the hardware does not provide SPUs or the spufs module is110 not loaded.111 112 113Notes114=====115 spu_run is meant to be used from libraries that implement a more116 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 to122=============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 127Bugs128====129 The code does not yet fully implement all features lined out here.130 131 132Author133======134 Arnd Bergmann <arndb@de.ibm.com>135 136See Also137========138 capabilities(7), close(2), spu_create(2), spufs(7)139