18c2ecf20Sopenharmony_ci.. SPDX-License-Identifier: GPL-2.0 28c2ecf20Sopenharmony_ci 38c2ecf20Sopenharmony_ci======= 48c2ecf20Sopenharmony_cispu_run 58c2ecf20Sopenharmony_ci======= 68c2ecf20Sopenharmony_ci 78c2ecf20Sopenharmony_ci 88c2ecf20Sopenharmony_ciName 98c2ecf20Sopenharmony_ci==== 108c2ecf20Sopenharmony_ci spu_run - execute an spu context 118c2ecf20Sopenharmony_ci 128c2ecf20Sopenharmony_ci 138c2ecf20Sopenharmony_ciSynopsis 148c2ecf20Sopenharmony_ci======== 158c2ecf20Sopenharmony_ci 168c2ecf20Sopenharmony_ci :: 178c2ecf20Sopenharmony_ci 188c2ecf20Sopenharmony_ci #include <sys/spu.h> 198c2ecf20Sopenharmony_ci 208c2ecf20Sopenharmony_ci int spu_run(int fd, unsigned int *npc, unsigned int *event); 218c2ecf20Sopenharmony_ci 228c2ecf20Sopenharmony_ciDescription 238c2ecf20Sopenharmony_ci=========== 248c2ecf20Sopenharmony_ci The spu_run system call is used on PowerPC machines that implement the 258c2ecf20Sopenharmony_ci Cell Broadband Engine Architecture in order to access Synergistic Pro- 268c2ecf20Sopenharmony_ci cessor Units (SPUs). It uses the fd that was returned from spu_cre- 278c2ecf20Sopenharmony_ci ate(2) to address a specific SPU context. When the context gets sched- 288c2ecf20Sopenharmony_ci uled to a physical SPU, it starts execution at the instruction pointer 298c2ecf20Sopenharmony_ci passed in npc. 308c2ecf20Sopenharmony_ci 318c2ecf20Sopenharmony_ci Execution of SPU code happens synchronously, meaning that spu_run does 328c2ecf20Sopenharmony_ci not return while the SPU is still running. If there is a need to exe- 338c2ecf20Sopenharmony_ci cute SPU code in parallel with other code on either the main CPU or 348c2ecf20Sopenharmony_ci other SPUs, you need to create a new thread of execution first, e.g. 358c2ecf20Sopenharmony_ci using the pthread_create(3) call. 368c2ecf20Sopenharmony_ci 378c2ecf20Sopenharmony_ci When spu_run returns, the current value of the SPU instruction pointer 388c2ecf20Sopenharmony_ci is written back to npc, so you can call spu_run again without updating 398c2ecf20Sopenharmony_ci the pointers. 408c2ecf20Sopenharmony_ci 418c2ecf20Sopenharmony_ci event can be a NULL pointer or point to an extended status code that 428c2ecf20Sopenharmony_ci gets filled when spu_run returns. It can be one of the following con- 438c2ecf20Sopenharmony_ci stants: 448c2ecf20Sopenharmony_ci 458c2ecf20Sopenharmony_ci SPE_EVENT_DMA_ALIGNMENT 468c2ecf20Sopenharmony_ci A DMA alignment error 478c2ecf20Sopenharmony_ci 488c2ecf20Sopenharmony_ci SPE_EVENT_SPE_DATA_SEGMENT 498c2ecf20Sopenharmony_ci A DMA segmentation error 508c2ecf20Sopenharmony_ci 518c2ecf20Sopenharmony_ci SPE_EVENT_SPE_DATA_STORAGE 528c2ecf20Sopenharmony_ci A DMA storage error 538c2ecf20Sopenharmony_ci 548c2ecf20Sopenharmony_ci If NULL is passed as the event argument, these errors will result in a 558c2ecf20Sopenharmony_ci signal delivered to the calling process. 568c2ecf20Sopenharmony_ci 578c2ecf20Sopenharmony_ciReturn Value 588c2ecf20Sopenharmony_ci============ 598c2ecf20Sopenharmony_ci spu_run returns the value of the spu_status register or -1 to indicate 608c2ecf20Sopenharmony_ci an error and set errno to one of the error codes listed below. The 618c2ecf20Sopenharmony_ci spu_status register value contains a bit mask of status codes and 628c2ecf20Sopenharmony_ci optionally a 14 bit code returned from the stop-and-signal instruction 638c2ecf20Sopenharmony_ci on the SPU. The bit masks for the status codes are: 648c2ecf20Sopenharmony_ci 658c2ecf20Sopenharmony_ci 0x02 668c2ecf20Sopenharmony_ci SPU was stopped by stop-and-signal. 678c2ecf20Sopenharmony_ci 688c2ecf20Sopenharmony_ci 0x04 698c2ecf20Sopenharmony_ci SPU was stopped by halt. 708c2ecf20Sopenharmony_ci 718c2ecf20Sopenharmony_ci 0x08 728c2ecf20Sopenharmony_ci SPU is waiting for a channel. 738c2ecf20Sopenharmony_ci 748c2ecf20Sopenharmony_ci 0x10 758c2ecf20Sopenharmony_ci SPU is in single-step mode. 768c2ecf20Sopenharmony_ci 778c2ecf20Sopenharmony_ci 0x20 788c2ecf20Sopenharmony_ci SPU has tried to execute an invalid instruction. 798c2ecf20Sopenharmony_ci 808c2ecf20Sopenharmony_ci 0x40 818c2ecf20Sopenharmony_ci SPU has tried to access an invalid channel. 828c2ecf20Sopenharmony_ci 838c2ecf20Sopenharmony_ci 0x3fff0000 848c2ecf20Sopenharmony_ci The bits masked with this value contain the code returned from 858c2ecf20Sopenharmony_ci stop-and-signal. 868c2ecf20Sopenharmony_ci 878c2ecf20Sopenharmony_ci There are always one or more of the lower eight bits set or an error 888c2ecf20Sopenharmony_ci code is returned from spu_run. 898c2ecf20Sopenharmony_ci 908c2ecf20Sopenharmony_ciErrors 918c2ecf20Sopenharmony_ci====== 928c2ecf20Sopenharmony_ci EAGAIN or EWOULDBLOCK 938c2ecf20Sopenharmony_ci fd is in non-blocking mode and spu_run would block. 948c2ecf20Sopenharmony_ci 958c2ecf20Sopenharmony_ci EBADF fd is not a valid file descriptor. 968c2ecf20Sopenharmony_ci 978c2ecf20Sopenharmony_ci EFAULT npc is not a valid pointer or status is neither NULL nor a valid 988c2ecf20Sopenharmony_ci pointer. 998c2ecf20Sopenharmony_ci 1008c2ecf20Sopenharmony_ci EINTR A signal occurred while spu_run was in progress. The npc value 1018c2ecf20Sopenharmony_ci has been updated to the new program counter value if necessary. 1028c2ecf20Sopenharmony_ci 1038c2ecf20Sopenharmony_ci EINVAL fd is not a file descriptor returned from spu_create(2). 1048c2ecf20Sopenharmony_ci 1058c2ecf20Sopenharmony_ci ENOMEM Insufficient memory was available to handle a page fault result- 1068c2ecf20Sopenharmony_ci ing from an MFC direct memory access. 1078c2ecf20Sopenharmony_ci 1088c2ecf20Sopenharmony_ci ENOSYS the functionality is not provided by the current system, because 1098c2ecf20Sopenharmony_ci either the hardware does not provide SPUs or the spufs module is 1108c2ecf20Sopenharmony_ci not loaded. 1118c2ecf20Sopenharmony_ci 1128c2ecf20Sopenharmony_ci 1138c2ecf20Sopenharmony_ciNotes 1148c2ecf20Sopenharmony_ci===== 1158c2ecf20Sopenharmony_ci spu_run is meant to be used from libraries that implement a more 1168c2ecf20Sopenharmony_ci abstract interface to SPUs, not to be used from regular applications. 1178c2ecf20Sopenharmony_ci See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec- 1188c2ecf20Sopenharmony_ci ommended libraries. 1198c2ecf20Sopenharmony_ci 1208c2ecf20Sopenharmony_ci 1218c2ecf20Sopenharmony_ciConforming to 1228c2ecf20Sopenharmony_ci============= 1238c2ecf20Sopenharmony_ci This call is Linux specific and only implemented by the ppc64 architec- 1248c2ecf20Sopenharmony_ci ture. Programs using this system call are not portable. 1258c2ecf20Sopenharmony_ci 1268c2ecf20Sopenharmony_ci 1278c2ecf20Sopenharmony_ciBugs 1288c2ecf20Sopenharmony_ci==== 1298c2ecf20Sopenharmony_ci The code does not yet fully implement all features lined out here. 1308c2ecf20Sopenharmony_ci 1318c2ecf20Sopenharmony_ci 1328c2ecf20Sopenharmony_ciAuthor 1338c2ecf20Sopenharmony_ci====== 1348c2ecf20Sopenharmony_ci Arnd Bergmann <arndb@de.ibm.com> 1358c2ecf20Sopenharmony_ci 1368c2ecf20Sopenharmony_ciSee Also 1378c2ecf20Sopenharmony_ci======== 1388c2ecf20Sopenharmony_ci capabilities(7), close(2), spu_create(2), spufs(7) 139