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. | |
osStatus_t | osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size) |
Get RTOS Kernel Information. | |
osKernelState_t | osKernelGetState (void) |
Get the current RTOS Kernel state. | |
osStatus_t | osKernelStart (void) |
Start the RTOS Kernel scheduler. | |
int32_t | osKernelLock (void) |
Lock the RTOS Kernel scheduler. | |
int32_t | osKernelUnlock (void) |
Unlock the RTOS Kernel scheduler. | |
int32_t | osKernelRestoreLock (int32_t lock) |
Restore the RTOS Kernel scheduler lock state. | |
uint32_t | osKernelSuspend (void) |
Suspend the RTOS Kernel scheduler. | |
void | osKernelResume (uint32_t sleep_ticks) |
Resume the RTOS Kernel scheduler. | |
uint32_t | osKernelGetTickCount (void) |
Get the RTOS kernel tick count. | |
uint32_t | osKernelGetTickFreq (void) |
Get the RTOS kernel tick frequency. | |
uint32_t | osKernelGetSysTimerCount (void) |
Get the RTOS kernel system timer count. | |
uint32_t | osKernelGetSysTimerFreq (void) |
Get the RTOS kernel system timer frequency. | |
osStatus_t | osKernelProtect (uint32_t safety_class) |
Protect the RTOS Kernel scheduler access. | |
osStatus_t | osKernelDestroyClass (uint32_t safety_class, uint32_t mode) |
Destroy objects for specified safety classes. | |
void | osFaultResume (void) |
Resume normal operation when exiting exception faults. | |
Provides version/system information and starts/controls the RTOS Kernel.
The kernel Information and Control function group allows to:
Code Example
struct osVersion_t |
Version information.
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). |
enum osKernelState_t |
Kernel state.
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. |
osStatus_t osKernelInitialize | ( | void | ) |
Initialize the RTOS Kernel.
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:
Code Example
osStatus_t osKernelGetInfo | ( | osVersion_t * | version, |
char * | id_buf, | ||
uint32_t | id_size | ||
) |
Get RTOS Kernel Information.
[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. |
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:
Code Example
osKernelState_t osKernelGetState | ( | void | ) |
Get the 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:
Code Example
osStatus_t osKernelStart | ( | void | ) |
Start the RTOS Kernel scheduler.
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:
Code Example
int32_t osKernelLock | ( | void | ) |
Lock the RTOS Kernel scheduler.
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:
Code Example
int32_t osKernelUnlock | ( | void | ) |
Unlock the RTOS Kernel scheduler.
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:
Code Example
int32_t osKernelRestoreLock | ( | int32_t | lock | ) |
Restore the RTOS Kernel scheduler lock state.
[in] | lock | lock state obtained by osKernelLock or osKernelUnlock. |
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:
Code Example
uint32_t osKernelSuspend | ( | void | ) |
Suspend the RTOS Kernel scheduler.
CMSIS-RTOS2 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 RTOS 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.
Code Example
void osKernelResume | ( | uint32_t | sleep_ticks | ) |
Resume the RTOS Kernel scheduler.
[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 RTOS kernel scheduler and thus wakes up the system from sleep mode.
Code Example
uint32_t osKernelGetTickCount | ( | void | ) |
Get the RTOS kernel tick count.
The function osKernelGetTickCount returns the current RTOS kernel tick count.
Code Example
Due to the limited value range used for the tick count it may overflow during runtime, i.e. after 232 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
uint32_t osKernelGetTickFreq | ( | void | ) |
Get the RTOS kernel tick frequency.
The function osKernelGetTickFreq returns the frequency of the current RTOS kernel tick.
uint32_t osKernelGetSysTimerCount | ( | void | ) |
Get the RTOS kernel system timer count.
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.
Code Example
uint32_t osKernelGetSysTimerFreq | ( | void | ) |
Get the RTOS kernel system timer frequency.
The function osKernelGetSysTimerFreq returns the frequency of the current RTOS kernel system timer.
osStatus_t osKernelProtect | ( | uint32_t | safety_class | ) |
Protect the RTOS Kernel scheduler access.
[in] | safety_class | safety class. |
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.
Possible osStatus_t return values:
Code Example:
osStatus_t osKernelDestroyClass | ( | uint32_t | safety_class, |
uint32_t | mode | ||
) |
Destroy objects for specified safety classes.
[in] | safety_class | safety class. |
[in] | mode | safety mode. |
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:
Code Example:
void osFaultResume | ( | void | ) |
Resume normal operation when exiting exception faults.
Resume normal RTOS operation when exiting exception faults.
Code Example: