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 timer:
  29 -# Define the timers:
  30 \code
  31 osTimerId_t one_shot_id, periodic_id;
  32 \endcode
  33 -# Instantiate and start the timers:
  34 \code
  35 // creates a one-shot timer:
  36 one_shot_id = osTimerNew((osTimerFunc_t)&one_shot_Callback, osTimerOnce, (void *)0);     // (void*)0 is passed as an argument
  37                                                                                            // to the callback function
  38
  39 // creates a periodic timer:
  40 periodic_id = osTimerNew((osTimerFunc_t)&periodic_Callback, osTimerPeriodic, (void *)5); // (void*)5 is passed as an argument
  41                                                                                            // to the callback function
  42 osTimerStart(one_shot_id, 500);
  43 osTimerStart(periodic_id, 1500);
  44 \endcode
  45
  46 @{
  47 */
  48 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  49 /**
  50 \enum  osTimerType_t
  51 \details
  52 The \ref osTimerType_t specifies the a repeating (periodic) or one-shot timer for the function \ref osTimerNew.
  53 */
  54
  55 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  56 /**
  57 \typedef osTimerId_t
  58 \details
  59 Instances of this type hold a reference to a timer object.
  60 */
  61
  62 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  63 /**
  64 \typedef void (*osTimerFunc_t) (void *argument)
  65 \details
  66 */
  67
  68 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  69 /**
  70 \struct osTimerAttr_t
  71 \details
  72 */
  73
  74 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  75 /**
  76 \fn osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr)
  77 \details
  78 The function \b osTimerNew creates an one-shot or periodic timer and associates it with a callback function with \a argument.
  79 The timer is in stopped state until it is started with \ref osTimerStart. The function can be safely called before the RTOS
  80 is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
  81
  82 The parameter \a func specifies the start address of the timer callback function.
  83
  84 The parameter \a type specifies the type of the timer (refer to \ref osTimerType_t).
  85
  86 The parameter \a attr sets the timer attributes (refer to \ref osTimerAttr_t). Default attributes will be used if set to
  87 \token{NULL}.
  88
  89 The function \b osTimerNew returns the pointer to the timer object identifier or \token{NULL} in case of an error.
  90
  91 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  92
  93 <b>Code Example</b>
  94 \code
  95 #include "cmsis_os2.h"
  96
  97 void Timer1_Callback  (void const *arg);                   // prototypes for timer callback function
  98 void Timer2_Callback  (void const *arg);
  99
 100 uint32_t  exec1;                                           // argument for the timer call back function
 101 uint32_t  exec2;                                           // argument for the timer call back function
 102
 103 void TimerCreate_example (void)  {
 104   osTimerId_t id1;                                         // timer id
 105   osTimerId_t id2;                                         // timer id
 106
 107   // Create one-shoot timer
 108   exec1 = 1;
 109   id1 = osTimerNew ((osTimerFunc_t)&Timer1_Callback, osTimerOnce, &exec1, NULL);
 110   if (id1 != NULL)  {
 111     // One-shoot timer created
 112   }
 113
 114   // Create periodic timer
 115   exec2 = 2;
 116   id2 = osTimerNew ((osTimerFunc_t)&Timer2_Callback, osTimerPeriodic, &exec2, NULL);
 117   if (id2 != NULL)  {
 118     // Periodic timer created
 119   }
 120   :
 121 }
 122 \endcode
 123 */
 124 */
 125
 126 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 127 /**
 128 \fn const char *osTimerGetName (osTimerId_t timer_id)
 129 \details
 130 The function \b osTimerGetName returns the pointer to the name string of the timer identified by parameter \a timer_id or
 131 \token{NULL} in case of an error.
 132
 133 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 134 */
 135
 136 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 137 /**
 138 \fn osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks)
 139 \details
 140 The function \b osTimerStart starts or restarts a timer specified by the parameter \a timer_id. The parameter \a ticks
 141 specifies the value of the timer in \ref CMSIS_RTOS_TimeOutValue "time ticks".
 142
 143 Possible \ref osStatus_t return values:
 144  - \em osOK: the specified timer has been started or restarted.
 145  - \em osErrorISR: \b osTimerStart cannot be called from interrupt service routines.
 146  - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid or \a ticks is incorrect.
 147  - \em osErrorResource: the timer specified by parameter \a timer_id is in an invalid timer state.
 148
 149 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 150
 151 <b>Code Example</b>
 152 \code
 153 #include "cmsis_os2.h"
 154
 155 void Timer_Callback  (void const *arg)  {                   // timer callback function
 156                                                             // arg contains &exec
 157                                                             // called every second after osTimerStart
 158 }
 159
 160 uint32_t  exec;                                             // argument for the timer call back function
 161
 162 void TimerStart_example (void)  {
 163   osTimerId_t id;                                           // timer id
 164   uint32_t    timerDelay;                                   // timer value
 165   osStatus_t  status;                                       // function return status
 166
 167   // Create periodic timer
 168   exec = 1;
 169   id = osTimerNew ((osTimerFunc_t)&Timer_Callback, osTimerPeriodic, &exec, NULL);
 170   if (id)  {
 171     timerDelay = 1000;
 172     status = osTimerStart (id, timerDelay);                 // start timer
 173     if (status != osOK)  {
 174       // Timer could not be started
 175     }
 176   }
 177   ;
 178 }
 179 \endcode
 180 */
 181
 182 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 183 /**
 184 \fn osStatus_t osTimerStop (osTimerId_t timer_id)
 185 \details
 186 The function \b osTimerStop stops a timer specified by the parameter \a timer_id.
 187
 188 Possible \ref osStatus_t return values:
 189  - \em osOK: the specified timer has been stopped.
 190  - \em osErrorISR: \b osTimerStop cannot be called from interrupt service routines.
 191  - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
 192  - \em osErrorResource: the timer specified by parameter \a timer_id is not running (you can only stop a running timer).
 193
 194 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 195
 196 <b>Code Example</b>
 197 \code
 198 #include "cmsis_os2.h"
 199
 200 void Timer_Callback  (void const *arg);                    // prototype for timer callback function
 201
 202 uint32_t  exec;                                            // argument for the timer call back function
 203
 204 void TimerStop_example (void)  {
 205   osTimerId_t id;                                          // timer id
 206   osStatus_t  status;                                      // function return status
 207
 208   // Create periodic timer
 209   exec = 1;
 210   id = osTimerNew ((osTimerFunc_t)&Timer_Callback, osTimerPeriodic, &exec, NULL);
 211   osTimerStart (id, 1000);                                 // start timer
 212   :
 213   status = osTimerStop (id);                               // stop timer
 214   if (status != osOK)  {
 215     // Timer could not be stopped
 216   }
 217   ;
 218   osTimerStart (id, 1000);                                 // start timer again
 219   ;
 220 }
 221 \endcode
 222 */
 223
 224 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 225 /**
 226 \fn uint32_t osTimerIsRunning (osTimerId_t timer_id)
 227 \details
 228 the function \b osTimerIsRunning checks whether a timer specified by parameter \a timer_id is running. It returns \token{1}
 229 if the timer is running and \token{0} if the timer is stopped or an error occurred.
 230
 231 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 232 */
 233
 234 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 235 /**
 236 \fn osStatus_t osTimerDelete (osTimerId_t timer_id)
 237 \details
 238 The function \b osTimerDelete deletes the timer specified by parameter \a timer_id.
 239
 240 Possible \ref osStatus_t return values:
 241  - \em osOK: the specified timer has been deleted.
 242  - \em osErrorISR: \b osTimerDelete cannot be called from interrupt service routines.
 243  - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
 244  - \em osErrorResource: the timer specified by parameter \a timer_id is in an invalid timer state.
 245
 246 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 247
 248 <b>Code Example</b>
 249 \code
 250 #include "cmsis_os2.h"
 251
 252 void Timer_Callback  (void const *arg);                    // prototype for timer callback function
 253
 254 uint32_t  exec;                                            // argument for the timer call back function
 255
 256 void TimerDelete_example (void)  {
 257   osTimerId_t id;                                          // timer id
 258   osStatus_t  status;                                      // function return status
 259
 260   // Create periodic timer
 261   exec = 1;
 262   id = osTimerNew ((osTimerFunc_t)&Timer_Callback, osTimerPeriodic, &exec, NULL);
 263   osTimerStart (id, 1000UL);                               // start timer
 264   ;
 265   status = osTimerDelete (id);                             // stop and delete timer
 266   if (status != osOK)  {
 267     // Timer could not be deleted
 268   }
 269   ;
 270 }
 271 \endcode
 272 */
 273 /// @}