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 \brief System tick timer interface for periodic RTOS Kernel Ticks defined in <b>%os_tick.h</b>
   6 \details
   7
   8 The <b>OS Tick API</b> is an interface to a system timer that generates the Kernel Ticks.
   9
  10 All Cortex-M processors provide an unified System Tick Timer that is typically used to generate the RTOS Kernel Tick.
  11 The Cortex-A processors do not implement an unified system timer and required a device specific implementation.
  12
  13 CMSIS-RTOS2 provides in the directory \ref directory "CMSIS/RTOS2/Source" the several OS Tick implementations that can be used by any RTOS kernel.
  14
  15 Filename                 | OS Tick Implementation for...
  16 :------------------------|:-----------------------------------------------------------------------
  17 \b %os_systick.c         | Cortex-M SysTick timer
  18 \b %os_tick_gtim.c       | Cortex-A Generic Timer (available in some devices)
  19 \b %os_tick_ptim.c       | Cortex-A Private Timer (available in some devices)
  20
  21 \note The above OS Tick source files implement \c weak functions which may be overwritten by user-specific implementations.
  22
  23 @{
  24 */
  25
  26 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  27 /**
  28 \fn int32_t  OS_Tick_Setup (uint32_t freq, IRQHandler_t handler)
  29 \details
  30
  31 Setup OS Tick timer to generate periodic RTOS Kernel Ticks.
  32
  33 The timer should be configured to generate periodic interrupts at frequency specified by \em freq.
  34 The parameter \em handler defines the interrupt handler function that is called.
  35
  36 The timer should only be initialized and configured but must not be started to create interrupts.
  37 The RTOS kernel calls the function \ref OS_Tick_Enable to start the timer interrupts.
  38
  39 <b>Cortex-M SysTick implementation:</b>
  40 \code
  41 #ifndef SYSTICK_IRQ_PRIORITY
  42 #define SYSTICK_IRQ_PRIORITY    0xFFU
  43 #endif
  44
  45 static uint8_t PendST;
  46
  47 int32_t  OS_Tick_Setup (uint32_t freq, IRQHandler_t handler) {
  48   (void)handler;
  49   uint32_t load;
  50
  51   if (freq == 0U) {
  52     return (-1);
  53   }
  54
  55   load = (SystemCoreClock / freq) - 1U;
  56   if (load > 0x00FFFFFFU) {
  57     return (-1);
  58   }
  59
  60   NVIC_SetPriority(SysTick_IRQn, SYSTICK_IRQ_PRIORITY);
  61
  62   SysTick->CTRL =  SysTick_CTRL_CLKSOURCE_Msk | SysTick_CTRL_TICKINT_Msk;
  63   SysTick->LOAD =  load;
  64   SysTick->VAL  =  0U;
  65
  66   PendST = 0U;
  67
  68   return (0);
  69 }
  70 \endcode
  71 */
  72
  73 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  74 /**
  75 \fn int32_t  OS_Tick_Enable (void)
  76 \details
  77 Enable OS Tick timer interrupt.
  78
  79 Enable and start the OS Tick timer to generate periodic RTOS Kernel Tick interrupts.
  80
  81 <b>Cortex-M SysTick implementation:</b>
  82 \code
  83 int32_t  OS_Tick_Enable (void) {
  84
  85   if (PendST != 0U) {
  86     PendST = 0U;
  87     SCB->ICSR = SCB_ICSR_PENDSTSET_Msk;
  88   }
  89
  90   SysTick->CTRL |=  SysTick_CTRL_ENABLE_Msk;
  91
  92   return (0);
  93 }
  94 \endcode
  95 */
  96
  97 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  98 /**
  99 \fn int32_t  OS_Tick_Disable (void)
 100 \details
 101 Disable OS Tick timer interrupt.
 102
 103 Stop the OS Tick timer and disable generation of RTOS Kernel Tick interrupts.
 104
 105 <b>Cortex-M SysTick implementation:</b>
 106 \code
 107 int32_t  OS_Tick_Disable (void) {
 108
 109   SysTick->CTRL &= ~SysTick_CTRL_ENABLE_Msk;
 110
 111   if ((SCB->ICSR & SCB_ICSR_PENDSTSET_Msk) != 0U) {
 112     SCB->ICSR = SCB_ICSR_PENDSTCLR_Msk;
 113     PendST = 1U;
 114   }
 115
 116   return (0);
 117 }
 118 \endcode
 119 */
 120
 121 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 122 /**
 123 \fn int32_t  OS_Tick_AcknowledgeIRQ (void)
 124 \details
 125 Acknowledge execution of OS Tick timer interrupt.
 126
 127 Acknowledge the execution of the OS Tick timer interrupt function, for example clear the pending flag.
 128
 129 <b>Cortex-M SysTick implementation:</b>
 130
 131 \code
 132 int32_t  OS_Tick_AcknowledgeIRQ (void) {
 133   (void)SysTick->CTRL;
 134   return (0);
 135 }
 136 \endcode
 137 */
 138
 139 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 140 /**
 141 \fn int32_t OS_Tick_GetIRQn (void)
 142 \details
 143 Get OS Tick timer IRQ number.
 144
 145 Return the numeric value that identifies the interrupt called by the OS Tick timer.
 146
 147 <b>Cortex-M SysTick implementation:</b>
 148
 149 \code
 150 int32_t  OS_Tick_GetIRQn (void) {
 151   return (SysTick_IRQn);
 152 }
 153 \endcode
 154 */
 155
 156 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 157 /**
 158 \fn uint32_t OS_Tick_GetClock (void)
 159 \details
 160 Get OS Tick timer clock frequency.
 161
 162 Return the input clock frequency of the OS Tick timer. This is the increment rate of the counter value returned by the function \ref OS_Tick_GetCount.
 163 This function is used to by the function \ref osKernelGetSysTimerFreq.
 164
 165 <b>Cortex-M SysTick implementation:</b>
 166
 167 \code
 168 uint32_t OS_Tick_GetClock (void) {
 169   return (SystemCoreClock);
 170 }
 171 \endcode
 172 */
 173
 174 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 175 /**
 176 \fn uint32_t OS_Tick_GetInterval (void)
 177 \details
 178 Get OS Tick timer interval reload value.
 179
 180 Return the number of counter ticks between to periodic OS Tick timer interrupts.
 181
 182 <b>Cortex-M SysTick implementation:</b>
 183
 184 \code
 185 uint32_t OS_Tick_GetInterval (void) {
 186   return (SysTick->LOAD + 1U);
 187 }
 188 \endcode
 189 */
 190
 191 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 192 /**
 193 \fn uint32_t OS_Tick_GetCount (void)
 194 \details
 195
 196 Get OS Tick timer counter value.
 197
 198 Return the current value of the OS Tick counter: 0 ... (reload value -1). The reload value is returned by the function \ref OS_Tick_GetInterval.
 199 The OS Tick timer counter value is used to by the function \ref osKernelGetSysTimerCount.
 200
 201 <b>Cortex-M SysTick implementation:</b>
 202
 203 \code
 204 uint32_t OS_Tick_GetCount (void) {
 205   uint32_t load = SysTick->LOAD;
 206   return  (load - SysTick->VAL);
 207 }
 208 \endcode
 209 */
 210
 211 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 212 /**
 213 \fn OS_Tick_GetOverflow (void)
 214 \details
 215 Get OS Tick timer overflow status.
 216
 217 Return the state of OS Tick timer interrupt pending bit that indicates timer overflows to adjust SysTimer calculations.
 218
 219 <b>Cortex-M SysTick implementation:</b>
 220
 221 \code
 222 uint32_t OS_Tick_GetOverflow (void) {
 223   return ((SCB->ICSR & SCB_ICSR_PENDSTSET_Msk) >> SCB_ICSR_PENDSTSET_Pos);
 224 }
 225 \endcode
 226 */
 227
 228 /** @} */ /* group CMSIS_RTOS_TickAPI */