CMSIS-RTOS v2 wrapper implementation

The CMSIS-RTOS v2 (CMSIS-RTOS2) provides generic RTOS interfaces for Arm® Cortex® processor-based devices. It provides a standardized API for software components that require RTOS functionality and gives therefore serious benefits to the users and the software industry:

• CMSIS-RTOS2 provides basic features that are required in many applications.
• The unified feature set of the CMSIS-RTOS2 reduces learning efforts and simplifies sharing of software components.
• Middleware components that use the CMSIS-RTOS2 are RTOS agnostic and are easier to adapt.
• Standard project templates of the CMSIS-RTOS2 may be shipped with freely available CMSIS-RTOS2 implementations.

This CMSIS-RTOS v2 represents a wrapper layer for CMSIS RTOS v2 APIs implementation based on threadX RTOS APIs. The list of features supported by the current implementation are as below:

Feature	Supported	Short Description
Kernel Information and Control	Y	It provide version/system information and starts/controls the RTOS Kernel. More...
Thread Management	Y	It define, create, and control thread functions.. More...
Thread Flags	N	It synchronize threads using flags. More...
Event Flags	Y	It synchronize threads using event flags. More...
Generic Wait Functions	Y	It wait for a certain period of time.. More...
Timer Management	Y	It create and control timer and timer callback functions. More...
Mutex Management	Y	It synchronize resource access using Mutual Exclusion (Mutex). More...
Semaphores	Y	It access shared resources simultaneously from different threads. More...
Memory Pool	Y	It manage thread-safe fixed-size blocks of dynamic memory. More...
Message Queue	Y	It exchange messages between threads in a FIFO-like operation. More...

For more information about CMSIS-RTOS v2 APIs, please refer to the ARM manual: CMSIS-RTOS API v2

CMSIS-RTOS v2 design

Kernel Initialize and Start

In threadX RTOS only one interface is used to start the kernel (tx_kernel_enter). This function will:

• _tx_initialize_low_level: invoke the low-level initialization to handle all processor specific initialization issues
• _tx_initialize_high_level: invoke the high-level initialization to exercise all of the ThreadX components and the application's initialization function
• tx_application_define: call the application provided initialization function. Pass the first available memory address to it
• _tx_thread_schedule: enter the scheduling loop to start executing threads.

For ARM CMSIS solution, its mandatory to separate the kernel initialization from the kernel start to allow the user to create threads, timers, semaphores,... in between. For that we design the CMSIS-RTOS2 wrapper as below:

• osKernelInitialize: will initialize the low level and high level layers by calling the function "_tx_initialize_kernel_setup"
• osKernelGetState: will call the application provided initialization function start the kernel.

Dynamic Memory Management

CMSIS-RTOS v2 APIs such as osThreadNew, give the possibilities to the user, when implementing his application, to:

• Pass the block memory and stack address (declared or allocated in the application level)
• Let the low layers (wrapper or RTOS) allocate the memory

However, the dynamic memory allocation is not a supported feature for threadX RTOS. In fact, its mandatory to implement it in CMSIS RTOS v2 wrapper level.

The global idea for dynamic memory allocation solution is to use two threadX BytePools:

• HeapBytePool: used for thread, timer, mutex, semaphore, event flags and message queue object block memory allocation
• StackBytePool: used for thread and message queue stack memory allocation.

In fact, three internal functions are added as following:

Function Name	Short Description
MemInit	creates the HeapBytePool and StackBytePool BytePools
MemAlloc	allocate the needed memory for object block or stack
MemFree	free the memory for object block or stack

Notes:

• The sizes of HeapBytePool and StackBytePool are user defined using respectively the macro defines RTOS2_BYTE_POOL_HEAP_SIZE and RTOS2_BYTE_POOL_STACK_SIZE
• The minimum size of HeapBytePool and StackBytePool is defined by the threadX macro define TX_BYTE_POOL_MIN
• The HeapBytePool and StackBytePool are allocated from the first free memory area defined by the threadX variable _tx_initialize_unused_memory.

Static Memory Management

