CMSIS-RTOS2  Version 2.0.0
Real-Time Operating System: API and RTX Reference Implementation
 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...

Data Structures

struct  osVersion_t
 Version information. More...
 

Enumerations

enum  osKernelState_t {
  osKernelInactive = 0,
  osKernelReady = 1,
  osKernelRunning = 2,
  osKernelLocked = 3,
  osKernelSuspended = 4,
  osKernelError = -1,
  osKernelReserved = 0x7FFFFFFFU
}
 Kernel state. More...
 

Functions

osStatus_t osKernelInitialize (void)
 Initialize the RTOS Kernel. More...
 
osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
 Get RTOS Kernel Information. More...
 
osKernelState_t osKernelGetState (void)
 Get the current RTOS Kernel state. More...
 
osStatus_t osKernelStart (void)
 Start the RTOS Kernel scheduler. More...
 
uint32_t osKernelLock (void)
 Lock the RTOS Kernel scheduler. More...
 
void osKernelUnlock (void)
 Unlock the RTOS Kernel scheduler. More...
 
uint32_t osKernelSuspend (void)
 Suspend the RTOS Kernel scheduler. More...
 
void osKernelResume (uint32_t sleep_ticks)
 Resume the RTOS Kernel scheduler. More...
 
uint64_t osKernelGetTickCount (void)
 Get the RTOS kernel tick count. More...
 
uint32_t osKernelGetTickFreq (void)
 Get the RTOS kernel tick frequency. More...
 
uint32_t osKernelGetSysTimerCount (void)
 Get the RTOS kernel system timer count. More...
 
uint32_t osKernelGetSysTimerFreq (void)
 Get the RTOS kernel system timer frequency. More...
 

Description

The Kernel Information and Control function group allows to:

Note
The Kernel initialization for RTX5 is documented in System Startup.

Code Example

int main (void) {
osKernelInitialize (); // initialize CMSIS-RTOS
// initialize peripherals here
// create 'thread' functions that start executing,
// example: tid_name = osThreadNew(thread, NULL, NULL);
osKernelStart (); // start thread execution
}

Data Structure Documentation

struct osVersion_t

Identifies the underlying RTOS kernel and API version number. The Version is represented in a combined decimal number in the format: major.minor.rev: mmnnnrrrr

Use osKernelGetInfo to retrieve the version numbers

Data Fields
uint32_t api API version (major.minor.rev: mmnnnrrrr dec).
uint32_t kernel Kernel version (major.minor.rev: mmnnnrrrr dec).

Enumeration Type Documentation

State of the Kernel. Can be retrieved by osKernelGetState.

Enumerator
osKernelInactive 

Inactive.

The kernel is not ready yet. osKernelInitialize needs to be executed successfully.

osKernelReady 

Ready.

The kernel is not yet running. osKernelStart transfers the kernel to the running state.

osKernelRunning 

Running.

The kernel is initialized and running.

osKernelLocked 

Locked.

The kernel was locked with osKernelLock. The function osKernelUnlock unlocks it.

osKernelSuspended 

Suspended.

The kernel was suspended using osKernelSuspend. The function osKernelResume returns to normal operation.

osKernelError 

Error.

An error occurred. The kernel error handler should have been called in this state.

osKernelReserved 

Prevents enum down-size compiler optimization.

Reserved.

Function Documentation

osStatus_t osKernelInitialize ( void  )
Returns
status code that indicates the execution status of the function.
Returns osStatus_t with osOK in case of success.
Returns osError if an internal error prevents the kernel initialization.

Initialize the RTOS Kernel. Before osKernelInitialize is successfully executed no RTOS function may be called.

The RTOS kernel does not start thread switching until the function osKernelStart is called.

Code Example:

