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