Task Event Flag API
[Task Synchronization API]

Files
file	mars_task_event_flag_types.h
	MARS Task Event Flag Types.
file	mars_task_event_flag.h
	[host] MARS Task Event Flag API
file	mars_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_SIZE   128
	Size of task event flag structure.
#define	MARS_TASK_EVENT_FLAG_ALIGN   128
	Alignment of task event flag structure.
#define	MARS_TASK_EVENT_FLAG_ALIGN_MASK   0x7f
	Alignment mask of task event flag structure.
#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_initialize (struct mars_context *mars, struct mars_task_event_flag *event_flag, uint8_t direction, uint8_t clear_mode)
	[host] Initializes 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)
	[host] Waits on a task event flag. (Blocking)
int	mars_task_event_flag_try_wait (struct mars_task_event_flag *event_flag, uint32_t mask, uint8_t mask_mode)
	[host] Waits on a task event flag. (Non-Blocking)
int	mars_task_event_flag_initialize (uint64_t event_flag_ea, uint8_t direction, uint8_t clear_mode)
	[MPU] Initializes 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)
	[MPU] Waits on a task event flag. (Blocking)
int	mars_task_event_flag_try_wait (uint64_t event_flag_ea, uint32_t mask, uint8_t mask_mode)
	[MPU] Waits on a task event flag. (Non-Blocking)
Variables
mars_task_event_flag	MARS_TASK_EVENT_FLAG_ALIGN
	MARS task event flag structure.

---

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_initialize	(	struct mars_context *	mars,
		struct mars_task_event_flag *	event_flag,
		uint8_t	direction,
		uint8_t	clear_mode
	)

[host] Initializes a task event flag.

Parameters:

[in]	mars	- pointer to initialized MARS context
[out]	event_flag	- pointer to event flag instance to initialize
[in]	direction	- direction of the event flag
[in]	clear_mode	- behavior of how the event flag is cleared

Returns:

MARS_SUCCESS - successfully initialized event flag
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_PARAMS - invalid direction or clear mode specified

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.

Parameters:

[in]	event_flag	- pointer to initialized 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.

Parameters:

[in]	event_flag	- pointer to initialized 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
	)

[host] Waits on a task event flag. (Blocking)

Parameters:

[in]	event_flag	- pointer to initialized event flag instance
[in]	mask	- bit mask to test event flag bits against
[in]	mask_mode	- specifies how to mask bits (AND, OR)

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_LIMIT - exceeded limit of max waiting tasks

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

[host] Waits on a task event flag. (Non-Blocking)

Parameters:

[in]	event_flag	- pointer to initialized event flag instance
[in]	mask	- bit mask to test event flag bits against
[in]	mask_mode	- specifies how to mask bits (AND, OR)

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_initialize	(	uint64_t	event_flag_ea,
		uint8_t	direction,
		uint8_t	clear_mode
	)

[MPU] Initializes a task event flag.

Parameters:

[out]	event_flag_ea	- ea of event flag instance to initialize
[in]	direction	- direction of the event flag
[in]	clear_mode	- behavior of how the event flag is cleared

Returns:

MARS_SUCCESS - successfully initialized event flag
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_PARAMS - invalid direction or clear mode specified

int mars_task_event_flag_clear	(	uint64_t	event_flag_ea,
		uint32_t	bits
	)

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

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.

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
	)

[MPU] Waits on a task event flag. (Blocking)

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)

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
	)

[MPU] Waits on a task event flag. (Non-Blocking)

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)

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

---

Variable Documentation

struct mars_task_event_flag MARS_TASK_EVENT_FLAG_ALIGN

MARS task event flag structure.

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

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

---