Synchronize resource access using Mutual Exclusion (Mutex). More...

Data Structures
struct	osMutexAttr_t
	Attributes structure for mutex. More...

Macros
#define	osMutexRecursive 0x00000001U
	Mutex attributes (attr_bits in osMutexAttr_t). More...

#define	osMutexPrioInherit 0x00000002U
	Priority inherit protocol. More...

#define	osMutexRobust 0x00000008U
	Robust mutex. More...

Typedefs
typedef void *	osMutexId_t

Functions
osMutexId_t	osMutexNew (const osMutexAttr_t *attr)
	Create and Initialize a Mutex object. More...

const char *	osMutexGetName (osMutexId_t mutex_id)
	Get name of a Mutex object. More...

osStatus_t	osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout)
	Acquire a Mutex or timeout if it is locked. More...

osStatus_t	osMutexRelease (osMutexId_t mutex_id)
	Release a Mutex that was acquired by osMutexAcquire. More...

osThreadId_t	osMutexGetOwner (osMutexId_t mutex_id)
	Get Thread which owns a Mutex object. More...

osStatus_t	osMutexDelete (osMutexId_t mutex_id)
	Delete a Mutex object. More...

Description

Mutual exclusion (widely known as Mutex) is used in various operating systems for resource management. Many resources in a microcontroller device can be used repeatedly, but only by one thread at a time (for example communication channels, memory, and files). 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).

CMSIS-RTOS Mutex

A mutex is a special version of a semaphore. Like the semaphore, it is a container for tokens. But instead of being able to have multiple tokens, a mutex can only carry one (representing the resource). Thus, a mutex token is binary and bounded. The advantage of a mutex is that it introduces thread ownership. When a thread acquires a mutex and becomes its owner, subsequent mutex acquires from that thread will succeed immediately without any latency (if osMutexRecursive is specified). Thus, mutex acquires/releases can be nested.

Note: Mutex management functions cannot be called from Interrupt Service Routines (ISR), unlike a binary semaphore that can be released from an ISR.; Refer to Mutex Configuration for RTX5 configuration options.

Data Structure Documentation

struct osMutexAttr_t

Data Fields

const char *

name

name of the mutex

String with a human readable name of the mutex object.

uint32_t

attr_bits

attribute bits

The following predefined bit masks can be assigned to set options for a mutex object.

Bit Mask	Description
osMutexRecursive	Mutex is recursive. The same thread can consume a mutex multiple times without locking itself.
osMutexPrioInherit	Priority inheritance protocol. While a thread owns this mutex it cannot be preempted by a higher priority thread to avoid starvation.
osMutexRobust	Robust mutex. Notify threads that acquire a mutex if the previous owner was terminated.

void *

cb_mem

memory for control block

Pointer to a memory location for the mutex object. This can optionally be used for custom memory management systems. Specify NULL to use the kernel memory management.

uint32_t

cb_size

size of provided memory for control block

The size of the memory block passed with cb_mem. Must be the size of a mutex object or larger.

Macro Definition Documentation

#define osMutexRecursive 0x00000001U

Recursive mutex.

osMutexAttr_t

#define osMutexPrioInherit 0x00000002U

osMutexAttr_t

#define osMutexRobust 0x00000008U

osMutexAttr_t

Typedef Documentation

osMutexId_t

Mutex ID identifies the mutex.

Function Documentation

osMutexId_t osMutexNew ( const osMutexAttr_t * attr )

Parameters

[in] attr mutex attributes; NULL: default values.

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

The function osMutexNew creates and initializes a new mutex object and returns the pointer to the mutex object identifier or NULL in case of an error.

The parameter attr sets the mutex object attributes (refer to osMutexAttr_t). Default attributes will be used if set to NULL.

Note: This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
  
osMutexId_t mutex_id;  
  
const osMutexAttr_t Thread_Mutex_attr = {
  "myThreadMutex",                          // human readable mutex name
  osMutexRecursive | osMutexPrioInherit,    // attr_bits
  NULL,                                     // memory for control block   
  NULL                                      // size for control block
  };
  
void CreateMutex (void)  {
 
  mutex_id = osMutexNew(&Thread_Mutex_attr);
  if (mutex_id != NULL)  {
    // Mutex object created
  }   
}

