CMSIS-RTOS2: Mutex Functions

| CMSIS-RTOS2 Version 2.1.1 Real-Time Operating System: API and RTX Reference Implementation

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions
Mutex Functions
Event functions

Events generated by mutex functions. More...

## Functions
void | EvrRtxMutexError (osMutexId_t mutex_id, int32_t status)
| Event on mutex error (Error) More...
void | EvrRtxMutexNew (const osMutexAttr_t *attr)
| Event on mutex create and initialize (API) More...
void | EvrRtxMutexCreated (osMutexId_t mutex_id)
| Event on successful mutex create (Op) More...
void | EvrRtxMutexGetName (osMutexId_t mutex_id, const char *name)
| Event on mutex name retrieve (API) More...
void | EvrRtxMutexAcquire (osMutexId_t mutex_id, uint32_t timeout)
| Event on mutex acquire (API) More...
void | EvrRtxMutexAcquirePending (osMutexId_t mutex_id, uint32_t timeout)
| Event on pending mutex acquire (Op) More...
void | EvrRtxMutexAcquireTimeout (osMutexId_t mutex_id)
| Event on mutex acquire timeout (Op) More...
void | EvrRtxMutexAcquired (osMutexId_t mutex_id, uint32_t lock)
| Event on successful mutex acquire (Op) More...
void | EvrRtxMutexNotAcquired (osMutexId_t mutex_id)
| Event on unsuccessful mutex acquire (Op) More...
void | EvrRtxMutexRelease (osMutexId_t mutex_id)
| Event on mutex release (API) More...
void | EvrRtxMutexReleased (osMutexId_t mutex_id, uint32_t lock)
| Event on successful mutex release (Op) More...
void | EvrRtxMutexGetOwner (osMutexId_t mutex_id, osThreadId_t thread_id)
| Event on mutex owner retrieve (API) More...
void | EvrRtxMutexDelete (osMutexId_t mutex_id)
| Event on mutex delete (API) More...
void | EvrRtxMutexDestroyed (osMutexId_t mutex_id)
| Event on successful mutex delete (Op) More...

## Description

## Function Documentation

void EvrRtxMutexError | ( | osMutexId_t | mutex_id,
|  | int32_t | status
| ) |  |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew or NULL when ID is unknown.
  [in] | status | extended execution status.

The event MutexError is generated when Mutex Management routines complete their execution due to an error.

The status parameter indicates the execution status and can be one of the osStatus_t codes or one of the extended execution status codes which are summarized in the table below.

Extended Status Code | Description
--- | ---
osRtxErrorKernelNotReady | Kernel scheduler is not in Ready state.
osRtxErrorKernelNotRunning | Kernel scheduler is not executing - there is no running thread.
osRtxErrorInvalidControlBlock | Object control block with invalid alignment or size was specified.
osRtxErrorInvalidDataMemory | Object data memory with invalid alignment or size was specified.
osRtxErrorInvalidThreadStack | Thread stack memory with invalid alignment or size was specified.
osRtxErrorInvalidPriority | Invalid thread priority was specified.
osRtxErrorThreadNotJoinable | Specified thread is not joinable.
osRtxErrorMutexNotOwned | Specified mutex is not owned by the current running thread.
osRtxErrorMutexNotLocked | Specified mutex is not locked.
osRtxErrorMutexLockLimit | Maximum number of recursive mutex locks reached.
osRtxErrorSemaphoreCountLimit | Semaphore count limit reached.
osRtxErrorTZ_InitContext_S | Secure context memory system initialization failed.
osRtxErrorTZ_AllocContext_S | Secure context memory allocation failed.
osRtxErrorTZ_FreeContext_S | Secure context memory deallocation failed.
osRtxErrorTZ_LoadContext_S | Secure context load failed.
osRtxErrorTZ_SaveContext_S | Secure context save failed.

Value in the Event Recorder shows:

- mutex_id : mutex ID.
- status : execution status code.

