Task Queue API
[Task Synchronization API]

Files
file	task_queue_types.h
	[host/MPU] MARS Task Queue Types
file	task_queue.h
	[host] MARS Task Queue Flag API
file	task_queue.h
	[MPU] MARS Task Queue API
Defines
#define	MARS_TASK_QUEUE_HOST_TO_MPU   0x10
	Queue direction from PPU to SPU.
#define	MARS_TASK_QUEUE_MPU_TO_HOST   0x11
	Queue direction from SPU to PPU.
#define	MARS_TASK_QUEUE_MPU_TO_MPU   0x12
	Queue direction from SPU to SPU.
#define	MARS_TASK_QUEUE_WAIT_MAX   18
	Maximum tasks allowed to wait on a queue.
#define	MARS_TASK_QUEUE_ENTRY_SIZE_MAX   16384
	Maximum size allowed for queue entry.
Functions
int	mars_task_queue_create (struct mars_context *mars, uint64_t *queue_ea, uint32_t size, uint32_t depth, uint8_t direction)
	[host] Creates a task queue.
int	mars_task_queue_destroy (uint64_t queue_ea)
	[host] Destroys a task queue.
int	mars_task_queue_count (uint64_t queue_ea, uint32_t *count)
	[host/MPU] Returns the number of data items in the task queue.
int	mars_task_queue_clear (uint64_t queue_ea)
	[host/MPU] Clears the data items in the task queue.
int	mars_task_queue_push (uint64_t queue_ea, const void *data)
	[host/MPU] Pushes the data specified into the task queue. (Task Switch Call)
int	mars_task_queue_try_push (uint64_t queue_ea, const void *data)
	[host/MPU] Pushes the data specified into the task queue.
int	mars_task_queue_pop (uint64_t queue_ea, void *data)
	[host/MPU] Pops data from a task queue. (Task Switch Call)
int	mars_task_queue_try_pop (uint64_t queue_ea, void *data)
	[host/MPU] Pops data from a task queue.
int	mars_task_queue_peek (uint64_t queue_ea, void *data)
	[host/MPU] Pops data from a task queue without removing it. (Task Switch Call)
int	mars_task_queue_try_peek (uint64_t queue_ea, void *data)
	[host/MPU] Pops data from a task queue without removing it.
int	mars_task_queue_push_begin (uint64_t queue_ea, const void *data, uint32_t tag)
	[MPU] Begins push operation on a task queue. (Task Switch Call)
int	mars_task_queue_push_end (uint64_t queue_ea, uint32_t tag)
	[MPU] Completes push operation on a task queue.
int	mars_task_queue_try_push_begin (uint64_t queue_ea, const void *data, uint32_t tag)
	[MPU] Begins push operation on a task queue.
int	mars_task_queue_pop_begin (uint64_t queue_ea, void *data, uint32_t tag)
	[MPU] Begins pop operation on a task queue. (Task Switch Call)
int	mars_task_queue_pop_end (uint64_t queue_ea, uint32_t tag)
	[MPU] Completes pop operation on a task queue.
int	mars_task_queue_try_pop_begin (uint64_t queue_ea, void *data, uint32_t tag)
	[MPU] Begins pop operation on a task queue.
int	mars_task_queue_peek_begin (uint64_t queue_ea, void *data, uint32_t tag)
	[MPU] Begins peek operation on a task queue. (Task Switch Call)
int	mars_task_queue_peek_end (uint64_t queue_ea, uint32_t tag)
	[MPU] Completes peek operation on a task queue.
int	mars_task_queue_try_peek_begin (uint64_t queue_ea, void *data, uint32_t tag)
	[MPU] Begins peek operation on a task queue.

---

Detailed Description

The MARS task queue allows for sending and receiving of data between multiple MARS tasks and the host program.

From either a host program or MARS task you can push data into the queue and also from either a host program or MARS task you can pop data out from the queue as soon as it becomes available.

The advantage of the MARS task queue is that when a MARS task requests to do a pop and no data is available yet to be received from the queue, the MARS task will enter a waiting state. As soon as data is available to be popped from the queue, the MARS task can be scheduled for resumed execution with the received data.

---

Function Documentation

int mars_task_queue_create	(	struct mars_context *	mars,
		uint64_t *	queue_ea,
		uint32_t	size,
		uint32_t	depth,
		uint8_t	direction
	)

