Kernel Information and Control

Provides version/system information and starts/controls 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 = 0x7FFFFFFF }
	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...
int32_t	osKernelLock (void)
	Lock the RTOS Kernel scheduler. More...
int32_t	osKernelUnlock (void)
	Unlock the RTOS Kernel scheduler. More...
int32_t	osKernelRestoreLock (int32_t lock)
	Restore the RTOS Kernel scheduler lock state. More...
uint32_t	osKernelSuspend (void)
	Suspend the RTOS Kernel scheduler. More...
void	osKernelResume (uint32_t sleep_ticks)
	Resume the RTOS Kernel scheduler. More...
uint32_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...
osStatus_t	osKernelProtect (uint32_t safety_class)
	Protect the RTOS Kernel scheduler access. More...
osStatus_t	osKernelDestroyClass (uint32_t safety_class, uint32_t mode)
	Destroy objects for specified safety classes. More...
void	osFaultResume (void)
	Resume normal operation when exiting exception faults. More...

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.

Note

The kernel information and control functions cannot be called from Interrupt Service Routines.

The kernel initialization for RTX5 is documented in System Startup.

Code Example

/*----------------------------------------------------------------------------
 * 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 (;;) {}
}

---

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

enum osKernelState_t

State of the kernel as retrieved by osKernelGetState. In case osKernelGetState fails or if it is called from an ISR, it will return osKernelError, otherwise it returns the kernel state.

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 functions osKernelUnlock or osKernelRestoreLock unlocks it.
osKernelSuspended	Suspended. The kernel was suspended using osKernelSuspend. The function osKernelResume returns to normal operation.
osKernelError	Error. An error occurred.
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.

The function osKernelInitialize initializes the RTOS Kernel. Before it is successfully executed, only the functions osKernelGetInfo and osKernelGetState may be called.

Possible osStatus_t return values:

• osOK in case of success.
• osError if an unspecific error occurred.
• osErrorISR if called from an Interrupt Service Routine.
• osErrorNoMemory if no memory could be reserved for the operation.

Note

This function cannot be called from Interrupt Service Routines.

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]	version	pointer to buffer for retrieving version information.
[out]	id_buf	pointer to buffer for retrieving kernel identification string.
[in]	id_size	size of buffer for kernel identification string.

Returns

status code that indicates the execution status of the function.

The function osKernelGetInfo retrieves the API and kernel version of the underlying RTOS kernel and a human readable identifier string for the kernel. It can be safely called before the RTOS is initialized or started (call to osKernelInitialize or osKernelStart).

Possible osStatus_t return values:

• osOK in case of success.
• osError if an unspecific error occurred.

Note

This function may be called from Interrupt Service Routines.

Code Example

void info (void) {
  char infobuf[100];
  osVersion_t osv;
  osStatus_t status;
 
  status = osKernelGetInfo(&osv, infobuf, sizeof(infobuf));
  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 function osKernelGetState returns the current state of the kernel and can be safely called before the RTOS is initialized or started (call to osKernelInitialize or osKernelStart). In case it fails it will return osKernelError, otherwise it returns the kernel state (refer to osKernelState_t for the list of kernel states).

Possible osKernelState_t return values:

• osKernelError if an unspecific error occurred.
• the actual kernel state otherwise.

Note

This function may be called from Interrupt Service Routines.

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.

The function osKernelStart starts the RTOS kernel and begins thread switching. It will not return to its calling function in case of success. Before it is successfully executed, only the functions osKernelGetInfo, osKernelGetState, and object creation functions (osXxxNew) may be called.

At least one initial thread should be created prior osKernelStart, see osThreadNew.

Possible osStatus_t return values:

• osError if an unspecific error occurred.
• osErrorISR if called from an Interrupt Service Routine.

Note

This function cannot be called from Interrupt Service Routines.

Code Example

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

int32_t osKernelLock

(

void

)

Returns

previous lock state (1 - locked, 0 - not locked, error code if negative).

The function osKernelLock allows to lock all task switches. It returns the previous value of the lock state (1 if it was locked, 0 if it was unlocked), or a negative number representing an error code otherwise (refer to osStatus_t).

Possible osStatus_t return values:

• osError if an unspecific error occurred.
• osErrorISR if called from an Interrupt Service Routine.
• osErrorSafetyClass if the calling thread safety class is lower than the kernel protect safety class.

Note

This function cannot be called from Interrupt Service Routines.

Code Example

int32_t state = osKernelLock();
// ... critical code
osKernelRestore(state);

int32_t osKernelUnlock

(

void

)

Returns

previous lock state (1 - locked, 0 - not locked, error code if negative).

The function osKernelUnlock resumes from osKernelLock. It returns the previous value of the lock state (1 if it was locked, 0 if it was unlocked), or a negative number representing an error code otherwise (refer to osStatus_t).

Possible osStatus_t return values:

• osError if an unspecific error occurred.
• osErrorISR if called from an Interrupt Service Routine.

Note

This function cannot be called from Interrupt Service Routines.

Code Example

int32_t sl = osKernelLock();
// ... critical code
{
  int32_t su = osKernelUnlock();
  // ... uncritical code
  osKernelRestoreLock(su);
}
// ... critical code
osKernelRestoreLock(sl);

int32_t osKernelRestoreLock

(

int32_t

lock

)

Parameters

[in]

lock

lock state obtained by osKernelLock or osKernelUnlock.

Returns

new lock state (1 - locked, 0 - not locked, error code if negative).

The function osKernelRestoreLock restores the previous lock state after osKernelLock or osKernelUnlock.

The argument lock specifies the lock state as obtained by osKernelLock or osKernelUnlock.

The function returns the new value of the lock state (1 if it was locked, 0 if it was unlocked), or a negative number representing an error code otherwise (refer to osStatus_t).

Possible osStatus_t return values:

• osError if an unspecific error occurred.
• osErrorISR if called from interrupt other than fault or osWatchdogAlarm_Handler.
• osErrorSafetyClass if the calling thread safety class is lower than the kernel protect safety class.

Code Example

int32_t sl = osKernelLock();
// ... critical code
{
  int32_t su = osKernelUnlock();
  // ... uncritical code
  osKernelRestoreLock(su);
}
// ... critical code
osKernelRestoreLock(sl);

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 function osKernelSuspend suspends the RTX kernel scheduler and thus enables sleep modes.

The return value can be used to determine the amount of system ticks until the next tick-based kernel event will occur, i.e. a delayed thread becomes ready again. It is recommended to set up the low power timer to generate a wake-up interrupt based on this return value.

Note

This function cannot be called from Interrupt Service Routines.

Code Example

void osRtxIdleThread (void) {
                                               /* The idle thread is 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 */
 
    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  */
 
      __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_ticks

