spe_context

NAME

spe_context_run - Request execution of an SPE context.

SYNOPSIS

#include <libspe2.h>

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

Parameters
spe	A pointer to the SPE context that should be run.
entry	Input: The entry point, that is, the initial value of the SPU instruction pointer, at which the SPE program should start executing. If the value of entry is SPE_DEFAULT_ENTRY, the entry point for the SPU main program is obtained from the loaded SPE image. This is usually the local store address of the initialization function crt0 (see Cell Broadband Engine Programming Handbook, Objects, Executables, and SPE Loading). Output: The SPU instruction pointer at the moment the SPU stopped execution, that is, the local store address of the next instruction that would be have been executed. This parameter can be used, for example, to allow the SPE program to "pause" and request some action from the PPE thread, for example, performing an I/O operation. After this PPE-side action has been completed, you can continue the SPE program calling spe_context_run again without changing entry.
runflags	A bit mask that can be used to request certain specific behavior for the execution of the SPE context. If the value is 0, this indicates default behavior (see Usage).
argp	An (optional) pointer to application specific data, and is passed as the second parameter to the SPE program, (see Note).
envp	An (optional) pointer to environment specific data, and is passed as the third parameter to the SPE program, (see Note).
stopinfo	An (optional) pointer to a structure of type spe_stop_info_t (see Usage).

DESCRIPTION

Request execution of an SPE context. A SPE program must be loaded (using spe_program_load) before you can run the SPE context.

The thread calling spe_context_run blocks and waits until the SPE stops, due to normal termination of the SPE program, or an SPU stop and signal instruction, or an error condition. When spe_context_run returns, the calling thread must take appropriate actions depending on the application logic.

spe_context_run returns information about the termination of the SPE program in three ways. This allows applications to deal with termination conditions on various levels.

First, the most common usage for many applications is covered by the return value of the function and the errno value being set appropriately.
Second, the optional stopinfo structure provides detailed information about the termination condition in a structured way that allows applications more fine-grained error handling and enables implementation of special scenarios.
Third, the stopinfo structure contains the field spu_status that contains the value of the CBEA SPU Status Register (SPU_Status) as specified in the Cell Broadband Engine Architecture, Version 1, section 8.5.2 upon termination of the SPE program. This can be very useful, especially in conjunction with the SPE_NO_CALLBACKS flag, for applications that run non-standard SPE programs and want to react to all possible conditions flexibly and not rely on predefined conventions.

RETURN VALUE

On success, 0 (zero) or a positive number is returned.

A return value of 0 (zero) indicates that the SPE program terminated normally by calling exit(). The actual exit value can be obtained from stopinfo.

A positive return value indicates that the SPE has stopped because the SPU issued a stop and signal instruction and the return value represents the 14-bit value set by that stop and signal instruction.

EXIT STATUS

On error, -1 is returned and errno is set to indicate the error.

Possible errors include:

ESRCH	The specified SPE context is not valid.
EINVAL	The value passed for flags is not valid.
EIO	An SPE I/O error occurred, for example, a misaligned DMA. Details can be found in stopinfo.
EFAULT	Some other SPE runtime problem occurred. Details can be found in stopinfo.
EPERM	The SPE isolation system mechanism is corrupted. No isolated SPE program can be loaded and started.

OPTIONS

