SPU_RUN
Section: Linux Programmer's Manual (2)
Updated: 2007-11-25
NAME
spu_run - execute an SPU context
SYNOPSIS
#include <sys/spu.h>
int spu_run(int fd, unsigned int *npc, unsigned int *event);
DESCRIPTION
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 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:
- 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 the
event
argument.
In this case, the events will not be reported to the calling process.
RETURN VALUE
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 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:
- 0x02
-
SPU was stopped by a
stop-and-signal
instruction.
- 0x04
-
SPU was stopped by a
halt
instruction.
- 0x08
-
SPU is waiting for a channel.
- 0x10
-
SPU is in single-step mode.
- 0x20
-
SPU has tried to execute an invalid instruction.
- 0x40
-
SPU has tried to access an invalid channel.
- 0x3fff0000
-
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.
ERRORS
- EBADF
-
fd
is not a valid file descriptor.
- EFAULT
-
npc
is not a valid pointer, or
event
is non-NULL and an invalid pointer.
- EINTR
-
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.
- 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 access.
- 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.
VERSIONS
The
spu_run()
system call was added to Linux in kernel 2.6.16.
CONFORMING TO
This call is Linux-specific and only implemented by the PowerPC
architecture.
Programs using this system call are not portable.
NOTES
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/deepcomputing/linuxoncell/
for the recommended libraries.
EXAMPLE
The 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) \
do { perror(msg); exit(EXIT_FAILURE); } while (0)
int main(void)
{
int context, fd, spu_status;
uint32_t instruction, npc;
context = spu_create("/spu/example-context", 0, 0755);
if (context == -1)
handle_error("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)
handle_error("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 = spu_run(context, &npc, NULL);
if (spu_status == -1)
handle_error("open");
/* 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);
exit(EXIT_SUCCESS);
}
SEE ALSO
close(2),
spu_create(2),
capabilities(7),
spufs(7)
COLOPHON
This page is part of release 3.27 of the Linux
man-pages
project.
A description of the project,
and information about reporting bugs,
can be found at
http://www.kernel.org/doc/man-pages/.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUE
-
- ERRORS
-
- VERSIONS
-
- CONFORMING TO
-
- NOTES
-
- EXAMPLE
-
- SEE ALSO
-
- COLOPHON
-
This document was created by
man2html,
using the manual pages.
Time: 07:34:53 GMT, March 26, 2013