Task Event Flag API
[Task Synchronization API]


Files

file  task_event_flag_types.h
 [host/MPU] MARS Task Event Flag Types
file  task_event_flag.h
 [host] MARS Task Event Flag API
file  task_event_flag.h
 [MPU] MARS Task Event Flag API

Defines

#define MARS_TASK_EVENT_FLAG_HOST_TO_MPU   0x10
 Event flag direction from PPU to SPU.
#define MARS_TASK_EVENT_FLAG_MPU_TO_HOST   0x11
 Event flag direction from SPU to PPU.
#define MARS_TASK_EVENT_FLAG_MPU_TO_MPU   0x12
 Event flag direction from SPU to SPU.
#define MARS_TASK_EVENT_FLAG_CLEAR_AUTO   0x20
 Event flag clear mode automatic.
#define MARS_TASK_EVENT_FLAG_CLEAR_MANUAL   0x21
 Event flag clear mode manual.
#define MARS_TASK_EVENT_FLAG_MASK_OR   0x30
 Event flag mask mode bitwise OR.
#define MARS_TASK_EVENT_FLAG_MASK_AND   0x31
 Event flag mask mode bitwise AND.
#define MARS_TASK_EVENT_FLAG_WAIT_MAX   15
 Maximum tasks allowed to wait on a single event flag.

Functions

int mars_task_event_flag_create (struct mars_context *mars, uint64_t *event_flag_ea, uint8_t direction, uint8_t clear_mode)
 [host] Creates a task event flag.
int mars_task_event_flag_destroy (uint64_t event_flag_ea)
 [host] Destroys a task event flag.
int mars_task_event_flag_clear (uint64_t event_flag_ea, uint32_t bits)
 [host/MPU] Clears the bits specified in the task event flag.
int mars_task_event_flag_set (uint64_t event_flag_ea, uint32_t bits)
 [host/MPU] Sets the bits specified in the task event flag.
int mars_task_event_flag_wait (uint64_t event_flag_ea, uint32_t mask, uint8_t mask_mode, uint32_t *bits)
 [host/MPU] Waits on a task event flag. (Task Switch Call)
int mars_task_event_flag_try_wait (uint64_t event_flag_ea, uint32_t mask, uint8_t mask_mode, uint32_t *bits)
 [host/MPU] Waits on a task event flag.

Detailed Description

The MARS task event flag allows the synchronization between multiple tasks and the host program by sending and receiving 32-bit event flags between one another.

The event flags can be sent from host program to MARS task or vice versa, as well as between multiple MARS tasks. While waiting on certain event flags to be received, the task transitions to the waiting state until the event flag is received.


Function Documentation

int mars_task_event_flag_create ( struct mars_context *  mars,
uint64_t *  event_flag_ea,
uint8_t  direction,
uint8_t  clear_mode 
)

[host] Creates a task event flag.

This function will allocate an instance of the task event flag. The event flag allows for tasks to wait on specific events. The event flag should be used in pairs with calls to set an event flag and wait for an event flag.

Key Parameters:

direction

clear_mode

Parameters:
[in] mars - pointer to MARS context
[out] event_flag_ea - ea of event flag instance
[in] direction - direction of the event flag
[in] clear_mode - behavior of how the event flag is cleared
Returns:
MARS_SUCCESS - successfully created event flag
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - invalid direction or clear mode specified

int mars_task_event_flag_destroy ( uint64_t  event_flag_ea  ) 

[host] Destroys a task event flag.

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

Parameters:
[in] event_flag_ea - ea of event flag instance
Returns:
MARS_SUCCESS - successfully destroyed event flag
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - ea not properly aligned

int mars_task_event_flag_clear ( uint64_t  event_flag_ea,
uint32_t  bits 
)

[host/MPU] Clears the bits specified in the task event flag.

This function will clear all bits currently set in the event flag. Tasks waiting on some events will remain in the waiting state.

Key Parameters:

bits

  • Specify only the bits you want to be cleared from the event flag bits.

Parameters:
[in] event_flag_ea - ea of initialized event flag instance
[in] bits - bits to clear
Returns:
MARS_SUCCESS - successfully cleared event flag bits
MARS_ERROR_NULL - ea is 0

