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

- RTX

- 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

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:

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

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