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 Calling \ref osTimerStart from an ISR will return \ref osErrorISR.
 126
 127 <b>Code Example</b>
 128 \code{.c}
 129 #include "cmsis_os2.h"
 130
 131 void Timer_Callback  (void const *arg)  {                   // timer callback function
 132                                                             // arg contains &exec
 133                                                             // called every second after osTimerStart
 134 }
 135
 136 uint32_t  exec;                                             // argument for the timer call back function
 137
 138 void TimerStart_example (void)  {
 139   osTimerId_t id;                                           // timer id
 140   uint32_t    timerDelay;                                   // timer value
 141   osStatus_t  status;                                       // function return status
 142
 143   // Create periodic timer
 144   exec = 1;
 145   id = osTimerNew ((os_timer_func_t)&Timer_Callback, osTimerPeriodic, &exec);
 146   if (id)  {
 147     timerDelay = 1000;
 148     status = osTimerStart (id, timerDelay);                 // start timer
 149     if (status != osOK)  {
 150       // Timer could not be started
 151     }
 152   }
 153   :
 154 }
 155 \endcode
 156 */
 157 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 158 /**
 159 \fn osStatus_t osTimerStop (osTimerId_t timer_id)
 160 \details
 161 Stop the timer.
 162
 163 \ref osStatus_t return values:
 164  - \em osOK: the specified timer has been stopped.
 165  - \em osErrorISR: \ref osTimerStop cannot be called from interrupt service routines.
 166  - \em osErrorParameter: \a timer_id is incorrect.
 167  - \em osErrorResource: the timer is not started.
 168
 169 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 170 Calling \ref osTimerStop from an ISR will return \ref osErrorISR.
 171
 172 <b>Code Example</b>
 173 \code{.c}
 174 #include "cmsis_os2.h"
 175
 176 void Timer_Callback  (void const *arg);                    // prototype for timer callback function
 177
 178 void TimerStop_example (void)  {
 179   osTimerId_t id;                                            // timer id
 180   osStatus_t  status;                                         // function return status
 181
 182   // Create periodic timer
 183   exec = 1;
 184   id = osTimerCreate ((os_timer_func_t)&Timer_Callback, osTimerPeriodic, NULL);
 185   osTimerStart (id, 1000);                                 // start timer
 186   :
 187   status = osTimerStop (id);                               // stop timer
 188   if (status != osOK)  {
 189     // Timer could not be stopped
 190   }
 191   :
 192   osTimerStart (id, 1000);                                 // start timer again
 193   :
 194 }
 195 \endcode
 196 */
 197 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 198 /**
 199 \fn uint32_t osTimerIsRunning (osTimerId_t timer_id)
 200 \details
 201 Test if timer is running.
 202 Returns 0 if timer is stopped.
 203 Returns 1 if timer is running.
 204
 205 */
 206 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 207 /**
 208 \fn osStatus_t osTimerDelete (osTimerId_t timer_id)
 209 \details
 210 Delete the timer object.
 211
 212 \ref osStatus_t return values:
 213  - \em osOK: the specified timer has been deleted.
 214  - \em osErrorISR: \ref osTimerDelete cannot be called from interrupt service routines.
 215  - \em osErrorParameter: \a timer_id is incorrect.
 216
 217 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 218 Calling \ref osTimerDelete from an ISR will return \ref osErrorISR.
 219
 220 <b>Code Example</b>
 221 \code{.c}
 222 #include "cmsis_os2.h"
 223
 224 void Timer_Callback  (void const *arg);                    // prototype for timer callback function
 225
 226 void TimerDelete_example (void)  {
 227   osTimerId_t id;                                            // timer id
 228   osStatus_t  status;                                         // function return status
 229
 230   // Create periodic timer
 231   exec = 1;
 232   id = osTimerCreate (osTimer(Timer2), osTimerPeriodic, &exec);
 233   osTimerStart (id, 1000UL);                               // start timer
 234   :
 235   status = osTimerDelete (id);                             // stop and delete timer
 236   if (status != osOK)  {
 237     // Timer could not be deleted
 238   }
 239   :
 240 }
 241 \endcode
 242 */
 243 /// @}