Task Queue API
[Task Synchronization API]


Files

file  task_queue_types.h
 MARS Task Queue Types.
file  task_queue.h
 [host] MARS Task Queue Flag API
file  task_queue.h
 [MPU] MARS Task Queue API

Data Structures

struct  mars_task_queue
 MARS task queue structure. More...

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, struct mars_task_queue **queue, uint32_t size, uint32_t depth, uint8_t direction)
 [host] Creates a task queue.
int mars_task_queue_destroy (struct mars_task_queue *queue)
 [host] Destroys a task queue.
int mars_task_queue_count (struct mars_task_queue *queue, uint32_t *count)
 [host] Returns the number of data items in the task queue.
int mars_task_queue_clear (struct mars_task_queue *queue)
 [host] Clears the data 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.
int mars_task_queue_try_push (struct mars_task_queue *queue, const void *data)
 [host] Pushes the data specified into the task queue.
int mars_task_queue_pop (struct mars_task_queue *queue, void *data)
 [host] Pops data from a task queue.
int mars_task_queue_try_pop (struct mars_task_queue *queue, void *data)
 [host] Pops data from a task queue.
int mars_task_queue_peek (struct mars_task_queue *queue, void *data)
 [host] Pops data from a task queue without removing it.
int mars_task_queue_try_peek (struct mars_task_queue *queue, void *data)
 [host] Pops data from a task queue without removing it.
int mars_task_queue_count (uint64_t queue_ea, uint32_t *count)
 [MPU] Returns the number of data items in the task queue.
int mars_task_queue_clear (uint64_t queue_ea)
 [MPU] Clears the data 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. (Task Switch Call)
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 (uint64_t queue_ea, const void *data)
 [MPU] Pushes the data specified into the 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 (uint64_t queue_ea, void *data)
 [MPU] Pops data from a task queue. (Task Switch Call)
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 (uint64_t queue_ea, void *data)
 [MPU] Pops data from 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 (uint64_t queue_ea, void *data)
 [MPU] Pops data from a task queue without removing it. (Task Switch Call)
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 (uint64_t queue_ea, void *data)
 [MPU] Pops data from a task queue without removing it.
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,
struct mars_task_queue **  queue,
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

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

Parameters:
[in] mars - pointer to MARS context
[out] queue - address of pointer to 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 - depth exceeds allowed limit
MARS_ERROR_PARAMS - invalid direction specified

int mars_task_queue_destroy ( struct mars_task_queue *  queue  ) 

[host] Destroys a task queue.

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

Parameters:
[in] queue - pointer to queue instance
Returns:
MARS_SUCCESS - successfully destroyed queue
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not properly aligned

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

[host] 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 - pointer to queue instance
[out] count - pointer to variable to store return count
Returns:
MARS_SUCCESS - successfully returned count
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly

int mars_task_queue_clear ( struct mars_task_queue *  queue  ) 

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

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

Parameters:
[in] queue - pointer to 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.

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

If the queue is full at the time of this call, this function will block 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.

Parameters:
[in] queue - pointer to 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.

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

If the queue is full at the time of this call, this function will not block and returns immediately 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.

Parameters:
[in] queue - pointer to 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.

This function will pop data from the queue.

If the queue is empty at the time of this call, this function will block until there is data to be popped from the queue.

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.

Parameters:
[in] queue - pointer to 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.

This function will pop data from the queue.

If the queue is empty at the time of this call, this function will not block and returns immediately 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.

Parameters:
[in] queue - pointer to 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.

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 block until there is data to be retrieved from the queue.

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.

Parameters:
[in] queue - pointer to 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_peek ( struct mars_task_queue *  queue,
void *  data 
)

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

This function will retrieve data from the queue.

If the queue is empty at the time of this call, this function will not block and returns immediately 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.

Parameters:
[in] queue - pointer to 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_count ( uint64_t  queue_ea,
uint32_t *  count 
)

[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  ) 

[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 
)

[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 6.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.

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_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 6.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.

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

[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.

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.

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.

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

[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 6.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.

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
MARS_ERROR_FORMAT - no context save area specified

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 6.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.

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

[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.

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.

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.

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. (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 6.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.

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
MARS_ERROR_FORMAT - no context save area specified

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 6.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.

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

[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.

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_BUSY - queue is empty
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.

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.

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_BUSY - queue is empty
MARS_ERROR_STATE - invalid direction
MARS_ERROR_PARAMS - invalid tag

Generated on Thu Oct 23 14:11:55 2008 for MARS by  doxygen 1.5.5