Task Semaphore API
[Task Synchronization API]

Files
file	task_semaphore_types.h
	[host/MPU] MARS Task Semaphore Types
file	task_semaphore.h
	[host] MARS Task Semaphore API
file	task_semaphore.h
	[MPU] MARS Task Semaphore API
Defines
#define	MARS_TASK_SEMAPHORE_WAIT_MAX   54
	Maximum task accesses allowed for single semaphore.
Functions
int	mars_task_semaphore_create (struct mars_context *mars, uint64_t *semaphore_ea, int32_t count)
	[host] Creates a task semaphore.
int	mars_task_semaphore_destroy (uint64_t semaphore_ea)
	[host] Destroys a task semaphore.
int	mars_task_semaphore_acquire (uint64_t semaphore_ea)
	[MPU] Acquires a task semaphore. (Task Switch Call)
int	mars_task_semaphore_release (uint64_t semaphore_ea)
	[MPU] Releases a task semaphore.

---

Detailed Description

The MARS task semaphore allows for synchronization between multiple tasks by preventing simultaneous access of some shared resource. The semaphore can be specified with how many simultaneous tasks can access the semaphore at any given time.

Whenever a task wants to access some semaphore protected shared resource, it must first request to acquire the semaphore access (P operation) of the semaphore. When done accessing the shared resource it must then release access (V operation) of the semaphore. If attempting to request a a semaphore and other tasks have already requested the total number of allowed accesses, the task will transition to the waiting state until some other tasks release the semaphore and access is obtained.

---

Function Documentation

int mars_task_semaphore_create	(	struct mars_context *	mars,
		uint64_t *	semaphore_ea,
		int32_t	count
	)

[host] Creates a task semaphore.

This function will allocate an instance of the task semaphore. The semaphore allows for tasks to wait until a semaphore can be obtained. The semaphore should be used in pairs with calls to acquire and release.

Key Parameters:

count

• Specify the total number of entities that can have access to the semaphore simultaneously.
• Must not be greater than MARS_TASK_SEMAPHORE_WAIT_MAX.

Parameters:

[in]	mars	- pointer to MARS context
[out]	semaphore_ea	- ea of semaphore instance
[in]	count	- initial number of task accesses allowed

Returns:

MARS_SUCCESS - successfully created semaphore
MARS_ERROR_NULL - null pointer is specified
MARS_ERROR_PARAMS - count exceeds allowed limit

int mars_task_semaphore_destroy

(

uint64_t

semaphore_ea

)

[host] Destroys a task semaphore.

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

Parameters:

[in]

semaphore_ea

- ea of semaphore instance

Returns:

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

int mars_task_semaphore_acquire

(

uint64_t

semaphore_ea

)

[MPU] Acquires a task semaphore. (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 will attempt to acquire the semaphore. If the total number of current accesses of the semaphore is greater than or equal to the total allowed specified at semaphore creation, the caller task will enter a waiting state until some other tasks release the semaphore and becomes available for acquiring.

Parameters:

[in]

semaphore_ea

- ea of initialized semaphore instance

Returns:

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

int mars_task_semaphore_release

(

uint64_t

semaphore_ea

)

[MPU] Releases a task semaphore.

This function will release a previously acquired semaphore. If their are other tasks currently waiting to acquire a semaphore, calling this function will resume a waiting task to allow it to acquire the semaphore.

Parameters:

[in]

semaphore_ea

- ea of initialized semaphore instance

Returns:

MARS_SUCCESS - successfully released semaphore
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly