CMSIS-RTOS2: Detailed API Function Differences

| 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
Detailed API Function Differences

This section lists the CMSIS-RTOS API v1 and API v2 functions along with the differences in functionality. The list is sorted alphabetically by API v2 function names and is structured the following way:

- RTOS API v2 function prototype
- RTOS API v1 function prototype that is equivalent or provides similar functionality
- Brief description of the RTOS v2 function.
- Description of the difference.

The background color indicates:

- Green: New functions in API v2 that are not available in API v1
- Amber: Functions that are modified or replaced in API v2 compared to API v1
- Red: Functions in API v1 that are deprecated in API v2

# Kernel Information and Control

`osStatus_t osKernelGetInfo (osVersion_t* version, char* id_buf, uint32_t id_size)`
none
Get RTOS Kernel Information.
New function osKernelGetInfo.

`osKernelState_t osKernelGetState (void)`
`int32_t osKernelRunning (void)`
Get the current RTOS Kernel state.

- The function osKernelGetState replaces the RTOS v1 function osKernelRunning.
- Return type changed to osKernelState_t.

`uint32_t osKernelGetTickCount (void)`
none
Get the RTOS kernel tick count.
New function.

`uint32_t osKernelGetTickFreq (void)`
none
Get the RTOS kernel tick frequency.

- The function osKernelGetTickFreq replaces the RTOS v1 macro osKernelTickMicroSec.

`uint32_t osKernelGetSysTimerCount (void)`
`uint32_t osKernelSysTick (void)`
Get the RTOS kernel system timer count.

- The function osKernelGetSysTimerCount replaces the RTOS v1 function osKernelSysTick.

`uint64_t osKernelGetSysTimerFreq (void)`
none
Get the RTOS kernel system timer frequency.
New function.

`osStatus_t osKernelInitialize (void)`
`osStatus osKernelInitialize (void)`
Initialize the RTOS Kernel.

- Return type changed to osStatus_t.

`int32_t osKernelLock (void)`
none
Lock the RTOS Kernel scheduler.
New function.

`int32_t osKernelUnlock (void)`
none
Unlock the RTOS Kernel scheduler.
New function.

`void osKernelRestoreLock (void)`
none
Restore the RTOS Kernel scheduler lock state.
New function.

`osStatus_t osKernelStart (void)`
`osStatus osKernelStart (void)`
Start the RTOS Kernel scheduler.

- Return type changed to osStatus_t.

`uint32_t osKernelSuspend (void)`
none
Suspend the RTOS Kernel scheduler.
New function.

`void osKernelResume (uint32_t sleep_time)`
none
Resume the RTOS Kernel scheduler.
New function.

# Thread Management

`osStatus_t osThreadDetach (osThreadId_t thread_id)`
none
Detach a thread (thread storage can be reclaimed when thread terminates).
New function.

`uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items)`
none
Enumerate active threads.
New function.

`__NO_RETURN void osThreadExit (void)`
none
Terminate execution of current running thread.
New function.

`uint32_t osThreadGetCount (osThreadId_t thread_id)`
none
Get number of active threads.
New function.

`const char *osThreadGetName (osThreadId_t thread_id)`
none
Get name of a thread.
New function.

`osThreadId_t osThreadGetId (void)`
`osThreadId osThreadGetId (void)`
Return the thread ID of the current running thread.

- Return type changed to osThreadId_t.

`osPriority_t osThreadGetPriority (osThreadId_t thread_id)`
`osPriority osThreadGetPriority (osThreadId thread_id)`
Get current priority of a thread.

- Return type changed to osPriority_t.
- Parameter type changed to osThreadId_t.

`uint32_t osThreadGetStackSize (osThreadId_t thread_id)`
none
Get stack size of a thread.
New function.

`uint32_t osThreadGetStackSpace (osThreadId_t thread_id)`
none
Get available stack space of a thread based on stack watermark recording during execution.
New function.

`osThreadState_t osThreadGetState (osThreadId_t thread_id)`
none
Get current thread state of a thread.
New function.

`osStatus_t osThreadJoin (osThreadId_t thread_id)`
none
Wait for specified thread to terminate.
New function.

`osThreadId_t osThreadNew (osThreadFunc_t function, void *argument, const osThreadAttr_t *attr)`
`osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument)`
Create a thread and add it to Active Threads.

- The function osThreadNew replaces the RTOS v1 function osThreadCreate.
- Options are now passed using a osThreadAttr_t struct, replacing the osThreadDef macro.
- New function prototype is `void func (void *arg)`, before: `void func (const void *arg)`.

`osStatus_t osThreadResume (osThreadId_t thread_id)`
none
Resume execution of a thread.
New function.

`osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority)`
`osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority)`
Change priority of a thread.

- Return type changed to osStatus_t.
- Parameter types changed to osThreadId_t and osPriority_t.

`osStatus_t osThreadSuspend (osThreadId_t thread_id)`
none
Suspend execution of a thread.
New function.

`osStatus_t osThreadTerminate (osThreadId_t thread_id)`
`osStatus osThreadTerminate (osThreadId thread_id)`
Terminate execution of a thread.

