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

Macros
#define	osFeature_MainThread 1
	main can be thread

#define	osFeature_SysTick 1
	osKernelSysTick functions available

#define	osCMSIS 0x10002U
	CMSIS-RTOS API version (main [31:16] .sub [15:0])

#define	osCMSIS_RTX ((4<<16)\|80)
	RTOS identification and version (main [31:16] .sub [15:0])

#define	osKernelSystemId "RTX V4.80"
	RTOS identification string.

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

#define	osKernelSysTickMicroSec(microsec) ((microsec * os_tickus_i) + ((microsec * os_tickus_f) >> 16))
	Convert a microseconds value to a RTOS kernel system timer value.

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

osStatus	osKernelStart (void)
	Start the RTOS Kernel.

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

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

Description

The Kernel Information and Control function group allow 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.

Example

void system_error (void)  {
                                                 // fatal error: set system to a safe state
  while (1);
}
int main (void) {                                // program execution starts here
  if (osKernelInitialize () != osOK)  {          // initialize RTOS kernel
    system_error ();                             // invoke system error function
  }
  system_initialize ();                          // setup and initialize peripherals
  osThreadCreate (osThread(job1));               // create threads              
  osThreadCreate (osThread(job2));              
  if (osKernelStart () != osOK)  {               // start kernel with job2 execution
    system_error ();                             // invoke system error function
  }
}

Macro Definition Documentation

#define osCMSIS 0x10002U

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.

#define osCMSIS_RTX ((4<<16)|80)

Identifies the CMSIS-RTOS RTX kernel and version number.

#define osFeature_MainThread 1

CMSIS-RTOS RTX starts with 'main'. The RTOS kernel is in this case already started.

#define osFeature_SysTick 1

CMSIS-RTOS RTX provides access to the RTOS kernel system timer with osKernelSysTick, osKernelSysTickFrequency, and osKernelSysTickMicroSec.

#define osKernelSystemId "RTX V4.80"

Defines the CMSIS-RTOS RTX Kernel and provides version information.

#define osKernelSysTickFrequency os_tickfreq

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 ) ((microsec * os_tickus_i) + ((microsec * os_tickus_f) >> 16))

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

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.

CMSIS-RTOS RTX Kernel starts thread execution with the function main. In this case, the function osKernelInitialize stops thread switching. This allows to setup the system to a defined state before thread switching is resumed with osKernelStart.

Note: Cannot be called from Interrupt Service Routines.

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 )

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

Identifies if the RTOS kernel is started. For CMSIS-RTOS RTX, this allows to identify that the RTOS kernel is already running.

Note: Interrupt Service Routines can call this function.

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.

Start the RTOS Kernel and begin thread switching. CMSIS-RTOS RTX starts thread execution with the function main. In this case, the function osKernelStart 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.

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 )

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.

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