Rohit Grover / FreeRTOS

www.freertos.org

Dependents:   Nucleo freertos_test FreeRTOS_test freertos_bluetooth ... more

Source/include/timers.h@0:8e57f3e9cc89, 2014-01-24 (annotated)

Committer:
rgrover1
Date:
Fri Jan 24 14:56:04 2014 +0000
Revision:
0:8e57f3e9cc89
Making FreeRTOS available as a library

Who changed what in which revision?

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