*const char * osMutexGetName ( osMutexId_t mutex_id )

Parameters

[in] mutex_id mutex ID obtained by osMutexNew.

Returns: name as NULL terminated string.

The function osMutexGetName returns the pointer to the name string of the mutex identified by parameter mutex_id or NULL in case of an error.

Note: This function cannot be called from Interrupt Service Routines.

osStatus_t osMutexAcquire	(	osMutexId_t	mutex_id,
		uint32_t	timeout
	)

Parameters

[in]	mutex_id	mutex ID obtained by osMutexNew.
[in]	timeout	Timeout Value or 0 in case of no time-out.

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

The blocking function osMutexAcquire waits until a mutex object specified by parameter mutex_id becomes available. If no other thread has obtained the mutex, the function instantly returns and blocks the mutex object.

The parameter timeout specifies how long the system waits to acquire the mutex. While the system waits, the thread that is calling this function is put into the BLOCKED state. The parameter timeout can have the following values:

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

Possible osStatus_t return values:

osOK: the mutex has been obtained.
osErrorTimeout: the mutex could not be obtained in the given time.
osErrorParameter: parameter mutex_id is NULL or invalid.
osErrorResource: the mutex specified by parameter mutex_id is in an invalid mutex state or the mutex could not be obtained when no timeout was specified.
osErrorISR: cannot be called from interrupt service routines.

Note: This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
  
void WaitMutex (void)  {
osMutexId_t mutex_id;   
osStatus_t  status;
 
  mutex_id = osMutexNew(NULL);
  if (mutex_id != NULL)  {
    status  = osMutexAcquire(mutex_id, 0);
    if (status != osOK)  {
      // handle failure code
    }
  }
}

osStatus_t osMutexRelease ( osMutexId_t mutex_id )

Parameters

[in] mutex_id mutex ID obtained by osMutexNew.

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

The function osMutexRelease releases a mutex specified by parameter mutex_id. Other threads that currently wait for this mutex will be put into the READY state.

Possible osStatus_t return values:

osOK: the mutex has been correctly released.
osErrorParameter: parameter mutex_id is NULL or invalid.
osErrorResource: the mutex specified by parameter mutex_id is in an invalid mutex state or the mutex was not obtained before/the current thread is not the owner of the mutex.
osErrorISR: osMutexRelease cannot be called from interrupt service routines.

Note: This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
  
osMutexId_t mutex_id;                                        // Mutex id populated by the function osMutexNew()
 
void ReleaseMutex (osMutexId_t mutex_id)  {
osStatus_t status;
  
  if (mutex_id != NULL)  {
    status = osMutexRelease(mutex_id);
    if (status != osOK)  {
      // handle failure code
    }
  }
}

osThreadId_t osMutexGetOwner ( osMutexId_t mutex_id )

Parameters

[in] mutex_id mutex ID obtained by osMutexNew.

Returns: thread ID of owner thread or NULL when mutex was not acquired.

The function osMutexGetOwner returns the thread object ID of the thread that acquired a mutex specified by parameter mutex_id. In case of an error or if the mutex is not owned by the thread, it returns NULL.

Note: This function cannot be called from Interrupt Service Routines.

osStatus_t osMutexDelete ( osMutexId_t mutex_id )

Parameters

[in] mutex_id mutex ID obtained by osMutexNew.

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

The function osMutexDelete deletes a mutex object specified by parameter mutex_id. It 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 osMutexNew.

Possible osStatus_t return values:

osOK: the mutex object has been deleted.
osErrorParameter: parameter mutex_id is NULL or invalid.
osErrorResource: the mutex specified by parameter mutex_id is in an invalid mutex state.
osErrorISR: osMutexDelete cannot be called from interrupt service routines.

Note: This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
  
osMutexId_t mutex_id;                            // Mutex id populated by the function osMutexNew()
 
void DeleteMutex (osMutexId_t mutex_id)  {
osStatus_t status;
  
  if (mutex_id != NULL)  {
    status = osMutexDelete(mutex_id);
    if (status != osOK)  {
      // handle failure code
    }
  }
}

Data Structures

Macros

Typedefs

Functions

Description

Data Structure Documentation

Macro Definition Documentation

Typedef Documentation

Function Documentation