MARS_ERROR_ALIGN - ea not aligned properly

int mars_task_event_flag_set ( uint64_t  event_flag_ea,
uint32_t  bits 
)

[host/MPU] Sets the bits specified in the task event flag.

This function will set the bits specified. The bits are OR'd with bits already set in the event flag at the time of this call. If there are any tasks in the waiting state, and this call satisfies the release condition of those tasks, all those tasks will be returned to the ready state.

Key Parameters:

bits

  • Specify only the bits you want to set in the event flag bits.

Parameters:
[in] event_flag_ea - ea of initialized event flag instance
[in] bits - bits to set
Returns:
MARS_SUCCESS - successfully cleared event flag bits
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_STATE - invalid direction

int mars_task_event_flag_wait ( uint64_t  event_flag_ea,
uint32_t  mask,
uint8_t  mask_mode,
uint32_t *  bits 
)

[host/MPU] Waits on a task event flag. (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 call will put the task into a waiting state until the specified event flag condition is met.

Key Parameters:

mask

  • Specify only the bits you want to test against in the event flag bits set.
  • Whether the test condition is satisfied or not will depend on mask_mode.

mask_mode

  • Specify how to test the mask bits against the event flag bits set.
  • Specify MARS_TASK_EVENT_FLAG_MASK_OR (mask | event flag bits), so the condition is satisfied if any bits specified in mask is set in the event flag bits.
  • Specify MARS_TASK_EVENT_FLAG_MASK_AND (mask & event flag bits) so the condition is satisfied if all bits specified in mask are set in the event flag bits.

bits

  • Specify a pointer to a variable where the event flag bits can be returned.
  • The resulting bits will be the state of bits in the event flag prior to any automatic clearing of bits (if MARS_TASK_EVENT_FLAG_CLEAR_AUTO was specified at creation).
  • The returned bits are only valid when MARS_SUCCESS is returned.

Parameters:
[in] event_flag_ea - ea of initialized event flag instance
[in] mask - bit mask to test event flag bits against
[in] mask_mode - specifies how to mask bits (AND, OR)
[out] bits - pointer of instance to return bits state
Returns:
MARS_SUCCESS - successfully received event
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_PARAMS - invalid mask_mode
MARS_ERROR_STATE - invalid direction
MARS_ERROR_LIMIT - exceeded limit of max waiting tasks
MARS_ERROR_FORMAT - no context save area specified

int mars_task_event_flag_try_wait ( uint64_t  event_flag_ea,
uint32_t  mask,
uint8_t  mask_mode,
uint32_t *  bits 
)

[host/MPU] Waits on a task event flag.

This call will test to see if the specified event flag condition is met returns immediately with MARS_ERROR_BUSY if it did not.

Key Parameters:

mask

  • Specify only the bits you want to test against in the event flag bits set.
  • Whether the test condition is satisfied or not will depend on mask_mode.

mask_mode

  • Specify how to test the mask bits against the event flag bits set.
  • Specify MARS_TASK_EVENT_FLAG_MASK_OR (mask | event flag bits), so the condition is satisfied if any bits specified in mask is set in the event flag bits.
  • Specify MARS_TASK_EVENT_FLAG_MASK_AND (mask & event flag bits) so the condition is satisfied if all bits specified in mask are set in the event flag bits.

bits

  • Specify a pointer to a variable where the event flag bits can be returned.
  • The resulting bits will be the state of bits in the event flag prior to any automatic clearing of bits (if MARS_TASK_EVENT_FLAG_CLEAR_AUTO was specified at creation).
  • The returned bits are only valid when MARS_SUCCESS is returned.

Parameters:
[in] event_flag_ea - ea of initialized event flag instance
[in] mask - bit mask to test event flag bits against
[in] mask_mode - specifies how to mask bits (AND, OR)
[out] bits - pointer of instance to return bits state
Returns:
MARS_SUCCESS - successfully received event
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_PARAMS - invalid mask_mode
MARS_ERROR_STATE - invalid direction
MARS_ERROR_BUSY - event not yet received


Generated on Thu Feb 19 05:23:55 2009 for MARS by  doxygen 1.5.7.1