- Return type changed to osStatus_t.
- Parameter type changed to osThreadId_t.

`osStatus_t osThreadYield (void)`
`osStatus osThreadYield (void)`
Pass control to next thread that is in state READY.

- Return type changed to osStatus_t.

# Thread Flags

New section to synchronize threads using flags. Thread flags and the more flexible Event Flags are replacing the RTOS v1 Signal Events. Refer to Signal Events for a list of deprecated functions. Refer to Thread Flags for details.

`uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags)`
none
Set the specified Thread Flags of a thread.
New function.

`uint32_t osThreadFlagsClear (uint32_t flags)`
none
Clear the specified Thread Flags of current running thread.
New function.

`uint32_t osThreadFlagsGet (void)`
none
Get the current Thread Flags of current running thread.
New function.

`uint32_t osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout)`
none
Wait for one or more Thread Flags of the current running thread to become signaled.
New function.

# Event Flags

New section to synchronize events using flags. Event flags and thread flags are replacing the RTOS v1 Signal Events. All functions listed in the RTOS v1 Signal Events have been deprecated. Refer to Signal Events for a list of deprecated functions. Refer to Event Flags for details about the new function.

`uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags)`
none
Clear the specified Event Flags.
New function.

`const char *osEventFlagsGetName (osEventFlagsId_t ef_id)`
none
Get name of an Event Flags object.
New function.

`osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id)`
none
Delete an Event Flags object.
New function.

`uint32_t osEventFlagsGet (osEventFlagsId_t ef_id)`
none
Get the current Event Flags.
New function.

`osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr)`
none
Create and Initialize an Event Flags object.
New function.

`uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags)`
none
Set the specified Event Flags.
New function.

`uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout)`
none
Wait for one or more Event Flags to become signaled.
New function.

# Generic Wait Functions

Refer to Generic Wait Functions for details.

`osStatus_t osDelay (uint32_t ticks)`
`osStatus osDelay (uint32_t timeout)`
Wait for Timeout (Time Delay).

- The return type changed to osStatus_t.

`osStatus_t osDelayUntil (uint32_t ticks)`
none
Wait until specified time.
New function.

none
`osEvent osWait (uint32_t millisec)`
Deprecated.

# Timer Management

Refer to Timer Management for details.

`osStatus_t osTimerDelete (osTimerId_t timer_id)`
`osStatus osTimerDelete (osTimerId timer_id)`
Delete a timer.

- The return type changed to osStatus_t.
- The parameter type has changed to osTimerId_t.

`const char *osTimerGetName (osTimerId_t timer_id)`
none
Get name of a timer.
New function.

`uint32_t osTimerIsRunning (osTimerId_t timer_id)`
none
Check if a timer is running.
New function.

`osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr)`
`osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument)`
Create and Initialize a timer.

- The function osTimerNew replaces the RTOS v1 function osTimerCreate.
- The return type changed to osTimerId_t.
- The parameter list and types have changed.

`osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks)`
`osStatus osTimerStart (osTimerId timer_id, uint32_t timeout)`
Start or restart a timer.

- The return type changed to osStatus_t.
- The first parameter type has changed to osTimerId_t.

`osStatus_t osTimerStop (osTimerId_t timer_id)`
`osStatus osTimerStop (osTimerId timer_id)`
Stop a timer.

- The return type changed to osStatus_t.
- The parameter type has changed to osTimerId_t.

# Mutexes

Refer to Mutex Management for details.

`osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout)`
`osStatus osMutexWait (osMutexId mutex_id, uint32_t timeout)`
Acquire a Mutex or timeout if it is locked.

- The function osMutexAcquire replaces the RTOS v1 function osMutexWait.
- Return type changed to osStatus_t.
- First parameter type changed to osMutexId_t.

`osStatus_t osMutexDelete (osMutexId_t mutex_id)`
`osStatus osMutexDelete (osMutexId mutex_id)`
Delete a Mutex object.

- The return type changed to osStatus_t.
- The parameter type changed to osMutexId_t.

`const char *osMutexGetName (osMutexId_t mutex_id)`
none
Get name of a Mutex object.
New function.

`osThreadId_t osMutexGetOwner (osMutexId_t mutex_id)`
none
Get Thread which owns a Mutex object.
New function.

`osMutexId_t osMutexNew (const osMutexAttr_t *attr)`
`osMutexId osMutexCreate (const osMutexDef_t *mutex_def)`
Create and Initialize a Mutex object.

- The function osMutexNew replaces the RTOS v1 function osMutexCreate.
- The return type changed to osMutexId_t.
- The parameter type changed to osMutexAttr_t.

`osStatus_t osMutexRelease (osMutexId_t mutex_id)`
`osStatus osMutexRelease (osMutexId mutex_id)`
Release a Mutex that was acquired by osMutexAcquire.

- The return type changed to osStatus_t.
- The parameter type changed to osMutexId_t.

# Semaphores

Refer to Semaphores for details.

`osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout)`
none
Acquire a Semaphore token or timeout if no tokens are available.
New function. Replaces `osSemaphoreWait`.

`osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id)`
`osStatus osSemaphoreDelete (osSemaphoreId semaphore_id)`
Delete a Semaphore object.

- The return type changed to osStatus_t.
- The parameter type has changed to osSemaphoreId_t.

`uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id)`
none
Get current Semaphore token count.
New function.

`const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id)`
none
Get name of a Semaphore object.
New function.

`osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr)`
`osSemaphoreId osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count)`
Create and Initialize a Semaphore object.

- The function osSemaphoreNew replaces the RTOS v1 function osSemaphoreCreate.
- The return type changed to osSemaphoreId_t.
- The parameter list and types have changed.

`osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id)`
`osStatus osSemaphoreRelease (osSemaphoreId semaphore_id)`
Release a Semaphore token up to the initial maximum count.

- The return type changed to osStatus_t.
- The parameter type has changed to osSemaphoreId_t.

none
`int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t timeout)`
Deprecated. Replaced by osSemaphoreAcquire.

# Memory Pool

`void * osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout)`
`void * osPoolAlloc (osPoolId pool_id)`
Allocate a memory block from a Memory Pool.

- The function osMemoryPoolAlloc replaces both RTOS v1 functions osPoolAlloc.
- The parameter list and types changed.

`osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id)`
none
Delete a Memory Pool object.
New function.

`osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void * block)`
`osStatus osPoolFree (osPoolId pool_id, void * block)`
Return an allocated memory block back to a Memory Pool.

- The function osMemoryPoolFree replaces the RTOS v1 function osPoolFree.
- The first parameter type osMemoryPoolId_t replaces the ROTS v1 type osPoolId.

`uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id)`
none
Get memory block size in a Memory Pool.
New function.

`uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id)`
none
Get maximum number of memory blocks in a Memory Pool.
New function.

`uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id)`
none
Get number of memory blocks used in a Memory Pool.
New function.

`const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id)`
none
Get name of a Memory Pool object.
New function.

`uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id)`
none
Get number of memory blocks available in a Memory Pool.
New function.

`osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr)`
`osPoolId osPoolCreate (const osPoolDef_t * pool_def)`
Get number of memory blocks available in a Memory Pool.

- The function osMemoryPoolNew replaces the RTOS v1 function osPoolCreate.
- The return type changed to osMemoryPoolId_t.
- Parameter list and parameter types have changed.

# Message Queue

In general, messages are now using fixed size memory instead of being 32-bit values. Refer to Message Queue for details.

`osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id)`
none
Delete a Message Queue object.
New function.

`osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout)`
`osEvent osMessageGet (osMessageQId queue_id, uint32_t timeout)`
Get a Message from a Queue or timeout if Queue is empty.

- The function osMessageQueueGet replaces the RTOS v1 function osMessageGet.
- The return type changed to osStatus_t.
- The parameter list and parameter types have changed.

`uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id)`
none
Get maximum number of messages in a Message Queue.
New function.

`uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id)`
none
Get number of queued messages in a Message Queue.
New function.

`uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id)`
none
Get maximum message size in a Message Queue.
New function.

`const char *osMessageQueueGetName (osMessageQueueId_t mq_id)`
none
Get name of a Message Queue object.
New function.

`uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id)`
none
Get number of available slots for messages in a Message Queue.
New function.

`osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr)`
`osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id)`
Create and Initialize a Message Queue object.

- The function osMessageQueueNew replaces the RTOS v1 function osMessageCreate.
- The return type changed to osMessageQueueId_t.
- The parameter list and parameter types have changed.

`osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout)`
`osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t timeout)`
Put a Message into a Queue or timeout if Queue is full.

- The function osMessageQueuePut replaces the RTOS v1 function osMessagePut.
- The return type changed to osStatus_t.
- The parameter list and parameter types have changed.

`osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id)`
none
Reset a Message Queue to initial empty state.
New function.

# Mail Queue

The Mail Queue RTOS v1 functions have been deprecated. Use the functionality of the Message Queue instead. Differences are listed under Message Queue.

none
`void * osMailAlloc (osMailQId queue_id, uint32_t timeout)`
Deprecated.

none
`void * osMailCAlloc (osMailQId queue_id, uint32_t timeout)`
Deprecated.

none
`osMailQId osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id)`
Deprecated.

none
`osStatus osMailFree (osMailQId queue_id, void *mail)`
Deprecated.

none
`osEvent osMailGet (osMailQId queue_id, uint32_t timeout)`
Deprecated.

none
`osStatus osMailPut (osMailQId queue_id, void *mail)`
Deprecated.

# Signal Events

The section RTOS v1 Signal Events has been deprecated. Use the functions listed under Thread Flags instead.

none
`int32_t osSignalClear (osThreadId thread_id, int32_t signals)`
Deprecated.

none
`int32_t osSignalSet (osThreadId thread_id, int32_t signals)`
Deprecated.

none
`osEvent osSignalWait (int32_t signals, uint32_t timeout)`
Deprecated.