CMSIS-RTOS RTX: Mutex Management

| CMSIS-RTOS RTX Version 4.80 CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions
Mutex Management
CMSIS-RTOS API (RTX)

Synchronize thread execution with a Mutex. More...

## Macros
#define | osMutexDef(name)
| 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. 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

## Macro Definition Documentation

#define osMutex | ( |  | name | ) | &os_mutex_def_##name

Access to mutex object for the functions osMutexCreate.

Parameters

  name | name of the mutex object.

#define osMutexDef | ( |  | name | ) |

Define a mutex object that is referenced by osMutex.

Parameters

  name | name of the mutex object.

## Function Documentation

osMutexId osMutexCreate | ( | const 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.

Create and initialize a Mutex object.

Note
  Cannot be called from Interrupt Service Routines.

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_id | mutex ID obtained by osMutexCreate.

Returns
  status code that indicates the execution status of the function.

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.

Note
  Cannot be called from Interrupt Service Routines.

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_id | mutex ID obtained by osMutexCreate.

Returns
  status code that indicates the execution status of the function.

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.

Note
  Cannot be called from Interrupt Service Routines.

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_id | mutex ID obtained by osMutexCreate.
  [in] | millisec | Timout Value or 0 in case of no time-out.

Returns
  status code that indicates the execution status of the function.

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.

Note
  Cannot be called from Interrupt Service Routines.

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