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