OS Tick 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...
void	OS_Tick_Enable (void)
	Enable OS Tick. More...
void	OS_Tick_Disable (void)
	Disable OS Tick. More...
void	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.1
 * @date     24. November 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"

//lint -emacro((923,9078),SCB,SysTick) "cast from unsigned long to pointer"
#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) {
    //lint -e{904} "Return statement before end of function"
    return (-1);
  }

  load = (SystemCoreClock / freq) - 1U;
  if (load > 0x00FFFFFFU) {
    //lint -e{904} "Return statement before end of function"
    return (-1);
  }

  // Set SysTick Interrupt Priority
#if   ((defined(__ARM_ARCH_8M_MAIN__) && (__ARM_ARCH_8M_MAIN__ != 0)) || \
       (defined(__CORTEX_M)           && (__CORTEX_M           == 7U)))
  SCB->SHPR[11] = SYSTICK_IRQ_PRIORITY;
#elif  (defined(__ARM_ARCH_8M_BASE__) && (__ARM_ARCH_8M_BASE__ != 0))
  SCB->SHPR[1] |= ((uint32_t)SYSTICK_IRQ_PRIORITY << 24);
#elif ((defined(__ARM_ARCH_7M__)      && (__ARM_ARCH_7M__      != 0)) || \
       (defined(__ARM_ARCH_7EM__)     && (__ARM_ARCH_7EM__     != 0)))
  SCB->SHP[11]  = SYSTICK_IRQ_PRIORITY;
#elif  (defined(__ARM_ARCH_6M__)      && (__ARM_ARCH_6M__      != 0))
  SCB->SHP[1]  |= ((uint32_t)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 void OS_Tick_Enable (void) {

  if (PendST != 0U) {
    PendST = 0U;
    SCB->ICSR = SCB_ICSR_PENDSTSET_Msk;
  }

  SysTick->CTRL |=  SysTick_CTRL_ENABLE_Msk;
}

/// Disable OS Tick.
__WEAK void 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;
  }
}

// Acknowledge OS Tick IRQ.
__WEAK void OS_Tick_AcknowledgeIRQ (void) {
  (void)SysTick->CTRL;
}

// Get OS Tick IRQ number.
__WEAK int32_t  OS_Tick_GetIRQn (void) {
  return ((int32_t)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

)

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

)

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

)

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