Task Queue API
[Task Synchronization API]


Files
file	mars_task_queue_types.h
	MARS Task Queue Types.
file	mars_task_queue.h
	[host] MARS Task Queue Flag API
file	mars_task_queue.h
	[MPU] MARS Task Queue API
Data Structures
struct	mars_task_queue
	MARS task queue structure. More...
Defines
#define	MARS_TASK_QUEUE_SIZE 128
	Size of task queue structure.
#define	MARS_TASK_QUEUE_ALIGN 128
	Alignment of task queue structure.
#define	MARS_TASK_QUEUE_ALIGN_MASK 0x7f
	Alignment mask of task queue structure.
#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.
#define	MARS_TASK_QUEUE_ENTRY_SIZE_MASK 0xf
	Mask for 16-byte alignment of queue entry size.
#define	MARS_TASK_QUEUE_ENTRY_ALIGN 16
	Alignment of queue entry data.
#define	MARS_TASK_QUEUE_ENTRY_ALIGN_MASK 0xf
	Alignment mask of queue entry data.
#define	MARS_TASK_QUEUE_BUFFER_ALIGN 16
	Alignment of queue buffer.
#define	MARS_TASK_QUEUE_BUFFER_ALIGN_MASK 0xf
	Alignment mask of queue buffer.
Functions
int	mars_task_queue_initialize (struct mars_context mars, struct mars_task_queue queue, void *buffer, uint32_t size, uint32_t depth, uint8_t direction)
	[host] Initializes a task queue.
int	mars_task_queue_count (struct mars_task_queue queue, uint32_t count)
	[host] Returns the number of items in the task queue.
int	mars_task_queue_clear (struct mars_task_queue *queue)
	[host] Clears the items in the task queue.
int	mars_task_queue_push (struct mars_task_queue queue, const void data)
	[host] Pushes the data specified into the task queue. (Blocking)
int	mars_task_queue_try_push (struct mars_task_queue queue, const void data)
	[host] Pushes the data specified into the task queue. (Non-Blocking)
int	mars_task_queue_pop (struct mars_task_queue queue, void data)
	[host] Pops data from a task queue. (Blocking)
int	mars_task_queue_try_pop (struct mars_task_queue queue, void data)
	[host] Pops data from a task queue. (Non-Blocking)
int	mars_task_queue_peek (struct mars_task_queue queue, void data)
	[host] Pops data from a task queue without removing it. (Blocking)
int	mars_task_queue_try_peek (struct mars_task_queue queue, void data)
	[host] Pops data from a task queue without removing it. (Non-Blocking)
int	mars_task_queue_initialize (uint64_t queue_ea, uint64_t buffer_ea, uint32_t size, uint32_t depth, uint8_t direction)
	[MPU] Initializes a task queue.
int	mars_task_queue_count (uint64_t queue_ea, uint32_t *count)
	[MPU] Returns the number of items in the task queue.
int	mars_task_queue_clear (uint64_t queue_ea)
	[MPU] Clears the items in the task queue.
int	mars_task_queue_push (uint64_t queue_ea, const void *data)
	[MPU] Pushes the data specified into the task queue. (Blocking)
int	mars_task_queue_push_begin (uint64_t queue_ea, const void *data, uint32_t tag)
	[MPU] Begins push operation on a task queue. (Blocking)
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 (uint64_t queue_ea, const void *data)
	[MPU] Pushes the data specified into the task queue. (Non-Blocking)
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. (Non-Blocking)
int	mars_task_queue_pop (uint64_t queue_ea, void *data)
	[MPU] Pops data from a task queue. (Blocking)
int	mars_task_queue_pop_begin (uint64_t queue_ea, void *data, uint32_t tag)
	[MPU] Begins pop operation on a task queue. (Blocking)
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 (uint64_t queue_ea, void *data)
	[MPU] Pops data from a task queue. (Non-Blocking)
int	mars_task_queue_try_pop_begin (uint64_t queue_ea, void *data, uint32_t tag)
	[MPU] Begins pop operation on a task queue. (Non-Blocking)
int	mars_task_queue_peek (uint64_t queue_ea, void *data)
	[MPU] Pops data from a task queue without removing it. (Blocking)
