begriffs open source - freertos/blob - include/timers.h

   1 /*\r
   2  * FreeRTOS Kernel V10.3.1\r
   3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://www.FreeRTOS.org\r
  23  * http://aws.amazon.com/freertos\r
  24  *\r
  25  */\r
  26 \r
  27 \r
  28 #ifndef TIMERS_H\r
  29     #define TIMERS_H\r
  30 \r
  31     #ifndef INC_FREERTOS_H\r
  32         #error "include FreeRTOS.h must appear in source files before include timers.h"\r
  33     #endif\r
  34 \r
  35 /*lint -save -e537 This headers are only multiply included if the application code\r
  36  * happens to also be including task.h. */\r
  37     #include "task.h"\r
  38 /*lint -restore */\r
  39 \r
  40     #ifdef __cplusplus\r
  41         extern "C" {\r
  42     #endif\r
  43 \r
  44 /*-----------------------------------------------------------\r
  45 * MACROS AND DEFINITIONS\r
  46 *----------------------------------------------------------*/\r
  47 \r
  48 /* IDs for commands that can be sent/received on the timer queue.  These are to\r
  49  * be used solely through the macros that make up the public software timer API,\r
  50  * as defined below.  The commands that are sent from interrupts must use the\r
  51  * highest numbers as tmrFIRST_FROM_ISR_COMMAND is used to determine if the task\r
  52  * or interrupt version of the queue send function should be used. */\r
  53     #define tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR    ( ( BaseType_t ) -2 )\r
  54     #define tmrCOMMAND_EXECUTE_CALLBACK             ( ( BaseType_t ) -1 )\r
  55     #define tmrCOMMAND_START_DONT_TRACE             ( ( BaseType_t ) 0 )\r
  56     #define tmrCOMMAND_START                        ( ( BaseType_t ) 1 )\r
  57     #define tmrCOMMAND_RESET                        ( ( BaseType_t ) 2 )\r
  58     #define tmrCOMMAND_STOP                         ( ( BaseType_t ) 3 )\r
  59     #define tmrCOMMAND_CHANGE_PERIOD                ( ( BaseType_t ) 4 )\r
  60     #define tmrCOMMAND_DELETE                       ( ( BaseType_t ) 5 )\r
  61 \r
  62     #define tmrFIRST_FROM_ISR_COMMAND               ( ( BaseType_t ) 6 )\r
  63     #define tmrCOMMAND_START_FROM_ISR               ( ( BaseType_t ) 6 )\r
  64     #define tmrCOMMAND_RESET_FROM_ISR               ( ( BaseType_t ) 7 )\r
  65     #define tmrCOMMAND_STOP_FROM_ISR                ( ( BaseType_t ) 8 )\r
  66     #define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR       ( ( BaseType_t ) 9 )\r
  67 \r
  68 \r
  69 /**\r
  70  * Type by which software timers are referenced.  For example, a call to\r
  71  * xTimerCreate() returns an TimerHandle_t variable that can then be used to\r
  72  * reference the subject timer in calls to other software timer API functions\r
  73  * (for example, xTimerStart(), xTimerReset(), etc.).\r
  74  */\r
  75     struct tmrTimerControl; /* The old naming convention is used to prevent breaking kernel aware debuggers. */\r
  76     typedef struct tmrTimerControl * TimerHandle_t;\r
  77 \r
  78 /*\r
  79  * Defines the prototype to which timer callback functions must conform.\r
  80  */\r
  81     typedef void (* TimerCallbackFunction_t)( TimerHandle_t xTimer );\r
  82 \r
  83 /*\r
  84  * Defines the prototype to which functions used with the\r
  85  * xTimerPendFunctionCallFromISR() function must conform.\r
  86  */\r
  87     typedef void (* PendedFunction_t)( void *,\r
  88                                        uint32_t );\r
  89 \r
  90 /**\r
  91  * TimerHandle_t xTimerCreate(  const char * const pcTimerName,\r
  92  *                              TickType_t xTimerPeriodInTicks,\r
  93  *                              UBaseType_t uxAutoReload,\r
  94  *                              void * pvTimerID,\r
  95  *                              TimerCallbackFunction_t pxCallbackFunction );\r
  96  *\r
  97  * Creates a new software timer instance, and returns a handle by which the\r
  98  * created software timer can be referenced.\r
  99  *\r
 100  * Internally, within the FreeRTOS implementation, software timers use a block\r
 101  * of memory, in which the timer data structure is stored.  If a software timer\r
 102  * is created using xTimerCreate() then the required memory is automatically\r
 103  * dynamically allocated inside the xTimerCreate() function.  (see\r
 104  * http://www.freertos.org/a00111.html).  If a software timer is created using\r
 105  * xTimerCreateStatic() then the application writer must provide the memory that\r
 106  * will get used by the software timer.  xTimerCreateStatic() therefore allows a\r
 107  * software timer to be created without using any dynamic memory allocation.\r
 108  *\r
 109  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),\r
 110  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and\r
 111  * xTimerChangePeriodFromISR() API functions can all be used to transition a\r
 112  * timer into the active state.\r
 113  *\r
 114  * @param pcTimerName A text name that is assigned to the timer.  This is done\r
 115  * purely to assist debugging.  The kernel itself only ever references a timer\r
 116  * by its handle, and never by its name.\r
 117  *\r
 118  * @param xTimerPeriodInTicks The timer period.  The time is defined in tick\r
 119  * periods so the constant portTICK_PERIOD_MS can be used to convert a time that\r
 120  * has been specified in milliseconds.  For example, if the timer must expire\r
 121  * after 100 ticks, then xTimerPeriodInTicks should be set to 100.\r
 122  * Alternatively, if the timer must expire after 500ms, then xPeriod can be set\r
 123  * to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or\r
 124  * equal to 1000.  Time timer period must be greater than 0.\r
 125  *\r
 126  * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will\r
 127  * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter.\r
 128  * If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and\r
 129  * enter the dormant state after it expires.\r
 130  *\r
 131  * @param pvTimerID An identifier that is assigned to the timer being created.\r
 132  * Typically this would be used in the timer callback function to identify which\r
 133  * timer expired when the same callback function is assigned to more than one\r
 134  * timer.\r
 135  *\r
 136  * @param pxCallbackFunction The function to call when the timer expires.\r
 137  * Callback functions must have the prototype defined by TimerCallbackFunction_t,\r
 138  * which is     "void vCallbackFunction( TimerHandle_t xTimer );".\r
 139  *\r
 140  * @return If the timer is successfully created then a handle to the newly\r
 141  * created timer is returned.  If the timer cannot be created because there is\r
 142  * insufficient FreeRTOS heap remaining to allocate the timer\r
 143  * structures then NULL is returned.\r
 144  *\r
 145  * Example usage:\r
 146  * @verbatim\r
 147  * #define NUM_TIMERS 5\r
 148  *\r
 149  * // An array to hold handles to the created timers.\r
 150  * TimerHandle_t xTimers[ NUM_TIMERS ];\r
 151  *\r
 152  * // An array to hold a count of the number of times each timer expires.\r
 153  * int32_t lExpireCounters[ NUM_TIMERS ] = { 0 };\r
 154  *\r
 155  * // Define a callback function that will be used by multiple timer instances.\r
 156  * // The callback function does nothing but count the number of times the\r
 157  * // associated timer expires, and stop the timer once the timer has expired\r
 158  * // 10 times.\r
 159  * void vTimerCallback( TimerHandle_t pxTimer )\r
 160  * {\r
 161  * int32_t lArrayIndex;\r
 162  * const int32_t xMaxExpiryCountBeforeStopping = 10;\r
 163  *\r
 164  *     // Optionally do something if the pxTimer parameter is NULL.\r
 165  *     configASSERT( pxTimer );\r
 166  *\r
 167  *     // Which timer expired?\r
 168  *     lArrayIndex = ( int32_t ) pvTimerGetTimerID( pxTimer );\r
 169  *\r
 170  *     // Increment the number of times that pxTimer has expired.\r
 171  *     lExpireCounters[ lArrayIndex ] += 1;\r
 172  *\r
 173  *     // If the timer has expired 10 times then stop it from running.\r
 174  *     if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping )\r
 175  *     {\r
 176  *         // Do not use a block time if calling a timer API function from a\r
 177  *         // timer callback function, as doing so could cause a deadlock!\r
 178  *         xTimerStop( pxTimer, 0 );\r
 179  *     }\r
 180  * }\r
 181  *\r
 182  * void main( void )\r
 183  * {\r
 184  * int32_t x;\r
 185  *\r
 186  *     // Create then start some timers.  Starting the timers before the scheduler\r
 187  *     // has been started means the timers will start running immediately that\r
 188  *     // the scheduler starts.\r
 189  *     for( x = 0; x < NUM_TIMERS; x++ )\r
 190  *     {\r
 191  *         xTimers[ x ] = xTimerCreate(    "Timer",       // Just a text name, not used by the kernel.\r
 192  *                                         ( 100 * x ),   // The timer period in ticks.\r
 193  *                                         pdTRUE,        // The timers will auto-reload themselves when they expire.\r
 194  *                                         ( void * ) x,  // Assign each timer a unique id equal to its array index.\r
 195  *                                         vTimerCallback // Each timer calls the same callback when it expires.\r
 196  *                                     );\r
 197  *\r
 198  *         if( xTimers[ x ] == NULL )\r
 199  *         {\r
 200  *             // The timer was not created.\r
 201  *         }\r
 202  *         else\r
 203  *         {\r
 204  *             // Start the timer.  No block time is specified, and even if one was\r
 205  *             // it would be ignored because the scheduler has not yet been\r
 206  *             // started.\r
 207  *             if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )\r
 208  *             {\r
 209  *                 // The timer could not be set into the Active state.\r
 210  *             }\r
 211  *         }\r
 212  *     }\r
 213  *\r
 214  *     // ...\r
 215  *     // Create tasks here.\r
 216  *     // ...\r
 217  *\r
 218  *     // Starting the scheduler will start the timers running as they have already\r
 219  *     // been set into the active state.\r
 220  *     vTaskStartScheduler();\r
 221  *\r
 222  *     // Should not reach here.\r
 223  *     for( ;; );\r
 224  * }\r
 225  * @endverbatim\r
 226  */\r
 227     #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
 228         TimerHandle_t xTimerCreate( const char * const pcTimerName,     /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
 229                                     const TickType_t xTimerPeriodInTicks,\r
 230                                     const UBaseType_t uxAutoReload,\r
 231                                     void * const pvTimerID,\r
 232                                     TimerCallbackFunction_t pxCallbackFunction ) PRIVILEGED_FUNCTION;\r
 233     #endif\r
 234 \r
 235 /**\r
 236  * TimerHandle_t xTimerCreateStatic(const char * const pcTimerName,\r
 237  *                                  TickType_t xTimerPeriodInTicks,\r
 238  *                                  UBaseType_t uxAutoReload,\r
 239  *                                  void * pvTimerID,\r
 240  *                                  TimerCallbackFunction_t pxCallbackFunction,\r
 241  *                                                                      StaticTimer_t *pxTimerBuffer );\r
 242  *\r
 243  * Creates a new software timer instance, and returns a handle by which the\r
 244  * created software timer can be referenced.\r
 245  *\r
 246  * Internally, within the FreeRTOS implementation, software timers use a block\r
 247  * of memory, in which the timer data structure is stored.  If a software timer\r
 248  * is created using xTimerCreate() then the required memory is automatically\r
 249  * dynamically allocated inside the xTimerCreate() function.  (see\r
 250  * http://www.freertos.org/a00111.html).  If a software timer is created using\r
 251  * xTimerCreateStatic() then the application writer must provide the memory that\r
 252  * will get used by the software timer.  xTimerCreateStatic() therefore allows a\r
 253  * software timer to be created without using any dynamic memory allocation.\r
 254  *\r
 255  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),\r
 256  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and\r
 257  * xTimerChangePeriodFromISR() API functions can all be used to transition a\r
 258  * timer into the active state.\r
 259  *\r
 260  * @param pcTimerName A text name that is assigned to the timer.  This is done\r
 261  * purely to assist debugging.  The kernel itself only ever references a timer\r
 262  * by its handle, and never by its name.\r
 263  *\r
 264  * @param xTimerPeriodInTicks The timer period.  The time is defined in tick\r
 265  * periods so the constant portTICK_PERIOD_MS can be used to convert a time that\r
 266  * has been specified in milliseconds.  For example, if the timer must expire\r
 267  * after 100 ticks, then xTimerPeriodInTicks should be set to 100.\r
 268  * Alternatively, if the timer must expire after 500ms, then xPeriod can be set\r
 269  * to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or\r
 270  * equal to 1000.  The timer period must be greater than 0.\r
 271  *\r
 272  * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will\r
 273  * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter.\r
 274  * If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and\r
 275  * enter the dormant state after it expires.\r
 276  *\r
 277  * @param pvTimerID An identifier that is assigned to the timer being created.\r
 278  * Typically this would be used in the timer callback function to identify which\r
 279  * timer expired when the same callback function is assigned to more than one\r
 280  * timer.\r
 281  *\r
 282  * @param pxCallbackFunction The function to call when the timer expires.\r
 283  * Callback functions must have the prototype defined by TimerCallbackFunction_t,\r
 284  * which is "void vCallbackFunction( TimerHandle_t xTimer );".\r
 285  *\r
 286  * @param pxTimerBuffer Must point to a variable of type StaticTimer_t, which\r
 287  * will be then be used to hold the software timer's data structures, removing\r
 288  * the need for the memory to be allocated dynamically.\r
 289  *\r
 290  * @return If the timer is created then a handle to the created timer is\r
 291  * returned.  If pxTimerBuffer was NULL then NULL is returned.\r
 292  *\r
 293  * Example usage:\r
 294  * @verbatim\r
 295  *\r
 296  * // The buffer used to hold the software timer's data structure.\r
 297  * static StaticTimer_t xTimerBuffer;\r
 298  *\r
 299  * // A variable that will be incremented by the software timer's callback\r
 300  * // function.\r
 301  * UBaseType_t uxVariableToIncrement = 0;\r
 302  *\r
 303  * // A software timer callback function that increments a variable passed to\r
 304  * // it when the software timer was created.  After the 5th increment the\r
 305  * // callback function stops the software timer.\r
 306  * static void prvTimerCallback( TimerHandle_t xExpiredTimer )\r
 307  * {\r
 308  * UBaseType_t *puxVariableToIncrement;\r
 309  * BaseType_t xReturned;\r
 310  *\r
 311  *     // Obtain the address of the variable to increment from the timer ID.\r
 312  *     puxVariableToIncrement = ( UBaseType_t * ) pvTimerGetTimerID( xExpiredTimer );\r
 313  *\r
 314  *     // Increment the variable to show the timer callback has executed.\r
 315  *     ( *puxVariableToIncrement )++;\r
 316  *\r
 317  *     // If this callback has executed the required number of times, stop the\r
 318  *     // timer.\r
 319  *     if( *puxVariableToIncrement == 5 )\r
 320  *     {\r
 321  *         // This is called from a timer callback so must not block.\r
 322  *         xTimerStop( xExpiredTimer, staticDONT_BLOCK );\r
 323  *     }\r
 324  * }\r
 325  *\r
 326  *\r
 327  * void main( void )\r
 328  * {\r
 329  *     // Create the software time.  xTimerCreateStatic() has an extra parameter\r
 330  *     // than the normal xTimerCreate() API function.  The parameter is a pointer\r
 331  *     // to the StaticTimer_t structure that will hold the software timer\r
 332  *     // structure.  If the parameter is passed as NULL then the structure will be\r
 333  *     // allocated dynamically, just as if xTimerCreate() had been called.\r
 334  *     xTimer = xTimerCreateStatic( "T1",             // Text name for the task.  Helps debugging only.  Not used by FreeRTOS.\r
 335  *                                  xTimerPeriod,     // The period of the timer in ticks.\r
 336  *                                  pdTRUE,           // This is an auto-reload timer.\r
 337  *                                  ( void * ) &uxVariableToIncrement,    // A variable incremented by the software timer's callback function\r
 338  *                                  prvTimerCallback, // The function to execute when the timer expires.\r
 339  *                                  &xTimerBuffer );  // The buffer that will hold the software timer structure.\r
 340  *\r
 341  *     // The scheduler has not started yet so a block time is not used.\r
 342  *     xReturned = xTimerStart( xTimer, 0 );\r
 343  *\r
 344  *     // ...\r
 345  *     // Create tasks here.\r
 346  *     // ...\r
 347  *\r
 348  *     // Starting the scheduler will start the timers running as they have already\r
 349  *     // been set into the active state.\r
 350  *     vTaskStartScheduler();\r
 351  *\r
 352  *     // Should not reach here.\r
 353  *     for( ;; );\r
 354  * }\r
 355  * @endverbatim\r
 356  */\r
 357     #if ( configSUPPORT_STATIC_ALLOCATION == 1 )\r
 358         TimerHandle_t xTimerCreateStatic( const char * const pcTimerName,       /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
 359                                           const TickType_t xTimerPeriodInTicks,\r
 360                                           const UBaseType_t uxAutoReload,\r
 361                                           void * const pvTimerID,\r
 362                                           TimerCallbackFunction_t pxCallbackFunction,\r
 363                                           StaticTimer_t * pxTimerBuffer ) PRIVILEGED_FUNCTION;\r
 364     #endif /* configSUPPORT_STATIC_ALLOCATION */\r
 365 \r
 366 /**\r
 367  * void *pvTimerGetTimerID( TimerHandle_t xTimer );\r
 368  *\r
 369  * Returns the ID assigned to the timer.\r
 370  *\r
 371  * IDs are assigned to timers using the pvTimerID parameter of the call to\r
 372  * xTimerCreated() that was used to create the timer, and by calling the\r
 373  * vTimerSetTimerID() API function.\r
 374  *\r
 375  * If the same callback function is assigned to multiple timers then the timer\r
 376  * ID can be used as time specific (timer local) storage.\r
 377  *\r
 378  * @param xTimer The timer being queried.\r
 379  *\r
 380  * @return The ID assigned to the timer being queried.\r
 381  *\r
 382  * Example usage:\r
 383  *\r
 384  * See the xTimerCreate() API function example usage scenario.\r
 385  */\r
 386     void * pvTimerGetTimerID( const TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;\r
 387 \r
 388 /**\r
 389  * void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );\r
 390  *\r
 391  * Sets the ID assigned to the timer.\r
 392  *\r
 393  * IDs are assigned to timers using the pvTimerID parameter of the call to\r
 394  * xTimerCreated() that was used to create the timer.\r
 395  *\r
 396  * If the same callback function is assigned to multiple timers then the timer\r
 397  * ID can be used as time specific (timer local) storage.\r
 398  *\r
 399  * @param xTimer The timer being updated.\r
 400  *\r
 401  * @param pvNewID The ID to assign to the timer.\r
 402  *\r
 403  * Example usage:\r
 404  *\r
 405  * See the xTimerCreate() API function example usage scenario.\r
 406  */\r
 407     void vTimerSetTimerID( TimerHandle_t xTimer,\r
 408                            void * pvNewID ) PRIVILEGED_FUNCTION;\r
 409 \r
 410 /**\r
 411  * BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );\r
 412  *\r
 413  * Queries a timer to see if it is active or dormant.\r
 414  *\r
 415  * A timer will be dormant if:\r
 416  *     1) It has been created but not started, or\r
 417  *     2) It is an expired one-shot timer that has not been restarted.\r
 418  *\r
 419  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),\r
 420  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and\r
 421  * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the\r
 422  * active state.\r
 423  *\r
 424  * @param xTimer The timer being queried.\r
 425  *\r
 426  * @return pdFALSE will be returned if the timer is dormant.  A value other than\r
 427  * pdFALSE will be returned if the timer is active.\r
 428  *\r
 429  * Example usage:\r
 430  * @verbatim\r
 431  * // This function assumes xTimer has already been created.\r
 432  * void vAFunction( TimerHandle_t xTimer )\r
 433  * {\r
 434  *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"\r
 435  *     {\r
 436  *         // xTimer is active, do something.\r
 437  *     }\r
 438  *     else\r
 439  *     {\r
 440  *         // xTimer is not active, do something else.\r
 441  *     }\r
 442  * }\r
 443  * @endverbatim\r
 444  */\r
 445     BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;\r
 446 \r
 447 /**\r
 448  * TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );\r
 449  *\r
 450  * Simply returns the handle of the timer service/daemon task.  It it not valid\r
 451  * to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started.\r
 452  */\r
 453     TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION;\r
 454 \r
 455 /**\r
 456  * BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );\r
 457  *\r
 458  * Timer functionality is provided by a timer service/daemon task.  Many of the\r
 459  * public FreeRTOS timer API functions send commands to the timer service task\r
 460  * through a queue called the timer command queue.  The timer command queue is\r
 461  * private to the kernel itself and is not directly accessible to application\r
 462  * code.  The length of the timer command queue is set by the\r
 463  * configTIMER_QUEUE_LENGTH configuration constant.\r
 464  *\r
 465  * xTimerStart() starts a timer that was previously created using the\r
 466  * xTimerCreate() API function.  If the timer had already been started and was\r
 467  * already in the active state, then xTimerStart() has equivalent functionality\r
 468  * to the xTimerReset() API function.\r
 469  *\r
 470  * Starting a timer ensures the timer is in the active state.  If the timer\r
 471  * is not stopped, deleted, or reset in the mean time, the callback function\r
 472  * associated with the timer will get called 'n' ticks after xTimerStart() was\r
 473  * called, where 'n' is the timers defined period.\r
 474  *\r
 475  * It is valid to call xTimerStart() before the scheduler has been started, but\r
 476  * when this is done the timer will not actually start until the scheduler is\r
 477  * started, and the timers expiry time will be relative to when the scheduler is\r
 478  * started, not relative to when xTimerStart() was called.\r
 479  *\r
 480  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStart()\r
 481  * to be available.\r
 482  *\r
 483  * @param xTimer The handle of the timer being started/restarted.\r
 484  *\r
 485  * @param xTicksToWait Specifies the time, in ticks, that the calling task should\r
 486  * be held in the Blocked state to wait for the start command to be successfully\r
 487  * sent to the timer command queue, should the queue already be full when\r
 488  * xTimerStart() was called.  xTicksToWait is ignored if xTimerStart() is called\r
 489  * before the scheduler is started.\r
 490  *\r
 491  * @return pdFAIL will be returned if the start command could not be sent to\r
 492  * the timer command queue even after xTicksToWait ticks had passed.  pdPASS will\r
 493  * be returned if the command was successfully sent to the timer command queue.\r
 494  * When the command is actually processed will depend on the priority of the\r
 495  * timer service/daemon task relative to other tasks in the system, although the\r
 496  * timers expiry time is relative to when xTimerStart() is actually called.  The\r
 497  * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY\r
 498  * configuration constant.\r
 499  *\r
 500  * Example usage:\r
 501  *\r
 502  * See the xTimerCreate() API function example usage scenario.\r
 503  *\r
 504  */\r
 505     #define xTimerStart( xTimer, xTicksToWait )                                           xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )\r
 506 \r
 507 /**\r
 508  * BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );\r
 509  *\r
 510  * Timer functionality is provided by a timer service/daemon task.  Many of the\r
 511  * public FreeRTOS timer API functions send commands to the timer service task\r
 512  * through a queue called the timer command queue.  The timer command queue is\r
 513  * private to the kernel itself and is not directly accessible to application\r
 514  * code.  The length of the timer command queue is set by the\r
 515  * configTIMER_QUEUE_LENGTH configuration constant.\r
 516  *\r
 517  * xTimerStop() stops a timer that was previously started using either of the\r
 518  * The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(),\r
 519  * xTimerChangePeriod() or xTimerChangePeriodFromISR() API functions.\r
 520  *\r
 521  * Stopping a timer ensures the timer is not in the active state.\r
 522  *\r
 523  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop()\r
 524  * to be available.\r
 525  *\r
 526  * @param xTimer The handle of the timer being stopped.\r
 527  *\r
 528  * @param xTicksToWait Specifies the time, in ticks, that the calling task should\r
 529  * be held in the Blocked state to wait for the stop command to be successfully\r
 530  * sent to the timer command queue, should the queue already be full when\r
 531  * xTimerStop() was called.  xTicksToWait is ignored if xTimerStop() is called\r
 532  * before the scheduler is started.\r
 533  *\r
 534  * @return pdFAIL will be returned if the stop command could not be sent to\r
 535  * the timer command queue even after xTicksToWait ticks had passed.  pdPASS will\r
 536  * be returned if the command was successfully sent to the timer command queue.\r
 537  * When the command is actually processed will depend on the priority of the\r
 538  * timer service/daemon task relative to other tasks in the system.  The timer\r
 539  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY\r
 540  * configuration constant.\r
 541  *\r
 542  * Example usage:\r
 543  *\r
 544  * See the xTimerCreate() API function example usage scenario.\r
 545  *\r
 546  */\r
 547     #define xTimerStop( xTimer, xTicksToWait )                                            xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xTicksToWait ) )\r
 548 \r
 549 /**\r
 550  * BaseType_t xTimerChangePeriod(   TimerHandle_t xTimer,\r
 551  *                                                                              TickType_t xNewPeriod,\r
 552  *                                                                              TickType_t xTicksToWait );\r
 553  *\r
 554  * Timer functionality is provided by a timer service/daemon task.  Many of the\r
 555  * public FreeRTOS timer API functions send commands to the timer service task\r
 556  * through a queue called the timer command queue.  The timer command queue is\r
 557  * private to the kernel itself and is not directly accessible to application\r
 558  * code.  The length of the timer command queue is set by the\r
 559  * configTIMER_QUEUE_LENGTH configuration constant.\r
 560  *\r
 561  * xTimerChangePeriod() changes the period of a timer that was previously\r
 562  * created using the xTimerCreate() API function.\r
 563  *\r
 564  * xTimerChangePeriod() can be called to change the period of an active or\r
 565  * dormant state timer.\r
 566  *\r
 567  * The configUSE_TIMERS configuration constant must be set to 1 for\r
 568  * xTimerChangePeriod() to be available.\r
 569  *\r
 570  * @param xTimer The handle of the timer that is having its period changed.\r
 571  *\r
 572  * @param xNewPeriod The new period for xTimer. Timer periods are specified in\r
 573  * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time\r
 574  * that has been specified in milliseconds.  For example, if the timer must\r
 575  * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively,\r
 576  * if the timer must expire after 500ms, then xNewPeriod can be set to\r
 577  * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than\r
 578  * or equal to 1000.\r
 579  *\r
 580  * @param xTicksToWait Specifies the time, in ticks, that the calling task should\r
 581  * be held in the Blocked state to wait for the change period command to be\r
 582  * successfully sent to the timer command queue, should the queue already be\r
 583  * full when xTimerChangePeriod() was called.  xTicksToWait is ignored if\r
 584  * xTimerChangePeriod() is called before the scheduler is started.\r
 585  *\r
 586  * @return pdFAIL will be returned if the change period command could not be\r
 587  * sent to the timer command queue even after xTicksToWait ticks had passed.\r
 588  * pdPASS will be returned if the command was successfully sent to the timer\r
 589  * command queue.  When the command is actually processed will depend on the\r
 590  * priority of the timer service/daemon task relative to other tasks in the\r
 591  * system.  The timer service/daemon task priority is set by the\r
 592  * configTIMER_TASK_PRIORITY configuration constant.\r
 593  *\r
 594  * Example usage:\r
 595  * @verbatim\r
 596  * // This function assumes xTimer has already been created.  If the timer\r
 597  * // referenced by xTimer is already active when it is called, then the timer\r
 598  * // is deleted.  If the timer referenced by xTimer is not active when it is\r
 599  * // called, then the period of the timer is set to 500ms and the timer is\r
 600  * // started.\r
 601  * void vAFunction( TimerHandle_t xTimer )\r
 602  * {\r
 603  *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"\r
 604  *     {\r
 605  *         // xTimer is already active - delete it.\r
 606  *         xTimerDelete( xTimer );\r
 607  *     }\r
 608  *     else\r
 609  *     {\r
 610  *         // xTimer is not active, change its period to 500ms.  This will also\r
 611  *         // cause the timer to start.  Block for a maximum of 100 ticks if the\r
 612  *         // change period command cannot immediately be sent to the timer\r
 613  *         // command queue.\r
 614  *         if( xTimerChangePeriod( xTimer, 500 / portTICK_PERIOD_MS, 100 ) == pdPASS )\r
 615  *         {\r
 616  *             // The command was successfully sent.\r
 617  *         }\r
 618  *         else\r
 619  *         {\r
 620  *             // The command could not be sent, even after waiting for 100 ticks\r
 621  *             // to pass.  Take appropriate action here.\r
 622  *         }\r
 623  *     }\r
 624  * }\r
 625  * @endverbatim\r
 626  */\r
 627     #define xTimerChangePeriod( xTimer, xNewPeriod, xTicksToWait )                        xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xTicksToWait ) )\r
 628 \r
 629 /**\r
 630  * BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );\r
 631  *\r
 632  * Timer functionality is provided by a timer service/daemon task.  Many of the\r
 633  * public FreeRTOS timer API functions send commands to the timer service task\r
 634  * through a queue called the timer command queue.  The timer command queue is\r
 635  * private to the kernel itself and is not directly accessible to application\r
 636  * code.  The length of the timer command queue is set by the\r
 637  * configTIMER_QUEUE_LENGTH configuration constant.\r
 638  *\r
 639  * xTimerDelete() deletes a timer that was previously created using the\r
 640  * xTimerCreate() API function.\r
 641  *\r
 642  * The configUSE_TIMERS configuration constant must be set to 1 for\r
 643  * xTimerDelete() to be available.\r
 644  *\r
 645  * @param xTimer The handle of the timer being deleted.\r
 646  *\r
 647  * @param xTicksToWait Specifies the time, in ticks, that the calling task should\r
 648  * be held in the Blocked state to wait for the delete command to be\r
 649  * successfully sent to the timer command queue, should the queue already be\r
 650  * full when xTimerDelete() was called.  xTicksToWait is ignored if xTimerDelete()\r
 651  * is called before the scheduler is started.\r
 652  *\r
 653  * @return pdFAIL will be returned if the delete command could not be sent to\r
 654  * the timer command queue even after xTicksToWait ticks had passed.  pdPASS will\r
 655  * be returned if the command was successfully sent to the timer command queue.\r
 656  * When the command is actually processed will depend on the priority of the\r
 657  * timer service/daemon task relative to other tasks in the system.  The timer\r
 658  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY\r
 659  * configuration constant.\r
 660  *\r
 661  * Example usage:\r
 662  *\r
 663  * See the xTimerChangePeriod() API function example usage scenario.\r
 664  */\r
 665     #define xTimerDelete( xTimer, xTicksToWait )                                          xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xTicksToWait ) )\r
 666 \r
 667 /**\r
 668  * BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );\r
 669  *\r
 670  * Timer functionality is provided by a timer service/daemon task.  Many of the\r
 671  * public FreeRTOS timer API functions send commands to the timer service task\r
 672  * through a queue called the timer command queue.  The timer command queue is\r
 673  * private to the kernel itself and is not directly accessible to application\r
 674  * code.  The length of the timer command queue is set by the\r
 675  * configTIMER_QUEUE_LENGTH configuration constant.\r
 676  *\r
 677  * xTimerReset() re-starts a timer that was previously created using the\r
 678  * xTimerCreate() API function.  If the timer had already been started and was\r
 679  * already in the active state, then xTimerReset() will cause the timer to\r
 680  * re-evaluate its expiry time so that it is relative to when xTimerReset() was\r
 681  * called.  If the timer was in the dormant state then xTimerReset() has\r
 682  * equivalent functionality to the xTimerStart() API function.\r
 683  *\r
 684  * Resetting a timer ensures the timer is in the active state.  If the timer\r
 685  * is not stopped, deleted, or reset in the mean time, the callback function\r
 686  * associated with the timer will get called 'n' ticks after xTimerReset() was\r
 687  * called, where 'n' is the timers defined period.\r
 688  *\r
 689  * It is valid to call xTimerReset() before the scheduler has been started, but\r
 690  * when this is done the timer will not actually start until the scheduler is\r
 691  * started, and the timers expiry time will be relative to when the scheduler is\r
 692  * started, not relative to when xTimerReset() was called.\r
 693  *\r
 694  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset()\r
 695  * to be available.\r
 696  *\r
 697  * @param xTimer The handle of the timer being reset/started/restarted.\r
 698  *\r
 699  * @param xTicksToWait Specifies the time, in ticks, that the calling task should\r
 700  * be held in the Blocked state to wait for the reset command to be successfully\r
 701  * sent to the timer command queue, should the queue already be full when\r
 702  * xTimerReset() was called.  xTicksToWait is ignored if xTimerReset() is called\r
 703  * before the scheduler is started.\r
 704  *\r
 705  * @return pdFAIL will be returned if the reset command could not be sent to\r
 706  * the timer command queue even after xTicksToWait ticks had passed.  pdPASS will\r
 707  * be returned if the command was successfully sent to the timer command queue.\r
 708  * When the command is actually processed will depend on the priority of the\r
 709  * timer service/daemon task relative to other tasks in the system, although the\r
 710  * timers expiry time is relative to when xTimerStart() is actually called.  The\r
 711  * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY\r
 712  * configuration constant.\r
 713  *\r
 714  * Example usage:\r
 715  * @verbatim\r
 716  * // When a key is pressed, an LCD back-light is switched on.  If 5 seconds pass\r
 717  * // without a key being pressed, then the LCD back-light is switched off.  In\r
 718  * // this case, the timer is a one-shot timer.\r
 719  *\r
 720  * TimerHandle_t xBacklightTimer = NULL;\r
 721  *\r
 722  * // The callback function assigned to the one-shot timer.  In this case the\r
 723  * // parameter is not used.\r
 724  * void vBacklightTimerCallback( TimerHandle_t pxTimer )\r
 725  * {\r
 726  *     // The timer expired, therefore 5 seconds must have passed since a key\r
 727  *     // was pressed.  Switch off the LCD back-light.\r
 728  *     vSetBacklightState( BACKLIGHT_OFF );\r
 729  * }\r
 730  *\r
 731  * // The key press event handler.\r
 732  * void vKeyPressEventHandler( char cKey )\r
 733  * {\r
 734  *     // Ensure the LCD back-light is on, then reset the timer that is\r
 735  *     // responsible for turning the back-light off after 5 seconds of\r
 736  *     // key inactivity.  Wait 10 ticks for the command to be successfully sent\r
 737  *     // if it cannot be sent immediately.\r
 738  *     vSetBacklightState( BACKLIGHT_ON );\r
 739  *     if( xTimerReset( xBacklightTimer, 100 ) != pdPASS )\r
 740  *     {\r
 741  *         // The reset command was not executed successfully.  Take appropriate\r
 742  *         // action here.\r
 743  *     }\r
 744  *\r
 745  *     // Perform the rest of the key processing here.\r
 746  * }\r
 747  *\r
 748  * void main( void )\r
 749  * {\r
 750  * int32_t x;\r
 751  *\r
 752  *     // Create then start the one-shot timer that is responsible for turning\r
 753  *     // the back-light off if no keys are pressed within a 5 second period.\r
 754  *     xBacklightTimer = xTimerCreate( "BacklightTimer",           // Just a text name, not used by the kernel.\r
 755  *                                     ( 5000 / portTICK_PERIOD_MS), // The timer period in ticks.\r
 756  *                                     pdFALSE,                    // The timer is a one-shot timer.\r
 757  *                                     0,                          // The id is not used by the callback so can take any value.\r
 758  *                                     vBacklightTimerCallback     // The callback function that switches the LCD back-light off.\r
 759  *                                   );\r
 760  *\r
 761  *     if( xBacklightTimer == NULL )\r
 762  *     {\r
 763  *         // The timer was not created.\r
 764  *     }\r
 765  *     else\r
 766  *     {\r
 767  *         // Start the timer.  No block time is specified, and even if one was\r
 768  *         // it would be ignored because the scheduler has not yet been\r
 769  *         // started.\r
 770  *         if( xTimerStart( xBacklightTimer, 0 ) != pdPASS )\r
 771  *         {\r
 772  *             // The timer could not be set into the Active state.\r
 773  *         }\r
 774  *     }\r
 775  *\r
 776  *     // ...\r
 777  *     // Create tasks here.\r
 778  *     // ...\r
 779  *\r
 780  *     // Starting the scheduler will start the timer running as it has already\r
 781  *     // been set into the active state.\r
 782  *     vTaskStartScheduler();\r
 783  *\r
 784  *     // Should not reach here.\r
 785  *     for( ;; );\r
 786  * }\r
 787  * @endverbatim\r
 788  */\r
 789     #define xTimerReset( xTimer, xTicksToWait )                                           xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )\r
 790 \r
 791 /**\r
 792  * BaseType_t xTimerStartFromISR(   TimerHandle_t xTimer,\r
 793  *                                                                      BaseType_t *pxHigherPriorityTaskWoken );\r
 794  *\r
 795  * A version of xTimerStart() that can be called from an interrupt service\r
 796  * routine.\r
 797  *\r
 798  * @param xTimer The handle of the timer being started/restarted.\r
 799  *\r
 800  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most\r
 801  * of its time in the Blocked state, waiting for messages to arrive on the timer\r
 802  * command queue.  Calling xTimerStartFromISR() writes a message to the timer\r
 803  * command queue, so has the potential to transition the timer service/daemon\r
 804  * task out of the Blocked state.  If calling xTimerStartFromISR() causes the\r
 805  * timer service/daemon task to leave the Blocked state, and the timer service/\r
 806  * daemon task has a priority equal to or greater than the currently executing\r
 807  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will\r
 808  * get set to pdTRUE internally within the xTimerStartFromISR() function.  If\r
 809  * xTimerStartFromISR() sets this value to pdTRUE then a context switch should\r
 810  * be performed before the interrupt exits.\r
 811  *\r
 812  * @return pdFAIL will be returned if the start command could not be sent to\r
 813  * the timer command queue.  pdPASS will be returned if the command was\r
 814  * successfully sent to the timer command queue.  When the command is actually\r
 815  * processed will depend on the priority of the timer service/daemon task\r
 816  * relative to other tasks in the system, although the timers expiry time is\r
 817  * relative to when xTimerStartFromISR() is actually called.  The timer\r
 818  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY\r
 819  * configuration constant.\r
 820  *\r
 821  * Example usage:\r
 822  * @verbatim\r
 823  * // This scenario assumes xBacklightTimer has already been created.  When a\r
 824  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass\r
 825  * // without a key being pressed, then the LCD back-light is switched off.  In\r
 826  * // this case, the timer is a one-shot timer, and unlike the example given for\r
 827  * // the xTimerReset() function, the key press event handler is an interrupt\r
 828  * // service routine.\r
 829  *\r
 830  * // The callback function assigned to the one-shot timer.  In this case the\r
 831  * // parameter is not used.\r
 832  * void vBacklightTimerCallback( TimerHandle_t pxTimer )\r
 833  * {\r
 834  *     // The timer expired, therefore 5 seconds must have passed since a key\r
 835  *     // was pressed.  Switch off the LCD back-light.\r
 836  *     vSetBacklightState( BACKLIGHT_OFF );\r
 837  * }\r
 838  *\r
 839  * // The key press interrupt service routine.\r
 840  * void vKeyPressEventInterruptHandler( void )\r
 841  * {\r
 842  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;\r
 843  *\r
 844  *     // Ensure the LCD back-light is on, then restart the timer that is\r
 845  *     // responsible for turning the back-light off after 5 seconds of\r
 846  *     // key inactivity.  This is an interrupt service routine so can only\r
 847  *     // call FreeRTOS API functions that end in "FromISR".\r
 848  *     vSetBacklightState( BACKLIGHT_ON );\r
 849  *\r
 850  *     // xTimerStartFromISR() or xTimerResetFromISR() could be called here\r
 851  *     // as both cause the timer to re-calculate its expiry time.\r
 852  *     // xHigherPriorityTaskWoken was initialised to pdFALSE when it was\r
 853  *     // declared (in this function).\r
 854  *     if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )\r
 855  *     {\r
 856  *         // The start command was not executed successfully.  Take appropriate\r
 857  *         // action here.\r
 858  *     }\r
 859  *\r
 860  *     // Perform the rest of the key processing here.\r
 861  *\r
 862  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch\r
 863  *     // should be performed.  The syntax required to perform a context switch\r
 864  *     // from inside an ISR varies from port to port, and from compiler to\r
 865  *     // compiler.  Inspect the demos for the port you are using to find the\r
 866  *     // actual syntax required.\r
 867  *     if( xHigherPriorityTaskWoken != pdFALSE )\r
 868  *     {\r
 869  *         // Call the interrupt safe yield function here (actual function\r
 870  *         // depends on the FreeRTOS port being used).\r
 871  *     }\r
 872  * }\r
 873  * @endverbatim\r
 874  */\r
 875     #define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken )                       xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )\r
 876 \r
 877 /**\r
 878  * BaseType_t xTimerStopFromISR(    TimerHandle_t xTimer,\r
 879  *                                                                      BaseType_t *pxHigherPriorityTaskWoken );\r
 880  *\r
 881  * A version of xTimerStop() that can be called from an interrupt service\r
 882  * routine.\r
 883  *\r
 884  * @param xTimer The handle of the timer being stopped.\r
 885  *\r
 886  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most\r
 887  * of its time in the Blocked state, waiting for messages to arrive on the timer\r
 888  * command queue.  Calling xTimerStopFromISR() writes a message to the timer\r
 889  * command queue, so has the potential to transition the timer service/daemon\r
 890  * task out of the Blocked state.  If calling xTimerStopFromISR() causes the\r
 891  * timer service/daemon task to leave the Blocked state, and the timer service/\r
 892  * daemon task has a priority equal to or greater than the currently executing\r
 893  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will\r
 894  * get set to pdTRUE internally within the xTimerStopFromISR() function.  If\r
 895  * xTimerStopFromISR() sets this value to pdTRUE then a context switch should\r
 896  * be performed before the interrupt exits.\r
 897  *\r
 898  * @return pdFAIL will be returned if the stop command could not be sent to\r
 899  * the timer command queue.  pdPASS will be returned if the command was\r
 900  * successfully sent to the timer command queue.  When the command is actually\r
 901  * processed will depend on the priority of the timer service/daemon task\r
 902  * relative to other tasks in the system.  The timer service/daemon task\r
 903  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.\r
 904  *\r
 905  * Example usage:\r
 906  * @verbatim\r
 907  * // This scenario assumes xTimer has already been created and started.  When\r
 908  * // an interrupt occurs, the timer should be simply stopped.\r
 909  *\r
 910  * // The interrupt service routine that stops the timer.\r
 911  * void vAnExampleInterruptServiceRoutine( void )\r
 912  * {\r
 913  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;\r
 914  *\r
 915  *     // The interrupt has occurred - simply stop the timer.\r
 916  *     // xHigherPriorityTaskWoken was set to pdFALSE where it was defined\r
 917  *     // (within this function).  As this is an interrupt service routine, only\r
 918  *     // FreeRTOS API functions that end in "FromISR" can be used.\r
 919  *     if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )\r
 920  *     {\r
 921  *         // The stop command was not executed successfully.  Take appropriate\r
 922  *         // action here.\r
 923  *     }\r
 924  *\r
 925  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch\r
 926  *     // should be performed.  The syntax required to perform a context switch\r
 927  *     // from inside an ISR varies from port to port, and from compiler to\r
 928  *     // compiler.  Inspect the demos for the port you are using to find the\r
 929  *     // actual syntax required.\r
 930  *     if( xHigherPriorityTaskWoken != pdFALSE )\r
 931  *     {\r
 932  *         // Call the interrupt safe yield function here (actual function\r
 933  *         // depends on the FreeRTOS port being used).\r
 934  *     }\r
 935  * }\r
 936  * @endverbatim\r
 937  */\r
 938     #define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken )                        xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U )\r
 939 \r
 940 /**\r
 941  * BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer,\r
 942  *                                                                               TickType_t xNewPeriod,\r
 943  *                                                                               BaseType_t *pxHigherPriorityTaskWoken );\r
 944  *\r
 945  * A version of xTimerChangePeriod() that can be called from an interrupt\r
 946  * service routine.\r
 947  *\r
 948  * @param xTimer The handle of the timer that is having its period changed.\r
 949  *\r
 950  * @param xNewPeriod The new period for xTimer. Timer periods are specified in\r
 951  * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time\r
 952  * that has been specified in milliseconds.  For example, if the timer must\r
 953  * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively,\r
 954  * if the timer must expire after 500ms, then xNewPeriod can be set to\r
 955  * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than\r
 956  * or equal to 1000.\r
 957  *\r
 958  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most\r
 959  * of its time in the Blocked state, waiting for messages to arrive on the timer\r
 960  * command queue.  Calling xTimerChangePeriodFromISR() writes a message to the\r
 961  * timer command queue, so has the potential to transition the timer service/\r
 962  * daemon task out of the Blocked state.  If calling xTimerChangePeriodFromISR()\r
 963  * causes the timer service/daemon task to leave the Blocked state, and the\r
 964  * timer service/daemon task has a priority equal to or greater than the\r
 965  * currently executing task (the task that was interrupted), then\r
 966  * *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the\r
 967  * xTimerChangePeriodFromISR() function.  If xTimerChangePeriodFromISR() sets\r
 968  * this value to pdTRUE then a context switch should be performed before the\r
 969  * interrupt exits.\r
 970  *\r
 971  * @return pdFAIL will be returned if the command to change the timers period\r
 972  * could not be sent to the timer command queue.  pdPASS will be returned if the\r
 973  * command was successfully sent to the timer command queue.  When the command\r
 974  * is actually processed will depend on the priority of the timer service/daemon\r
 975  * task relative to other tasks in the system.  The timer service/daemon task\r
 976  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.\r
 977  *\r
 978  * Example usage:\r
 979  * @verbatim\r
 980  * // This scenario assumes xTimer has already been created and started.  When\r
 981  * // an interrupt occurs, the period of xTimer should be changed to 500ms.\r
 982  *\r
 983  * // The interrupt service routine that changes the period of xTimer.\r
 984  * void vAnExampleInterruptServiceRoutine( void )\r
 985  * {\r
 986  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;\r
 987  *\r
 988  *     // The interrupt has occurred - change the period of xTimer to 500ms.\r
 989  *     // xHigherPriorityTaskWoken was set to pdFALSE where it was defined\r
 990  *     // (within this function).  As this is an interrupt service routine, only\r
 991  *     // FreeRTOS API functions that end in "FromISR" can be used.\r
 992  *     if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )\r
 993  *     {\r
 994  *         // The command to change the timers period was not executed\r
 995  *         // successfully.  Take appropriate action here.\r
 996  *     }\r
 997  *\r
 998  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch\r
 999  *     // should be performed.  The syntax required to perform a context switch\r
1000  *     // from inside an ISR varies from port to port, and from compiler to\r
1001  *     // compiler.  Inspect the demos for the port you are using to find the\r
1002  *     // actual syntax required.\r
1003  *     if( xHigherPriorityTaskWoken != pdFALSE )\r
1004  *     {\r
1005  *         // Call the interrupt safe yield function here (actual function\r
1006  *         // depends on the FreeRTOS port being used).\r
1007  *     }\r
1008  * }\r
1009  * @endverbatim\r
1010  */\r
1011     #define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken )    xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )\r
1012 \r
1013 /**\r
1014  * BaseType_t xTimerResetFromISR(   TimerHandle_t xTimer,\r
1015  *                                                                      BaseType_t *pxHigherPriorityTaskWoken );\r
1016  *\r
1017  * A version of xTimerReset() that can be called from an interrupt service\r
1018  * routine.\r
1019  *\r
1020  * @param xTimer The handle of the timer that is to be started, reset, or\r
1021  * restarted.\r
1022  *\r
1023  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most\r
1024  * of its time in the Blocked state, waiting for messages to arrive on the timer\r
1025  * command queue.  Calling xTimerResetFromISR() writes a message to the timer\r
1026  * command queue, so has the potential to transition the timer service/daemon\r
1027  * task out of the Blocked state.  If calling xTimerResetFromISR() causes the\r
1028  * timer service/daemon task to leave the Blocked state, and the timer service/\r
1029  * daemon task has a priority equal to or greater than the currently executing\r
1030  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will\r
1031  * get set to pdTRUE internally within the xTimerResetFromISR() function.  If\r
1032  * xTimerResetFromISR() sets this value to pdTRUE then a context switch should\r
1033  * be performed before the interrupt exits.\r
1034  *\r
1035  * @return pdFAIL will be returned if the reset command could not be sent to\r
1036  * the timer command queue.  pdPASS will be returned if the command was\r
1037  * successfully sent to the timer command queue.  When the command is actually\r
1038  * processed will depend on the priority of the timer service/daemon task\r
1039  * relative to other tasks in the system, although the timers expiry time is\r
1040  * relative to when xTimerResetFromISR() is actually called.  The timer service/daemon\r
1041  * task priority is set by the configTIMER_TASK_PRIORITY configuration constant.\r
1042  *\r
1043  * Example usage:\r
1044  * @verbatim\r
1045  * // This scenario assumes xBacklightTimer has already been created.  When a\r
1046  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass\r
1047  * // without a key being pressed, then the LCD back-light is switched off.  In\r
1048  * // this case, the timer is a one-shot timer, and unlike the example given for\r
1049  * // the xTimerReset() function, the key press event handler is an interrupt\r
1050  * // service routine.\r
1051  *\r
1052  * // The callback function assigned to the one-shot timer.  In this case the\r
1053  * // parameter is not used.\r
1054  * void vBacklightTimerCallback( TimerHandle_t pxTimer )\r
1055  * {\r
1056  *     // The timer expired, therefore 5 seconds must have passed since a key\r
1057  *     // was pressed.  Switch off the LCD back-light.\r
1058  *     vSetBacklightState( BACKLIGHT_OFF );\r
1059  * }\r
1060  *\r
1061  * // The key press interrupt service routine.\r
1062  * void vKeyPressEventInterruptHandler( void )\r
1063  * {\r
1064  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;\r
1065  *\r
1066  *     // Ensure the LCD back-light is on, then reset the timer that is\r
1067  *     // responsible for turning the back-light off after 5 seconds of\r
1068  *     // key inactivity.  This is an interrupt service routine so can only\r
1069  *     // call FreeRTOS API functions that end in "FromISR".\r
1070  *     vSetBacklightState( BACKLIGHT_ON );\r
1071  *\r
1072  *     // xTimerStartFromISR() or xTimerResetFromISR() could be called here\r
1073  *     // as both cause the timer to re-calculate its expiry time.\r
1074  *     // xHigherPriorityTaskWoken was initialised to pdFALSE when it was\r
1075  *     // declared (in this function).\r
1076  *     if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )\r
1077  *     {\r
1078  *         // The reset command was not executed successfully.  Take appropriate\r
1079  *         // action here.\r
1080  *     }\r
1081  *\r
1082  *     // Perform the rest of the key processing here.\r
1083  *\r
1084  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch\r
1085  *     // should be performed.  The syntax required to perform a context switch\r
1086  *     // from inside an ISR varies from port to port, and from compiler to\r
1087  *     // compiler.  Inspect the demos for the port you are using to find the\r
1088  *     // actual syntax required.\r
1089  *     if( xHigherPriorityTaskWoken != pdFALSE )\r
1090  *     {\r
1091  *         // Call the interrupt safe yield function here (actual function\r
1092  *         // depends on the FreeRTOS port being used).\r
1093  *     }\r
1094  * }\r
1095  * @endverbatim\r
1096  */\r
1097     #define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken )                       xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )\r
1098 \r
1099 \r
1100 /**\r
1101  * BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,\r
1102  *                                          void *pvParameter1,\r
1103  *                                          uint32_t ulParameter2,\r
1104  *                                          BaseType_t *pxHigherPriorityTaskWoken );\r
1105  *\r
1106  *\r
1107  * Used from application interrupt service routines to defer the execution of a\r
1108  * function to the RTOS daemon task (the timer service task, hence this function\r
1109  * is implemented in timers.c and is prefixed with 'Timer').\r
1110  *\r
1111  * Ideally an interrupt service routine (ISR) is kept as short as possible, but\r
1112  * sometimes an ISR either has a lot of processing to do, or needs to perform\r
1113  * processing that is not deterministic.  In these cases\r
1114  * xTimerPendFunctionCallFromISR() can be used to defer processing of a function\r
1115  * to the RTOS daemon task.\r
1116  *\r
1117  * A mechanism is provided that allows the interrupt to return directly to the\r
1118  * task that will subsequently execute the pended callback function.  This\r
1119  * allows the callback function to execute contiguously in time with the\r
1120  * interrupt - just as if the callback had executed in the interrupt itself.\r
1121  *\r
1122  * @param xFunctionToPend The function to execute from the timer service/\r
1123  * daemon task.  The function must conform to the PendedFunction_t\r
1124  * prototype.\r
1125  *\r
1126  * @param pvParameter1 The value of the callback function's first parameter.\r
1127  * The parameter has a void * type to allow it to be used to pass any type.\r
1128  * For example, unsigned longs can be cast to a void *, or the void * can be\r
1129  * used to point to a structure.\r
1130  *\r
1131  * @param ulParameter2 The value of the callback function's second parameter.\r
1132  *\r
1133  * @param pxHigherPriorityTaskWoken As mentioned above, calling this function\r
1134  * will result in a message being sent to the timer daemon task.  If the\r
1135  * priority of the timer daemon task (which is set using\r
1136  * configTIMER_TASK_PRIORITY in FreeRTOSConfig.h) is higher than the priority of\r
1137  * the currently running task (the task the interrupt interrupted) then\r
1138  * *pxHigherPriorityTaskWoken will be set to pdTRUE within\r
1139  * xTimerPendFunctionCallFromISR(), indicating that a context switch should be\r
1140  * requested before the interrupt exits.  For that reason\r
1141  * *pxHigherPriorityTaskWoken must be initialised to pdFALSE.  See the\r
1142  * example code below.\r
1143  *\r
1144  * @return pdPASS is returned if the message was successfully sent to the\r
1145  * timer daemon task, otherwise pdFALSE is returned.\r
1146  *\r
1147  * Example usage:\r
1148  * @verbatim\r
1149  *\r
1150  *      // The callback function that will execute in the context of the daemon task.\r
1151  *  // Note callback functions must all use this same prototype.\r
1152  *  void vProcessInterface( void *pvParameter1, uint32_t ulParameter2 )\r
1153  *      {\r
1154  *              BaseType_t xInterfaceToService;\r
1155  *\r
1156  *              // The interface that requires servicing is passed in the second\r
1157  *      // parameter.  The first parameter is not used in this case.\r
1158  *              xInterfaceToService = ( BaseType_t ) ulParameter2;\r
1159  *\r
1160  *              // ...Perform the processing here...\r
1161  *      }\r
1162  *\r
1163  *      // An ISR that receives data packets from multiple interfaces\r
1164  *  void vAnISR( void )\r
1165  *      {\r
1166  *              BaseType_t xInterfaceToService, xHigherPriorityTaskWoken;\r
1167  *\r
1168  *              // Query the hardware to determine which interface needs processing.\r
1169  *              xInterfaceToService = prvCheckInterfaces();\r
1170  *\r
1171  *      // The actual processing is to be deferred to a task.  Request the\r
1172  *      // vProcessInterface() callback function is executed, passing in the\r
1173  *              // number of the interface that needs processing.  The interface to\r
1174  *              // service is passed in the second parameter.  The first parameter is\r
1175  *              // not used in this case.\r
1176  *              xHigherPriorityTaskWoken = pdFALSE;\r
1177  *              xTimerPendFunctionCallFromISR( vProcessInterface, NULL, ( uint32_t ) xInterfaceToService, &xHigherPriorityTaskWoken );\r
1178  *\r
1179  *              // If xHigherPriorityTaskWoken is now set to pdTRUE then a context\r
1180  *              // switch should be requested.  The macro used is port specific and will\r
1181  *              // be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to\r
1182  *              // the documentation page for the port being used.\r
1183  *              portYIELD_FROM_ISR( xHigherPriorityTaskWoken );\r
1184  *\r
1185  *      }\r
1186  * @endverbatim\r
1187  */\r
1188     BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,\r
1189                                               void * pvParameter1,\r
1190                                               uint32_t ulParameter2,\r
1191                                               BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;\r
1192 \r
1193 /**\r
1194  * BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,\r
1195  *                                    void *pvParameter1,\r
1196  *                                    uint32_t ulParameter2,\r
1197  *                                    TickType_t xTicksToWait );\r
1198  *\r
1199  *\r
1200  * Used to defer the execution of a function to the RTOS daemon task (the timer\r
1201  * service task, hence this function is implemented in timers.c and is prefixed\r
1202  * with 'Timer').\r
1203  *\r
1204  * @param xFunctionToPend The function to execute from the timer service/\r
1205  * daemon task.  The function must conform to the PendedFunction_t\r
1206  * prototype.\r
1207  *\r
1208  * @param pvParameter1 The value of the callback function's first parameter.\r
1209  * The parameter has a void * type to allow it to be used to pass any type.\r
1210  * For example, unsigned longs can be cast to a void *, or the void * can be\r
1211  * used to point to a structure.\r
1212  *\r
1213  * @param ulParameter2 The value of the callback function's second parameter.\r
1214  *\r
1215  * @param xTicksToWait Calling this function will result in a message being\r
1216  * sent to the timer daemon task on a queue.  xTicksToWait is the amount of\r
1217  * time the calling task should remain in the Blocked state (so not using any\r
1218  * processing time) for space to become available on the timer queue if the\r
1219  * queue is found to be full.\r
1220  *\r
1221  * @return pdPASS is returned if the message was successfully sent to the\r
1222  * timer daemon task, otherwise pdFALSE is returned.\r
1223  *\r
1224  */\r
1225     BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,\r
1226                                        void * pvParameter1,\r
1227                                        uint32_t ulParameter2,\r
1228                                        TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;\r
1229 \r
1230 /**\r
1231  * const char * const pcTimerGetName( TimerHandle_t xTimer );\r
1232  *\r
1233  * Returns the name that was assigned to a timer when the timer was created.\r
1234  *\r
1235  * @param xTimer The handle of the timer being queried.\r
1236  *\r
1237  * @return The name assigned to the timer specified by the xTimer parameter.\r
1238  */\r
1239     const char * pcTimerGetName( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
1240 \r
1241 /**\r
1242  * void vTimerSetReloadMode( TimerHandle_t xTimer, const UBaseType_t uxAutoReload );\r
1243  *\r
1244  * Updates a timer to be either an auto-reload timer, in which case the timer\r
1245  * automatically resets itself each time it expires, or a one-shot timer, in\r
1246  * which case the timer will only expire once unless it is manually restarted.\r
1247  *\r
1248  * @param xTimer The handle of the timer being updated.\r
1249  *\r
1250  * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will\r
1251  * expire repeatedly with a frequency set by the timer's period (see the\r
1252  * xTimerPeriodInTicks parameter of the xTimerCreate() API function).  If\r
1253  * uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and\r
1254  * enter the dormant state after it expires.\r
1255  */\r
1256     void vTimerSetReloadMode( TimerHandle_t xTimer,\r
1257                               const UBaseType_t uxAutoReload ) PRIVILEGED_FUNCTION;\r
1258 \r
1259 /**\r
1260  * UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer );\r
1261  *\r
1262  * Queries a timer to determine if it is an auto-reload timer, in which case the timer\r
1263  * automatically resets itself each time it expires, or a one-shot timer, in\r
1264  * which case the timer will only expire once unless it is manually restarted.\r
1265  *\r
1266  * @param xTimer The handle of the timer being queried.\r
1267  *\r
1268  * @return If the timer is an auto-reload timer then pdTRUE is returned, otherwise\r
1269  * pdFALSE is returned.\r
1270  */\r
1271     UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;\r
1272 \r
1273 /**\r
1274  * TickType_t xTimerGetPeriod( TimerHandle_t xTimer );\r
1275  *\r
1276  * Returns the period of a timer.\r
1277  *\r
1278  * @param xTimer The handle of the timer being queried.\r
1279  *\r
1280  * @return The period of the timer in ticks.\r
1281  */\r
1282     TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;\r
1283 \r
1284 /**\r
1285  * TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );\r
1286  *\r
1287  * Returns the time in ticks at which the timer will expire.  If this is less\r
1288  * than the current tick count then the expiry time has overflowed from the\r
1289  * current time.\r
1290  *\r
1291  * @param xTimer The handle of the timer being queried.\r
1292  *\r
1293  * @return If the timer is running then the time in ticks at which the timer\r
1294  * will next expire is returned.  If the timer is not running then the return\r
1295  * value is undefined.\r
1296  */\r
1297     TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;\r
1298 \r
1299 /*\r
1300  * Functions beyond this part are not part of the public API and are intended\r
1301  * for use by the kernel only.\r
1302  */\r
1303     BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;\r
1304     BaseType_t xTimerGenericCommand( TimerHandle_t xTimer,\r
1305                                      const BaseType_t xCommandID,\r
1306                                      const TickType_t xOptionalValue,\r
1307                                      BaseType_t * const pxHigherPriorityTaskWoken,\r
1308                                      const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;\r
1309 \r
1310     #if ( configUSE_TRACE_FACILITY == 1 )\r
1311         void vTimerSetTimerNumber( TimerHandle_t xTimer,\r
1312                                    UBaseType_t uxTimerNumber ) PRIVILEGED_FUNCTION;\r
1313         UBaseType_t uxTimerGetTimerNumber( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;\r
1314     #endif\r
1315 \r
1316     #ifdef __cplusplus\r
1317         }\r
1318     #endif\r
1319 #endif /* TIMERS_H */\r