CMSIS-RTOS2: Semaphore Functions

| CMSIS-RTOS2 Version 2.1.3 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
Semaphore Functions
Event functions

Events generated by semaphore functions. More...

## Functions
void | EvrRtxSemaphoreError (osSemaphoreId_t semaphore_id, int32_t status)
| Event on semaphore error (Error) More...
void | EvrRtxSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr)
| Event on semaphore create and initialize (API) More...
void | EvrRtxSemaphoreCreated (osSemaphoreId_t semaphore_id, const char *name)
| Event on successful semaphore create (Op) More...
void | EvrRtxSemaphoreGetName (osSemaphoreId_t semaphore_id, const char *name)
| Event on semaphore name retrieve (API) More...
void | EvrRtxSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout)
| Event on semaphore acquire (API) More...
void | EvrRtxSemaphoreAcquirePending (osSemaphoreId_t semaphore_id, uint32_t timeout)
| Event on pending semaphore acquire (Op) More...
void | EvrRtxSemaphoreAcquireTimeout (osSemaphoreId_t semaphore_id)
| Event on semaphore acquire timeout (Op) More...
void | EvrRtxSemaphoreAcquired (osSemaphoreId_t semaphore_id, uint32_t tokens)
| Event on successful semaphore acquire (Op) More...
void | EvrRtxSemaphoreNotAcquired (osSemaphoreId_t semaphore_id)
| Event on unsuccessful semaphore acquire (Op) More...
void | EvrRtxSemaphoreRelease (osSemaphoreId_t semaphore_id)
| Event on semaphore release (API) More...
void | EvrRtxSemaphoreReleased (osSemaphoreId_t semaphore_id, uint32_t tokens)
| Event on successful semaphore release (Op) More...
void | EvrRtxSemaphoreGetCount (osSemaphoreId_t semaphore_id, uint32_t count)
| Event on semaphore token count retrieval (API) More...
void | EvrRtxSemaphoreDelete (osSemaphoreId_t semaphore_id)
| Event on semaphore delete (API) More...
void | EvrRtxSemaphoreDestroyed (osSemaphoreId_t semaphore_id)
| Event on successful semaphore delete (Op) More...

## Description

## Function Documentation

void EvrRtxSemaphoreError | ( | osSemaphoreId_t | semaphore_id,
|  | int32_t | status
| ) |  |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew or NULL when ID is unknown.
  [in] | status | extended execution status.

The event SemaphoreError is generated when Semaphores 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:

- semaphore_id : semaphore ID.
- status : execution status code.

void EvrRtxSemaphoreNew | ( | uint32_t | max_count,
|  | uint32_t | initial_count,
|  | const osSemaphoreAttr_t * | attr
| ) |  |

Parameters

  [in] | max_count | maximum number of available tokens.
  [in] | initial_count | initial number of available tokens.
  [in] | attr | semaphore attributes.

The event SemaphoreNew is generated when the function osSemaphoreNew is called.

Value in the Event Recorder shows:

- max_count : maximum number of available tokens.
- initial_count : initial number of available tokens.
- attr : memory address of Semaphore attributes or 0 when they are not specified.

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

void EvrRtxSemaphoreCreated | ( | osSemaphoreId_t | semaphore_id,
|  | const char * | name
| ) |  |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.
  [in] | name | pointer to semaphore object name.

The event SemaphoreCreated is generated when the function osSemaphoreNew successfully creates a semaphore object.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.

void EvrRtxSemaphoreGetName | ( | osSemaphoreId_t | semaphore_id,
|  | const char * | name
| ) |  |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.
  [in] | name | pointer to semaphore object name.

The event SemaphoreGetName is generated when the function osSemaphoreGetName is called and its execution result is known.

Value in the Event Recorder shows:

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

void EvrRtxSemaphoreAcquire | ( | osSemaphoreId_t | semaphore_id,
|  | uint32_t | timeout
| ) |  |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.
  [in] | timeout | Timeout Value or 0 in case of no time-out.

The event SemaphoreAcquire is generated when the function osSemaphoreAcquire is called.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.
- timeout : Timeout Value.

void EvrRtxSemaphoreAcquirePending | ( | osSemaphoreId_t | semaphore_id,
|  | uint32_t | timeout
| ) |  |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.
  [in] | timeout | Timeout Value or 0 in case of no time-out.

The event SemaphoreAcquirePending is generated when the function osSemaphoreAcquire blocks current running thread and waits for semaphore token to become available.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.
- timeout : Timeout Value.

void EvrRtxSemaphoreAcquireTimeout | ( | osSemaphoreId_t | semaphore_id | ) |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.

The event SemaphoreAcquireTimeout is generated when wait for semaphore to become available is aborted due to expired wait timeout.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.

void EvrRtxSemaphoreAcquired | ( | osSemaphoreId_t | semaphore_id,
|  | uint32_t | tokens
| ) |  |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.
  [in] | tokens | number of available tokens.

The event SemaphoreAcquired is generated when the function osSemaphoreAcquire successfully acquires the semaphore token.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.
- tokens : available tokens.

void EvrRtxSemaphoreNotAcquired | ( | osSemaphoreId_t | semaphore_id | ) |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.

The event SemaphoreNotAcquired is generated when the function osMutexAcquire returns without timeout and semaphore token was not acquired.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.

void EvrRtxSemaphoreRelease | ( | osSemaphoreId_t | semaphore_id | ) |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.

The event SemaphoreRelease is generated when the function osSemaphoreRelease is called.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.

void EvrRtxSemaphoreReleased | ( | osSemaphoreId_t | semaphore_id,
|  | uint32_t | tokens
| ) |  |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.
  [in] | tokens | number of available tokens.

The event SemaphoreReleased is generated when the function osSemaphoreRelease successfully releases the semaphore token.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.
- tokens : available tokens.

void EvrRtxSemaphoreGetCount | ( | osSemaphoreId_t | semaphore_id,
|  | uint32_t | count
| ) |  |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.
  [in] | count | current number of available tokens.

The event SemaphoreGetCount is generated when the function osSemaphoreGetCount is called and its execution result is known.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.
- count : retrieved current number of available tokens.

void EvrRtxSemaphoreDelete | ( | osSemaphoreId_t | semaphore_id | ) |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.

The event SemaphoreDelete is generated when the function osSemaphoreDelete is called.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.

void EvrRtxSemaphoreDestroyed | ( | osSemaphoreId_t | semaphore_id | ) |

Parameters

  [in] | semaphore_id | semaphore ID obtained by osSemaphoreNew.

The event SemaphoreDestroyed is generated when the function osSemaphoreDelete successfully deletes the semaphore object.

Value in the Event Recorder shows:

- semaphore_id : semaphore ID.