int	mars_task_queue_peek_begin (uint64_t queue_ea, void *data, uint32_t tag)
	[MPU] Begins peek operation on a task queue. (Blocking)
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 (uint64_t queue_ea, void *data)
	[MPU] Pops data from a task queue without removing it. (Non-Blocking)
int	mars_task_queue_try_peek_begin (uint64_t queue_ea, void *data, uint32_t tag)
	[MPU] Begins peek operation on a task queue. (Non-Blocking)
Variables
mars_task_queue	MARS_TASK_QUEUE_ALIGN
	MARS task queue structure.

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_initialize	(	struct mars_context *	mars,
		struct mars_task_queue *	queue,
		void *	buffer,
		uint32_t	size,
		uint32_t	depth,
		uint8_t	direction
	)

[host] Initializes a task queue.

Parameters:

`[in]`	mars	- pointer to initialized MARS context
`[out]`	queue	- pointer to queue instance to initialize
`[in]`	buffer	- pointer to data buffer managed by queue
`[in]`	size	- size of each data entry in data buffer
`[in]`	depth	- maximum number of data entries in data buffer
`[in]`	direction	- direction of the event flag

Returns:: MARS_SUCCESS - successfully initialized queue
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_PARAMS - size is not multiple of 16 bytes or is greater than 16KB maximum
MARS_ERROR_PARAMS - depth exceeds allowed limit
MARS_ERROR_PARAMS - invalid direction specified

int mars_task_queue_count	(	struct mars_task_queue *	queue,
		uint32_t *	count
	)

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

Parameters:

`[in]`	queue	- pointer to 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 ( struct mars_task_queue * queue )

[host] Clears the items in the task queue.

Parameters:

[in] queue - pointer to initialized queue instance

Returns:: MARS_SUCCESS - successfully cleared queue
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly

int mars_task_queue_push	(	struct mars_task_queue *	queue,
		const void *	data
	)

[host] Pushes the data specified into the task queue. (Blocking)

Parameters:

`[in]`	queue	- pointer to initialized queue instance
`[in]`	data	- address of data to be pushed into queue

Returns:: MARS_SUCCESS - successfully pushed data into queue
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_STATE - invalid direction

int mars_task_queue_try_push	(	struct mars_task_queue *	queue,
		const void *	data
	)

[host] Pushes the data specified into the task queue. (Non-Blocking)

Parameters:

`[in]`	queue	- pointer to initialized queue instance
`[in]`	data	- address of data to be pushed into queue

Returns:: MARS_SUCCESS - successfully pushed data into queue
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_BUSY - queue is full
MARS_ERROR_STATE - invalid direction

int mars_task_queue_pop	(	struct mars_task_queue *	queue,
		void *	data
	)

[host] Pops data from a task queue. (Blocking)

Parameters:

`[in]`	queue	- pointer to initialized task instance
`[in]`	data	- address of data to be popped from queue

Returns:: MARS_SUCCESS - successfully received event
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_STATE - invalid direction

int mars_task_queue_try_pop	(	struct mars_task_queue *	queue,
		void *	data
	)

[host] Pops data from a task queue. (Non-Blocking)

Parameters:

`[in]`	queue	- pointer to initialized task instance
`[in]`	data	- address of data to be popped from queue

Returns:: MARS_SUCCESS - successfully received event
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_BUSY - queue is empty
MARS_ERROR_STATE - invalid direction

int mars_task_queue_peek	(	struct mars_task_queue *	queue,
		void *	data
	)

[host] Pops data from a task queue without removing it. (Blocking)

Parameters:

`[in]`	queue	- pointer to initialized task instance
`[in]`	data	- address of data to be popped from queue

Returns:: MARS_SUCCESS - successfully received event
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
MARS_ERROR_STATE - invalid direction

int mars_task_queue_try_peek	(	struct mars_task_queue *	queue,
		void *	data
	)

[host] Pops data from a task queue without removing it. (Non-Blocking)

Parameters:

`[in]`	queue	- pointer to initialized task instance
`[in]`	data	- address of data to be popped from queue

Returns:: MARS_SUCCESS - successfully received event
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_BUSY - queue is empty
MARS_ERROR_STATE - invalid direction

