SPU_RUN

NAME

SYNOPSIS

#include <sys/spu.h>

int spu_run(int fd, unsigned int *npc, unsigned int *event);

DESCRIPTION

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

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

CONFORMING TO

NOTES

EXAMPLE

#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

COLOPHON

Index

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

VERSIONS

CONFORMING TO

NOTES

EXAMPLE

SEE ALSO

COLOPHON