begriffs open source - cmsis/blob - CMSIS/Documentation/Doxygen/RTOS2/src/ref_cmsis_os2_timer.txt

   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
   7 In 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
  11 The 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
  15 Working with Timers
  16 --------------------
  17 The following steps are required to use a software timer:
  18 -# Define the timers:
  19 \code
  20 osTimerId_t one_shot_id, periodic_id;
  21 \endcode
  22 -# Define callback functions:
  23 \code
  24 static 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 }
  28 static 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:
  36 one_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:
  39 periodic_id = osTimerNew(periodic_Callback, osTimerPeriodic, (void *)5, NULL); // (void*)5 is passed as an argument
  40                                                                                // to the callback function
  41 osTimerStart(one_shot_id, 500U);
  42 osTimerStart(periodic_id, 1500U);
  43
  44 // start the one-shot timer again after it has triggered the first time:
  45 osTimerStart(one_shot_id, 500U);
  46
  47 // when timers are not needed any longer free the resources:
  48 osTimerDelete(one_shot_id);
  49 osTimerDelete(periodic_id);
  50 \endcode
  51 */
  52
  53 /**
  54 \addtogroup CMSIS_RTOS_TimerMgmt
  55 @{
  56 */
  57
  58 /**
  59 \typedef osTimerType_t
  60 \details
  61 The \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
  65 The 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
  69 The 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
  75 Instances of this type hold a reference to a timer object. \n
  76 Returned by:
  77 - \ref osTimerNew
  78 */
  79
  80 /**
  81 \typedef void (*osTimerFunc_t) (void *argument)
  82 \details
  83 The timer callback function is called every time the timer elapses.
  84
  85 The callback might be executed either in a dedicated timer thread or in interrupt context. Thus it is recommended to only
  86 use 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
  94 Specifies 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
 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);               // prototypes for timer callback function
 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 = 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
 145 The 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
 154 The function \b osTimerStart starts or restarts a timer specified by the parameter \a timer_id. The parameter \a ticks
 155 specifies the value of the timer in \ref CMSIS_RTOS_TimeOutValue "time ticks".
 156
 157 Possible \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
 170 void Timer_Callback (void *arg) {               // timer callback function
 171                                                 // arg contains &exec
 172                                                 // called every second after osTimerStart
 173 }
 174
 175 uint32_t exec;                                  // argument for the timer call back function
 176
 177 void 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
 200 The function \b osTimerStop stops a timer specified by the parameter \a timer_id.
 201
 202 Possible \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
 215 void Timer_Callback (void *arg);                // prototype for timer callback function
 216
 217 uint32_t exec;                                  // argument for the timer call back function
 218
 219 void 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
 242 The function \b osTimerIsRunning checks whether a timer specified by parameter \a timer_id is running. It returns \token{1}
 243 if 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
 251 The function \b osTimerDelete deletes the timer specified by parameter \a timer_id.
 252
 253 Possible \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
 266 void Timer_Callback (void *arg);                // prototype for timer callback function
 267
 268 uint32_t exec;                                  // argument for the timer call back function
 269
 270 void 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
 296 Reserved for future use (must be set to '0' for future compatibility).
 297
 298 \var osTimerAttr_t::cb_mem
 299 \details
 300 Pointer to a memory for the timer control block object. Refer to \ref CMSIS_RTOS_MemoryMgmt_Manual for more information.
 301
 302 Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the timer control block.
 303
 304 \var osTimerAttr_t::cb_size
 305 \details
 306 The size (in bytes) of memory block passed with \ref cb_mem. Required value depends on the underlying kernel implementation.
 307
 308 Default: \token{0} as the default is no memory provided with \ref cb_mem.
 309
 310 \var osTimerAttr_t::name
 311 \details
 312 Pointer to a constant string with a human readable name (displayed during debugging) of the timer object.
 313
 314 Default: \token{NULL} no name specified.
 315 */