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