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