begriffs open source - cmsis/blob - CMSIS/DoxyGen/RTOS2/src/cmsis_os2_tick.txt

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 //  ==== OS Tick API ====
   3 /**
   4 \addtogroup CMSIS_RTOS_TickAPI OS Tick API
   5 \ingroup CMSIS_RTOS
   6 \brief Provides a low level API between an device agnostic RTOS implementation and specific periodic timer capabilities.
   7 \details The CMSIS OS Tick API may be used by an arbitrary RTOS implementation to be easily potable across a wide range
   8 of controllers.
   9
  10 Cortex-M devices share a common System Tick Timer to be used for RTOS timing purposes. Cortex-A devices do not have a
  11 common System Tick Timer but various vendor specific solution. In order to make it easier to enable an RTOS, such as RTX5,
  12 to support a wide range of Cortex Microcontrollers the OS Tick API is used to encapsulate the device specific timer
  13 implementations.
  14
  15 A default implementation for Cortex-M System Tick Timer can be found in \ref os_systick.c.
  16
  17 \note The default implementation is defined \c weak thus it can easily be overwritten by an alternative user implementation.
  18
  19 \include "../../RTOS2/Source/os_systick.c"
  20
  21 @{
  22 */
  23
  24 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  25 /**
  26 \fn int32_t  OS_Tick_Setup (uint32_t freq, IRQHandler_t handler)
  27 \details Setup the a hardware time to be used for generating periodic tick interrupts to the RTOS.
  28
  29 The timer should be configured to generate interrupts at the given frequency.
  30 The given callback should be used as the interrupt handler.
  31
  32 The timer should only be initialized and configured accordingly. It must not be started nor
  33 creating interrupts before \ref OS_Tick_Enable is called.
  34
  35 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
  36 like the following example:
  37
  38 \code
  39 #ifndef SYSTICK_IRQ_PRIORITY
  40 #define SYSTICK_IRQ_PRIORITY    0xFFU
  41 #endif
  42
  43 static uint8_t PendST;
  44
  45 int32_t  OS_Tick_Setup (uint32_t freq, IRQHandler_t handler) {
  46   (void)handler;
  47   uint32_t load;
  48
  49   if (freq == 0U) {
  50     return (-1);
  51   }
  52
  53   load = (SystemCoreClock / freq) - 1U;
  54   if (load > 0x00FFFFFFU) {
  55     return (-1);
  56   }
  57
  58   NVIC_SetPriority(SysTick_IRQn, SYSTICK_IRQ_PRIORITY);
  59
  60   SysTick->CTRL =  SysTick_CTRL_CLKSOURCE_Msk | SysTick_CTRL_TICKINT_Msk;
  61   SysTick->LOAD =  load;
  62   SysTick->VAL  =  0U;
  63
  64   PendST = 0U;
  65
  66   return (0);
  67 }
  68 \endcode
  69 */
  70
  71 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  72 /**
  73 \fn int32_t  OS_Tick_Enable (void)
  74 \details Start the timer to count and enable generation of periodic interrupts.
  75
  76 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
  77 like the following example:
  78
  79 \code
  80 int32_t  OS_Tick_Enable (void) {
  81
  82   if (PendST != 0U) {
  83     PendST = 0U;
  84     SCB->ICSR = SCB_ICSR_PENDSTSET_Msk;
  85   }
  86
  87   SysTick->CTRL |=  SysTick_CTRL_ENABLE_Msk;
  88
  89   return (0);
  90 }
  91 \endcode
  92 */
  93
  94 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  95 /**
  96 \fn int32_t  OS_Tick_Disable (void)
  97 \details Stop the timer from counting and disable generation of periodic interrupts.
  98
  99 After a call to this function the timer must not generate any further interrupt.
 100
 101 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
 102 like the following example:
 103
 104 \code
 105 int32_t  OS_Tick_Disable (void) {
 106
 107   SysTick->CTRL &= ~SysTick_CTRL_ENABLE_Msk;
 108
 109   if ((SCB->ICSR & SCB_ICSR_PENDSTSET_Msk) != 0U) {
 110     SCB->ICSR = SCB_ICSR_PENDSTCLR_Msk;
 111     PendST = 1U;
 112   }
 113
 114   return (0);
 115 }
 116 \endcode
 117 */
 118
 119 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 120 /**
 121 \fn int32_t  OS_Tick_AcknowledgeIRQ (void)
 122 \details Acknowledge the pending tick interrupt, i.e. by clear the pending flag.
 123
 124 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
 125 like the following example:
 126
 127 \code
 128 int32_t  OS_Tick_AcknowledgeIRQ (void) {
 129   (void)SysTick->CTRL;
 130   return (0);
 131 }
 132 \endcode
 133 */
 134
 135 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 136 /**
 137 \fn int32_t OS_Tick_GetIRQn (void)
 138 \details Return the actual numeric value to identify the interrupt used by the timer.
 139
 140 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
 141 like the following example:
 142
 143 \code
 144 int32_t  OS_Tick_GetIRQn (void) {
 145   return (SysTick_IRQn);
 146 }
 147 \endcode
 148 */
 149
 150 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 151 /**
 152 \fn uint32_t OS_Tick_GetClock (void)
 153 \details Return the clock frequency the timer operates at, i.e. giving the rate the internal counter value is incremented at.
 154
 155 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
 156 like the following example:
 157
 158 \code
 159 uint32_t OS_Tick_GetClock (void) {
 160   return (SystemCoreClock);
 161 }
 162 \endcode
 163 */
 164
 165 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 166 /**
 167 \fn uint32_t OS_Tick_GetInterval (void)
 168 \details Return the actual counting interval used for the internal counter value between to consecutive tick interrupts.
 169
 170 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
 171 like the following example:
 172
 173 \code
 174 uint32_t OS_Tick_GetInterval (void) {
 175   return (SysTick->LOAD + 1U);
 176 }
 177 \endcode
 178 */
 179
 180 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 181 /**
 182 \fn uint32_t OS_Tick_GetCount (void)
 183 \details Return the current value of the internal counter between 0 to \ref OS_Tick_GetInterval() - 1.
 184
 185 This value is used to calculate subticks, i.e. OS_Tick_GetCount() / OS_Tick_GetInterval(), if a higher time resolution is needed.
 186
 187 \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.
 188
 189 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
 190 like the following example:
 191
 192 \code
 193 uint32_t OS_Tick_GetCount (void) {
 194   uint32_t load = SysTick->LOAD;
 195   return  (load - SysTick->VAL);
 196 }
 197 \endcode
 198 */
 199
 200 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 201 /**
 202 \fn OS_Tick_GetOverflow (void)
 203 \details Return the current state of the overflow signal, i.e. the timers interrupt pending bit.
 204
 205 This information can be used to calculate an intermediate (but correct) tick value while the tick
 206 interrupt is pending but blocked.
 207
 208 For a simple Cortex-M device using the built in SystemTick timer the default implementation looks
 209 like the following example:
 210
 211 \code
 212 uint32_t OS_Tick_GetOverflow (void) {
 213   return ((SysTick->CTRL >> 16) & 1U);
 214 }
 215 \endcode
 216 */
 217
 218 /** @} */ /* group CMSIS_RTOS_TickAPI */