Generic RTOS Interface

CMSIS-RTOS2 is a generic API that is agnostic of the underlying RTOS kernel. Application programmers call CMSIS-RTOS2 API functions in the user code to ensure maximum portability from one RTOS to another. Middleware using CMSIS-RTOS2 API takes advantages of this approach by avoiding unnecessary porting efforts.

CMSIS-RTOS API Structure

A typical CMSIS-RTOS2 API implementation interfaces to an existing real-time kernel. The CMSIS-RTOS2 API provides the following attributes and functionalities:

• Function names, identifiers, and parameters are descriptive and easy to understand. The functions are powerful and flexible which reduces the number of functions exposed to the user.
• Thread Management allows you to define, create, and control threads.
• Interrupt Service Routines (ISR) can call some CMSIS-RTOS functions. When a CMSIS-RTOS function cannot be called from an ISR context, it rejects the invocation and returns an error code.
• Three different event types support communication between multiple threads and/or ISR:
  • Thread Flags: may be used to indicate specific conditions to a thread.
  • Event Flags: may be used to indicate events to a thread or ISR.
  • Messages: can be sent to a thread or an ISR. Messages are buffered in a queue.
• Mutex Management and Semaphores are incorporated.
• CPU time can be scheduled with the following functionalities:
  • A timeout parameter is incorporated in many CMSIS-RTOS functions to avoid system lockup. When a timeout is specified, the system waits until a resource is available or an event occurs. While waiting, other threads are scheduled.
  • The osDelay and osDelayUntil functions put a thread into the WAITING state for a specified period of time.
  • The osThreadYield provides co-operative thread switching and passes execution to another thread of the same priority.
• Timer Management functions are used to trigger the execution of functions.

The CMSIS-RTOS2 API is designed to optionally incorporate multi-processor systems and/or access protection via the Cortex-M Memory Protection Unit (MPU).

In some RTOS implementations threads may execute on different processors, thus message queues may reside in shared memory resources.

The CMSIS-RTOS2 API encourages the software industry to evolve existing RTOS implementations. RTOS implementations can be different and optimized in various aspects towards the Cortex-M processors. Optional features may be for example

• Support of the Cortex-M Memory Protection Unit (MPU).
• Support of multi-processor systems.
• Support of a DMA controller.
• Deterministic context switching.
• Round-robin context switching.
• Deadlock avoidance, for example with priority inversion.
• Zero interrupt latency by using Armv7-M instructions LDREX and STREX.

cmsis_os2.h header file

The file cmsis_os2.h is a standard header file that interfaces to every CMSIS-RTOS2 compliant real-time operating systems (RTOS). Each implementation is provided the same cmsis_os2.h which defines the interface to the CMSIS-RTOS C API v2.

Using the cmsis_os2.h along with dynamic object allocation allows to create source code or libraries that require no modifications when using on a different CMSIS-RTOS2 implementation.

Using a CMSIS-RTOS2 Implementation

A CMSIS-RTOS2 component may be provided as library or source code (the picture below shows a library). A CMSIS-based application is extended with RTOS functionality by adding a CMSIS-RTOS2 component (and typically some configuration files). The cmsis_os2.h header file gives access to RTOS API functions and is the only interface header required when dynamic object allocation is used. This enables portable application that works with every RTOS kernel event without re-compilation of the source code when the kernel is changed.

Static object allocation requires access to RTOS object control block definitions. An implementation specific header file (rtos.h in the picture below) provides access to such definitions. The section For RTX v5 these definitions are provided in the header file rtx_os.h that contains this definitions for RTX v5.

CMSIS-RTOS File Structure

Once the files are added to a project, the user can start working with the CMSIS-RTOS functions. A code example is provided below:

Code Example

/*----------------------------------------------------------------------------
 * CMSIS-RTOS 'main' function template
 *---------------------------------------------------------------------------*/
 
#include "RTE_Components.h"
#include  CMSIS_device_header
#include "cmsis_os2.h"
 
/*----------------------------------------------------------------------------
 * Application main thread
 *---------------------------------------------------------------------------*/
void app_main (void *argument) {
 
  // ...
  for (;;) {}
}
 
int main (void) {
 
  // System Initialization
  SystemCoreClockUpdate();
#ifdef RTE_Compiler_EventRecorder
  // Initialize and start Event Recorder
  EventRecorderInitialize(EventRecordError, 1U);
#endif
  // ...
 
  osKernelInitialize();                 // Initialize CMSIS-RTOS
  osThreadNew(app_main, NULL, NULL);    // Create application main thread
  osKernelStart();                      // Start thread execution
  for (;;) {}
}