.\" Copyright (c) International Business Machines Corp., 2006 .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" HISTORY: .\" 2005-09-28, created by Arnd Bergmann .\" 2006-06-16, revised by Eduardo M. Fleury .\" 2007-07-10, some polishing by mtk .\" 2007-09-28, updates for newer kernels, added example .\" by Jeremy Kerr .\" .TH spu_run 2 2024-05-02 "Linux man-pages 6.8" .SH NAME spu_run \- execute an SPU context .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf .BR "#include " " /* Definition of " SPU_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include .P .BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \ ", uint32_t *" event ); .fi .P .IR Note : glibc provides no wrapper for .BR spu_run (), necessitating the use of .BR syscall (2). .SH DESCRIPTION The .BR spu_run () system call is used on PowerPC machines that implement the Cell Broadband Engine Architecture in order to access Synergistic Processor Units (SPUs). The .I fd argument is a file descriptor returned by .BR spu_create (2) that refers to a specific SPU context. When the context gets scheduled to a physical SPU, it starts execution at the instruction pointer passed in .IR npc . .P Execution of SPU code happens synchronously, meaning that .BR spu_run () blocks while the SPU is still running. If there is a need to execute SPU code in parallel with other code on either the main CPU or other SPUs, a new thread of execution must be created first (e.g., using .BR pthread_create (3)). .P When .BR spu_run () returns, the current value of the SPU program counter is written to .IR npc , so successive calls to .BR spu_run () can use the same .I npc pointer. .P The .I event argument provides a buffer for an extended status code. If the SPU context was created with the .B SPU_CREATE_EVENTS_ENABLED flag, then this buffer is populated by the Linux kernel before .BR spu_run () returns. .P The status code may be one (or more) of the following constants: .TP .B SPE_EVENT_DMA_ALIGNMENT A DMA alignment error occurred. .TP .B SPE_EVENT_INVALID_DMA An invalid MFC DMA command was attempted. .\" SPE_EVENT_SPE_DATA_SEGMENT is defined, but does not seem to be generated .\" at any point (in Linux 5.9 sources). .TP .B SPE_EVENT_SPE_DATA_STORAGE A DMA storage error occurred. .TP .B SPE_EVENT_SPE_ERROR An illegal instruction was executed. .P NULL is a valid value for the .I event argument. In this case, the events will not be reported to the calling process. .SH RETURN VALUE On success, .BR spu_run () returns the value of the .I spu_status register. On failure, it returns \-1 and sets .I errno is set to indicate the error. .P The .I spu_status register value is a bit mask of status codes and optionally a 14-bit code returned from the .B stop-and-signal instruction on the SPU. The bit masks for the status codes are: .TP .B 0x02 SPU was stopped by a .B stop-and-signal instruction. .TP .B 0x04 SPU was stopped by a .B halt instruction. .TP .B 0x08 SPU is waiting for a channel. .TP .B 0x10 SPU is in single-step mode. .TP .B 0x20 SPU has tried to execute an invalid instruction. .TP .B 0x40 SPU has tried to access an invalid channel. .TP .B 0x3fff0000 The bits masked with this value contain the code returned from a .B stop-and-signal instruction. These bits are valid only if the 0x02 bit is set. .P If .BR spu_run () has not returned an error, one or more bits among the lower eight ones are always set. .SH ERRORS .TP .B EBADF .I fd is not a valid file descriptor. .TP .B EFAULT .I npc is not a valid pointer, or .I event is non-NULL and an invalid pointer. .TP .B EINTR A signal occurred while .BR spu_run () was in progress; see .BR signal (7). The .I npc value has been updated to the new program counter value if necessary. .TP .B EINVAL .I fd is not a valid file descriptor returned from .BR spu_create (2). .TP .B ENOMEM There was not enough memory available to handle a page fault resulting from a Memory Flow Controller (MFC) direct memory access. .TP .B ENOSYS The functionality is not provided by the current system, because either the hardware does not provide SPUs or the spufs module is not loaded. .SH STANDARDS Linux on PowerPC. .SH HISTORY Linux 2.6.16. .SH NOTES .BR spu_run () is meant to be used from libraries that implement a more abstract interface to SPUs, not to be used from regular applications. See .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ .UE for the recommended libraries. .SH EXAMPLES The following is an example of running a simple, one-instruction SPU program with the .BR spu_run () system call. .P .\" SRC BEGIN (spu_run.c) .EX #include #include #include #include #include #include #include \& int main(void) { int context, fd, spu_status; uint32_t instruction, npc; \& context = syscall(SYS_spu_create, "/spu/example\-context", 0, 0755); if (context == \-1) err(EXIT_FAILURE, "spu_create"); \& /* * Write a \[aq]stop 0x1234\[aq] instruction to the SPU\[aq]s * local store memory. */ instruction = 0x00001234; \& fd = open("/spu/example\-context/mem", O_RDWR); if (fd == \-1) err(EXIT_FAILURE, "open"); write(fd, &instruction, sizeof(instruction)); \& /* * set npc to the starting instruction address of the * SPU program. Since we wrote the instruction at the * start of the mem file, the entry point will be 0x0. */ npc = 0; \& spu_status = syscall(SYS_spu_run, context, &npc, NULL); if (spu_status == \-1) err(EXIT_FAILURE, "open"); \& /* * We should see a status code of 0x12340002: * 0x00000002 (spu was stopped due to stop\-and\-signal) * | 0x12340000 (the stop\-and\-signal code) */ printf("SPU Status: %#08x\en", spu_status); \& exit(EXIT_SUCCESS); } .EE .\" SRC END .\" .SH AUTHORS .\" Arnd Bergmann , Jeremy Kerr .SH SEE ALSO .BR close (2), .BR spu_create (2), .BR capabilities (7), .BR spufs (7)