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