CMSIS-RTOS RTX: Kernel Information and Control

| CMSIS-RTOS RTX Version 4.80 CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions
Kernel Information and Control
CMSIS-RTOS API (RTX)

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
}