PPE-assisted library facilities

The SPEs in the Cell BE are designed to bear the computational workload of an application. They are not well-suited for the general purpose code that is often needed outside the "compute kernels" of an application.

The SPE Runtime Management Library provides the infrastructure that enables the SPE program to issue a callback to the PPE-side of the SPE thread. From an SPE program's point of view, this mechanism allows certain functions to be offloaded to the PPE.

To provide this functionality the SPE program uses the stop and signal instruction (see note) with a signal type 0x21XX to stop the SPE and notify the PPE-side of the SPE thread that the callback with number XX should be run. The SPE can also pass 4 bytes as an argument to the library function. This argument must immediately follow the stop and signal instruction in the SPE local store.

Note: See C/C++ Language Extensions for Cell Broadband Engine Architecture, SPU Control Intrinsics,spu_stop: stop and signal – (void) spu_stop(type)

Execution of the SPU program is stopped. The address of the stop instruction is placed into the least significant bits of the SPU NPC register. The signal type is written to the SPU status register, and the PPU is interrupted.

In libspe the execution of callbacks is handled inside the spe_context_run function. It recognizes the SPE callback as a special stop reason, stop and signal with a signal type in the range of 0x2100 to 0x21ff, and matches the lower 8 bit of the signal type with a list of registered library callback function handlers, which are then called. After the function returns, spe_context_run restarts SPE program execution at the last SPU instruction counter plus 4, that is, it skips the argument in the SPE local store.

The prototype of a valid library callback function handler must be:

int function_name (void *ls_base, unsigned int ls_address)

Parameters

ls_base: A pointer to the beginning of the memory-mapped SPE local store.
ls_address: the offset of the callback argument relative to ls_base in bytes.

Return values

On success, the function returns 0 (zero).

A non-zero return value is interpreted as failure. In this case, the SPE stops, spe_context_run returns with an SPE_CALLBACK_ERROR, and this return value is reported as part of stopinfo.

Example

A simple example of a callback that just prints its argument:

/*
 * simple library callback handler
 */

int simple_handler (void *ls_base, unsigned int ls_address)
{
	int arg = *((int *)((char *)ls_base + ls_address));
	
	printf ("callback argument was %d \n", arg];
	return 0;
};

Before you can use a library callback function, you must use the libspe function spe_callback_handler_register to register it. If an SPE program tries to use a callback that has not been properly registered, the SPE stops and spe_context_run returns with an SPE_CALLBACK _ERROR.

Implementations of libspe can reserve certain callback numbers for "built-in" functions:

Note: (Linux) The Cell BE Linux Reference Implementation Application Binary Interface Specification reserves certain standardized library classes and call opcodes. These correspond the following reserved callnums in libspe:

0	ISO/IEC C Standard Header
1	POSIX.1 (IEEE Standard 1003.1)
2	POSIX.4
3	Operating system-dependent system calls

If invalid opcodes and/or invalid pointers are passed to callbacks corresponding to these reserved callnums as their arguments, the callbacks return non-zero values to indicate failure.