os/7.4.2/include/os/timers.h

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