1 /* 2 * FreeRTOS Kernel V10.4.3 3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a copy of 6 * this software and associated documentation files (the "Software"), to deal in 7 * the Software without restriction, including without limitation the rights to 8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 * the Software, and to permit persons to whom the Software is furnished to do so, 10 * subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be included in all 13 * copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 * 22 * https://www.FreeRTOS.org 23 * https://github.com/FreeRTOS 24 * 25 */ 26 27 28 #ifndef INC_TASK_H 29 #define INC_TASK_H 30 31 #ifndef INC_FREERTOS_H 32 #error "include FreeRTOS.h must appear in source files before include task.h" 33 #endif 34 35 #include "list.h" 36 #ifdef ESP_PLATFORM // IDF-3793 37 #include "freertos/portmacro.h" 38 #endif // ESP_PLATFORM 39 40 /* *INDENT-OFF* */ 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 /* *INDENT-ON* */ 45 46 /*----------------------------------------------------------- 47 * MACROS AND DEFINITIONS 48 *----------------------------------------------------------*/ 49 50 #define tskKERNEL_VERSION_NUMBER "V10.4.3" 51 #define tskKERNEL_VERSION_MAJOR 10 52 #define tskKERNEL_VERSION_MINOR 4 53 #define tskKERNEL_VERSION_BUILD 3 54 55 /* MPU region parameters passed in ulParameters 56 * of MemoryRegion_t struct. */ 57 #define tskMPU_REGION_READ_ONLY ( 1UL << 0UL ) 58 #define tskMPU_REGION_READ_WRITE ( 1UL << 1UL ) 59 #define tskMPU_REGION_EXECUTE_NEVER ( 1UL << 2UL ) 60 #define tskMPU_REGION_NORMAL_MEMORY ( 1UL << 3UL ) 61 #define tskMPU_REGION_DEVICE_MEMORY ( 1UL << 4UL ) 62 63 /* The direct to task notification feature used to have only a single notification 64 * per task. Now there is an array of notifications per task that is dimensioned by 65 * configTASK_NOTIFICATION_ARRAY_ENTRIES. For backward compatibility, any use of the 66 * original direct to task notification defaults to using the first index in the 67 * array. */ 68 #define tskDEFAULT_INDEX_TO_NOTIFY ( 0 ) 69 70 #define tskNO_AFFINITY ( 0x7FFFFFFF ) 71 72 /** 73 * task. h 74 * 75 * Type by which tasks are referenced. For example, a call to xTaskCreate 76 * returns (via a pointer parameter) an TaskHandle_t variable that can then 77 * be used as a parameter to vTaskDelete to delete the task. 78 * 79 * @cond !DOC_SINGLE_GROUP 80 * \defgroup TaskHandle_t TaskHandle_t 81 * @endcond 82 * \ingroup Tasks 83 */ 84 struct tskTaskControlBlock; /* The old naming convention is used to prevent breaking kernel aware debuggers. */ 85 #ifdef ESP_PLATFORM // IDF-3769 86 typedef void* TaskHandle_t; 87 #else 88 typedef struct tskTaskControlBlock* TaskHandle_t; 89 #endif // ESP_PLATFORM 90 /** 91 * Defines the prototype to which the application task hook function must 92 * conform. 93 */ 94 typedef BaseType_t (* TaskHookFunction_t)( void * ); 95 96 /** Task states returned by eTaskGetState. */ 97 typedef enum 98 { 99 eRunning = 0, /* A task is querying the state of itself, so must be running. */ 100 eReady, /* The task being queried is in a read or pending ready list. */ 101 eBlocked, /* The task being queried is in the Blocked state. */ 102 eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */ 103 eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */ 104 eInvalid /* Used as an 'invalid state' value. */ 105 } eTaskState; 106 107 /* Actions that can be performed when vTaskNotify() is called. */ 108 typedef enum 109 { 110 eNoAction = 0, /* Notify the task without updating its notify value. */ 111 eSetBits, /* Set bits in the task's notification value. */ 112 eIncrement, /* Increment the task's notification value. */ 113 eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */ 114 eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */ 115 } eNotifyAction; 116 117 /** @cond !DOC_EXCLUDE_HEADER_SECTION */ 118 /** 119 * Used internally only. 120 */ 121 typedef struct xTIME_OUT 122 { 123 BaseType_t xOverflowCount; 124 TickType_t xTimeOnEntering; 125 } TimeOut_t; 126 127 /** 128 * Defines the memory ranges allocated to the task when an MPU is used. 129 */ 130 typedef struct xMEMORY_REGION 131 { 132 void * pvBaseAddress; 133 uint32_t ulLengthInBytes; 134 uint32_t ulParameters; 135 } MemoryRegion_t; 136 137 /* 138 * Parameters required to create an MPU protected task. 139 */ 140 typedef struct xTASK_PARAMETERS 141 { 142 TaskFunction_t pvTaskCode; 143 const char * const pcName; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 144 configSTACK_DEPTH_TYPE usStackDepth; 145 void * pvParameters; 146 UBaseType_t uxPriority; 147 StackType_t * puxStackBuffer; 148 MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ]; 149 #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) ) 150 StaticTask_t * const pxTaskBuffer; 151 #endif 152 } TaskParameters_t; 153 154 /* Used with the uxTaskGetSystemState() function to return the state of each task 155 * in the system. */ 156 typedef struct xTASK_STATUS 157 { 158 TaskHandle_t xHandle; /* The handle of the task to which the rest of the information in the structure relates. */ 159 const char * pcTaskName; /* A pointer to the task's name. This value will be invalid if the task was deleted since the structure was populated! */ /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 160 UBaseType_t xTaskNumber; /* A number unique to the task. */ 161 eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */ 162 UBaseType_t uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */ 163 UBaseType_t uxBasePriority; /* The priority to which the task will return if the task's current priority has been inherited to avoid unbounded priority inversion when obtaining a mutex. Only valid if configUSE_MUTEXES is defined as 1 in FreeRTOSConfig.h. */ 164 uint32_t ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock. See https://www.FreeRTOS.org/rtos-run-time-stats.html. Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */ 165 StackType_t * pxStackBase; /* Points to the lowest address of the task's stack area. */ 166 configSTACK_DEPTH_TYPE usStackHighWaterMark; /* The minimum amount of stack space that has remained for the task since the task was created. The closer this value is to zero the closer the task has come to overflowing its stack. */ 167 #if configTASKLIST_INCLUDE_COREID 168 BaseType_t xCoreID; /*!< Core this task is pinned to (0, 1, or -1 for tskNO_AFFINITY). This field is present if CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID is set. */ 169 #endif 170 } TaskStatus_t; 171 172 /** @endcond */ 173 174 /** 175 * Possible return values for eTaskConfirmSleepModeStatus(). 176 */ 177 typedef enum 178 { 179 eAbortSleep = 0, /* A task has been made ready or a context switch pended since portSUPPORESS_TICKS_AND_SLEEP() was called - abort entering a sleep mode. */ 180 eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */ 181 eNoTasksWaitingTimeout /* No tasks are waiting for a timeout so it is safe to enter a sleep mode that can only be exited by an external interrupt. */ 182 } eSleepModeStatus; 183 184 /** 185 * Defines the priority used by the idle task. This must not be modified. 186 * 187 * \ingroup TaskUtils 188 */ 189 #define tskIDLE_PRIORITY ( ( UBaseType_t ) 0U ) 190 191 /** 192 * @cond !DOC_EXCLUDE_HEADER_SECTION 193 * task. h 194 * @endcond 195 * 196 * Macro for forcing a context switch. 197 * 198 * @cond !DOC_SINGLE_GROUP 199 * \defgroup taskYIELD taskYIELD 200 * @endcond 201 * \ingroup SchedulerControl 202 */ 203 #define taskYIELD() portYIELD() 204 205 /** 206 * @cond !DOC_EXCLUDE_HEADER_SECTION 207 * task. h 208 * @endcond 209 * 210 * Macro to mark the start of a critical code region. Preemptive context 211 * switches cannot occur when in a critical region. 212 * 213 * @note This may alter the stack (depending on the portable implementation) 214 * so must be used with care! 215 * 216 * @cond !DOC_SINGLE_GROUP 217 * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL 218 * @endcond 219 * \ingroup SchedulerControl 220 */ 221 #ifdef ESP_PLATFORM 222 #define taskENTER_CRITICAL( x ) portENTER_CRITICAL( x ) 223 #else 224 #define taskENTER_CRITICAL( ) portENTER_CRITICAL( ) 225 #endif // ESP_PLATFORM 226 #define taskENTER_CRITICAL_FROM_ISR( ) portSET_INTERRUPT_MASK_FROM_ISR() 227 228 #ifdef ESP_PLATFORM 229 #define taskENTER_CRITICAL_ISR( x ) portENTER_CRITICAL_ISR( x ) 230 #else 231 #define taskENTER_CRITICAL_ISR( ) portENTER_CRITICAL_ISR( ) 232 #endif // ESP_PLATFORM 233 234 /** 235 * @cond !DOC_EXCLUDE_HEADER_SECTION 236 * task. h 237 * @endcond 238 * 239 * Macro to mark the end of a critical code region. Preemptive context 240 * switches cannot occur when in a critical region. 241 * 242 * @note This may alter the stack (depending on the portable implementation) 243 * so must be used with care! 244 * 245 * @cond !DOC_SINGLE_GROUP 246 * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL 247 * @endcond 248 * \ingroup SchedulerControl 249 */ 250 251 #ifdef ESP_PLATFORM 252 #define taskEXIT_CRITICAL( x ) portEXIT_CRITICAL( x ) 253 #else 254 #define taskEXIT_CRITICAL( ) portEXIT_CRITICAL( ) 255 #endif // ESP_PLATFORM 256 #define taskEXIT_CRITICAL_FROM_ISR( x ) portCLEAR_INTERRUPT_MASK_FROM_ISR( x ) 257 258 #ifdef ESP_PLATFORM 259 #define taskEXIT_CRITICAL_ISR( x ) portEXIT_CRITICAL_ISR( x ) 260 #else 261 #define taskEXIT_CRITICAL_ISR( ) portEXIT_CRITICAL_ISR( ) 262 #endif // ESP_PLATFORM 263 /** 264 * @cond !DOC_EXCLUDE_HEADER_SECTION 265 * task. h 266 * @endcond 267 * 268 * Macro to disable all maskable interrupts. 269 * 270 * @cond !DOC_SINGLE_GROUP 271 * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS 272 * @endcond 273 * \ingroup SchedulerControl 274 */ 275 #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS() 276 277 /** 278 * @cond !DOC_EXCLUDE_HEADER_SECTION 279 * task. h 280 * @endcond 281 * 282 * Macro to enable microcontroller interrupts. 283 * 284 * @cond !DOC_SINGLE_GROUP 285 * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS 286 * @endcond 287 * \ingroup SchedulerControl 288 */ 289 #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS() 290 291 /* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is 292 * 0 to generate more optimal code when configASSERT() is defined as the constant 293 * is used in assert() statements. */ 294 #define taskSCHEDULER_SUSPENDED ( ( BaseType_t ) 0 ) 295 #define taskSCHEDULER_NOT_STARTED ( ( BaseType_t ) 1 ) 296 #define taskSCHEDULER_RUNNING ( ( BaseType_t ) 2 ) 297 298 299 /*----------------------------------------------------------- 300 * TASK CREATION API 301 *----------------------------------------------------------*/ 302 303 /** 304 * Create a new task with a specified affinity. 305 * 306 * This function is similar to xTaskCreate, but allows setting task affinity 307 * in SMP system. 308 * 309 * @param pvTaskCode Pointer to the task entry function. Tasks 310 * must be implemented to never return (i.e. continuous loop), or should be 311 * terminated using vTaskDelete function. 312 * 313 * @param pcName A descriptive name for the task. This is mainly used to 314 * facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default 315 * is 16. 316 * 317 * @param usStackDepth The size of the task stack specified as the number of 318 * bytes. Note that this differs from vanilla FreeRTOS. 319 * 320 * @param pvParameters Pointer that will be used as the parameter for the task 321 * being created. 322 * 323 * @param uxPriority The priority at which the task should run. Systems that 324 * include MPU support can optionally create tasks in a privileged (system) 325 * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For 326 * example, to create a privileged task at priority 2 the uxPriority parameter 327 * should be set to ( 2 | portPRIVILEGE_BIT ). 328 * 329 * @param pvCreatedTask Used to pass back a handle by which the created task 330 * can be referenced. 331 * 332 * @param xCoreID If the value is tskNO_AFFINITY, the created task is not 333 * pinned to any CPU, and the scheduler can run it on any core available. 334 * Values 0 or 1 indicate the index number of the CPU which the task should 335 * be pinned to. Specifying values larger than (portNUM_PROCESSORS - 1) will 336 * cause the function to fail. 337 * 338 * @return pdPASS if the task was successfully created and added to a ready 339 * list, otherwise an error code defined in the file projdefs.h 340 * 341 * \ingroup Tasks 342 */ 343 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) 344 BaseType_t xTaskCreatePinnedToCore( TaskFunction_t pvTaskCode, 345 const char * const pcName, 346 const uint32_t usStackDepth, 347 void * const pvParameters, 348 UBaseType_t uxPriority, 349 TaskHandle_t * const pvCreatedTask, 350 const BaseType_t xCoreID); 351 352 #endif 353 354 /** 355 * Create a new task and add it to the list of tasks that are ready to run. 356 * 357 * Internally, within the FreeRTOS implementation, tasks use two blocks of 358 * memory. The first block is used to hold the task's data structures. The 359 * second block is used by the task as its stack. If a task is created using 360 * xTaskCreate() then both blocks of memory are automatically dynamically 361 * allocated inside the xTaskCreate() function. (see 362 * https://www.FreeRTOS.org/a00111.html). If a task is created using 363 * xTaskCreateStatic() then the application writer must provide the required 364 * memory. xTaskCreateStatic() therefore allows a task to be created without 365 * using any dynamic memory allocation. 366 * 367 * See xTaskCreateStatic() for a version that does not use any dynamic memory 368 * allocation. 369 * 370 * xTaskCreate() can only be used to create a task that has unrestricted 371 * access to the entire microcontroller memory map. Systems that include MPU 372 * support can alternatively create an MPU constrained task using 373 * xTaskCreateRestricted(). 374 * 375 * @param pvTaskCode Pointer to the task entry function. Tasks 376 * must be implemented to never return (i.e. continuous loop), or should be 377 * terminated using vTaskDelete function. 378 * 379 * @param pcName A descriptive name for the task. This is mainly used to 380 * facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default 381 * is 16. 382 * 383 * @param usStackDepth The size of the task stack specified as the number of 384 * bytes. Note that this differs from vanilla FreeRTOS. 385 * 386 * @param pvParameters Pointer that will be used as the parameter for the task 387 * being created. 388 * 389 * @param uxPriority The priority at which the task should run. Systems that 390 * include MPU support can optionally create tasks in a privileged (system) 391 * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For 392 * example, to create a privileged task at priority 2 the uxPriority parameter 393 * should be set to ( 2 | portPRIVILEGE_BIT ). 394 * 395 * @param pvCreatedTask Used to pass back a handle by which the created task 396 * can be referenced. 397 * 398 * @return pdPASS if the task was successfully created and added to a ready 399 * list, otherwise an error code defined in the file projdefs.h 400 * 401 * @note If program uses thread local variables (ones specified with "__thread" keyword) 402 * then storage for them will be allocated on the task's stack. 403 * 404 * Example usage: 405 * @code{c} 406 * // Task to be created. 407 * void vTaskCode( void * pvParameters ) 408 * { 409 * for( ;; ) 410 * { 411 * // Task code goes here. 412 * } 413 * } 414 * 415 * // Function that creates a task. 416 * void vOtherFunction( void ) 417 * { 418 * static uint8_t ucParameterToPass; 419 * TaskHandle_t xHandle = NULL; 420 * 421 * // Create the task, storing the handle. Note that the passed parameter ucParameterToPass 422 * // must exist for the lifetime of the task, so in this case is declared static. If it was just an 423 * // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time 424 * // the new task attempts to access it. 425 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle ); 426 * configASSERT( xHandle ); 427 * 428 * // Use the handle to delete the task. 429 * if( xHandle != NULL ) 430 * { 431 * vTaskDelete( xHandle ); 432 * } 433 * } 434 * @endcode 435 * @cond !DOC_SINGLE_GROUP 436 * \defgroup xTaskCreate xTaskCreate 437 * @endcond 438 * \ingroup Tasks 439 */ 440 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) 441 xTaskCreate(TaskFunction_t pvTaskCode,const char * const pcName,const uint32_t usStackDepth,void * const pvParameters,UBaseType_t uxPriority,TaskHandle_t * const pxCreatedTask)442 static inline IRAM_ATTR BaseType_t xTaskCreate( 443 TaskFunction_t pvTaskCode, 444 const char * const pcName, /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 445 const uint32_t usStackDepth, 446 void * const pvParameters, 447 UBaseType_t uxPriority, 448 TaskHandle_t * const pxCreatedTask) PRIVILEGED_FUNCTION 449 { 450 return xTaskCreatePinnedToCore( pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask, tskNO_AFFINITY ); 451 } 452 453 #endif 454 455 456 457 458 /** 459 * Create a new task with a specified affinity. 460 * 461 * This function is similar to xTaskCreateStatic, but allows specifying 462 * task affinity in an SMP system. 463 * 464 * @param pvTaskCode Pointer to the task entry function. Tasks 465 * must be implemented to never return (i.e. continuous loop), or should be 466 * terminated using vTaskDelete function. 467 * 468 * @param pcName A descriptive name for the task. This is mainly used to 469 * facilitate debugging. The maximum length of the string is defined by 470 * configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. 471 * 472 * @param ulStackDepth The size of the task stack specified as the number of 473 * bytes. Note that this differs from vanilla FreeRTOS. 474 * 475 * @param pvParameters Pointer that will be used as the parameter for the task 476 * being created. 477 * 478 * @param uxPriority The priority at which the task will run. 479 * 480 * @param pxStackBuffer Must point to a StackType_t array that has at least 481 * ulStackDepth indexes - the array will then be used as the task's stack, 482 * removing the need for the stack to be allocated dynamically. 483 * 484 * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will 485 * then be used to hold the task's data structures, removing the need for the 486 * memory to be allocated dynamically. 487 * 488 * @param xCoreID If the value is tskNO_AFFINITY, the created task is not 489 * pinned to any CPU, and the scheduler can run it on any core available. 490 * Values 0 or 1 indicate the index number of the CPU which the task should 491 * be pinned to. Specifying values larger than (portNUM_PROCESSORS - 1) will 492 * cause the function to fail. 493 * 494 * @return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will 495 * be created and pdPASS is returned. If either pxStackBuffer or pxTaskBuffer 496 * are NULL then the task will not be created and 497 * errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned. 498 * 499 * \ingroup Tasks 500 */ 501 #if( configSUPPORT_STATIC_ALLOCATION == 1 ) 502 TaskHandle_t xTaskCreateStaticPinnedToCore( TaskFunction_t pvTaskCode, 503 const char * const pcName, 504 const uint32_t ulStackDepth, 505 void * const pvParameters, 506 UBaseType_t uxPriority, 507 StackType_t * const pxStackBuffer, 508 StaticTask_t * const pxTaskBuffer, 509 const BaseType_t xCoreID ); 510 #endif /* configSUPPORT_STATIC_ALLOCATION */ 511 512 /** 513 * Create a new task and add it to the list of tasks that are ready to run. 514 * 515 * Internally, within the FreeRTOS implementation, tasks use two blocks of 516 * memory. The first block is used to hold the task's data structures. The 517 * second block is used by the task as its stack. If a task is created using 518 * xTaskCreate() then both blocks of memory are automatically dynamically 519 * allocated inside the xTaskCreate() function. (see 520 * http://www.freertos.org/a00111.html). If a task is created using 521 * xTaskCreateStatic() then the application writer must provide the required 522 * memory. xTaskCreateStatic() therefore allows a task to be created without 523 * using any dynamic memory allocation. 524 * 525 * @param pvTaskCode Pointer to the task entry function. Tasks 526 * must be implemented to never return (i.e. continuous loop), or should be 527 * terminated using vTaskDelete function. 528 * 529 * @param pcName A descriptive name for the task. This is mainly used to 530 * facilitate debugging. The maximum length of the string is defined by 531 * configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. 532 * 533 * @param ulStackDepth The size of the task stack specified as the number of 534 * bytes. Note that this differs from vanilla FreeRTOS. 535 * 536 * @param pvParameters Pointer that will be used as the parameter for the task 537 * being created. 538 * 539 * @param uxPriority The priority at which the task will run. 540 * 541 * @param pxStackBuffer Must point to a StackType_t array that has at least 542 * ulStackDepth indexes - the array will then be used as the task's stack, 543 * removing the need for the stack to be allocated dynamically. 544 * 545 * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will 546 * then be used to hold the task's data structures, removing the need for the 547 * memory to be allocated dynamically. 548 * 549 * @return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will 550 * be created and pdPASS is returned. If either pxStackBuffer or pxTaskBuffer 551 * are NULL then the task will not be created and 552 * errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned. 553 * 554 * @note If program uses thread local variables (ones specified with "__thread" keyword) 555 * then storage for them will be allocated on the task's stack. 556 * 557 * Example usage: 558 * @code{c} 559 * 560 * // Dimensions the buffer that the task being created will use as its stack. 561 * // NOTE: This is the number of bytes the stack will hold, not the number of 562 * // words as found in vanilla FreeRTOS. 563 * #define STACK_SIZE 200 564 * 565 * // Structure that will hold the TCB of the task being created. 566 * StaticTask_t xTaskBuffer; 567 * 568 * // Buffer that the task being created will use as its stack. Note this is 569 * // an array of StackType_t variables. The size of StackType_t is dependent on 570 * // the RTOS port. 571 * StackType_t xStack[ STACK_SIZE ]; 572 * 573 * // Function that implements the task being created. 574 * void vTaskCode( void * pvParameters ) 575 * { 576 * // The parameter value is expected to be 1 as 1 is passed in the 577 * // pvParameters value in the call to xTaskCreateStatic(). 578 * configASSERT( ( uint32_t ) pvParameters == 1UL ); 579 * 580 * for( ;; ) 581 * { 582 * // Task code goes here. 583 * } 584 * } 585 * 586 * // Function that creates a task. 587 * void vOtherFunction( void ) 588 * { 589 * TaskHandle_t xHandle = NULL; 590 * 591 * // Create the task without using any dynamic memory allocation. 592 * xHandle = xTaskCreateStatic( 593 * vTaskCode, // Function that implements the task. 594 * "NAME", // Text name for the task. 595 * STACK_SIZE, // Stack size in bytes, not words. 596 * ( void * ) 1, // Parameter passed into the task. 597 * tskIDLE_PRIORITY,// Priority at which the task is created. 598 * xStack, // Array to use as the task's stack. 599 * &xTaskBuffer ); // Variable to hold the task's data structure. 600 * 601 * // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have 602 * // been created, and xHandle will be the task's handle. Use the handle 603 * // to suspend the task. 604 * vTaskSuspend( xHandle ); 605 * } 606 * @endcode 607 * \ingroup Tasks 608 */ 609 610 #if( configSUPPORT_STATIC_ALLOCATION == 1 ) xTaskCreateStatic(TaskFunction_t pvTaskCode,const char * const pcName,const uint32_t ulStackDepth,void * const pvParameters,UBaseType_t uxPriority,StackType_t * const puxStackBuffer,StaticTask_t * const pxTaskBuffer)611 static inline IRAM_ATTR TaskHandle_t xTaskCreateStatic( 612 TaskFunction_t pvTaskCode, 613 const char * const pcName, /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 614 const uint32_t ulStackDepth, 615 void * const pvParameters, 616 UBaseType_t uxPriority, 617 StackType_t * const puxStackBuffer, 618 StaticTask_t * const pxTaskBuffer) PRIVILEGED_FUNCTION 619 { 620 return xTaskCreateStaticPinnedToCore( pvTaskCode, pcName, ulStackDepth, pvParameters, uxPriority, puxStackBuffer, pxTaskBuffer, tskNO_AFFINITY ); 621 } 622 #endif /* configSUPPORT_STATIC_ALLOCATION */ 623 624 /** 625 * @cond !DOC_EXCLUDE_HEADER_SECTION 626 * task. h 627 * @code{c} 628 * BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask ); 629 * @endcode 630 * @endcond 631 * 632 * Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1. 633 * 634 * xTaskCreateRestricted() should only be used in systems that include an MPU 635 * implementation. 636 * 637 * Create a new task and add it to the list of tasks that are ready to run. 638 * The function parameters define the memory regions and associated access 639 * permissions allocated to the task. 640 * 641 * See xTaskCreateRestrictedStatic() for a version that does not use any 642 * dynamic memory allocation. 643 * 644 * @param pxTaskDefinition Pointer to a structure that contains a member 645 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API 646 * documentation) plus an optional stack buffer and the memory region 647 * definitions. 648 * 649 * @param pxCreatedTask Used to pass back a handle by which the created task 650 * can be referenced. 651 * 652 * return pdPASS if the task was successfully created and added to a ready 653 * list, otherwise an error code defined in the file projdefs.h 654 * 655 * Example usage: 656 * @code{c} 657 * // Create an TaskParameters_t structure that defines the task to be created. 658 * static const TaskParameters_t xCheckTaskParameters = 659 * { 660 * vATask, // pvTaskCode - the function that implements the task. 661 * "ATask", // pcName - just a text name for the task to assist debugging. 662 * 100, // usStackDepth - the stack size DEFINED IN WORDS. 663 * NULL, // pvParameters - passed into the task function as the function parameters. 664 * ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state. 665 * cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack. 666 * 667 * // xRegions - Allocate up to three separate memory regions for access by 668 * // the task, with appropriate access permissions. Different processors have 669 * // different memory alignment requirements - refer to the FreeRTOS documentation 670 * // for full information. 671 * { 672 * // Base address Length Parameters 673 * { cReadWriteArray, 32, portMPU_REGION_READ_WRITE }, 674 * { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY }, 675 * { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE } 676 * } 677 * }; 678 * 679 * int main( void ) 680 * { 681 * TaskHandle_t xHandle; 682 * 683 * // Create a task from the const structure defined above. The task handle 684 * // is requested (the second parameter is not NULL) but in this case just for 685 * // demonstration purposes as its not actually used. 686 * xTaskCreateRestricted( &xRegTest1Parameters, &xHandle ); 687 * 688 * // Start the scheduler. 689 * vTaskStartScheduler(); 690 * 691 * // Will only get here if there was insufficient memory to create the idle 692 * // and/or timer task. 693 * for( ;; ); 694 * } 695 * @endcode 696 * @cond !DOC_SINGLE_GROUP 697 * \defgroup xTaskCreateRestricted xTaskCreateRestricted 698 * @endcond 699 * \ingroup Tasks 700 */ 701 #if ( portUSING_MPU_WRAPPERS == 1 ) 702 BaseType_t xTaskCreateRestricted( const TaskParameters_t * const pxTaskDefinition, 703 TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION; 704 #endif 705 706 /** 707 * @cond !DOC_EXCLUDE_HEADER_SECTION 708 * task. h 709 * @code{c} 710 * BaseType_t xTaskCreateRestrictedStatic( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask ); 711 * @endcode 712 * @endcond 713 * 714 * Only available when configSUPPORT_STATIC_ALLOCATION is set to 1. 715 * 716 * xTaskCreateRestrictedStatic() should only be used in systems that include an 717 * MPU implementation. 718 * 719 * Internally, within the FreeRTOS implementation, tasks use two blocks of 720 * memory. The first block is used to hold the task's data structures. The 721 * second block is used by the task as its stack. If a task is created using 722 * xTaskCreateRestricted() then the stack is provided by the application writer, 723 * and the memory used to hold the task's data structure is automatically 724 * dynamically allocated inside the xTaskCreateRestricted() function. If a task 725 * is created using xTaskCreateRestrictedStatic() then the application writer 726 * must provide the memory used to hold the task's data structures too. 727 * xTaskCreateRestrictedStatic() therefore allows a memory protected task to be 728 * created without using any dynamic memory allocation. 729 * 730 * @param pxTaskDefinition Pointer to a structure that contains a member 731 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API 732 * documentation) plus an optional stack buffer and the memory region 733 * definitions. If configSUPPORT_STATIC_ALLOCATION is set to 1 the structure 734 * contains an additional member, which is used to point to a variable of type 735 * StaticTask_t - which is then used to hold the task's data structure. 736 * 737 * @param pxCreatedTask Used to pass back a handle by which the created task 738 * can be referenced. 739 * 740 * return pdPASS if the task was successfully created and added to a ready 741 * list, otherwise an error code defined in the file projdefs.h 742 * 743 * Example usage: 744 * @code{c} 745 * // Create an TaskParameters_t structure that defines the task to be created. 746 * // The StaticTask_t variable is only included in the structure when 747 * // configSUPPORT_STATIC_ALLOCATION is set to 1. The PRIVILEGED_DATA macro can 748 * // be used to force the variable into the RTOS kernel's privileged data area. 749 * static PRIVILEGED_DATA StaticTask_t xTaskBuffer; 750 * static const TaskParameters_t xCheckTaskParameters = 751 * { 752 * vATask, // pvTaskCode - the function that implements the task. 753 * "ATask", // pcName - just a text name for the task to assist debugging. 754 * 100, // usStackDepth - the stack size DEFINED IN BYTES. 755 * NULL, // pvParameters - passed into the task function as the function parameters. 756 * ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state. 757 * cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack. 758 * 759 * // xRegions - Allocate up to three separate memory regions for access by 760 * // the task, with appropriate access permissions. Different processors have 761 * // different memory alignment requirements - refer to the FreeRTOS documentation 762 * // for full information. 763 * { 764 * // Base address Length Parameters 765 * { cReadWriteArray, 32, portMPU_REGION_READ_WRITE }, 766 * { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY }, 767 * { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE } 768 * } 769 * 770 * &xTaskBuffer; // Holds the task's data structure. 771 * }; 772 * 773 * int main( void ) 774 * { 775 * TaskHandle_t xHandle; 776 * 777 * // Create a task from the const structure defined above. The task handle 778 * // is requested (the second parameter is not NULL) but in this case just for 779 * // demonstration purposes as its not actually used. 780 * xTaskCreateRestricted( &xRegTest1Parameters, &xHandle ); 781 * 782 * // Start the scheduler. 783 * vTaskStartScheduler(); 784 * 785 * // Will only get here if there was insufficient memory to create the idle 786 * // and/or timer task. 787 * for( ;; ); 788 * } 789 * @endcode 790 * @cond !DOC_SINGLE_GROUP 791 * \defgroup xTaskCreateRestrictedStatic xTaskCreateRestrictedStatic 792 * @endcond 793 * \ingroup Tasks 794 */ 795 #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) ) 796 BaseType_t xTaskCreateRestrictedStatic( const TaskParameters_t * const pxTaskDefinition, 797 TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION; 798 #endif 799 800 /** 801 * @cond !DOC_EXCLUDE_HEADER_SECTION 802 * task. h 803 * @code{c} 804 * void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions ); 805 * @endcode 806 * @endcond 807 * 808 * Memory regions are assigned to a restricted task when the task is created by 809 * a call to xTaskCreateRestricted(). These regions can be redefined using 810 * vTaskAllocateMPURegions(). 811 * 812 * @param xTask The handle of the task being updated. 813 * 814 * @param pxRegions A pointer to an MemoryRegion_t structure that contains the 815 * new memory region definitions. 816 * 817 * Example usage: 818 * @code{c} 819 * // Define an array of MemoryRegion_t structures that configures an MPU region 820 * // allowing read/write access for 1024 bytes starting at the beginning of the 821 * // ucOneKByte array. The other two of the maximum 3 definable regions are 822 * // unused so set to zero. 823 * static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] = 824 * { 825 * // Base address Length Parameters 826 * { ucOneKByte, 1024, portMPU_REGION_READ_WRITE }, 827 * { 0, 0, 0 }, 828 * { 0, 0, 0 } 829 * }; 830 * 831 * void vATask( void *pvParameters ) 832 * { 833 * // This task was created such that it has access to certain regions of 834 * // memory as defined by the MPU configuration. At some point it is 835 * // desired that these MPU regions are replaced with that defined in the 836 * // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions() 837 * // for this purpose. NULL is used as the task handle to indicate that this 838 * // function should modify the MPU regions of the calling task. 839 * vTaskAllocateMPURegions( NULL, xAltRegions ); 840 * 841 * // Now the task can continue its function, but from this point on can only 842 * // access its stack and the ucOneKByte array (unless any other statically 843 * // defined or shared regions have been declared elsewhere). 844 * } 845 * @endcode 846 * @cond !DOC_SINGLE_GROUP 847 * \defgroup xTaskCreateRestricted xTaskCreateRestricted 848 * @endcond 849 * \ingroup Tasks 850 */ 851 void vTaskAllocateMPURegions( TaskHandle_t xTask, 852 const MemoryRegion_t * const pxRegions ) PRIVILEGED_FUNCTION; 853 854 /** 855 * @cond !DOC_EXCLUDE_HEADER_SECTION 856 * task. h 857 * @code{c} 858 * void vTaskDelete( TaskHandle_t xTask ); 859 * @endcode 860 * @endcond 861 * 862 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available. 863 * See the configuration section for more information. 864 * 865 * Remove a task from the RTOS real time kernel's management. The task being 866 * deleted will be removed from all ready, blocked, suspended and event lists. 867 * 868 * NOTE: The idle task is responsible for freeing the kernel allocated 869 * memory from tasks that have been deleted. It is therefore important that 870 * the idle task is not starved of microcontroller processing time if your 871 * application makes any calls to vTaskDelete (). Memory allocated by the 872 * task code is not automatically freed, and should be freed before the task 873 * is deleted. 874 * 875 * See the demo application file death.c for sample code that utilises 876 * vTaskDelete (). 877 * 878 * @param xTaskToDelete The handle of the task to be deleted. Passing NULL will 879 * cause the calling task to be deleted. 880 * 881 * Example usage: 882 * @code{c} 883 * void vOtherFunction( void ) 884 * { 885 * TaskHandle_t xHandle; 886 * 887 * // Create the task, storing the handle. 888 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 889 * 890 * // Use the handle to delete the task. 891 * vTaskDelete( xHandle ); 892 * } 893 * @endcode 894 * @cond !DOC_SINGLE_GROUP 895 * \defgroup vTaskDelete vTaskDelete 896 * @endcond 897 * \ingroup Tasks 898 */ 899 void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION; 900 901 /*----------------------------------------------------------- 902 * TASK CONTROL API 903 *----------------------------------------------------------*/ 904 905 /** 906 * @cond !DOC_EXCLUDE_HEADER_SECTION 907 * task. h 908 * @code{c} 909 * void vTaskDelay( const TickType_t xTicksToDelay ); 910 * @endcode 911 * @endcond 912 * 913 * Delay a task for a given number of ticks. The actual time that the 914 * task remains blocked depends on the tick rate. The constant 915 * portTICK_PERIOD_MS can be used to calculate real time from the tick 916 * rate - with the resolution of one tick period. 917 * 918 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available. 919 * See the configuration section for more information. 920 * 921 * 922 * vTaskDelay() specifies a time at which the task wishes to unblock relative to 923 * the time at which vTaskDelay() is called. For example, specifying a block 924 * period of 100 ticks will cause the task to unblock 100 ticks after 925 * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method 926 * of controlling the frequency of a periodic task as the path taken through the 927 * code, as well as other task and interrupt activity, will effect the frequency 928 * at which vTaskDelay() gets called and therefore the time at which the task 929 * next executes. See xTaskDelayUntil() for an alternative API function designed 930 * to facilitate fixed frequency execution. It does this by specifying an 931 * absolute time (rather than a relative time) at which the calling task should 932 * unblock. 933 * 934 * @param xTicksToDelay The amount of time, in tick periods, that 935 * the calling task should block. 936 * 937 * Example usage: 938 * @code{c} 939 * void vTaskFunction( void * pvParameters ) 940 * { 941 * // Block for 500ms. 942 * const TickType_t xDelay = 500 / portTICK_PERIOD_MS; 943 * 944 * for( ;; ) 945 * { 946 * // Simply toggle the LED every 500ms, blocking between each toggle. 947 * vToggleLED(); 948 * vTaskDelay( xDelay ); 949 * } 950 * } 951 * @endcode 952 * 953 * @cond !DOC_SINGLE_GROUP 954 * \defgroup vTaskDelay vTaskDelay 955 * @endcond 956 * \ingroup TaskCtrl 957 */ 958 void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION; 959 960 /** 961 * @cond !DOC_EXCLUDE_HEADER_SECTION 962 * task. h 963 * @code{c} 964 * BaseType_t xTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement ); 965 * @endcode 966 * @endcond 967 * 968 * INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available. 969 * See the configuration section for more information. 970 * 971 * Delay a task until a specified time. This function can be used by periodic 972 * tasks to ensure a constant execution frequency. 973 * 974 * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will 975 * cause a task to block for the specified number of ticks from the time vTaskDelay () is 976 * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed 977 * execution frequency as the time between a task starting to execute and that task 978 * calling vTaskDelay () may not be fixed [the task may take a different path though the 979 * code between calls, or may get interrupted or preempted a different number of times 980 * each time it executes]. 981 * 982 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function 983 * is called, xTaskDelayUntil () specifies the absolute (exact) time at which it wishes to 984 * unblock. 985 * 986 * The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a 987 * time specified in milliseconds with a resolution of one tick period. 988 * 989 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the 990 * task was last unblocked. The variable must be initialised with the current time 991 * prior to its first use (see the example below). Following this the variable is 992 * automatically updated within xTaskDelayUntil (). 993 * 994 * @param xTimeIncrement The cycle time period. The task will be unblocked at 995 * time *pxPreviousWakeTime + xTimeIncrement. Calling xTaskDelayUntil with the 996 * same xTimeIncrement parameter value will cause the task to execute with 997 * a fixed interface period. 998 * 999 * @return Value which can be used to check whether the task was actually delayed. 1000 * Will be pdTRUE if the task way delayed and pdFALSE otherwise. A task will not 1001 * be delayed if the next expected wake time is in the past. 1002 * 1003 * Example usage: 1004 * @code{c} 1005 * // Perform an action every 10 ticks. 1006 * void vTaskFunction( void * pvParameters ) 1007 * { 1008 * TickType_t xLastWakeTime; 1009 * const TickType_t xFrequency = 10; 1010 * BaseType_t xWasDelayed; 1011 * 1012 * // Initialise the xLastWakeTime variable with the current time. 1013 * xLastWakeTime = xTaskGetTickCount (); 1014 * for( ;; ) 1015 * { 1016 * // Wait for the next cycle. 1017 * xWasDelayed = xTaskDelayUntil( &xLastWakeTime, xFrequency ); 1018 * 1019 * // Perform action here. xWasDelayed value can be used to determine 1020 * // whether a deadline was missed if the code here took too long. 1021 * } 1022 * } 1023 * @endcode 1024 * @cond !DOC_SINGLE_GROUP 1025 * \defgroup xTaskDelayUntil xTaskDelayUntil 1026 * @endcond 1027 * \ingroup TaskCtrl 1028 */ 1029 BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime, 1030 const TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION; 1031 1032 /* 1033 * vTaskDelayUntil() is the older version of xTaskDelayUntil() and does not 1034 * return a value. 1035 */ 1036 #define vTaskDelayUntil( pxPreviousWakeTime, xTimeIncrement ) \ 1037 { \ 1038 ( void ) xTaskDelayUntil( pxPreviousWakeTime, xTimeIncrement ); \ 1039 } 1040 1041 1042 /** 1043 * @cond !DOC_EXCLUDE_HEADER_SECTION 1044 * task. h 1045 * @code{c} 1046 * BaseType_t xTaskAbortDelay( TaskHandle_t xTask ); 1047 * @endcode 1048 * @endcond 1049 * 1050 * INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this 1051 * function to be available. 1052 * 1053 * A task will enter the Blocked state when it is waiting for an event. The 1054 * event it is waiting for can be a temporal event (waiting for a time), such 1055 * as when vTaskDelay() is called, or an event on an object, such as when 1056 * xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task 1057 * that is in the Blocked state is used in a call to xTaskAbortDelay() then the 1058 * task will leave the Blocked state, and return from whichever function call 1059 * placed the task into the Blocked state. 1060 * 1061 * There is no 'FromISR' version of this function as an interrupt would need to 1062 * know which object a task was blocked on in order to know which actions to 1063 * take. For example, if the task was blocked on a queue the interrupt handler 1064 * would then need to know if the queue was locked. 1065 * 1066 * @param xTask The handle of the task to remove from the Blocked state. 1067 * 1068 * @return If the task referenced by xTask was not in the Blocked state then 1069 * pdFAIL is returned. Otherwise pdPASS is returned. 1070 * 1071 * @cond !DOC_SINGLE_GROUP 1072 * \defgroup xTaskAbortDelay xTaskAbortDelay 1073 * @endcond 1074 * \ingroup TaskCtrl 1075 */ 1076 BaseType_t xTaskAbortDelay( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1077 1078 /** 1079 * @cond !DOC_EXCLUDE_HEADER_SECTION 1080 * task. h 1081 * @code{c} 1082 * UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask ); 1083 * @endcode 1084 * @endcond 1085 * 1086 * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. 1087 * See the configuration section for more information. 1088 * 1089 * Obtain the priority of any task. 1090 * 1091 * @param xTask Handle of the task to be queried. Passing a NULL 1092 * handle results in the priority of the calling task being returned. 1093 * 1094 * @return The priority of xTask. 1095 * 1096 * Example usage: 1097 * @code{c} 1098 * void vAFunction( void ) 1099 * { 1100 * TaskHandle_t xHandle; 1101 * 1102 * // Create a task, storing the handle. 1103 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 1104 * 1105 * // ... 1106 * 1107 * // Use the handle to obtain the priority of the created task. 1108 * // It was created with tskIDLE_PRIORITY, but may have changed 1109 * // it itself. 1110 * if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY ) 1111 * { 1112 * // The task has changed it's priority. 1113 * } 1114 * 1115 * // ... 1116 * 1117 * // Is our priority higher than the created task? 1118 * if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) ) 1119 * { 1120 * // Our priority (obtained using NULL handle) is higher. 1121 * } 1122 * } 1123 * @endcode 1124 * @cond !DOC_SINGLE_GROUP 1125 * \defgroup uxTaskPriorityGet uxTaskPriorityGet 1126 * @endcond 1127 * \ingroup TaskCtrl 1128 */ 1129 UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1130 1131 /** 1132 * @cond !DOC_EXCLUDE_HEADER_SECTION 1133 * task. h 1134 * @code{c} 1135 * UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask ); 1136 * @endcode 1137 * @endcond 1138 * 1139 * A version of uxTaskPriorityGet() that can be used from an ISR. 1140 */ 1141 UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1142 1143 /** 1144 * @cond !DOC_EXCLUDE_HEADER_SECTION 1145 * task. h 1146 * @code{c} 1147 * eTaskState eTaskGetState( TaskHandle_t xTask ); 1148 * @endcode 1149 * @endcond 1150 * 1151 * INCLUDE_eTaskGetState must be defined as 1 for this function to be available. 1152 * See the configuration section for more information. 1153 * 1154 * Obtain the state of any task. States are encoded by the eTaskState 1155 * enumerated type. 1156 * 1157 * @param xTask Handle of the task to be queried. 1158 * 1159 * @return The state of xTask at the time the function was called. Note the 1160 * state of the task might change between the function being called, and the 1161 * functions return value being tested by the calling task. 1162 */ 1163 eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1164 1165 /** 1166 * @cond !DOC_EXCLUDE_HEADER_SECTION 1167 * task. h 1168 * @code{c} 1169 * void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState ); 1170 * @endcode 1171 * @endcond 1172 * 1173 * configUSE_TRACE_FACILITY must be defined as 1 for this function to be 1174 * available. See the configuration section for more information. 1175 * 1176 * Populates a TaskStatus_t structure with information about a task. 1177 * 1178 * @param xTask Handle of the task being queried. If xTask is NULL then 1179 * information will be returned about the calling task. 1180 * 1181 * @param pxTaskStatus A pointer to the TaskStatus_t structure that will be 1182 * filled with information about the task referenced by the handle passed using 1183 * the xTask parameter. 1184 * 1185 * @param xGetFreeStackSpace The TaskStatus_t structure contains a member to report 1186 * the stack high water mark of the task being queried. Calculating the stack 1187 * high water mark takes a relatively long time, and can make the system 1188 * temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to 1189 * allow the high water mark checking to be skipped. The high watermark value 1190 * will only be written to the TaskStatus_t structure if xGetFreeStackSpace is 1191 * not set to pdFALSE; 1192 * 1193 * @param eState The TaskStatus_t structure contains a member to report the 1194 * state of the task being queried. Obtaining the task state is not as fast as 1195 * a simple assignment - so the eState parameter is provided to allow the state 1196 * information to be omitted from the TaskStatus_t structure. To obtain state 1197 * information then set eState to eInvalid - otherwise the value passed in 1198 * eState will be reported as the task state in the TaskStatus_t structure. 1199 * 1200 * Example usage: 1201 * @code{c} 1202 * void vAFunction( void ) 1203 * { 1204 * TaskHandle_t xHandle; 1205 * TaskStatus_t xTaskDetails; 1206 * 1207 * // Obtain the handle of a task from its name. 1208 * xHandle = xTaskGetHandle( "Task_Name" ); 1209 * 1210 * // Check the handle is not NULL. 1211 * configASSERT( xHandle ); 1212 * 1213 * // Use the handle to obtain further information about the task. 1214 * vTaskGetInfo( xHandle, 1215 * &xTaskDetails, 1216 * pdTRUE, // Include the high water mark in xTaskDetails. 1217 * eInvalid ); // Include the task state in xTaskDetails. 1218 * } 1219 * @endcode 1220 * @cond !DOC_SINGLE_GROUP 1221 * \defgroup vTaskGetInfo vTaskGetInfo 1222 * @endcond 1223 * \ingroup TaskCtrl 1224 */ 1225 void vTaskGetInfo( TaskHandle_t xTask, 1226 TaskStatus_t * pxTaskStatus, 1227 BaseType_t xGetFreeStackSpace, 1228 eTaskState eState ) PRIVILEGED_FUNCTION; 1229 1230 /** 1231 * @cond !DOC_EXCLUDE_HEADER_SECTION 1232 * task. h 1233 * @code{c} 1234 * void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ); 1235 * @endcode 1236 * @endcond 1237 * 1238 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. 1239 * See the configuration section for more information. 1240 * 1241 * Set the priority of any task. 1242 * 1243 * A context switch will occur before the function returns if the priority 1244 * being set is higher than the currently executing task. 1245 * 1246 * @param xTask Handle to the task for which the priority is being set. 1247 * Passing a NULL handle results in the priority of the calling task being set. 1248 * 1249 * @param uxNewPriority The priority to which the task will be set. 1250 * 1251 * Example usage: 1252 * @code{c} 1253 * void vAFunction( void ) 1254 * { 1255 * TaskHandle_t xHandle; 1256 * 1257 * // Create a task, storing the handle. 1258 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 1259 * 1260 * // ... 1261 * 1262 * // Use the handle to raise the priority of the created task. 1263 * vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 ); 1264 * 1265 * // ... 1266 * 1267 * // Use a NULL handle to raise our priority to the same value. 1268 * vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 ); 1269 * } 1270 * @endcode 1271 * @cond !DOC_SINGLE_GROUP 1272 * \defgroup vTaskPrioritySet vTaskPrioritySet 1273 * @endcond 1274 * \ingroup TaskCtrl 1275 */ 1276 void vTaskPrioritySet( TaskHandle_t xTask, 1277 UBaseType_t uxNewPriority ) PRIVILEGED_FUNCTION; 1278 1279 /** 1280 * @cond !DOC_EXCLUDE_HEADER_SECTION 1281 * task. h 1282 * @code{c} 1283 * void vTaskSuspend( TaskHandle_t xTaskToSuspend ); 1284 * @endcode 1285 * @endcond 1286 * 1287 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. 1288 * See the configuration section for more information. 1289 * 1290 * Suspend any task. When suspended a task will never get any microcontroller 1291 * processing time, no matter what its priority. 1292 * 1293 * Calls to vTaskSuspend are not accumulative - 1294 * i.e. calling vTaskSuspend () twice on the same task still only requires one 1295 * call to vTaskResume () to ready the suspended task. 1296 * 1297 * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL 1298 * handle will cause the calling task to be suspended. 1299 * 1300 * Example usage: 1301 * @code{c} 1302 * void vAFunction( void ) 1303 * { 1304 * TaskHandle_t xHandle; 1305 * 1306 * // Create a task, storing the handle. 1307 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 1308 * 1309 * // ... 1310 * 1311 * // Use the handle to suspend the created task. 1312 * vTaskSuspend( xHandle ); 1313 * 1314 * // ... 1315 * 1316 * // The created task will not run during this period, unless 1317 * // another task calls vTaskResume( xHandle ). 1318 * 1319 * //... 1320 * 1321 * 1322 * // Suspend ourselves. 1323 * vTaskSuspend( NULL ); 1324 * 1325 * // We cannot get here unless another task calls vTaskResume 1326 * // with our handle as the parameter. 1327 * } 1328 * @endcode 1329 * @cond !DOC_SINGLE_GROUP 1330 * \defgroup vTaskSuspend vTaskSuspend 1331 * @endcond 1332 * \ingroup TaskCtrl 1333 */ 1334 void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION; 1335 1336 /** 1337 * @cond !DOC_EXCLUDE_HEADER_SECTION 1338 * task. h 1339 * @code{c} 1340 * void vTaskResume( TaskHandle_t xTaskToResume ); 1341 * @endcode 1342 * @endcond 1343 * 1344 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. 1345 * See the configuration section for more information. 1346 * 1347 * Resumes a suspended task. 1348 * 1349 * A task that has been suspended by one or more calls to vTaskSuspend () 1350 * will be made available for running again by a single call to 1351 * vTaskResume (). 1352 * 1353 * @param xTaskToResume Handle to the task being readied. 1354 * 1355 * Example usage: 1356 * @code{c} 1357 * void vAFunction( void ) 1358 * { 1359 * TaskHandle_t xHandle; 1360 * 1361 * // Create a task, storing the handle. 1362 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 1363 * 1364 * // ... 1365 * 1366 * // Use the handle to suspend the created task. 1367 * vTaskSuspend( xHandle ); 1368 * 1369 * // ... 1370 * 1371 * // The created task will not run during this period, unless 1372 * // another task calls vTaskResume( xHandle ). 1373 * 1374 * //... 1375 * 1376 * 1377 * // Resume the suspended task ourselves. 1378 * vTaskResume( xHandle ); 1379 * 1380 * // The created task will once again get microcontroller processing 1381 * // time in accordance with its priority within the system. 1382 * } 1383 * @endcode 1384 * @cond !DOC_SINGLE_GROUP 1385 * \defgroup vTaskResume vTaskResume 1386 * @endcond 1387 * \ingroup TaskCtrl 1388 */ 1389 void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; 1390 1391 /** 1392 * @cond !DOC_EXCLUDE_HEADER_SECTION 1393 * task. h 1394 * @code{c} 1395 * void xTaskResumeFromISR( TaskHandle_t xTaskToResume ); 1396 * @endcode 1397 * @endcond 1398 * 1399 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be 1400 * available. See the configuration section for more information. 1401 * 1402 * An implementation of vTaskResume() that can be called from within an ISR. 1403 * 1404 * A task that has been suspended by one or more calls to vTaskSuspend () 1405 * will be made available for running again by a single call to 1406 * xTaskResumeFromISR (). 1407 * 1408 * xTaskResumeFromISR() should not be used to synchronise a task with an 1409 * interrupt if there is a chance that the interrupt could arrive prior to the 1410 * task being suspended - as this can lead to interrupts being missed. Use of a 1411 * semaphore as a synchronisation mechanism would avoid this eventuality. 1412 * 1413 * @param xTaskToResume Handle to the task being readied. 1414 * 1415 * @return pdTRUE if resuming the task should result in a context switch, 1416 * otherwise pdFALSE. This is used by the ISR to determine if a context switch 1417 * may be required following the ISR. 1418 * 1419 * @cond !DOC_SINGLE_GROUP 1420 * \defgroup vTaskResumeFromISR vTaskResumeFromISR 1421 * @endcond 1422 * \ingroup TaskCtrl 1423 */ 1424 BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; 1425 1426 /*----------------------------------------------------------- 1427 * SCHEDULER CONTROL 1428 *----------------------------------------------------------*/ 1429 /** @cond !DOC_EXCLUDE_HEADER_SECTION */ 1430 /** 1431 * @cond !DOC_EXCLUDE_HEADER_SECTION 1432 * task. h 1433 * @code{c} 1434 * void vTaskStartScheduler( void ); 1435 * @endcode 1436 * @endcond 1437 * 1438 * Starts the real time kernel tick processing. After calling the kernel 1439 * has control over which tasks are executed and when. 1440 1441 * NOTE: In ESP-IDF the scheduler is started automatically during 1442 * application startup, vTaskStartScheduler() should not be called from 1443 * ESP-IDF applications. 1444 * 1445 * See the demo application file main.c for an example of creating 1446 * tasks and starting the kernel. 1447 * 1448 * Example usage: 1449 * @code{c} 1450 * void vAFunction( void ) 1451 * { 1452 * // Create at least one task before starting the kernel. 1453 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); 1454 * 1455 * // Start the real time kernel with preemption. 1456 * vTaskStartScheduler (); 1457 * 1458 * // Will not get here unless a task calls vTaskEndScheduler () 1459 * } 1460 * @endcode 1461 * 1462 * @cond !DOC_SINGLE_GROUP 1463 * \defgroup vTaskStartScheduler vTaskStartScheduler 1464 * @endcond 1465 * \ingroup SchedulerControl 1466 */ 1467 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; 1468 1469 /** 1470 * @cond !DOC_EXCLUDE_HEADER_SECTION 1471 * task. h 1472 * @code{c} 1473 * void vTaskEndScheduler( void ); 1474 * @endcode 1475 * @endcond 1476 * 1477 * NOTE: At the time of writing only the x86 real mode port, which runs on a PC 1478 * in place of DOS, implements this function. 1479 * 1480 * Stops the real time kernel tick. All created tasks will be automatically 1481 * deleted and multitasking (either preemptive or cooperative) will 1482 * stop. Execution then resumes from the point where vTaskStartScheduler () 1483 * was called, as if vTaskStartScheduler () had just returned. 1484 * 1485 * See the demo application file main. c in the demo/PC directory for an 1486 * example that uses vTaskEndScheduler (). 1487 * 1488 * vTaskEndScheduler () requires an exit function to be defined within the 1489 * portable layer (see vPortEndScheduler () in port. c for the PC port). This 1490 * performs hardware specific operations such as stopping the kernel tick. 1491 * 1492 * vTaskEndScheduler () will cause all of the resources allocated by the 1493 * kernel to be freed - but will not free resources allocated by application 1494 * tasks. 1495 * 1496 * Example usage: 1497 * @code{c} 1498 * void vTaskCode( void * pvParameters ) 1499 * { 1500 * for( ;; ) 1501 * { 1502 * // Task code goes here. 1503 * 1504 * // At some point we want to end the real time kernel processing 1505 * // so call ... 1506 * vTaskEndScheduler (); 1507 * } 1508 * } 1509 * 1510 * void vAFunction( void ) 1511 * { 1512 * // Create at least one task before starting the kernel. 1513 * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); 1514 * 1515 * // Start the real time kernel with preemption. 1516 * vTaskStartScheduler (); 1517 * 1518 * // Will only get here when the vTaskCode () task has called 1519 * // vTaskEndScheduler (). When we get here we are back to single task 1520 * // execution. 1521 * } 1522 * @endcode 1523 * 1524 * @cond !DOC_SINGLE_GROUP 1525 * \defgroup vTaskEndScheduler vTaskEndScheduler 1526 * @endcond 1527 * \ingroup SchedulerControl 1528 */ 1529 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; 1530 1531 /** @endcond */ 1532 1533 /** 1534 * @cond !DOC_EXCLUDE_HEADER_SECTION 1535 * task. h 1536 * @code{c} 1537 * void vTaskSuspendAll( void ); 1538 * @endcode 1539 * @endcond 1540 * 1541 * Suspends the scheduler without disabling interrupts. Context switches will 1542 * not occur while the scheduler is suspended. 1543 * 1544 * After calling vTaskSuspendAll () the calling task will continue to execute 1545 * without risk of being swapped out until a call to xTaskResumeAll () has been 1546 * made. 1547 * 1548 * API functions that have the potential to cause a context switch (for example, 1549 * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler 1550 * is suspended. 1551 * 1552 * Example usage: 1553 * @code{c} 1554 * void vTask1( void * pvParameters ) 1555 * { 1556 * for( ;; ) 1557 * { 1558 * // Task code goes here. 1559 * 1560 * // ... 1561 * 1562 * // At some point the task wants to perform a long operation during 1563 * // which it does not want to get swapped out. It cannot use 1564 * // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the 1565 * // operation may cause interrupts to be missed - including the 1566 * // ticks. 1567 * 1568 * // Prevent the real time kernel swapping out the task. 1569 * vTaskSuspendAll (); 1570 * 1571 * // Perform the operation here. There is no need to use critical 1572 * // sections as we have all the microcontroller processing time. 1573 * // During this time interrupts will still operate and the kernel 1574 * // tick count will be maintained. 1575 * 1576 * // ... 1577 * 1578 * // The operation is complete. Restart the kernel. 1579 * xTaskResumeAll (); 1580 * } 1581 * } 1582 * @endcode 1583 * @cond !DOC_SINGLE_GROUP 1584 * \defgroup vTaskSuspendAll vTaskSuspendAll 1585 * @endcond 1586 * \ingroup SchedulerControl 1587 */ 1588 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION; 1589 1590 /** 1591 * @cond !DOC_EXCLUDE_HEADER_SECTION 1592 * task. h 1593 * @code{c} 1594 * BaseType_t xTaskResumeAll( void ); 1595 * @endcode 1596 * @endcond 1597 * 1598 * Resumes scheduler activity after it was suspended by a call to 1599 * vTaskSuspendAll(). 1600 * 1601 * xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks 1602 * that were previously suspended by a call to vTaskSuspend(). 1603 * 1604 * @return If resuming the scheduler caused a context switch then pdTRUE is 1605 * returned, otherwise pdFALSE is returned. 1606 * 1607 * Example usage: 1608 * @code{c} 1609 * void vTask1( void * pvParameters ) 1610 * { 1611 * for( ;; ) 1612 * { 1613 * // Task code goes here. 1614 * 1615 * // ... 1616 * 1617 * // At some point the task wants to perform a long operation during 1618 * // which it does not want to get swapped out. It cannot use 1619 * // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the 1620 * // operation may cause interrupts to be missed - including the 1621 * // ticks. 1622 * 1623 * // Prevent the real time kernel swapping out the task. 1624 * vTaskSuspendAll (); 1625 * 1626 * // Perform the operation here. There is no need to use critical 1627 * // sections as we have all the microcontroller processing time. 1628 * // During this time interrupts will still operate and the real 1629 * // time kernel tick count will be maintained. 1630 * 1631 * // ... 1632 * 1633 * // The operation is complete. Restart the kernel. We want to force 1634 * // a context switch - but there is no point if resuming the scheduler 1635 * // caused a context switch already. 1636 * if( !xTaskResumeAll () ) 1637 * { 1638 * taskYIELD (); 1639 * } 1640 * } 1641 * } 1642 * @endcode 1643 * @cond !DOC_SINGLE_GROUP 1644 * \defgroup xTaskResumeAll xTaskResumeAll 1645 * @endcond 1646 * \ingroup SchedulerControl 1647 */ 1648 BaseType_t xTaskResumeAll( void ) PRIVILEGED_FUNCTION; 1649 1650 /*----------------------------------------------------------- 1651 * TASK UTILITIES 1652 *----------------------------------------------------------*/ 1653 1654 /** 1655 * @cond !DOC_EXCLUDE_HEADER_SECTION 1656 * task. h 1657 * @code{c} 1658 * TickType_t xTaskGetTickCount( void ); 1659 * @endcode 1660 * @endcond 1661 * 1662 * @return The count of ticks since vTaskStartScheduler was called. 1663 * 1664 * @cond !DOC_SINGLE_GROUP 1665 * \defgroup xTaskGetTickCount xTaskGetTickCount 1666 * @endcond 1667 * \ingroup TaskUtils 1668 */ 1669 TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION; 1670 1671 /** 1672 * @cond !DOC_EXCLUDE_HEADER_SECTION 1673 * task. h 1674 * @code{c} 1675 * TickType_t xTaskGetTickCountFromISR( void ); 1676 * @endcode 1677 * @endcond 1678 * 1679 * @return The count of ticks since vTaskStartScheduler was called. 1680 * 1681 * This is a version of xTaskGetTickCount() that is safe to be called from an 1682 * ISR - provided that TickType_t is the natural word size of the 1683 * microcontroller being used or interrupt nesting is either not supported or 1684 * not being used. 1685 * 1686 * @cond !DOC_SINGLE_GROUP 1687 * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR 1688 * @endcond 1689 * \ingroup TaskUtils 1690 */ 1691 TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION; 1692 1693 /** 1694 * @cond !DOC_EXCLUDE_HEADER_SECTION 1695 * task. h 1696 * @code{c} 1697 * uint16_t uxTaskGetNumberOfTasks( void ); 1698 * @endcode 1699 * @endcond 1700 * 1701 * @return The number of tasks that the real time kernel is currently managing. 1702 * This includes all ready, blocked and suspended tasks. A task that 1703 * has been deleted but not yet freed by the idle task will also be 1704 * included in the count. 1705 * 1706 * @cond !DOC_SINGLE_GROUP 1707 * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks 1708 * @endcond 1709 * \ingroup TaskUtils 1710 */ 1711 UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION; 1712 1713 /** 1714 * @cond !DOC_EXCLUDE_HEADER_SECTION 1715 * task. h 1716 * @code{c} 1717 * char *pcTaskGetName( TaskHandle_t xTaskToQuery ); 1718 * @endcode 1719 * @endcond 1720 * 1721 * @return The text (human readable) name of the task referenced by the handle 1722 * xTaskToQuery. A task can query its own name by either passing in its own 1723 * handle, or by setting xTaskToQuery to NULL. 1724 * 1725 * @cond !DOC_SINGLE_GROUP 1726 * \defgroup pcTaskGetName pcTaskGetName 1727 * @endcond 1728 * \ingroup TaskUtils 1729 */ 1730 char * pcTaskGetName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 1731 1732 /** 1733 * @cond !DOC_EXCLUDE_HEADER_SECTION 1734 * task. h 1735 * @code{c} 1736 * TaskHandle_t xTaskGetHandle( const char *pcNameToQuery ); 1737 * @endcode 1738 * @endcond 1739 * 1740 * NOTE: This function takes a relatively long time to complete and should be 1741 * used sparingly. 1742 * 1743 * @return The handle of the task that has the human readable name pcNameToQuery. 1744 * NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle 1745 * must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available. 1746 * 1747 * @cond !DOC_SINGLE_GROUP 1748 * \defgroup pcTaskGetHandle pcTaskGetHandle 1749 * @endcond 1750 * \ingroup TaskUtils 1751 */ 1752 TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 1753 1754 /** 1755 * Returns the high water mark of the stack associated with xTask. 1756 * 1757 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for 1758 * this function to be available. 1759 * 1760 * Returns the high water mark of the stack associated with xTask. That is, 1761 * the minimum free stack space there has been (in bytes not words, unlike vanilla 1762 * FreeRTOS) since the task started. The smaller the returned 1763 * number the closer the task has come to overflowing its stack. 1764 * 1765 * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the 1766 * same except for their return type. Using configSTACK_DEPTH_TYPE allows the 1767 * user to determine the return type. It gets around the problem of the value 1768 * overflowing on 8-bit types without breaking backward compatibility for 1769 * applications that expect an 8-bit return type. 1770 * 1771 * @param xTask Handle of the task associated with the stack to be checked. 1772 * Set xTask to NULL to check the stack of the calling task. 1773 * 1774 * @return The smallest amount of free stack space there has been (in bytes not words, 1775 * unlike vanilla FreeRTOS) since the task referenced by 1776 * xTask was created. 1777 */ 1778 UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1779 1780 /** 1781 * Returns the start of the stack associated with xTask. 1782 * 1783 * INCLUDE_uxTaskGetStackHighWaterMark2 must be set to 1 in FreeRTOSConfig.h for 1784 * this function to be available. 1785 * 1786 * Returns the high water mark of the stack associated with xTask. That is, 1787 * the minimum free stack space there has been (in words, so on a 32 bit machine 1788 * a value of 1 means 4 bytes) since the task started. The smaller the returned 1789 * number the closer the task has come to overflowing its stack. 1790 * 1791 * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the 1792 * same except for their return type. Using configSTACK_DEPTH_TYPE allows the 1793 * user to determine the return type. It gets around the problem of the value 1794 * overflowing on 8-bit types without breaking backward compatibility for 1795 * applications that expect an 8-bit return type. 1796 * 1797 * @param xTask Handle of the task associated with the stack to be checked. 1798 * Set xTask to NULL to check the stack of the calling task. 1799 * 1800 * @return The smallest amount of free stack space there has been (in words, so 1801 * actual spaces on the stack rather than bytes) since the task referenced by 1802 * xTask was created. 1803 */ 1804 configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1805 1806 /** 1807 * Returns the start of the stack associated with xTask. 1808 * 1809 * INCLUDE_pxTaskGetStackStart must be set to 1 in FreeRTOSConfig.h for 1810 * this function to be available. 1811 * 1812 * Returns the lowest stack memory address, regardless of whether the stack grows up or down. 1813 * 1814 * @param xTask Handle of the task associated with the stack returned. 1815 * Set xTask to NULL to return the stack of the calling task. 1816 * 1817 * @return A pointer to the start of the stack. 1818 */ 1819 uint8_t* pxTaskGetStackStart( TaskHandle_t xTask) PRIVILEGED_FUNCTION; 1820 1821 /* When using trace macros it is sometimes necessary to include task.h before 1822 * FreeRTOS.h. When this is done TaskHookFunction_t will not yet have been defined, 1823 * so the following two prototypes will cause a compilation error. This can be 1824 * fixed by simply guarding against the inclusion of these two prototypes unless 1825 * they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration 1826 * constant. */ 1827 #ifdef configUSE_APPLICATION_TASK_TAG 1828 #if configUSE_APPLICATION_TASK_TAG == 1 1829 /** 1830 * @cond !DOC_EXCLUDE_HEADER_SECTION 1831 * task.h 1832 * @code{c} 1833 * void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction ); 1834 * @endcode 1835 * @endcond 1836 * 1837 * Sets pxHookFunction to be the task hook function used by the task xTask. 1838 * @param xTask Handle of the task to set the hook function for 1839 * Passing xTask as NULL has the effect of setting the calling 1840 * tasks hook function. 1841 * @param pxHookFunction Pointer to the hook function. 1842 */ 1843 void vTaskSetApplicationTaskTag( TaskHandle_t xTask, 1844 TaskHookFunction_t pxHookFunction ) PRIVILEGED_FUNCTION; 1845 1846 /** 1847 * @cond !DOC_EXCLUDE_HEADER_SECTION 1848 * task.h 1849 * @code{c} 1850 * void xTaskGetApplicationTaskTag( TaskHandle_t xTask ); 1851 * @endcode 1852 * @endcond 1853 * 1854 * Returns the pxHookFunction value assigned to the task xTask. Do not 1855 * call from an interrupt service routine - call 1856 * xTaskGetApplicationTaskTagFromISR() instead. 1857 */ 1858 TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1859 1860 /** 1861 * @cond !DOC_EXCLUDE_HEADER_SECTION 1862 * task.h 1863 * @code{c} 1864 * void xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask ); 1865 * @endcode 1866 * @endcond 1867 * 1868 * Returns the pxHookFunction value assigned to the task xTask. Can 1869 * be called from an interrupt service routine. 1870 */ 1871 TaskHookFunction_t xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1872 #endif /* configUSE_APPLICATION_TASK_TAG ==1 */ 1873 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */ 1874 1875 #if ( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 ) 1876 1877 /** 1878 * Set local storage pointer specific to the given task. 1879 * 1880 * Each task contains an array of pointers that is dimensioned by the 1881 * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. 1882 * The kernel does not use the pointers itself, so the application writer 1883 * can use the pointers for any purpose they wish. 1884 * 1885 * @param xTaskToSet Task to set thread local storage pointer for 1886 * @param xIndex The index of the pointer to set, from 0 to 1887 * configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1. 1888 * @param pvValue Pointer value to set. 1889 */ 1890 void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, 1891 BaseType_t xIndex, 1892 void * pvValue ) PRIVILEGED_FUNCTION; 1893 1894 1895 /** 1896 * Get local storage pointer specific to the given task. 1897 * 1898 * Each task contains an array of pointers that is dimensioned by the 1899 * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. 1900 * The kernel does not use the pointers itself, so the application writer 1901 * can use the pointers for any purpose they wish. 1902 * 1903 * @param xTaskToQuery Task to get thread local storage pointer for 1904 * @param xIndex The index of the pointer to get, from 0 to 1905 * configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1. 1906 * @return Pointer value 1907 */ 1908 void * pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery, 1909 BaseType_t xIndex ) PRIVILEGED_FUNCTION; 1910 1911 #if ( configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS ) 1912 1913 /** 1914 * Prototype of local storage pointer deletion callback. 1915 */ 1916 typedef void (*TlsDeleteCallbackFunction_t)( int, void * ); 1917 1918 /** 1919 * Set local storage pointer and deletion callback. 1920 * 1921 * Each task contains an array of pointers that is dimensioned by the 1922 * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. 1923 * The kernel does not use the pointers itself, so the application writer 1924 * can use the pointers for any purpose they wish. 1925 * 1926 * Local storage pointers set for a task can reference dynamically 1927 * allocated resources. This function is similar to 1928 * vTaskSetThreadLocalStoragePointer, but provides a way to release 1929 * these resources when the task gets deleted. For each pointer, 1930 * a callback function can be set. This function will be called 1931 * when task is deleted, with the local storage pointer index 1932 * and value as arguments. 1933 * 1934 * @param xTaskToSet Task to set thread local storage pointer for 1935 * @param xIndex The index of the pointer to set, from 0 to 1936 * configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1. 1937 * @param pvValue Pointer value to set. 1938 * @param pvDelCallback Function to call to dispose of the local 1939 * storage pointer when the task is deleted. 1940 */ 1941 void vTaskSetThreadLocalStoragePointerAndDelCallback( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue, TlsDeleteCallbackFunction_t pvDelCallback); 1942 #endif 1943 1944 #endif 1945 1946 #if ( configCHECK_FOR_STACK_OVERFLOW > 0 ) 1947 1948 /** 1949 * @cond !DOC_EXCLUDE_HEADER_SECTION 1950 * task.h 1951 * @code{c} 1952 * void vApplicationStackOverflowHook( TaskHandle_t xTask char *pcTaskName); 1953 * @endcode 1954 * @endcond 1955 * The application stack overflow hook is called when a stack overflow is detected for a task. 1956 * 1957 * Details on stack overflow detection can be found here: https://www.FreeRTOS.org/Stacks-and-stack-overflow-checking.html 1958 * 1959 * @param xTask the task that just exceeded its stack boundaries. 1960 * @param pcTaskName A character string containing the name of the offending task. 1961 */ 1962 void vApplicationStackOverflowHook( TaskHandle_t xTask, 1963 char * pcTaskName ); 1964 1965 #endif 1966 1967 #if ( configUSE_TICK_HOOK > 0 ) 1968 /** 1969 * @cond !DOC_EXCLUDE_HEADER_SECTION 1970 * task.h 1971 * @code{c} 1972 * void vApplicationTickHook( void ); 1973 * @endcode 1974 * @endcond 1975 * 1976 * This hook function is called in the system tick handler after any OS work is completed. 1977 */ 1978 void vApplicationTickHook( void ); /*lint !e526 Symbol not defined as it is an application callback. */ 1979 1980 #endif 1981 1982 #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) 1983 /** 1984 * @cond !DOC_EXCLUDE_HEADER_SECTION 1985 * task.h 1986 * @code{c} 1987 * void vApplicationGetIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer, StackType_t ** ppxIdleTaskStackBuffer, uint32_t *pulIdleTaskStackSize ) 1988 * @endcode 1989 * @endcond 1990 * This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Idle Task TCB. This function is required when 1991 * configSUPPORT_STATIC_ALLOCATION is set. For more information see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION 1992 * 1993 * @param ppxIdleTaskTCBBuffer A handle to a statically allocated TCB buffer 1994 * @param ppxIdleTaskStackBuffer A handle to a statically allocated Stack buffer for thie idle task 1995 * @param pulIdleTaskStackSize A pointer to the number of elements that will fit in the allocated stack buffer 1996 */ 1997 void vApplicationGetIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer, 1998 StackType_t ** ppxIdleTaskStackBuffer, 1999 uint32_t * pulIdleTaskStackSize ); /*lint !e526 Symbol not defined as it is an application callback. */ 2000 #endif 2001 2002 /** 2003 * @cond !DOC_EXCLUDE_HEADER_SECTION 2004 * task.h 2005 * @code{c} 2006 * BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter ); 2007 * @endcode 2008 * @endcond 2009 * 2010 * Calls the hook function associated with xTask. Passing xTask as NULL has 2011 * the effect of calling the Running tasks (the calling task) hook function. 2012 * 2013 * @param xTask Handle of the task to call the hook for. 2014 * @param pvParameter Parameter passed to the hook function for the task to interpret as it 2015 * wants. The return value is the value returned by the task hook function 2016 * registered by the user. 2017 */ 2018 BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, 2019 void * pvParameter ) PRIVILEGED_FUNCTION; 2020 2021 /** 2022 * xTaskGetIdleTaskHandle() is only available if 2023 * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h. 2024 * 2025 * Simply returns the handle of the idle task. It is not valid to call 2026 * xTaskGetIdleTaskHandle() before the scheduler has been started. 2027 */ 2028 TaskHandle_t xTaskGetIdleTaskHandle( void ) PRIVILEGED_FUNCTION; 2029 2030 /** 2031 * configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for 2032 * uxTaskGetSystemState() to be available. 2033 * 2034 * uxTaskGetSystemState() populates an TaskStatus_t structure for each task in 2035 * the system. TaskStatus_t structures contain, among other things, members 2036 * for the task handle, task name, task priority, task state, and total amount 2037 * of run time consumed by the task. See the TaskStatus_t structure 2038 * definition in this file for the full member list. 2039 * 2040 * NOTE: This function is intended for debugging use only as its use results in 2041 * the scheduler remaining suspended for an extended period. 2042 * 2043 * @param pxTaskStatusArray A pointer to an array of TaskStatus_t structures. 2044 * The array must contain at least one TaskStatus_t structure for each task 2045 * that is under the control of the RTOS. The number of tasks under the control 2046 * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function. 2047 * 2048 * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray 2049 * parameter. The size is specified as the number of indexes in the array, or 2050 * the number of TaskStatus_t structures contained in the array, not by the 2051 * number of bytes in the array. 2052 * 2053 * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in 2054 * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the 2055 * total run time (as defined by the run time stats clock, see 2056 * https://www.FreeRTOS.org/rtos-run-time-stats.html) since the target booted. 2057 * pulTotalRunTime can be set to NULL to omit the total run time information. 2058 * 2059 * @return The number of TaskStatus_t structures that were populated by 2060 * uxTaskGetSystemState(). This should equal the number returned by the 2061 * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed 2062 * in the uxArraySize parameter was too small. 2063 * 2064 * Example usage: 2065 * @code{c} 2066 * // This example demonstrates how a human readable table of run time stats 2067 * // information is generated from raw data provided by uxTaskGetSystemState(). 2068 * // The human readable table is written to pcWriteBuffer 2069 * void vTaskGetRunTimeStats( char *pcWriteBuffer ) 2070 * { 2071 * TaskStatus_t *pxTaskStatusArray; 2072 * volatile UBaseType_t uxArraySize, x; 2073 * uint32_t ulTotalRunTime, ulStatsAsPercentage; 2074 * 2075 * // Make sure the write buffer does not contain a string. 2076 * *pcWriteBuffer = 0x00; 2077 * 2078 * // Take a snapshot of the number of tasks in case it changes while this 2079 * // function is executing. 2080 * uxArraySize = uxTaskGetNumberOfTasks(); 2081 * 2082 * // Allocate a TaskStatus_t structure for each task. An array could be 2083 * // allocated statically at compile time. 2084 * pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) ); 2085 * 2086 * if( pxTaskStatusArray != NULL ) 2087 * { 2088 * // Generate raw status information about each task. 2089 * uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime ); 2090 * 2091 * // For percentage calculations. 2092 * ulTotalRunTime /= 100UL; 2093 * 2094 * // Avoid divide by zero errors. 2095 * if( ulTotalRunTime > 0 ) 2096 * { 2097 * // For each populated position in the pxTaskStatusArray array, 2098 * // format the raw data as human readable ASCII data 2099 * for( x = 0; x < uxArraySize; x++ ) 2100 * { 2101 * // What percentage of the total run time has the task used? 2102 * // This will always be rounded down to the nearest integer. 2103 * // ulTotalRunTimeDiv100 has already been divided by 100. 2104 * ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime; 2105 * 2106 * if( ulStatsAsPercentage > 0UL ) 2107 * { 2108 * sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage ); 2109 * } 2110 * else 2111 * { 2112 * // If the percentage is zero here then the task has 2113 * // consumed less than 1% of the total run time. 2114 * sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter ); 2115 * } 2116 * 2117 * pcWriteBuffer += strlen( ( char * ) pcWriteBuffer ); 2118 * } 2119 * } 2120 * 2121 * // The array is no longer needed, free the memory it consumes. 2122 * vPortFree( pxTaskStatusArray ); 2123 * } 2124 * } 2125 * @endcode 2126 */ 2127 UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, 2128 const UBaseType_t uxArraySize, 2129 uint32_t * const pulTotalRunTime ) PRIVILEGED_FUNCTION; 2130 2131 /** 2132 * List all the current tasks. 2133 * 2134 * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must 2135 * both be defined as 1 for this function to be available. See the 2136 * configuration section of the FreeRTOS.org website for more information. 2137 * 2138 * NOTE 1: This function will disable interrupts for its duration. It is 2139 * not intended for normal application runtime use but as a debug aid. 2140 * 2141 * Lists all the current tasks, along with their current state and stack 2142 * usage high water mark. 2143 * 2144 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or 2145 * suspended ('S'). 2146 * 2147 * PLEASE NOTE: 2148 * 2149 * This function is provided for convenience only, and is used by many of the 2150 * demo applications. Do not consider it to be part of the scheduler. 2151 * 2152 * vTaskList() calls uxTaskGetSystemState(), then formats part of the 2153 * uxTaskGetSystemState() output into a human readable table that displays task 2154 * names, states and stack usage. 2155 * 2156 * vTaskList() has a dependency on the sprintf() C library function that might 2157 * bloat the code size, use a lot of stack, and provide different results on 2158 * different platforms. An alternative, tiny, third party, and limited 2159 * functionality implementation of sprintf() is provided in many of the 2160 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note 2161 * printf-stdarg.c does not provide a full snprintf() implementation!). 2162 * 2163 * It is recommended that production systems call uxTaskGetSystemState() 2164 * directly to get access to raw stats data, rather than indirectly through a 2165 * call to vTaskList(). 2166 * 2167 * @param pcWriteBuffer A buffer into which the above mentioned details 2168 * will be written, in ASCII form. This buffer is assumed to be large 2169 * enough to contain the generated report. Approximately 40 bytes per 2170 * task should be sufficient. 2171 * 2172 * @cond !DOC_SINGLE_GROUP 2173 * \defgroup vTaskList vTaskList 2174 * @endcond 2175 * \ingroup TaskUtils 2176 */ 2177 void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 2178 2179 /** 2180 * Get the state of running tasks as a string 2181 * 2182 * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS 2183 * must both be defined as 1 for this function to be available. The application 2184 * must also then provide definitions for 2185 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE() 2186 * to configure a peripheral timer/counter and return the timers current count 2187 * value respectively. The counter should be at least 10 times the frequency of 2188 * the tick count. 2189 * 2190 * NOTE 1: This function will disable interrupts for its duration. It is 2191 * not intended for normal application runtime use but as a debug aid. 2192 * 2193 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total 2194 * accumulated execution time being stored for each task. The resolution 2195 * of the accumulated time value depends on the frequency of the timer 2196 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. 2197 * Calling vTaskGetRunTimeStats() writes the total execution time of each 2198 * task into a buffer, both as an absolute count value and as a percentage 2199 * of the total system execution time. 2200 * 2201 * NOTE 2: 2202 * 2203 * This function is provided for convenience only, and is used by many of the 2204 * demo applications. Do not consider it to be part of the scheduler. 2205 * 2206 * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the 2207 * uxTaskGetSystemState() output into a human readable table that displays the 2208 * amount of time each task has spent in the Running state in both absolute and 2209 * percentage terms. 2210 * 2211 * vTaskGetRunTimeStats() has a dependency on the sprintf() C library function 2212 * that might bloat the code size, use a lot of stack, and provide different 2213 * results on different platforms. An alternative, tiny, third party, and 2214 * limited functionality implementation of sprintf() is provided in many of the 2215 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note 2216 * printf-stdarg.c does not provide a full snprintf() implementation!). 2217 * 2218 * It is recommended that production systems call uxTaskGetSystemState() directly 2219 * to get access to raw stats data, rather than indirectly through a call to 2220 * vTaskGetRunTimeStats(). 2221 * 2222 * @param pcWriteBuffer A buffer into which the execution times will be 2223 * written, in ASCII form. This buffer is assumed to be large enough to 2224 * contain the generated report. Approximately 40 bytes per task should 2225 * be sufficient. 2226 * 2227 * @cond !DOC_SINGLE_GROUP 2228 * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats 2229 * @endcond 2230 * \ingroup TaskUtils 2231 */ 2232 void vTaskGetRunTimeStats( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 2233 2234 /** 2235 * @cond !DOC_EXCLUDE_HEADER_SECTION 2236 * task. h 2237 * @code 2238 * uint32_t ulTaskGetIdleRunTimeCounter( void ); 2239 * @endcode 2240 * @endcond 2241 * 2242 * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS 2243 * must both be defined as 1 for this function to be available. The application 2244 * must also then provide definitions for 2245 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE() 2246 * to configure a peripheral timer/counter and return the timers current count 2247 * value respectively. The counter should be at least 10 times the frequency of 2248 * the tick count. 2249 * 2250 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total 2251 * accumulated execution time being stored for each task. The resolution 2252 * of the accumulated time value depends on the frequency of the timer 2253 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. 2254 * While uxTaskGetSystemState() and vTaskGetRunTimeStats() writes the total 2255 * execution time of each task into a buffer, ulTaskGetIdleRunTimeCounter() 2256 * returns the total execution time of just the idle task. 2257 * 2258 * @return The total run time of the idle task. This is the amount of time the 2259 * idle task has actually been executing. The unit of time is dependent on the 2260 * frequency configured using the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and 2261 * portGET_RUN_TIME_COUNTER_VALUE() macros. 2262 * 2263 * @cond !DOC_SINGLE_GROUP 2264 * \defgroup ulTaskGetIdleRunTimeCounter ulTaskGetIdleRunTimeCounter 2265 * @endcond 2266 * \ingroup TaskUtils 2267 */ 2268 uint32_t ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION; 2269 2270 /** 2271 * @cond !DOC_EXCLUDE_HEADER_SECTION 2272 * task. h 2273 * @code{c} 2274 * BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction ); 2275 * BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction ); 2276 * @endcode 2277 * @endcond 2278 * 2279 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. 2280 * 2281 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these 2282 * functions to be available. 2283 * 2284 * Sends a direct to task notification to a task, with an optional value and 2285 * action. 2286 * 2287 * Each task has a private array of "notification values" (or 'notifications'), 2288 * each of which is a 32-bit unsigned integer (uint32_t). The constant 2289 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the 2290 * array, and (for backward compatibility) defaults to 1 if left undefined. 2291 * Prior to FreeRTOS V10.4.0 there was only one notification value per task. 2292 * 2293 * Events can be sent to a task using an intermediary object. Examples of such 2294 * objects are queues, semaphores, mutexes and event groups. Task notifications 2295 * are a method of sending an event directly to a task without the need for such 2296 * an intermediary object. 2297 * 2298 * A notification sent to a task can optionally perform an action, such as 2299 * update, overwrite or increment one of the task's notification values. In 2300 * that way task notifications can be used to send data to a task, or be used as 2301 * light weight and fast binary or counting semaphores. 2302 * 2303 * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a 2304 * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block 2305 * to wait for a notification value to have a non-zero value. The task does 2306 * not consume any CPU time while it is in the Blocked state. 2307 * 2308 * A notification sent to a task will remain pending until it is cleared by the 2309 * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their 2310 * un-indexed equivalents). If the task was already in the Blocked state to 2311 * wait for a notification when the notification arrives then the task will 2312 * automatically be removed from the Blocked state (unblocked) and the 2313 * notification cleared. 2314 * 2315 * **NOTE** Each notification within the array operates independently - a task 2316 * can only block on one notification within the array at a time and will not be 2317 * unblocked by a notification sent to any other array index. 2318 * 2319 * Backward compatibility information: 2320 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and 2321 * all task notification API functions operated on that value. Replacing the 2322 * single notification value with an array of notification values necessitated a 2323 * new set of API functions that could address specific notifications within the 2324 * array. xTaskNotify() is the original API function, and remains backward 2325 * compatible by always operating on the notification value at index 0 in the 2326 * array. Calling xTaskNotify() is equivalent to calling xTaskNotifyIndexed() 2327 * with the uxIndexToNotify parameter set to 0. 2328 * 2329 * @param xTaskToNotify The handle of the task being notified. The handle to a 2330 * task can be returned from the xTaskCreate() API function used to create the 2331 * task, and the handle of the currently running task can be obtained by calling 2332 * xTaskGetCurrentTaskHandle(). 2333 * 2334 * @param uxIndexToNotify The index within the target task's array of 2335 * notification values to which the notification is to be sent. uxIndexToNotify 2336 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotify() does 2337 * not have this parameter and always sends notifications to index 0. 2338 * 2339 * @param ulValue Data that can be sent with the notification. How the data is 2340 * used depends on the value of the eAction parameter. 2341 * 2342 * @param eAction Specifies how the notification updates the task's notification 2343 * value, if at all. Valid values for eAction are as follows: 2344 * 2345 * eSetBits - 2346 * The target notification value is bitwise ORed with ulValue. 2347 * xTaskNotifyIndexed() always returns pdPASS in this case. 2348 * 2349 * eIncrement - 2350 * The target notification value is incremented. ulValue is not used and 2351 * xTaskNotifyIndexed() always returns pdPASS in this case. 2352 * 2353 * eSetValueWithOverwrite - 2354 * The target notification value is set to the value of ulValue, even if the 2355 * task being notified had not yet processed the previous notification at the 2356 * same array index (the task already had a notification pending at that index). 2357 * xTaskNotifyIndexed() always returns pdPASS in this case. 2358 * 2359 * eSetValueWithoutOverwrite - 2360 * If the task being notified did not already have a notification pending at the 2361 * same array index then the target notification value is set to ulValue and 2362 * xTaskNotifyIndexed() will return pdPASS. If the task being notified already 2363 * had a notification pending at the same array index then no action is 2364 * performed and pdFAIL is returned. 2365 * 2366 * eNoAction - 2367 * The task receives a notification at the specified array index without the 2368 * notification value at that index being updated. ulValue is not used and 2369 * xTaskNotifyIndexed() always returns pdPASS in this case. 2370 * 2371 * pulPreviousNotificationValue - 2372 * Can be used to pass out the subject task's notification value before any 2373 * bits are modified by the notify function. 2374 * 2375 * @return Dependent on the value of eAction. See the description of the 2376 * eAction parameter. 2377 * 2378 * @cond !DOC_SINGLE_GROUP 2379 * \defgroup xTaskNotifyIndexed xTaskNotifyIndexed 2380 * @endcond 2381 * \ingroup TaskNotifications 2382 */ 2383 BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, 2384 UBaseType_t uxIndexToNotify, 2385 uint32_t ulValue, 2386 eNotifyAction eAction, 2387 uint32_t * pulPreviousNotificationValue ) PRIVILEGED_FUNCTION; 2388 #define xTaskNotify( xTaskToNotify, ulValue, eAction ) \ 2389 xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL ) 2390 #define xTaskNotifyIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction ) \ 2391 xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL ) 2392 2393 /** 2394 * @cond !DOC_EXCLUDE_HEADER_SECTION 2395 * task. h 2396 * @code{c} 2397 * BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue ); 2398 * BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue ); 2399 * @endcode 2400 * @endcond 2401 * 2402 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. 2403 * 2404 * xTaskNotifyAndQueryIndexed() performs the same operation as 2405 * xTaskNotifyIndexed() with the addition that it also returns the subject 2406 * task's prior notification value (the notification value at the time the 2407 * function is called rather than when the function returns) in the additional 2408 * pulPreviousNotifyValue parameter. 2409 * 2410 * xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the 2411 * addition that it also returns the subject task's prior notification value 2412 * (the notification value as it was at the time the function is called, rather 2413 * than when the function returns) in the additional pulPreviousNotifyValue 2414 * parameter. 2415 * 2416 * @cond !DOC_SINGLE_GROUP 2417 * \defgroup xTaskNotifyAndQueryIndexed xTaskNotifyAndQueryIndexed 2418 * @endcond 2419 * \ingroup TaskNotifications 2420 */ 2421 #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) \ 2422 xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) 2423 #define xTaskNotifyAndQueryIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotifyValue ) \ 2424 xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) 2425 2426 /** 2427 * @cond !DOC_EXCLUDE_HEADER_SECTION 2428 * task. h 2429 * @code{c} 2430 * BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken ); 2431 * BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken ); 2432 * @endcode 2433 * @endcond 2434 * 2435 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. 2436 * 2437 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these 2438 * functions to be available. 2439 * 2440 * A version of xTaskNotifyIndexed() that can be used from an interrupt service 2441 * routine (ISR). 2442 * 2443 * Each task has a private array of "notification values" (or 'notifications'), 2444 * each of which is a 32-bit unsigned integer (uint32_t). The constant 2445 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the 2446 * array, and (for backward compatibility) defaults to 1 if left undefined. 2447 * Prior to FreeRTOS V10.4.0 there was only one notification value per task. 2448 * 2449 * Events can be sent to a task using an intermediary object. Examples of such 2450 * objects are queues, semaphores, mutexes and event groups. Task notifications 2451 * are a method of sending an event directly to a task without the need for such 2452 * an intermediary object. 2453 * 2454 * A notification sent to a task can optionally perform an action, such as 2455 * update, overwrite or increment one of the task's notification values. In 2456 * that way task notifications can be used to send data to a task, or be used as 2457 * light weight and fast binary or counting semaphores. 2458 * 2459 * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a 2460 * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block 2461 * to wait for a notification value to have a non-zero value. The task does 2462 * not consume any CPU time while it is in the Blocked state. 2463 * 2464 * A notification sent to a task will remain pending until it is cleared by the 2465 * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their 2466 * un-indexed equivalents). If the task was already in the Blocked state to 2467 * wait for a notification when the notification arrives then the task will 2468 * automatically be removed from the Blocked state (unblocked) and the 2469 * notification cleared. 2470 * 2471 * **NOTE** Each notification within the array operates independently - a task 2472 * can only block on one notification within the array at a time and will not be 2473 * unblocked by a notification sent to any other array index. 2474 * 2475 * Backward compatibility information: 2476 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and 2477 * all task notification API functions operated on that value. Replacing the 2478 * single notification value with an array of notification values necessitated a 2479 * new set of API functions that could address specific notifications within the 2480 * array. xTaskNotifyFromISR() is the original API function, and remains 2481 * backward compatible by always operating on the notification value at index 0 2482 * within the array. Calling xTaskNotifyFromISR() is equivalent to calling 2483 * xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0. 2484 * 2485 * @param uxIndexToNotify The index within the target task's array of 2486 * notification values to which the notification is to be sent. uxIndexToNotify 2487 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyFromISR() 2488 * does not have this parameter and always sends notifications to index 0. 2489 * 2490 * @param xTaskToNotify The handle of the task being notified. The handle to a 2491 * task can be returned from the xTaskCreate() API function used to create the 2492 * task, and the handle of the currently running task can be obtained by calling 2493 * xTaskGetCurrentTaskHandle(). 2494 * 2495 * @param ulValue Data that can be sent with the notification. How the data is 2496 * used depends on the value of the eAction parameter. 2497 * 2498 * @param eAction Specifies how the notification updates the task's notification 2499 * value, if at all. Valid values for eAction are as follows: 2500 * 2501 * eSetBits - 2502 * The task's notification value is bitwise ORed with ulValue. xTaskNotify() 2503 * always returns pdPASS in this case. 2504 * 2505 * eIncrement - 2506 * The task's notification value is incremented. ulValue is not used and 2507 * xTaskNotify() always returns pdPASS in this case. 2508 * 2509 * eSetValueWithOverwrite - 2510 * The task's notification value is set to the value of ulValue, even if the 2511 * task being notified had not yet processed the previous notification (the 2512 * task already had a notification pending). xTaskNotify() always returns 2513 * pdPASS in this case. 2514 * 2515 * eSetValueWithoutOverwrite - 2516 * If the task being notified did not already have a notification pending then 2517 * the task's notification value is set to ulValue and xTaskNotify() will 2518 * return pdPASS. If the task being notified already had a notification 2519 * pending then no action is performed and pdFAIL is returned. 2520 * 2521 * eNoAction - 2522 * The task receives a notification without its notification value being 2523 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in 2524 * this case. 2525 * 2526 * @param pxHigherPriorityTaskWoken xTaskNotifyFromISR() will set 2527 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the 2528 * task to which the notification was sent to leave the Blocked state, and the 2529 * unblocked task has a priority higher than the currently running task. If 2530 * xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should 2531 * be requested before the interrupt is exited. How a context switch is 2532 * requested from an ISR is dependent on the port - see the documentation page 2533 * for the port in use. 2534 * 2535 * @return Dependent on the value of eAction. See the description of the 2536 * eAction parameter. 2537 * 2538 * @cond !DOC_SINGLE_GROUP 2539 * \defgroup xTaskNotifyIndexedFromISR xTaskNotifyIndexedFromISR 2540 * @endcond 2541 * \ingroup TaskNotifications 2542 */ 2543 BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, 2544 UBaseType_t uxIndexToNotify, 2545 uint32_t ulValue, 2546 eNotifyAction eAction, 2547 uint32_t * pulPreviousNotificationValue, 2548 BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 2549 #define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \ 2550 xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) 2551 #define xTaskNotifyIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \ 2552 xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) 2553 2554 /** 2555 * @cond !DOC_EXCLUDE_HEADER_SECTION 2556 * task. h 2557 * @code{c} 2558 * BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ); 2559 * BaseType_t xTaskNotifyAndQueryFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ); 2560 * @endcode 2561 * @endcond 2562 * 2563 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. 2564 * 2565 * xTaskNotifyAndQueryIndexedFromISR() performs the same operation as 2566 * xTaskNotifyIndexedFromISR() with the addition that it also returns the 2567 * subject task's prior notification value (the notification value at the time 2568 * the function is called rather than at the time the function returns) in the 2569 * additional pulPreviousNotifyValue parameter. 2570 * 2571 * xTaskNotifyAndQueryFromISR() performs the same operation as 2572 * xTaskNotifyFromISR() with the addition that it also returns the subject 2573 * task's prior notification value (the notification value at the time the 2574 * function is called rather than at the time the function returns) in the 2575 * additional pulPreviousNotifyValue parameter. 2576 * 2577 * @cond !DOC_SINGLE_GROUP 2578 * \defgroup xTaskNotifyAndQueryIndexedFromISR xTaskNotifyAndQueryIndexedFromISR 2579 * @endcond 2580 * \ingroup TaskNotifications 2581 */ 2582 #define xTaskNotifyAndQueryIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \ 2583 xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) ) 2584 #define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \ 2585 xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) ) 2586 2587 /** 2588 * @cond !DOC_EXCLUDE_HEADER_SECTION 2589 * task. h 2590 * @code{c} 2591 * BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); 2592 * 2593 * BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); 2594 * @endcode 2595 * @endcond 2596 * 2597 * Waits for a direct to task notification to be pending at a given index within 2598 * an array of direct to task notifications. 2599 * 2600 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. 2601 * 2602 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 2603 * function to be available. 2604 * 2605 * Each task has a private array of "notification values" (or 'notifications'), 2606 * each of which is a 32-bit unsigned integer (uint32_t). The constant 2607 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the 2608 * array, and (for backward compatibility) defaults to 1 if left undefined. 2609 * Prior to FreeRTOS V10.4.0 there was only one notification value per task. 2610 * 2611 * Events can be sent to a task using an intermediary object. Examples of such 2612 * objects are queues, semaphores, mutexes and event groups. Task notifications 2613 * are a method of sending an event directly to a task without the need for such 2614 * an intermediary object. 2615 * 2616 * A notification sent to a task can optionally perform an action, such as 2617 * update, overwrite or increment one of the task's notification values. In 2618 * that way task notifications can be used to send data to a task, or be used as 2619 * light weight and fast binary or counting semaphores. 2620 * 2621 * A notification sent to a task will remain pending until it is cleared by the 2622 * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their 2623 * un-indexed equivalents). If the task was already in the Blocked state to 2624 * wait for a notification when the notification arrives then the task will 2625 * automatically be removed from the Blocked state (unblocked) and the 2626 * notification cleared. 2627 * 2628 * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a 2629 * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block 2630 * to wait for a notification value to have a non-zero value. The task does 2631 * not consume any CPU time while it is in the Blocked state. 2632 * 2633 * **NOTE** Each notification within the array operates independently - a task 2634 * can only block on one notification within the array at a time and will not be 2635 * unblocked by a notification sent to any other array index. 2636 * 2637 * Backward compatibility information: 2638 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and 2639 * all task notification API functions operated on that value. Replacing the 2640 * single notification value with an array of notification values necessitated a 2641 * new set of API functions that could address specific notifications within the 2642 * array. xTaskNotifyWait() is the original API function, and remains backward 2643 * compatible by always operating on the notification value at index 0 in the 2644 * array. Calling xTaskNotifyWait() is equivalent to calling 2645 * xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0. 2646 * 2647 * @param uxIndexToWaitOn The index within the calling task's array of 2648 * notification values on which the calling task will wait for a notification to 2649 * be received. uxIndexToWaitOn must be less than 2650 * configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyWait() does 2651 * not have this parameter and always waits for notifications on index 0. 2652 * 2653 * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value 2654 * will be cleared in the calling task's notification value before the task 2655 * checks to see if any notifications are pending, and optionally blocks if no 2656 * notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX (if 2657 * limits.h is included) or 0xffffffffUL (if limits.h is not included) will have 2658 * the effect of resetting the task's notification value to 0. Setting 2659 * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged. 2660 * 2661 * @param ulBitsToClearOnExit If a notification is pending or received before 2662 * the calling task exits the xTaskNotifyWait() function then the task's 2663 * notification value (see the xTaskNotify() API function) is passed out using 2664 * the pulNotificationValue parameter. Then any bits that are set in 2665 * ulBitsToClearOnExit will be cleared in the task's notification value (note 2666 * *pulNotificationValue is set before any bits are cleared). Setting 2667 * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL 2668 * (if limits.h is not included) will have the effect of resetting the task's 2669 * notification value to 0 before the function exits. Setting 2670 * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged 2671 * when the function exits (in which case the value passed out in 2672 * pulNotificationValue will match the task's notification value). 2673 * 2674 * @param pulNotificationValue Used to pass the task's notification value out 2675 * of the function. Note the value passed out will not be effected by the 2676 * clearing of any bits caused by ulBitsToClearOnExit being non-zero. 2677 * 2678 * @param xTicksToWait The maximum amount of time that the task should wait in 2679 * the Blocked state for a notification to be received, should a notification 2680 * not already be pending when xTaskNotifyWait() was called. The task 2681 * will not consume any processing time while it is in the Blocked state. This 2682 * is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be 2683 * used to convert a time specified in milliseconds to a time specified in 2684 * ticks. 2685 * 2686 * @return If a notification was received (including notifications that were 2687 * already pending when xTaskNotifyWait was called) then pdPASS is 2688 * returned. Otherwise pdFAIL is returned. 2689 * 2690 * @cond !DOC_SINGLE_GROUP 2691 * \defgroup xTaskNotifyWaitIndexed xTaskNotifyWaitIndexed 2692 * @endcond 2693 * \ingroup TaskNotifications 2694 */ 2695 BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, 2696 uint32_t ulBitsToClearOnEntry, 2697 uint32_t ulBitsToClearOnExit, 2698 uint32_t * pulNotificationValue, 2699 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 2700 #define xTaskNotifyWait( ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \ 2701 xTaskGenericNotifyWait( tskDEFAULT_INDEX_TO_NOTIFY, ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) ) 2702 #define xTaskNotifyWaitIndexed( uxIndexToWaitOn, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \ 2703 xTaskGenericNotifyWait( ( uxIndexToWaitOn ), ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) ) 2704 2705 /** 2706 * @cond !DOC_EXCLUDE_HEADER_SECTION 2707 * task. h 2708 * @code{c} 2709 * BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify ); 2710 * BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify ); 2711 * @endcode 2712 * @endcond 2713 * 2714 * Sends a direct to task notification to a particular index in the target 2715 * task's notification array in a manner similar to giving a counting semaphore. 2716 * 2717 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details. 2718 * 2719 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these 2720 * macros to be available. 2721 * 2722 * Each task has a private array of "notification values" (or 'notifications'), 2723 * each of which is a 32-bit unsigned integer (uint32_t). The constant 2724 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the 2725 * array, and (for backward compatibility) defaults to 1 if left undefined. 2726 * Prior to FreeRTOS V10.4.0 there was only one notification value per task. 2727 * 2728 * Events can be sent to a task using an intermediary object. Examples of such 2729 * objects are queues, semaphores, mutexes and event groups. Task notifications 2730 * are a method of sending an event directly to a task without the need for such 2731 * an intermediary object. 2732 * 2733 * A notification sent to a task can optionally perform an action, such as 2734 * update, overwrite or increment one of the task's notification values. In 2735 * that way task notifications can be used to send data to a task, or be used as 2736 * light weight and fast binary or counting semaphores. 2737 * 2738 * xTaskNotifyGiveIndexed() is a helper macro intended for use when task 2739 * notifications are used as light weight and faster binary or counting 2740 * semaphore equivalents. Actual FreeRTOS semaphores are given using the 2741 * xSemaphoreGive() API function, the equivalent action that instead uses a task 2742 * notification is xTaskNotifyGiveIndexed(). 2743 * 2744 * When task notifications are being used as a binary or counting semaphore 2745 * equivalent then the task being notified should wait for the notification 2746 * using the ulTaskNotificationTakeIndexed() API function rather than the 2747 * xTaskNotifyWaitIndexed() API function. 2748 * 2749 * **NOTE** Each notification within the array operates independently - a task 2750 * can only block on one notification within the array at a time and will not be 2751 * unblocked by a notification sent to any other array index. 2752 * 2753 * Backward compatibility information: 2754 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and 2755 * all task notification API functions operated on that value. Replacing the 2756 * single notification value with an array of notification values necessitated a 2757 * new set of API functions that could address specific notifications within the 2758 * array. xTaskNotifyGive() is the original API function, and remains backward 2759 * compatible by always operating on the notification value at index 0 in the 2760 * array. Calling xTaskNotifyGive() is equivalent to calling 2761 * xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0. 2762 * 2763 * @param xTaskToNotify The handle of the task being notified. The handle to a 2764 * task can be returned from the xTaskCreate() API function used to create the 2765 * task, and the handle of the currently running task can be obtained by calling 2766 * xTaskGetCurrentTaskHandle(). 2767 * 2768 * @param uxIndexToNotify The index within the target task's array of 2769 * notification values to which the notification is to be sent. uxIndexToNotify 2770 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGive() 2771 * does not have this parameter and always sends notifications to index 0. 2772 * 2773 * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the 2774 * eAction parameter set to eIncrement - so pdPASS is always returned. 2775 * 2776 * @cond !DOC_SINGLE_GROUP 2777 * \defgroup xTaskNotifyGiveIndexed xTaskNotifyGiveIndexed 2778 * @endcond 2779 * \ingroup TaskNotifications 2780 */ 2781 #define xTaskNotifyGive( xTaskToNotify ) \ 2782 xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL ) 2783 #define xTaskNotifyGiveIndexed( xTaskToNotify, uxIndexToNotify ) \ 2784 xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ), eIncrement, NULL ) 2785 2786 /** 2787 * @cond !DOC_EXCLUDE_HEADER_SECTION 2788 * task. h 2789 * @code{c} 2790 * void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken ); 2791 * void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken ); 2792 * @endcode 2793 * @endcond 2794 * 2795 * A version of xTaskNotifyGiveIndexed() that can be called from an interrupt 2796 * service routine (ISR). 2797 * 2798 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details. 2799 * 2800 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro 2801 * to be available. 2802 * 2803 * Each task has a private array of "notification values" (or 'notifications'), 2804 * each of which is a 32-bit unsigned integer (uint32_t). The constant 2805 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the 2806 * array, and (for backward compatibility) defaults to 1 if left undefined. 2807 * Prior to FreeRTOS V10.4.0 there was only one notification value per task. 2808 * 2809 * Events can be sent to a task using an intermediary object. Examples of such 2810 * objects are queues, semaphores, mutexes and event groups. Task notifications 2811 * are a method of sending an event directly to a task without the need for such 2812 * an intermediary object. 2813 * 2814 * A notification sent to a task can optionally perform an action, such as 2815 * update, overwrite or increment one of the task's notification values. In 2816 * that way task notifications can be used to send data to a task, or be used as 2817 * light weight and fast binary or counting semaphores. 2818 * 2819 * vTaskNotifyGiveIndexedFromISR() is intended for use when task notifications 2820 * are used as light weight and faster binary or counting semaphore equivalents. 2821 * Actual FreeRTOS semaphores are given from an ISR using the 2822 * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses 2823 * a task notification is vTaskNotifyGiveIndexedFromISR(). 2824 * 2825 * When task notifications are being used as a binary or counting semaphore 2826 * equivalent then the task being notified should wait for the notification 2827 * using the ulTaskNotificationTakeIndexed() API function rather than the 2828 * xTaskNotifyWaitIndexed() API function. 2829 * 2830 * **NOTE** Each notification within the array operates independently - a task 2831 * can only block on one notification within the array at a time and will not be 2832 * unblocked by a notification sent to any other array index. 2833 * 2834 * Backward compatibility information: 2835 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and 2836 * all task notification API functions operated on that value. Replacing the 2837 * single notification value with an array of notification values necessitated a 2838 * new set of API functions that could address specific notifications within the 2839 * array. xTaskNotifyFromISR() is the original API function, and remains 2840 * backward compatible by always operating on the notification value at index 0 2841 * within the array. Calling xTaskNotifyGiveFromISR() is equivalent to calling 2842 * xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0. 2843 * 2844 * @param xTaskToNotify The handle of the task being notified. The handle to a 2845 * task can be returned from the xTaskCreate() API function used to create the 2846 * task, and the handle of the currently running task can be obtained by calling 2847 * xTaskGetCurrentTaskHandle(). 2848 * 2849 * @param uxIndexToNotify The index within the target task's array of 2850 * notification values to which the notification is to be sent. uxIndexToNotify 2851 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. 2852 * xTaskNotifyGiveFromISR() does not have this parameter and always sends 2853 * notifications to index 0. 2854 * 2855 * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set 2856 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the 2857 * task to which the notification was sent to leave the Blocked state, and the 2858 * unblocked task has a priority higher than the currently running task. If 2859 * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch 2860 * should be requested before the interrupt is exited. How a context switch is 2861 * requested from an ISR is dependent on the port - see the documentation page 2862 * for the port in use. 2863 * 2864 * @cond !DOC_SINGLE_GROUP 2865 * \defgroup vTaskNotifyGiveIndexedFromISR vTaskNotifyGiveIndexedFromISR 2866 * @endcond 2867 * \ingroup TaskNotifications 2868 */ 2869 void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, 2870 UBaseType_t uxIndexToNotify, 2871 BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 2872 #define vTaskNotifyGiveFromISR( xTaskToNotify, pxHigherPriorityTaskWoken ) \ 2873 vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( pxHigherPriorityTaskWoken ) ); 2874 #define vTaskNotifyGiveIndexedFromISR( xTaskToNotify, uxIndexToNotify, pxHigherPriorityTaskWoken ) \ 2875 vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( pxHigherPriorityTaskWoken ) ); 2876 2877 /** 2878 * @cond !DOC_EXCLUDE_HEADER_SECTION 2879 * task. h 2880 * @code{c} 2881 * uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait ); 2882 * 2883 * uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait ); 2884 * @endcode 2885 * @endcond 2886 * 2887 * Waits for a direct to task notification on a particular index in the calling 2888 * task's notification array in a manner similar to taking a counting semaphore. 2889 * 2890 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. 2891 * 2892 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 2893 * function to be available. 2894 * 2895 * Each task has a private array of "notification values" (or 'notifications'), 2896 * each of which is a 32-bit unsigned integer (uint32_t). The constant 2897 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the 2898 * array, and (for backward compatibility) defaults to 1 if left undefined. 2899 * Prior to FreeRTOS V10.4.0 there was only one notification value per task. 2900 * 2901 * Events can be sent to a task using an intermediary object. Examples of such 2902 * objects are queues, semaphores, mutexes and event groups. Task notifications 2903 * are a method of sending an event directly to a task without the need for such 2904 * an intermediary object. 2905 * 2906 * A notification sent to a task can optionally perform an action, such as 2907 * update, overwrite or increment one of the task's notification values. In 2908 * that way task notifications can be used to send data to a task, or be used as 2909 * light weight and fast binary or counting semaphores. 2910 * 2911 * ulTaskNotifyTakeIndexed() is intended for use when a task notification is 2912 * used as a faster and lighter weight binary or counting semaphore alternative. 2913 * Actual FreeRTOS semaphores are taken using the xSemaphoreTake() API function, 2914 * the equivalent action that instead uses a task notification is 2915 * ulTaskNotifyTakeIndexed(). 2916 * 2917 * When a task is using its notification value as a binary or counting semaphore 2918 * other tasks should send notifications to it using the xTaskNotifyGiveIndexed() 2919 * macro, or xTaskNotifyIndex() function with the eAction parameter set to 2920 * eIncrement. 2921 * 2922 * ulTaskNotifyTakeIndexed() can either clear the task's notification value at 2923 * the array index specified by the uxIndexToWaitOn parameter to zero on exit, 2924 * in which case the notification value acts like a binary semaphore, or 2925 * decrement the notification value on exit, in which case the notification 2926 * value acts like a counting semaphore. 2927 * 2928 * A task can use ulTaskNotifyTakeIndexed() to [optionally] block to wait for 2929 * the task's notification value to be non-zero. The task does not consume any 2930 * CPU time while it is in the Blocked state. 2931 * 2932 * Where as xTaskNotifyWaitIndexed() will return when a notification is pending, 2933 * ulTaskNotifyTakeIndexed() will return when the task's notification value is 2934 * not zero. 2935 * 2936 * **NOTE** Each notification within the array operates independently - a task 2937 * can only block on one notification within the array at a time and will not be 2938 * unblocked by a notification sent to any other array index. 2939 * 2940 * Backward compatibility information: 2941 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and 2942 * all task notification API functions operated on that value. Replacing the 2943 * single notification value with an array of notification values necessitated a 2944 * new set of API functions that could address specific notifications within the 2945 * array. ulTaskNotifyTake() is the original API function, and remains backward 2946 * compatible by always operating on the notification value at index 0 in the 2947 * array. Calling ulTaskNotifyTake() is equivalent to calling 2948 * ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0. 2949 * 2950 * @param uxIndexToWaitOn The index within the calling task's array of 2951 * notification values on which the calling task will wait for a notification to 2952 * be non-zero. uxIndexToWaitOn must be less than 2953 * configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyTake() does 2954 * not have this parameter and always waits for notifications on index 0. 2955 * 2956 * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's 2957 * notification value is decremented when the function exits. In this way the 2958 * notification value acts like a counting semaphore. If xClearCountOnExit is 2959 * not pdFALSE then the task's notification value is cleared to zero when the 2960 * function exits. In this way the notification value acts like a binary 2961 * semaphore. 2962 * 2963 * @param xTicksToWait The maximum amount of time that the task should wait in 2964 * the Blocked state for the task's notification value to be greater than zero, 2965 * should the count not already be greater than zero when 2966 * ulTaskNotifyTake() was called. The task will not consume any processing 2967 * time while it is in the Blocked state. This is specified in kernel ticks, 2968 * the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time 2969 * specified in milliseconds to a time specified in ticks. 2970 * 2971 * @return The task's notification count before it is either cleared to zero or 2972 * decremented (see the xClearCountOnExit parameter). 2973 * 2974 * @cond !DOC_SINGLE_GROUP 2975 * \defgroup ulTaskNotifyTakeIndexed ulTaskNotifyTakeIndexed 2976 * @endcond 2977 * \ingroup TaskNotifications 2978 */ 2979 uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWaitOn, 2980 BaseType_t xClearCountOnExit, 2981 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 2982 #define ulTaskNotifyTake( xClearCountOnExit, xTicksToWait ) \ 2983 ulTaskGenericNotifyTake( ( tskDEFAULT_INDEX_TO_NOTIFY ), ( xClearCountOnExit ), ( xTicksToWait ) ) 2984 #define ulTaskNotifyTakeIndexed( uxIndexToWaitOn, xClearCountOnExit, xTicksToWait ) \ 2985 ulTaskGenericNotifyTake( ( uxIndexToWaitOn ), ( xClearCountOnExit ), ( xTicksToWait ) ) 2986 2987 /** 2988 * @cond !DOC_EXCLUDE_HEADER_SECTION 2989 * task. h 2990 * @code{c} 2991 * BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToCLear ); 2992 * 2993 * BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask ); 2994 * @endcode 2995 * @endcond 2996 * 2997 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. 2998 * 2999 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these 3000 * functions to be available. 3001 * 3002 * Each task has a private array of "notification values" (or 'notifications'), 3003 * each of which is a 32-bit unsigned integer (uint32_t). The constant 3004 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the 3005 * array, and (for backward compatibility) defaults to 1 if left undefined. 3006 * Prior to FreeRTOS V10.4.0 there was only one notification value per task. 3007 * 3008 * If a notification is sent to an index within the array of notifications then 3009 * the notification at that index is said to be 'pending' until it is read or 3010 * explicitly cleared by the receiving task. xTaskNotifyStateClearIndexed() 3011 * is the function that clears a pending notification without reading the 3012 * notification value. The notification value at the same array index is not 3013 * altered. Set xTask to NULL to clear the notification state of the calling 3014 * task. 3015 * 3016 * Backward compatibility information: 3017 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and 3018 * all task notification API functions operated on that value. Replacing the 3019 * single notification value with an array of notification values necessitated a 3020 * new set of API functions that could address specific notifications within the 3021 * array. xTaskNotifyStateClear() is the original API function, and remains 3022 * backward compatible by always operating on the notification value at index 0 3023 * within the array. Calling xTaskNotifyStateClear() is equivalent to calling 3024 * xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0. 3025 * 3026 * @param xTask The handle of the RTOS task that will have a notification state 3027 * cleared. Set xTask to NULL to clear a notification state in the calling 3028 * task. To obtain a task's handle create the task using xTaskCreate() and 3029 * make use of the pxCreatedTask parameter, or create the task using 3030 * xTaskCreateStatic() and store the returned value, or use the task's name in 3031 * a call to xTaskGetHandle(). 3032 * 3033 * @param uxIndexToClear The index within the target task's array of 3034 * notification values to act upon. For example, setting uxIndexToClear to 1 3035 * will clear the state of the notification at index 1 within the array. 3036 * uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. 3037 * ulTaskNotifyStateClear() does not have this parameter and always acts on the 3038 * notification at index 0. 3039 * 3040 * @return pdTRUE if the task's notification state was set to 3041 * eNotWaitingNotification, otherwise pdFALSE. 3042 * 3043 * @cond !DOC_SINGLE_GROUP 3044 * \defgroup xTaskNotifyStateClearIndexed xTaskNotifyStateClearIndexed 3045 * @endcond 3046 * \ingroup TaskNotifications 3047 */ 3048 BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, 3049 UBaseType_t uxIndexToClear ) PRIVILEGED_FUNCTION; 3050 #define xTaskNotifyStateClear( xTask ) \ 3051 xTaskGenericNotifyStateClear( ( xTask ), ( tskDEFAULT_INDEX_TO_NOTIFY ) ) 3052 #define xTaskNotifyStateClearIndexed( xTask, uxIndexToClear ) \ 3053 xTaskGenericNotifyStateClear( ( xTask ), ( uxIndexToClear ) ) 3054 3055 /** 3056 * @cond !DOC_EXCLUDE_HEADER_SECTION 3057 * task. h 3058 * @code{c} 3059 * uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear ); 3060 * 3061 * uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear ); 3062 * @endcode 3063 * @endcond 3064 * 3065 * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. 3066 * 3067 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these 3068 * functions to be available. 3069 * 3070 * Each task has a private array of "notification values" (or 'notifications'), 3071 * each of which is a 32-bit unsigned integer (uint32_t). The constant 3072 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the 3073 * array, and (for backward compatibility) defaults to 1 if left undefined. 3074 * Prior to FreeRTOS V10.4.0 there was only one notification value per task. 3075 * 3076 * ulTaskNotifyValueClearIndexed() clears the bits specified by the 3077 * ulBitsToClear bit mask in the notification value at array index uxIndexToClear 3078 * of the task referenced by xTask. 3079 * 3080 * Backward compatibility information: 3081 * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and 3082 * all task notification API functions operated on that value. Replacing the 3083 * single notification value with an array of notification values necessitated a 3084 * new set of API functions that could address specific notifications within the 3085 * array. ulTaskNotifyValueClear() is the original API function, and remains 3086 * backward compatible by always operating on the notification value at index 0 3087 * within the array. Calling ulTaskNotifyValueClear() is equivalent to calling 3088 * ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0. 3089 * 3090 * @param xTask The handle of the RTOS task that will have bits in one of its 3091 * notification values cleared. Set xTask to NULL to clear bits in a 3092 * notification value of the calling task. To obtain a task's handle create the 3093 * task using xTaskCreate() and make use of the pxCreatedTask parameter, or 3094 * create the task using xTaskCreateStatic() and store the returned value, or 3095 * use the task's name in a call to xTaskGetHandle(). 3096 * 3097 * @param uxIndexToClear The index within the target task's array of 3098 * notification values in which to clear the bits. uxIndexToClear 3099 * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. 3100 * ulTaskNotifyValueClear() does not have this parameter and always clears bits 3101 * in the notification value at index 0. 3102 * 3103 * @param ulBitsToClear Bit mask of the bits to clear in the notification value of 3104 * xTask. Set a bit to 1 to clear the corresponding bits in the task's notification 3105 * value. Set ulBitsToClear to 0xffffffff (UINT_MAX on 32-bit architectures) to clear 3106 * the notification value to 0. Set ulBitsToClear to 0 to query the task's 3107 * notification value without clearing any bits. 3108 * 3109 * 3110 * @return The value of the target task's notification value before the bits 3111 * specified by ulBitsToClear were cleared. 3112 * @cond !DOC_SINGLE_GROUP 3113 * \defgroup ulTaskNotifyValueClear ulTaskNotifyValueClear 3114 * @endcond 3115 * \ingroup TaskNotifications 3116 */ 3117 uint32_t ulTaskGenericNotifyValueClear( TaskHandle_t xTask, 3118 UBaseType_t uxIndexToClear, 3119 uint32_t ulBitsToClear ) PRIVILEGED_FUNCTION; 3120 #define ulTaskNotifyValueClear( xTask, ulBitsToClear ) \ 3121 ulTaskGenericNotifyValueClear( ( xTask ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulBitsToClear ) ) 3122 #define ulTaskNotifyValueClearIndexed( xTask, uxIndexToClear, ulBitsToClear ) \ 3123 ulTaskGenericNotifyValueClear( ( xTask ), ( uxIndexToClear ), ( ulBitsToClear ) ) 3124 3125 /** 3126 * @cond !DOC_EXCLUDE_HEADER_SECTION 3127 * task.h 3128 * @code{c} 3129 * void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ); 3130 * @endcode 3131 * @endcond 3132 * 3133 * Capture the current time for future use with xTaskCheckForTimeOut(). 3134 * 3135 * @param pxTimeOut Pointer to a timeout object into which the current time 3136 * is to be captured. The captured time includes the tick count and the number 3137 * of times the tick count has overflowed since the system first booted. 3138 * \defgroup vTaskSetTimeOutState vTaskSetTimeOutState 3139 * @cond !DOC_SINGLE_GROUP 3140 * \ingroup TaskCtrl 3141 * @endcond 3142 */ 3143 void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION; 3144 3145 /** 3146 * @cond !DOC_EXCLUDE_HEADER_SECTION 3147 * task.h 3148 * @code 3149 * BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ); 3150 * @endcode 3151 * @endcond 3152 * 3153 * Determines if pxTicksToWait ticks has passed since a time was captured 3154 * using a call to vTaskSetTimeOutState(). The captured time includes the tick 3155 * count and the number of times the tick count has overflowed. 3156 * 3157 * @param pxTimeOut The time status as captured previously using 3158 * vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated 3159 * to reflect the current time status. 3160 * @param pxTicksToWait The number of ticks to check for timeout i.e. if 3161 * pxTicksToWait ticks have passed since pxTimeOut was last updated (either by 3162 * vTaskSetTimeOutState() or xTaskCheckForTimeOut()), the timeout has occurred. 3163 * If the timeout has not occurred, pxTicksToWait is updated to reflect the 3164 * number of remaining ticks. 3165 * 3166 * @return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is 3167 * returned and pxTicksToWait is updated to reflect the number of remaining 3168 * ticks. 3169 * 3170 * @see https://www.FreeRTOS.org/xTaskCheckForTimeOut.html 3171 * 3172 * Example Usage: 3173 * @code 3174 * // Driver library function used to receive uxWantedBytes from an Rx buffer 3175 * // that is filled by a UART interrupt. If there are not enough bytes in the 3176 * // Rx buffer then the task enters the Blocked state until it is notified that 3177 * // more data has been placed into the buffer. If there is still not enough 3178 * // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut() 3179 * // is used to re-calculate the Block time to ensure the total amount of time 3180 * // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This 3181 * // continues until either the buffer contains at least uxWantedBytes bytes, 3182 * // or the total amount of time spent in the Blocked state reaches 3183 * // MAX_TIME_TO_WAIT – at which point the task reads however many bytes are 3184 * // available up to a maximum of uxWantedBytes. 3185 * 3186 * size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes ) 3187 * { 3188 * size_t uxReceived = 0; 3189 * TickType_t xTicksToWait = MAX_TIME_TO_WAIT; 3190 * TimeOut_t xTimeOut; 3191 * 3192 * // Initialize xTimeOut. This records the time at which this function 3193 * // was entered. 3194 * vTaskSetTimeOutState( &xTimeOut ); 3195 * 3196 * // Loop until the buffer contains the wanted number of bytes, or a 3197 * // timeout occurs. 3198 * while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes ) 3199 * { 3200 * // The buffer didn't contain enough data so this task is going to 3201 * // enter the Blocked state. Adjusting xTicksToWait to account for 3202 * // any time that has been spent in the Blocked state within this 3203 * // function so far to ensure the total amount of time spent in the 3204 * // Blocked state does not exceed MAX_TIME_TO_WAIT. 3205 * if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE ) 3206 * { 3207 * //Timed out before the wanted number of bytes were available, 3208 * // exit the loop. 3209 * break; 3210 * } 3211 * 3212 * // Wait for a maximum of xTicksToWait ticks to be notified that the 3213 * // receive interrupt has placed more data into the buffer. 3214 * ulTaskNotifyTake( pdTRUE, xTicksToWait ); 3215 * } 3216 * 3217 * // Attempt to read uxWantedBytes from the receive buffer into pucBuffer. 3218 * // The actual number of bytes read (which might be less than 3219 * // uxWantedBytes) is returned. 3220 * uxReceived = UART_read_from_receive_buffer( pxUARTInstance, 3221 * pucBuffer, 3222 * uxWantedBytes ); 3223 * 3224 * return uxReceived; 3225 * } 3226 * @endcode 3227 * @cond !DOC_SINGLE_GROUP 3228 * \defgroup xTaskCheckForTimeOut xTaskCheckForTimeOut 3229 * @endcond 3230 * \ingroup TaskCtrl 3231 */ 3232 BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, 3233 TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION; 3234 3235 /** 3236 * @cond !DOC_EXCLUDE_HEADER_SECTION 3237 * task.h 3238 * @code{c} 3239 * BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp ); 3240 * @endcode 3241 * @endcond 3242 * 3243 * This function corrects the tick count value after the application code has held 3244 * interrupts disabled for an extended period resulting in tick interrupts having 3245 * been missed. 3246 * 3247 * This function is similar to vTaskStepTick(), however, unlike 3248 * vTaskStepTick(), xTaskCatchUpTicks() may move the tick count forward past a 3249 * time at which a task should be removed from the blocked state. That means 3250 * tasks may have to be removed from the blocked state as the tick count is 3251 * moved. 3252 * 3253 * @param xTicksToCatchUp The number of tick interrupts that have been missed due to 3254 * interrupts being disabled. Its value is not computed automatically, so must be 3255 * computed by the application writer. 3256 * 3257 * @return pdTRUE if moving the tick count forward resulted in a task leaving the 3258 * blocked state and a context switch being performed. Otherwise pdFALSE. 3259 * 3260 * \defgroup xTaskCatchUpTicks xTaskCatchUpTicks 3261 * @cond !DOC_SINGLE_GROUP 3262 * \ingroup TaskCtrl 3263 * @endcond 3264 */ 3265 BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp ) PRIVILEGED_FUNCTION; 3266 3267 3268 /*----------------------------------------------------------- 3269 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES 3270 *----------------------------------------------------------*/ 3271 /** @cond !DOC_EXCLUDE_HEADER_SECTION */ 3272 /* 3273 * Return the handle of the task running on a certain CPU. Because of 3274 * the nature of SMP processing, there is no guarantee that this 3275 * value will still be valid on return and should only be used for 3276 * debugging purposes. 3277 */ 3278 TaskHandle_t xTaskGetCurrentTaskHandleForCPU( BaseType_t cpuid ); 3279 3280 /** 3281 * Get the handle of idle task for the given CPU. 3282 * 3283 * xTaskGetIdleTaskHandleForCPU() is only available if 3284 * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h. 3285 * 3286 * @param cpuid The CPU to get the handle for 3287 * 3288 * @return Idle task handle of a given cpu. It is not valid to call 3289 * xTaskGetIdleTaskHandleForCPU() before the scheduler has been started. 3290 */ 3291 TaskHandle_t xTaskGetIdleTaskHandleForCPU( UBaseType_t cpuid ); 3292 3293 /* 3294 * Get the current core affinity of a task 3295 */ 3296 BaseType_t xTaskGetAffinity( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 3297 3298 /* 3299 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 3300 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 3301 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 3302 * 3303 * Called from the real time kernel tick (either preemptive or cooperative), 3304 * this increments the tick count and checks if any tasks that are blocked 3305 * for a finite period required removing from a blocked list and placing on 3306 * a ready list. If a non-zero value is returned then a context switch is 3307 * required because either: 3308 * + A task was removed from a blocked list because its timeout had expired, 3309 * or 3310 * + Time slicing is in use and there is a task of equal priority to the 3311 * currently running task. 3312 */ 3313 BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION; 3314 3315 /* 3316 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 3317 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 3318 * 3319 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 3320 * 3321 * Removes the calling task from the ready list and places it both 3322 * on the list of tasks waiting for a particular event, and the 3323 * list of delayed tasks. The task will be removed from both lists 3324 * and replaced on the ready list should either the event occur (and 3325 * there be no higher priority tasks waiting on the same event) or 3326 * the delay period expires. 3327 * 3328 * The 'unordered' version replaces the event list item value with the 3329 * xItemValue value, and inserts the list item at the end of the list. 3330 * 3331 * The 'ordered' version uses the existing event list item value (which is the 3332 * owning task's priority) to insert the list item into the event list in task 3333 * priority order. 3334 * 3335 * @param pxEventList The list containing tasks that are blocked waiting 3336 * for the event to occur. 3337 * 3338 * @param xItemValue The item value to use for the event list item when the 3339 * event list is not ordered by task priority. 3340 * 3341 * @param xTicksToWait The maximum amount of time that the task should wait 3342 * for the event to occur. This is specified in kernel ticks, the constant 3343 * portTICK_PERIOD_MS can be used to convert kernel ticks into a real time 3344 * period. 3345 */ 3346 void vTaskPlaceOnEventList( List_t * const pxEventList, 3347 const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 3348 void vTaskPlaceOnUnorderedEventList( List_t * pxEventList, 3349 const TickType_t xItemValue, 3350 const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 3351 3352 /* 3353 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 3354 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 3355 * 3356 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 3357 * 3358 * This function performs nearly the same function as vTaskPlaceOnEventList(). 3359 * The difference being that this function does not permit tasks to block 3360 * indefinitely, whereas vTaskPlaceOnEventList() does. 3361 * 3362 */ 3363 void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, 3364 TickType_t xTicksToWait, 3365 const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION; 3366 3367 /* 3368 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 3369 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 3370 * 3371 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 3372 * 3373 * Removes a task from both the specified event list and the list of blocked 3374 * tasks, and places it on a ready queue. 3375 * 3376 * xTaskRemoveFromEventList()/vTaskRemoveFromUnorderedEventList() will be called 3377 * if either an event occurs to unblock a task, or the block timeout period 3378 * expires. 3379 * 3380 * xTaskRemoveFromEventList() is used when the event list is in task priority 3381 * order. It removes the list item from the head of the event list as that will 3382 * have the highest priority owning task of all the tasks on the event list. 3383 * vTaskRemoveFromUnorderedEventList() is used when the event list is not 3384 * ordered and the event list items hold something other than the owning tasks 3385 * priority. In this case the event list item value is updated to the value 3386 * passed in the xItemValue parameter. 3387 * 3388 * @return pdTRUE if the task being removed has a higher priority than the task 3389 * making the call, otherwise pdFALSE. 3390 */ 3391 BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList ) PRIVILEGED_FUNCTION; 3392 void vTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem, 3393 const TickType_t xItemValue ) PRIVILEGED_FUNCTION; 3394 3395 /* 3396 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 3397 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 3398 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 3399 * 3400 * Sets the pointer to the current TCB to the TCB of the highest priority task 3401 * that is ready to run. 3402 */ 3403 portDONT_DISCARD void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION; 3404 3405 /* 3406 * THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE. THEY ARE USED BY 3407 * THE EVENT BITS MODULE. 3408 */ 3409 TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION; 3410 3411 /* 3412 * Return the handle of the calling task. 3413 */ 3414 TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION; 3415 3416 /* 3417 * Shortcut used by the queue implementation to prevent unnecessary call to 3418 * taskYIELD(); 3419 */ 3420 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION; 3421 3422 /* 3423 * Returns the scheduler state as taskSCHEDULER_RUNNING, 3424 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED. 3425 */ 3426 BaseType_t xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION; 3427 3428 /* 3429 * Raises the priority of the mutex holder to that of the calling task should 3430 * the mutex holder have a priority less than the calling task. 3431 */ 3432 BaseType_t xTaskPriorityInherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION; 3433 3434 /* 3435 * Set the priority of a task back to its proper priority in the case that it 3436 * inherited a higher priority while it was holding a semaphore. 3437 */ 3438 BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION; 3439 3440 /* 3441 * If a higher priority task attempting to obtain a mutex caused a lower 3442 * priority task to inherit the higher priority task's priority - but the higher 3443 * priority task then timed out without obtaining the mutex, then the lower 3444 * priority task will disinherit the priority again - but only down as far as 3445 * the highest priority task that is still waiting for the mutex (if there were 3446 * more than one task waiting for the mutex). 3447 */ 3448 void vTaskPriorityDisinheritAfterTimeout( TaskHandle_t const pxMutexHolder, 3449 UBaseType_t uxHighestPriorityWaitingTask ) PRIVILEGED_FUNCTION; 3450 3451 /* 3452 * Get the uxTCBNumber assigned to the task referenced by the xTask parameter. 3453 */ 3454 UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 3455 3456 /* 3457 * Set the uxTaskNumber of the task referenced by the xTask parameter to 3458 * uxHandle. 3459 */ 3460 void vTaskSetTaskNumber( TaskHandle_t xTask, 3461 const UBaseType_t uxHandle ) PRIVILEGED_FUNCTION; 3462 3463 /* 3464 * Only available when configUSE_TICKLESS_IDLE is set to 1. 3465 * If tickless mode is being used, or a low power mode is implemented, then 3466 * the tick interrupt will not execute during idle periods. When this is the 3467 * case, the tick count value maintained by the scheduler needs to be kept up 3468 * to date with the actual execution time by being skipped forward by a time 3469 * equal to the idle period. 3470 */ 3471 void vTaskStepTick( const TickType_t xTicksToJump ) PRIVILEGED_FUNCTION; 3472 3473 /* 3474 * Only available when configUSE_TICKLESS_IDLE is set to 1. 3475 * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port 3476 * specific sleep function to determine if it is ok to proceed with the sleep, 3477 * and if it is ok to proceed, if it is ok to sleep indefinitely. 3478 * 3479 * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only 3480 * called with the scheduler suspended, not from within a critical section. It 3481 * is therefore possible for an interrupt to request a context switch between 3482 * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being 3483 * entered. eTaskConfirmSleepModeStatus() should be called from a short 3484 * critical section between the timer being stopped and the sleep mode being 3485 * entered to ensure it is ok to proceed into the sleep mode. 3486 */ 3487 eSleepModeStatus eTaskConfirmSleepModeStatus( void ) PRIVILEGED_FUNCTION; 3488 3489 /* 3490 * For internal use only. Increment the mutex held count when a mutex is 3491 * taken and return the handle of the task that has taken the mutex. 3492 */ 3493 TaskHandle_t pvTaskIncrementMutexHeldCount( void ) PRIVILEGED_FUNCTION; 3494 3495 /* 3496 * For internal use only. Same as vTaskSetTimeOutState(), but without a critical 3497 * section. 3498 */ 3499 void vTaskInternalSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION; 3500 3501 #ifdef ESP_PLATFORM 3502 /* TODO: IDF-3683 */ 3503 #include "freertos/task_snapshot.h" 3504 #endif // ESP_PLATFORM 3505 3506 /** @endcond */ 3507 3508 #ifdef __cplusplus 3509 } 3510 #endif 3511 /* *INDENT-ON* */ 3512 #endif /* INC_TASK_H */ 3513
