1//  ==== Timer Management Functions ====
2/**
3\addtogroup CMSIS_RTOS_TimerMgmt Timer Management
4\ingroup CMSIS_RTOS
5\brief Create and control timer and timer callback functions.
6\details
7In addition to the \ref CMSIS_RTOS_Wait CMSIS-RTOS also supports virtual timer objects. These timer objects can trigger the execution of a function (not threads). When a timer expires, a callback function is executed to run associated code with the timer. Each timer can be configured as a one-shot or a periodic timer. A periodic timer repeats its operation until it is \ref osTimerDelete "deleted" or \ref osTimerStop "stopped". All timers can be \ref osTimerStart "started, restarted", or \ref osTimerStop "stopped".
8
9\note Timer management functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
10
11The figure below shows the behavior of a periodic timer. For one-shot timers, the timer stops after execution of the callback function.
12
13\image html "Timer.png" "Behavior of a Periodic Timer"
14
15Working with Timers
16--------------------
17The following steps are required to use a software timer:
18-# Define the timers:
19\code
20osTimerId_t one_shot_id, periodic_id;
21\endcode
22-# Define callback functions:
23\code
24static void one_shot_Callback (void *argument) {
25  int32_t arg = (int32_t)argument; // cast back argument '0'
26  // do something, i.e. set thread/event flags
27}
28static void periodic_Callback (void *argument) {
29  int32_t arg = (int32_t)argument; // cast back argument '5'
30  // do something, i.e. set thread/event flags
31}
32\endcode
33-# Instantiate and start the timers:
34\code
35// creates a one-shot timer:
36one_shot_id = osTimerNew(one_shot_Callback, osTimerOnce, (void *)0, NULL);     // (void*)0 is passed as an argument
37                                                                               // to the callback function
38// creates a periodic timer:
39periodic_id = osTimerNew(periodic_Callback, osTimerPeriodic, (void *)5, NULL); // (void*)5 is passed as an argument
40                                                                               // to the callback function
41osTimerStart(one_shot_id, 500U);
42osTimerStart(periodic_id, 1500U);
43
44// start the one-shot timer again after it has triggered the first time:
45osTimerStart(one_shot_id, 500U);
46
47// when timers are not needed any longer free the resources:
48osTimerDelete(one_shot_id);
49osTimerDelete(periodic_id);
50\endcode
51*/
52
53/**
54\addtogroup CMSIS_RTOS_TimerMgmt
55@{
56*/
57
58/**
59\typedef osTimerType_t
60\details
61The \b osTimerType_t specifies the timer type as repeating (periodic) or one-shot. Used in the function \ref osTimerNew.
62
63\var osTimerType_t::osTimerOnce
64\details
65The timer is not automatically restarted once it has elapsed. It can be restarted manually using \ref osTimerStart as needed.
66
67\var osTimerType_t::osTimerPeriodic
68\details
69The timer repeats automatically and triggers the callback continuously while running, see \ref osTimerStart and \ref osTimerStop.
70*/
71
72/**
73\typedef osTimerId_t
74\details
75Instances of this type hold a reference to a timer object. \n
76Returned by:
77- \ref osTimerNew
78*/
79
80/**
81\typedef void (*osTimerFunc_t) (void *argument)
82\details
83The timer callback function is called every time the timer elapses.
84
85The callback might be executed either in a dedicated timer thread or in interrupt context. Thus it is recommended to only
86use ISR callable functions from the timer callback.
87
88\param[in] argument The argument provided to \ref osTimerNew.
89*/
90
91/**
92\struct osTimerAttr_t
93\details
94Specifies the following attributes for the \ref osTimerNew function.
95
96*/
97
98
99/**
100\fn osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr)
101\details
102The function \b osTimerNew creates an one-shot or periodic timer and associates it with a callback function with \a argument.
103The timer is in stopped state until it is started with \ref osTimerStart. The function can be safely called before the RTOS
104is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
105
106The function \b osTimerNew returns the pointer to the timer object identifier or \token{NULL} in case of an error.
107
108\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
109
110<b>Code Example</b>
111\code
112#include "cmsis_os2.h"
113
114void Timer1_Callback (void *arg);               // prototypes for timer callback function
115void Timer2_Callback (void *arg);               // prototypes for timer callback function
116
117uint32_t exec1;                                 // argument for the timer call back function
118uint32_t exec2;                                 // argument for the timer call back function
119
120void TimerCreate_example (void)  {
121  osTimerId_t id1;                              // timer id
122  osTimerId_t id2;                              // timer id
123
124  // Create one-shoot timer
125  exec1 = 1U;
126  id1 = osTimerNew(Timer1_Callback, osTimerOnce, &exec1, NULL);
127  if (id1 != NULL) {
128    // One-shoot timer created
129  }
130
131  // Create periodic timer
132  exec2 = 2U;
133  id2 = osTimerNew(Timer2_Callback, osTimerPeriodic, &exec2, NULL);
134  if (id2 != NULL) {
135    // Periodic timer created
136  }
137  :
138}
139\endcode
140*/
141
142/**
143\fn const char *osTimerGetName (osTimerId_t timer_id)
144\details
145The function \b osTimerGetName returns the pointer to the name string of the timer identified by parameter \a timer_id or
146\token{NULL} in case of an error.
147
148\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
149*/
150
151/**
152\fn osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks)
153\details
154The function \b osTimerStart starts or restarts a timer specified by the parameter \a timer_id. The parameter \a ticks
155specifies the value of the timer in \ref CMSIS_RTOS_TimeOutValue "time ticks".
156
157Possible \ref osStatus_t return values:
158 - \em osOK: the specified timer has been started or restarted.
159 - \em osErrorISR: \b osTimerStart cannot be called from interrupt service routines.
160 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid or \a ticks is incorrect.
161 - \em osErrorResource: the timer is in an invalid state.
162 - \em osErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified timer.
163
164\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
165
166<b>Code Example</b>
167\code
168#include "cmsis_os2.h"
169
170void Timer_Callback (void *arg) {               // timer callback function
171                                                // arg contains &exec
172                                                // called every second after osTimerStart
173}
174
175uint32_t exec;                                  // argument for the timer call back function
176
177void TimerStart_example (void) {
178  osTimerId_t id;                               // timer id
179  uint32_t    timerDelay;                       // timer value
180  osStatus_t  status;                           // function return status
181
182  // Create periodic timer
183  exec = 1U;
184  id = osTimerNew(Timer_Callback, osTimerPeriodic, &exec, NULL);
185  if (id != NULL)  {
186    timerDelay = 1000U;
187    status = osTimerStart(id, timerDelay);       // start timer
188    if (status != osOK) {
189      // Timer could not be started
190    }
191  }
192  ;
193}
194\endcode
195*/
196
197/**
198\fn osStatus_t osTimerStop (osTimerId_t timer_id)
199\details
200The function \b osTimerStop stops a timer specified by the parameter \a timer_id.
201
202Possible \ref osStatus_t return values:
203 - \em osOK: the specified timer has been stopped.
204 - \em osErrorISR: \b osTimerStop cannot be called from interrupt service routines.
205 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
206 - \em osErrorResource: the timer is not running (you can only stop a running timer).
207 - \em osErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified timer.
208
209\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
210
211<b>Code Example</b>
212\code
213#include "cmsis_os2.h"
214
215void Timer_Callback (void *arg);                // prototype for timer callback function
216
217uint32_t exec;                                  // argument for the timer call back function
218
219void TimerStop_example (void) {
220  osTimerId_t id;                               // timer id
221  osStatus_t  status;                           // function return status
222
223  // Create periodic timer
224  exec = 1U;
225  id = osTimerNew(Timer_Callback, osTimerPeriodic, &exec, NULL);
226  osTimerStart(id, 1000U);                      // start timer
227  :
228  status = osTimerStop(id);                     // stop timer
229  if (status != osOK) {
230    // Timer could not be stopped
231  }
232  ;
233  osTimerStart(id, 1000U);                      // start timer again
234  ;
235}
236\endcode
237*/
238
239/**
240\fn uint32_t osTimerIsRunning (osTimerId_t timer_id)
241\details
242The function \b osTimerIsRunning checks whether a timer specified by parameter \a timer_id is running. It returns \token{1}
243if the timer is running and \token{0} if the timer is stopped or an error occurred.
244
245\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
246*/
247
248/**
249\fn osStatus_t osTimerDelete (osTimerId_t timer_id)
250\details
251The function \b osTimerDelete deletes the timer specified by parameter \a timer_id.
252
253Possible \ref osStatus_t return values:
254 - \em osOK: the specified timer has been deleted.
255 - \em osErrorISR: \b osTimerDelete cannot be called from interrupt service routines.
256 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
257 - \em osErrorResource: the timer is in an invalid state.
258 - \em osErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified timer.
259
260\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
261
262<b>Code Example</b>
263\code
264#include "cmsis_os2.h"
265
266void Timer_Callback (void *arg);                // prototype for timer callback function
267
268uint32_t exec;                                  // argument for the timer call back function
269
270void TimerDelete_example (void) {
271  osTimerId_t id;                               // timer id
272  osStatus_t  status;                           // function return status
273
274  // Create periodic timer
275  exec = 1U;
276  id = osTimerNew(Timer_Callback, osTimerPeriodic, &exec, NULL);
277  osTimerStart(id, 1000U);                      // start timer
278  ;
279  status = osTimerDelete(id);                   // stop and delete timer
280  if (status != osOK) {
281    // Timer could not be deleted
282  }
283  ;
284}
285\endcode
286*/
287
288/**
289@}
290*/
291
292// these struct members must stay outside the group to avoid double entries in documentation
293/**
294\var osTimerAttr_t::attr_bits
295\details
296Reserved for future use (must be set to '0' for future compatibility).
297
298\var osTimerAttr_t::cb_mem
299\details
300Pointer to a memory for the timer control block object. Refer to \ref CMSIS_RTOS_MemoryMgmt_Manual for more information.
301
302Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the timer control block.
303
304\var osTimerAttr_t::cb_size
305\details
306The size (in bytes) of memory block passed with \ref cb_mem. Required value depends on the underlying kernel implementation.
307
308Default: \token{0} as the default is no memory provided with \ref cb_mem.
309
310\var osTimerAttr_t::name
311\details
312Pointer to a constant string with a human readable name (displayed during debugging) of the timer object.
313
314Default: \token{NULL} no name specified.
315*/