Startup & Shutdown
[Environmental Management]

Collaboration diagram for Startup & Shutdown:

---

Detailed Description

Functions to start and terminate the MOC-execution environment.

To be able to communicate with other processes every MOC-process needs to setup his MOC-Environment before any MOC-function can be called (there are some exceptions though).

The PPU-process has a special role, because he is the one who starts the SPU-processes. SPU-processes can be added to the MOC-environment by calling MOC_Add_spu_thread with the appropriate SPU-thread-handle (This implementation only supports the embedded binary concept where the SPU-binary is embedded into the PPU-binary and accessed via a handle). The order of calling determines the rank of the SPU-processes. To get the number of total and available SPUs the functions MOC_Get_avail_spu_count and MOC_Get_max_spu_count can be used.

The buffer-size and the size of the message-queues can be set before calling MOC_Init on the PPU using MOC_Set_buffer_size and MOC_Set_queue_size.

MOC_Init only returns after all processes have called this function and have set up their environment.

If the MOC-environment isn't needed anymore, MOC_Finalize should be called by all MOC-processes. MOC_Finalize only returns after all MOC-processes have called this functions and have shutdown their environments.

PPU & SPU
int	MOC_Finalize (void)
	Terminates MPI execution environment.
PPU-only
int	MOC_Get_avail_spu_count (int *count)
	Returns the number of available SPUs.
int	MOC_Get_max_spu_count (int *count)
	Returns the number of SPUs.
int	MOC_Add_spu_thread (spe_program_handle_t *phandle, void *argp)
	Adds a SPU-Thread.
int	MOC_Set_buffer_size (uint32_t size)
	Sets the size of the buffer used for buffered communication.
int	MOC_Set_queue_size (uint8_t size)
	Sets the size of the message-queues.
int	MOC_Init (int *argc, char ***argv)
	Initialize the MPI execution environment.
SPU-only
int	MOC_Init (unsigned long long argp, int length, void *buffer)
	Initialize the MPI execution environment.

---

Function Documentation

int MOC_Add_spu_thread	(	spe_program_handle_t *	phandle,
		void *	argp
	)

Adds a SPU-Thread.

Attention:

PPU-only

Note:

Must be called before calling MOC_Init

The order of executions defines the order of the ranks of the SPU-Threads

Parameters:

	phandle	in Handle of the SPE-Program
	argp	in Pointer to some user-defined information in the main-memory

Return values:

	MOC_SUCCESS	No error; MPI routine completed successfully.
	MOC_ERR_BUFFER_OVERFLOW	A Buffer-Overflow occured. Mosst likely you tried to add more SPU-threads than defined by MOC_SPU_THREAD_MAX.
	MOC_ERR_INTERN	Internal Error

int MOC_Finalize

(

void

)

Terminates MPI execution environment.

Note:

All processes must call this routine before exiting.

Return values:

MOC_SUCCESS

No error; MPI routine completed successfully.

int MOC_Get_avail_spu_count

(

int *

count

)

Returns the number of available SPUs.

Attention:

PPU-only

Note:

Must be called before MOC_Init

This function should return the count of free SPUs. But this doesn't really works. To get the available SPU-count the function spe_cpu_info_get() from libspe2 with SPE_COUNT_USABLE_SPES-flag is used. However this function can only detect if a SPU-thread is used by the calling function. There seems to be no means to detect SPU-thread used by other applications.

Parameters:

count

out number of available SPUs

Return values:

	MOC_SUCCESS	No error; MPI routine completed successfully.
	...	error-code

int MOC_Get_max_spu_count

(

int *

count

)

Returns the number of SPUs.

Attention:

PPU-only

Note:

Must be called before MOC_Init

Parameters:

count

out SPU-count

Return values:

	MOC_SUCCESS	No error; MPI routine completed successfully.
	...	error-code

int MOC_Init	(	unsigned long long	argp,
		int	length,
		void *	buffer
	)

Initialize the MPI execution environment.

Attention:

SPU-only function

Note:

All processes must call this routine before executing any MOC-routine.

Parameters:

	argp	in Pointer to user-defined information in the main-memory
	length	in Length of the user-defined information in bytes
	buffer	out Buffer into which the user-defined information should be copied

Return values:

	MOC_SUCCESS	No error; MPI routine completed successfully.
	MOC_ERR_NO_MEMORY	Insufficient Memory.
	MOC_ERR_INTERN	Internal Error

int MOC_Init	(	int *	argc,
		char ***	argv
	)

Initialize the MPI execution environment.

Attention:

PPU-only function

Note:

All processes must call this routine before executing any MOC-routine.

Parameters:

	argc	in Pointer to the number of arguments
	argv	in Pointer to the argument vector

Return values:

	MOC_SUCCESS	No error; MPI routine completed successfully.
	MOC_ERR_NO_MEMORY	Insufficient Memory.
	MOC_ERR_INTERN	Internal Error

int MOC_Set_buffer_size

(

uint32_t

size

)

Sets the size of the buffer used for buffered communication.

Attention:

PPU-only

Note:

Must be called before MOC_Init

Parameters:

size

buffer-size

Returns:

0 if success, otherwise error-code

int MOC_Set_queue_size

(

uint8_t

size

)

Sets the size of the message-queues.

Attention:

PPU-only

Note:

Must be called before MOC_Init

Parameters:

size

queue-size

Returns:

0 if success, otherwise error-code