Task Event Flag API
[Task Synchronization API]

Files
file	task_event_flag_types.h
	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
Data Structures
struct	mars_task_event_flag
	MARS task event flag structure. More...
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, struct mars_task_event_flag **event_flag, uint8_t direction, uint8_t clear_mode)
	[host] Creates a task event flag.
int	mars_task_event_flag_destroy (struct mars_task_event_flag *event_flag)
	[host] Destroys a task event flag.
int	mars_task_event_flag_clear (struct mars_task_event_flag *event_flag, uint32_t bits)
	[host] Clears the bits specified in the task event flag.
int	mars_task_event_flag_set (struct mars_task_event_flag *event_flag, uint32_t bits)
	[host] Sets the bits specified in the task event flag.
int	mars_task_event_flag_wait (struct mars_task_event_flag *event_flag, uint32_t mask, uint8_t mask_mode, uint32_t *bits)
	[host] Waits on a task event flag.
int	mars_task_event_flag_try_wait (struct mars_task_event_flag *event_flag, uint32_t mask, uint8_t mask_mode, uint32_t *bits)
	[host] Waits on a task event flag.
int	mars_task_event_flag_clear (uint64_t event_flag_ea, uint32_t bits)
	[MPU] Clears the bits specified in the task event flag.
int	mars_task_event_flag_set (uint64_t event_flag_ea, uint32_t bits)
	[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)
	[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)
	[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,
		struct mars_task_event_flag **	event_flag,
		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

• Specify the communication direction of the event flag.
• Must be one of MARS_TASK_EVENT_FLAG_HOST_TO_MPU, MARS_TASK_EVENT_FLAG_MPU_TO_HOST, MARS_TASK_EVENT_FLAG_MPU_TO_MPU.

clear_mode

• Specify when the event flag is cleared.
• Specify MARS_TASK_EVENT_FLAG_CLEAR_AUTO to have event flag bits cleared automatically when a task waiting on the event flag bits has been notified of the event.
• Specify MARS_TASK_EVENT_FLAG_CLEAR_MANUAL to have the event flag bits remain set until the user manually clears them through mars_task_event_flag_clear.

Parameters:

[in]	mars	- pointer to MARS context
[out]	event_flag	- address of pointer to 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

(

struct mars_task_event_flag *

event_flag

)

[host] Destroys a task event flag.

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

Parameters:

[in]

event_flag

- pointer to event flag instance

Returns:

MARS_SUCCESS - successfully destroyed event flag
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not properly aligned

int mars_task_event_flag_clear	(	struct mars_task_event_flag *	event_flag,
		uint32_t	bits
	)

[host] 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	- pointer to event flag instance
[in]	bits	- bits to clear

Returns:

MARS_SUCCESS - successfully cleared event flag bits
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly

int mars_task_event_flag_set	(	struct mars_task_event_flag *	event_flag,
		uint32_t	bits
	)

[host] 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	- pointer to event flag instance
[in]	bits	- bits to set

Returns:

MARS_SUCCESS - successfully cleared event flag bits
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_STATE - invalid direction

int mars_task_event_flag_wait	(	struct mars_task_event_flag *	event_flag,
		uint32_t	mask,
		uint8_t	mask_mode,
		uint32_t *	bits
	)

[host] Waits on a task event flag.

This call will block 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).

Parameters:

[in]	event_flag	- pointer to 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 to instance to store bits upon release

Returns:

MARS_SUCCESS - successfully received event
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_PARAMS - invalid mask mode
MARS_ERROR_STATE - invalid direction

int mars_task_event_flag_try_wait	(	struct mars_task_event_flag *	event_flag,
		uint32_t	mask,
		uint8_t	mask_mode,
		uint32_t *	bits
	)

[host] Waits on a task event flag.

This call will test to see if the specified event flag condition is met without blocking and 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).

Parameters:

[in]	event_flag	- pointer to 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 to instance to store bits upon release

Returns:

MARS_SUCCESS - successfully received event
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_PARAMS - invalid mask_mode
MARS_ERROR_STATE - invalid direction
MARS_ERROR_BUSY - event not yet received

int mars_task_event_flag_clear	(	uint64_t	event_flag_ea,
		uint32_t	bits
	)

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

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

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

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 to instance to store bits upon release

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
	)

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

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 to instance to store bits upon release

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