CMSIS-RTOS RTX  Version 4.51
CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Kernel Information and Control

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 osCMSIS   0x10001
 API version (main [31:16] .sub [15:0])
 
#define osKernelSystemId   "RTX V4.61"
 RTOS identification string.
 

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.
 

Description

The Kernel Information and Control function group allows to:

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
if (osKernelStart () != osOK) { // start kernel with job2 execution
system_error (); // invoke system error function
}
}

Macro Definition Documentation

#define osCMSIS   0x10001

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 osFeature_MainThread   1

A CMSIS-RTOS implementation may support to start thread execution with the function 'main'. When the value osFeature_MainThread is 1 the RTOS offers to start with 'main'. The RTOS kernel is in this case already started. When the value 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 osKernelSystemId   "RTX V4.61"

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.

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:

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 to setup the system to a defined state before thread switching is resumed with osKernelStart.
#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 to identify that the RTOS kernel is already running.

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.

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