#include "RTE_Components.h"
#include CMSIS_device_header
#include "cmsis_os2.h"
/*----------------------------------------------------------------------------
* Application main thread
*---------------------------------------------------------------------------*/
void app_main (void *argument) {
// ...
for (;;) {}
}
int main (void) {
// System Initialization
SystemCoreClockUpdate();
// ...
osKernelInitialize(); // Initialize CMSIS-RTOS
osThreadNew(app_main, NULL, NULL); // Create application main thread
osKernelStart(); // Start thread execution
for (;;) {}
}
osStatus_t osKernelGetInfo ( osVersion_t version,
char *  id_buf,
uint32_t  id_size 
)
Parameters
[out]versionpointer to buffer for retrieving version information.
[out]id_bufpointer to buffer for retrieving kernel identification string.
[in]id_sizesize of buffer for kernel identification string.
Returns
status code that indicates the execution status of the function.

Retrieve API and kernel version of the underlying RTOS kernel and a human readable identifier string for the kernel.

Code Example:

void info (void) {
char infobuf[100];
osStatus_t status;
status = osKernelGetInfo(&osv, infobuf, 100);
if(status == osOK) {
printf("Kernel Information: %s\r\n", infobuf);
printf("Kernel Version : %d\r\n", osv.kernel);
printf("Kernel API Version: %d\r\n", osv.api);
}
}
osKernelState_t osKernelGetState ( void  )
Returns
current RTOS Kernel state.
The state of the kernel is represented in the osKernelState_t enum. osKernelGetState can be safely called before the RTOS is initialized.
Note
Cannot be called from Interrupt Service Routines. Calling osKernelGetState from an ISR will return osKernelError.

Code Example:

int main (void) {
// System Initialization
SystemCoreClockUpdate();
// ...
if(osKernelGetState() == osKernelInactive) { // Is the kernel initialized?
osKernelInitialize(); // Initialize CMSIS-RTOS kernel
}
;
}
osStatus_t osKernelStart ( void  )
Returns
status code that indicates the execution status of the function.

Start the RTOS Kernel and begin thread switching. The function osKernelStart will not return to its calling function in case of success.

Note
Cannot be called from Interrupt Service Routines. Calling osKernelStart from an ISR will return osErrorISR.

Code Example:

int main (void) {
// System Initialization
SystemCoreClockUpdate();
// ...
}
; // ... Start Threads
if (osKernelGetState() == osKernelReady) { // If kernel is ready to run...
osKernelStart(); // ... start thread execution
}
while(1); // only reached in case of error
}
uint32_t osKernelLock ( void  )
Returns
0 already locked, 1 locked.

Allows to lock all task switches. Code Example:

uint32_t lock;
lock = osKernelLock();
if (lock) {
}
void osKernelUnlock ( void  )

Resumes from osKernelLock.

uint32_t osKernelSuspend ( void  )
Returns
time in ticks, for how long the system can sleep or power-down.

CMSIS-RTOS provides extension for tick-less operation which is useful for applications that use extensively low-power modes where the SysTick timer is also disabled. To provide a time-tick in such power-saving modes a wake-up timer is used to derive timer intervals. The functions osKernelSuspend and osKernelResume control the tick-less operation.

Code Example:

void os_idle_demon (void) {
/* The idle demon is a system thread, running when no other thread is */
/* ready to run. */
unsigned int sleep;
for (;;) {
/* HERE: include optional user code to be executed when no task runs.*/
sleep = osKernelSuspend(); /* Suspend RTX thread scheduler */S
if (sleep) { /* How long can we sleep? */
/* "sleep" is in RTX Timer Ticks which is 1ms in this configuration */
/* Setup wake-up e.g. watchdog */
/* Enter Power-down mode */
__WFE(); /* Enter Power-down mode */
/* After Wake-up */
sleep = tc; /* Adjust with cycles slept */
}
osKernelResume(sleep); /* Resume thread scheduler */
}
}
void osKernelResume ( uint32_t  sleep_ticks)
Parameters
[in]sleep_tickstime in ticks for how long the system was in sleep or power-down mode.

See osKernelSuspend.

uint64_t osKernelGetTickCount ( void  )
Returns
RTOS kernel current tick count.
uint32_t osKernelGetTickFreq ( void  )
Returns
frequency of the kernel tick.
uint32_t osKernelGetSysTimerCount ( void  )
Returns
RTOS kernel current system timer count as 32-bit value.
uint32_t osKernelGetSysTimerFreq ( void  )
Returns
frequency of the system timer.