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

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