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

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