Mutex Management

Synchronize thread execution with a Mutex. More...

Defines
#define	osMutexDef(name)   osMutexDef_t os_mutex_def_##name = { 0 }
	Define a Mutex.
#define	osMutex(name)   &os_mutex_def_##name
	Access a Mutex defintion.
Functions
osMutexId	osMutexCreate (osMutexDef_t *mutex_def)
	Create and Initialize a Mutex object.
osStatus	osMutexWait (osMutexId mutex_id, uint32_t millisec)
	Wait until a Mutex becomes available.
osStatus	osMutexRelease (osMutexId mutex_id)
	Release a Mutex that was obtained by osMutexWait.

---

Description

The Mutex Management function group is used to synchronize the execution of threads. This is for example used to protect access to a shared resource, for example a shared memory image.

Note:

Mutex Management functions cannot be called from interrupt service routines (ISR).

CMSIS-RTOS Mutex

---

Define Documentation

#define osMutex

(

name

)

&os_mutex_def_##name

Access to mutex object for the functions osMutexCreate.

Parameters:

name	name of the mutex object.

Note:

CAN BE CHANGED: The parameter to osMutex shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

#define osMutexDef

(

name

)

osMutexDef_t os_mutex_def_##name = { 0 }

Define a mutex object that is referenced by osMutex.

Parameters:

name	name of the mutex object.

Note:

CAN BE CHANGED: The parameter to osMutexDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

---

Function Documentation

osMutexId osMutexCreate

(

osMutexDef_t *

mutex_def

)

Parameters:

[in]

mutex_def

mutex definition referenced with osMutex.

Returns:

mutex ID for reference by other functions or NULL in case of error.

Note:

MUST REMAIN UNCHANGED: osMutexCreate shall be consistent in every CMSIS-RTOS.

Create and initialize a Mutex object.

osStatus osMutexRelease

(

osMutexId

mutex_id

)

Parameters:

[in]

mutex_id

mutex ID obtained by osMutexCreate.

Returns:

status code that indicates the execution status of the function.

Note:

MUST REMAIN UNCHANGED: osMutexRelease shall be consistent in every CMSIS-RTOS.

Release a Mutex that was obtained with osMutexWait. Other threads that currently wait for the same mutex will be now put into the state READY.

Status and Error Codes

• osOK: the mutex has been correctly released.
• osErrorResource: the mutex was not obtained before.
• osErrorParameter: the parameter mutex_id is incorrect.
• osErrorISR: osMutexRelease cannot be called from interrupt service routines.

osStatus osMutexWait	(	osMutexId	mutex_id,
		uint32_t	millisec
	)

Parameters:

[in]	mutex_id	mutex ID obtained by osMutexCreate.
[in]	millisec	timeout value or 0 in case of no time-out.

Returns:

status code that indicates the execution status of the function.

Note:

MUST REMAIN UNCHANGED: osMutexWait shall be consistent in every CMSIS-RTOS.

Wait until a Mutex becomes available. If no other thread has obtained the Mutex, the function instantly returns and blocks the mutex object.

Status and Error Codes

• osOK: the mutex has been obtain.
• osErrorTimeoutResource: the mutex could not be obtained in the given time.
• osErrorResource: the mutex could not be obtained when no timeout was specified.
• osErrorParameter: the parameter mutex_id is incorrect.
• osErrorISR: osMutexWait cannot be called from interrupt service routines.