CMSIS-RTOS2  Version 2.1.2
Real-Time Operating System: API and RTX Reference Implementation
 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.


uint32_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.


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.


osPriority_t osThreadGetPriority (osThreadId_t thread_id)
osPriority   osThreadGetPriority (osThreadId thread_id)

Get current priority of a thread.


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.


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.


osStatus_t osThreadYield (void)
osStatus   osThreadYield (void)

Pass control to next thread that is in state READY.

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).


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.


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.


osStatus_t osTimerStop (osTimerId_t timer_id)
osStatus   osTimerStop (osTimerId timer_id)

Stop a timer.

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.


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.

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.


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.


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 Memory Pool.
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.