1 /* 2 * FreeRTOS Kernel V10.3.1 3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a copy 6 * of this software and associated documentation files (the "Software"), to deal 7 * in the Software without restriction, including without limitation the rights 8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 * copies of the Software, and to permit persons to whom the Software is 10 * furnished to do so, subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be included in 13 * all copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 * SOFTWARE. 22 * 23 * http://www.FreeRTOS.org 24 * http://aws.amazon.com/freertos 25 * 26 * 1 tab == 4 spaces! 27 */ 28 29 #ifndef TIMERS_H 30 #define TIMERS_H 31 32 #ifndef INC_FREERTOS_H 33 # error \ 34 "include FreeRTOS.h must appear in source files before include timers.h" 35 #endif 36 37 /*lint -save -e537 This headers are only multiply included if the application 38 code happens to also be including task.h. */ 39 #include "task.h" 40 /*lint -restore */ 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /*----------------------------------------------------------- 47 * MACROS AND DEFINITIONS 48 *----------------------------------------------------------*/ 49 50 /* IDs for commands that can be sent/received on the timer queue. These are to 51 be used solely through the macros that make up the public software timer API, 52 as defined below. The commands that are sent from interrupts must use the 53 highest numbers as tmrFIRST_FROM_ISR_COMMAND is used to determine if the task 54 or interrupt version of the queue send function should be used. */ 55 #define tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR ((BaseType_t)-2) 56 #define tmrCOMMAND_EXECUTE_CALLBACK ((BaseType_t)-1) 57 #define tmrCOMMAND_START_DONT_TRACE ((BaseType_t)0) 58 #define tmrCOMMAND_START ((BaseType_t)1) 59 #define tmrCOMMAND_RESET ((BaseType_t)2) 60 #define tmrCOMMAND_STOP ((BaseType_t)3) 61 #define tmrCOMMAND_CHANGE_PERIOD ((BaseType_t)4) 62 #define tmrCOMMAND_DELETE ((BaseType_t)5) 63 64 #define tmrFIRST_FROM_ISR_COMMAND ((BaseType_t)6) 65 #define tmrCOMMAND_START_FROM_ISR ((BaseType_t)6) 66 #define tmrCOMMAND_RESET_FROM_ISR ((BaseType_t)7) 67 #define tmrCOMMAND_STOP_FROM_ISR ((BaseType_t)8) 68 #define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR ((BaseType_t)9) 69 70 /** 71 * Type by which software timers are referenced. For example, a call to 72 * xTimerCreate() returns an TimerHandle_t variable that can then be used to 73 * reference the subject timer in calls to other software timer API functions 74 * (for example, xTimerStart(), xTimerReset(), etc.). 75 */ 76 struct tmrTimerControl; /* The old naming convention is used to prevent breaking 77 kernel aware debuggers. */ 78 typedef struct tmrTimerControl *TimerHandle_t; 79 80 /* 81 * Defines the prototype to which timer callback functions must conform. 82 */ 83 typedef void (*TimerCallbackFunction_t)(TimerHandle_t xTimer); 84 85 /* 86 * Defines the prototype to which functions used with the 87 * xTimerPendFunctionCallFromISR() function must conform. 88 */ 89 typedef void (*PendedFunction_t)(void *, uint32_t); 90 91 /** 92 * TimerHandle_t xTimerCreate( const char * const pcTimerName, 93 * TickType_t xTimerPeriodInTicks, 94 * UBaseType_t uxAutoReload, 95 * void * pvTimerID, 96 * TimerCallbackFunction_t pxCallbackFunction ); 97 * 98 * Creates a new software timer instance, and returns a handle by which the 99 * created software timer can be referenced. 100 * 101 * Internally, within the FreeRTOS implementation, software timers use a block 102 * of memory, in which the timer data structure is stored. If a software timer 103 * is created using xTimerCreate() then the required memory is automatically 104 * dynamically allocated inside the xTimerCreate() function. (see 105 * http://www.freertos.org/a00111.html). If a software timer is created using 106 * xTimerCreateStatic() then the application writer must provide the memory that 107 * will get used by the software timer. xTimerCreateStatic() therefore allows a 108 * software timer to be created without using any dynamic memory allocation. 109 * 110 * Timers are created in the dormant state. The xTimerStart(), xTimerReset(), 111 * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and 112 * xTimerChangePeriodFromISR() API functions can all be used to transition a 113 * timer into the active state. 114 * 115 * @param pcTimerName A text name that is assigned to the timer. This is done 116 * purely to assist debugging. The kernel itself only ever references a timer 117 * by its handle, and never by its name. 118 * 119 * @param xTimerPeriodInTicks The timer period. The time is defined in tick 120 * periods so the constant portTICK_PERIOD_MS can be used to convert a time that 121 * has been specified in milliseconds. For example, if the timer must expire 122 * after 100 ticks, then xTimerPeriodInTicks should be set to 100. 123 * Alternatively, if the timer must expire after 500ms, then xPeriod can be set 124 * to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or 125 * equal to 1000. 126 * 127 * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will 128 * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter. 129 * If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and 130 * enter the dormant state after it expires. 131 * 132 * @param pvTimerID An identifier that is assigned to the timer being created. 133 * Typically this would be used in the timer callback function to identify which 134 * timer expired when the same callback function is assigned to more than one 135 * timer. 136 * 137 * @param pxCallbackFunction The function to call when the timer expires. 138 * Callback functions must have the prototype defined by 139 * TimerCallbackFunction_t, which is "void vCallbackFunction( TimerHandle_t 140 * xTimer );". 141 * 142 * @return If the timer is successfully created then a handle to the newly 143 * created timer is returned. If the timer cannot be created (because either 144 * there is insufficient FreeRTOS heap remaining to allocate the timer 145 * structures, or the timer period was set to 0) then NULL is returned. 146 * 147 * Example usage: 148 * @verbatim 149 * #define NUM_TIMERS 5 150 * 151 * // An array to hold handles to the created timers. 152 * TimerHandle_t xTimers[ NUM_TIMERS ]; 153 * 154 * // An array to hold a count of the number of times each timer expires. 155 * int32_t lExpireCounters[ NUM_TIMERS ] = { 0 }; 156 * 157 * // Define a callback function that will be used by multiple timer instances. 158 * // The callback function does nothing but count the number of times the 159 * // associated timer expires, and stop the timer once the timer has expired 160 * // 10 times. 161 * void vTimerCallback( TimerHandle_t pxTimer ) 162 * { 163 * int32_t lArrayIndex; 164 * const int32_t xMaxExpiryCountBeforeStopping = 10; 165 * 166 * // Optionally do something if the pxTimer parameter is NULL. 167 * configASSERT( pxTimer ); 168 * 169 * // Which timer expired? 170 * lArrayIndex = ( int32_t ) pvTimerGetTimerID( pxTimer ); 171 * 172 * // Increment the number of times that pxTimer has expired. 173 * lExpireCounters[ lArrayIndex ] += 1; 174 * 175 * // If the timer has expired 10 times then stop it from running. 176 * if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping ) 177 * { 178 * // Do not use a block time if calling a timer API function from a 179 * // timer callback function, as doing so could cause a deadlock! 180 * xTimerStop( pxTimer, 0 ); 181 * } 182 * } 183 * 184 * void main( void ) 185 * { 186 * int32_t x; 187 * 188 * // Create then start some timers. Starting the timers before the 189 * scheduler 190 * // has been started means the timers will start running immediately that 191 * // the scheduler starts. 192 * for( x = 0; x < NUM_TIMERS; x++ ) 193 * { 194 * xTimers[ x ] = xTimerCreate( "Timer", // Just a text name, 195 * not used by the kernel. ( 100 * x ), // The timer period in ticks. pdTRUE, 196 * // The timers will auto-reload themselves when they expire. ( void * ) x, // 197 * Assign each timer a unique id equal to its array index. vTimerCallback // 198 * Each timer calls the same callback when it expires. 199 * ); 200 * 201 * if( xTimers[ x ] == NULL ) 202 * { 203 * // The timer was not created. 204 * } 205 * else 206 * { 207 * // Start the timer. No block time is specified, and even if one 208 * was 209 * // it would be ignored because the scheduler has not yet been 210 * // started. 211 * if( xTimerStart( xTimers[ x ], 0 ) != pdPASS ) 212 * { 213 * // The timer could not be set into the Active state. 214 * } 215 * } 216 * } 217 * 218 * // ... 219 * // Create tasks here. 220 * // ... 221 * 222 * // Starting the scheduler will start the timers running as they have 223 * already 224 * // been set into the active state. 225 * vTaskStartScheduler(); 226 * 227 * // Should not reach here. 228 * for( ;; ); 229 * } 230 * @endverbatim 231 */ 232 #if (configSUPPORT_DYNAMIC_ALLOCATION == 1) 233 TimerHandle_t xTimerCreate( 234 const char 235 *const pcTimerName, /*lint !e971 Unqualified char types are allowed for 236 strings and single characters only. */ 237 const TickType_t xTimerPeriodInTicks, 238 const UBaseType_t uxAutoReload, 239 void *const pvTimerID, 240 TimerCallbackFunction_t pxCallbackFunction) PRIVILEGED_FUNCTION; 241 #endif 242 243 /** 244 * TimerHandle_t xTimerCreateStatic(const char * const pcTimerName, 245 * TickType_t xTimerPeriodInTicks, 246 * UBaseType_t uxAutoReload, 247 * void * pvTimerID, 248 * TimerCallbackFunction_t pxCallbackFunction, 249 * StaticTimer_t *pxTimerBuffer ); 250 * 251 * Creates a new software timer instance, and returns a handle by which the 252 * created software timer can be referenced. 253 * 254 * Internally, within the FreeRTOS implementation, software timers use a block 255 * of memory, in which the timer data structure is stored. If a software timer 256 * is created using xTimerCreate() then the required memory is automatically 257 * dynamically allocated inside the xTimerCreate() function. (see 258 * http://www.freertos.org/a00111.html). If a software timer is created using 259 * xTimerCreateStatic() then the application writer must provide the memory that 260 * will get used by the software timer. xTimerCreateStatic() therefore allows a 261 * software timer to be created without using any dynamic memory allocation. 262 * 263 * Timers are created in the dormant state. The xTimerStart(), xTimerReset(), 264 * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and 265 * xTimerChangePeriodFromISR() API functions can all be used to transition a 266 * timer into the active state. 267 * 268 * @param pcTimerName A text name that is assigned to the timer. This is done 269 * purely to assist debugging. The kernel itself only ever references a timer 270 * by its handle, and never by its name. 271 * 272 * @param xTimerPeriodInTicks The timer period. The time is defined in tick 273 * periods so the constant portTICK_PERIOD_MS can be used to convert a time that 274 * has been specified in milliseconds. For example, if the timer must expire 275 * after 100 ticks, then xTimerPeriodInTicks should be set to 100. 276 * Alternatively, if the timer must expire after 500ms, then xPeriod can be set 277 * to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or 278 * equal to 1000. 279 * 280 * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will 281 * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter. 282 * If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and 283 * enter the dormant state after it expires. 284 * 285 * @param pvTimerID An identifier that is assigned to the timer being created. 286 * Typically this would be used in the timer callback function to identify which 287 * timer expired when the same callback function is assigned to more than one 288 * timer. 289 * 290 * @param pxCallbackFunction The function to call when the timer expires. 291 * Callback functions must have the prototype defined by 292 *TimerCallbackFunction_t, which is "void vCallbackFunction( TimerHandle_t 293 *xTimer );". 294 * 295 * @param pxTimerBuffer Must point to a variable of type StaticTimer_t, which 296 * will be then be used to hold the software timer's data structures, removing 297 * the need for the memory to be allocated dynamically. 298 * 299 * @return If the timer is created then a handle to the created timer is 300 * returned. If pxTimerBuffer was NULL then NULL is returned. 301 * 302 * Example usage: 303 * @verbatim 304 * 305 * // The buffer used to hold the software timer's data structure. 306 * static StaticTimer_t xTimerBuffer; 307 * 308 * // A variable that will be incremented by the software timer's callback 309 * // function. 310 * UBaseType_t uxVariableToIncrement = 0; 311 * 312 * // A software timer callback function that increments a variable passed to 313 * // it when the software timer was created. After the 5th increment the 314 * // callback function stops the software timer. 315 * static void prvTimerCallback( TimerHandle_t xExpiredTimer ) 316 * { 317 * UBaseType_t *puxVariableToIncrement; 318 * BaseType_t xReturned; 319 * 320 * // Obtain the address of the variable to increment from the timer ID. 321 * puxVariableToIncrement = ( UBaseType_t * ) pvTimerGetTimerID( 322 *xExpiredTimer ); 323 * 324 * // Increment the variable to show the timer callback has executed. 325 * ( *puxVariableToIncrement )++; 326 * 327 * // If this callback has executed the required number of times, stop the 328 * // timer. 329 * if( *puxVariableToIncrement == 5 ) 330 * { 331 * // This is called from a timer callback so must not block. 332 * xTimerStop( xExpiredTimer, staticDONT_BLOCK ); 333 * } 334 * } 335 * 336 * 337 * void main( void ) 338 * { 339 * // Create the software time. xTimerCreateStatic() has an extra parameter 340 * // than the normal xTimerCreate() API function. The parameter is a 341 *pointer 342 * // to the StaticTimer_t structure that will hold the software timer 343 * // structure. If the parameter is passed as NULL then the structure will 344 *be 345 * // allocated dynamically, just as if xTimerCreate() had been called. 346 * xTimer = xTimerCreateStatic( "T1", // Text name for the task. 347 *Helps debugging only. Not used by FreeRTOS. xTimerPeriod, // The period 348 *of the timer in ticks. pdTRUE, // This is an auto-reload timer. ( 349 *void * ) &uxVariableToIncrement, // A variable incremented by the software 350 *timer's callback function prvTimerCallback, // The function to execute when 351 *the timer expires. &xTimerBuffer ); // The buffer that will hold the software 352 *timer structure. 353 * 354 * // The scheduler has not started yet so a block time is not used. 355 * xReturned = xTimerStart( xTimer, 0 ); 356 * 357 * // ... 358 * // Create tasks here. 359 * // ... 360 * 361 * // Starting the scheduler will start the timers running as they have 362 *already 363 * // been set into the active state. 364 * vTaskStartScheduler(); 365 * 366 * // Should not reach here. 367 * for( ;; ); 368 * } 369 * @endverbatim 370 */ 371 #if (configSUPPORT_STATIC_ALLOCATION == 1) 372 TimerHandle_t xTimerCreateStatic( 373 const char 374 *const pcTimerName, /*lint !e971 Unqualified char types are allowed for 375 strings and single characters only. */ 376 const TickType_t xTimerPeriodInTicks, 377 const UBaseType_t uxAutoReload, 378 void *const pvTimerID, 379 TimerCallbackFunction_t pxCallbackFunction, 380 StaticTimer_t *pxTimerBuffer) PRIVILEGED_FUNCTION; 381 #endif /* configSUPPORT_STATIC_ALLOCATION */ 382 383 /** 384 * void *pvTimerGetTimerID( TimerHandle_t xTimer ); 385 * 386 * Returns the ID assigned to the timer. 387 * 388 * IDs are assigned to timers using the pvTimerID parameter of the call to 389 * xTimerCreated() that was used to create the timer, and by calling the 390 * vTimerSetTimerID() API function. 391 * 392 * If the same callback function is assigned to multiple timers then the timer 393 * ID can be used as time specific (timer local) storage. 394 * 395 * @param xTimer The timer being queried. 396 * 397 * @return The ID assigned to the timer being queried. 398 * 399 * Example usage: 400 * 401 * See the xTimerCreate() API function example usage scenario. 402 */ 403 void *pvTimerGetTimerID(const TimerHandle_t xTimer) PRIVILEGED_FUNCTION; 404 405 /** 406 * void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ); 407 * 408 * Sets the ID assigned to the timer. 409 * 410 * IDs are assigned to timers using the pvTimerID parameter of the call to 411 * xTimerCreated() that was used to create the timer. 412 * 413 * If the same callback function is assigned to multiple timers then the timer 414 * ID can be used as time specific (timer local) storage. 415 * 416 * @param xTimer The timer being updated. 417 * 418 * @param pvNewID The ID to assign to the timer. 419 * 420 * Example usage: 421 * 422 * See the xTimerCreate() API function example usage scenario. 423 */ 424 void vTimerSetTimerID(TimerHandle_t xTimer, void *pvNewID) PRIVILEGED_FUNCTION; 425 426 /** 427 * BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ); 428 * 429 * Queries a timer to see if it is active or dormant. 430 * 431 * A timer will be dormant if: 432 * 1) It has been created but not started, or 433 * 2) It is an expired one-shot timer that has not been restarted. 434 * 435 * Timers are created in the dormant state. The xTimerStart(), xTimerReset(), 436 * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and 437 * xTimerChangePeriodFromISR() API functions can all be used to transition a 438 * timer into the active state. 439 * 440 * @param xTimer The timer being queried. 441 * 442 * @return pdFALSE will be returned if the timer is dormant. A value other than 443 * pdFALSE will be returned if the timer is active. 444 * 445 * Example usage: 446 * @verbatim 447 * // This function assumes xTimer has already been created. 448 * void vAFunction( TimerHandle_t xTimer ) 449 * { 450 * if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and 451 * equivalently "if( xTimerIsTimerActive( xTimer ) )" 452 * { 453 * // xTimer is active, do something. 454 * } 455 * else 456 * { 457 * // xTimer is not active, do something else. 458 * } 459 * } 460 * @endverbatim 461 */ 462 BaseType_t xTimerIsTimerActive(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; 463 464 /** 465 * TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ); 466 * 467 * Simply returns the handle of the timer service/daemon task. It it not valid 468 * to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been 469 * started. 470 */ 471 TaskHandle_t xTimerGetTimerDaemonTaskHandle(void) PRIVILEGED_FUNCTION; 472 473 /** 474 * BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait ); 475 * 476 * Timer functionality is provided by a timer service/daemon task. Many of the 477 * public FreeRTOS timer API functions send commands to the timer service task 478 * through a queue called the timer command queue. The timer command queue is 479 * private to the kernel itself and is not directly accessible to application 480 * code. The length of the timer command queue is set by the 481 * configTIMER_QUEUE_LENGTH configuration constant. 482 * 483 * xTimerStart() starts a timer that was previously created using the 484 * xTimerCreate() API function. If the timer had already been started and was 485 * already in the active state, then xTimerStart() has equivalent functionality 486 * to the xTimerReset() API function. 487 * 488 * Starting a timer ensures the timer is in the active state. If the timer 489 * is not stopped, deleted, or reset in the mean time, the callback function 490 * associated with the timer will get called 'n' ticks after xTimerStart() was 491 * called, where 'n' is the timers defined period. 492 * 493 * It is valid to call xTimerStart() before the scheduler has been started, but 494 * when this is done the timer will not actually start until the scheduler is 495 * started, and the timers expiry time will be relative to when the scheduler is 496 * started, not relative to when xTimerStart() was called. 497 * 498 * The configUSE_TIMERS configuration constant must be set to 1 for 499 * xTimerStart() to be available. 500 * 501 * @param xTimer The handle of the timer being started/restarted. 502 * 503 * @param xTicksToWait Specifies the time, in ticks, that the calling task 504 * should be held in the Blocked state to wait for the start command to be 505 * successfully sent to the timer command queue, should the queue already be 506 * full when xTimerStart() was called. xTicksToWait is ignored if xTimerStart() 507 * is called before the scheduler is started. 508 * 509 * @return pdFAIL will be returned if the start command could not be sent to 510 * the timer command queue even after xTicksToWait ticks had passed. pdPASS 511 * will be returned if the command was successfully sent to the timer command 512 * queue. When the command is actually processed will depend on the priority of 513 * the timer service/daemon task relative to other tasks in the system, although 514 * the timers expiry time is relative to when xTimerStart() is actually called. 515 * The timer service/daemon task priority is set by the 516 * configTIMER_TASK_PRIORITY configuration constant. 517 * 518 * Example usage: 519 * 520 * See the xTimerCreate() API function example usage scenario. 521 * 522 */ 523 #define xTimerStart(xTimer, xTicksToWait) \ 524 xTimerGenericCommand( \ 525 (xTimer), \ 526 tmrCOMMAND_START, \ 527 (xTaskGetTickCount()), \ 528 NULL, \ 529 (xTicksToWait)) 530 531 /** 532 * BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait ); 533 * 534 * Timer functionality is provided by a timer service/daemon task. Many of the 535 * public FreeRTOS timer API functions send commands to the timer service task 536 * through a queue called the timer command queue. The timer command queue is 537 * private to the kernel itself and is not directly accessible to application 538 * code. The length of the timer command queue is set by the 539 * configTIMER_QUEUE_LENGTH configuration constant. 540 * 541 * xTimerStop() stops a timer that was previously started using either of the 542 * The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), 543 * xTimerChangePeriod() or xTimerChangePeriodFromISR() API functions. 544 * 545 * Stopping a timer ensures the timer is not in the active state. 546 * 547 * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop() 548 * to be available. 549 * 550 * @param xTimer The handle of the timer being stopped. 551 * 552 * @param xTicksToWait Specifies the time, in ticks, that the calling task 553 * should be held in the Blocked state to wait for the stop command to be 554 * successfully sent to the timer command queue, should the queue already be 555 * full when xTimerStop() was called. xTicksToWait is ignored if xTimerStop() 556 * is called before the scheduler is started. 557 * 558 * @return pdFAIL will be returned if the stop command could not be sent to 559 * the timer command queue even after xTicksToWait ticks had passed. pdPASS 560 * will be returned if the command was successfully sent to the timer command 561 * queue. When the command is actually processed will depend on the priority of 562 * the timer service/daemon task relative to other tasks in the system. The 563 * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY 564 * configuration constant. 565 * 566 * Example usage: 567 * 568 * See the xTimerCreate() API function example usage scenario. 569 * 570 */ 571 #define xTimerStop(xTimer, xTicksToWait) \ 572 xTimerGenericCommand((xTimer), tmrCOMMAND_STOP, 0U, NULL, (xTicksToWait)) 573 574 /** 575 * BaseType_t xTimerChangePeriod( TimerHandle_t xTimer, 576 * TickType_t xNewPeriod, 577 * TickType_t xTicksToWait ); 578 * 579 * Timer functionality is provided by a timer service/daemon task. Many of the 580 * public FreeRTOS timer API functions send commands to the timer service task 581 * through a queue called the timer command queue. The timer command queue is 582 * private to the kernel itself and is not directly accessible to application 583 * code. The length of the timer command queue is set by the 584 * configTIMER_QUEUE_LENGTH configuration constant. 585 * 586 * xTimerChangePeriod() changes the period of a timer that was previously 587 * created using the xTimerCreate() API function. 588 * 589 * xTimerChangePeriod() can be called to change the period of an active or 590 * dormant state timer. 591 * 592 * The configUSE_TIMERS configuration constant must be set to 1 for 593 * xTimerChangePeriod() to be available. 594 * 595 * @param xTimer The handle of the timer that is having its period changed. 596 * 597 * @param xNewPeriod The new period for xTimer. Timer periods are specified in 598 * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a 599 *time that has been specified in milliseconds. For example, if the timer must 600 * expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively, 601 * if the timer must expire after 500ms, then xNewPeriod can be set to 602 * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than 603 * or equal to 1000. 604 * 605 * @param xTicksToWait Specifies the time, in ticks, that the calling task 606 *should be held in the Blocked state to wait for the change period command to 607 *be successfully sent to the timer command queue, should the queue already be 608 * full when xTimerChangePeriod() was called. xTicksToWait is ignored if 609 * xTimerChangePeriod() is called before the scheduler is started. 610 * 611 * @return pdFAIL will be returned if the change period command could not be 612 * sent to the timer command queue even after xTicksToWait ticks had passed. 613 * pdPASS will be returned if the command was successfully sent to the timer 614 * command queue. When the command is actually processed will depend on the 615 * priority of the timer service/daemon task relative to other tasks in the 616 * system. The timer service/daemon task priority is set by the 617 * configTIMER_TASK_PRIORITY configuration constant. 618 * 619 * Example usage: 620 * @verbatim 621 * // This function assumes xTimer has already been created. If the timer 622 * // referenced by xTimer is already active when it is called, then the timer 623 * // is deleted. If the timer referenced by xTimer is not active when it is 624 * // called, then the period of the timer is set to 500ms and the timer is 625 * // started. 626 * void vAFunction( TimerHandle_t xTimer ) 627 * { 628 * if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and 629 *equivalently "if( xTimerIsTimerActive( xTimer ) )" 630 * { 631 * // xTimer is already active - delete it. 632 * xTimerDelete( xTimer ); 633 * } 634 * else 635 * { 636 * // xTimer is not active, change its period to 500ms. This will also 637 * // cause the timer to start. Block for a maximum of 100 ticks if the 638 * // change period command cannot immediately be sent to the timer 639 * // command queue. 640 * if( xTimerChangePeriod( xTimer, 500 / portTICK_PERIOD_MS, 100 ) == 641 *pdPASS ) 642 * { 643 * // The command was successfully sent. 644 * } 645 * else 646 * { 647 * // The command could not be sent, even after waiting for 100 648 *ticks 649 * // to pass. Take appropriate action here. 650 * } 651 * } 652 * } 653 * @endverbatim 654 */ 655 #define xTimerChangePeriod(xTimer, xNewPeriod, xTicksToWait) \ 656 xTimerGenericCommand( \ 657 (xTimer), \ 658 tmrCOMMAND_CHANGE_PERIOD, \ 659 (xNewPeriod), \ 660 NULL, \ 661 (xTicksToWait)) 662 663 /** 664 * BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait ); 665 * 666 * Timer functionality is provided by a timer service/daemon task. Many of the 667 * public FreeRTOS timer API functions send commands to the timer service task 668 * through a queue called the timer command queue. The timer command queue is 669 * private to the kernel itself and is not directly accessible to application 670 * code. The length of the timer command queue is set by the 671 * configTIMER_QUEUE_LENGTH configuration constant. 672 * 673 * xTimerDelete() deletes a timer that was previously created using the 674 * xTimerCreate() API function. 675 * 676 * The configUSE_TIMERS configuration constant must be set to 1 for 677 * xTimerDelete() to be available. 678 * 679 * @param xTimer The handle of the timer being deleted. 680 * 681 * @param xTicksToWait Specifies the time, in ticks, that the calling task 682 * should be held in the Blocked state to wait for the delete command to be 683 * successfully sent to the timer command queue, should the queue already be 684 * full when xTimerDelete() was called. xTicksToWait is ignored if 685 * xTimerDelete() is called before the scheduler is started. 686 * 687 * @return pdFAIL will be returned if the delete command could not be sent to 688 * the timer command queue even after xTicksToWait ticks had passed. pdPASS 689 * will be returned if the command was successfully sent to the timer command 690 * queue. When the command is actually processed will depend on the priority of 691 * the timer service/daemon task relative to other tasks in the system. The 692 * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY 693 * configuration constant. 694 * 695 * Example usage: 696 * 697 * See the xTimerChangePeriod() API function example usage scenario. 698 */ 699 #define xTimerDelete(xTimer, xTicksToWait) \ 700 xTimerGenericCommand((xTimer), tmrCOMMAND_DELETE, 0U, NULL, (xTicksToWait)) 701 702 /** 703 * BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait ); 704 * 705 * Timer functionality is provided by a timer service/daemon task. Many of the 706 * public FreeRTOS timer API functions send commands to the timer service task 707 * through a queue called the timer command queue. The timer command queue is 708 * private to the kernel itself and is not directly accessible to application 709 * code. The length of the timer command queue is set by the 710 * configTIMER_QUEUE_LENGTH configuration constant. 711 * 712 * xTimerReset() re-starts a timer that was previously created using the 713 * xTimerCreate() API function. If the timer had already been started and was 714 * already in the active state, then xTimerReset() will cause the timer to 715 * re-evaluate its expiry time so that it is relative to when xTimerReset() was 716 * called. If the timer was in the dormant state then xTimerReset() has 717 * equivalent functionality to the xTimerStart() API function. 718 * 719 * Resetting a timer ensures the timer is in the active state. If the timer 720 * is not stopped, deleted, or reset in the mean time, the callback function 721 * associated with the timer will get called 'n' ticks after xTimerReset() was 722 * called, where 'n' is the timers defined period. 723 * 724 * It is valid to call xTimerReset() before the scheduler has been started, but 725 * when this is done the timer will not actually start until the scheduler is 726 * started, and the timers expiry time will be relative to when the scheduler is 727 * started, not relative to when xTimerReset() was called. 728 * 729 * The configUSE_TIMERS configuration constant must be set to 1 for 730 * xTimerReset() to be available. 731 * 732 * @param xTimer The handle of the timer being reset/started/restarted. 733 * 734 * @param xTicksToWait Specifies the time, in ticks, that the calling task 735 * should be held in the Blocked state to wait for the reset command to be 736 * successfully sent to the timer command queue, should the queue already be 737 * full when xTimerReset() was called. xTicksToWait is ignored if xTimerReset() 738 * is called before the scheduler is started. 739 * 740 * @return pdFAIL will be returned if the reset command could not be sent to 741 * the timer command queue even after xTicksToWait ticks had passed. pdPASS 742 * will be returned if the command was successfully sent to the timer command 743 * queue. When the command is actually processed will depend on the priority of 744 * the timer service/daemon task relative to other tasks in the system, although 745 * the timers expiry time is relative to when xTimerStart() is actually called. 746 * The timer service/daemon task priority is set by the 747 * configTIMER_TASK_PRIORITY configuration constant. 748 * 749 * Example usage: 750 * @verbatim 751 * // When a key is pressed, an LCD back-light is switched on. If 5 seconds 752 * pass 753 * // without a key being pressed, then the LCD back-light is switched off. In 754 * // this case, the timer is a one-shot timer. 755 * 756 * TimerHandle_t xBacklightTimer = NULL; 757 * 758 * // The callback function assigned to the one-shot timer. In this case the 759 * // parameter is not used. 760 * void vBacklightTimerCallback( TimerHandle_t pxTimer ) 761 * { 762 * // The timer expired, therefore 5 seconds must have passed since a key 763 * // was pressed. Switch off the LCD back-light. 764 * vSetBacklightState( BACKLIGHT_OFF ); 765 * } 766 * 767 * // The key press event handler. 768 * void vKeyPressEventHandler( char cKey ) 769 * { 770 * // Ensure the LCD back-light is on, then reset the timer that is 771 * // responsible for turning the back-light off after 5 seconds of 772 * // key inactivity. Wait 10 ticks for the command to be successfully sent 773 * // if it cannot be sent immediately. 774 * vSetBacklightState( BACKLIGHT_ON ); 775 * if( xTimerReset( xBacklightTimer, 100 ) != pdPASS ) 776 * { 777 * // The reset command was not executed successfully. Take appropriate 778 * // action here. 779 * } 780 * 781 * // Perform the rest of the key processing here. 782 * } 783 * 784 * void main( void ) 785 * { 786 * int32_t x; 787 * 788 * // Create then start the one-shot timer that is responsible for turning 789 * // the back-light off if no keys are pressed within a 5 second period. 790 * xBacklightTimer = xTimerCreate( "BacklightTimer", // Just a 791 * text name, not used by the kernel. ( 5000 / portTICK_PERIOD_MS), // The timer 792 * period in ticks. pdFALSE, // The timer is a one-shot 793 * timer. 0, // The id is not used by the callback so 794 * can take any value. vBacklightTimerCallback // The callback function that 795 * switches the LCD back-light off. 796 * ); 797 * 798 * if( xBacklightTimer == NULL ) 799 * { 800 * // The timer was not created. 801 * } 802 * else 803 * { 804 * // Start the timer. No block time is specified, and even if one was 805 * // it would be ignored because the scheduler has not yet been 806 * // started. 807 * if( xTimerStart( xBacklightTimer, 0 ) != pdPASS ) 808 * { 809 * // The timer could not be set into the Active state. 810 * } 811 * } 812 * 813 * // ... 814 * // Create tasks here. 815 * // ... 816 * 817 * // Starting the scheduler will start the timer running as it has already 818 * // been set into the active state. 819 * vTaskStartScheduler(); 820 * 821 * // Should not reach here. 822 * for( ;; ); 823 * } 824 * @endverbatim 825 */ 826 #define xTimerReset(xTimer, xTicksToWait) \ 827 xTimerGenericCommand( \ 828 (xTimer), \ 829 tmrCOMMAND_RESET, \ 830 (xTaskGetTickCount()), \ 831 NULL, \ 832 (xTicksToWait)) 833 834 /** 835 * BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, 836 * BaseType_t *pxHigherPriorityTaskWoken ); 837 * 838 * A version of xTimerStart() that can be called from an interrupt service 839 * routine. 840 * 841 * @param xTimer The handle of the timer being started/restarted. 842 * 843 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most 844 * of its time in the Blocked state, waiting for messages to arrive on the timer 845 * command queue. Calling xTimerStartFromISR() writes a message to the timer 846 * command queue, so has the potential to transition the timer service/daemon 847 * task out of the Blocked state. If calling xTimerStartFromISR() causes the 848 * timer service/daemon task to leave the Blocked state, and the timer service/ 849 * daemon task has a priority equal to or greater than the currently executing 850 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will 851 * get set to pdTRUE internally within the xTimerStartFromISR() function. If 852 * xTimerStartFromISR() sets this value to pdTRUE then a context switch should 853 * be performed before the interrupt exits. 854 * 855 * @return pdFAIL will be returned if the start command could not be sent to 856 * the timer command queue. pdPASS will be returned if the command was 857 * successfully sent to the timer command queue. When the command is actually 858 * processed will depend on the priority of the timer service/daemon task 859 * relative to other tasks in the system, although the timers expiry time is 860 * relative to when xTimerStartFromISR() is actually called. The timer 861 * service/daemon task priority is set by the configTIMER_TASK_PRIORITY 862 * configuration constant. 863 * 864 * Example usage: 865 * @verbatim 866 * // This scenario assumes xBacklightTimer has already been created. When a 867 * // key is pressed, an LCD back-light is switched on. If 5 seconds pass 868 * // without a key being pressed, then the LCD back-light is switched off. In 869 * // this case, the timer is a one-shot timer, and unlike the example given for 870 * // the xTimerReset() function, the key press event handler is an interrupt 871 * // service routine. 872 * 873 * // The callback function assigned to the one-shot timer. In this case the 874 * // parameter is not used. 875 * void vBacklightTimerCallback( TimerHandle_t pxTimer ) 876 * { 877 * // The timer expired, therefore 5 seconds must have passed since a key 878 * // was pressed. Switch off the LCD back-light. 879 * vSetBacklightState( BACKLIGHT_OFF ); 880 * } 881 * 882 * // The key press interrupt service routine. 883 * void vKeyPressEventInterruptHandler( void ) 884 * { 885 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; 886 * 887 * // Ensure the LCD back-light is on, then restart the timer that is 888 * // responsible for turning the back-light off after 5 seconds of 889 * // key inactivity. This is an interrupt service routine so can only 890 * // call FreeRTOS API functions that end in "FromISR". 891 * vSetBacklightState( BACKLIGHT_ON ); 892 * 893 * // xTimerStartFromISR() or xTimerResetFromISR() could be called here 894 * // as both cause the timer to re-calculate its expiry time. 895 * // xHigherPriorityTaskWoken was initialised to pdFALSE when it was 896 * // declared (in this function). 897 * if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != 898 *pdPASS ) 899 * { 900 * // The start command was not executed successfully. Take appropriate 901 * // action here. 902 * } 903 * 904 * // Perform the rest of the key processing here. 905 * 906 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch 907 * // should be performed. The syntax required to perform a context switch 908 * // from inside an ISR varies from port to port, and from compiler to 909 * // compiler. Inspect the demos for the port you are using to find the 910 * // actual syntax required. 911 * if( xHigherPriorityTaskWoken != pdFALSE ) 912 * { 913 * // Call the interrupt safe yield function here (actual function 914 * // depends on the FreeRTOS port being used). 915 * } 916 * } 917 * @endverbatim 918 */ 919 #define xTimerStartFromISR(xTimer, pxHigherPriorityTaskWoken) \ 920 xTimerGenericCommand( \ 921 (xTimer), \ 922 tmrCOMMAND_START_FROM_ISR, \ 923 (xTaskGetTickCountFromISR()), \ 924 (pxHigherPriorityTaskWoken), \ 925 0U) 926 927 /** 928 * BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, 929 * BaseType_t *pxHigherPriorityTaskWoken ); 930 * 931 * A version of xTimerStop() that can be called from an interrupt service 932 * routine. 933 * 934 * @param xTimer The handle of the timer being stopped. 935 * 936 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most 937 * of its time in the Blocked state, waiting for messages to arrive on the timer 938 * command queue. Calling xTimerStopFromISR() writes a message to the timer 939 * command queue, so has the potential to transition the timer service/daemon 940 * task out of the Blocked state. If calling xTimerStopFromISR() causes the 941 * timer service/daemon task to leave the Blocked state, and the timer service/ 942 * daemon task has a priority equal to or greater than the currently executing 943 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will 944 * get set to pdTRUE internally within the xTimerStopFromISR() function. If 945 * xTimerStopFromISR() sets this value to pdTRUE then a context switch should 946 * be performed before the interrupt exits. 947 * 948 * @return pdFAIL will be returned if the stop command could not be sent to 949 * the timer command queue. pdPASS will be returned if the command was 950 * successfully sent to the timer command queue. When the command is actually 951 * processed will depend on the priority of the timer service/daemon task 952 * relative to other tasks in the system. The timer service/daemon task 953 * priority is set by the configTIMER_TASK_PRIORITY configuration constant. 954 * 955 * Example usage: 956 * @verbatim 957 * // This scenario assumes xTimer has already been created and started. When 958 * // an interrupt occurs, the timer should be simply stopped. 959 * 960 * // The interrupt service routine that stops the timer. 961 * void vAnExampleInterruptServiceRoutine( void ) 962 * { 963 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; 964 * 965 * // The interrupt has occurred - simply stop the timer. 966 * // xHigherPriorityTaskWoken was set to pdFALSE where it was defined 967 * // (within this function). As this is an interrupt service routine, only 968 * // FreeRTOS API functions that end in "FromISR" can be used. 969 * if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS ) 970 * { 971 * // The stop command was not executed successfully. Take appropriate 972 * // action here. 973 * } 974 * 975 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch 976 * // should be performed. The syntax required to perform a context switch 977 * // from inside an ISR varies from port to port, and from compiler to 978 * // compiler. Inspect the demos for the port you are using to find the 979 * // actual syntax required. 980 * if( xHigherPriorityTaskWoken != pdFALSE ) 981 * { 982 * // Call the interrupt safe yield function here (actual function 983 * // depends on the FreeRTOS port being used). 984 * } 985 * } 986 * @endverbatim 987 */ 988 #define xTimerStopFromISR(xTimer, pxHigherPriorityTaskWoken) \ 989 xTimerGenericCommand( \ 990 (xTimer), \ 991 tmrCOMMAND_STOP_FROM_ISR, \ 992 0, \ 993 (pxHigherPriorityTaskWoken), \ 994 0U) 995 996 /** 997 * BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer, 998 * TickType_t xNewPeriod, 999 * BaseType_t *pxHigherPriorityTaskWoken 1000 *); 1001 * 1002 * A version of xTimerChangePeriod() that can be called from an interrupt 1003 * service routine. 1004 * 1005 * @param xTimer The handle of the timer that is having its period changed. 1006 * 1007 * @param xNewPeriod The new period for xTimer. Timer periods are specified in 1008 * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a 1009 *time that has been specified in milliseconds. For example, if the timer must 1010 * expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively, 1011 * if the timer must expire after 500ms, then xNewPeriod can be set to 1012 * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than 1013 * or equal to 1000. 1014 * 1015 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most 1016 * of its time in the Blocked state, waiting for messages to arrive on the timer 1017 * command queue. Calling xTimerChangePeriodFromISR() writes a message to the 1018 * timer command queue, so has the potential to transition the timer service/ 1019 * daemon task out of the Blocked state. If calling xTimerChangePeriodFromISR() 1020 * causes the timer service/daemon task to leave the Blocked state, and the 1021 * timer service/daemon task has a priority equal to or greater than the 1022 * currently executing task (the task that was interrupted), then 1023 * *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the 1024 * xTimerChangePeriodFromISR() function. If xTimerChangePeriodFromISR() sets 1025 * this value to pdTRUE then a context switch should be performed before the 1026 * interrupt exits. 1027 * 1028 * @return pdFAIL will be returned if the command to change the timers period 1029 * could not be sent to the timer command queue. pdPASS will be returned if the 1030 * command was successfully sent to the timer command queue. When the command 1031 * is actually processed will depend on the priority of the timer service/daemon 1032 * task relative to other tasks in the system. The timer service/daemon task 1033 * priority is set by the configTIMER_TASK_PRIORITY configuration constant. 1034 * 1035 * Example usage: 1036 * @verbatim 1037 * // This scenario assumes xTimer has already been created and started. When 1038 * // an interrupt occurs, the period of xTimer should be changed to 500ms. 1039 * 1040 * // The interrupt service routine that changes the period of xTimer. 1041 * void vAnExampleInterruptServiceRoutine( void ) 1042 * { 1043 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; 1044 * 1045 * // The interrupt has occurred - change the period of xTimer to 500ms. 1046 * // xHigherPriorityTaskWoken was set to pdFALSE where it was defined 1047 * // (within this function). As this is an interrupt service routine, only 1048 * // FreeRTOS API functions that end in "FromISR" can be used. 1049 * if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) != 1050 *pdPASS ) 1051 * { 1052 * // The command to change the timers period was not executed 1053 * // successfully. Take appropriate action here. 1054 * } 1055 * 1056 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch 1057 * // should be performed. The syntax required to perform a context switch 1058 * // from inside an ISR varies from port to port, and from compiler to 1059 * // compiler. Inspect the demos for the port you are using to find the 1060 * // actual syntax required. 1061 * if( xHigherPriorityTaskWoken != pdFALSE ) 1062 * { 1063 * // Call the interrupt safe yield function here (actual function 1064 * // depends on the FreeRTOS port being used). 1065 * } 1066 * } 1067 * @endverbatim 1068 */ 1069 #define xTimerChangePeriodFromISR( \ 1070 xTimer, xNewPeriod, pxHigherPriorityTaskWoken) \ 1071 xTimerGenericCommand( \ 1072 (xTimer), \ 1073 tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, \ 1074 (xNewPeriod), \ 1075 (pxHigherPriorityTaskWoken), \ 1076 0U) 1077 1078 /** 1079 * BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, 1080 * BaseType_t *pxHigherPriorityTaskWoken ); 1081 * 1082 * A version of xTimerReset() that can be called from an interrupt service 1083 * routine. 1084 * 1085 * @param xTimer The handle of the timer that is to be started, reset, or 1086 * restarted. 1087 * 1088 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most 1089 * of its time in the Blocked state, waiting for messages to arrive on the timer 1090 * command queue. Calling xTimerResetFromISR() writes a message to the timer 1091 * command queue, so has the potential to transition the timer service/daemon 1092 * task out of the Blocked state. If calling xTimerResetFromISR() causes the 1093 * timer service/daemon task to leave the Blocked state, and the timer service/ 1094 * daemon task has a priority equal to or greater than the currently executing 1095 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will 1096 * get set to pdTRUE internally within the xTimerResetFromISR() function. If 1097 * xTimerResetFromISR() sets this value to pdTRUE then a context switch should 1098 * be performed before the interrupt exits. 1099 * 1100 * @return pdFAIL will be returned if the reset command could not be sent to 1101 * the timer command queue. pdPASS will be returned if the command was 1102 * successfully sent to the timer command queue. When the command is actually 1103 * processed will depend on the priority of the timer service/daemon task 1104 * relative to other tasks in the system, although the timers expiry time is 1105 * relative to when xTimerResetFromISR() is actually called. The timer 1106 *service/daemon task priority is set by the configTIMER_TASK_PRIORITY 1107 *configuration constant. 1108 * 1109 * Example usage: 1110 * @verbatim 1111 * // This scenario assumes xBacklightTimer has already been created. When a 1112 * // key is pressed, an LCD back-light is switched on. If 5 seconds pass 1113 * // without a key being pressed, then the LCD back-light is switched off. In 1114 * // this case, the timer is a one-shot timer, and unlike the example given for 1115 * // the xTimerReset() function, the key press event handler is an interrupt 1116 * // service routine. 1117 * 1118 * // The callback function assigned to the one-shot timer. In this case the 1119 * // parameter is not used. 1120 * void vBacklightTimerCallback( TimerHandle_t pxTimer ) 1121 * { 1122 * // The timer expired, therefore 5 seconds must have passed since a key 1123 * // was pressed. Switch off the LCD back-light. 1124 * vSetBacklightState( BACKLIGHT_OFF ); 1125 * } 1126 * 1127 * // The key press interrupt service routine. 1128 * void vKeyPressEventInterruptHandler( void ) 1129 * { 1130 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; 1131 * 1132 * // Ensure the LCD back-light is on, then reset the timer that is 1133 * // responsible for turning the back-light off after 5 seconds of 1134 * // key inactivity. This is an interrupt service routine so can only 1135 * // call FreeRTOS API functions that end in "FromISR". 1136 * vSetBacklightState( BACKLIGHT_ON ); 1137 * 1138 * // xTimerStartFromISR() or xTimerResetFromISR() could be called here 1139 * // as both cause the timer to re-calculate its expiry time. 1140 * // xHigherPriorityTaskWoken was initialised to pdFALSE when it was 1141 * // declared (in this function). 1142 * if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != 1143 *pdPASS ) 1144 * { 1145 * // The reset command was not executed successfully. Take appropriate 1146 * // action here. 1147 * } 1148 * 1149 * // Perform the rest of the key processing here. 1150 * 1151 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch 1152 * // should be performed. The syntax required to perform a context switch 1153 * // from inside an ISR varies from port to port, and from compiler to 1154 * // compiler. Inspect the demos for the port you are using to find the 1155 * // actual syntax required. 1156 * if( xHigherPriorityTaskWoken != pdFALSE ) 1157 * { 1158 * // Call the interrupt safe yield function here (actual function 1159 * // depends on the FreeRTOS port being used). 1160 * } 1161 * } 1162 * @endverbatim 1163 */ 1164 #define xTimerResetFromISR(xTimer, pxHigherPriorityTaskWoken) \ 1165 xTimerGenericCommand( \ 1166 (xTimer), \ 1167 tmrCOMMAND_RESET_FROM_ISR, \ 1168 (xTaskGetTickCountFromISR()), \ 1169 (pxHigherPriorityTaskWoken), \ 1170 0U) 1171 1172 /** 1173 * BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, 1174 * void *pvParameter1, 1175 * uint32_t ulParameter2, 1176 * BaseType_t 1177 **pxHigherPriorityTaskWoken ); 1178 * 1179 * 1180 * Used from application interrupt service routines to defer the execution of a 1181 * function to the RTOS daemon task (the timer service task, hence this function 1182 * is implemented in timers.c and is prefixed with 'Timer'). 1183 * 1184 * Ideally an interrupt service routine (ISR) is kept as short as possible, but 1185 * sometimes an ISR either has a lot of processing to do, or needs to perform 1186 * processing that is not deterministic. In these cases 1187 * xTimerPendFunctionCallFromISR() can be used to defer processing of a function 1188 * to the RTOS daemon task. 1189 * 1190 * A mechanism is provided that allows the interrupt to return directly to the 1191 * task that will subsequently execute the pended callback function. This 1192 * allows the callback function to execute contiguously in time with the 1193 * interrupt - just as if the callback had executed in the interrupt itself. 1194 * 1195 * @param xFunctionToPend The function to execute from the timer service/ 1196 * daemon task. The function must conform to the PendedFunction_t 1197 * prototype. 1198 * 1199 * @param pvParameter1 The value of the callback function's first parameter. 1200 * The parameter has a void * type to allow it to be used to pass any type. 1201 * For example, unsigned longs can be cast to a void *, or the void * can be 1202 * used to point to a structure. 1203 * 1204 * @param ulParameter2 The value of the callback function's second parameter. 1205 * 1206 * @param pxHigherPriorityTaskWoken As mentioned above, calling this function 1207 * will result in a message being sent to the timer daemon task. If the 1208 * priority of the timer daemon task (which is set using 1209 * configTIMER_TASK_PRIORITY in FreeRTOSConfig.h) is higher than the priority of 1210 * the currently running task (the task the interrupt interrupted) then 1211 * *pxHigherPriorityTaskWoken will be set to pdTRUE within 1212 * xTimerPendFunctionCallFromISR(), indicating that a context switch should be 1213 * requested before the interrupt exits. For that reason 1214 * *pxHigherPriorityTaskWoken must be initialised to pdFALSE. See the 1215 * example code below. 1216 * 1217 * @return pdPASS is returned if the message was successfully sent to the 1218 * timer daemon task, otherwise pdFALSE is returned. 1219 * 1220 * Example usage: 1221 * @verbatim 1222 * 1223 * // The callback function that will execute in the context of the daemon 1224 *task. 1225 * // Note callback functions must all use this same prototype. 1226 * void vProcessInterface( void *pvParameter1, uint32_t ulParameter2 ) 1227 * { 1228 * BaseType_t xInterfaceToService; 1229 * 1230 * // The interface that requires servicing is passed in the second 1231 * // parameter. The first parameter is not used in this case. 1232 * xInterfaceToService = ( BaseType_t ) ulParameter2; 1233 * 1234 * // ...Perform the processing here... 1235 * } 1236 * 1237 * // An ISR that receives data packets from multiple interfaces 1238 * void vAnISR( void ) 1239 * { 1240 * BaseType_t xInterfaceToService, xHigherPriorityTaskWoken; 1241 * 1242 * // Query the hardware to determine which interface needs processing. 1243 * xInterfaceToService = prvCheckInterfaces(); 1244 * 1245 * // The actual processing is to be deferred to a task. Request the 1246 * // vProcessInterface() callback function is executed, passing in the 1247 * // number of the interface that needs processing. The interface to 1248 * // service is passed in the second parameter. The first parameter is 1249 * // not used in this case. 1250 * xHigherPriorityTaskWoken = pdFALSE; 1251 * xTimerPendFunctionCallFromISR( vProcessInterface, NULL, ( uint32_t ) 1252 *xInterfaceToService, &xHigherPriorityTaskWoken ); 1253 * 1254 * // If xHigherPriorityTaskWoken is now set to pdTRUE then a context 1255 * // switch should be requested. The macro used is port specific and will 1256 * // be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to 1257 * // the documentation page for the port being used. 1258 * portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); 1259 * 1260 * } 1261 * @endverbatim 1262 */ 1263 BaseType_t xTimerPendFunctionCallFromISR( 1264 PendedFunction_t xFunctionToPend, 1265 void *pvParameter1, 1266 uint32_t ulParameter2, 1267 BaseType_t *pxHigherPriorityTaskWoken) PRIVILEGED_FUNCTION; 1268 1269 /** 1270 * BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, 1271 * void *pvParameter1, 1272 * uint32_t ulParameter2, 1273 * TickType_t xTicksToWait ); 1274 * 1275 * 1276 * Used to defer the execution of a function to the RTOS daemon task (the timer 1277 * service task, hence this function is implemented in timers.c and is prefixed 1278 * with 'Timer'). 1279 * 1280 * @param xFunctionToPend The function to execute from the timer service/ 1281 * daemon task. The function must conform to the PendedFunction_t 1282 * prototype. 1283 * 1284 * @param pvParameter1 The value of the callback function's first parameter. 1285 * The parameter has a void * type to allow it to be used to pass any type. 1286 * For example, unsigned longs can be cast to a void *, or the void * can be 1287 * used to point to a structure. 1288 * 1289 * @param ulParameter2 The value of the callback function's second parameter. 1290 * 1291 * @param xTicksToWait Calling this function will result in a message being 1292 * sent to the timer daemon task on a queue. xTicksToWait is the amount of 1293 * time the calling task should remain in the Blocked state (so not using any 1294 * processing time) for space to become available on the timer queue if the 1295 * queue is found to be full. 1296 * 1297 * @return pdPASS is returned if the message was successfully sent to the 1298 * timer daemon task, otherwise pdFALSE is returned. 1299 * 1300 */ 1301 BaseType_t xTimerPendFunctionCall( 1302 PendedFunction_t xFunctionToPend, 1303 void *pvParameter1, 1304 uint32_t ulParameter2, 1305 TickType_t xTicksToWait) PRIVILEGED_FUNCTION; 1306 1307 /** 1308 * const char * const pcTimerGetName( TimerHandle_t xTimer ); 1309 * 1310 * Returns the name that was assigned to a timer when the timer was created. 1311 * 1312 * @param xTimer The handle of the timer being queried. 1313 * 1314 * @return The name assigned to the timer specified by the xTimer parameter. 1315 */ 1316 const char *pcTimerGetName(TimerHandle_t xTimer) 1317 PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for 1318 strings and single characters only. */ 1319 1320 /** 1321 * void vTimerSetReloadMode( TimerHandle_t xTimer, const UBaseType_t 1322 * uxAutoReload ); 1323 * 1324 * Updates a timer to be either an auto-reload timer, in which case the timer 1325 * automatically resets itself each time it expires, or a one-shot timer, in 1326 * which case the timer will only expire once unless it is manually restarted. 1327 * 1328 * @param xTimer The handle of the timer being updated. 1329 * 1330 * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will 1331 * expire repeatedly with a frequency set by the timer's period (see the 1332 * xTimerPeriodInTicks parameter of the xTimerCreate() API function). If 1333 * uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and 1334 * enter the dormant state after it expires. 1335 */ 1336 void vTimerSetReloadMode(TimerHandle_t xTimer, const UBaseType_t uxAutoReload) 1337 PRIVILEGED_FUNCTION; 1338 1339 /** 1340 * UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer ); 1341 * 1342 * Queries a timer to determine if it is an auto-reload timer, in which case the 1343 * timer automatically resets itself each time it expires, or a one-shot timer, 1344 * in which case the timer will only expire once unless it is manually 1345 * restarted. 1346 * 1347 * @param xTimer The handle of the timer being queried. 1348 * 1349 * @return If the timer is an auto-reload timer then pdTRUE is returned, 1350 * otherwise pdFALSE is returned. 1351 */ 1352 UBaseType_t uxTimerGetReloadMode(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; 1353 1354 /** 1355 * TickType_t xTimerGetPeriod( TimerHandle_t xTimer ); 1356 * 1357 * Returns the period of a timer. 1358 * 1359 * @param xTimer The handle of the timer being queried. 1360 * 1361 * @return The period of the timer in ticks. 1362 */ 1363 TickType_t xTimerGetPeriod(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; 1364 1365 /** 1366 * TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ); 1367 * 1368 * Returns the time in ticks at which the timer will expire. If this is less 1369 * than the current tick count then the expiry time has overflowed from the 1370 * current time. 1371 * 1372 * @param xTimer The handle of the timer being queried. 1373 * 1374 * @return If the timer is running then the time in ticks at which the timer 1375 * will next expire is returned. If the timer is not running then the return 1376 * value is undefined. 1377 */ 1378 TickType_t xTimerGetExpiryTime(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; 1379 1380 /* 1381 * Functions beyond this part are not part of the public API and are intended 1382 * for use by the kernel only. 1383 */ 1384 BaseType_t xTimerCreateTimerTask(void) PRIVILEGED_FUNCTION; 1385 BaseType_t xTimerGenericCommand( 1386 TimerHandle_t xTimer, 1387 const BaseType_t xCommandID, 1388 const TickType_t xOptionalValue, 1389 BaseType_t *const pxHigherPriorityTaskWoken, 1390 const TickType_t xTicksToWait) PRIVILEGED_FUNCTION; 1391 1392 #if (configUSE_TRACE_FACILITY == 1) 1393 void vTimerSetTimerNumber(TimerHandle_t xTimer, UBaseType_t uxTimerNumber) 1394 PRIVILEGED_FUNCTION; 1395 UBaseType_t uxTimerGetTimerNumber(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; 1396 #endif 1397 1398 #ifdef __cplusplus 1399 } 1400 #endif 1401 #endif /* TIMERS_H */ 1402