[host] Creates a task queue.

This function will allocate an instance of the task queue. The queue allows for tasks to wait until data is available from a FIFO data queue. The queue should be used in pairs with various calls to push and pop the the queue

Key Parameters:

size

• Specify the size of each data item in the queue.
• The size needs to be a multiple of 16 bytes and no larger than MARS_TASK_QUEUE_ENTRY_SIZE_MAX.

depth

• Specify the depth of the total queue.
• The number specified here is the total number of data items the queue can hold at a time.
• The size of the total queue is size * depth.

direction

• Specify the communication direction of the queue.
• Must be one of MARS_TASK_QUEUE_HOST_TO_MPU, MARS_TASK_QUEUE_MPU_TO_HOST, MARS_TASK_QUEUE_MPU_TO_MPU.

Parameters:

[in]	mars	- pointer to MARS context
[out]	queue_ea	- address of 64-bit address of queue instance
[in]	size	- size of each data item in data buffer
[in]	depth	- maximum number of data entries in data buffer
[in]	direction	- direction of the event flag

Returns:

MARS_SUCCESS - successfully created queue
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - size is not multiple of 16 bytes or is greater than 16KB maximum
MARS_ERROR_PARAMS - invalid direction specified
MARS_ERROR_MEMORY - not enough memory for queue buffer allocation

int mars_task_queue_destroy

(

uint64_t

queue_ea

)

[host] Destroys a task queue.

This function will free any resources allocated during creation of the task queue.

Parameters:

[in]

queue_ea

- ea of queue instance

Returns:

MARS_SUCCESS - successfully destroyed queue
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - ea not properly aligned
MARS_ERROR_STATE - tasks still waiting

int mars_task_queue_count	(	uint64_t	queue_ea,
		uint32_t *	count
	)

[host/MPU] Returns the number of data items in the task queue.

This function will return the total number of data items in the queue at the time of the call.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	count	- pointer to variable to store return count

Returns:

MARS_SUCCESS - successfully returned count
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly

int mars_task_queue_clear

(

uint64_t

queue_ea

)

[host/MPU] Clears the data items in the task queue.

This function will clear all data items currently in the queue. Entities waiting to pop data from the queue will remain waiting. Entities waiting to push data into the queue will resume.

Parameters:

[in]

queue_ea

- ea of initialized queue instance

Returns:

MARS_SUCCESS - successfully cleared queue
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly

int mars_task_queue_push	(	uint64_t	queue_ea,
		const void *	data
	)

[host/MPU] Pushes the data specified into the task queue. (Task Switch Call)

Note:

The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function will push the data specified into the queue. The entity waiting longest to pop data from the queue can resume.

If the queue is full at the time of this call, this function will cause the caller task to enter a waiting state until there is room in the queue to push the data.

Key Parameters:

data

• Specify the pointer to user data to copy into the queue.
• The size of data should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[in]	data	- address of data to be pushed into queue

Returns:

MARS_SUCCESS - successfully pushed data into queue
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
MARS_ERROR_STATE - invalid direction
MARS_ERROR_FORMAT - no context save area specified

int mars_task_queue_try_push	(	uint64_t	queue_ea,
		const void *	data
	)

[host/MPU] Pushes the data specified into the task queue.

This function will push the data specified into the queue. The entity waiting longest to pop data from the queue can resume.

If the queue is full at the time of this call, this function will return immedately with MARS_ERROR_BUSY.

Key Parameters:

data

• Specify the pointer to user data to copy into the queue.
• The size of data should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[in]	data	- address of data to be pushed into queue

Returns:

MARS_SUCCESS - successfully pushed data into queue
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_BUSY - queue is full
MARS_ERROR_STATE - invalid direction

int mars_task_queue_pop	(	uint64_t	queue_ea,
		void *	data
	)

[host/MPU] Pops data from a task queue. (Task Switch Call)

Note:

The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function will pop data from the queue.

If the queue is empty at the time of this call, this function will cause the caller task to enter a waiting state until there is data in the queue to pop.

Key Parameters:

data

• Specify the pointer to some allocated memory to copy the popped data.
• The size of the allocated memory area should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	data	- address of data to be popped from queue

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
MARS_ERROR_STATE - invalid direction
MARS_ERROR_FORMAT - no context save area specified

