TI's CC3100 websocket camera demo with Arducam mini ov5642 and freertos. Should work with other M3's. Work in progress test demo.

Dependencies:   mbed

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers timers.h Source File

timers.h

00001 /*
00002     FreeRTOS V8.2.1 - Copyright (C) 2015 Real Time Engineers Ltd.
00003     All rights reserved
00004 
00005     VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
00006 
00007     This file is part of the FreeRTOS distribution.
00008 
00009     FreeRTOS is free software; you can redistribute it and/or modify it under
00010     the terms of the GNU General Public License (version 2) as published by the
00011     Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception.
00012 
00013     ***************************************************************************
00014     >>!   NOTE: The modification to the GPL is included to allow you to     !<<
00015     >>!   distribute a combined work that includes FreeRTOS without being   !<<
00016     >>!   obliged to provide the source code for proprietary components     !<<
00017     >>!   outside of the FreeRTOS kernel.                                   !<<
00018     ***************************************************************************
00019 
00020     FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
00021     WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00022     FOR A PARTICULAR PURPOSE.  Full license text is available on the following
00023     link: http://www.freertos.org/a00114.html
00024 
00025     ***************************************************************************
00026      *                                                                       *
00027      *    FreeRTOS provides completely free yet professionally developed,    *
00028      *    robust, strictly quality controlled, supported, and cross          *
00029      *    platform software that is more than just the market leader, it     *
00030      *    is the industry's de facto standard.                               *
00031      *                                                                       *
00032      *    Help yourself get started quickly while simultaneously helping     *
00033      *    to support the FreeRTOS project by purchasing a FreeRTOS           *
00034      *    tutorial book, reference manual, or both:                          *
00035      *    http://www.FreeRTOS.org/Documentation                              *
00036      *                                                                       *
00037     ***************************************************************************
00038 
00039     http://www.FreeRTOS.org/FAQHelp.html - Having a problem?  Start by reading
00040     the FAQ page "My application does not run, what could be wrong?".  Have you
00041     defined configASSERT()?
00042 
00043     http://www.FreeRTOS.org/support - In return for receiving this top quality
00044     embedded software for free we request you assist our global community by
00045     participating in the support forum.
00046 
00047     http://www.FreeRTOS.org/training - Investing in training allows your team to
00048     be as productive as possible as early as possible.  Now you can receive
00049     FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers
00050     Ltd, and the world's leading authority on the world's leading RTOS.
00051 
00052     http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
00053     including FreeRTOS+Trace - an indispensable productivity tool, a DOS
00054     compatible FAT file system, and our tiny thread aware UDP/IP stack.
00055 
00056     http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.
00057     Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.
00058 
00059     http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High
00060     Integrity Systems ltd. to sell under the OpenRTOS brand.  Low cost OpenRTOS
00061     licenses offer ticketed support, indemnification and commercial middleware.
00062 
00063     http://www.SafeRTOS.com - High Integrity Systems also provide a safety
00064     engineered and independently SIL3 certified version for use in safety and
00065     mission critical applications that require provable dependability.
00066 
00067     1 tab == 4 spaces!
00068 */
00069 
00070 
00071 #ifndef TIMERS_H
00072 #define TIMERS_H
00073 
00074 #ifndef INC_FREERTOS_H
00075     #error "include FreeRTOS.h must appear in source files before include timers.h"
00076 #endif
00077 
00078 /*lint -e537 This headers are only multiply included if the application code
00079 happens to also be including task.h. */
00080 #include "task.h"
00081 /*lint +e537 */
00082 
00083 #ifdef __cplusplus
00084 extern "C" {
00085 #endif
00086 
00087 /*-----------------------------------------------------------
00088  * MACROS AND DEFINITIONS
00089  *----------------------------------------------------------*/
00090 
00091 /* IDs for commands that can be sent/received on the timer queue.  These are to
00092 be used solely through the macros that make up the public software timer API,
00093 as defined below.  The commands that are sent from interrupts must use the
00094 highest numbers as tmrFIRST_FROM_ISR_COMMAND is used to determine if the task
00095 or interrupt version of the queue send function should be used. */
00096 #define tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR    ( ( BaseType_t ) -2 )
00097 #define tmrCOMMAND_EXECUTE_CALLBACK             ( ( BaseType_t ) -1 )
00098 #define tmrCOMMAND_START_DONT_TRACE             ( ( BaseType_t ) 0 )
00099 #define tmrCOMMAND_START                        ( ( BaseType_t ) 1 )
00100 #define tmrCOMMAND_RESET                        ( ( BaseType_t ) 2 )
00101 #define tmrCOMMAND_STOP                         ( ( BaseType_t ) 3 )
00102 #define tmrCOMMAND_CHANGE_PERIOD                ( ( BaseType_t ) 4 )
00103 #define tmrCOMMAND_DELETE                       ( ( BaseType_t ) 5 )
00104 
00105 #define tmrFIRST_FROM_ISR_COMMAND               ( ( BaseType_t ) 6 )
00106 #define tmrCOMMAND_START_FROM_ISR               ( ( BaseType_t ) 6 )
00107 #define tmrCOMMAND_RESET_FROM_ISR               ( ( BaseType_t ) 7 )
00108 #define tmrCOMMAND_STOP_FROM_ISR                ( ( BaseType_t ) 8 )
00109 #define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR       ( ( BaseType_t ) 9 )
00110 
00111 
00112 /**
00113  * Type by which software timers are referenced.  For example, a call to
00114  * xTimerCreate() returns an TimerHandle_t variable that can then be used to
00115  * reference the subject timer in calls to other software timer API functions
00116  * (for example, xTimerStart(), xTimerReset(), etc.).
00117  */
00118 typedef void * TimerHandle_t;
00119 
00120 /*
00121  * Defines the prototype to which timer callback functions must conform.
00122  */
00123 typedef void (*TimerCallbackFunction_t)( TimerHandle_t xTimer );
00124 
00125 /*
00126  * Defines the prototype to which functions used with the
00127  * xTimerPendFunctionCallFromISR() function must conform.
00128  */
00129 typedef void (*PendedFunction_t)( void *, uint32_t );
00130 
00131 /**
00132  * TimerHandle_t xTimerCreate(  const char * const pcTimerName,
00133  *                              TickType_t xTimerPeriodInTicks,
00134  *                              UBaseType_t uxAutoReload,
00135  *                              void * pvTimerID,
00136  *                              TimerCallbackFunction_t pxCallbackFunction );
00137  *
00138  * Creates a new software timer instance.  This allocates the storage required
00139  * by the new timer, initialises the new timers internal state, and returns a
00140  * handle by which the new timer can be referenced.
00141  *
00142  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),
00143  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and
00144  * xTimerChangePeriodFromISR() API functions can all be used to transition a
00145  * timer into the active state.
00146  *
00147  * @param pcTimerName A text name that is assigned to the timer.  This is done
00148  * purely to assist debugging.  The kernel itself only ever references a timer
00149  * by its handle, and never by its name.
00150  *
00151  * @param xTimerPeriodInTicks The timer period.  The time is defined in tick
00152  * periods so the constant portTICK_PERIOD_MS can be used to convert a time that
00153  * has been specified in milliseconds.  For example, if the timer must expire
00154  * after 100 ticks, then xTimerPeriodInTicks should be set to 100.
00155  * Alternatively, if the timer must expire after 500ms, then xPeriod can be set
00156  * to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or
00157  * equal to 1000.
00158  *
00159  * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will
00160  * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter.
00161  * If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and
00162  * enter the dormant state after it expires.
00163  *
00164  * @param pvTimerID An identifier that is assigned to the timer being created.
00165  * Typically this would be used in the timer callback function to identify which
00166  * timer expired when the same callback function is assigned to more than one
00167  * timer.
00168  *
00169  * @param pxCallbackFunction The function to call when the timer expires.
00170  * Callback functions must have the prototype defined by TimerCallbackFunction_t,
00171  * which is "void vCallbackFunction( TimerHandle_t xTimer );".
00172  *
00173  * @return If the timer is successfully created then a handle to the newly
00174  * created timer is returned.  If the timer cannot be created (because either
00175  * there is insufficient FreeRTOS heap remaining to allocate the timer
00176  * structures, or the timer period was set to 0) then NULL is returned.
00177  *
00178  * Example usage:
00179  * @verbatim
00180  * #define NUM_TIMERS 5
00181  *
00182  * // An array to hold handles to the created timers.
00183  * TimerHandle_t xTimers[ NUM_TIMERS ];
00184  *
00185  * // An array to hold a count of the number of times each timer expires.
00186  * int32_t lExpireCounters[ NUM_TIMERS ] = { 0 };
00187  *
00188  * // Define a callback function that will be used by multiple timer instances.
00189  * // The callback function does nothing but count the number of times the
00190  * // associated timer expires, and stop the timer once the timer has expired
00191  * // 10 times.
00192  * void vTimerCallback( TimerHandle_t pxTimer )
00193  * {
00194  * int32_t lArrayIndex;
00195  * const int32_t xMaxExpiryCountBeforeStopping = 10;
00196  *
00197  *     // Optionally do something if the pxTimer parameter is NULL.
00198  *     configASSERT( pxTimer );
00199  *
00200  *     // Which timer expired?
00201  *     lArrayIndex = ( int32_t ) pvTimerGetTimerID( pxTimer );
00202  *
00203  *     // Increment the number of times that pxTimer has expired.
00204  *     lExpireCounters[ lArrayIndex ] += 1;
00205  *
00206  *     // If the timer has expired 10 times then stop it from running.
00207  *     if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping )
00208  *     {
00209  *         // Do not use a block time if calling a timer API function from a
00210  *         // timer callback function, as doing so could cause a deadlock!
00211  *         xTimerStop( pxTimer, 0 );
00212  *     }
00213  * }
00214  *
00215  * void main( void )
00216  * {
00217  * int32_t x;
00218  *
00219  *     // Create then start some timers.  Starting the timers before the scheduler
00220  *     // has been started means the timers will start running immediately that
00221  *     // the scheduler starts.
00222  *     for( x = 0; x < NUM_TIMERS; x++ )
00223  *     {
00224  *         xTimers[ x ] = xTimerCreate(    "Timer",       // Just a text name, not used by the kernel.
00225  *                                         ( 100 * x ),   // The timer period in ticks.
00226  *                                         pdTRUE,        // The timers will auto-reload themselves when they expire.
00227  *                                         ( void * ) x,  // Assign each timer a unique id equal to its array index.
00228  *                                         vTimerCallback // Each timer calls the same callback when it expires.
00229  *                                     );
00230  *
00231  *         if( xTimers[ x ] == NULL )
00232  *         {
00233  *             // The timer was not created.
00234  *         }
00235  *         else
00236  *         {
00237  *             // Start the timer.  No block time is specified, and even if one was
00238  *             // it would be ignored because the scheduler has not yet been
00239  *             // started.
00240  *             if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )
00241  *             {
00242  *                 // The timer could not be set into the Active state.
00243  *             }
00244  *         }
00245  *     }
00246  *
00247  *     // ...
00248  *     // Create tasks here.
00249  *     // ...
00250  *
00251  *     // Starting the scheduler will start the timers running as they have already
00252  *     // been set into the active state.
00253  *     xTaskStartScheduler();
00254  *
00255  *     // Should not reach here.
00256  *     for( ;; );
00257  * }
00258  * @endverbatim
00259  */
00260 TimerHandle_t xTimerCreate( const char * const pcTimerName, const TickType_t xTimerPeriodInTicks, const UBaseType_t uxAutoReload, void * const pvTimerID, TimerCallbackFunction_t pxCallbackFunction ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
00261 
00262 /**
00263  * void *pvTimerGetTimerID( TimerHandle_t xTimer );
00264  *
00265  * Returns the ID assigned to the timer.
00266  *
00267  * IDs are assigned to timers using the pvTimerID parameter of the call to
00268  * xTimerCreated() that was used to create the timer, and by calling the
00269  * vTimerSetTimerID() API function.
00270  *
00271  * If the same callback function is assigned to multiple timers then the timer
00272  * ID can be used as time specific (timer local) storage.
00273  *
00274  * @param xTimer The timer being queried.
00275  *
00276  * @return The ID assigned to the timer being queried.
00277  *
00278  * Example usage:
00279  *
00280  * See the xTimerCreate() API function example usage scenario.
00281  */
00282 void *pvTimerGetTimerID( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
00283 
00284 /**
00285  * void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );
00286  *
00287  * Sets the ID assigned to the timer.
00288  *
00289  * IDs are assigned to timers using the pvTimerID parameter of the call to
00290  * xTimerCreated() that was used to create the timer.
00291  *
00292  * If the same callback function is assigned to multiple timers then the timer
00293  * ID can be used as time specific (timer local) storage.
00294  *
00295  * @param xTimer The timer being updated.
00296  *
00297  * @param pvNewID The ID to assign to the timer.
00298  *
00299  * Example usage:
00300  *
00301  * See the xTimerCreate() API function example usage scenario.
00302  */
00303 void vTimerSetTimerID( const TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION;
00304 
00305 /**
00306  * BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );
00307  *
00308  * Queries a timer to see if it is active or dormant.
00309  *
00310  * A timer will be dormant if:
00311  *     1) It has been created but not started, or
00312  *     2) It is an expired one-shot timer that has not been restarted.
00313  *
00314  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),
00315  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and
00316  * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the
00317  * active state.
00318  *
00319  * @param xTimer The timer being queried.
00320  *
00321  * @return pdFALSE will be returned if the timer is dormant.  A value other than
00322  * pdFALSE will be returned if the timer is active.
00323  *
00324  * Example usage:
00325  * @verbatim
00326  * // This function assumes xTimer has already been created.
00327  * void vAFunction( TimerHandle_t xTimer )
00328  * {
00329  *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"
00330  *     {
00331  *         // xTimer is active, do something.
00332  *     }
00333  *     else
00334  *     {
00335  *         // xTimer is not active, do something else.
00336  *     }
00337  * }
00338  * @endverbatim
00339  */
00340 BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
00341 
00342 /**
00343  * TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
00344  *
00345  * xTimerGetTimerDaemonTaskHandle() is only available if
00346  * INCLUDE_xTimerGetTimerDaemonTaskHandle is set to 1 in FreeRTOSConfig.h.
00347  *
00348  * Simply returns the handle of the timer service/daemon task.  It it not valid
00349  * to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started.
00350  */
00351 TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
00352 
00353 /**
00354  * BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
00355  *
00356  * Timer functionality is provided by a timer service/daemon task.  Many of the
00357  * public FreeRTOS timer API functions send commands to the timer service task
00358  * through a queue called the timer command queue.  The timer command queue is
00359  * private to the kernel itself and is not directly accessible to application
00360  * code.  The length of the timer command queue is set by the
00361  * configTIMER_QUEUE_LENGTH configuration constant.
00362  *
00363  * xTimerStart() starts a timer that was previously created using the
00364  * xTimerCreate() API function.  If the timer had already been started and was
00365  * already in the active state, then xTimerStart() has equivalent functionality
00366  * to the xTimerReset() API function.
00367  *
00368  * Starting a timer ensures the timer is in the active state.  If the timer
00369  * is not stopped, deleted, or reset in the mean time, the callback function
00370  * associated with the timer will get called 'n' ticks after xTimerStart() was
00371  * called, where 'n' is the timers defined period.
00372  *
00373  * It is valid to call xTimerStart() before the scheduler has been started, but
00374  * when this is done the timer will not actually start until the scheduler is
00375  * started, and the timers expiry time will be relative to when the scheduler is
00376  * started, not relative to when xTimerStart() was called.
00377  *
00378  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStart()
00379  * to be available.
00380  *
00381  * @param xTimer The handle of the timer being started/restarted.
00382  *
00383  * @param xTicksToWait Specifies the time, in ticks, that the calling task should
00384  * be held in the Blocked state to wait for the start command to be successfully
00385  * sent to the timer command queue, should the queue already be full when
00386  * xTimerStart() was called.  xTicksToWait is ignored if xTimerStart() is called
00387  * before the scheduler is started.
00388  *
00389  * @return pdFAIL will be returned if the start command could not be sent to
00390  * the timer command queue even after xTicksToWait ticks had passed.  pdPASS will
00391  * be returned if the command was successfully sent to the timer command queue.
00392  * When the command is actually processed will depend on the priority of the
00393  * timer service/daemon task relative to other tasks in the system, although the
00394  * timers expiry time is relative to when xTimerStart() is actually called.  The
00395  * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY
00396  * configuration constant.
00397  *
00398  * Example usage:
00399  *
00400  * See the xTimerCreate() API function example usage scenario.
00401  *
00402  */
00403 #define xTimerStart( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
00404 
00405 /**
00406  * BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );
00407  *
00408  * Timer functionality is provided by a timer service/daemon task.  Many of the
00409  * public FreeRTOS timer API functions send commands to the timer service task
00410  * through a queue called the timer command queue.  The timer command queue is
00411  * private to the kernel itself and is not directly accessible to application
00412  * code.  The length of the timer command queue is set by the
00413  * configTIMER_QUEUE_LENGTH configuration constant.
00414  *
00415  * xTimerStop() stops a timer that was previously started using either of the
00416  * The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(),
00417  * xTimerChangePeriod() or xTimerChangePeriodFromISR() API functions.
00418  *
00419  * Stopping a timer ensures the timer is not in the active state.
00420  *
00421  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop()
00422  * to be available.
00423  *
00424  * @param xTimer The handle of the timer being stopped.
00425  *
00426  * @param xTicksToWait Specifies the time, in ticks, that the calling task should
00427  * be held in the Blocked state to wait for the stop command to be successfully
00428  * sent to the timer command queue, should the queue already be full when
00429  * xTimerStop() was called.  xTicksToWait is ignored if xTimerStop() is called
00430  * before the scheduler is started.
00431  *
00432  * @return pdFAIL will be returned if the stop command could not be sent to
00433  * the timer command queue even after xTicksToWait ticks had passed.  pdPASS will
00434  * be returned if the command was successfully sent to the timer command queue.
00435  * When the command is actually processed will depend on the priority of the
00436  * timer service/daemon task relative to other tasks in the system.  The timer
00437  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
00438  * configuration constant.
00439  *
00440  * Example usage:
00441  *
00442  * See the xTimerCreate() API function example usage scenario.
00443  *
00444  */
00445 #define xTimerStop( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xTicksToWait ) )
00446 
00447 /**
00448  * BaseType_t xTimerChangePeriod(   TimerHandle_t xTimer,
00449  *                                      TickType_t xNewPeriod,
00450  *                                      TickType_t xTicksToWait );
00451  *
00452  * Timer functionality is provided by a timer service/daemon task.  Many of the
00453  * public FreeRTOS timer API functions send commands to the timer service task
00454  * through a queue called the timer command queue.  The timer command queue is
00455  * private to the kernel itself and is not directly accessible to application
00456  * code.  The length of the timer command queue is set by the
00457  * configTIMER_QUEUE_LENGTH configuration constant.
00458  *
00459  * xTimerChangePeriod() changes the period of a timer that was previously
00460  * created using the xTimerCreate() API function.
00461  *
00462  * xTimerChangePeriod() can be called to change the period of an active or
00463  * dormant state timer.
00464  *
00465  * The configUSE_TIMERS configuration constant must be set to 1 for
00466  * xTimerChangePeriod() to be available.
00467  *
00468  * @param xTimer The handle of the timer that is having its period changed.
00469  *
00470  * @param xNewPeriod The new period for xTimer. Timer periods are specified in
00471  * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time
00472  * that has been specified in milliseconds.  For example, if the timer must
00473  * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively,
00474  * if the timer must expire after 500ms, then xNewPeriod can be set to
00475  * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than
00476  * or equal to 1000.
00477  *
00478  * @param xTicksToWait Specifies the time, in ticks, that the calling task should
00479  * be held in the Blocked state to wait for the change period command to be
00480  * successfully sent to the timer command queue, should the queue already be
00481  * full when xTimerChangePeriod() was called.  xTicksToWait is ignored if
00482  * xTimerChangePeriod() is called before the scheduler is started.
00483  *
00484  * @return pdFAIL will be returned if the change period command could not be
00485  * sent to the timer command queue even after xTicksToWait ticks had passed.
00486  * pdPASS will be returned if the command was successfully sent to the timer
00487  * command queue.  When the command is actually processed will depend on the
00488  * priority of the timer service/daemon task relative to other tasks in the
00489  * system.  The timer service/daemon task priority is set by the
00490  * configTIMER_TASK_PRIORITY configuration constant.
00491  *
00492  * Example usage:
00493  * @verbatim
00494  * // This function assumes xTimer has already been created.  If the timer
00495  * // referenced by xTimer is already active when it is called, then the timer
00496  * // is deleted.  If the timer referenced by xTimer is not active when it is
00497  * // called, then the period of the timer is set to 500ms and the timer is
00498  * // started.
00499  * void vAFunction( TimerHandle_t xTimer )
00500  * {
00501  *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"
00502  *     {
00503  *         // xTimer is already active - delete it.
00504  *         xTimerDelete( xTimer );
00505  *     }
00506  *     else
00507  *     {
00508  *         // xTimer is not active, change its period to 500ms.  This will also
00509  *         // cause the timer to start.  Block for a maximum of 100 ticks if the
00510  *         // change period command cannot immediately be sent to the timer
00511  *         // command queue.
00512  *         if( xTimerChangePeriod( xTimer, 500 / portTICK_PERIOD_MS, 100 ) == pdPASS )
00513  *         {
00514  *             // The command was successfully sent.
00515  *         }
00516  *         else
00517  *         {
00518  *             // The command could not be sent, even after waiting for 100 ticks
00519  *             // to pass.  Take appropriate action here.
00520  *         }
00521  *     }
00522  * }
00523  * @endverbatim
00524  */
00525  #define xTimerChangePeriod( xTimer, xNewPeriod, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xTicksToWait ) )
00526 
00527 /**
00528  * BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );
00529  *
00530  * Timer functionality is provided by a timer service/daemon task.  Many of the
00531  * public FreeRTOS timer API functions send commands to the timer service task
00532  * through a queue called the timer command queue.  The timer command queue is
00533  * private to the kernel itself and is not directly accessible to application
00534  * code.  The length of the timer command queue is set by the
00535  * configTIMER_QUEUE_LENGTH configuration constant.
00536  *
00537  * xTimerDelete() deletes a timer that was previously created using the
00538  * xTimerCreate() API function.
00539  *
00540  * The configUSE_TIMERS configuration constant must be set to 1 for
00541  * xTimerDelete() to be available.
00542  *
00543  * @param xTimer The handle of the timer being deleted.
00544  *
00545  * @param xTicksToWait Specifies the time, in ticks, that the calling task should
00546  * be held in the Blocked state to wait for the delete command to be
00547  * successfully sent to the timer command queue, should the queue already be
00548  * full when xTimerDelete() was called.  xTicksToWait is ignored if xTimerDelete()
00549  * is called before the scheduler is started.
00550  *
00551  * @return pdFAIL will be returned if the delete command could not be sent to
00552  * the timer command queue even after xTicksToWait ticks had passed.  pdPASS will
00553  * be returned if the command was successfully sent to the timer command queue.
00554  * When the command is actually processed will depend on the priority of the
00555  * timer service/daemon task relative to other tasks in the system.  The timer
00556  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
00557  * configuration constant.
00558  *
00559  * Example usage:
00560  *
00561  * See the xTimerChangePeriod() API function example usage scenario.
00562  */
00563 #define xTimerDelete( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xTicksToWait ) )
00564 
00565 /**
00566  * BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
00567  *
00568  * Timer functionality is provided by a timer service/daemon task.  Many of the
00569  * public FreeRTOS timer API functions send commands to the timer service task
00570  * through a queue called the timer command queue.  The timer command queue is
00571  * private to the kernel itself and is not directly accessible to application
00572  * code.  The length of the timer command queue is set by the
00573  * configTIMER_QUEUE_LENGTH configuration constant.
00574  *
00575  * xTimerReset() re-starts a timer that was previously created using the
00576  * xTimerCreate() API function.  If the timer had already been started and was
00577  * already in the active state, then xTimerReset() will cause the timer to
00578  * re-evaluate its expiry time so that it is relative to when xTimerReset() was
00579  * called.  If the timer was in the dormant state then xTimerReset() has
00580  * equivalent functionality to the xTimerStart() API function.
00581  *
00582  * Resetting a timer ensures the timer is in the active state.  If the timer
00583  * is not stopped, deleted, or reset in the mean time, the callback function
00584  * associated with the timer will get called 'n' ticks after xTimerReset() was
00585  * called, where 'n' is the timers defined period.
00586  *
00587  * It is valid to call xTimerReset() before the scheduler has been started, but
00588  * when this is done the timer will not actually start until the scheduler is
00589  * started, and the timers expiry time will be relative to when the scheduler is
00590  * started, not relative to when xTimerReset() was called.
00591  *
00592  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset()
00593  * to be available.
00594  *
00595  * @param xTimer The handle of the timer being reset/started/restarted.
00596  *
00597  * @param xTicksToWait Specifies the time, in ticks, that the calling task should
00598  * be held in the Blocked state to wait for the reset command to be successfully
00599  * sent to the timer command queue, should the queue already be full when
00600  * xTimerReset() was called.  xTicksToWait is ignored if xTimerReset() is called
00601  * before the scheduler is started.
00602  *
00603  * @return pdFAIL will be returned if the reset command could not be sent to
00604  * the timer command queue even after xTicksToWait ticks had passed.  pdPASS will
00605  * be returned if the command was successfully sent to the timer command queue.
00606  * When the command is actually processed will depend on the priority of the
00607  * timer service/daemon task relative to other tasks in the system, although the
00608  * timers expiry time is relative to when xTimerStart() is actually called.  The
00609  * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY
00610  * configuration constant.
00611  *
00612  * Example usage:
00613  * @verbatim
00614  * // When a key is pressed, an LCD back-light is switched on.  If 5 seconds pass
00615  * // without a key being pressed, then the LCD back-light is switched off.  In
00616  * // this case, the timer is a one-shot timer.
00617  *
00618  * TimerHandle_t xBacklightTimer = NULL;
00619  *
00620  * // The callback function assigned to the one-shot timer.  In this case the
00621  * // parameter is not used.
00622  * void vBacklightTimerCallback( TimerHandle_t pxTimer )
00623  * {
00624  *     // The timer expired, therefore 5 seconds must have passed since a key
00625  *     // was pressed.  Switch off the LCD back-light.
00626  *     vSetBacklightState( BACKLIGHT_OFF );
00627  * }
00628  *
00629  * // The key press event handler.
00630  * void vKeyPressEventHandler( char cKey )
00631  * {
00632  *     // Ensure the LCD back-light is on, then reset the timer that is
00633  *     // responsible for turning the back-light off after 5 seconds of
00634  *     // key inactivity.  Wait 10 ticks for the command to be successfully sent
00635  *     // if it cannot be sent immediately.
00636  *     vSetBacklightState( BACKLIGHT_ON );
00637  *     if( xTimerReset( xBacklightTimer, 100 ) != pdPASS )
00638  *     {
00639  *         // The reset command was not executed successfully.  Take appropriate
00640  *         // action here.
00641  *     }
00642  *
00643  *     // Perform the rest of the key processing here.
00644  * }
00645  *
00646  * void main( void )
00647  * {
00648  * int32_t x;
00649  *
00650  *     // Create then start the one-shot timer that is responsible for turning
00651  *     // the back-light off if no keys are pressed within a 5 second period.
00652  *     xBacklightTimer = xTimerCreate( "BacklightTimer",           // Just a text name, not used by the kernel.
00653  *                                     ( 5000 / portTICK_PERIOD_MS), // The timer period in ticks.
00654  *                                     pdFALSE,                    // The timer is a one-shot timer.
00655  *                                     0,                          // The id is not used by the callback so can take any value.
00656  *                                     vBacklightTimerCallback     // The callback function that switches the LCD back-light off.
00657  *                                   );
00658  *
00659  *     if( xBacklightTimer == NULL )
00660  *     {
00661  *         // The timer was not created.
00662  *     }
00663  *     else
00664  *     {
00665  *         // Start the timer.  No block time is specified, and even if one was
00666  *         // it would be ignored because the scheduler has not yet been
00667  *         // started.
00668  *         if( xTimerStart( xBacklightTimer, 0 ) != pdPASS )
00669  *         {
00670  *             // The timer could not be set into the Active state.
00671  *         }
00672  *     }
00673  *
00674  *     // ...
00675  *     // Create tasks here.
00676  *     // ...
00677  *
00678  *     // Starting the scheduler will start the timer running as it has already
00679  *     // been set into the active state.
00680  *     xTaskStartScheduler();
00681  *
00682  *     // Should not reach here.
00683  *     for( ;; );
00684  * }
00685  * @endverbatim
00686  */
00687 #define xTimerReset( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
00688 
00689 /**
00690  * BaseType_t xTimerStartFromISR(   TimerHandle_t xTimer,
00691  *                                  BaseType_t *pxHigherPriorityTaskWoken );
00692  *
00693  * A version of xTimerStart() that can be called from an interrupt service
00694  * routine.
00695  *
00696  * @param xTimer The handle of the timer being started/restarted.
00697  *
00698  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
00699  * of its time in the Blocked state, waiting for messages to arrive on the timer
00700  * command queue.  Calling xTimerStartFromISR() writes a message to the timer
00701  * command queue, so has the potential to transition the timer service/daemon
00702  * task out of the Blocked state.  If calling xTimerStartFromISR() causes the
00703  * timer service/daemon task to leave the Blocked state, and the timer service/
00704  * daemon task has a priority equal to or greater than the currently executing
00705  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
00706  * get set to pdTRUE internally within the xTimerStartFromISR() function.  If
00707  * xTimerStartFromISR() sets this value to pdTRUE then a context switch should
00708  * be performed before the interrupt exits.
00709  *
00710  * @return pdFAIL will be returned if the start command could not be sent to
00711  * the timer command queue.  pdPASS will be returned if the command was
00712  * successfully sent to the timer command queue.  When the command is actually
00713  * processed will depend on the priority of the timer service/daemon task
00714  * relative to other tasks in the system, although the timers expiry time is
00715  * relative to when xTimerStartFromISR() is actually called.  The timer
00716  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
00717  * configuration constant.
00718  *
00719  * Example usage:
00720  * @verbatim
00721  * // This scenario assumes xBacklightTimer has already been created.  When a
00722  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass
00723  * // without a key being pressed, then the LCD back-light is switched off.  In
00724  * // this case, the timer is a one-shot timer, and unlike the example given for
00725  * // the xTimerReset() function, the key press event handler is an interrupt
00726  * // service routine.
00727  *
00728  * // The callback function assigned to the one-shot timer.  In this case the
00729  * // parameter is not used.
00730  * void vBacklightTimerCallback( TimerHandle_t pxTimer )
00731  * {
00732  *     // The timer expired, therefore 5 seconds must have passed since a key
00733  *     // was pressed.  Switch off the LCD back-light.
00734  *     vSetBacklightState( BACKLIGHT_OFF );
00735  * }
00736  *
00737  * // The key press interrupt service routine.
00738  * void vKeyPressEventInterruptHandler( void )
00739  * {
00740  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
00741  *
00742  *     // Ensure the LCD back-light is on, then restart the timer that is
00743  *     // responsible for turning the back-light off after 5 seconds of
00744  *     // key inactivity.  This is an interrupt service routine so can only
00745  *     // call FreeRTOS API functions that end in "FromISR".
00746  *     vSetBacklightState( BACKLIGHT_ON );
00747  *
00748  *     // xTimerStartFromISR() or xTimerResetFromISR() could be called here
00749  *     // as both cause the timer to re-calculate its expiry time.
00750  *     // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
00751  *     // declared (in this function).
00752  *     if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )
00753  *     {
00754  *         // The start command was not executed successfully.  Take appropriate
00755  *         // action here.
00756  *     }
00757  *
00758  *     // Perform the rest of the key processing here.
00759  *
00760  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
00761  *     // should be performed.  The syntax required to perform a context switch
00762  *     // from inside an ISR varies from port to port, and from compiler to
00763  *     // compiler.  Inspect the demos for the port you are using to find the
00764  *     // actual syntax required.
00765  *     if( xHigherPriorityTaskWoken != pdFALSE )
00766  *     {
00767  *         // Call the interrupt safe yield function here (actual function
00768  *         // depends on the FreeRTOS port being used).
00769  *     }
00770  * }
00771  * @endverbatim
00772  */
00773 #define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
00774 
00775 /**
00776  * BaseType_t xTimerStopFromISR(    TimerHandle_t xTimer,
00777  *                                  BaseType_t *pxHigherPriorityTaskWoken );
00778  *
00779  * A version of xTimerStop() that can be called from an interrupt service
00780  * routine.
00781  *
00782  * @param xTimer The handle of the timer being stopped.
00783  *
00784  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
00785  * of its time in the Blocked state, waiting for messages to arrive on the timer
00786  * command queue.  Calling xTimerStopFromISR() writes a message to the timer
00787  * command queue, so has the potential to transition the timer service/daemon
00788  * task out of the Blocked state.  If calling xTimerStopFromISR() causes the
00789  * timer service/daemon task to leave the Blocked state, and the timer service/
00790  * daemon task has a priority equal to or greater than the currently executing
00791  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
00792  * get set to pdTRUE internally within the xTimerStopFromISR() function.  If
00793  * xTimerStopFromISR() sets this value to pdTRUE then a context switch should
00794  * be performed before the interrupt exits.
00795  *
00796  * @return pdFAIL will be returned if the stop command could not be sent to
00797  * the timer command queue.  pdPASS will be returned if the command was
00798  * successfully sent to the timer command queue.  When the command is actually
00799  * processed will depend on the priority of the timer service/daemon task
00800  * relative to other tasks in the system.  The timer service/daemon task
00801  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
00802  *
00803  * Example usage:
00804  * @verbatim
00805  * // This scenario assumes xTimer has already been created and started.  When
00806  * // an interrupt occurs, the timer should be simply stopped.
00807  *
00808  * // The interrupt service routine that stops the timer.
00809  * void vAnExampleInterruptServiceRoutine( void )
00810  * {
00811  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
00812  *
00813  *     // The interrupt has occurred - simply stop the timer.
00814  *     // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
00815  *     // (within this function).  As this is an interrupt service routine, only
00816  *     // FreeRTOS API functions that end in "FromISR" can be used.
00817  *     if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
00818  *     {
00819  *         // The stop command was not executed successfully.  Take appropriate
00820  *         // action here.
00821  *     }
00822  *
00823  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
00824  *     // should be performed.  The syntax required to perform a context switch
00825  *     // from inside an ISR varies from port to port, and from compiler to
00826  *     // compiler.  Inspect the demos for the port you are using to find the
00827  *     // actual syntax required.
00828  *     if( xHigherPriorityTaskWoken != pdFALSE )
00829  *     {
00830  *         // Call the interrupt safe yield function here (actual function
00831  *         // depends on the FreeRTOS port being used).
00832  *     }
00833  * }
00834  * @endverbatim
00835  */
00836 #define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U )
00837 
00838 /**
00839  * BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer,
00840  *                                       TickType_t xNewPeriod,
00841  *                                       BaseType_t *pxHigherPriorityTaskWoken );
00842  *
00843  * A version of xTimerChangePeriod() that can be called from an interrupt
00844  * service routine.
00845  *
00846  * @param xTimer The handle of the timer that is having its period changed.
00847  *
00848  * @param xNewPeriod The new period for xTimer. Timer periods are specified in
00849  * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time
00850  * that has been specified in milliseconds.  For example, if the timer must
00851  * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively,
00852  * if the timer must expire after 500ms, then xNewPeriod can be set to
00853  * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than
00854  * or equal to 1000.
00855  *
00856  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
00857  * of its time in the Blocked state, waiting for messages to arrive on the timer
00858  * command queue.  Calling xTimerChangePeriodFromISR() writes a message to the
00859  * timer command queue, so has the potential to transition the timer service/
00860  * daemon task out of the Blocked state.  If calling xTimerChangePeriodFromISR()
00861  * causes the timer service/daemon task to leave the Blocked state, and the
00862  * timer service/daemon task has a priority equal to or greater than the
00863  * currently executing task (the task that was interrupted), then
00864  * *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the
00865  * xTimerChangePeriodFromISR() function.  If xTimerChangePeriodFromISR() sets
00866  * this value to pdTRUE then a context switch should be performed before the
00867  * interrupt exits.
00868  *
00869  * @return pdFAIL will be returned if the command to change the timers period
00870  * could not be sent to the timer command queue.  pdPASS will be returned if the
00871  * command was successfully sent to the timer command queue.  When the command
00872  * is actually processed will depend on the priority of the timer service/daemon
00873  * task relative to other tasks in the system.  The timer service/daemon task
00874  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
00875  *
00876  * Example usage:
00877  * @verbatim
00878  * // This scenario assumes xTimer has already been created and started.  When
00879  * // an interrupt occurs, the period of xTimer should be changed to 500ms.
00880  *
00881  * // The interrupt service routine that changes the period of xTimer.
00882  * void vAnExampleInterruptServiceRoutine( void )
00883  * {
00884  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
00885  *
00886  *     // The interrupt has occurred - change the period of xTimer to 500ms.
00887  *     // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
00888  *     // (within this function).  As this is an interrupt service routine, only
00889  *     // FreeRTOS API functions that end in "FromISR" can be used.
00890  *     if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
00891  *     {
00892  *         // The command to change the timers period was not executed
00893  *         // successfully.  Take appropriate action here.
00894  *     }
00895  *
00896  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
00897  *     // should be performed.  The syntax required to perform a context switch
00898  *     // from inside an ISR varies from port to port, and from compiler to
00899  *     // compiler.  Inspect the demos for the port you are using to find the
00900  *     // actual syntax required.
00901  *     if( xHigherPriorityTaskWoken != pdFALSE )
00902  *     {
00903  *         // Call the interrupt safe yield function here (actual function
00904  *         // depends on the FreeRTOS port being used).
00905  *     }
00906  * }
00907  * @endverbatim
00908  */
00909 #define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )
00910 
00911 /**
00912  * BaseType_t xTimerResetFromISR(   TimerHandle_t xTimer,
00913  *                                  BaseType_t *pxHigherPriorityTaskWoken );
00914  *
00915  * A version of xTimerReset() that can be called from an interrupt service
00916  * routine.
00917  *
00918  * @param xTimer The handle of the timer that is to be started, reset, or
00919  * restarted.
00920  *
00921  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
00922  * of its time in the Blocked state, waiting for messages to arrive on the timer
00923  * command queue.  Calling xTimerResetFromISR() writes a message to the timer
00924  * command queue, so has the potential to transition the timer service/daemon
00925  * task out of the Blocked state.  If calling xTimerResetFromISR() causes the
00926  * timer service/daemon task to leave the Blocked state, and the timer service/
00927  * daemon task has a priority equal to or greater than the currently executing
00928  * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
00929  * get set to pdTRUE internally within the xTimerResetFromISR() function.  If
00930  * xTimerResetFromISR() sets this value to pdTRUE then a context switch should
00931  * be performed before the interrupt exits.
00932  *
00933  * @return pdFAIL will be returned if the reset command could not be sent to
00934  * the timer command queue.  pdPASS will be returned if the command was
00935  * successfully sent to the timer command queue.  When the command is actually
00936  * processed will depend on the priority of the timer service/daemon task
00937  * relative to other tasks in the system, although the timers expiry time is
00938  * relative to when xTimerResetFromISR() is actually called.  The timer service/daemon
00939  * task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
00940  *
00941  * Example usage:
00942  * @verbatim
00943  * // This scenario assumes xBacklightTimer has already been created.  When a
00944  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass
00945  * // without a key being pressed, then the LCD back-light is switched off.  In
00946  * // this case, the timer is a one-shot timer, and unlike the example given for
00947  * // the xTimerReset() function, the key press event handler is an interrupt
00948  * // service routine.
00949  *
00950  * // The callback function assigned to the one-shot timer.  In this case the
00951  * // parameter is not used.
00952  * void vBacklightTimerCallback( TimerHandle_t pxTimer )
00953  * {
00954  *     // The timer expired, therefore 5 seconds must have passed since a key
00955  *     // was pressed.  Switch off the LCD back-light.
00956  *     vSetBacklightState( BACKLIGHT_OFF );
00957  * }
00958  *
00959  * // The key press interrupt service routine.
00960  * void vKeyPressEventInterruptHandler( void )
00961  * {
00962  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
00963  *
00964  *     // Ensure the LCD back-light is on, then reset the timer that is
00965  *     // responsible for turning the back-light off after 5 seconds of
00966  *     // key inactivity.  This is an interrupt service routine so can only
00967  *     // call FreeRTOS API functions that end in "FromISR".
00968  *     vSetBacklightState( BACKLIGHT_ON );
00969  *
00970  *     // xTimerStartFromISR() or xTimerResetFromISR() could be called here
00971  *     // as both cause the timer to re-calculate its expiry time.
00972  *     // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
00973  *     // declared (in this function).
00974  *     if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )
00975  *     {
00976  *         // The reset command was not executed successfully.  Take appropriate
00977  *         // action here.
00978  *     }
00979  *
00980  *     // Perform the rest of the key processing here.
00981  *
00982  *     // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
00983  *     // should be performed.  The syntax required to perform a context switch
00984  *     // from inside an ISR varies from port to port, and from compiler to
00985  *     // compiler.  Inspect the demos for the port you are using to find the
00986  *     // actual syntax required.
00987  *     if( xHigherPriorityTaskWoken != pdFALSE )
00988  *     {
00989  *         // Call the interrupt safe yield function here (actual function
00990  *         // depends on the FreeRTOS port being used).
00991  *     }
00992  * }
00993  * @endverbatim
00994  */
00995 #define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
00996 
00997 
00998 /**
00999  * BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,
01000  *                                          void *pvParameter1,
01001  *                                          uint32_t ulParameter2,
01002  *                                          BaseType_t *pxHigherPriorityTaskWoken );
01003  *
01004  *
01005  * Used from application interrupt service routines to defer the execution of a
01006  * function to the RTOS daemon task (the timer service task, hence this function
01007  * is implemented in timers.c and is prefixed with 'Timer').
01008  *
01009  * Ideally an interrupt service routine (ISR) is kept as short as possible, but
01010  * sometimes an ISR either has a lot of processing to do, or needs to perform
01011  * processing that is not deterministic.  In these cases
01012  * xTimerPendFunctionCallFromISR() can be used to defer processing of a function
01013  * to the RTOS daemon task.
01014  *
01015  * A mechanism is provided that allows the interrupt to return directly to the
01016  * task that will subsequently execute the pended callback function.  This
01017  * allows the callback function to execute contiguously in time with the
01018  * interrupt - just as if the callback had executed in the interrupt itself.
01019  *
01020  * @param xFunctionToPend The function to execute from the timer service/
01021  * daemon task.  The function must conform to the PendedFunction_t
01022  * prototype.
01023  *
01024  * @param pvParameter1 The value of the callback function's first parameter.
01025  * The parameter has a void * type to allow it to be used to pass any type.
01026  * For example, unsigned longs can be cast to a void *, or the void * can be
01027  * used to point to a structure.
01028  *
01029  * @param ulParameter2 The value of the callback function's second parameter.
01030  *
01031  * @param pxHigherPriorityTaskWoken As mentioned above, calling this function
01032  * will result in a message being sent to the timer daemon task.  If the
01033  * priority of the timer daemon task (which is set using
01034  * configTIMER_TASK_PRIORITY in FreeRTOSConfig.h) is higher than the priority of
01035  * the currently running task (the task the interrupt interrupted) then
01036  * *pxHigherPriorityTaskWoken will be set to pdTRUE within
01037  * xTimerPendFunctionCallFromISR(), indicating that a context switch should be
01038  * requested before the interrupt exits.  For that reason
01039  * *pxHigherPriorityTaskWoken must be initialised to pdFALSE.  See the
01040  * example code below.
01041  *
01042  * @return pdPASS is returned if the message was successfully sent to the
01043  * timer daemon task, otherwise pdFALSE is returned.
01044  *
01045  * Example usage:
01046  * @verbatim
01047  *
01048  *  // The callback function that will execute in the context of the daemon task.
01049  *  // Note callback functions must all use this same prototype.
01050  *  void vProcessInterface( void *pvParameter1, uint32_t ulParameter2 )
01051  *  {
01052  *      BaseType_t xInterfaceToService;
01053  *
01054  *      // The interface that requires servicing is passed in the second
01055  *      // parameter.  The first parameter is not used in this case.
01056  *      xInterfaceToService = ( BaseType_t ) ulParameter2;
01057  *
01058  *      // ...Perform the processing here...
01059  *  }
01060  *
01061  *  // An ISR that receives data packets from multiple interfaces
01062  *  void vAnISR( void )
01063  *  {
01064  *      BaseType_t xInterfaceToService, xHigherPriorityTaskWoken;
01065  *
01066  *      // Query the hardware to determine which interface needs processing.
01067  *      xInterfaceToService = prvCheckInterfaces();
01068  *
01069  *      // The actual processing is to be deferred to a task.  Request the
01070  *      // vProcessInterface() callback function is executed, passing in the
01071  *      // number of the interface that needs processing.  The interface to
01072  *      // service is passed in the second parameter.  The first parameter is
01073  *      // not used in this case.
01074  *      xHigherPriorityTaskWoken = pdFALSE;
01075  *      xTimerPendFunctionCallFromISR( vProcessInterface, NULL, ( uint32_t ) xInterfaceToService, &xHigherPriorityTaskWoken );
01076  *
01077  *      // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
01078  *      // switch should be requested.  The macro used is port specific and will
01079  *      // be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to
01080  *      // the documentation page for the port being used.
01081  *      portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
01082  *
01083  *  }
01084  * @endverbatim
01085  */
01086 BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken );
01087 
01088  /**
01089   * BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,
01090   *                                    void *pvParameter1,
01091   *                                    uint32_t ulParameter2,
01092   *                                    TickType_t xTicksToWait );
01093   *
01094   *
01095   * Used to defer the execution of a function to the RTOS daemon task (the timer
01096   * service task, hence this function is implemented in timers.c and is prefixed
01097   * with 'Timer').
01098   *
01099   * @param xFunctionToPend The function to execute from the timer service/
01100   * daemon task.  The function must conform to the PendedFunction_t
01101   * prototype.
01102   *
01103   * @param pvParameter1 The value of the callback function's first parameter.
01104   * The parameter has a void * type to allow it to be used to pass any type.
01105   * For example, unsigned longs can be cast to a void *, or the void * can be
01106   * used to point to a structure.
01107   *
01108   * @param ulParameter2 The value of the callback function's second parameter.
01109   *
01110   * @param xTicksToWait Calling this function will result in a message being
01111   * sent to the timer daemon task on a queue.  xTicksToWait is the amount of
01112   * time the calling task should remain in the Blocked state (so not using any
01113   * processing time) for space to become available on the timer queue if the
01114   * queue is found to be full.
01115   *
01116   * @return pdPASS is returned if the message was successfully sent to the
01117   * timer daemon task, otherwise pdFALSE is returned.
01118   *
01119   */
01120 BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait );
01121 
01122 /**
01123  * const char * const pcTimerGetTimerName( TimerHandle_t xTimer );
01124  *
01125  * Returns the name that was assigned to a timer when the timer was created.
01126  *
01127  * @param xTimer The handle of the timer being queried.
01128  *
01129  * @return The name assigned to the timer specified by the xTimer parameter.
01130  */
01131 const char * pcTimerGetTimerName( TimerHandle_t xTimer ); /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
01132 
01133 /*
01134  * Functions beyond this part are not part of the public API and are intended
01135  * for use by the kernel only.
01136  */
01137 BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;
01138 BaseType_t xTimerGenericCommand( TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t * const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
01139 
01140 #ifdef __cplusplus
01141 }
01142 #endif
01143 #endif /* TIMERS_H */
01144 
01145 
01146 
01147