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