SPU Thread Management

Overview

The SPU thread management API provides functions for creating, running, and managing SPU threads on the PlayStation 3’s Cell Broadband Engine. SPU threads are dedicated programs running on the Synergistic Processing Elements (SPEs).

Key Concepts

SPU Thread Group: A collection of SPU threads that run together
SPU Image: Binary code loaded from an ELF file to execute on an SPU
Local Store: 256 KB of memory private to each SPU
Mailbox Communication: Message passing between PPU and SPU threads

The PS3 has 6 SPEs available to user programs. For optimal performance, avoid running more than 6 SPU threads simultaneously to prevent context switches.

SPU Image Management

sysSpuImageOpen

Create a SPU image from an ELF file.

s32 sysSpuImageOpen(sysSpuImage* image, const char* path)

image

sysSpuImage*

required

Pointer to the SPU image structure to be initialized

path

const char*

required

Path to the SPU ELF file

return

s32

Zero if successful, nonzero on error

sysSpuImageImport

Import a SPU image from an ELF file in memory.

s32 sysSpuImageImport(sysSpuImage *image, const void *elf, u32 type)

image

sysSpuImage*

required

Pointer to the image structure to be updated

elf

const void*

required

Pointer to ELF data in memory

type

u32

Type of the image file (generally set to 0)

return

s32

Zero if successful, nonzero on error

sysSpuImageClose

Close an opened SPU image file.

s32 sysSpuImageClose(sysSpuImage *image)

image

sysSpuImage*

required

Pointer to the SPU image structure

return

s32

Zero if successful, nonzero on error

Thread Group Management

sysSpuThreadGroupCreate

Create a SPU thread group.

s32 sysSpuThreadGroupCreate(sys_spu_group_t *group, u32 num, u32 prio, sysSpuThreadGroupAttribute *attr)

group

sys_spu_group_t*

required

Pointer to the returned thread group identifier

num

u32

required

Number of SPU threads in the group (1-6)

prio

u32

required

Priority of the thread group

attr

sysSpuThreadGroupAttribute*

required

Pointer to a thread group attribute structure

return

s32

Zero if successful, nonzero on error

sysSpuThreadGroupStart

Start execution of all threads in a SPU thread group.

s32 sysSpuThreadGroupStart(sys_spu_group_t group)

group

sys_spu_group_t

required

Thread group identifier

return

s32

Zero if successful, nonzero on error

sysSpuThreadGroupJoin

Wait for a SPU thread group to finish execution.

s32 sysSpuThreadGroupJoin(sys_spu_group_t group, u32 *cause, u32 *status)

group

sys_spu_group_t

required

Thread group identifier

cause

u32*

required

Pointer to returned termination cause

status

u32*

required

Pointer to returned termination status

return

s32

Zero if successful, nonzero on error

sysSpuThreadGroupDestroy

Destroy a SPU thread group.

s32 sysSpuThreadGroupDestroy(sys_spu_group_t group)

group

sys_spu_group_t

required

Thread group identifier

return

s32

Zero if successful, nonzero on error

Thread Management

sysSpuThreadInitialize

Initialize a SPU thread within a thread group.

s32 sysSpuThreadInitialize(sys_spu_thread_t* thread, sys_spu_group_t group, u32 spu,
                           sysSpuImage* image, sysSpuThreadAttribute* attributes,
                           sysSpuThreadArgument* arguments)

thread

sys_spu_thread_t*

required

Pointer to the returned thread identifier

group

sys_spu_group_t

required

Thread group identifier

spu

u32

required

Index of thread in group (0 to group size - 1)

image

sysSpuImage*

required

Pointer to the SPU image structure

attributes

sysSpuThreadAttribute*

required

Pointer to thread attributes

arguments

sysSpuThreadArgument*

required

Pointer to arguments for the thread’s main function

return

s32

Zero if successful, nonzero on error

sysSpuThreadSetArguments

Set or update SPU thread arguments.

s32 sysSpuThreadSetArguments(sys_spu_thread_t thread, sysSpuThreadArgument* arguments)

thread

sys_spu_thread_t

required

Thread identifier

arguments

sysSpuThreadArgument*

required

Pointer to the arguments list

return

s32

Zero if successful, nonzero on error

sysSpuThreadGetExitStatus