int mars_task_queue_initialize	(	uint64_t	queue_ea,
		uint64_t	buffer_ea,
		uint32_t	size,
		uint32_t	depth,
		uint8_t	direction
	)

[MPU] Initializes a task queue.

Parameters:

`[out]`	queue_ea	- ea of queue instance to initialize
`[in]`	buffer_ea	- ea of data buffer
`[in]`	size	- size of each data entry in data buffer
`[in]`	depth	- maximum number of data entries in data buffer
`[in]`	direction	- direction of the queue

Returns:: MARS_SUCCESS - successfully initialized queue
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_PARAMS - size is not multiple of 16 bytes or is greater than 16KB maximum
MARS_ERROR_PARAMS - depth exceeds allowed limit
MARS_ERROR_PARAMS - invalid direction specified

int mars_task_queue_count	(	uint64_t	queue_ea,
		uint32_t *	count
	)

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

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 )

[MPU] Clears the items in the task queue.

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
	)

[MPU] Pushes the data specified into the task queue. (Blocking)

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

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

[MPU] Begins push operation on a task queue. (Blocking)

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

int mars_task_queue_push_end	(	uint64_t	queue_ea,
		uint32_t	tag
	)

[MPU] Completes push operation on a task queue.

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	(	uint64_t	queue_ea,
		const void *	data
	)

[MPU] Pushes the data specified into the task queue. (Non-Blocking)

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_try_push_begin	(	uint64_t	queue_ea,
		const void *	data,
		uint32_t	tag
	)

[MPU] Begins push operation on a task queue. (Non-Blocking)

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	(	uint64_t	queue_ea,
		void *	data
	)

[MPU] Pops data from a task queue. (Blocking)

Parameters:

`[in]`	queue_ea	- ea of initialized queue instance
`[in]`	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

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

[MPU] Begins pop operation on a task queue. (Blocking)

Parameters:

`[in]`	queue_ea	- ea of initialized queue instance
`[in]`	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

int mars_task_queue_pop_end	(	uint64_t	queue_ea,
		uint32_t	tag
	)

[MPU] Completes pop operation on a task queue.

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	(	uint64_t	queue_ea,
		void *	data
	)

[MPU] Pops data from a task queue. (Non-Blocking)

Parameters:

`[in]`	queue_ea	- ea of initialized queue instance
`[in]`	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_try_pop_begin	(	uint64_t	queue_ea,
		void *	data,
		uint32_t	tag
	)

[MPU] Begins pop operation on a task queue. (Non-Blocking)

Parameters:

`[in]`	queue_ea	- ea of initialized queue instance
`[in]`	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	(	uint64_t	queue_ea,
		void *	data
	)

[MPU] Pops data from a task queue without removing it. (Blocking)

Parameters:

`[in]`	queue_ea	- ea of initialized queue instance
`[in]`	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

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

[MPU] Begins peek operation on a task queue. (Blocking)

Parameters:

`[in]`	queue_ea	- ea of initialized queue instance
`[in]`	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

int mars_task_queue_peek_end	(	uint64_t	queue_ea,
		uint32_t	tag
	)

[MPU] Completes peek operation on a task queue.

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	(	uint64_t	queue_ea,
		void *	data
	)

[MPU] Pops data from a task queue without removing it. (Non-Blocking)

Parameters:

`[in]`	queue_ea	- ea of initialized queue instance
`[in]`	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

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

[MPU] Begins peek operation on a task queue. (Non-Blocking)

Parameters:

`[in]`	queue_ea	- ea of initialized queue instance
`[in]`	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

Variable Documentation

struct mars_task_queue MARS_TASK_QUEUE_ALIGN

MARS task queue structure.

An instance of this structure must be created when using any of the MARS queue API.

If allocating a memory area for this structure, make sure to allocate a memory area that is aligned to MARS_TASK_QUEUE_ALIGN bytes and of size MARS_TASK_QUEUE_SIZE bytes.

Generated on Wed Jun 25 11:07:27 2008 for MARS by

1.5.2

Task Queue API [Task Synchronization API]

Files

Data Structures

Defines

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation

Task Queue API
[Task Synchronization API]