CMSIS-RTOS  Version 1.02
CMSIS-RTOS API: Generic RTOS interface for Cortex-M processor-based devices.
Mutex Management

Synchronize thread execution with a Mutex. More...

Macros

#define osMutexDef(name)   const osMutexDef_t os_mutex_def_##name = { 0 }
 Define a Mutex.
 
#define osMutex(name)   &os_mutex_def_##name
 Access a Mutex definition.
 

Functions

osMutexId osMutexCreate (const 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.
 
osStatus osMutexDelete (osMutexId mutex_id)
 Delete a Mutex that was created by osMutexCreate.
 

Description

The Mutex Management function group is used to synchronize the execution of threads. Mutually exclusive (known as Mutex) is commonly used in various operating systems for resource management. Many resources in a microcontroller device can only be used by one thread at a time (for example communication channels). Mutexes are used to protect access to a shared resource. A Mutex is created and then passed between the threads (they can acquire and release the Mutex).

Note
  • Mutex Management functions cannot be called from interrupt service routines (ISR).
  • A thread must not be deleted while it is controlling a Mutex. Otherwise, the Mutex resource will be locked out to all other threads.
Mutex.png
CMSIS-RTOS Mutex

Macro Definition Documentation

#define osMutex (   name)    &os_mutex_def_##name

Access to mutex object for the functions osMutexCreate.

Parameters
namename 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)    const osMutexDef_t os_mutex_def_##name = { 0 }

Define a mutex object that is referenced by osMutex.

Parameters
namename 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 ( const osMutexDef_t mutex_def)
Parameters
[in]mutex_defmutex 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.

Code Example

#include "cmsis_os.h"
osMutexDef (MutexIsr); // Mutex name definition
void CreateMutex (void) {
osMutexId mutex_id;
mutex_id = osMutexCreate (osMutex (MutexIsr));
if (mutex_id != NULL) {
// Mutex object created
}
}
osStatus osMutexDelete ( osMutexId  mutex_id)
Parameters
[in]mutex_idmutex ID obtained by osMutexCreate.
Returns
status code that indicates the execution status of the function.
Note
MUST REMAIN UNCHANGED: osMutexDelete shall be consistent in every CMSIS-RTOS.

Delete a Mutex object. The function releases internal memory obtained for Mutex handling. After this call the mutex_id is no longer valid and cannot be used. The Mutex may be created again using the function osMutexCreate.

Status and Error Codes

  • osOK: the mutex object has been deleted.
  • osErrorISR: osMutexDelete cannot be called from interrupt service routines.
  • osErrorResource: all tokens have already been released.
  • osErrorParameter: the parameter mutex_id is incorrect.

Code Example

#include "cmsis_os.h"
osMutexDef (MutexIsr); // Mutex name definition
osMutexId mutex_id; // Mutex id populated by the function CreateMutex()
osMutexId CreateMutex (void); // function prototype that creates the Mutex
void DeleteMutex (osMutexId mutex_id) {
osStatus status;
if (mutex_id != NULL) {
status = osMutexDelete(mutex_id);
if (status != osOK) {
// handle failure code
}
}
}
osStatus osMutexRelease ( osMutexId  mutex_id)
Parameters
[in]mutex_idmutex 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.

Code Example

#include "cmsis_os.h"
osMutexDef (MutexIsr); // Mutex name definition
osMutexId mutex_id; // Mutex id populated by the function CreateMutex()
osMutexId CreateMutex (void); // function prototype that creates the Mutex
void ReleaseMutex (osMutexId mutex_id) {
osStatus status;
if (mutex_id != NULL) {
status = osMutexRelease(mutex_id);
if (status != osOK) {
// handle failure code
}
}
}
osStatus osMutexWait ( osMutexId  mutex_id,
uint32_t  millisec 
)
Parameters
[in]mutex_idmutex ID obtained by osMutexCreate.
[in]millisectimeout 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.

The argument millisec specifies how long the system waits for a mutex. While the system waits the thread that is calling this function is put into the state WAITING. The millisec timeout can have the following values:

  • when millisec is 0, the function returns instantly.
  • when millisec is set to osWaitForever the function will wait for an infinite time until the mutex becomes available.
  • all other values specify a time in millisecond for a timeout.

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.

Code Example

#include "cmsis_os.h"
osMutexDef (MutexIsr);
void WaitMutex (void) {
osMutexId mutex_id;
osStatus status;
mutex_id = osMutexCreate (osMutex (MutexIsr));
if (mutex_id != NULL) {
status = osMutexWait (mutex_id, 0);
if (status != osOK) {
// handle failure code
}
}
}