Get the exit status of a terminated SPU thread.

s32 sysSpuThreadGetExitStatus(sys_spu_thread_t thread, s32* status)

thread

sys_spu_thread_t

required

Thread identifier

status

s32*

required

Pointer to the returned exit status

return

s32

Zero if successful, nonzero on error

Mailbox Communication

sysSpuThreadWriteMb

Write to a SPU thread’s inbound mailbox.

s32 sysSpuThreadWriteMb(sys_spu_thread_t thread, u32 value)

thread

sys_spu_thread_t

required

Thread identifier

value

u32

required

32-bit value to write to mailbox

return

s32

Zero if successful, nonzero on error

sysSpuThreadWriteSignal

Write to a SPU thread’s signal notification register.

s32 sysSpuThreadWriteSignal(sys_spu_thread_t thread, u32 signal, u32 value)

thread

sys_spu_thread_t

required

Thread identifier

signal

u32

required

Signal register number (0 for register 1, 1 for register 2)

value

u32

required

Value to write to the signal register

return

s32

Zero if successful, nonzero on error

Local Store Access

sysSpuThreadWriteLocalStorage

Write a value to a SPU thread’s local store memory.

s32 sysSpuThreadWriteLocalStorage(sys_spu_thread_t thread, u32 address, u64 value, u32 type)

thread

sys_spu_thread_t

required

Thread identifier

address

u32

required

Address in local store (0-262143)

value

u64

required

Value to write

type

u32

required

Data type size

return

s32

Zero if successful, nonzero on error

sysSpuThreadReadLocalStorage

Read a value from a SPU thread’s local store memory.

s32 sysSpuThreadReadLocalStorage(sys_spu_thread_t thread, u32 address, u64* value, u32 type)

thread

sys_spu_thread_t

required

Thread identifier

address

u32

required

Address in local store

value

u64*

required

Pointer to store the read value

type

u32

required

Data type size

return

s32

Zero if successful, nonzero on error

SPU-Side Functions

These functions are called from within SPU code:

spu_thread_exit

Terminate the running SPU thread.

void spu_thread_exit(int status)

status

int

required

Exit status value returned to PPU

spu_thread_group_exit

Terminate the entire SPU thread group.

void spu_thread_group_exit(int status)

status

int

required

Thread group exit status

spu_thread_group_yield

Voluntarily yield execution to allow thread group scheduling.

void spu_thread_group_yield(void)

Example Usage

Basic SPU Thread Creation

#include <ppu/include/sys/spu.h>
#include <ppu/include/lv2/spu.h>

sys_spu_group_t group;
sys_spu_thread_t thread;
sysSpuImage image;
sysSpuThreadGroupAttribute groupAttr;
sysSpuThreadAttribute threadAttr;
sysSpuThreadArgument args;

// Initialize attributes
sysSpuThreadGroupAttributeInitialize(groupAttr);
sysSpuThreadGroupAttributeName(groupAttr, "MySpuGroup");

sysSpuThreadAttributeInitialize(threadAttr);
sysSpuThreadAttributeName(threadAttr, "MySpuThread");

sysSpuThreadArgumentInitialize(args);
args.arg0 = 0x1234;
args.arg1 = 0x5678;

// Load SPU image
if (sysSpuImageOpen(&image, "/app_home/spu_program.elf") != 0) {
    printf("Failed to load SPU image\n");
    return -1;
}

// Create thread group
if (sysSpuThreadGroupCreate(&group, 1, 100, &groupAttr) != 0) {
    printf("Failed to create thread group\n");
    sysSpuImageClose(&image);
    return -1;
}

// Initialize thread
if (sysSpuThreadInitialize(&thread, group, 0, &image, &threadAttr, &args) != 0) {
    printf("Failed to initialize thread\n");
    sysSpuThreadGroupDestroy(group);
    sysSpuImageClose(&image);
    return -1;
}

// Start thread group
if (sysSpuThreadGroupStart(group) != 0) {
    printf("Failed to start thread group\n");
    sysSpuThreadGroupDestroy(group);
    sysSpuImageClose(&image);
    return -1;
}

// Wait for completion
u32 cause, status;
sysSpuThreadGroupJoin(group, &cause, &status);

// Cleanup
sysSpuThreadGroupDestroy(group);
sysSpuImageClose(&image);

