Data structures

This section summarizes the specified data structures upon which the libspe API relies. These data structures are defined in the <libspe2.h> header file. Any libspe application should include this header file.

 /*
  * spe_context_ptr_t
  * 	This pointer serves as the identifier for a specific
  *	SPE context throughout the API (where needed)
  */
typedef struct spe_context * spe_context_ptr_t;

/*
 * spe_gang_context_ptr_t
 * 	This pointer serves as the identifier for a specific
 *	SPE gang context throughout the API (where needed)
 */
typedef struct spe_gang_context * spe_gang_context_ptr_t;

/*
 * SPE program handle
 * Structure spe_program_handle per CESOF specification
 * libspe2 applications usually only keep a pointer
 * to the program handle and do not use the structure
 * directly.
 */
typedef struct spe_program_handle {
	/*
	 * handle_size allows for future extensions of the spe_program_handle 
	 * struct by new fields, without breaking compatibility with existing users. 
	 * Users of the new field would check whether the size is large enough. 
	 */
	unsigned int	handle_size;
	void				*elf_image;
	void				*toe_shadow;
} spe_program_handle_t;

/*
 * SPE stop information
 * This structure is used to return all information available 
 * on the reason why an SPE program stopped execution. 
 * This information is important for some advanced programming 
 * patterns and/or detailed error reporting.
 */
 
/* spe_stop_info_t
 */
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;
		void *__reserved_ptr;
     unsigned long long __reserved_u64;
	} result;
	int spu_status;
} spe_stop_info_t;

/* spe problem state areas
 */

typedef struct spe_mssync_area {
	unsigned int MFC_MSSync;
} spe_mssync_area_t;

typedef struct spe_mfc_command_area {
	unsigned char reserved_0_3[4];
	unsigned int MFC_LSA;
	unsigned int MFC_EAH;
	unsigned int MFC_EAL;
	unsigned int MFC_Size_Tag;
	union {     
		unsigned int MFC_ClassID_CMD;
		unsigned int MFC_CMDStatus;
	};
	unsigned char reserved_18_103[236];
	unsigned int MFC_QStatus;
	unsigned char reserved_108_203[252];
	unsigned int Prxy_QueryType;      
	unsigned char reserved_208_21B[20];      
	unsigned int Prxy_QueryMask;     
	unsigned char reserved_220_22B[12];   
	unsigned int Prxy_TagStatus;  
} spe_mfc_command_area_t;  

typedef struct spe_spu_control_area {
	unsigned char reserved_0_3[4]; 
	unsigned int SPU_Out_Mbox; 
	unsigned char reserved_8_B[4];
	unsigned int SPU_In_Mbox; 
	unsigned char reserved_10_13[4]; 
	unsigned int SPU_Mbox_Stat; 
	unsigned char reserved_18_1B[4];
	unsigned int SPU_RunCntl;
	unsigned char reserved_20_23[4];  
	unsigned int SPU_Status; 
	unsigned char reserved_28_33[12];
	unsigned int SPU_NPC;    
} spe_spu_control_area_t;

typedef struct spe_sig_notify_1_area {     
	 unsigned char reserved_0_B[12]; 
	 unsigned int SPU_Sig_Notify_1;    
 } spe_sig_notify_1_area_t;   

typedef struct spe_sig_notify_2_area {  
	 unsigned char reserved_0_B[12]; 
	 unsigned int SPU_Sig_Notify_2;    
 } spe_sig_notify_2_area_t;

/*
 * SPE event structure
 * This structure is used for SPE event handling
 */
 
/*
 * spe_event_data_t
 * User data to be associated with an event
 */
typedef union spe_event_data {
  void *ptr;
  unsigned int u32;
  unsigned long long u64;
} spe_event_data_t;

/* spe_event_t
 */
typedef struct spe_event_unit {
  unsigned int events;
  spe_context_ptr_t spe;
  spe_event_data_t data;
} spe_event_unit_t;