Provide version/system information and start the RTOS Kernel. More...

Macros
#define	osFeature_MainThread 1
	main thread 1=main can be thread, 0=not available More...

#define	osFeature_SysTick 1
	osKernelSysTick functions: 1=available, 0=not available More...

#define	osCMSIS 0x10002
	API version (main [31:16] .sub [15:0]) More...

#define	osCMSIS_KERNEL 0x10000
	RTOS identification and version (main [31:16] .sub [15:0]) More...

#define	osKernelSystemId "KERNEL V1.00"
	RTOS identification string. More...

#define	osKernelSysTickFrequency 100000000
	The RTOS kernel system timer frequency in Hz. More...

#define	osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
	Convert a microseconds value to a RTOS kernel system timer value. More...

Functions
osStatus	osKernelInitialize (void)
	Initialize the RTOS Kernel for creating objects. More...

osStatus	osKernelStart (void)
	Start the RTOS Kernel. More...

int32_t	osKernelRunning (void)
	Check if the RTOS kernel is already started. More...

uint32_t	osKernelSysTick (void)
	Get the RTOS kernel system timer counter. More...

Description

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.

The function main is a special thread function that may be started at system initialization. In this case it has the initial priority osPriorityNormal.

When reaching main, it is necessary to:

Call osKernelInitialize() to initialize the CMSIS-RTOS Kernel
Setup device peripherals and create other RTOS objects using the os*Create functions.
Start the Kernel and begin thread switching by calling osKernelStart().

Code Example

int main (void) {
  osKernelInitialize ();                    // initialize CMSIS-RTOS
 
  // initialize peripherals here
 
  // create 'thread' functions that start executing,
  // example: tid_name = osThreadCreate (osThread(name), NULL);
 
  osKernelStart ();                         // start thread execution 
}

Macro Definition Documentation

#define osCMSIS 0x10002

Version information of the CMSIS-RTOS API whereby major version is in bits [31:16] and sub version in bits [15:0]. The value 0x10000 represents version 1.00.

Note: MUST REMAIN UNCHANGED: osCMSIS identifies the CMSIS-RTOS API version.

#define osCMSIS_KERNEL 0x10000

Identifies the underlying RTOS kernel and version number. The actual name of that define depends on the RTOS Kernel used in the implementation. For example, osCMSIS_FreeRTOS identifies the FreeRTOS kernel and the value indicates the version number of that kernel whereby the major version is in bits [31:16] and sub version in bits [15:0]. The value 0x10000 represents version 1.00.

Note: CAN BE CHANGED: osCMSIS_KERNEL identifies the underlying RTOS kernel and version number.

#define osFeature_MainThread 1

A CMSIS-RTOS implementation may support to start thread execution with the function 'main'.

When osFeature_MainThread is 1 the RTOS offers to start with 'main'. The RTOS kernel is in this case already started.
When osFeature_MainThread is 0 the RTOS requires explicit start with osKernelStart.

CMSIS-RTOS RTX Setting: osFeature_MainThread is 1

Note: MUST REMAIN UNCHANGED: osFeature_xxx shall be consistent in every CMSIS-RTOS.

#define osFeature_SysTick 1

A CMSIS-RTOS implementation may provide access to the RTOS kernel system timer.

When osFeature_SysTick is 1 access to the RTOS kernel system timer is provided with osKernelSysTick, osKernelSysTickFrequency, and osKernelSysTickMicroSec.
When osFeature_SysTick is 0 access to the RTOS kernel system timer is not implemented.

CMSIS-RTOS RTX Setting: osFeature_SysTick is 1

#define osKernelSystemId "KERNEL V1.00"

Defines a string that identifies the underlying RTOS Kernel and provides version information. The length of that string is limited to 21 bytes. A valid identification string is for example, "FreeRTOS V1.00".

Note: MUST REMAIN UNCHANGED: osKernelSystemId shall be consistent in every CMSIS-RTOS.

#define osKernelSysTickFrequency 100000000

Specifies the frequency of the Kernel SysTick timer in Hz. The value is typically use to scale a time value and is for example used in osKernelSysTickMicroSec.

See Also: osKernelSysTick

Note: Reflects the system timer setting and is typically defined in a configuration file.

