spu_run (2) - Linux Man Pages
spu_run: execute an SPU context
spu_run - execute an SPU context
#include <sys/spu.h> int spu_run(int fd, unsigned int *npc, unsigned int *event);
DESCRIPTIONThe 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 fd argument is a file descriptor returned by 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 npc.
Execution of SPU code happens synchronously, meaning that 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 pthread_create(3)).
When spu_run() returns, the current value of the SPU program counter is written to npc, so successive calls to spu_run() can use the same npc pointer.
The event argument provides a buffer for an extended status code. If the SPU context was created with the SPU_CREATE_EVENTS_ENABLED flag, then this buffer is populated by the Linux kernel before spu_run() returns.
The status code may be one (or more) of the following constants:
- A DMA alignment error occurred.
- An invalid MFC DMA command was attempted.
- A DMA storage error occurred.
- An illegal instruction was executed.
RETURN VALUEOn success, spu_run() returns the value of the spu_status register. On error, it returns -1 and sets errno to one of the error codes listed below.
The spu_status register value is a bit mask of status codes and optionally a 14-bit code returned from the stop-and-signal instruction on the SPU. The bit masks for the status codes are:
- SPU was stopped by a stop-and-signal instruction.
- SPU was stopped by a halt instruction.
- SPU is waiting for a channel.
- SPU is in single-step mode.
- SPU has tried to execute an invalid instruction.
- SPU has tried to access an invalid channel.
- The bits masked with this value contain the code returned from a stop-and-signal instruction. These bits are valid only if the 0x02 bit is set.
- fd is not a valid file descriptor.
- npc is not a valid pointer, or event is non-NULL and an invalid pointer.
- A signal occurred while spu_run() was in progress; see signal(7). The npc value has been updated to the new program counter value if necessary.
- fd is not a valid file descriptor returned from spu_create(2).
- There was not enough memory available to handle a page fault resulting from a Memory Flow Controller (MFC) direct memory access.
- The functionality is not provided by the current system, because either the hardware does not provide SPUs or the spufs module is not loaded.
VERSIONSThe spu_run() system call was added to Linux in kernel 2.6.16.
CONFORMING TOThis call is Linux-specific and implemented only by the PowerPC architecture. Programs using this system call are not portable.
NOTESGlibc does not provide a wrapper for this system call; call it using syscall(2). Note however, that 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 for the recommended libraries.
EXAMPLEThe following is an example of running a simple, one-instruction SPU program with the spu_run() system call.
#include <stdlib.h> #include <stdint.h> #include <unistd.h> #include <stdio.h> #include <sys/types.h> #include <fcntl.h>
#define handle_error(msg) \
This page is part of release 5.05 of the Linux
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at