CMSIS-RTOS2: OS Tick API

| CMSIS-RTOS2 Version 2.1.1 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
CMSIS-RTOS2 API

Provides a low level API between an device agnostic RTOS implementation and specific periodic timer capabilities. More...

## Functions
int32_t | OS_Tick_Setup (uint32_t freq, IRQHandler_t handler)
| Setup OS Tick. More...
int32_t | OS_Tick_Enable (void)
| Enable OS Tick. More...
int32_t | OS_Tick_Disable (void)
| Disable OS Tick. More...
int32_t | OS_Tick_AcknowledgeIRQ (void)
| Acknowledge OS Tick IRQ. More...
int32_t | OS_Tick_GetIRQn (void)
| Get OS Tick IRQ number. More...
uint32_t | OS_Tick_GetClock (void)
| Get OS Tick clock. More...
uint32_t | OS_Tick_GetInterval (void)
| Get OS Tick interval. More...
uint32_t | OS_Tick_GetCount (void)
| Get OS Tick count value. More...
uint32_t | OS_Tick_GetOverflow (void)
| Get OS Tick overflow status. More...

## Description

The CMSIS OS Tick API may be used by an arbitrary RTOS implementation to be easily potable across a wide range of controllers.

Cortex-M devices share a common System Tick Timer to be used for RTOS timing purposes. Cortex-A devices do not have a common System Tick Timer but various vendor specific solution. In order to make it easier to enable an RTOS, such as RTX5, to support a wide range of Cortex Microcontrollers the OS Tick API is used to encapsulate the device specific timer implementations.

A default implementation for Cortex-M System Tick Timer can be found in os_systick.c.

Note
  The default implementation is defined `weak` thus it can easily be overwritten by an alternative user implementation.

/**************************************************************************//**
* @file os_systick.c
* @brief CMSIS OS Tick SysTick implementation
* @version V1.0.0
* @date 05. June 2017
******************************************************************************/
/*
* Copyright (c) 2017-2017 ARM Limited. All rights reserved.
*
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the License); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an AS IS BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include "os_tick.h"
#include "RTE_Components.h"
#include CMSIS_device_header
#ifdef SysTick
#ifndef SYSTICK_IRQ_PRIORITY
#define SYSTICK_IRQ_PRIORITY 0xFFU
#endif
static uint8_t PendST;
// Setup OS Tick.
__WEAK int32_t OS_Tick_Setup (uint32_t freq, IRQHandler_t handler) {
uint32_t load;
(void)handler;
if (freq == 0U) {
return (-1);
}
load = (SystemCoreClock / freq) - 1U;
if (load > 0x00FFFFFFU) {
return (-1);
}
// Set SysTick Interrupt Priority
#if ((defined(__ARM_ARCH_8M_MAIN__) && (__ARM_ARCH_8M_MAIN__ == 1U)) || \
(defined(__CORTEX_M) && (__CORTEX_M == 7U)))
SCB->SHPR[11] = SYSTICK_IRQ_PRIORITY;
#elif (defined(__ARM_ARCH_8M_BASE__) && (__ARM_ARCH_8M_BASE__ == 1U))
SCB->SHPR[1] |= (SYSTICK_IRQ_PRIORITY << 24);
#elif ((defined(__ARM_ARCH_7M__) && (__ARM_ARCH_7M__ == 1U)) || \
(defined(__ARM_ARCH_7EM__) && (__ARM_ARCH_7EM__ == 1U)))
SCB->SHP[11] = SYSTICK_IRQ_PRIORITY;
#elif (defined(__ARM_ARCH_6M__) && (__ARM_ARCH_6M__ == 1U))
SCB->SHP[1] |= (SYSTICK_IRQ_PRIORITY << 24);
#else
#error "Unknown ARM Core!"
#endif
SysTick->CTRL = SysTick_CTRL_CLKSOURCE_Msk | SysTick_CTRL_TICKINT_Msk;
SysTick->LOAD = load;
SysTick->VAL = 0U;
PendST = 0U;
return (0);
}
/// Enable OS Tick.
__WEAK 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);
}
/// Disable OS Tick.
__WEAK 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);
}
// Acknowledge OS Tick IRQ.
__WEAK int32_t OS_Tick_AcknowledgeIRQ (void) {
(void)SysTick->CTRL;
return (0);
}
// Get OS Tick IRQ number.
__WEAK int32_t OS_Tick_GetIRQn (void) {
return (SysTick_IRQn);
}
// Get OS Tick clock.
__WEAK uint32_t OS_Tick_GetClock (void) {
return (SystemCoreClock);
}
// Get OS Tick interval.
__WEAK uint32_t OS_Tick_GetInterval (void) {
return (SysTick->LOAD + 1U);
}
// Get OS Tick count value.
__WEAK uint32_t OS_Tick_GetCount (void) {
uint32_t load = SysTick->LOAD;
return (load - SysTick->VAL);
}
// Get OS Tick overflow status.
__WEAK uint32_t OS_Tick_GetOverflow (void) {
return ((SysTick->CTRL >> 16) & 1U);
}
#endif // SysTick

## 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 the a hardware time to be used for generating periodic tick interrupts to the RTOS.

The timer should be configured to generate interrupts at the given frequency. The given callback should be used as the interrupt handler.

The timer should only be initialized and configured accordingly. It must not be started nor creating interrupts before OS_Tick_Enable is called.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

#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 |  | ) |

Returns
  0 on success, -1 on error.

Start the timer to count and enable generation of periodic interrupts.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

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

Returns
  0 on success, -1 on error.

Stop the timer from counting and disable generation of periodic interrupts.

After a call to this function the timer must not generate any further interrupt.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

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

Returns
  0 on success, -1 on error.

Acknowledge the pending tick interrupt, i.e. by clear the pending flag.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

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

int32_t OS_Tick_GetIRQn | ( | void |  | ) |

Returns
  OS Tick IRQ number.

Return the actual numeric value to identify the interrupt used by the timer.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

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

uint32_t OS_Tick_GetClock | ( | void |  | ) |

Returns
  OS Tick clock in Hz.

Return the clock frequency the timer operates at, i.e. giving the rate the internal counter value is incremented at.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

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

uint32_t OS_Tick_GetInterval | ( | void |  | ) |

Returns
  OS Tick interval.

Return the actual counting interval used for the internal counter value between to consecutive tick interrupts.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

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

uint32_t OS_Tick_GetCount | ( | void |  | ) |

Returns
  OS Tick count value.

Return the current value of the internal counter between 0 to OS_Tick_GetInterval() - 1.

This value is used to calculate subticks, i.e. OS_Tick_GetCount() / OS_Tick_GetInterval(), if a higher time resolution is needed.

Note
  If the hardware is a down-counter (such as the Cortex-M System Tick Timer) one has to calculate the corresponding up-counter value.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

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).

Return the current state of the overflow signal, i.e. the timers interrupt pending bit.

This information can be used to calculate an intermediate (but correct) tick value while the tick interrupt is pending but blocked.

For a simple Cortex-M device using the built in SystemTick timer the default implementation looks like the following example:

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