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