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