The file cmsis_os.h is a template header file for a CMSIS-RTOS compliant Real-Time Operating System (RTOS).

Each RTOS that is compliant with CMSIS-RTOS shall provide a specific cmsis_os.h header file that represents its implementation.

The file cmsis_os.h contains:

CMSIS-RTOS API function definitions
struct definitions for parameters and return types
status and priority values used by CMSIS-RTOS API functions
macros for defining threads and other kernel objects

Name conventions and header file modifications

All definitions are prefixed with os to give an unique name space for CMSIS-RTOS functions. Definitions that are prefixed os_ are not used in the application code but local to this header file. All definitions and functions that belong to a module are grouped and have a common prefix, i.e. osThread.

Definitions that are marked with CAN BE CHANGED can be adapted towards the needs of the actual CMSIS-RTOS implementation. These definitions can be specific to the underlying RTOS kernel.

Definitions that are marked with MUST REMAIN UNCHANGED cannot be altered. Otherwise the CMSIS-RTOS implementation is no longer compliant to the standard. Note that some functions are optional and need not to be provided by every CMSIS-RTOS implementation.

Function calls from interrupt service routines

The following CMSIS-RTOS functions can be called from threads and interrupt service routines (ISR):

Functions that cannot be called from an ISR are verifying the interrupt status and return in case that they are called from an ISR context the status code osErrorISR. In some implementations this condition might be caught using the HARD FAULT vector.

Some CMSIS-RTOS implementations support CMSIS-RTOS function calls from multiple ISR at the same time. If this is impossible, the CMSIS-RTOS rejects calls by nested ISR functions with the status code osErrorISRRecursive.

Define and reference object definitions

With #define osObjectsExternal objects are defined as external symbols. This allows to create a consistent header file that is used troughtout a project as shown below:

Header File

#include <cmsis_os.h>                                         // CMSIS RTOS header file
// Thread definition
extern void thread_sample (void const *argument);             // function prototype
osThreadDef (thread_sample, osPriorityBelowNormal, 1, 100);
// Pool definition
osPoolDef(MyPool, 10, long);

This header file defines all objects when included in a C/C++ source file. When #define osObjectsExternal is present before the header file, the objects are defined as external symbols. A single consistent header file can therefore be used throughout the whole project.

Example

#include "osObjects.h" // Definition of the CMSIS-RTOS objects

#define osObjectExternal // Objects will be defined as external symbols

#include "osObjects.h" // Reference to the CMSIS-RTOS objects