int mars_task_queue_try_pop	(	uint64_t	queue_ea,
		void *	data
	)

[host/MPU] Pops data from a task queue.

This function will pop data from the queue.

If the queue is empty at the time of this call, this function will return immedately with MARS_ERROR_BUSY.

Key Parameters:

data

• Specify the pointer to some allocated memory to copy the popped data.
• The size of the allocated memory area should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	data	- address for data to be popped from queue

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_BUSY - queue is empty
MARS_ERROR_STATE - invalid direction

int mars_task_queue_peek	(	uint64_t	queue_ea,
		void *	data
	)

[host/MPU] Pops data from a task queue without removing it. (Task Switch Call)

Note:

The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function will retrieve data from the queue without removing it from the queue.

If the queue is empty at the time of this call, this function will cause the caller task to enter a waiting state until there is data in the queue to be retrieved.

Key Parameters:

data

• Specify the pointer to some allocated memory to copy the popped data.
• The size of the allocated memory area should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	data	- address of data to be popped from queue

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
MARS_ERROR_STATE - invalid direction
MARS_ERROR_FORMAT - no context save area specified

int mars_task_queue_try_peek	(	uint64_t	queue_ea,
		void *	data
	)

[host/MPU] Pops data from a task queue without removing it.

This function will retrieve data from the queue without removing it from the queue.

If the queue is empty at the time of this call, this function will return immedately with MARS_ERROR_BUSY.

Key Parameters:

data

• Specify the pointer to some allocated memory to copy the popped data.
• The size of the allocated memory area should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	data	- address of data to be popped from queue

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_BUSY - queue is empty
MARS_ERROR_STATE - invalid direction

int mars_task_queue_push_begin	(	uint64_t	queue_ea,
		const void *	data,
		uint32_t	tag
	)

[MPU] Begins push operation on a task queue. (Task Switch Call)

Note:

The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function will begin pushing the data specified into the queue. This only initiates the memory transfer of data into the queue. This function must be completed with a matching call to mars_task_queue_push_end to guarantee the completion of the push.

If the queue is full at the time of this call, this function will cause the caller task to enter a waiting state until there is room in the queue to push the data.

Key Parameters:

data

• Specify the pointer to user data to copy into the queue.
• The size of data should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

tag

• Specify a memory transfer tag value between 0-31.
• Multiple push operations can be initiated concurrently, and each can be waited for independently if different memory tranfer tags are specified.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[in]	data	- address of data to be pushed into queue
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully pushed data into queue
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag
MARS_ERROR_FORMAT - no context save area specified

int mars_task_queue_push_end	(	uint64_t	queue_ea,
		uint32_t	tag
	)

[MPU] Completes push operation on a task queue.

This function will complete a push operation initiated with mars_task_queue_push_begin or mars_task_queue_try_push_begin. This function must be called in pair for each call to mars_task_queue_push_begin or mars_task_queue_try_push_begin to guarantee the completion of the initiated push operation.

Key Parameters:

tag

• Specify the memory transfer tag specified at push operation initialization.
• If multiple push operations were initiated concurrently, this call must wait for all memory transfers initiated with the same tag to complete.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully pushed data into queue
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag

int mars_task_queue_try_push_begin	(	uint64_t	queue_ea,
		const void *	data,
		uint32_t	tag
	)

[MPU] Begins push operation on a task queue.

This function will begin pushing the data specified into the queue. This only initiates the memory transfer of data into the queue. This function must be completed with a matching call to mars_task_queue_push_end to guarantee the completion of the push.

If the queue is full at the time of this call, this function will return immedately with MARS_ERROR_BUSY.

Key Parameters:

data

• Specify the pointer to user data to copy into the queue.
• The size of data should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

tag

• Specify a memory transfer tag value between 0-31.
• Multiple push operations can be initiated concurrently, and each can be waited for independently if different memory tranfer tags are specified.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[in]	data	- address of data to be pushed into queue
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully pushed data into queue
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_BUSY - queue is full
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag

int mars_task_queue_pop_begin	(	uint64_t	queue_ea,
		void *	data,
		uint32_t	tag
	)

[MPU] Begins pop operation on a task queue. (Task Switch Call)