CMSIS-RTOS v2 gives the possibilities to the user, when implementing his application, to statically allocate the memory. In fact, static buffers will be created and allocated based on user defines RTOS2_BYTE_POOL_HEAP_SIZE and RTOS2_BYTE_POOL_STACK_SIZE. The minimum size of HeapBytePool and StackBytePool is defined by the threadX macro define TX_BYTE_POOL_MIN.

CMSIS-RTOS v2 Modules description

Kernel Information and Control

The kernel Information and Control function group allows to:

• Obtain information about the system and the underlying kernel.
• Obtain version information about the CMSIS-RTOS API.
• Initialize of the RTOS kernel for creating objects.
• Start the RTOS kernel and thread switching.
• Check the execution status of the RTOS kernel.

API Name	Supported	Short Description	Limitation
osKernelInitialize	Y	Kernel Initialize...	No limitations
osKernelGetInfo	Y	Kernel Get Info...	No limitations
osKernelGetState	Y	Kernel Get State...	Only osKernelInactive, osKernelReady and osKernelRunning states are supported
osKernelStart	Y	Kernel Start...	No limitations
osKernelLock	N	Kernel Lock...	This API is not supported due to threadX limitation
osKernelUnlock	N	Kernel Unlock...	This API is not supported due to threadX limitation
osKernelRestoreLock	N	Kernel Restore Lock...	This API is not supported due to threadX limitation
osKernelSuspend	N	Kernel Suspend...	This API is not supported due to threadX limitation
osKernelResume	N	Kernel Resume...	This API is not supported due to threadX limitation
osKernelGetTickCount	Y	Kernel Get Tick Count...	No limitations
osKernelGetTickFreq	Y	Kernel Get Tick Freq...	No limitations
osKernelGetSysTimerCount	Y	Kernel Get SysTimer Count...	No limitations
osKernelGetSysTimerFreq	Y	Kernel Get SysTimer Freq...	No limitations

Notes:

• Due to threadX RTOS limitation (no lock or suspend feature are supported), all kernel lock, suspend and resume APIs are not supported.

Thread Management

The Thread Management function group allows defining, creating, and controlling thread functions in the system.

API Name	Supported	Short Description	Limitation
osThreadNew	Y	Thread New...	If argument is given as input this will be considered as entry_input for threadX
osThreadGetName	Y	Thread Get Name...	No limitations
osThreadGetId	Y	Thread Get Id...	No limitations
osThreadGetState	Y	Thread Get State...	Only osThreadRunning, osThreadReady, osThreadTerminated and osThreadBlocked thread states are supported
osThreadSetPriority	Y	Thread Set Priority...	No limitations
osThreadGetPriority	Y	Thread Get Priority...	No limitations
osThreadYield	Y	Thread Yield...	No limitations
osThreadSuspend	Y	Thread Suspend...	No limitations
osThreadResume	Y	Thread Resume...	No limitations
osThreadDetach	Y	Thread Detach...	TX_THREAD_USER_EXTENSION must be defined
osThreadJoin	Y	Thread Join...	TX_THREAD_USER_EXTENSION must be defined
osThreadExit	Y	Thread Exit...	No limitations
osThreadTerminate	Y	Thread Terminate...	No limitations
osThreadGetStackSize	Y	Thread Get Stack Size...	No limitations
osThreadGetStackSpace	Y	Thread Get Stack Space...	No limitations
osThreadGetCount	Y	Thread Get Count...	No limitations
osThreadEnumerate	Y	Thread Enumerate...	No limitations

Notes:

• Thread management functions cannot be called from Interrupt Service Routines.
• To support osThreadDetach and osThreadJoin APIs, the TX_THREAD_USER_EXTENSION must be defined as tx_thread_detached_joinable (ULONG) in tx_user.h file

Thread Flags

Thread Flags are a more specialized version of the Event Flags. See Event Flags. While Event Flags can be used to globally signal a number of threads, thread flags are only send to a single specific thread. Every thread instance can receive thread flags without any additional allocation of a thread flags object.

API Name	Supported	Short Description	Limitation
osThreadFlagsSet	N	Thread Flags Set...	Not yet implemented
osThreadFlagsClear	N	Thread Flags Clear...	Not yet implemented
osThreadFlagsGet	N	Thread Flags Get...	Not yet implemented
osThreadFlagsWait	N	Thread Flags Wait...	Not yet implemented

