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. The timer number is passed as a parameter to the callback function. Each timer can be configured as a
  13 one-shot or a  periodic timer. A periodic timer repeats its operation until it is \ref osTimerDelete "deleted" or
  14 \ref osTimerStop "stopped". All timers can be \ref osTimerStart "started, restarted", or \ref osTimerStop "stopped".
  15
  16 Timers are handled in the thread \b osTimerThread. Callback functions run under control of this thread and may use other
  17 CMSIS-RTOS API calls.
  18
  19 The figure below shows the behavior of a periodic timer. For one-shot timers, the timer stops after execution of the
  20 callback function.
  21
  22 \image html "Timer.png" "Behavior of a Periodic Timer"
  23
  24 Working with Timers
  25 --------------------
  26 The following steps are required to use a timer:
  27 -# Define the timers:
  28 \code{.c}
  29 osTimerId one_shot_id, periodic_id;
  30 \endcode
  31 -# Instantiate and start the timers:
  32 \code{.c}
  33 one_shot_id = osTimerNew((os_timer_func_t)&one_shot_Callback, osTimerOnce, (void *)0);                                   // creates a one-shot timer;
  34                                                                              // (void*)0 is passed as an argument
  35                                                                              // to the callback function
  36 periodic_id = osTimerNew((os_timer_func_t)&periodic_Callback, osTimerPeriodic, (void *)5);                       // creates a periodic timer;
  37                                                                              // (void*)5 is passed as an argument
  38                                                                              // to the callback function
  39 osTimerStart(one_shot_id, 500);
  40 osTimerStart(periodic, 1500);
  41 \endcode
  42
  43 @{
  44 */
  45 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  46 /**
  47 \enum  osTimerType_t
  48 \details
  49 The \ref osTimerType_t specifies the a repeating (periodic) or one-shot timer for the function \ref osTimerNew.
  50
  51 */
  52 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  53 /**
  54 \typedef osTimerId_t
  55 \details
  56 Instances of this type hold a reference to a timer object.
  57
  58 */
  59 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  60 /**
  61 \typedef void (*os_timer_func_t) (void *argument)
  62 \details
  63
  64 */
  65 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  66 /**
  67 \struct osTimerAttr_t
  68 \details
  69
  70
  71
  72 */
  73 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  74 /**
  75 \fn osTimerId_t osTimerNew (os_timer_func_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr)
  76 \details
  77 Create a one-shot or periodic timer and associate it with a callback function argument.
  78 The timer is in stopped until it is started with \ref osTimerStart.
  79
  80 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  81
  82 <b>Code Example</b>
  83 \code{.c}
  84 #include "cmsis_os2.h"
  85
  86 void Timer1_Callback  (void const *arg);                   // prototypes for timer callback function
  87 void Timer2_Callback  (void const *arg);
  88
  89 uint32_t  exec1;                                           // argument for the timer call back function
  90 uint32_t  exec2;                                           // argument for the timer call back function
  91
  92 void TimerCreate_example (void)  {
  93   osTimerId_t id1;                                         // timer id
  94   osTimerId_t id2;                                         // timer id
  95
  96   // Create one-shoot timer
  97   exec1 = 1;
  98   id1 = osTimerNew ((os_timer_func_t)&Timer1_Callback, osTimerOnce, &exec1);
  99   if (id1 != NULL)  {
 100     // One-shoot timer created
 101   }
 102
 103   // Create periodic timer
 104   exec2 = 2;
 105   id2 = osTimerNew ((os_timer_func_t)&Timer2_Callback, osTimerPeriodic, &exec2);
 106   if (id2 != NULL)  {
 107     // Periodic timer created
 108   }
 109   :
 110 }
 111 \endcode
 112 */
 113 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 114 /**
 115 \fn osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks)
 116 \details
 117 Start or restart the timer.
 118
 119 \ref osStatus_t return values:
 120  - \em osOK: the specified timer has been started or restarted.
 121  - \em osErrorISR: \ref osTimerStart cannot be called from interrupt service routines.
 122  - \em osErrorParameter: \a timer_id is incorrect.
 123
 124 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 125
 126 <b>Code Example</b>
 127 \code{.c}
 128 #include "cmsis_os2.h"
 129
 130 void Timer_Callback  (void const *arg)  {                   // timer callback function
 131                                                             // arg contains &exec
 132                                                             // called every second after osTimerStart
 133 }
 134
 135 uint32_t  exec;                                             // argument for the timer call back function
 136
 137 void TimerStart_example (void)  {
 138   osTimerId_t id;                                           // timer id
 139   uint32_t    timerDelay;                                   // timer value
 140   osStatus_t  status;                                       // function return status
 141
 142   // Create periodic timer
 143   exec = 1;
 144   id = osTimerNew ((os_timer_func_t)&Timer_Callback, osTimerPeriodic, &exec);
 145   if (id)  {
 146     timerDelay = 1000;
 147     status = osTimerStart (id, timerDelay);                 // start timer
 148     if (status != osOK)  {
 149       // Timer could not be started
 150     }
 151   }
 152   :
 153 }
 154 \endcode
 155 */
 156 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 157 /**
 158 \fn osStatus_t osTimerStop (osTimerId_t timer_id)
 159 \details
 160 Stop the timer.
 161
 162 \ref osStatus_t return values:
 163  - \em osOK: the specified timer has been stopped.
 164  - \em osErrorISR: \ref osTimerStop cannot be called from interrupt service routines.
 165  - \em osErrorParameter: \a timer_id is incorrect.
 166  - \em osErrorResource: the timer is not started.
 167
 168 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 169
 170 <b>Code Example</b>
 171 \code{.c}
 172 #include "cmsis_os2.h"
 173
 174 void Timer_Callback  (void const *arg);                    // prototype for timer callback function
 175
 176 void TimerStop_example (void)  {
 177   osTimerId_t id;                                            // timer id
 178   osStatus_t  status;                                         // function return status
 179
 180   // Create periodic timer
 181   exec = 1;
 182   id = osTimerCreate ((os_timer_func_t)&Timer_Callback, osTimerPeriodic, NULL);
 183   osTimerStart (id, 1000);                                 // start timer
 184   :
 185   status = osTimerStop (id);                               // stop timer
 186   if (status != osOK)  {
 187     // Timer could not be stopped
 188   }
 189   :
 190   osTimerStart (id, 1000);                                 // start timer again
 191   :
 192 }
 193 \endcode
 194 */
 195 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 196 /**
 197 \fn uint32_t osTimerIsRunning (osTimerId_t timer_id)
 198 \details
 199 Test if timer is running.
 200 Returns 0 if timer is stopped.
 201 Returns 1 if timer is running.
 202
 203 */
 204 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 205 /**
 206 \fn osStatus_t osTimerDelete (osTimerId_t timer_id)
 207 \details
 208 Delete the timer object.
 209
 210 \ref osStatus_t return values:
 211  - \em osOK: the specified timer has been deleted.
 212  - \em osErrorISR: \ref osTimerDelete cannot be called from interrupt service routines.
 213  - \em osErrorParameter: \a timer_id is incorrect.
 214
 215 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 216
 217 <b>Code Example</b>
 218 \code{.c}
 219 #include "cmsis_os2.h"
 220
 221 void Timer_Callback  (void const *arg);                    // prototype for timer callback function
 222
 223 void TimerDelete_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 = osTimerCreate (osTimer(Timer2), osTimerPeriodic, &exec);
 230   osTimerStart (id, 1000UL);                               // start timer
 231   :
 232   status = osTimerDelete (id);                             // stop and delete timer
 233   if (status != osOK)  {
 234     // Timer could not be deleted
 235   }
 236   :
 237 }
 238 \endcode
 239 */
 240 /// @}