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