João Jardim / FreeRTOS_V8_2_1_LPC1768

FreeRTOS v_8.2.1 for LPC1768

Dependents:   frtos_v_8_bluetooth frtos_v_8_pololu frtos_v_8_Final

source/include/timers.h@0:91ad48ad5687, 2015-06-06 (annotated)

Committer:
dflet
Date:
Sat Jun 06 13:27:43 2015 +0000
Revision:
0:91ad48ad5687
Setup for LPC CM3 but may work with LPC CM4

Who changed what in which revision?

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