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 \endcode
  55
  56 @{
  57 */
  58 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  59 /**
  60 \enum osTimerType_t
  61 \details
  62 The \ref osTimerType_t specifies the a repeating (periodic) or one-shot timer for the function \ref osTimerNew.
  63
  64 \var osTimerType_t::osTimerOnce
  65 \details
  66 The timer is not automatically restarted once it has elapsed.
  67
  68 \var osTimerType_t::osTimerPeriodic
  69 \details
  70 The timer repeats automatically and triggers the callback continuously.
  71 */
  72
  73 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  74 /**
  75 \typedef osTimerId_t
  76 \details
  77 Instances of this type hold a reference to a timer object.
  78 */
  79
  80 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  81 /**
  82 \typedef void (*osTimerFunc_t) (void *argument)
  83 \details
  84 The timer callback function is called everytime the timer elapses.
  85
  86 The callback might be executed either in a dedicated timer thread or in interrupt context. Thus it is recommended to only
  87 use ISR callable functions from the timer callback.
  88
  89 \param[in] argument The argument provided to \ref osTimerNew.
  90 */
  91
  92 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  93 /**
  94 \struct osTimerAttr_t
  95 \details
  96 */
  97
  98 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  99 /**
 100 \fn osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr)
 101 \details
 102 The function \b osTimerNew creates an one-shot or periodic timer and associates it with a callback function with \a argument.
 103 The timer is in stopped state until it is started with \ref osTimerStart. The function can be safely called before the RTOS
 104 is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
 105
 106 The 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
 114 void Timer1_Callback (void *arg);                          // prototypes for timer callback function
 115 void Timer2_Callback (void *arg);
 116
 117 uint32_t  exec1;                                           // argument for the timer call back function
 118 uint32_t  exec2;                                           // argument for the timer call back function
 119
 120 void TimerCreate_example (void)  {
 121   osTimerId_t id1;                                         // timer id
 122   osTimerId_t id2;                                         // timer id
 123
 124   // Create one-shoot timer
 125   exec1 = 1;
 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 = 2;
 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 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 144 /**
 145 \fn const char *osTimerGetName (osTimerId_t timer_id)
 146 \details
 147 The function \b osTimerGetName returns the pointer to the name string of the timer identified by parameter \a timer_id or
 148 \token{NULL} in case of an error.
 149
 150 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 151 */
 152
 153 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 154 /**
 155 \fn osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks)
 156 \details
 157 The function \b osTimerStart starts or restarts a timer specified by the parameter \a timer_id. The parameter \a ticks
 158 specifies the value of the timer in \ref CMSIS_RTOS_TimeOutValue "time ticks".
 159
 160 Possible \ref osStatus_t return values:
 161  - \em osOK: the specified timer has been started or restarted.
 162  - \em osErrorISR: \b osTimerStart cannot be called from interrupt service routines.
 163  - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid or \a ticks is incorrect.
 164  - \em osErrorResource: the timer specified by parameter \a timer_id is in an invalid timer state.
 165
 166 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 167
 168 <b>Code Example</b>
 169 \code
 170 #include "cmsis_os2.h"
 171
 172 void Timer_Callback (void *arg)  {                          // timer callback function
 173                                                             // arg contains &exec
 174                                                             // called every second after osTimerStart
 175 }
 176
 177 uint32_t  exec;                                             // argument for the timer call back function
 178
 179 void TimerStart_example (void)  {
 180   osTimerId_t id;                                           // timer id
 181   uint32_t    timerDelay;                                   // timer value
 182   osStatus_t  status;                                       // function return status
 183
 184   // Create periodic timer
 185   exec = 1;
 186   id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
 187   if (id)  {
 188     timerDelay = 1000;
 189     status = osTimerStart (id, timerDelay);                 // start timer
 190     if (status != osOK)  {
 191       // Timer could not be started
 192     }
 193   }
 194   ;
 195 }
 196 \endcode
 197 */
 198
 199 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 200 /**
 201 \fn osStatus_t osTimerStop (osTimerId_t timer_id)
 202 \details
 203 The function \b osTimerStop stops a timer specified by the parameter \a timer_id.
 204
 205 Possible \ref osStatus_t return values:
 206  - \em osOK: the specified timer has been stopped.
 207  - \em osErrorISR: \b osTimerStop cannot be called from interrupt service routines.
 208  - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
 209  - \em osErrorResource: the timer specified by parameter \a timer_id is not running (you can only stop a running timer).
 210
 211 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 212
 213 <b>Code Example</b>
 214 \code
 215 #include "cmsis_os2.h"
 216
 217 void Timer_Callback (void *arg);                           // prototype for timer callback function
 218
 219 uint32_t  exec;                                            // argument for the timer call back function
 220
 221 void TimerStop_example (void) {
 222   osTimerId_t id;                                          // timer id
 223   osStatus_t  status;                                      // function return status
 224
 225   // Create periodic timer
 226   exec = 1;
 227   id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
 228   osTimerStart (id, 1000);                                 // start timer
 229   :
 230   status = osTimerStop (id);                               // stop timer
 231   if (status != osOK) {
 232     // Timer could not be stopped
 233   }
 234   ;
 235   osTimerStart (id, 1000);                                 // start timer again
 236   ;
 237 }
 238 \endcode
 239 */
 240
 241 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 242 /**
 243 \fn uint32_t osTimerIsRunning (osTimerId_t timer_id)
 244 \details
 245 The function \b osTimerIsRunning checks whether a timer specified by parameter \a timer_id is running. It returns \token{1}
 246 if the timer is running and \token{0} if the timer is stopped or an error occurred.
 247
 248 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 249 */
 250
 251 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 252 /**
 253 \fn osStatus_t osTimerDelete (osTimerId_t timer_id)
 254 \details
 255 The function \b osTimerDelete deletes the timer specified by parameter \a timer_id.
 256
 257 Possible \ref osStatus_t return values:
 258  - \em osOK: the specified timer has been deleted.
 259  - \em osErrorISR: \b osTimerDelete cannot be called from interrupt service routines.
 260  - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
 261  - \em osErrorResource: the timer specified by parameter \a timer_id is in an invalid timer state.
 262
 263 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 264
 265 <b>Code Example</b>
 266 \code
 267 #include "cmsis_os2.h"
 268
 269 void Timer_Callback (void *arg);                           // prototype for timer callback function
 270
 271 uint32_t  exec;                                            // argument for the timer call back function
 272
 273 void TimerDelete_example (void) {
 274   osTimerId_t id;                                          // timer id
 275   osStatus_t  status;                                      // function return status
 276
 277   // Create periodic timer
 278   exec = 1;
 279   id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
 280   osTimerStart (id, 1000UL);                               // start timer
 281   ;
 282   status = osTimerDelete (id);                             // stop and delete timer
 283   if (status != osOK) {
 284     // Timer could not be deleted
 285   }
 286   ;
 287 }
 288 \endcode
 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
 296 Reserved for future use (set to '0').\n
 297 Default: \token{0}.
 298
 299 \var osTimerAttr_t::cb_mem
 300 \details
 301 Pointer to a memory location for the timer control block object. This can optionally be used for custom memory management systems.\n
 302 Default: \token{NULL} (uses kernel memory management).
 303
 304
 305 \var osTimerAttr_t::cb_size
 306 \details
 307 The size of the memory block passed with \ref cb_mem. Must be the size of a timer control block object or larger.
 308
 309 \var osTimerAttr_t::name
 310 \details
 311 Pointer to a string with a human readable name of the timer object.\n
 312 Default: \token{NULL}.
 313 */