162306a36Sopenharmony_ci.. SPDX-License-Identifier: GPL-2.0 262306a36Sopenharmony_ci 362306a36Sopenharmony_ci======= 462306a36Sopenharmony_cispu_run 562306a36Sopenharmony_ci======= 662306a36Sopenharmony_ci 762306a36Sopenharmony_ci 862306a36Sopenharmony_ciName 962306a36Sopenharmony_ci==== 1062306a36Sopenharmony_ci spu_run - execute an spu context 1162306a36Sopenharmony_ci 1262306a36Sopenharmony_ci 1362306a36Sopenharmony_ciSynopsis 1462306a36Sopenharmony_ci======== 1562306a36Sopenharmony_ci 1662306a36Sopenharmony_ci :: 1762306a36Sopenharmony_ci 1862306a36Sopenharmony_ci #include <sys/spu.h> 1962306a36Sopenharmony_ci 2062306a36Sopenharmony_ci int spu_run(int fd, unsigned int *npc, unsigned int *event); 2162306a36Sopenharmony_ci 2262306a36Sopenharmony_ciDescription 2362306a36Sopenharmony_ci=========== 2462306a36Sopenharmony_ci The spu_run system call is used on PowerPC machines that implement the 2562306a36Sopenharmony_ci Cell Broadband Engine Architecture in order to access Synergistic Pro- 2662306a36Sopenharmony_ci cessor Units (SPUs). It uses the fd that was returned from spu_cre- 2762306a36Sopenharmony_ci ate(2) to address a specific SPU context. When the context gets sched- 2862306a36Sopenharmony_ci uled to a physical SPU, it starts execution at the instruction pointer 2962306a36Sopenharmony_ci passed in npc. 3062306a36Sopenharmony_ci 3162306a36Sopenharmony_ci Execution of SPU code happens synchronously, meaning that spu_run does 3262306a36Sopenharmony_ci not return while the SPU is still running. If there is a need to exe- 3362306a36Sopenharmony_ci cute SPU code in parallel with other code on either the main CPU or 3462306a36Sopenharmony_ci other SPUs, you need to create a new thread of execution first, e.g. 3562306a36Sopenharmony_ci using the pthread_create(3) call. 3662306a36Sopenharmony_ci 3762306a36Sopenharmony_ci When spu_run returns, the current value of the SPU instruction pointer 3862306a36Sopenharmony_ci is written back to npc, so you can call spu_run again without updating 3962306a36Sopenharmony_ci the pointers. 4062306a36Sopenharmony_ci 4162306a36Sopenharmony_ci event can be a NULL pointer or point to an extended status code that 4262306a36Sopenharmony_ci gets filled when spu_run returns. It can be one of the following con- 4362306a36Sopenharmony_ci stants: 4462306a36Sopenharmony_ci 4562306a36Sopenharmony_ci SPE_EVENT_DMA_ALIGNMENT 4662306a36Sopenharmony_ci A DMA alignment error 4762306a36Sopenharmony_ci 4862306a36Sopenharmony_ci SPE_EVENT_SPE_DATA_SEGMENT 4962306a36Sopenharmony_ci A DMA segmentation error 5062306a36Sopenharmony_ci 5162306a36Sopenharmony_ci SPE_EVENT_SPE_DATA_STORAGE 5262306a36Sopenharmony_ci A DMA storage error 5362306a36Sopenharmony_ci 5462306a36Sopenharmony_ci If NULL is passed as the event argument, these errors will result in a 5562306a36Sopenharmony_ci signal delivered to the calling process. 5662306a36Sopenharmony_ci 5762306a36Sopenharmony_ciReturn Value 5862306a36Sopenharmony_ci============ 5962306a36Sopenharmony_ci spu_run returns the value of the spu_status register or -1 to indicate 6062306a36Sopenharmony_ci an error and set errno to one of the error codes listed below. The 6162306a36Sopenharmony_ci spu_status register value contains a bit mask of status codes and 6262306a36Sopenharmony_ci optionally a 14 bit code returned from the stop-and-signal instruction 6362306a36Sopenharmony_ci on the SPU. The bit masks for the status codes are: 6462306a36Sopenharmony_ci 6562306a36Sopenharmony_ci 0x02 6662306a36Sopenharmony_ci SPU was stopped by stop-and-signal. 6762306a36Sopenharmony_ci 6862306a36Sopenharmony_ci 0x04 6962306a36Sopenharmony_ci SPU was stopped by halt. 7062306a36Sopenharmony_ci 7162306a36Sopenharmony_ci 0x08 7262306a36Sopenharmony_ci SPU is waiting for a channel. 7362306a36Sopenharmony_ci 7462306a36Sopenharmony_ci 0x10 7562306a36Sopenharmony_ci SPU is in single-step mode. 7662306a36Sopenharmony_ci 7762306a36Sopenharmony_ci 0x20 7862306a36Sopenharmony_ci SPU has tried to execute an invalid instruction. 7962306a36Sopenharmony_ci 8062306a36Sopenharmony_ci 0x40 8162306a36Sopenharmony_ci SPU has tried to access an invalid channel. 8262306a36Sopenharmony_ci 8362306a36Sopenharmony_ci 0x3fff0000 8462306a36Sopenharmony_ci The bits masked with this value contain the code returned from 8562306a36Sopenharmony_ci stop-and-signal. 8662306a36Sopenharmony_ci 8762306a36Sopenharmony_ci There are always one or more of the lower eight bits set or an error 8862306a36Sopenharmony_ci code is returned from spu_run. 8962306a36Sopenharmony_ci 9062306a36Sopenharmony_ciErrors 9162306a36Sopenharmony_ci====== 9262306a36Sopenharmony_ci EAGAIN or EWOULDBLOCK 9362306a36Sopenharmony_ci fd is in non-blocking mode and spu_run would block. 9462306a36Sopenharmony_ci 9562306a36Sopenharmony_ci EBADF fd is not a valid file descriptor. 9662306a36Sopenharmony_ci 9762306a36Sopenharmony_ci EFAULT npc is not a valid pointer or status is neither NULL nor a valid 9862306a36Sopenharmony_ci pointer. 9962306a36Sopenharmony_ci 10062306a36Sopenharmony_ci EINTR A signal occurred while spu_run was in progress. The npc value 10162306a36Sopenharmony_ci has been updated to the new program counter value if necessary. 10262306a36Sopenharmony_ci 10362306a36Sopenharmony_ci EINVAL fd is not a file descriptor returned from spu_create(2). 10462306a36Sopenharmony_ci 10562306a36Sopenharmony_ci ENOMEM Insufficient memory was available to handle a page fault result- 10662306a36Sopenharmony_ci ing from an MFC direct memory access. 10762306a36Sopenharmony_ci 10862306a36Sopenharmony_ci ENOSYS the functionality is not provided by the current system, because 10962306a36Sopenharmony_ci either the hardware does not provide SPUs or the spufs module is 11062306a36Sopenharmony_ci not loaded. 11162306a36Sopenharmony_ci 11262306a36Sopenharmony_ci 11362306a36Sopenharmony_ciNotes 11462306a36Sopenharmony_ci===== 11562306a36Sopenharmony_ci spu_run is meant to be used from libraries that implement a more 11662306a36Sopenharmony_ci abstract interface to SPUs, not to be used from regular applications. 11762306a36Sopenharmony_ci See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec- 11862306a36Sopenharmony_ci ommended libraries. 11962306a36Sopenharmony_ci 12062306a36Sopenharmony_ci 12162306a36Sopenharmony_ciConforming to 12262306a36Sopenharmony_ci============= 12362306a36Sopenharmony_ci This call is Linux specific and only implemented by the ppc64 architec- 12462306a36Sopenharmony_ci ture. Programs using this system call are not portable. 12562306a36Sopenharmony_ci 12662306a36Sopenharmony_ci 12762306a36Sopenharmony_ciBugs 12862306a36Sopenharmony_ci==== 12962306a36Sopenharmony_ci The code does not yet fully implement all features lined out here. 13062306a36Sopenharmony_ci 13162306a36Sopenharmony_ci 13262306a36Sopenharmony_ciAuthor 13362306a36Sopenharmony_ci====== 13462306a36Sopenharmony_ci Arnd Bergmann <arndb@de.ibm.com> 13562306a36Sopenharmony_ci 13662306a36Sopenharmony_ciSee Also 13762306a36Sopenharmony_ci======== 13862306a36Sopenharmony_ci capabilities(7), close(2), spu_create(2), spufs(7) 139