The following flags are accepted for the runflags parameter. Multiple flags can be combined using bit-wise OR.

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 registered SPE library calls ("callbacks" from this library's view) should not run automatically if a callback is encountered. This also disables callbacks that are predefined in the library implementation. See PPE-assisted library calls for details.; spe_context_run returns as if the SPU would have issued a regular stop and signal instruction. The signal code is returned as part of stopinfo.

USAGE

stopinfo

When spe_context_run returns, it provides information about the exact conditions in which the SPE stopped program execution in the data structure pointed to by stopinfo. If stopinfo is NULL, this information is not returned by the call.

If stopinfo is a valid pointer, the structure is filled with all information available as to the reason why the SPE program stopped running. This information is important for some advanced programming patterns, or detailed error reporting, or both.

If stopinfo is NULL, no information beyond the return value (specified below) as to the reason and associated data why the SPE program stopped execution will be returned.

The data type spe_stop_info_t is defined as follows:

typedef struct spe_stop_info { 	
   unsigned int stop_reason; 	
   union { 		
     int spe_exit_code; 		
     int spe_signal_code; 		
     int spe_runtime_error; 		
     int spe_runtime_exception;  		
     int spe_runtime_fatal; 		
     int spe_callback_error; 		
     int spe_isolation_error;
     void *__reserved_ptr; 
     unsigned long long __reserved_u64; 	
   } result; 	
   int spu_status; 
} spe_stop_info_t;

The valid values for stop_reason are defined by the following constants:

SPE_EXIT	SPE program terminated calling exit(code) with code in the range 0..255. The code is saved in spe_exit_code.
SPE_STOP_AND_SIGNAL	SPE program stopped because SPU ran a stop and signal instruction. Further information in field spe_signal_code.
SPE_RUNTIME_ERROR	SPE program stopped because of a one of the reasons found in spe_runtime_error. Note: (Linux) The error SPE_SPU_INVALID_INSTR is reported as a Linux signal SIGILL if the SPE context was created without the flag SPE_EVENTS_ENABLE.
SPE_RUNTIME_EXCEPTION	SPE program stopped asynchronously because of a runtime exception (event) described in spe_runtime_exception. In this case, spe_status would be meaningless and is therefore set to -1. Note: (Linux^®) This error situation can only be caught and reported by spe_context_run if the SPE context was created with the flag SPE_EVENTS_ENABLE indicating that event support is requested. Otherwise the Linux kernel generates a signal to indicate the runtime error.
SPE_RUNTIME_FATAL	The SPE program stopped for other reasons, usually fatal operating system errors such as insufficient resources. Further information in spe_runtime_fatal. In this case, spe_status would be meaningless and is therefore set to -1.
SPE_CALLBACK_ERROR	An SPE program tried to use unregistered library callback, or a library callback returned a non-zero exit value, which is provided in spe_callback_error.
SPE_ISOLATION_ERROR	The SPE isolation system mechanism has detected an error when attempting to load the isolated SPE program. The reason for the failure is captured in spe_isolation_error.

Depending on stop_reason more specific information is provided in the result field:

spe_exit_code	Exit code returned by the SPE program in the range 0..255. The convention for stop and signal usage by SPE programs is that 0x2000-0x20FF are exit events. 0x2100-0x21FF are callback events. 0x0 is an invalid instruction runtime error. Signal codes 0x0001-0x1FFF are user-defined signals. This convention determines the mapping to the respective fields in stopinfo.
spe_signal_code	Stop and signal code sent by the SPE program. The lower 14-bit of this field contain the signal number. The convention for stop and signal usage by SPE programs is that 0x2000-0x20FF are exit events. 0x2100-0x21FF are callback events. 0x0 is an invalid instruction runtime error. Signal codes 0x0001-0x1FFF are user-defined signals. This convention determines the mapping to the respective fields in stopinfo.
spe_runtime_error	SPE_SPU_HALT: SPU was stopped by halt. SPE_SPU_SINGLE_STEP: SPU is in single-step mode SPE_SPU_INVALID_INSTR: SPU has tried to execute an invalid instruction SPE_SPU_INVALID_CHANNEL: SPU has tried to access an invalid channel
spe_runtime_exception	SPE_DMA_ALIGNMENT: A DMA alignment error SPE_DMA_SEGMENTATION: A DMA segmentation error SPE_DMA_STORAGE: A DMA storage error SPE_INVALID_DMA: An invalid DMA error
spe_runtime_fatal	Contains the (implementation-dependent) errno as set by the underlying system call that failed.
spe_callback_error	Contains the return code from the failed library callback, or it is set to -1 in the case of unregistered library callback.
spe_isolation_error	Contains the implementation-dependent error code for the failed starting of an isolated SPE program.

The field spu_status contains the value of the architected "SPU Status Register (SPU_Status)" as defined in the Cell Broadband Engine Architecture, Version 1.0, section 8.5.2 at the point in time the SPU stopped execution. In some circumstances, for example, asynchronous errors such as DMA alignment errors, this value would be meaningless and therefore a value of -1 is returned to indicate that situation.

The content of spu_status is fully reflected in the stop_reason and subsequent field and is returned to allow low-level application their own, direct interpretation of spu_status directly following the CBE Architecture specification. Most applications do not need this field.

NOTES

Argument passing to SPE programs:

An application may pass arguments to an SPE program by using argp, envp, and the SPE_RUN_USER_REGS flag above. The SPE registers r3, r4, and r5 are initialized according to the following scheme:

If SPE_RUN_USER_REGS is not set, then the registers are initialized as follows:

r3 spe - the address of the SPE context being run
r4 argp - usually a pointer to argv of the main program
r5 envp - usually the environment pointer of the main program

All 32-bit or 64-bit pointers are put into the correct preferred slots for the 128-bit SPE registers.

If SPE_RUN_USER_REGS is set, then the registers are initialized with a copy of an (uninterpreted) 48-byte user data field pointed to by argp. envp is ignored in this case.

spe_context_run