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