Task Barrier API
[Task Synchronization API]

Files
file	mars_task_barrier_types.h
	MARS Task Barrier Types.
file	mars_task_barrier.h
	[host] MARS Task Barrier API
file	mars_task_barrier.h
	[MPU] MARS Task Barrier API
Data Structures
struct	mars_task_barrier
	MARS task barrier structure. More...
Defines
#define	MARS_TASK_BARRIER_SIZE   128
	Size of task barrier structure.
#define	MARS_TASK_BARRIER_ALIGN   128
	Alignment of task barrier structure.
#define	MARS_TASK_BARRIER_ALIGN_MASK   0x7f
	Alignment mask of task barrier structure.
#define	MARS_TASK_BARRIER_WAIT_MAX   53
	Maximum tasks allowed for single barrier.
Functions
int	mars_task_barrier_initialize (struct mars_context *mars, struct mars_task_barrier *barrier, uint32_t total)
	[host] Initializes a task barrier.
int	mars_task_barrier_initialize (uint64_t barrier_ea, uint32_t total)
	[MPU] Initializes a task barrier.
int	mars_task_barrier_notify (uint64_t barrier_ea)
	[MPU] Notifies a task barrier.
int	mars_task_barrier_wait (uint64_t barrier_ea)
	[MPU] Waits on a task barrier. (Blocking)
int	mars_task_barrier_try_wait (uint64_t barrier_ea)
	[MPU] Waits on a task barrier. (Non-Blocking)
Variables
mars_task_barrier	MARS_TASK_BARRIER_ALIGN
	MARS task barrier structure.

---

Detailed Description

The MARS task barrier allows the synchronization of multiple tasks. At barrier initialization, the total number of tasks that need to be synchronized is specified. When each task arrives at the barrier, it will notify the barrier and enter a waiting state until the barrier is released. When the total number of tasks specified at initialization have arrived at the barrier and notified it, the barrier is released and all tasks are returned to the ready state to be scheduled to run once again.

---

Function Documentation

int mars_task_barrier_initialize	(	struct mars_context *	mars,
		struct mars_task_barrier *	barrier,
		uint32_t	total
	)

[host] Initializes a task barrier.

Parameters:

[in]	mars	- pointer to initialized MARS context
[out]	barrier	- pointer to barrier instance to initialize
[in]	total	- number of notifies before barrier released

Returns:

MARS_SUCCESS - successfully initialized barrier
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - instance not properly aligned
MARS_ERROR_PARAMS - total exceeds allowed limit

int mars_task_barrier_initialize	(	uint64_t	barrier_ea,
		uint32_t	total
	)

[MPU] Initializes a task barrier.

Parameters:

[out]	barrier_ea	- ea of barrier instance to initialize
[in]	total	- number of notifies before barrier released

Returns:

MARS_SUCCESS - successfully initialized barrier
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not properly aligned
MARS_ERROR_PARAMS - total exceeds allowed limit

int mars_task_barrier_notify

(

uint64_t

barrier_ea

)

[MPU] Notifies a task barrier.

Parameters:

[in]

barrier_ea

- ea of initialized barrier instance

Returns:

MARS_SUCCESS - successfully notified barrier
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not properly aligned
MARS_ERROR_LIMIT - total notifications already received

int mars_task_barrier_wait

(

uint64_t

barrier_ea

)

[MPU] Waits on a task barrier. (Blocking)

Parameters:

[in]

barrier_ea

- ea of initialized barrier instance

Returns:

MARS_SUCCESS - barrier is released
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not properly aligned
MARS_ERROR_LIMIT - maximum number of tasks already waiting
MARS_ERROR_FORMAT - no context save area specified

int mars_task_barrier_try_wait

(

uint64_t

barrier_ea

)

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

Parameters:

[in]

barrier_ea

- ea of initialized barrier instance

Returns:

MARS_SUCCESS - barrier is released
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not properly aligned
MARS_ERROR_BUSY - not all notifications arrived yet

---

Variable Documentation

struct mars_task_barrier MARS_TASK_BARRIER_ALIGN

MARS task barrier structure.

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

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

---