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

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