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