Mutex Management API

Data Structures
struct	mars_mutex_status
	MARS mutex structure. More...
Files
file	mutex_types.h
	[host/MPU] MARS Mutex Types
file	mutex.h
	[host] MARS Mutex API
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)
	[host] Locks a mutex.
int	mars_mutex_unlock_put (uint64_t mutex_ea, struct mars_mutex *mutex)
	[host] Unlocks a mutex.

---

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:

The use of mutexes should be mainly reserved for implementing the workload model layer. Access to the mutex API is limited to the workload module layer from the MPU-side. It is left up to the workload module whether or not to provide access to mutex routines through the workload model API.

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

- ea 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

- ea 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

- ea 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.

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

Parameters:

[in]

mutex_ea

- ea of mutex instance

Returns:

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

int mars_mutex_unlock

(

uint64_t

mutex_ea

)

[host] Unlocks a mutex.

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

Parameters:

[in]

mutex_ea

- ea 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

int mars_mutex_lock_get	(	uint64_t	mutex_ea,
		struct mars_mutex *	mutex
	)

[host] 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.

Note:

This call should only be used when MARS_ENABLE_DISCRETE_SHARED_MEMORY is enabled. Otherwise, the mutex parameter is ignored and the function behaves the same as mars_mutex_lock.

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
	)

[host] 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.

Note:

This call should only be used when MARS_ENABLE_DISCRETE_SHARED_MEMORY is enabled. Otherwise, the mutex parameter is ignored and the function behaves the same as mars_mutex_unlock.

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