HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |NOTES |EXAMPLES |SEE ALSO |COLOPHON | |
spu_run(2) System Calls Manualspu_run(2)spu_run - execute an SPU context
Standard C library (libc,-lc)
#include <sys/spu.h>/* Definition ofSPU_*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>int syscall(SYS_spu_run, intfd, uint32_t *npc, uint32_t *event);Note: glibc provides no wrapper forspu_run(), necessitating the use ofsyscall(2).
Thespu_run() system call is used on PowerPC machines that implement the Cell Broadband Engine Architecture in order to access Synergistic Processor Units (SPUs). Thefd argument is a file descriptor returned byspu_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 innpc. Execution of SPU code happens synchronously, meaning thatspu_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., usingpthread_create(3)). Whenspu_run() returns, the current value of the SPU program counter is written tonpc, so successive calls tospu_run() can use the samenpc pointer. Theevent argument provides a buffer for an extended status code. If the SPU context was created with theSPU_CREATE_EVENTS_ENABLED flag, then this buffer is populated by the Linux kernel beforespu_run() returns. The status code may be one (or more) of the following constants:SPE_EVENT_DMA_ALIGNMENT A DMA alignment error occurred.SPE_EVENT_INVALID_DMA An invalid MFC DMA command was attempted.SPE_EVENT_SPE_DATA_STORAGE A DMA storage error occurred.SPE_EVENT_SPE_ERROR An illegal instruction was executed. NULL is a valid value for theevent argument. In this case, the events will not be reported to the calling process.
On success,spu_run() returns the value of thespu_status register. On failure, it returns -1 and setserrno is set to indicate the error. Thespu_status register value is a bit mask of status codes and optionally a 14-bit code returned from thestop-and-signal instruction on the SPU. The bit masks for the status codes are:0x02SPU was stopped by astop-and-signalinstruction.0x04SPU was stopped by ahaltinstruction.0x08SPU is waiting for a channel.0x10SPU is in single-step mode.0x20SPU has tried to execute an invalid instruction.0x40SPU has tried to access an invalid channel.0x3fff0000 The bits masked with this value contain the code returned from astop-and-signalinstruction. These bits are valid only if the 0x02 bit is set. Ifspu_run() has not returned an error, one or more bits among the lower eight ones are always set.
EBADFfd is not a valid file descriptor.EFAULTnpc is not a valid pointer, orevent is non-NULL and an invalid pointer.EINTRA signal occurred whilespu_run() was in progress; seesignal(7). Thenpc value has been updated to the new program counter value if necessary.EINVALfd is not a valid file descriptor returned fromspu_create(2).ENOMEMThere was not enough memory available to handle a page fault resulting from a Memory Flow Controller (MFC) direct memory access.ENOSYSThe functionality is not provided by the current system, because either the hardware does not provide SPUs or the spufs module is not loaded.
Linux on PowerPC.
Linux 2.6.16.
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 ⟨http://www.bsc.es/projects/deepcomputing/linuxoncell/⟩ for the recommended libraries.
The following is an example of running a simple, one-instruction SPU program with thespu_run() system call. #include <err.h> #include <fcntl.h> #include <stdint.h> #include <stdio.h> #include <stdlib.h> #include <sys/types.h> #include <unistd.h> 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 'stop 0x1234' instruction to the SPU'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\n", spu_status); exit(EXIT_SUCCESS); }close(2),spu_create(2),capabilities(7),spufs(7)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17spu_run(2)Pages that refer to this page:spu_create(2), syscalls(2), spufs(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |