CMSIS-RTOS2: OS Tick API

| CMSIS-RTOS2 Version 2.1.3 Real-Time Operating System: API and RTX Reference Implementation

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions
OS Tick API

System tick timer interface for periodic RTOS Kernel Ticks defined in os_tick.h More...

## Functions
int32_t | OS_Tick_Setup (uint32_t freq, IRQHandler_t handler)
| Setup OS Tick timer to generate periodic RTOS Kernel Ticks. More...
void | OS_Tick_Enable (void)
| Enable OS Tick timer interrupt. More...
void | OS_Tick_Disable (void)
| Disable OS Tick timer interrupt. More...
void | OS_Tick_AcknowledgeIRQ (void)
| Acknowledge execution of OS Tick timer interrupt. More...
int32_t | OS_Tick_GetIRQn (void)
| Get OS Tick timer IRQ number. More...
uint32_t | OS_Tick_GetClock (void)
| Get OS Tick timer clock frequency. More...
uint32_t | OS_Tick_GetInterval (void)
| Get OS Tick timer interval reload value. More...
uint32_t | OS_Tick_GetCount (void)
| Get OS Tick timer counter value. More...
uint32_t | OS_Tick_GetOverflow (void)
| Get OS Tick timer overflow status. More...

## Description

The OS Tick API is an interface to a system timer that generates the Kernel Ticks.

All Cortex-M processors provide an unified System Tick Timer that is typically used to generate the RTOS Kernel Tick. The Cortex-A processors do not implement an unified system timer and required a device specific implementation.

CMSIS-RTOS2 provides in the directory CMSIS/RTOS2/Source the several OS Tick implementations that can be used by any RTOS kernel.

Filename | OS Tick Implementation for...
--- | ---
os_systick.c | Cortex-M SysTick timer
os_tick_gtim.c | Cortex-A Generic Timer (available in some devices)
os_tick_ptim.c | Cortex-A Private Timer (available in some devices)

Note
  The above OS Tick source files implement `weak` functions which may be overwritten by user-specific implementations.

## Function Documentation

int32_t OS_Tick_Setup | ( | uint32_t | freq,
|  | IRQHandler_t | handler
| ) |  |

Parameters

  [in] | freq | tick frequency in Hz
  [in] | handler | tick IRQ handler

Returns
  0 on success, -1 on error.

Setup OS Tick timer to generate periodic RTOS Kernel Ticks.

The timer should be configured to generate periodic interrupts at frequency specified by freq. The parameter handler defines the interrupt handler function that is called.

The timer should only be initialized and configured but must not be started to create interrupts. The RTOS kernel calls the function OS_Tick_Enable to start the timer interrupts.

Cortex-M SysTick implementation:

#ifndef SYSTICK_IRQ_PRIORITY
#define SYSTICK_IRQ_PRIORITY 0xFFU
#endif
static uint8_t PendST;
int32_t OS_Tick_Setup (uint32_t freq, IRQHandler_t handler) {
(void)handler;
uint32_t load;
if (freq == 0U) {
return (-1);
}
load = (SystemCoreClock / freq) - 1U;
if (load > 0x00FFFFFFU) {
return (-1);
}
NVIC_SetPriority(SysTick_IRQn, SYSTICK_IRQ_PRIORITY);
SysTick->CTRL = SysTick_CTRL_CLKSOURCE_Msk | SysTick_CTRL_TICKINT_Msk;
SysTick->LOAD = load;
SysTick->VAL = 0U;
PendST = 0U;
return (0);
}

int32_t OS_Tick_Enable | ( | void |  | ) |

Enable OS Tick timer interrupt.

Enable and start the OS Tick timer to generate periodic RTOS Kernel Tick interrupts.

Cortex-M SysTick implementation:

int32_t OS_Tick_Enable (void) {
if (PendST != 0U) {
PendST = 0U;
SCB->ICSR = SCB_ICSR_PENDSTSET_Msk;
}
SysTick->CTRL |= SysTick_CTRL_ENABLE_Msk;
return (0);
}

int32_t OS_Tick_Disable | ( | void |  | ) |

Disable OS Tick timer interrupt.

Stop the OS Tick timer and disable generation of RTOS Kernel Tick interrupts.

Cortex-M SysTick implementation:

int32_t OS_Tick_Disable (void) {
SysTick->CTRL &= ~SysTick_CTRL_ENABLE_Msk;
if ((SCB->ICSR & SCB_ICSR_PENDSTSET_Msk) != 0U) {
SCB->ICSR = SCB_ICSR_PENDSTCLR_Msk;
PendST = 1U;
}
return (0);
}

int32_t OS_Tick_AcknowledgeIRQ | ( | void |  | ) |

Acknowledge execution of OS Tick timer interrupt.

Acknowledge the execution of the OS Tick timer interrupt function, for example clear the pending flag.

Cortex-M SysTick implementation:

int32_t OS_Tick_AcknowledgeIRQ (void) {
(void)SysTick->CTRL;
return (0);
}

int32_t OS_Tick_GetIRQn | ( | void |  | ) |

Returns
  OS Tick IRQ number

Get OS Tick timer IRQ number.

Return the numeric value that identifies the interrupt called by the OS Tick timer.

Cortex-M SysTick implementation:

int32_t OS_Tick_GetIRQn (void) {
return (SysTick_IRQn);
}

uint32_t OS_Tick_GetClock | ( | void |  | ) |

Returns
  OS Tick timer clock frequency in Hz

Get OS Tick timer clock frequency.

Return the input clock frequency of the OS Tick timer. This is the increment rate of the counter value returned by the function OS_Tick_GetCount. This function is used to by the function osKernelGetSysTimerFreq.

Cortex-M SysTick implementation:

uint32_t OS_Tick_GetClock (void) {
return (SystemCoreClock);
}

uint32_t OS_Tick_GetInterval | ( | void |  | ) |

Returns
  OS Tick timer interval reload value

Get OS Tick timer interval reload value.

Return the number of counter ticks between to periodic OS Tick timer interrupts.

Cortex-M SysTick implementation:

uint32_t OS_Tick_GetInterval (void) {
return (SysTick->LOAD + 1U);
}

uint32_t OS_Tick_GetCount | ( | void |  | ) |

Returns
  OS Tick timer counter value

Get OS Tick timer counter value.

Return the current value of the OS Tick counter: 0 ... (reload value -1). The reload value is returned by the function OS_Tick_GetInterval. The OS Tick timer counter value is used to by the function osKernelGetSysTimerCount.

Cortex-M SysTick implementation:

uint32_t OS_Tick_GetCount (void) {
uint32_t load = SysTick->LOAD;
return (load - SysTick->VAL);
}

OS_Tick_GetOverflow | ( | void |  | ) |

Returns
  OS Tick overflow status (1 - overflow, 0 - no overflow).

Get OS Tick timer overflow status.

Return the state of OS Tick timer interrupt pending bit that indicates timer overflows to adjust SysTimer calculations.

Cortex-M SysTick implementation:

uint32_t OS_Tick_GetOverflow (void) {
return ((SysTick->CTRL >> 16) & 1U);
}