Notes:

• Thread flag management functions cannot be called from Interrupt Service Routines, except for osThreadFlagsSet.
• The Thread flag management functions are not supported in the current CMSIS RTOS v2 implementation and will be implemented in the future version.

Event Flags

The event flags management functions in CMSIS-RTOS allow you to control or wait for event flags. Each signal has up to 31 event flags.

A thread :

• Can wait for event flags to be set (using osEventFlagsWait). Using this function, it enters the BLOCKED state.
• May set one or more flags in any other given thread (using osEventFlagsSet).
• May clear its own signals or the signals of other threads (using osEventFlagsClear).
• When a thread wakes up and resumes execution, its signal flags are automatically cleared (unless event flags option osFlagsNoClear is specified).

API Name	Supported	Short Description	Limitation
osEventFlagsNew	Y	Thread Flags Set...	No limitations
osEventFlagsSet	Y	Thread Flags Clear...	No limitations
osEventFlagsClear	Y	Thread Flags Get...	No limitations
osEventFlagsGet	Y	Thread Flags Wait...	No limitations
osEventFlagsWait	Y	Thread Flags Clear...	No limitations
osEventFlagsDelete	Y	Thread Flags Get...	No limitations
osEventFlagsGetName	Y	Thread Flags Wait...	No limitations

Notes:

• The functions osEventFlagsSet, osEventFlagsClear, osEventFlagsGet, and osEventFlagsWait can be called from Interrupt Service Routines
• If a thread is blocked on waiting an event flag, the osEventFlagsSet will unblock it.

Generic Wait Functions

The generic wait functions provide means for a time delay.

API Name	Supported	Short Description	Limitation
osDelay	Y	Delay...	No limitations
osDelayUntil	Y	Delay Until...	No limitations

Notes:

• Generic wait functions cannot be called from Interrupt Service Routines.

Timer Management

In addition to the Generic Wait Functions CMSIS-RTOS also supports virtual timer objects. These timer objects can trigger the execution of a function (not threads). When a timer expires, a callback function is executed to run associated code with the timer. Each timer can be configured as a one-shot or a periodic timer. A periodic timer repeats its operation until it is deleted or stopped. All timers can be started, restarted, or stopped.

API Name	Supported	Short Description	Limitation
osTimerNew	Y	Timer New...	No limitations
osTimerGetName	Y	Timer Get Name...	No limitations
osTimerStart	Y	Timer Start...	No limitations
osTimerStop	Y	Timer Stop...	No limitations
osTimerIsRunning	Y	Timer Is Running...	No limitations
osTimerDelete	Y	Timer Delete...	No limitations

Notes:

• Timer management functions cannot be called from Interrupt Service Routines.

Mutex Management

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

API Name	Supported	Short Description	Limitation
osMutexNew	Y	Mutex New...	osMutexRobust and osMutexRecursive mutex types are not supported
osMutexGetName	Y	Mutex Get Name...	No limitations
osMutexAcquire	Y	Mutex Acquire...	No limitations
osMutexRelease	Y	Mutex Release...	No limitations
osMutexGetOwner	Y	Mutex Get Owner...	No limitations
osMutexDelete	Y	Mutex Delete...	No limitations

Notes:

• Mutex management functions cannot be called from Interrupt Service Routines (ISR), unlike a binary semaphore that can be released from an ISR.
• If a thread is blocked on acquiring or releasing the mutex, the osMutexAcquire and osMutexRelease will unblock it. Therefore, acquiring or releasing the mutex will not change the mutex status except from the number of thread blocked on it.

Semaphores

Semaphores are used to manage and protect access to shared resources. Semaphores are very similar to Mutexes. Whereas a Mutex permits just one thread to access a shared resource at a time, a semaphore can be used to permit a fixed number of threads/ISRs to access a pool of shared resources. Using semaphores, access to a group of identical peripherals can be managed (for example multiple DMA channels).

API Name	Supported	Short Description	Limitation
osSemaphoreNew	Y	Semaphore New...	The parameter max_count is not supported
osSemaphoreGetName	Y	Semaphore Get Name...	No limitations
osSemaphoreAcquire	Y	Semaphore Acquire...	No limitations
osSemaphoreRelease	Y	Semaphore Release...	No limitations
osSemaphoreGetCount	N	Semaphore Get Count...	This API is not supported due to max_count limitation
osSemaphoreDelete	Y	Semaphore Delete...	No limitations

Notes:

• The functions osSemaphoreAcquire, osSemaphoreGetCount, and osSemaphoreRelease can be called from Interrupt Service Routines.
• If a thread is blocked on acquiring or releasing the semaphore, the osSemaphoreAcquire and osSemaphoreRelease will unblock it. Therefore, acquiring or releasing the semaphore will not change the semaphore status except from the number of thread blocked on it
• Due to max_count limitation, the binary semaphore is not supported.

Memory Pool

Memory Pools are fixed-size blocks of memory that are thread-safe. They operate much faster than the dynamically allocated heap and do not suffer from fragmentation. Being thread-safe, they can be accessed from threads and ISRs alike. A Memory Pool can be seen as a linked list of available (unused) memory blocks of fixed and equal size. Allocating memory from a pool (using osMemoryPoolAlloc) simply unchains a block from the list and hands over control to the user. Freeing memory to the pool (using osMemoryPoolFree) simply rechains the block into the list.

API Name	Supported	Short Description	Limitation
osMemoryPoolNew	Y	MemoryPool New...	No limitations
osMemoryPoolGetName	Y	MemoryPool Get Name...	No limitations
osMemoryPoolAlloc	Y	MemoryPool Alloc...	No limitations
osMemoryPoolFree	Y	MemoryPool Free...	No limitations
osMemoryPoolGetCapacity	Y	MemoryPool Get Capacity...	No limitations
osMemoryPoolGetBlockSize	Y	MemoryPool Get Block Size...	No limitations
osMemoryPoolGetCount	Y	MemoryPool Get Count...	No limitations
osMemoryPoolGetSpace	Y	MemoryPool Get Count...	No limitations
osMemoryPoolDelete	Y	MemoryPool Delete...	No limitations

Notes:

• The functions osMemoryPoolAlloc, osMemoryPoolFree, osMemoryPoolGetCapacity, osMemoryPoolGetBlockSize, osMemoryPoolGetCount, osMemoryPoolGetSpace can be called from Interrupt Service Routines.

Message Queue

Message passing is another basic communication model between threads. In the message passing model, one thread sends data explicitly, while another thread receives it. The operation is more like some kind of I/O rather than a direct access to information to be shared. In CMSIS-RTOS, this mechanism is called s message queue. The data is passed from one thread to another in a FIFO-like operation. Using message queue functions, you can control, send, receive, or wait for messages. The data to be passed can be of integer or pointer type.

API Name	Supported	Short Description	Limitation
osMessageQueueNew	Y	MessageQueue New...	No limitations
osMessageQueueGetName	Y	MessageQueue Get Name...	No limitations
osMessageQueuePut	Y	MessageQueue Put...	Message priority is not supported
osMessageQueueGet	Y	MessageQueue Get...	Message priority is not supported
osMessageQueueGetCapacity	Y	MessageQueue Get Capacity...	No limitations
osMessageQueueGetMsgSize	Y	MessageQueue Get Msg Size...	No limitations
osMessageQueueGetCount	Y	MessageQueue Get Count...	No limitations
osMessageQueueGetSpace	Y	MessageQueue Get Space...	No limitations
osMessageQueueReset	Y	MessageQueue Reset...	No limitations
osMessageQueueDelete	Y	MessageQueue Delete...	No limitations

Notes:

• The functions osMessageQueuePut, osMessageQueueGet, osMessageQueueGetCapacity, osMessageQueueGetMsgSize, osMessageQueueGetCount, osMessageQueueGetSpace can be called from Interrupt Service Routines.
• If a thread is blocked on getting or putting a message on the queue, the osMessageQueuePut and osMessageQueueGet will unblock it. Therefore, putting or getting a message will not change the queue status except from the number of thread blocked on it.