Task Semaphore API
[Task Synchronization API]

Files
file	mars_task_semaphore_types.h
	MARS Task Semaphore Types.
file	mars_task_semaphore.h
	[host] MARS Task Semaphore API
file	mars_task_semaphore.h
	[MPU] MARS Task Semaphore API
Data Structures
struct	mars_task_semaphore
	MARS task semaphore structure. More...
Defines
#define	MARS_TASK_SEMAPHORE_SIZE   128
	Size of task semaphore structure.
#define	MARS_TASK_SEMAPHORE_ALIGN   128
	Alignment of task semaphore structure.
#define	MARS_TASK_SEMAPHORE_ALIGN_MASK   0x7f
	Alignment mask of task semaphore structure.
#define	MARS_TASK_SEMAPHORE_WAIT_MAX   55
	Maximum task accesses allowed for single semaphore.
Functions
int	mars_task_semaphore_initialize (struct mars_context *mars, struct mars_task_semaphore *semaphore, int32_t count)
	[host] Initializes a task semaphore.
int	mars_task_semaphore_initialize (uint64_t semaphore_ea, int32_t count)
	[MPU] Initializes a task semaphore.
int	mars_task_semaphore_acquire (uint64_t semaphore_ea)
	[MPU] Acquires a task semaphore. (Blocking)
int	mars_task_semaphore_release (uint64_t semaphore_ea)
	[MPU] Releases a task semaphore.
Variables
mars_task_semaphore	MARS_TASK_SEMAPHORE_ALIGN
	MARS task semaphore structure.

---

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_initialize	(	struct mars_context *	mars,
		struct mars_task_semaphore *	semaphore,
		int32_t	count
	)

[host] Initializes a task semaphore.

Parameters:

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

Returns:

MARS_SUCCESS - successfully initialized semaphore
MARS_ERROR_NULL - null pointer is specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_PARAMS - count exceeds allowed limit

int mars_task_semaphore_initialize	(	uint64_t	semaphore_ea,
		int32_t	count
	)

[MPU] Initializes a task semaphore.

Parameters:

[out]	semaphore_ea	- ea of semaphore instance to initialize
[in]	count	- initial number of task accesses allowed

Returns:

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

int mars_task_semaphore_acquire

(

uint64_t

semaphore_ea

)

[MPU] Acquires a task semaphore. (Blocking)

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.

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

---

Variable Documentation

struct mars_task_semaphore MARS_TASK_SEMAPHORE_ALIGN

MARS task semaphore structure.

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

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

---