void EvrRtxMutexNew | ( | const osMutexAttr_t * | attr | ) |

Parameters

  [in] | attr | mutex attributes

The event MutexNew is generated when the function osMutexNew is called.

Value in the Event Recorder shows:

- attr : memory address of Mutex attributes or 0 when they are not specified.

In case when mutex attributes are provided in the API call they are also detailed in the Event Recorder.

void EvrRtxMutexCreated | ( | osMutexId_t | mutex_id | ) |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.

The event MutexCreated is generated when the function osMutexNew successfully creates a mutex object.

Value in the Event Recorder shows:

- mutex_id : mutex ID.

void EvrRtxMutexGetName | ( | osMutexId_t | mutex_id,
|  | const char * | name
| ) |  |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.
  [in] | name | pointer to mutex object name

The event MutexGetName is generated when the function osMutexGetName is called and its execution result is known.

Value in the Event Recorder shows:

- mutex_id : mutex ID.
- name : retrieved memory address of name string (0 in case of a failure).

void EvrRtxMutexAcquire | ( | 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.

The event MutexAcquire is generated when the function osMutexAcquire is called.

Value in the Event Recorder shows:

- mutex_id : mutex ID.
- timeout : Timeout Value.

void EvrRtxMutexAcquirePending | ( | 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.

The event MutexAcquirePending is generated when the function osMutexAcquire blocks current running thread and waits for mutex to become available.

Value in the Event Recorder shows:

- mutex_id : mutex ID.
- timeout : Timeout Value.

void EvrRtxMutexAcquireTimeout | ( | osMutexId_t | mutex_id | ) |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.

The event MutexAcquireTimeout is generated when wait for mutex to become available is aborted due to expired wait timeout.

Value in the Event Recorder shows:

- mutex_id : mutex ID.

void EvrRtxMutexAcquired | ( | osMutexId_t | mutex_id,
|  | uint32_t | lock
| ) |  |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.
  [in] | lock | current number of times mutex object is locked

The event MutexAcquired is generated when the function osMutexAcquire successfully acquires a mutex.

Value in the Event Recorder shows:

- mutex_id : mutex ID.
- lock : current lock counter state.

void EvrRtxMutexNotAcquired | ( | osMutexId_t | mutex_id | ) |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.

The event MutexNotAcquired is generated when the function osMutexAcquire returns without timeout and mutex was not acquired.

Value in the Event Recorder shows:

- mutex_id : mutex ID.

void EvrRtxMutexRelease | ( | osMutexId_t | mutex_id | ) |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.

The event MutexRelease is generated when the function osMutexRelease is called.

Value in the Event Recorder shows:

- mutex_id : mutex ID.

void EvrRtxMutexReleased | ( | osMutexId_t | mutex_id,
|  | uint32_t | lock
| ) |  |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.
  [in] | lock | current number of times mutex object is locked

The event MutexReleased is generated when the function osMutexRelease successfully releases a mutex.

Value in the Event Recorder shows:

- mutex_id : mutex ID.
- lock : current lock counter state.

void EvrRtxMutexGetOwner | ( | osMutexId_t | mutex_id,
|  | osThreadId_t | thread_id
| ) |  |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.
  [in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId.

The event MutexGetOwner is generated when the function osMutexGetOwner is called and its execution result is known.

Value in the Event Recorder shows:

- mutex_id : mutex ID.
- thread_id : retrieved owner thread ID (0 in case of a failure or when mutex is not locked)

void EvrRtxMutexDelete | ( | osMutexId_t | mutex_id | ) |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.

The event MutexDelete is generated when the function osMutexDelete is called.

Value in the Event Recorder shows:

- mutex_id : mutex ID.

void EvrRtxMutexDestroyed | ( | osMutexId_t | mutex_id | ) |

Parameters

  [in] | mutex_id | mutex ID obtained by osMutexNew.

The event MutexDestroyed is generated when the function osMutexDelete successfully deletes the mutex object.

Value in the Event Recorder shows:

- mutex_id : mutex ID.