Mutex Management API

Files
file	mutex_types.h
	[host/MPU] MARS Mutex Types
file	mutex.h
	[host] MARS Mutex API
file	mutex.h
	[MPU] MARS Mutex API
Data Structures
struct	mars_mutex
	MARS mutex structure. More...
Functions
int	mars_mutex_create (uint64_t *mutex_ea)
	[host] Creates a mutex.
int	mars_mutex_destroy (uint64_t mutex_ea)
	[host] Destroys a mutex.
int	mars_mutex_reset (uint64_t mutex_ea)
	[host] Resets a mutex.
int	mars_mutex_lock (uint64_t mutex_ea)
	[host] Locks a mutex.
int	mars_mutex_unlock (uint64_t mutex_ea)
	[host] Unlocks a mutex.
int	mars_mutex_lock_get (uint64_t mutex_ea, struct mars_mutex *mutex)
	[MPU] Locks a mutex.
int	mars_mutex_unlock_put (uint64_t mutex_ea, struct mars_mutex *mutex)
	[MPU] Unlocks a mutex.
Variables
struct mars_mutex	MARS_MUTEX_ALIGN
	MARS mutex structure.

---

Detailed Description

A MARS mutex instance can be used to protect blocks of code from executing simultaneously whether it be in a host program or MPU program. This can be useful if some code in the host program or MPU program accesses some common resource, such as a global variable. If the block of code is protected by the MARS mutex, it is guaranteed that the protected block of code in the host program will not be executed simultaneously as any other host program thread or any other MPU program.

The MARS mutex is independent of the MARS context or MARS workload model. A MARS mutex can be used in a host program without even creating a MARS context. A MARS mutex can also be used in an MPU program independent of any MARS workload model or API. However, an MPU program independent of any MARS workload model means the user will be responsible for the loading and execution of such a program and has close to no meaning with regards to the usage of MARS.

The MARS mutex does not call into the MARS kernel's scheduler. This means that when some entity attempts to lock a mutex that is already locked, the mutex will block execution of the entity until the lock can be obtained. For the MPU-side, this means that the MARS kernel can not schedule any other workloads while a MARS mutex is waiting to lock.

Note:

If you want to make use of synchronization methods that call into the MARS kernel's scheduler and allow for other workloads to be scheduled during the time a synchronization object waits, refer to the synchronization methods provided by the various workload models.

---

Function Documentation

int mars_mutex_create

(

uint64_t *

mutex_ea

)

[host] Creates a mutex.

This function creates a mutex instance that can be locked or unlocked from both host and MPU to restrict concurrent accesses.

Parameters:

[in]

mutex_ea

- address of 64-bit address of mutex instance

Returns:

MARS_SUCCESS - successfully created mutex
MARS_ERROR_NULL - null pointer is specified
MARS_ERROR_MEMORY - instance not aligned properly

int mars_mutex_destroy

(

uint64_t

mutex_ea

)

[host] Destroys a mutex.

This function destroys a mutex instance.

Parameters:

[in]

mutex_ea

- 64-bit address of mutex instance

Returns:

MARS_SUCCESS - successfully destroyed mutex
MARS_ERROR_NULL - null pointer is specified
MARS_ERROR_ALIGN - instance not aligned properly

int mars_mutex_reset

(

uint64_t

mutex_ea

)

[host] Resets a mutex.

This function resets a mutex instance and forces it into an unlocked state regardless of whether it is locked or unlocked.

Parameters:

[in]

mutex_ea

- 64-bit address of mutex instance

Returns:

MARS_SUCCESS - successfully reset mutex
MARS_ERROR_NULL - null pointer is specified
MARS_ERROR_ALIGN - instance not aligned properly

int mars_mutex_lock

(

uint64_t

mutex_ea

)

[host] Locks a mutex.

[MPU] Locks a mutex.

This function locks a mutex and blocks other requests to lock it.

Parameters:

[in]

mutex_ea

- 64-bit address of mutex instance

Returns:

MARS_SUCCESS - successfully locked mutex
MARS_ERROR_NULL - null pointer is specified
MARS_ERROR_ALIGN - instance not aligned properly

This function locks a mutex and blocks other requests to lock it.

Parameters:

[in]

mutex_ea

- ea of mutex instance to lock

Returns:

MARS_SUCCESS - successfully locked mutex
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly

int mars_mutex_unlock

(

uint64_t

mutex_ea

)

[host] Unlocks a mutex.

[MPU] Unlocks a mutex.

This function unlocks a previously locked mutex to allow other lock requests.

Parameters:

[in]

mutex_ea

- 64-bit address of mutex instance

Returns:

MARS_SUCCESS - successfully unlocked mutex
MARS_ERROR_NULL - null pointer is specified
MARS_ERROR_ALIGN - instance not aligned properly
MARS_ERROR_STATE - instance not in locked state

This function unlocks a previously locked mutex to allow other lock requests.

Parameters:

[in]

mutex_ea

- ea of mutex instance to unlock

Returns:

MARS_SUCCESS - successfully unlocked mutex
MARS_ERROR_NULL - ea is 0
MARS_ERROR_ALIGN - ea not aligned properly
MARS_ERROR_STATE - instance not in locked state

int mars_mutex_lock_get	(	uint64_t	mutex_ea,
		struct mars_mutex *	mutex
	)

[MPU] Locks a mutex.

This function locks a mutex and blocks other requests to lock it. It also loads the mutex instance from the effective address specified into the local mutex instance.

Parameters:

[in]	mutex_ea	- ea of mutex instance to lock
[in]	mutex	- pointer to local mutex instance

Returns:

MARS_SUCCESS - successfully locked mutex
MARS_ERROR_NULL - ea is 0 or mutex is NULL
MARS_ERROR_ALIGN - ea or mutex not aligned properly

int mars_mutex_unlock_put	(	uint64_t	mutex_ea,
		struct mars_mutex *	mutex
	)

[MPU] Unlocks a mutex.

This function unlocks a previously locked mutex to allow other lock requests. It also stores the local mutex instance into the effective address specified.

Parameters:

[in]	mutex_ea	- ea of mutex instance to unlock
[in]	mutex	- pointer to local mutex instance

Returns:

MARS_SUCCESS - successfully unlocked mutex
MARS_ERROR_NULL - ea is 0 or mutex is NULL
MARS_ERROR_ALIGN - ea or mutex not aligned properly
MARS_ERROR_STATE - instance not in locked state

---

Variable Documentation

struct mars_mutex MARS_MUTEX_ALIGN

MARS mutex structure.

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