CMSIS-RTOS: Kernel Information and Control

| CMSIS-RTOS Version 1.02 CMSIS-RTOS API: Generic RTOS interface for Cortex-M processor-based devices.

- Main Page
- Usage and Description
- Reference

Macros | Functions
Kernel Information and Control
CMSIS-RTOS API

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
#define | osFeature_SysTick 1
| osKernelSysTick functions: 1=available, 0=not available
#define | osCMSIS 0x10002
| API version (main [31:16] .sub [15:0])
#define | osCMSIS_KERNEL 0x10000
| RTOS identification and version (main [31:16] .sub [15:0])
#define | osKernelSystemId "KERNEL V1.00"
| RTOS identification string.
#define | osKernelSysTickFrequency 100000000
| The RTOS kernel system timer frequency in Hz.
#define | osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
| 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 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:

1. Call osKernelInitialize() to initialize the CMSIS-RTOS Kernel
2. Setup device peripherals and create other RTOS objects using the os*Create functions.
3. 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.

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.

#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
}