Mailbox Communication Example

// PPU side - send message to SPU
u32 message = 0xDEADBEEF;
sysSpuThreadWriteMb(thread, message);

// SPU side - receive message
#include <spu_mfcio.h>

u32 received = spu_read_in_mbox();
printf("SPU received: 0x%08x\n", received);

// SPU side - send response
spu_write_out_mbox(0xCAFEBABE);

// PPU side - read response (using problem storage)
u32 response = sysSpuThreadReadProblemStorage(thread, SPU_Out_MBox);

Constants

Thread Attributes

SPU_THREAD_ATTR_NONE - No special attributes
SPU_THREAD_ATTR_ASYNC_INT_ENABLE - Enable asynchronous interrupts
SPU_THREAD_ATTR_DEC_SYNC_TB_ENABLE - Synchronize decrementer with PPU time base

Thread Group Types

SPU_THREAD_GROUP_TYPE_NORMAL - Normal thread group
SPU_THREAD_GROUP_TYPE_SEQUENTIAL - Sequential execution
SPU_THREAD_GROUP_TYPE_SYSTEM - System thread group
SPU_THREAD_GROUP_TYPE_MEMORY_FROM_CONTAINER - Use memory container

Signal Configuration

SPU_SIGNAL1_OVERWRITE - Signal 1 in overwrite mode
SPU_SIGNAL1_OR - Signal 1 in OR mode
SPU_SIGNAL2_OVERWRITE - Signal 2 in overwrite mode
SPU_SIGNAL2_OR - Signal 2 in OR mode

Memory-Mapped Addresses

SPU thread resources are memory-mapped starting at 0xF0000000:

#define SPU_THREAD_BASE         0xF0000000ULL
#define SPU_THREAD_OFFSET       0x00100000ULL

// Get base address for SPU thread N
uint64_t addr = SPU_THREAD_BASE + (N * SPU_THREAD_OFFSET);

// Access local storage
uint64_t ls_addr = addr + SPU_LOCAL_OFFSET;  // +0x00000000

// Access problem storage (registers)
uint64_t ps_addr = addr + SPU_PROBLEM_OFFSET;  // +0x00040000

Graphics APIs

Input APIs

Audio APIs

Network APIs

System APIs

System Utility APIs

Media APIs

Device APIs

SPU APIs

Math Libraries

​Overview

​Key Concepts

​SPU Image Management

​sysSpuImageOpen

​sysSpuImageImport

​sysSpuImageClose

​Thread Group Management

​sysSpuThreadGroupCreate

​sysSpuThreadGroupStart

​sysSpuThreadGroupJoin

​sysSpuThreadGroupDestroy

​Thread Management

​sysSpuThreadInitialize

​sysSpuThreadSetArguments

​sysSpuThreadGetExitStatus

​Mailbox Communication

​sysSpuThreadWriteMb

​sysSpuThreadWriteSignal

​Local Store Access

​sysSpuThreadWriteLocalStorage

​sysSpuThreadReadLocalStorage

​SPU-Side Functions

​spu_thread_exit

​spu_thread_group_exit

​spu_thread_group_yield

​Example Usage

​Basic SPU Thread Creation

​Mailbox Communication Example

​Constants

​Thread Attributes

​Thread Group Types

​Signal Configuration

​Memory-Mapped Addresses

Build docs developers (and LLMs) love

Overview

Key Concepts

SPU Image Management

sysSpuImageOpen

sysSpuImageImport

sysSpuImageClose

Thread Group Management

sysSpuThreadGroupCreate

sysSpuThreadGroupStart

sysSpuThreadGroupJoin

sysSpuThreadGroupDestroy

Thread Management

sysSpuThreadInitialize

sysSpuThreadSetArguments

sysSpuThreadGetExitStatus

Mailbox Communication

sysSpuThreadWriteMb

sysSpuThreadWriteSignal

Local Store Access

sysSpuThreadWriteLocalStorage

sysSpuThreadReadLocalStorage

SPU-Side Functions

spu_thread_exit

spu_thread_group_exit

spu_thread_group_yield

Example Usage

Basic SPU Thread Creation

Mailbox Communication Example

Constants

Thread Attributes

Thread Group Types

Signal Configuration

Memory-Mapped Addresses