Creating threads for the SPEs

Programs to be run on an SPE are most often written in C or C++ (or assembly language) and can use the SPE data types and intrinsics defined in the SPU C/C++ Language Extensions.

The SPU C/C++ Language Extensions are described in SPU C/C++ language extensions (intrinsics). The SPE code modules must be written and compiled separately from the PPE code modules, using different compilers. A PPE module starts an SPE module running by creating a thread on the SPE, using the spe_context_create, spe_program_load, and spe_context_run library calls, provided in the SPE runtime management library.

The spe_context_create call creates a context for the SPE thread which contains the persistent information about a logical SPE. This information should not be accessed directly by the application. The signature and parameter synopsis for the spe_create_thread library call is:

spe_context_ptr_t  spe_context_create(unsigned int flags, 
  spe_gang_context_ptr_t gang)

flags – This is a bit-wise OR of modifiers that is applied when the new context is created. The following values are accepted:
- 0 – No modifiers are applied.
- SPE_EVENTS_ENABLE – Configure the context with event handling enabled.
- SPE_CFG_SIGNOTIFY1_OR – Configure the SPU Signal Notification 1 Register to be in “logical OR” mode instead of the default “Overwrite” mode.
- SPE_CFG_SIGNOTIFY2_OR – Configure the SPU Signal Notification 2 Register to be in “logical OR” mode instead of the default “Overwrite” mode.
- SPE_MAP_PS – Request permission for memory-mapped access to the SPE thread's problem state area.
- SPE_ISOLATE – Specifies that the SPE will execute in the isolation mode.
- SPE_ISOLATED_EMULATE – Specifies that the SPE will execute in an emulated isolation mode.
gang – Collection of contexts in which the context being created should made a part of.

Before being able to run an SPE context, an SPE program has to be loaded into the context using the spe_program_load subroutine. The signature and parameter synopsis for the spe_program_load library call is:

int  spe_program_load(spe_context_ptr spe, spe_program_handle_t *program)

spe – The SPE context in which in specified program is to be loaded.
program – Indicates the program to be loaded into the SPE context. This is an opaque pointer to an SPE Executable and Linking Format (ELF) image that has already been loaded and mapped into system memory. This pointer is normally provided as a symbol reference to an SPE ELF executable image that has been embedded into a PPE ELF object and linked with the calling PPE program. This pointer can also be established dynamically by loading a shared library containing an embedded SPE ELF executable, using dlopen(2) and dlsym(2), or by using the spe_image_open function to load and map a raw SPE ELF executable.

An SPE context is executed on a physical SPE by calling the spe_context_run function. This subroutine causes the current PPE thread to transition to a SPE thread by passing its execution control from the PPE to the SPE whose context is scheduled to run on. The PPE resumes execution when the SPE stops.

Note: In order to achieve multiple threads of execution (PPE and SPE threads), separate "pthreads" must be created for each thread of execution using pthread_create. An example is provided in Producing a simple multi-threaded CBE program.

The signature and parameter synopsis for the spe_context_run library call is:

int spe_context_run(spe_context_ptr_t spe, unsigned int *entry, 
  unsigned int runflags, void *argp, void *envp, spe_stop_info_t *stopinfo)

spe — The context to be run.
entry — Pointer initial value of the instruction pointer in which the SPE program should start executing. If the value pointed to by entry is SPE_DEFAULT_ENTRY, the default entry for the main program obtained from loaded SPE image will be used. Upon return from the spe_context_run call, the value pointed to by entry contains the next instruction to be executed upon resumption of the program.
runflags — This is a bit-wise OR of modifiers which request specific behavior when the SPE context is run. Flags include:
- 0 — Default behavior. No modifiers are applied.
- SPE_RUN_USER_REGS — Specifies that the SPE setup registers, r3, r4, and r5, are initialized with the 48 bytes pointed to by argp.
- SPE_NO_CALLBACKS — Specifies that register SPE library callbacks should not be automatically executed. This includes “PPE-assisted library calls” that are provided by the SPE Runtime library.
argp — An optional pointer to application specific data. It is passed as the second parameter of the SPU program.
envp — An optional pointer to environment specific data. It is passed as the third parameter of the SPU program.
stopinfo — An optional pointer to a structure of type spe_stop_info_t that provides information as to the reason why the SPE stopped running. See library documentation for more details on this structure.

The following code sample shows PPE code creating a SPE context, loading a SPE program into the context and running the program from the current thread.

#include <libspe2.h>
extern spe_program_handle_t spe_code; 
…
spe_context_ptr_t ctx;
unsigned int entry = SPE_DEFAULT_ENTRY;

if ((ctx = spe_context_create(0, NULL)) == NULL) {
	perror(“Failed creating SPE context);
	exit(1);
}
if (spe_program_load(ctx, &spe_code)) {
	perror(“Failed loading program”);
	exit(1);
}
if (spe_context_run(ctx, &entry, 0, NULL, NULL, NULL) < 0) {
	perror(“Failed running context”);
	exit(1);
}