int spu_run(int fd, unsigned int *npc, unsigned int *event);
The 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 con-
text 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
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
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()
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.
NULL is a valid value for the event argument. In this case, the events
will not be reported to the calling process.
On 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
The spu_status register value is a bit mask of status codes and option-
ally a 14-bit code returned from the stop-and-signal instruction on the
SPU. The bit masks for the status codes are:
The bits masked with this value contain the code returned from a
stop-and-signal instruction. These bits are only valid if the
0x02 bit is set.
If spu_run() has not returned an error, one or more bits among the
lower eight ones are always set.
EBADF fd is not a valid file descriptor.
EFAULT npc is not a valid pointer, or event is non-NULL and an invalid
EINTR A signal occurred while spu_run() was in progress; see sig-
nal(7). The npc value has been updated to the new program
counter value if necessary.
EINVAL fd is not a valid file descriptor returned from spu_create(2).
ENOMEM There was not enough memory available to handle a page fault
resulting from a Memory Flow Controller (MFC) direct memory
ENOSYS The functionality is not provided by the current system, because
either the hardware does not provide SPUs or the spufs module is
The spu_run() system call was added to Linux in kernel 2.6.16.
This call is Linux-specific and only implemented by the PowerPC archi-
tecture. Programs using this system call are not portable.
Glibc 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 http://www.bsc.es/projects/deep-
computing/linuxoncell/ for the recommended libraries.
The following is an example of running a simple, one-instruction SPU
program with the spu_run() system call.
/* 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)
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 = spu_run(context, &npc, NULL);
if (spu_status == -1)
/* we should see a status code of 0x1234002:
* 0x00000002 (spu was stopped due to stop-and-signal)
* | 0x12340000 (the stop-and-signal code)
printf("SPU Status: 0x%08x\n", spu_status);
close(2), spu_create(2), capabilities(7), spufs(7)
This page is part of release 3.35 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://man7.org/linux/man-pages/.
Linux 2007-11-25 SPU_RUN(2)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017
All Rights Reserved.