os/7.0.2/include/os/timers.h

   1 /*
   2     FreeRTOS V7.0.2 - Copyright (C) 2011 Real Time Engineers Ltd.
   3
   4
   5     ***************************************************************************
   6      *                                                                       *
   7      *    FreeRTOS tutorial books are available in pdf and paperback.        *
   8      *    Complete, revised, and edited pdf reference manuals are also       *
   9      *    available.                                                         *
  10      *                                                                       *
  11      *    Purchasing FreeRTOS documentation will not only help you, by       *
  12      *    ensuring you get running as quickly as possible and with an        *
  13      *    in-depth knowledge of how to use FreeRTOS, it will also help       *
  14      *    the FreeRTOS project to continue with its mission of providing     *
  15      *    professional grade, cross platform, de facto standard solutions    *
  16      *    for microcontrollers - completely free of charge!                  *
  17      *                                                                       *
  18      *    >>> See http://www.FreeRTOS.org/Documentation for details. <<<     *
  19      *                                                                       *
  20      *    Thank you for using FreeRTOS, and thank you for your support!      *
  21      *                                                                       *
  22     ***************************************************************************
  23
  24
  25     This file is part of the FreeRTOS distribution.
  26
  27     FreeRTOS is free software; you can redistribute it and/or modify it under
  28     the terms of the GNU General Public License (version 2) as published by the
  29     Free Software Foundation AND MODIFIED BY the FreeRTOS exception.
  30     >>>NOTE<<< The modification to the GPL is included to allow you to
  31     distribute a combined work that includes FreeRTOS without being obliged to
  32     provide the source code for proprietary components outside of the FreeRTOS
  33     kernel.  FreeRTOS is distributed in the hope that it will be useful, but
  34     WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  35     or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  36     more details. You should have received a copy of the GNU General Public
  37     License and the FreeRTOS license exception along with FreeRTOS; if not it
  38     can be viewed here: http://www.freertos.org/a00114.html and also obtained
  39     by writing to Richard Barry, contact details for whom are available on the
  40     FreeRTOS WEB site.
  41
  42     1 tab == 4 spaces!
  43
  44     http://www.FreeRTOS.org - Documentation, latest information, license and
  45     contact details.
  46
  47     http://www.SafeRTOS.com - A version that is certified for use in safety
  48     critical systems.
  49
  50     http://www.OpenRTOS.com - Commercial support, development, porting,
  51     licensing and training services.
  52 */
  53
  54
  55 #ifndef TIMERS_H
  56 #define TIMERS_H
  57
  58 #ifndef INC_FREERTOS_H
  59     #error "include FreeRTOS.h must appear in source files before include timers.h"
  60 #endif
  61
  62 #include "os/portable.h"
  63 #include "os/list.h"
  64 #include "os/task.h"
  65
  66 #ifdef __cplusplus
  67 extern "C" {
  68 #endif
  69
  70 /* IDs for commands that can be sent/received on the timer queue.  These are to
  71 be used solely through the macros that make up the public software timer API,
  72 as defined below. */
  73 #define tmrCOMMAND_START                    0
  74 #define tmrCOMMAND_STOP                     1
  75 #define tmrCOMMAND_CHANGE_PERIOD            2
  76 #define tmrCOMMAND_DELETE                   3
  77
  78 /*-----------------------------------------------------------
  79  * MACROS AND DEFINITIONS
  80  *----------------------------------------------------------*/
  81
  82  /**
  83  * Type by which software timers are referenced.  For example, a call to
  84  * xTimerCreate() returns an xTimerHandle variable that can then be used to
  85  * reference the subject timer in calls to other software timer API functions
  86  * (for example, xTimerStart(), xTimerReset(), etc.).
  87  */
  88 typedef void * xTimerHandle;
  89
  90 /* Define the prototype to which timer callback functions must conform. */
  91 typedef void (*tmrTIMER_CALLBACK)( xTimerHandle xTimer );
  92
  93 /**
  94  * xTimerHandle xTimerCreate(   const signed char *pcTimerName,
  95  *                              portTickType xTimerPeriodInTicks,
  96  *                              unsigned portBASE_TYPE uxAutoReload,
  97  *                              void * pvTimerID,
  98  *                              tmrTIMER_CALLBACK pxCallbackFunction );
  99  *
 100  * Creates a new software timer instance.  This allocates the storage required
 101  * by the new timer, initialises the new timers internal state, and returns a
 102  * handle by which the new timer can be referenced.
 103  *
 104  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),
 105  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and
 106  * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the
 107  * active state.
 108  *
 109  * @param pcTimerName A text name that is assigned to the timer.  This is done
 110  * purely to assist debugging.  The kernel itself only ever references a timer by
 111  * its handle, and never by its name.
 112  *
 113  * @param xTimerPeriodInTicks The timer period.  The time is defined in tick periods so
 114  * the constant portTICK_RATE_MS can be used to convert a time that has been
 115  * specified in milliseconds.  For example, if the timer must expire after 100
 116  * ticks, then xTimerPeriodInTicks should be set to 100.  Alternatively, if the timer
 117  * must expire after 500ms, then xPeriod can be set to ( 500 / portTICK_RATE_MS )
 118  * provided configTICK_RATE_HZ is less than or equal to 1000.
 119  *
 120  * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will
 121  * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter.  If
 122  * uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and
 123  * enter the dormant state after it expires.
 124  *
 125  * @param pvTimerID An identifier that is assigned to the timer being created.
 126  * Typically this would be used in the timer callback function to identify which
 127  * timer expired when the same callback function is assigned to more than one
 128  * timer.
 129  *
 130  * @param pxCallbackFunction The function to call when the timer expires.
 131  * Callback functions must have the prototype defined by tmrTIMER_CALLBACK,
 132  * which is "void vCallbackFunction( xTimerHandle xTimer );".
 133  *
 134  * @return If the timer is successfully create then a handle to the newly
 135  * created timer is returned.  If the timer cannot be created (because either
 136  * there is insufficient FreeRTOS heap remaining to allocate the timer
 137  * structures, or the timer period was set to 0) then 0 is returned.
 138  *
 139  * Example usage:
 140  *
 141  *
 142  * define NUM_TIMERS 5
 143  *
 144  * // An array to hold handles to the created timers.
 145  * xTimerHandle xTimers[ NUM_TIMERS ];
 146  *
 147  * // An array to hold a count of the number of times each timer expires.
 148  * long lExpireCounters[ NUM_TIMERS ] = { 0 };
 149  *
 150  * // Define a callback function that will be used by multiple timer instances.
 151  * // The callback function does nothing but count the number of times the
 152  * // associated timer expires, and stop the timer once the timer has expired
 153  * // 10 times.
 154  * void vTimerCallback( xTimerHandle pxTimer )
 155  * {
 156  * long lArrayIndex;
 157  * const long xMaxExpiryCountBeforeStopping = 10;
 158  *
 159  *     // Optionally do something if the pxTimer parameter is NULL.
 160  *     configASSERT( pxTimer );
 161  *
 162  *     // Which timer expired?
 163  *     lArrayIndex = ( long ) pvTimerGetTimerID( pxTimer );
 164  *
 165  *     // Increment the number of times that pxTimer has expired.
 166  *     lExpireCounters[ lArrayIndex ] += 1;
 167  *
 168  *     // If the timer has expired 10 times then stop it from running.
 169  *     if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping )
 170  *     {
 171  *         // Do not use a block time if calling a timer API function from a
 172  *         // timer callback function, as doing so could cause a deadlock!
 173  *         xTimerStop( pxTimer, 0 );
 174  *     }
 175  * }
 176  *
 177  * void main( void )
 178  * {
 179  * long x;
 180  *
 181  *     // Create then start some timers.  Starting the timers before the scheduler
 182  *     // has been started means the timers will start running immediately that
 183  *     // the scheduler starts.
 184  *     for( x = 0; x < NUM_TIMERS; x++ )
 185  *     {
 186  *         xTimers[ x ] = xTimerCreate(     "Timer",         // Just a text name, not used by the kernel.
 187  *                                         ( 100 * x ),     // The timer period in ticks.
 188  *                                         pdTRUE,         // The timers will auto-reload themselves when they expire.
 189  *                                         ( void * ) x,     // Assign each timer a unique id equal to its array index.
 190  *                                         vTimerCallback     // Each timer calls the same callback when it expires.
 191  *                                     );
 192  *
 193  *         if( xTimers[ x ] == NULL )
 194  *         {
 195  *             // The timer was not created.
 196  *         }
 197  *         else
 198  *         {
 199  *             // Start the timer.  No block time is specified, and even if one was
 200  *             // it would be ignored because the scheduler has not yet been
 201  *             // started.
 202  *             if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )
 203  *             {
 204  *                 // The timer could not be set into the Active state.
 205  *             }
 206  *         }
 207  *     }
 208  *
 209  *     // ...
 210  *     // Create tasks here.
 211  *     // ...
 212  *
 213  *     // Starting the scheduler will start the timers running as they have already
 214  *     // been set into the active state.
 215  *     xTaskStartScheduler();
 216  *
 217  *     // Should not reach here.
 218  *     for( ;; );
 219  * }
 220  */
 221 xTimerHandle xTimerCreate( const signed char *pcTimerName, portTickType xTimerPeriodInTicks, unsigned portBASE_TYPE uxAutoReload, void * pvTimerID, tmrTIMER_CALLBACK pxCallbackFunction ) PRIVILEGED_FUNCTION;
 222
 223 /**
 224  * void *pvTimerGetTimerID( xTimerHandle xTimer );
 225  *
 226  * Returns the ID assigned to the timer.
 227  *
 228  * IDs are assigned to timers using the pvTimerID parameter of the call to
 229  * xTimerCreated() that was used to create the timer.
 230  *
 231  * If the same callback function is assigned to multiple timers then the timer
 232  * ID can be used within the callback function to identify which timer actually
 233  * expired.
 234  *
 235  * @param xTimer The timer being queried.
 236  *
 237  * @return The ID assigned to the timer being queried.
 238  *
 239  * Example usage:
 240  *
 241  * See the xTimerCreate() API function example usage scenario.
 242  */
 243 void *pvTimerGetTimerID( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
 244
 245 /**
 246  * portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer );
 247  *
 248  * Queries a timer to see if it is active or dormant.
 249  *
 250  * A timer will be dormant if:
 251  *     1) It has been created but not started, or
 252  *     2) It is an expired on-shot timer that has not been restarted.
 253  *
 254  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),
 255  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and
 256  * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the
 257  * active state.
 258  *
 259  * @param xTimer The timer being queried.
 260  *
 261  * @return pdFALSE will be returned if the timer is dormant.  A value other than
 262  * pdFALSE will be returned if the timer is active.
 263  *
 264  * Example usage:
 265  *
 266  * // This function assumes xTimer has already been created.
 267  * void vAFunction( xTimerHandle xTimer )
 268  * {
 269  *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"
 270  *     {
 271  *         // xTimer is active, do something.
 272  *     }
 273  *     else
 274  *     {
 275  *         // xTimer is not active, do something else.
 276  *     }
 277  * }
 278  */
 279 portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
 280
 281 /**
 282  * xTimerGetTimerDaemonTaskHandle() is only available if
 283  * INCLUDE_xTimerGetTimerDaemonTaskHandle is set to 1 in FreeRTOSConfig.h.
 284  *
 285  * Simply returns the handle of the timer service/daemon task.  It it not valid
 286  * to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started.
 287  */
 288 xTaskHandle xTimerGetTimerDaemonTaskHandle( void );
 289
 290 /**
 291  * portBASE_TYPE xTimerStart( xTimerHandle xTimer, portTickType xBlockTime );
 292  *
 293  * Timer functionality is provided by a timer service/daemon task.  Many of the
 294  * public FreeRTOS timer API functions send commands to the timer service task
 295  * though a queue called the timer command queue.  The timer command queue is
 296  * private to the kernel itself and is not directly accessible to application
 297  * code.  The length of the timer command queue is set by the
 298  * configTIMER_QUEUE_LENGTH configuration constant.
 299  *
 300  * xTimerStart() starts a timer that was previously created using the
 301  * xTimerCreate() API function.  If the timer had already been started and was
 302  * already in the active state, then xTimerStart() has equivalent functionality
 303  * to the xTimerReset() API function.
 304  *
 305  * Starting a timer ensures the timer is in the active state.  If the timer
 306  * is not stopped, deleted, or reset in the mean time, the callback function
 307  * associated with the timer will get called 'n' ticks after xTimerStart() was
 308  * called, where 'n' is the timers defined period.
 309  *
 310  * It is valid to call xTimerStart() before the scheduler has been started, but
 311  * when this is done the timer will not actually start until the scheduler is
 312  * started, and the timers expiry time will be relative to when the scheduler is
 313  * started, not relative to when xTimerStart() was called.
 314  *
 315  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStart()
 316  * to be available.
 317  *
 318  * @param xTimer The handle of the timer being started/restarted.
 319  *
 320  * @param xBlockTime Specifies the time, in ticks, that the calling task should
 321  * be held in the Blocked state to wait for the start command to be successfully
 322  * sent to the timer command queue, should the queue already be full when
 323  * xTimerStart() was called.  xBlockTime is ignored if xTimerStart() is called
 324  * before the scheduler is started.
 325  *
 326  * @return pdFAIL will be returned if the start command could not be sent to
 327  * the timer command queue even after xBlockTime ticks had passed.  pdPASS will
 328  * be returned if the command was successfully sent to the timer command queue.
 329  * When the command is actually processed will depend on the priority of the
 330  * timer service/daemon task relative to other tasks in the system, although the
 331  * timers expiry time is relative to when xTimerStart() is actually called.  The
 332  * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY
 333  * configuration constant.
 334  *
 335  * Example usage:
 336  *
 337  * See the xTimerCreate() API function example usage scenario.
 338  *
 339  */
 340 #define xTimerStart( xTimer, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xBlockTime ) )
 341
 342 /**
 343  * portBASE_TYPE xTimerStop( xTimerHandle xTimer, portTickType xBlockTime );
 344  *
 345  * Timer functionality is provided by a timer service/daemon task.  Many of the
 346  * public FreeRTOS timer API functions send commands to the timer service task
 347  * though a queue called the timer command queue.  The timer command queue is
 348  * private to the kernel itself and is not directly accessible to application
 349  * code.  The length of the timer command queue is set by the
 350  * configTIMER_QUEUE_LENGTH configuration constant.
 351  *
 352  * xTimerStop() stops a timer that was previously started using either of the
 353  * The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(),
 354  * xTimerChangePeriod() or xTimerChangePeriodFromISR() API functions.
 355  *
 356  * Stopping a timer ensures the timer is not in the active state.
 357  *
 358  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop()
 359  * to be available.
 360  *
 361  * @param xTimer The handle of the timer being stopped.
 362  *
 363  * @param xBlockTime Specifies the time, in ticks, that the calling task should
 364  * be held in the Blocked state to wait for the stop command to be successfully
 365  * sent to the timer command queue, should the queue already be full when
 366  * xTimerStop() was called.  xBlockTime is ignored if xTimerStop() is called
 367  * before the scheduler is started.
 368  *
 369  * @return pdFAIL will be returned if the stop command could not be sent to
 370  * the timer command queue even after xBlockTime ticks had passed.  pdPASS will
 371  * be returned if the command was successfully sent to the timer command queue.
 372  * When the command is actually processed will depend on the priority of the
 373  * timer service/daemon task relative to other tasks in the system.  The timer
 374  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
 375  * configuration constant.
 376  *
 377  * Example usage:
 378  *
 379  * See the xTimerCreate() API function example usage scenario.
 380  *
 381  */
 382 #define xTimerStop( xTimer, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xBlockTime ) )
 383
 384 /**
 385  * portBASE_TYPE xTimerChangePeriod(    xTimerHandle xTimer,
 386  *                                      portTickType xNewPeriod,
 387  *                                      portTickType xBlockTime );
 388  *
 389  * Timer functionality is provided by a timer service/daemon task.  Many of the
 390  * public FreeRTOS timer API functions send commands to the timer service task
 391  * though a queue called the timer command queue.  The timer command queue is
 392  * private to the kernel itself and is not directly accessible to application
 393  * code.  The length of the timer command queue is set by the
 394  * configTIMER_QUEUE_LENGTH configuration constant.
 395  *
 396  * xTimerChangePeriod() changes the period of a timer that was previously
 397  * created using the xTimerCreate() API function.
 398  *
 399  * xTimerChangePeriod() can be called to change the period of an active or
 400  * dormant state timer.
 401  *
 402  * The configUSE_TIMERS configuration constant must be set to 1 for
 403  * xTimerChangePeriod() to be available.
 404  *
 405  * @param xTimer The handle of the timer that is having its period changed.
 406  *
 407  * @param xNewPeriod The new period for xTimer. Timer periods are specified in
 408  * tick periods, so the constant portTICK_RATE_MS can be used to convert a time
 409  * that has been specified in milliseconds.  For example, if the timer must
 410  * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively,
 411  * if the timer must expire after 500ms, then xNewPeriod can be set to
 412  * ( 500 / portTICK_RATE_MS ) provided configTICK_RATE_HZ is less than
 413  * or equal to 1000.
 414  *
 415  * @param xBlockTime Specifies the time, in ticks, that the calling task should
 416  * be held in the Blocked state to wait for the change period command to be
 417  * successfully sent to the timer command queue, should the queue already be
 418  * full when xTimerChangePeriod() was called.  xBlockTime is ignored if
 419  * xTimerChangePeriod() is called before the scheduler is started.
 420  *
 421  * @return pdFAIL will be returned if the change period command could not be
 422  * sent to the timer command queue even after xBlockTime ticks had passed.
 423  * pdPASS will be returned if the command was successfully sent to the timer
 424  * command queue.  When the command is actually processed will depend on the
 425  * priority of the timer service/daemon task relative to other tasks in the
 426  * system.  The timer service/daemon task priority is set by the
 427  * configTIMER_TASK_PRIORITY configuration constant.
 428  *
 429  * Example usage:
 430  *
 431  * // This function assumes xTimer has already been created.  If the timer
 432  * // referenced by xTimer is already active when it is called, then the timer
 433  * // is deleted.  If the timer referenced by xTimer is not active when it is
 434  * // called, then the period of the timer is set to 500ms and the timer is
 435  * // started.
 436  * void vAFunction( xTimerHandle xTimer )
 437  * {
 438  *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"
 439  *     {
 440  *         // xTimer is already active - delete it.
 441  *         xTimerDelete( xTimer );
 442  *     }
 443  *     else
 444  *     {
 445  *         // xTimer is not active, change its period to 500ms.  This will also
 446  *         // cause the timer to start.  Block for a maximum of 100 ticks if the
 447  *         // change period command cannot immediately be sent to the timer
 448  *         // command queue.
 449  *         if( xTimerChangePeriod( xTimer, 500 / portTICK_RATE_MS, 100 ) == pdPASS )
 450  *         {
 451  *             // The command was successfully sent.
 452  *         }
 453  *         else
 454  *         {
 455  *             // The command could not be sent, even after waiting for 100 ticks
 456  *             // to pass.  Take appropriate action here.
 457  *         }
 458  *     }
 459  * }
 460  */
 461  #define xTimerChangePeriod( xTimer, xNewPeriod, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xBlockTime ) )
 462
 463 /**
 464  * portBASE_TYPE xTimerDelete( xTimerHandle xTimer, portTickType xBlockTime );
 465  *
 466  * Timer functionality is provided by a timer service/daemon task.  Many of the
 467  * public FreeRTOS timer API functions send commands to the timer service task
 468  * though a queue called the timer command queue.  The timer command queue is
 469  * private to the kernel itself and is not directly accessible to application
 470  * code.  The length of the timer command queue is set by the
 471  * configTIMER_QUEUE_LENGTH configuration constant.
 472  *
 473  * xTimerDelete() deletes a timer that was previously created using the
 474  * xTimerCreate() API function.
 475  *
 476  * The configUSE_TIMERS configuration constant must be set to 1 for
 477  * xTimerDelete() to be available.
 478  *
 479  * @param xTimer The handle of the timer being deleted.
 480  *
 481  * @param xBlockTime Specifies the time, in ticks, that the calling task should
 482  * be held in the Blocked state to wait for the delete command to be
 483  * successfully sent to the timer command queue, should the queue already be
 484  * full when xTimerDelete() was called.  xBlockTime is ignored if xTimerDelete()
 485  * is called before the scheduler is started.
 486  *
 487  * @return pdFAIL will be returned if the delete command could not be sent to
 488  * the timer command queue even after xBlockTime ticks had passed.  pdPASS will
 489  * be returned if the command was successfully sent to the timer command queue.
 490  * When the command is actually processed will depend on the priority of the
 491  * timer service/daemon task relative to other tasks in the system.  The timer
 492  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
 493  * configuration constant.
 494  *
 495  * Example usage:
 496  *
 497  * See the xTimerChangePeriod() API function example usage scenario.
 498  */
 499 #define xTimerDelete( xTimer, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xBlockTime ) )
 500
 501 /**
 502  * portBASE_TYPE xTimerReset( xTimerHandle xTimer, portTickType xBlockTime );
 503  *
 504  * Timer functionality is provided by a timer service/daemon task.  Many of the
 505  * public FreeRTOS timer API functions send commands to the timer service task
 506  * though a queue called the timer command queue.  The timer command queue is
 507  * private to the kernel itself and is not directly accessible to application
 508  * code.  The length of the timer command queue is set by the
 509  * configTIMER_QUEUE_LENGTH configuration constant.
 510  *
 511  * xTimerReset() re-starts a timer that was previously created using the
 512  * xTimerCreate() API function.  If the timer had already been started and was
 513  * already in the active state, then xTimerReset() will cause the timer to
 514  * re-evaluate its expiry time so that it is relative to when xTimerReset() was
 515  * called.  If the timer was in the dormant state then xTimerReset() has
 516  * equivalent functionality to the xTimerStart() API function.
 517  *
 518  * Resetting a timer ensures the timer is in the active state.  If the timer
 519  * is not stopped, deleted, or reset in the mean time, the callback function
 520  * associated with the timer will get called 'n' ticks after xTimerReset() was
 521  * called, where 'n' is the timers defined period.
 522  *
 523  * It is valid to call xTimerReset() before the scheduler has been started, but
 524  * when this is done the timer will not actually start until the scheduler is
 525  * started, and the timers expiry time will be relative to when the scheduler is
 526  * started, not relative to when xTimerReset() was called.
 527  *
 528  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset()
 529  * to be available.
 530  *
 531  * @param xTimer The handle of the timer being reset/started/restarted.
 532  *
 533  * @param xBlockTime Specifies the time, in ticks, that the calling task should
 534  * be held in the Blocked state to wait for the reset command to be successfully
 535  * sent to the timer command queue, should the queue already be full when
 536  * xTimerReset() was called.  xBlockTime is ignored if xTimerReset() is called
 537  * before the scheduler is started.
 538  *
 539  * @return pdFAIL will be returned if the reset command could not be sent to
 540  * the timer command queue even after xBlockTime ticks had passed.  pdPASS will
 541  * be returned if the command was successfully sent to the timer command queue.
 542  * When the command is actually processed will depend on the priority of the
 543  * timer service/daemon task relative to other tasks in the system, although the
 544  * timers expiry time is relative to when xTimerStart() is actually called.  The
 545  * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY
 546  * configuration constant.
 547  *
 548  * Example usage:
 549  *
 550  * // When a key is pressed, an LCD back-light is switched on.  If 5 seconds pass
 551  * // without a key being pressed, then the LCD back-light is switched off.  In
 552  * // this case, the timer is a one-shot timer.
 553  *
 554  * xTimerHandle xBacklightTimer = NULL;
 555  *
 556  * // The callback function assigned to the one-shot timer.  In this case the
 557  * // parameter is not used.
 558  * void vBacklightTimerCallback( xTimerHandle pxTimer )
 559  * {
 560  *     // The timer expired, therefore 5 seconds must have passed since a key
 561  *     // was pressed.  Switch off the LCD back-light.
 562  *     vSetBacklightState( BACKLIGHT_OFF );
 563  * }
 564  *
 565  * // The key press event handler.
 566  * void vKeyPressEventHandler( char cKey )
 567  * {
 568  *     // Ensure the LCD back-light is on, then reset the timer that is
 569  *     // responsible for turning the back-light off after 5 seconds of
 570  *     // key inactivity.  Wait 10 ticks for the command to be successfully sent
 571  *     // if it cannot be sent immediately.
 572  *     vSetBacklightState( BACKLIGHT_ON );
 573  *     if( xTimerReset( xBacklightTimer, 100 ) != pdPASS )
 574  *     {
 575  *         // The reset command was not executed successfully.  Take appropriate
 576  *         // action here.
 577  *     }
 578  *
 579  *     // Perform the rest of the key processing here.
 580  * }
 581  *
 582  * void main( void )
 583  * {
 584  * long x;
 585  *
 586  *     // Create then start the one-shot timer that is responsible for turning
 587  *     // the back-light off if no keys are pressed within a 5 second period.
 588  *     xBacklightTimer = xTimerCreate( "BacklightTimer",           // Just a text name, not used by the kernel.
 589  *                                     ( 5000 / portTICK_RATE_MS), // The timer period in ticks.
 590  *                                     pdFALSE,                    // The timer is a one-shot timer.
 591  *                                     0,                          // The id is not used by the callback so can take any value.
 592  *                                     vBacklightTimerCallback     // The callback function that switches the LCD back-light off.
 593  *                                   );
 594  *
 595  *     if( xBacklightTimer == NULL )
 596  *     {
 597  *         // The timer was not created.
 598  *     }
 599  *     else
 600  *     {
 601  *         // Start the timer.  No block time is specified, and even if one was
 602  *         // it would be ignored because the scheduler has not yet been
 603  *         // started.
 604  *         if( xTimerStart( xBacklightTimer, 0 ) != pdPASS )
 605  *         {
 606  *             // The timer could not be set into the Active state.
 607  *         }
 608  *     }
 609  *
 610  *     // ...
 611  *     // Create tasks here.
 612  *     // ...
 613  *
 614  *     // Starting the scheduler will start the timer running as it has already
 615  *     // been set into the active state.
 616  *     xTaskStartScheduler();
 617  *
 618  *     // Should not reach here.
 619  *     for( ;; );
 620  * }
 621  */
 622 #define xTimerReset( xTimer, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xBlockTime ) )
 623
 624 /**
 625  * portBASE_TYPE xTimerStartFromISR(    xTimerHandle xTimer,
 626  *                                      portBASE_TYPE *pxHigherPriorityTaskWoken );
 627  *
 628  * A version of xTimerStart() that can be called from an interrupt service
 629  * routine.
 630  *
 631  * @param xTimer The handle of the timer being started/restarted.
 632  *
 633  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
 634  * of its time in the Blocked state, waiting for messages to arrive on the timer
 635  * command queue.  Calling xTimerStartFromISR() writes a message to the timer
 636  * command queue, so has the potential to transition the timer service/daemon
 637  * task out of the Blocked state.  If calling xTimerStartFromISR() causes the
 638  * timer service/daemon task to leave the Blocked state, and the timer service/
 639  * daemon task has a priority equal to or greater than the currently executing
 640  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
 641  * get set to pdTRUE internally within the xTimerStartFromISR() function.  If
 642  * xTimerStartFromISR() sets this value to pdTRUE then a context switch should
 643  * be performed before the interrupt exits.
 644  *
 645  * @return pdFAIL will be returned if the start command could not be sent to
 646  * the timer command queue.  pdPASS will be returned if the command was
 647  * successfully sent to the timer command queue.  When the command is actually
 648  * processed will depend on the priority of the timer service/daemon task
 649  * relative to other tasks in the system, although the timers expiry time is
 650  * relative to when xTimerStartFromISR() is actually called.  The timer service/daemon
 651  * task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
 652  *
 653  * Example usage:
 654  *
 655  * // This scenario assumes xBacklightTimer has already been created.  When a
 656  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass
 657  * // without a key being pressed, then the LCD back-light is switched off.  In
 658  * // this case, the timer is a one-shot timer, and unlike the example given for
 659  * // the xTimerReset() function, the key press event handler is an interrupt
 660  * // service routine.
 661  *
 662  * // The callback function assigned to the one-shot timer.  In this case the
 663  * // parameter is not used.
 664  * void vBacklightTimerCallback( xTimerHandle pxTimer )
 665  * {
 666  *     // The timer expired, therefore 5 seconds must have passed since a key
 667  *     // was pressed.  Switch off the LCD back-light.
 668  *     vSetBacklightState( BACKLIGHT_OFF );
 669  * }
 670  *
 671  * // The key press interrupt service routine.
 672  * void vKeyPressEventInterruptHandler( void )
 673  * {
 674  * portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE;
 675  *
 676  *     // Ensure the LCD back-light is on, then restart the timer that is
 677  *     // responsible for turning the back-light off after 5 seconds of
 678  *     // key inactivity.  This is an interrupt service routine so can only
 679  *     // call FreeRTOS API functions that end in "FromISR".
 680  *     vSetBacklightState( BACKLIGHT_ON );
 681  *
 682  *     // xTimerStartFromISR() or xTimerResetFromISR() could be called here
 683  *     // as both cause the timer to re-calculate its expiry time.
 684  *     // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
 685  *     // declared (in this function).
 686  *     if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )
 687  *     {
 688  *         // The start command was not executed successfully.  Take appropriate
 689  *         // action here.
 690  *     }
 691  *
 692  *     // Perform the rest of the key processing here.
 693  *
 694  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
 695  *     // should be performed.  The syntax required to perform a context switch
 696  *     // from inside an ISR varies from port to port, and from compiler to
 697  *     // compiler.  Inspect the demos for the port you are using to find the
 698  *     // actual syntax required.
 699  *     if( xHigherPriorityTaskWoken != pdFALSE )
 700  *     {
 701  *         // Call the interrupt safe yield function here (actual function
 702  *         // depends on the FreeRTOS port being used.
 703  *     }
 704  * }
 705  */
 706 #define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
 707
 708 /**
 709  * portBASE_TYPE xTimerStopFromISR(     xTimerHandle xTimer,
 710  *                                      portBASE_TYPE *pxHigherPriorityTaskWoken );
 711  *
 712  * A version of xTimerStop() that can be called from an interrupt service
 713  * routine.
 714  *
 715  * @param xTimer The handle of the timer being stopped.
 716  *
 717  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
 718  * of its time in the Blocked state, waiting for messages to arrive on the timer
 719  * command queue.  Calling xTimerStopFromISR() writes a message to the timer
 720  * command queue, so has the potential to transition the timer service/daemon
 721  * task out of the Blocked state.  If calling xTimerStopFromISR() causes the
 722  * timer service/daemon task to leave the Blocked state, and the timer service/
 723  * daemon task has a priority equal to or greater than the currently executing
 724  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
 725  * get set to pdTRUE internally within the xTimerStopFromISR() function.  If
 726  * xTimerStopFromISR() sets this value to pdTRUE then a context switch should
 727  * be performed before the interrupt exits.
 728  *
 729  * @return pdFAIL will be returned if the stop command could not be sent to
 730  * the timer command queue.  pdPASS will be returned if the command was
 731  * successfully sent to the timer command queue.  When the command is actually
 732  * processed will depend on the priority of the timer service/daemon task
 733  * relative to other tasks in the system.  The timer service/daemon task
 734  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
 735  *
 736  * Example usage:
 737  *
 738  * // This scenario assumes xTimer has already been created and started.  When
 739  * // an interrupt occurs, the timer should be simply stopped.
 740  *
 741  * // The interrupt service routine that stops the timer.
 742  * void vAnExampleInterruptServiceRoutine( void )
 743  * {
 744  * portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE;
 745  *
 746  *     // The interrupt has occurred - simply stop the timer.
 747  *     // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
 748  *     // (within this function).  As this is an interrupt service routine, only
 749  *     // FreeRTOS API functions that end in "FromISR" can be used.
 750  *     if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
 751  *     {
 752  *         // The stop command was not executed successfully.  Take appropriate
 753  *         // action here.
 754  *     }
 755  *
 756  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
 757  *     // should be performed.  The syntax required to perform a context switch
 758  *     // from inside an ISR varies from port to port, and from compiler to
 759  *     // compiler.  Inspect the demos for the port you are using to find the
 760  *     // actual syntax required.
 761  *     if( xHigherPriorityTaskWoken != pdFALSE )
 762  *     {
 763  *         // Call the interrupt safe yield function here (actual function
 764  *         // depends on the FreeRTOS port being used.
 765  *     }
 766  * }
 767  */
 768 #define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0, ( pxHigherPriorityTaskWoken ), 0U )
 769
 770 /**
 771  * portBASE_TYPE xTimerChangePeriodFromISR( xTimerHandle xTimer,
 772  *                                          portTickType xNewPeriod,
 773  *                                          portBASE_TYPE *pxHigherPriorityTaskWoken );
 774  *
 775  * A version of xTimerChangePeriod() that can be called from an interrupt
 776  * service routine.
 777  *
 778  * @param xTimer The handle of the timer that is having its period changed.
 779  *
 780  * @param xNewPeriod The new period for xTimer. Timer periods are specified in
 781  * tick periods, so the constant portTICK_RATE_MS can be used to convert a time
 782  * that has been specified in milliseconds.  For example, if the timer must
 783  * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively,
 784  * if the timer must expire after 500ms, then xNewPeriod can be set to
 785  * ( 500 / portTICK_RATE_MS ) provided configTICK_RATE_HZ is less than
 786  * or equal to 1000.
 787  *
 788  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
 789  * of its time in the Blocked state, waiting for messages to arrive on the timer
 790  * command queue.  Calling xTimerChangePeriodFromISR() writes a message to the
 791  * timer command queue, so has the potential to transition the timer service/
 792  * daemon task out of the Blocked state.  If calling xTimerChangePeriodFromISR()
 793  * causes the timer service/daemon task to leave the Blocked state, and the
 794  * timer service/daemon task has a priority equal to or greater than the
 795  * currently executing task (the task that was interrupted), then
 796  * *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the
 797  * xTimerChangePeriodFromISR() function.  If xTimerChangePeriodFromISR() sets
 798  * this value to pdTRUE then a context switch should be performed before the
 799  * interrupt exits.
 800  *
 801  * @return pdFAIL will be returned if the command to change the timers period
 802  * could not be sent to the timer command queue.  pdPASS will be returned if the
 803  * command was successfully sent to the timer command queue.  When the command
 804  * is actually processed will depend on the priority of the timer service/daemon
 805  * task relative to other tasks in the system.  The timer service/daemon task
 806  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
 807  *
 808  * Example usage:
 809  *
 810  * // This scenario assumes xTimer has already been created and started.  When
 811  * // an interrupt occurs, the period of xTimer should be changed to 500ms.
 812  *
 813  * // The interrupt service routine that changes the period of xTimer.
 814  * void vAnExampleInterruptServiceRoutine( void )
 815  * {
 816  * portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE;
 817  *
 818  *     // The interrupt has occurred - change the period of xTimer to 500ms.
 819  *     // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
 820  *     // (within this function).  As this is an interrupt service routine, only
 821  *     // FreeRTOS API functions that end in "FromISR" can be used.
 822  *     if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
 823  *     {
 824  *         // The command to change the timers period was not executed
 825  *         // successfully.  Take appropriate action here.
 826  *     }
 827  *
 828  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
 829  *     // should be performed.  The syntax required to perform a context switch
 830  *     // from inside an ISR varies from port to port, and from compiler to
 831  *     // compiler.  Inspect the demos for the port you are using to find the
 832  *     // actual syntax required.
 833  *     if( xHigherPriorityTaskWoken != pdFALSE )
 834  *     {
 835  *         // Call the interrupt safe yield function here (actual function
 836  *         // depends on the FreeRTOS port being used.
 837  *     }
 838  * }
 839  */
 840 #define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )
 841
 842 /**
 843  * portBASE_TYPE xTimerResetFromISR(    xTimerHandle xTimer,
 844  *                                      portBASE_TYPE *pxHigherPriorityTaskWoken );
 845  *
 846  * A version of xTimerReset() that can be called from an interrupt service
 847  * routine.
 848  *
 849  * @param xTimer The handle of the timer that is to be started, reset, or
 850  * restarted.
 851  *
 852  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
 853  * of its time in the Blocked state, waiting for messages to arrive on the timer
 854  * command queue.  Calling xTimerResetFromISR() writes a message to the timer
 855  * command queue, so has the potential to transition the timer service/daemon
 856  * task out of the Blocked state.  If calling xTimerResetFromISR() causes the
 857  * timer service/daemon task to leave the Blocked state, and the timer service/
 858  * daemon task has a priority equal to or greater than the currently executing
 859  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
 860  * get set to pdTRUE internally within the xTimerResetFromISR() function.  If
 861  * xTimerResetFromISR() sets this value to pdTRUE then a context switch should
 862  * be performed before the interrupt exits.
 863  *
 864  * @return pdFAIL will be returned if the reset command could not be sent to
 865  * the timer command queue.  pdPASS will be returned if the command was
 866  * successfully sent to the timer command queue.  When the command is actually
 867  * processed will depend on the priority of the timer service/daemon task
 868  * relative to other tasks in the system, although the timers expiry time is
 869  * relative to when xTimerResetFromISR() is actually called.  The timer service/daemon
 870  * task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
 871  *
 872  * Example usage:
 873  *
 874  * // This scenario assumes xBacklightTimer has already been created.  When a
 875  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass
 876  * // without a key being pressed, then the LCD back-light is switched off.  In
 877  * // this case, the timer is a one-shot timer, and unlike the example given for
 878  * // the xTimerReset() function, the key press event handler is an interrupt
 879  * // service routine.
 880  *
 881  * // The callback function assigned to the one-shot timer.  In this case the
 882  * // parameter is not used.
 883  * void vBacklightTimerCallback( xTimerHandle pxTimer )
 884  * {
 885  *     // The timer expired, therefore 5 seconds must have passed since a key
 886  *     // was pressed.  Switch off the LCD back-light.
 887  *     vSetBacklightState( BACKLIGHT_OFF );
 888  * }
 889  *
 890  * // The key press interrupt service routine.
 891  * void vKeyPressEventInterruptHandler( void )
 892  * {
 893  * portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE;
 894  *
 895  *     // Ensure the LCD back-light is on, then reset the timer that is
 896  *     // responsible for turning the back-light off after 5 seconds of
 897  *     // key inactivity.  This is an interrupt service routine so can only
 898  *     // call FreeRTOS API functions that end in "FromISR".
 899  *     vSetBacklightState( BACKLIGHT_ON );
 900  *
 901  *     // xTimerStartFromISR() or xTimerResetFromISR() could be called here
 902  *     // as both cause the timer to re-calculate its expiry time.
 903  *     // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
 904  *     // declared (in this function).
 905  *     if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )
 906  *     {
 907  *         // The reset command was not executed successfully.  Take appropriate
 908  *         // action here.
 909  *     }
 910  *
 911  *     // Perform the rest of the key processing here.
 912  *
 913  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
 914  *     // should be performed.  The syntax required to perform a context switch
 915  *     // from inside an ISR varies from port to port, and from compiler to
 916  *     // compiler.  Inspect the demos for the port you are using to find the
 917  *     // actual syntax required.
 918  *     if( xHigherPriorityTaskWoken != pdFALSE )
 919  *     {
 920  *         // Call the interrupt safe yield function here (actual function
 921  *         // depends on the FreeRTOS port being used.
 922  *     }
 923  * }
 924  */
 925 #define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
 926
 927 /*
 928  * Functions beyond this part are not part of the public API and are intended
 929  * for use by the kernel only.
 930  */
 931 portBASE_TYPE xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;
 932 portBASE_TYPE xTimerGenericCommand( xTimerHandle xTimer, portBASE_TYPE xCommandID, portTickType xOptionalValue, portBASE_TYPE *pxHigherPriorityTaskWoken, portTickType xBlockTime ) PRIVILEGED_FUNCTION;
 933
 934 #ifdef __cplusplus
 935 }
 936 #endif
 937 #endif /* TIMERS_H */
 938
 939
 940