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