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  *     // Ensure the LCD back-light is on, then reset the timer that is
 741  *     // responsible for turning the back-light off after 5 seconds of
 742  *     // key inactivity.  Wait 10 ticks for the command to be successfully sent
 743  *     // if it cannot be sent immediately.
 744  *     vSetBacklightState( BACKLIGHT_ON );
 745  *     if( xTimerReset( xBacklightTimer, 100 ) != pdPASS )
 746  *     {
 747  *         // The reset command was not executed successfully.  Take appropriate
 748  *         // action here.
 749  *     }
 750  *
 751  *     // Perform the rest of the key processing here.
 752  * }
 753  *
 754  * void main( void )
 755  * {
 756  * int32_t x;
 757  *
 758  *     // Create then start the one-shot timer that is responsible for turning
 759  *     // the back-light off if no keys are pressed within a 5 second period.
 760  *     xBacklightTimer = xTimerCreate( "BacklightTimer",           // Just a text name, not used by the kernel.
 761  *                                     ( 5000 / portTICK_PERIOD_MS), // The timer period in ticks.
 762  *                                     pdFALSE,                    // The timer is a one-shot timer.
 763  *                                     0,                          // The id is not used by the callback so can take any value.
 764  *                                     vBacklightTimerCallback     // The callback function that switches the LCD back-light off.
 765  *                                   );
 766  *
 767  *     if( xBacklightTimer == NULL )
 768  *     {
 769  *         // The timer was not created.
 770  *     }
 771  *     else
 772  *     {
 773  *         // Start the timer.  No block time is specified, and even if one was
 774  *         // it would be ignored because the scheduler has not yet been
 775  *         // started.
 776  *         if( xTimerStart( xBacklightTimer, 0 ) != pdPASS )
 777  *         {
 778  *             // The timer could not be set into the Active state.
 779  *         }
 780  *     }
 781  *
 782  *     // ...
 783  *     // Create tasks here.
 784  *     // ...
 785  *
 786  *     // Starting the scheduler will start the timer running as it has already
 787  *     // been set into the active state.
 788  *     vTaskStartScheduler();
 789  *
 790  *     // Should not reach here.
 791  *     for( ;; );
 792  * }
 793  * @endverbatim
 794  */
 795 #define xTimerReset( xTimer, xTicksToWait ) \
 796     xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
 797
 798 /**
 799  * BaseType_t xTimerStartFromISR(   TimerHandle_t xTimer,
 800  *                                  BaseType_t *pxHigherPriorityTaskWoken );
 801  *
 802  * A version of xTimerStart() that can be called from an interrupt service
 803  * routine.
 804  *
 805  * @param xTimer The handle of the timer being started/restarted.
 806  *
 807  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
 808  * of its time in the Blocked state, waiting for messages to arrive on the timer
 809  * command queue.  Calling xTimerStartFromISR() writes a message to the timer
 810  * command queue, so has the potential to transition the timer service/daemon
 811  * task out of the Blocked state.  If calling xTimerStartFromISR() causes the
 812  * timer service/daemon task to leave the Blocked state, and the timer service/
 813  * daemon task has a priority equal to or greater than the currently executing
 814  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
 815  * get set to pdTRUE internally within the xTimerStartFromISR() function.  If
 816  * xTimerStartFromISR() sets this value to pdTRUE then a context switch should
 817  * be performed before the interrupt exits.
 818  *
 819  * @return pdFAIL will be returned if the start command could not be sent to
 820  * the timer command queue.  pdPASS will be returned if the command was
 821  * successfully sent to the timer command queue.  When the command is actually
 822  * processed will depend on the priority of the timer service/daemon task
 823  * relative to other tasks in the system, although the timers expiry time is
 824  * relative to when xTimerStartFromISR() is actually called.  The timer
 825  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
 826  * configuration constant.
 827  *
 828  * Example usage:
 829  * @verbatim
 830  * // This scenario assumes xBacklightTimer has already been created.  When a
 831  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass
 832  * // without a key being pressed, then the LCD back-light is switched off.  In
 833  * // this case, the timer is a one-shot timer, and unlike the example given for
 834  * // the xTimerReset() function, the key press event handler is an interrupt
 835  * // service routine.
 836  *
 837  * // The callback function assigned to the one-shot timer.  In this case the
 838  * // parameter is not used.
 839  * void vBacklightTimerCallback( TimerHandle_t pxTimer )
 840  * {
 841  *     // The timer expired, therefore 5 seconds must have passed since a key
 842  *     // was pressed.  Switch off the LCD back-light.
 843  *     vSetBacklightState( BACKLIGHT_OFF );
 844  * }
 845  *
 846  * // The key press interrupt service routine.
 847  * void vKeyPressEventInterruptHandler( void )
 848  * {
 849  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
 850  *
 851  *     // Ensure the LCD back-light is on, then restart the timer that is
 852  *     // responsible for turning the back-light off after 5 seconds of
 853  *     // key inactivity.  This is an interrupt service routine so can only
 854  *     // call FreeRTOS API functions that end in "FromISR".
 855  *     vSetBacklightState( BACKLIGHT_ON );
 856  *
 857  *     // xTimerStartFromISR() or xTimerResetFromISR() could be called here
 858  *     // as both cause the timer to re-calculate its expiry time.
 859  *     // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
 860  *     // declared (in this function).
 861  *     if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )
 862  *     {
 863  *         // The start command was not executed successfully.  Take appropriate
 864  *         // action here.
 865  *     }
 866  *
 867  *     // Perform the rest of the key processing here.
 868  *
 869  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
 870  *     // should be performed.  The syntax required to perform a context switch
 871  *     // from inside an ISR varies from port to port, and from compiler to
 872  *     // compiler.  Inspect the demos for the port you are using to find the
 873  *     // actual syntax required.
 874  *     if( xHigherPriorityTaskWoken != pdFALSE )
 875  *     {
 876  *         // Call the interrupt safe yield function here (actual function
 877  *         // depends on the FreeRTOS port being used).
 878  *     }
 879  * }
 880  * @endverbatim
 881  */
 882 #define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken ) \
 883     xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
 884
 885 /**
 886  * BaseType_t xTimerStopFromISR(    TimerHandle_t xTimer,
 887  *                                  BaseType_t *pxHigherPriorityTaskWoken );
 888  *
 889  * A version of xTimerStop() that can be called from an interrupt service
 890  * routine.
 891  *
 892  * @param xTimer The handle of the timer being stopped.
 893  *
 894  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
 895  * of its time in the Blocked state, waiting for messages to arrive on the timer
 896  * command queue.  Calling xTimerStopFromISR() writes a message to the timer
 897  * command queue, so has the potential to transition the timer service/daemon
 898  * task out of the Blocked state.  If calling xTimerStopFromISR() causes the
 899  * timer service/daemon task to leave the Blocked state, and the timer service/
 900  * daemon task has a priority equal to or greater than the currently executing
 901  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
 902  * get set to pdTRUE internally within the xTimerStopFromISR() function.  If
 903  * xTimerStopFromISR() sets this value to pdTRUE then a context switch should
 904  * be performed before the interrupt exits.
 905  *
 906  * @return pdFAIL will be returned if the stop command could not be sent to
 907  * the timer command queue.  pdPASS will be returned if the command was
 908  * successfully sent to the timer command queue.  When the command is actually
 909  * processed will depend on the priority of the timer service/daemon task
 910  * relative to other tasks in the system.  The timer service/daemon task
 911  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
 912  *
 913  * Example usage:
 914  * @verbatim
 915  * // This scenario assumes xTimer has already been created and started.  When
 916  * // an interrupt occurs, the timer should be simply stopped.
 917  *
 918  * // The interrupt service routine that stops the timer.
 919  * void vAnExampleInterruptServiceRoutine( void )
 920  * {
 921  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
 922  *
 923  *     // The interrupt has occurred - simply stop the timer.
 924  *     // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
 925  *     // (within this function).  As this is an interrupt service routine, only
 926  *     // FreeRTOS API functions that end in "FromISR" can be used.
 927  *     if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
 928  *     {
 929  *         // The stop command was not executed successfully.  Take appropriate
 930  *         // action here.
 931  *     }
 932  *
 933  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
 934  *     // should be performed.  The syntax required to perform a context switch
 935  *     // from inside an ISR varies from port to port, and from compiler to
 936  *     // compiler.  Inspect the demos for the port you are using to find the
 937  *     // actual syntax required.
 938  *     if( xHigherPriorityTaskWoken != pdFALSE )
 939  *     {
 940  *         // Call the interrupt safe yield function here (actual function
 941  *         // depends on the FreeRTOS port being used).
 942  *     }
 943  * }
 944  * @endverbatim
 945  */
 946 #define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken ) \
 947     xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U )
 948
 949 /**
 950  * BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer,
 951  *                                       TickType_t xNewPeriod,
 952  *                                       BaseType_t *pxHigherPriorityTaskWoken );
 953  *
 954  * A version of xTimerChangePeriod() that can be called from an interrupt
 955  * service routine.
 956  *
 957  * @param xTimer The handle of the timer that is having its period changed.
 958  *
 959  * @param xNewPeriod The new period for xTimer. Timer periods are specified in
 960  * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time
 961  * that has been specified in milliseconds.  For example, if the timer must
 962  * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively,
 963  * if the timer must expire after 500ms, then xNewPeriod can be set to
 964  * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than
 965  * or equal to 1000.
 966  *
 967  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
 968  * of its time in the Blocked state, waiting for messages to arrive on the timer
 969  * command queue.  Calling xTimerChangePeriodFromISR() writes a message to the
 970  * timer command queue, so has the potential to transition the timer service/
 971  * daemon task out of the Blocked state.  If calling xTimerChangePeriodFromISR()
 972  * causes the timer service/daemon task to leave the Blocked state, and the
 973  * timer service/daemon task has a priority equal to or greater than the
 974  * currently executing task (the task that was interrupted), then
 975  * *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the
 976  * xTimerChangePeriodFromISR() function.  If xTimerChangePeriodFromISR() sets
 977  * this value to pdTRUE then a context switch should be performed before the
 978  * interrupt exits.
 979  *
 980  * @return pdFAIL will be returned if the command to change the timers period
 981  * could not be sent to the timer command queue.  pdPASS will be returned if the
 982  * command was successfully sent to the timer command queue.  When the command
 983  * is actually processed will depend on the priority of the timer service/daemon
 984  * task relative to other tasks in the system.  The timer service/daemon task
 985  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
 986  *
 987  * Example usage:
 988  * @verbatim
 989  * // This scenario assumes xTimer has already been created and started.  When
 990  * // an interrupt occurs, the period of xTimer should be changed to 500ms.
 991  *
 992  * // The interrupt service routine that changes the period of xTimer.
 993  * void vAnExampleInterruptServiceRoutine( void )
 994  * {
 995  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
 996  *
 997  *     // The interrupt has occurred - change the period of xTimer to 500ms.
 998  *     // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
 999  *     // (within this function).  As this is an interrupt service routine, only
1000  *     // FreeRTOS API functions that end in "FromISR" can be used.
1001  *     if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
1002  *     {
1003  *         // The command to change the timers period was not executed
1004  *         // successfully.  Take appropriate action here.
1005  *     }
1006  *
1007  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
1008  *     // should be performed.  The syntax required to perform a context switch
1009  *     // from inside an ISR varies from port to port, and from compiler to
1010  *     // compiler.  Inspect the demos for the port you are using to find the
1011  *     // actual syntax required.
1012  *     if( xHigherPriorityTaskWoken != pdFALSE )
1013  *     {
1014  *         // Call the interrupt safe yield function here (actual function
1015  *         // depends on the FreeRTOS port being used).
1016  *     }
1017  * }
1018  * @endverbatim
1019  */
1020 #define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken ) \
1021     xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )
1022
1023 /**
1024  * BaseType_t xTimerResetFromISR(   TimerHandle_t xTimer,
1025  *                                  BaseType_t *pxHigherPriorityTaskWoken );
1026  *
1027  * A version of xTimerReset() that can be called from an interrupt service
1028  * routine.
1029  *
1030  * @param xTimer The handle of the timer that is to be started, reset, or
1031  * restarted.
1032  *
1033  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
1034  * of its time in the Blocked state, waiting for messages to arrive on the timer
1035  * command queue.  Calling xTimerResetFromISR() writes a message to the timer
1036  * command queue, so has the potential to transition the timer service/daemon
1037  * task out of the Blocked state.  If calling xTimerResetFromISR() causes the
1038  * timer service/daemon task to leave the Blocked state, and the timer service/
1039  * daemon task has a priority equal to or greater than the currently executing
1040  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
1041  * get set to pdTRUE internally within the xTimerResetFromISR() function.  If
1042  * xTimerResetFromISR() sets this value to pdTRUE then a context switch should
1043  * be performed before the interrupt exits.
1044  *
1045  * @return pdFAIL will be returned if the reset command could not be sent to
1046  * the timer command queue.  pdPASS will be returned if the command was
1047  * successfully sent to the timer command queue.  When the command is actually
1048  * processed will depend on the priority of the timer service/daemon task
1049  * relative to other tasks in the system, although the timers expiry time is
1050  * relative to when xTimerResetFromISR() is actually called.  The timer service/daemon
1051  * task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
1052  *
1053  * Example usage:
1054  * @verbatim
1055  * // This scenario assumes xBacklightTimer has already been created.  When a
1056  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass
1057  * // without a key being pressed, then the LCD back-light is switched off.  In
1058  * // this case, the timer is a one-shot timer, and unlike the example given for
1059  * // the xTimerReset() function, the key press event handler is an interrupt
1060  * // service routine.
1061  *
1062  * // The callback function assigned to the one-shot timer.  In this case the
1063  * // parameter is not used.
1064  * void vBacklightTimerCallback( TimerHandle_t pxTimer )
1065  * {
1066  *     // The timer expired, therefore 5 seconds must have passed since a key
1067  *     // was pressed.  Switch off the LCD back-light.
1068  *     vSetBacklightState( BACKLIGHT_OFF );
1069  * }
1070  *
1071  * // The key press interrupt service routine.
1072  * void vKeyPressEventInterruptHandler( void )
1073  * {
1074  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
1075  *
1076  *     // Ensure the LCD back-light is on, then reset the timer that is
1077  *     // responsible for turning the back-light off after 5 seconds of
1078  *     // key inactivity.  This is an interrupt service routine so can only
1079  *     // call FreeRTOS API functions that end in "FromISR".
1080  *     vSetBacklightState( BACKLIGHT_ON );
1081  *
1082  *     // xTimerStartFromISR() or xTimerResetFromISR() could be called here
1083  *     // as both cause the timer to re-calculate its expiry time.
1084  *     // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
1085  *     // declared (in this function).
1086  *     if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )
1087  *     {
1088  *         // The reset command was not executed successfully.  Take appropriate
1089  *         // action here.
1090  *     }
1091  *
1092  *     // Perform the rest of the key processing here.
1093  *
1094  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
1095  *     // should be performed.  The syntax required to perform a context switch
1096  *     // from inside an ISR varies from port to port, and from compiler to
1097  *     // compiler.  Inspect the demos for the port you are using to find the
1098  *     // actual syntax required.
1099  *     if( xHigherPriorityTaskWoken != pdFALSE )
1100  *     {
1101  *         // Call the interrupt safe yield function here (actual function
1102  *         // depends on the FreeRTOS port being used).
1103  *     }
1104  * }
1105  * @endverbatim
1106  */
1107 #define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken ) \
1108     xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
1109
1110
1111 /**
1112  * BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,
1113  *                                          void *pvParameter1,
1114  *                                          uint32_t ulParameter2,
1115  *                                          BaseType_t *pxHigherPriorityTaskWoken );
1116  *
1117  *
1118  * Used from application interrupt service routines to defer the execution of a
1119  * function to the RTOS daemon task (the timer service task, hence this function
1120  * is implemented in timers.c and is prefixed with 'Timer').
1121  *
1122  * Ideally an interrupt service routine (ISR) is kept as short as possible, but
1123  * sometimes an ISR either has a lot of processing to do, or needs to perform
1124  * processing that is not deterministic.  In these cases
1125  * xTimerPendFunctionCallFromISR() can be used to defer processing of a function
1126  * to the RTOS daemon task.
1127  *
1128  * A mechanism is provided that allows the interrupt to return directly to the
1129  * task that will subsequently execute the pended callback function.  This
1130  * allows the callback function to execute contiguously in time with the
1131  * interrupt - just as if the callback had executed in the interrupt itself.
1132  *
1133  * @param xFunctionToPend The function to execute from the timer service/
1134  * daemon task.  The function must conform to the PendedFunction_t
1135  * prototype.
1136  *
1137  * @param pvParameter1 The value of the callback function's first parameter.
1138  * The parameter has a void * type to allow it to be used to pass any type.
1139  * For example, unsigned longs can be cast to a void *, or the void * can be
1140  * used to point to a structure.
1141  *
1142  * @param ulParameter2 The value of the callback function's second parameter.
1143  *
1144  * @param pxHigherPriorityTaskWoken As mentioned above, calling this function
1145  * will result in a message being sent to the timer daemon task.  If the
1146  * priority of the timer daemon task (which is set using
1147  * configTIMER_TASK_PRIORITY in FreeRTOSConfig.h) is higher than the priority of
1148  * the currently running task (the task the interrupt interrupted) then
1149  * *pxHigherPriorityTaskWoken will be set to pdTRUE within
1150  * xTimerPendFunctionCallFromISR(), indicating that a context switch should be
1151  * requested before the interrupt exits.  For that reason
1152  * *pxHigherPriorityTaskWoken must be initialised to pdFALSE.  See the
1153  * example code below.
1154  *
1155  * @return pdPASS is returned if the message was successfully sent to the
1156  * timer daemon task, otherwise pdFALSE is returned.
1157  *
1158  * Example usage:
1159  * @verbatim
1160  *
1161  *  // The callback function that will execute in the context of the daemon task.
1162  *  // Note callback functions must all use this same prototype.
1163  *  void vProcessInterface( void *pvParameter1, uint32_t ulParameter2 )
1164  *  {
1165  *      BaseType_t xInterfaceToService;
1166  *
1167  *      // The interface that requires servicing is passed in the second
1168  *      // parameter.  The first parameter is not used in this case.
1169  *      xInterfaceToService = ( BaseType_t ) ulParameter2;
1170  *
1171  *      // ...Perform the processing here...
1172  *  }
1173  *
1174  *  // An ISR that receives data packets from multiple interfaces
1175  *  void vAnISR( void )
1176  *  {
1177  *      BaseType_t xInterfaceToService, xHigherPriorityTaskWoken;
1178  *
1179  *      // Query the hardware to determine which interface needs processing.
1180  *      xInterfaceToService = prvCheckInterfaces();
1181  *
1182  *      // The actual processing is to be deferred to a task.  Request the
1183  *      // vProcessInterface() callback function is executed, passing in the
1184  *      // number of the interface that needs processing.  The interface to
1185  *      // service is passed in the second parameter.  The first parameter is
1186  *      // not used in this case.
1187  *      xHigherPriorityTaskWoken = pdFALSE;
1188  *      xTimerPendFunctionCallFromISR( vProcessInterface, NULL, ( uint32_t ) xInterfaceToService, &xHigherPriorityTaskWoken );
1189  *
1190  *      // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
1191  *      // switch should be requested.  The macro used is port specific and will
1192  *      // be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to
1193  *      // the documentation page for the port being used.
1194  *      portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
1195  *
1196  *  }
1197  * @endverbatim
1198  */
1199 #if ( INCLUDE_xTimerPendFunctionCall == 1 )
1200     BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,
1201                                               void * pvParameter1,
1202                                               uint32_t ulParameter2,
1203                                               BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
1204 #endif
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 #if ( INCLUDE_xTimerPendFunctionCall == 1 )
1239     BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,
1240                                        void * pvParameter1,
1241                                        uint32_t ulParameter2,
1242                                        TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
1243 #endif
1244
1245 /**
1246  * const char * const pcTimerGetName( TimerHandle_t xTimer );
1247  *
1248  * Returns the name that was assigned to a timer when the timer was created.
1249  *
1250  * @param xTimer The handle of the timer being queried.
1251  *
1252  * @return The name assigned to the timer specified by the xTimer parameter.
1253  */
1254 const char * pcTimerGetName( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
1255
1256 /**
1257  * void vTimerSetReloadMode( TimerHandle_t xTimer, const BaseType_t xAutoReload );
1258  *
1259  * Updates a timer to be either an auto-reload timer, in which case the timer
1260  * automatically resets itself each time it expires, or a one-shot timer, in
1261  * which case the timer will only expire once unless it is manually restarted.
1262  *
1263  * @param xTimer The handle of the timer being updated.
1264  *
1265  * @param xAutoReload If xAutoReload is set to pdTRUE then the timer will
1266  * expire repeatedly with a frequency set by the timer's period (see the
1267  * xTimerPeriodInTicks parameter of the xTimerCreate() API function).  If
1268  * xAutoReload is set to pdFALSE then the timer will be a one-shot timer and
1269  * enter the dormant state after it expires.
1270  */
1271 void vTimerSetReloadMode( TimerHandle_t xTimer,
1272                           const BaseType_t xAutoReload ) PRIVILEGED_FUNCTION;
1273
1274 /**
1275  * BaseType_t xTimerGetReloadMode( TimerHandle_t xTimer );
1276  *
1277  * Queries a timer to determine if it is an auto-reload timer, in which case the timer
1278  * automatically resets itself each time it expires, or a one-shot timer, in
1279  * which case the timer will only expire once unless it is manually restarted.
1280  *
1281  * @param xTimer The handle of the timer being queried.
1282  *
1283  * @return If the timer is an auto-reload timer then pdTRUE is returned, otherwise
1284  * pdFALSE is returned.
1285  */
1286 BaseType_t xTimerGetReloadMode( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
1287
1288 /**
1289  * UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer );
1290  *
1291  * Queries a timer to determine if it is an auto-reload timer, in which case the timer
1292  * automatically resets itself each time it expires, or a one-shot timer, in
1293  * which case the timer will only expire once unless it is manually restarted.
1294  *
1295  * @param xTimer The handle of the timer being queried.
1296  *
1297  * @return If the timer is an auto-reload timer then pdTRUE is returned, otherwise
1298  * pdFALSE is returned.
1299  */
1300 UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
1301
1302 /**
1303  * TickType_t xTimerGetPeriod( TimerHandle_t xTimer );
1304  *
1305  * Returns the period of a timer.
1306  *
1307  * @param xTimer The handle of the timer being queried.
1308  *
1309  * @return The period of the timer in ticks.
1310  */
1311 TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
1312
1313 /**
1314  * TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );
1315  *
1316  * Returns the time in ticks at which the timer will expire.  If this is less
1317  * than the current tick count then the expiry time has overflowed from the
1318  * current time.
1319  *
1320  * @param xTimer The handle of the timer being queried.
1321  *
1322  * @return If the timer is running then the time in ticks at which the timer
1323  * will next expire is returned.  If the timer is not running then the return
1324  * value is undefined.
1325  */
1326 TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
1327
1328 /**
1329  * BaseType_t xTimerGetStaticBuffer( TimerHandle_t xTimer,
1330  *                                   StaticTimer_t ** ppxTimerBuffer );
1331  *
1332  * Retrieve pointer to a statically created timer's data structure
1333  * buffer. This is the same buffer that is supplied at the time of
1334  * creation.
1335  *
1336  * @param xTimer The timer for which to retrieve the buffer.
1337  *
1338  * @param ppxTaskBuffer Used to return a pointer to the timers's data
1339  * structure buffer.
1340  *
1341  * @return pdTRUE if the buffer was retrieved, pdFALSE otherwise.
1342  */
1343 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
1344     BaseType_t xTimerGetStaticBuffer( TimerHandle_t xTimer,
1345                                       StaticTimer_t ** ppxTimerBuffer ) PRIVILEGED_FUNCTION;
1346 #endif /* configSUPPORT_STATIC_ALLOCATION */
1347
1348 /*
1349  * Functions beyond this part are not part of the public API and are intended
1350  * for use by the kernel only.
1351  */
1352 BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;
1353
1354 /*
1355  * Splitting the xTimerGenericCommand into two sub functions and making it a macro
1356  * removes a recursion path when called from ISRs. This is primarily for the XCore
1357  * XCC port which detects the recursion path and throws an error during compilation
1358  * when this is not split.
1359  */
1360 BaseType_t xTimerGenericCommandFromTask( TimerHandle_t xTimer,
1361                                          const BaseType_t xCommandID,
1362                                          const TickType_t xOptionalValue,
1363                                          BaseType_t * const pxHigherPriorityTaskWoken,
1364                                          const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
1365
1366 BaseType_t xTimerGenericCommandFromISR( TimerHandle_t xTimer,
1367                                         const BaseType_t xCommandID,
1368                                         const TickType_t xOptionalValue,
1369                                         BaseType_t * const pxHigherPriorityTaskWoken,
1370                                         const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
1371
1372 #define xTimerGenericCommand( xTimer, xCommandID, xOptionalValue, pxHigherPriorityTaskWoken, xTicksToWait )         \
1373     ( ( xCommandID ) < tmrFIRST_FROM_ISR_COMMAND ?                                                                  \
1374       xTimerGenericCommandFromTask( xTimer, xCommandID, xOptionalValue, pxHigherPriorityTaskWoken, xTicksToWait ) : \
1375       xTimerGenericCommandFromISR( xTimer, xCommandID, xOptionalValue, pxHigherPriorityTaskWoken, xTicksToWait ) )
1376 #if ( configUSE_TRACE_FACILITY == 1 )
1377     void vTimerSetTimerNumber( TimerHandle_t xTimer,
1378                                UBaseType_t uxTimerNumber ) PRIVILEGED_FUNCTION;
1379     UBaseType_t uxTimerGetTimerNumber( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
1380 #endif
1381
1382 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
1383
1384 /**
1385  * task.h
1386  * @code{c}
1387  * void vApplicationGetTimerTaskMemory( StaticTask_t ** ppxTimerTaskTCBBuffer, StackType_t ** ppxTimerTaskStackBuffer, configSTACK_DEPTH_TYPE * puxTimerTaskStackSize )
1388  * @endcode
1389  *
1390  * 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
1391  * configSUPPORT_STATIC_ALLOCATION is set.  For more information see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION
1392  *
1393  * @param ppxTimerTaskTCBBuffer   A handle to a statically allocated TCB buffer
1394  * @param ppxTimerTaskStackBuffer A handle to a statically allocated Stack buffer for the idle task
1395  * @param puxTimerTaskStackSize   A pointer to the number of elements that will fit in the allocated stack buffer
1396  */
1397     void vApplicationGetTimerTaskMemory( StaticTask_t ** ppxTimerTaskTCBBuffer,
1398                                          StackType_t ** ppxTimerTaskStackBuffer,
1399                                          configSTACK_DEPTH_TYPE * puxTimerTaskStackSize );
1400
1401 #endif
1402
1403 #if ( configUSE_DAEMON_TASK_STARTUP_HOOK != 0 )
1404
1405 /**
1406  *  timers.h
1407  * @code{c}
1408  * void vApplicationDaemonTaskStartupHook( void );
1409  * @endcode
1410  *
1411  * This hook function is called form the timer task once when the task starts running.
1412  */
1413     /* MISRA Ref 8.6.1 [External linkage] */
1414     /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-86 */
1415     /* coverity[misra_c_2012_rule_8_6_violation] */
1416     void vApplicationDaemonTaskStartupHook( void );
1417
1418 #endif
1419
1420 /*
1421  * This function resets the internal state of the timer module. It must be called
1422  * by the application before restarting the scheduler.
1423  */
1424 void vTimerResetState( void ) PRIVILEGED_FUNCTION;
1425
1426 /* *INDENT-OFF* */
1427 #ifdef __cplusplus
1428     }
1429 #endif
1430 /* *INDENT-ON* */
1431 #endif /* TIMERS_H */