Task Barrier API
[Task Synchronization API]

Files
file	task_barrier_types.h
	[host/MPU] MARS Task Barrier Types
file	task_barrier.h
	[host] MARS Task Barrier API
file	task_barrier.h
	[MPU] MARS Task Barrier API
Defines
#define	MARS_TASK_BARRIER_WAIT_MAX   25
	Maximum tasks allowed for single barrier.
Functions
int	mars_task_barrier_create (struct mars_context *mars, uint64_t *barrier_ea, uint32_t total)
	[host] Creates a task barrier.
int	mars_task_barrier_destroy (uint64_t barrier_ea)
	[host] Destroys a task barrier.
int	mars_task_barrier_notify (uint64_t barrier_ea)
	[MPU] Notifies a task barrier. (Task Switch Call)
int	mars_task_barrier_try_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. (Task Switch Call)
int	mars_task_barrier_try_wait (uint64_t barrier_ea)
	[MPU] Waits on a task barrier.

---

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_create	(	struct mars_context *	mars,
		uint64_t *	barrier_ea,
		uint32_t	total
	)

[host] Creates a task barrier.

This function will allocate an instance of the task barrier. The barrier allows for tasks within the barrier group to wait until all tasks arrive at some synchronization point and notify the barrier. All tasks included in the barrier group should call the notify and wait in pairs.

Key Parameters:

total

• Specify total number of tasks that will be associated with this barrier.
• Total must be a value between 1 and MARS_TASK_BARRIER_WAIT_MAX.

Parameters:

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

Returns:

MARS_SUCCESS - successfully created barrier
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - total is 0 or exceeds allowed limit

int mars_task_barrier_destroy

(

uint64_t

barrier_ea

)

[host] Destroys a task barrier.

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

Parameters:

[in]

barrier_ea

- ea of barrier instance

Returns:

MARS_SUCCESS - successfully destroyed barrier
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_ALIGN - ea not properly aligned
MARS_ERROR_STATE - tasks still waiting

int mars_task_barrier_notify

(

uint64_t

barrier_ea

)

[MPU] Notifies a task barrier. (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 function notifies the barrier that the caller task has reached the synchronization point. Once a task reaches the synchronization point and notifies the barrier, it may handle other processing before calling the required mars_task_barrier_wait.

If all tasks from the previous barrier cycle have not reached the synchronization point and notified/waited on the barrier yet, the caller task will enter a waiting state until the previous barrier cycle is released.

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 - maximum number of tasks already waiting
MARS_ERROR_FORMAT - no context save area specified

int mars_task_barrier_try_notify

(

uint64_t

barrier_ea

)

[MPU] Notifies a task barrier.

This function notifies the barrier that the caller task has reached the synchronization point. Once a task reaches the synchronization point and notifies the barrier, it may handle other processing before calling the required mars_task_barrier_wait.

If all tasks from the previous barrier cycle have not reached the synchronization point and notified the barrier yet, this function will return immediately with MARS_ERROR_BUSY.

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_BUSY - previous waits have not completed

int mars_task_barrier_wait

(

uint64_t

barrier_ea

)

[MPU] Waits on a task barrier. (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 function should be called after the caller task has previously called mars_task_barrier_notify. This function should be called when the task that reached the synchronization point is ready to wait for others to arrive at the synchronization point.

If not all tasks associated with the barrier have reached the synchronization point and notified the barrier at the time of this call, the caller task will enter a waiting state until all notifications are received from the other tasks and the barrier is released.

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.

This function should be called after the caller task has previously called mars_task_barrier_notify. This function should be called when the task that reached the synchronization point is ready to wait for others to arrive at the synchronization point.

If not all tasks associated with the barrier have reached the synchronization point and notified the barrier at the time of this call, this function will return immediately with MARS_ERROR_BUSY.

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