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