time in ticks for how long the system was in sleep or power-down mode.

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 function osKernelResume enables the RTX kernel scheduler and thus wakes up the system from sleep mode.

Note

This function cannot be called from Interrupt Service Routines.

Code Example

void osRtxIdleThread (void) {
                                               /* The idle thread is 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 */
 
    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  */
 
      __WFE();                                 /* Enter Power-down mode        */
      
                                               /* After Wake-up                */
      sleep = tc;                              /* Adjust with cycles slept     */  
    }
 
    osKernelResume(sleep);                     /* Resume thread scheduler      */
  }
}

uint32_t osKernelGetTickCount

(

void

)

Returns

RTOS kernel current tick count.

The function osKernelGetTickCount returns the current RTOS kernel tick count.

Note

This function may be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
 
void Thread_1 (void *arg)  {                // Thread function
  uint32_t tick;

  tick = osKernelGetTickCount();            // retrieve the number of system ticks
  for (;;) {
    tick += 1000;                           // delay 1000 ticks periodically
    osDelayUntil(tick);
    // ...
  }
}

Due to the limited value range used for the tick count it may overflow during runtime, i.e. after 2³² ticks which are roughly 49days @ 1ms. Typically one has not to take special care of this unless a monotonic counter is needed. For such a case an additional 64bit tick counter can be implemented as follows. The given example needs GetTick() called at least twice per tick overflow to work properly.

Code Example

uint64_t GetTick(void) {
  static uint32_t tick_h = 0U;
  static uint32_t tick_l = 0U;
         uint32_t tick;

  tick = osKernelGetTickCount();
  if (tick < tick_l) {
    tick_h++;
  }
  tick_l = tick;

  return (((uint64_t)tick_h << 32) | tick_l);
}

uint32_t osKernelGetTickFreq

(

void

)

Returns

frequency of the kernel tick in hertz, i.e. kernel ticks per second.

The function osKernelGetTickFreq returns the frequency of the current RTOS kernel tick.

Note

This function may be called from Interrupt Service Routines.

uint32_t osKernelGetSysTimerCount

(

void

)

Returns

RTOS kernel current system timer count as 32-bit value.

The function osKernelGetSysTimerCount returns the current RTOS kernel system timer as a 32-bit value. The value is a rolling 32-bit counter that is composed of the kernel system interrupt timer value and the counter that counts these interrupts (RTOS kernel ticks).

This function allows the implementation of very short timeout checks below the RTOS tick granularity. Such checks might be required when checking for a busy status in a device or peripheral initialization routine, see code example below.

Note

This function may be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
 
void SetupDevice (void)  {
  uint32_t tick;
  
  // Calculating 100us timeout in system timer ticks
  const uint32_t timeout = 100U * osKernelGetSysTimerFreq() / 1000000u;
  
  tick = osKernelGetSysTimerCount();             // 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 ((osKernelGetSysTimerCount() - tick) < timeout));
  if (Device.Busy)  {              
    ;                                            // in case device still busy, signal error
  }
                                                 // start interacting with device
}

uint32_t osKernelGetSysTimerFreq

(

void

)

Returns

frequency of the system timer in hertz, i.e. timer ticks per second.

The function osKernelGetSysTimerFreq returns the frequency of the current RTOS kernel system timer.

Note

This function may be called from Interrupt Service Routines.

osStatus_t osKernelProtect

(

uint32_t

safety_class

)

Parameters

[in]

safety_class

safety class.

Returns

status code that indicates the execution status of the function.

The function osKernelProtect configures kernel access protection. After its successful execution, only threads with safety class equal or higher than the safety_class specified in the argument can execute kernel control functions.

• osKernelLock
• osKernelUnlock
• osKernelRestoreLock
• osKernelSuspend
• osKernelResume
• osKernelProtect

Possible osStatus_t return values:

• osOK in case of success.
• osErrorParameter if safety_class is invalid.
• osError if kernel is not in ready or running state.
• osErrorISR if called from an Interrupt Service Routine.
• osErrorSafetyClass if the calling thread safety class is lower than the kernel protect safety class.

Note

This function cannot be called from Interrupt Service Routines.

Code Example:

#include "cmsis_os2.h"
 
void ProtectKernelControlFunctions (void) {
  osStatus_t status;
 
  status = osKernelProtect(4U); // Enable Kernel Control for threads with safety class 4 or higher
  // verify status value here.
}

osStatus_t osKernelDestroyClass	(	uint32_t	safety_class,
		uint32_t	mode
	)

Parameters

[in]	safety_class	safety class.
[in]	mode	safety mode.

Returns

status code that indicates the execution status of the function.

The function osKernelDestroyClass destroys RTOS objects based on safety class assignment. safety_class provides the reference safety class value, while mode is considered as a bitmap that additionally specifies the safety classes to be destroyed.

If osSafetyWithSameClass is set in mode than the RTOS objects with safety class value equal to safety_class will be destroyed.
If osSafetyWithLowerClass is set in mode than the RTOS objects with safety class value lower than safety_class will be destroyed.

Possible osStatus_t return values:

• osOK in case of success.
• osErrorParameter if safety_class is invalid.
• osErrorResource if no other READY thread exists.
• osErrorISR if called from interrupt other than osWatchdogAlarm_Handler.
• osErrorSafetyClass if the calling thread safety class is lower than the kernel protect safety class.

Code Example:

#include "cmsis_os2.h"
 
void DestroyNonCriticalClasses (void) {
  osStatus_t status;
 
  status = osKernelDestroyClass(4U, osSafetyWithSameClass | osSafetyWithLowerClass); // Destroy objects with safety class 4 or lower
  // verify status value here.
}

void osFaultResume

(

void

)

Resume normal RTOS operation when exiting exception faults.

Code Example:

void HardFault_Handler (void) {
  __ASM volatile (
    "...                          \n\t" // Enter assembly and handle faults
    "...                          \n\t"
    "ldr  r0,=osFaultResume       \n\t" // Before exiting the handler load and
    "bx   r0                      \n\t" // jump to osFaultResume
  );
}