#define osKernelSysTickMicroSec ( microsec ) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)

Allows you to scale a microsecond value to the frequency of the Kernel SysTick timer. This macro is typically used to check for short timeouts in polling loops.

See Also: osKernelSysTick

Parameters

microsec time value in microseconds.

Returns: time value normalized to the osKernelSysTickFrequency

Function Documentation

osStatus osKernelInitialize ( void )

Returns: status code that indicates the execution status of the function.

Note: MUST REMAIN UNCHANGED: osKernelInitialize shall be consistent in every CMSIS-RTOS.

Initialize of the RTOS Kernel to allow peripheral setup and creation of other RTOS objects with the functions:

osThreadCreate : Create a thread function.
osTimerCreate : Define attributes of the timer callback function.
osMutexCreate : Define and initialize a mutex.
osSemaphoreCreate : Define and initialize a semaphore.
osPoolCreate : Define and initialize a fix-size memory pool.
osMessageCreate : Define and initialize a message queue.
osMailCreate : Define and initialize a mail queue with fix-size memory blocks.

The RTOS kernel does not start thread switching until the function osKernelStart is called.

Note: In case that the RTOS Kernel starts thread execution with the function main the function osKernelInitialize stops thread switching. This allows you to setup the system to a defined state before thread switching is resumed with osKernelStart.

Code Example

#include "cmsis_os.h"
 
int main (void)  {
  if (!osKernelRunning ())  {                    // if kernel is not running, initialize the kernel
    if (osKernelInitialize () != osOK)  {        // check osStatus for other possible valid values
      // exit with an error message
    }
  }
  :
}

int32_t osKernelRunning ( void )

Note: MUST REMAIN UNCHANGED: osKernelRunning shall be consistent in every CMSIS-RTOS.

Returns: 0 RTOS is not started, 1 RTOS is started.

Identifies if the RTOS kernel is started. For systems with the option to start the main function as a thread this allows you to identify that the RTOS kernel is already running.

Note: Interrupt Service Routines can call this function.

Code Example

#include "cmsis_os.h"
 
int main (void) {                                // program execution starts here
  if (osKernelRunning ())  {                    
    :                                            // main is already a thread function
  }
}

osStatus osKernelStart ( void )

Returns: status code that indicates the execution status of the function.

Note: MUST REMAIN UNCHANGED: osKernelStart shall be consistent in every CMSIS-RTOS.

Start the RTOS Kernel and begin thread switching.

Note: When the CMSIS-RTOS starts thread execution with the function main this function resumes thread switching. The main thread will continue executing after osKernelStart.

Status and Error Codes

osOK: the RTOS kernel has been successfully started.
osErrorISR: osKernelStart cannot be called from interrupt service routines.

Note: Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
 
int main (void)  {
  if (osKernelInitialize () != osOK)  {          // check osStatus for other possible valid values
    // exit with an error message
  }
 
  if (!osKernelRunning ())  {                    // is the kernel running ?
    if (osKernelStart () != osOK)  {             // start the kernel
                                                 // kernel could not be started
    }
  }
}

uint32_t osKernelSysTick ( void )

Note: MUST REMAIN UNCHANGED: osKernelSysTick shall be consistent in every CMSIS-RTOS.

Returns: RTOS kernel system timer as 32-bit value

Get the value of the Kernel SysTick timer for time comparison. The value is a rolling 32-bit counter that is typically composed of the kernel system interrupt timer value and an counter that counts these interrupts.

This function allows the implementation of timeout checks. These are for example required when checking for a busy status in a device or peripheral initialization routine.

Note: Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
void SetupDevice (void)  {
  uint32_t tick;
  
  tick = osKernelSysTick();                      // get start value of the Kernel system tick
  Device.Setup ();                               // initialize a device or peripheral
  do {                                           // poll device busy status for 100 microseconds
    if (!Device.Busy) break;                     // check if device is correctly initialized
  } while ((osKernelSysTick() - tick) < osKernelSysTickMicroSec(100));  
  if (Device.Busy)  {              
    ;                                            // in case device still busy, signal error
  }
                                                 // start interacting with device
}

Macros

Functions

Description

Macro Definition Documentation

Function Documentation