Note:

The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function will begin popping data from the queue. This only initiates the memory transfer of data from the queue. This function must be completed with a matching call to mars_task_queue_pop_end to guarantee the completion of the pop.

If the queue is empty at the time of this call, this function will cause the caller task to enter a waiting state until there is data in the queue to pop.

Key Parameters:

data

• Specify the pointer to some allocated memory to copy the popped data.
• The size of the allocated memory area should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	data	- address of data to be popped from queue
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag
MARS_ERROR_FORMAT - no context save area specified

int mars_task_queue_pop_end	(	uint64_t	queue_ea,
		uint32_t	tag
	)

[MPU] Completes pop operation on a task queue.

This function will complete a pop operation initiated with mars_task_queue_pop_begin or mars_task_queue_try_pop_begin. This function must be called in pair for each call to mars_task_queue_pop_begin or mars_task_queue_try_pop_begin to guarantee the completion of the initiated pop operation.

Key Parameters:

tag

• Specify the memory transfer tag specified at pop operation initialization.
• If multiple pop operations were initiated concurrently, this call must wait for all memory transfers initiated with the same tag to complete.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag

int mars_task_queue_try_pop_begin	(	uint64_t	queue_ea,
		void *	data,
		uint32_t	tag
	)

[MPU] Begins pop operation on a task queue.

This function will begin popping data from the queue. This only initiates the memory transfer of data from the queue. This function must be completed with a matching call to mars_task_queue_pop_end to guarantee the completion of the pop.

If the queue is empty at the time of this call, this function will return immedately with MARS_ERROR_BUSY.

Key Parameters:

data

• Specify the pointer to some allocated memory to copy the popped data.
• The size of the allocated memory area should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	data	- address for data to be popped from queue
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_BUSY - queue is empty
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag

int mars_task_queue_peek_begin	(	uint64_t	queue_ea,
		void *	data,
		uint32_t	tag
	)

[MPU] Begins peek operation on a task queue. (Task Switch Call)

Note:

The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).

This function will begin retriveing data from the queue without removing the data from the queue. This only initiates the memory transfer of data from the queue. This function must be completed with a matching call to mars_task_queue_peek_end to guarantee the completion of the peek.

If the queue is empty at the time of this call, this function will cause the caller task to enter a waiting state until there is data in the queue to be retrived.

Key Parameters:

data

• Specify the pointer to some allocated memory to copy the popped data.
• The size of the allocated memory area should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	data	- address of data to be popped from queue
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag
MARS_ERROR_FORMAT - no context save area specified

int mars_task_queue_peek_end	(	uint64_t	queue_ea,
		uint32_t	tag
	)

[MPU] Completes peek operation on a task queue.

This function will complete a peek operation initiated with mars_task_queue_peek_begin or mars_task_queue_try_peek_begin. This function must be called in pair for each call to mars_task_queue_peek_begin or mars_task_queue_try_peek_begin to guarantee the completion of the initiated peek operation.

Key Parameters:

tag

• Specify the memory transfer tag specified at peek operation initialization.
• If multiple peek operations were initiated concurrently, this call must wait for all memory transfers initiated with the same tag to complete.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag

int mars_task_queue_try_peek_begin	(	uint64_t	queue_ea,
		void *	data,
		uint32_t	tag
	)

[MPU] Begins peek operation on a task queue.

This function will begin retriveing data from the queue without removing the data from the queue. This only initiates the memory transfer of data from the queue. This function must be completed with a matching call to mars_task_queue_peek_end to guarantee the completion of the peek.

If the queue is empty at the time of this call, this function will return immedately with MARS_ERROR_BUSY.

Key Parameters:

data

• Specify the pointer to some allocated memory to copy the popped data.
• The size of the allocated memory area should be equal to the size specified at queue creation.
• Note: In the Cell B.E. processor, data must be aligned to 16-bytes.

Parameters:

[in]	queue_ea	- ea of initialized queue instance
[out]	data	- address of data to be popped from queue
[in]	tag	- tag identifier for memory transfer

Returns:

MARS_SUCCESS - successfully popped data from queue
MARS_ERROR_NULL - ea or data is 0
MARS_ERROR_ALIGN - ea or data not aligned properly
MARS_ERROR_BUSY - queue is empty
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag