1 /* 2 FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd. 3 All rights reserved 4 5 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. 6 7 This file is part of the FreeRTOS distribution. 8 9 FreeRTOS is free software; you can redistribute it and/or modify it under 10 the terms of the GNU General Public License (version 2) as published by the 11 Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception. 12 13 *************************************************************************** 14 >>! NOTE: The modification to the GPL is included to allow you to !<< 15 >>! distribute a combined work that includes FreeRTOS without being !<< 16 >>! obliged to provide the source code for proprietary components !<< 17 >>! outside of the FreeRTOS kernel. !<< 18 *************************************************************************** 19 20 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY 21 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 22 FOR A PARTICULAR PURPOSE. Full license text is available on the following 23 link: http://www.freertos.org/a00114.html 24 25 *************************************************************************** 26 * * 27 * FreeRTOS provides completely free yet professionally developed, * 28 * robust, strictly quality controlled, supported, and cross * 29 * platform software that is more than just the market leader, it * 30 * is the industry's de facto standard. * 31 * * 32 * Help yourself get started quickly while simultaneously helping * 33 * to support the FreeRTOS project by purchasing a FreeRTOS * 34 * tutorial book, reference manual, or both: * 35 * http://www.FreeRTOS.org/Documentation * 36 * * 37 *************************************************************************** 38 39 http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading 40 the FAQ page "My application does not run, what could be wrong?". Have you 41 defined configASSERT()? 42 43 http://www.FreeRTOS.org/support - In return for receiving this top quality 44 embedded software for free we request you assist our global community by 45 participating in the support forum. 46 47 http://www.FreeRTOS.org/training - Investing in training allows your team to 48 be as productive as possible as early as possible. Now you can receive 49 FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers 50 Ltd, and the world's leading authority on the world's leading RTOS. 51 52 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products, 53 including FreeRTOS+Trace - an indispensable productivity tool, a DOS 54 compatible FAT file system, and our tiny thread aware UDP/IP stack. 55 56 http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate. 57 Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS. 58 59 http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High 60 Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS 61 licenses offer ticketed support, indemnification and commercial middleware. 62 63 http://www.SafeRTOS.com - High Integrity Systems also provide a safety 64 engineered and independently SIL3 certified version for use in safety and 65 mission critical applications that require provable dependability. 66 67 1 tab == 4 spaces! 68 */ 69 70 71 #ifndef INC_TASK_H 72 #define INC_TASK_H 73 74 #ifndef INC_FREERTOS_H 75 #error "include FreeRTOS.h must appear in source files before include task.h" 76 #endif 77 78 #include "list.h" 79 80 #ifdef __cplusplus 81 extern "C" { 82 #endif 83 84 /*----------------------------------------------------------- 85 * MACROS AND DEFINITIONS 86 *----------------------------------------------------------*/ 87 88 #define tskKERNEL_VERSION_NUMBER "V9.0.0" 89 #define tskKERNEL_VERSION_MAJOR 9 90 #define tskKERNEL_VERSION_MINOR 0 91 #define tskKERNEL_VERSION_BUILD 0 92 93 /** 94 * task. h 95 * 96 * Type by which tasks are referenced. For example, a call to xTaskCreate 97 * returns (via a pointer parameter) an TaskHandle_t variable that can then 98 * be used as a parameter to vTaskDelete to delete the task. 99 * 100 * \defgroup TaskHandle_t TaskHandle_t 101 * \ingroup Tasks 102 */ 103 typedef void * TaskHandle_t; 104 105 /* 106 * Defines the prototype to which the application task hook function must 107 * conform. 108 */ 109 typedef BaseType_t (*TaskHookFunction_t)( void * ); 110 111 /* Task states returned by eTaskGetState. */ 112 typedef enum 113 { 114 eRunning = 0, /* A task is querying the state of itself, so must be running. */ 115 eReady, /* The task being queried is in a read or pending ready list. */ 116 eBlocked, /* The task being queried is in the Blocked state. */ 117 eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */ 118 eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */ 119 eInvalid /* Used as an 'invalid state' value. */ 120 } eTaskState; 121 122 /* Actions that can be performed when vTaskNotify() is called. */ 123 typedef enum 124 { 125 eNoAction = 0, /* Notify the task without updating its notify value. */ 126 eSetBits, /* Set bits in the task's notification value. */ 127 eIncrement, /* Increment the task's notification value. */ 128 eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */ 129 eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */ 130 } eNotifyAction; 131 132 /* 133 * Used internally only. 134 */ 135 typedef struct xTIME_OUT 136 { 137 BaseType_t xOverflowCount; 138 TickType_t xTimeOnEntering; 139 } TimeOut_t; 140 141 /* 142 * Defines the memory ranges allocated to the task when an MPU is used. 143 */ 144 typedef struct xMEMORY_REGION 145 { 146 void *pvBaseAddress; 147 uint32_t ulLengthInBytes; 148 uint32_t ulParameters; 149 } MemoryRegion_t; 150 151 /* 152 * Parameters required to create an MPU protected task. 153 */ 154 typedef struct xTASK_PARAMETERS 155 { 156 TaskFunction_t pvTaskCode; 157 const char * const pcName; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 158 uint16_t usStackDepth; 159 void *pvParameters; 160 UBaseType_t uxPriority; 161 StackType_t *puxStackBuffer; 162 MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ]; 163 } TaskParameters_t; 164 165 /* Used with the uxTaskGetSystemState() function to return the state of each task 166 in the system. */ 167 typedef struct xTASK_STATUS 168 { 169 TaskHandle_t xHandle; /* The handle of the task to which the rest of the information in the structure relates. */ 170 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. */ 171 UBaseType_t xTaskNumber; /* A number unique to the task. */ 172 eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */ 173 UBaseType_t uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */ 174 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. */ 175 uint32_t ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock. See http://www.freertos.org/rtos-run-time-stats.html. Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */ 176 StackType_t *pxStackBase; /* Points to the lowest address of the task's stack area. */ 177 uint16_t 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. */ 178 } TaskStatus_t; 179 180 /* Possible return values for eTaskConfirmSleepModeStatus(). */ 181 typedef enum 182 { 183 eAbortSleep = 0, /* A task has been made ready or a context switch pended since portSUPPORESS_TICKS_AND_SLEEP() was called - abort entering a sleep mode. */ 184 eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */ 185 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. */ 186 } eSleepModeStatus; 187 188 /** 189 * Defines the priority used by the idle task. This must not be modified. 190 * 191 * \ingroup TaskUtils 192 */ 193 #define tskIDLE_PRIORITY ( ( UBaseType_t ) 0U ) 194 195 /** 196 * task. h 197 * 198 * Macro for forcing a context switch. 199 * 200 * \defgroup taskYIELD taskYIELD 201 * \ingroup SchedulerControl 202 */ 203 #define taskYIELD() portYIELD() 204 205 /** 206 * task. h 207 * 208 * Macro to mark the start of a critical code region. Preemptive context 209 * switches cannot occur when in a critical region. 210 * 211 * NOTE: This may alter the stack (depending on the portable implementation) 212 * so must be used with care! 213 * 214 * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL 215 * \ingroup SchedulerControl 216 */ 217 #define taskENTER_CRITICAL() portENTER_CRITICAL() 218 #define taskENTER_CRITICAL_FROM_ISR() portSET_INTERRUPT_MASK_FROM_ISR() 219 220 /** 221 * task. h 222 * 223 * Macro to mark the end of a critical code region. Preemptive context 224 * switches cannot occur when in a critical region. 225 * 226 * NOTE: This may alter the stack (depending on the portable implementation) 227 * so must be used with care! 228 * 229 * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL 230 * \ingroup SchedulerControl 231 */ 232 #define taskEXIT_CRITICAL() portEXIT_CRITICAL() 233 #define taskEXIT_CRITICAL_FROM_ISR( x ) portCLEAR_INTERRUPT_MASK_FROM_ISR( x ) 234 /** 235 * task. h 236 * 237 * Macro to disable all maskable interrupts. 238 * 239 * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS 240 * \ingroup SchedulerControl 241 */ 242 #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS() 243 244 /** 245 * task. h 246 * 247 * Macro to enable microcontroller interrupts. 248 * 249 * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS 250 * \ingroup SchedulerControl 251 */ 252 #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS() 253 254 /* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is 255 0 to generate more optimal code when configASSERT() is defined as the constant 256 is used in assert() statements. */ 257 #define taskSCHEDULER_SUSPENDED ( ( BaseType_t ) 0 ) 258 #define taskSCHEDULER_NOT_STARTED ( ( BaseType_t ) 1 ) 259 #define taskSCHEDULER_RUNNING ( ( BaseType_t ) 2 ) 260 261 262 /*----------------------------------------------------------- 263 * TASK CREATION API 264 *----------------------------------------------------------*/ 265 266 /** 267 * task. h 268 *<pre> 269 BaseType_t xTaskCreate( 270 TaskFunction_t pvTaskCode, 271 const char * const pcName, 272 uint16_t usStackDepth, 273 void *pvParameters, 274 UBaseType_t uxPriority, 275 TaskHandle_t *pvCreatedTask 276 );</pre> 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 * http://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 pvTaskCode 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 pvCreatedTask 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 <pre> 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 </pre> 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, 362 const uint16_t usStackDepth, 363 void * const pvParameters, 364 UBaseType_t uxPriority, 365 TaskHandle_t * const pxCreatedTask ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 366 #endif 367 368 /** 369 * task. h 370 *<pre> 371 TaskHandle_t xTaskCreateStatic( TaskFunction_t pvTaskCode, 372 const char * const pcName, 373 uint32_t ulStackDepth, 374 void *pvParameters, 375 UBaseType_t uxPriority, 376 StackType_t *pxStackBuffer, 377 StaticTask_t *pxTaskBuffer );</pre> 378 * 379 * Create a new task and add it to the list of tasks that are ready to run. 380 * 381 * Internally, within the FreeRTOS implementation, tasks use two blocks of 382 * memory. The first block is used to hold the task's data structures. The 383 * second block is used by the task as its stack. If a task is created using 384 * xTaskCreate() then both blocks of memory are automatically dynamically 385 * allocated inside the xTaskCreate() function. (see 386 * http://www.freertos.org/a00111.html). If a task is created using 387 * xTaskCreateStatic() then the application writer must provide the required 388 * memory. xTaskCreateStatic() therefore allows a task to be created without 389 * using any dynamic memory allocation. 390 * 391 * @param pvTaskCode Pointer to the task entry function. Tasks 392 * must be implemented to never return (i.e. continuous loop). 393 * 394 * @param pcName A descriptive name for the task. This is mainly used to 395 * facilitate debugging. The maximum length of the string is defined by 396 * configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. 397 * 398 * @param ulStackDepth The size of the task stack specified as the number of 399 * variables the stack can hold - not the number of bytes. For example, if 400 * the stack is 32-bits wide and ulStackDepth is defined as 100 then 400 bytes 401 * will be allocated for stack storage. 402 * 403 * @param pvParameters Pointer that will be used as the parameter for the task 404 * being created. 405 * 406 * @param uxPriority The priority at which the task will run. 407 * 408 * @param pxStackBuffer Must point to a StackType_t array that has at least 409 * ulStackDepth indexes - the array will then be used as the task's stack, 410 * removing the need for the stack to be allocated dynamically. 411 * 412 * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will 413 * then be used to hold the task's data structures, removing the need for the 414 * memory to be allocated dynamically. 415 * 416 * @return If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will 417 * be created and pdPASS is returned. If either pxStackBuffer or pxTaskBuffer 418 * are NULL then the task will not be created and 419 * errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned. 420 * 421 * Example usage: 422 <pre> 423 424 // Dimensions the buffer that the task being created will use as its stack. 425 // NOTE: This is the number of words the stack will hold, not the number of 426 // bytes. For example, if each stack item is 32-bits, and this is set to 100, 427 // then 400 bytes (100 * 32-bits) will be allocated. 428 #define STACK_SIZE 200 429 430 // Structure that will hold the TCB of the task being created. 431 StaticTask_t xTaskBuffer; 432 433 // Buffer that the task being created will use as its stack. Note this is 434 // an array of StackType_t variables. The size of StackType_t is dependent on 435 // the RTOS port. 436 StackType_t xStack[ STACK_SIZE ]; 437 438 // Function that implements the task being created. 439 void vTaskCode( void * pvParameters ) 440 { 441 // The parameter value is expected to be 1 as 1 is passed in the 442 // pvParameters value in the call to xTaskCreateStatic(). 443 configASSERT( ( uint32_t ) pvParameters == 1UL ); 444 445 for( ;; ) 446 { 447 // Task code goes here. 448 } 449 } 450 451 // Function that creates a task. 452 void vOtherFunction( void ) 453 { 454 TaskHandle_t xHandle = NULL; 455 456 // Create the task without using any dynamic memory allocation. 457 xHandle = xTaskCreateStatic( 458 vTaskCode, // Function that implements the task. 459 "NAME", // Text name for the task. 460 STACK_SIZE, // Stack size in words, not bytes. 461 ( void * ) 1, // Parameter passed into the task. 462 tskIDLE_PRIORITY,// Priority at which the task is created. 463 xStack, // Array to use as the task's stack. 464 &xTaskBuffer ); // Variable to hold the task's data structure. 465 466 // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have 467 // been created, and xHandle will be the task's handle. Use the handle 468 // to suspend the task. 469 vTaskSuspend( xHandle ); 470 } 471 </pre> 472 * \defgroup xTaskCreateStatic xTaskCreateStatic 473 * \ingroup Tasks 474 */ 475 #if( configSUPPORT_STATIC_ALLOCATION == 1 ) 476 TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode, 477 const char * const pcName, 478 const uint32_t ulStackDepth, 479 void * const pvParameters, 480 UBaseType_t uxPriority, 481 StackType_t * const puxStackBuffer, 482 StaticTask_t * const pxTaskBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 483 #endif /* configSUPPORT_STATIC_ALLOCATION */ 484 485 /** 486 * task. h 487 *<pre> 488 BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );</pre> 489 * 490 * xTaskCreateRestricted() should only be used in systems that include an MPU 491 * implementation. 492 * 493 * Create a new task and add it to the list of tasks that are ready to run. 494 * The function parameters define the memory regions and associated access 495 * permissions allocated to the task. 496 * 497 * @param pxTaskDefinition Pointer to a structure that contains a member 498 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API 499 * documentation) plus an optional stack buffer and the memory region 500 * definitions. 501 * 502 * @param pxCreatedTask Used to pass back a handle by which the created task 503 * can be referenced. 504 * 505 * @return pdPASS if the task was successfully created and added to a ready 506 * list, otherwise an error code defined in the file projdefs.h 507 * 508 * Example usage: 509 <pre> 510 // Create an TaskParameters_t structure that defines the task to be created. 511 static const TaskParameters_t xCheckTaskParameters = 512 { 513 vATask, // pvTaskCode - the function that implements the task. 514 "ATask", // pcName - just a text name for the task to assist debugging. 515 100, // usStackDepth - the stack size DEFINED IN WORDS. 516 NULL, // pvParameters - passed into the task function as the function parameters. 517 ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state. 518 cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack. 519 520 // xRegions - Allocate up to three separate memory regions for access by 521 // the task, with appropriate access permissions. Different processors have 522 // different memory alignment requirements - refer to the FreeRTOS documentation 523 // for full information. 524 { 525 // Base address Length Parameters 526 { cReadWriteArray, 32, portMPU_REGION_READ_WRITE }, 527 { cReadOnlyArray, 32, portMPU_REGION_READ_ONLY }, 528 { cPrivilegedOnlyAccessArray, 128, portMPU_REGION_PRIVILEGED_READ_WRITE } 529 } 530 }; 531 532 int main( void ) 533 { 534 TaskHandle_t xHandle; 535 536 // Create a task from the const structure defined above. The task handle 537 // is requested (the second parameter is not NULL) but in this case just for 538 // demonstration purposes as its not actually used. 539 xTaskCreateRestricted( &xRegTest1Parameters, &xHandle ); 540 541 // Start the scheduler. 542 vTaskStartScheduler(); 543 544 // Will only get here if there was insufficient memory to create the idle 545 // and/or timer task. 546 for( ;; ); 547 } 548 </pre> 549 * \defgroup xTaskCreateRestricted xTaskCreateRestricted 550 * \ingroup Tasks 551 */ 552 #if( portUSING_MPU_WRAPPERS == 1 ) 553 BaseType_t xTaskCreateRestricted( const TaskParameters_t * const pxTaskDefinition, TaskHandle_t *pxCreatedTask ) PRIVILEGED_FUNCTION; 554 #endif 555 556 /** 557 * task. h 558 *<pre> 559 void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );</pre> 560 * 561 * Memory regions are assigned to a restricted task when the task is created by 562 * a call to xTaskCreateRestricted(). These regions can be redefined using 563 * vTaskAllocateMPURegions(). 564 * 565 * @param xTask The handle of the task being updated. 566 * 567 * @param xRegions A pointer to an MemoryRegion_t structure that contains the 568 * new memory region definitions. 569 * 570 * Example usage: 571 <pre> 572 // Define an array of MemoryRegion_t structures that configures an MPU region 573 // allowing read/write access for 1024 bytes starting at the beginning of the 574 // ucOneKByte array. The other two of the maximum 3 definable regions are 575 // unused so set to zero. 576 static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] = 577 { 578 // Base address Length Parameters 579 { ucOneKByte, 1024, portMPU_REGION_READ_WRITE }, 580 { 0, 0, 0 }, 581 { 0, 0, 0 } 582 }; 583 584 void vATask( void *pvParameters ) 585 { 586 // This task was created such that it has access to certain regions of 587 // memory as defined by the MPU configuration. At some point it is 588 // desired that these MPU regions are replaced with that defined in the 589 // xAltRegions const struct above. Use a call to vTaskAllocateMPURegions() 590 // for this purpose. NULL is used as the task handle to indicate that this 591 // function should modify the MPU regions of the calling task. 592 vTaskAllocateMPURegions( NULL, xAltRegions ); 593 594 // Now the task can continue its function, but from this point on can only 595 // access its stack and the ucOneKByte array (unless any other statically 596 // defined or shared regions have been declared elsewhere). 597 } 598 </pre> 599 * \defgroup xTaskCreateRestricted xTaskCreateRestricted 600 * \ingroup Tasks 601 */ 602 void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions ) PRIVILEGED_FUNCTION; 603 604 /** 605 * task. h 606 * <pre>void vTaskDelete( TaskHandle_t xTask );</pre> 607 * 608 * INCLUDE_vTaskDelete must be defined as 1 for this function to be available. 609 * See the configuration section for more information. 610 * 611 * Remove a task from the RTOS real time kernel's management. The task being 612 * deleted will be removed from all ready, blocked, suspended and event lists. 613 * 614 * NOTE: The idle task is responsible for freeing the kernel allocated 615 * memory from tasks that have been deleted. It is therefore important that 616 * the idle task is not starved of microcontroller processing time if your 617 * application makes any calls to vTaskDelete (). Memory allocated by the 618 * task code is not automatically freed, and should be freed before the task 619 * is deleted. 620 * 621 * See the demo application file death.c for sample code that utilises 622 * vTaskDelete (). 623 * 624 * @param xTask The handle of the task to be deleted. Passing NULL will 625 * cause the calling task to be deleted. 626 * 627 * Example usage: 628 <pre> 629 void vOtherFunction( void ) 630 { 631 TaskHandle_t xHandle; 632 633 // Create the task, storing the handle. 634 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 635 636 // Use the handle to delete the task. 637 vTaskDelete( xHandle ); 638 } 639 </pre> 640 * \defgroup vTaskDelete vTaskDelete 641 * \ingroup Tasks 642 */ 643 void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION; 644 645 /*----------------------------------------------------------- 646 * TASK CONTROL API 647 *----------------------------------------------------------*/ 648 649 /** 650 * task. h 651 * <pre>void vTaskDelay( const TickType_t xTicksToDelay );</pre> 652 * 653 * Delay a task for a given number of ticks. The actual time that the 654 * task remains blocked depends on the tick rate. The constant 655 * portTICK_PERIOD_MS can be used to calculate real time from the tick 656 * rate - with the resolution of one tick period. 657 * 658 * INCLUDE_vTaskDelay must be defined as 1 for this function to be available. 659 * See the configuration section for more information. 660 * 661 * 662 * vTaskDelay() specifies a time at which the task wishes to unblock relative to 663 * the time at which vTaskDelay() is called. For example, specifying a block 664 * period of 100 ticks will cause the task to unblock 100 ticks after 665 * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method 666 * of controlling the frequency of a periodic task as the path taken through the 667 * code, as well as other task and interrupt activity, will effect the frequency 668 * at which vTaskDelay() gets called and therefore the time at which the task 669 * next executes. See vTaskDelayUntil() for an alternative API function designed 670 * to facilitate fixed frequency execution. It does this by specifying an 671 * absolute time (rather than a relative time) at which the calling task should 672 * unblock. 673 * 674 * @param xTicksToDelay The amount of time, in tick periods, that 675 * the calling task should block. 676 * 677 * Example usage: 678 679 void vTaskFunction( void * pvParameters ) 680 { 681 // Block for 500ms. 682 const TickType_t xDelay = 500 / portTICK_PERIOD_MS; 683 684 for( ;; ) 685 { 686 // Simply toggle the LED every 500ms, blocking between each toggle. 687 vToggleLED(); 688 vTaskDelay( xDelay ); 689 } 690 } 691 692 * \defgroup vTaskDelay vTaskDelay 693 * \ingroup TaskCtrl 694 */ 695 void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION; 696 697 /** 698 * task. h 699 * <pre>void vTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement );</pre> 700 * 701 * INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available. 702 * See the configuration section for more information. 703 * 704 * Delay a task until a specified time. This function can be used by periodic 705 * tasks to ensure a constant execution frequency. 706 * 707 * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will 708 * cause a task to block for the specified number of ticks from the time vTaskDelay () is 709 * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed 710 * execution frequency as the time between a task starting to execute and that task 711 * calling vTaskDelay () may not be fixed [the task may take a different path though the 712 * code between calls, or may get interrupted or preempted a different number of times 713 * each time it executes]. 714 * 715 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function 716 * is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to 717 * unblock. 718 * 719 * The constant portTICK_PERIOD_MS can be used to calculate real time from the tick 720 * rate - with the resolution of one tick period. 721 * 722 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the 723 * task was last unblocked. The variable must be initialised with the current time 724 * prior to its first use (see the example below). Following this the variable is 725 * automatically updated within vTaskDelayUntil (). 726 * 727 * @param xTimeIncrement The cycle time period. The task will be unblocked at 728 * time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the 729 * same xTimeIncrement parameter value will cause the task to execute with 730 * a fixed interface period. 731 * 732 * Example usage: 733 <pre> 734 // Perform an action every 10 ticks. 735 void vTaskFunction( void * pvParameters ) 736 { 737 TickType_t xLastWakeTime; 738 const TickType_t xFrequency = 10; 739 740 // Initialise the xLastWakeTime variable with the current time. 741 xLastWakeTime = xTaskGetTickCount (); 742 for( ;; ) 743 { 744 // Wait for the next cycle. 745 vTaskDelayUntil( &xLastWakeTime, xFrequency ); 746 747 // Perform action here. 748 } 749 } 750 </pre> 751 * \defgroup vTaskDelayUntil vTaskDelayUntil 752 * \ingroup TaskCtrl 753 */ 754 void vTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION; 755 756 /** 757 * task. h 758 * <pre>BaseType_t xTaskAbortDelay( TaskHandle_t xTask );</pre> 759 * 760 * INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this 761 * function to be available. 762 * 763 * A task will enter the Blocked state when it is waiting for an event. The 764 * event it is waiting for can be a temporal event (waiting for a time), such 765 * as when vTaskDelay() is called, or an event on an object, such as when 766 * xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task 767 * that is in the Blocked state is used in a call to xTaskAbortDelay() then the 768 * task will leave the Blocked state, and return from whichever function call 769 * placed the task into the Blocked state. 770 * 771 * @param xTask The handle of the task to remove from the Blocked state. 772 * 773 * @return If the task referenced by xTask was not in the Blocked state then 774 * pdFAIL is returned. Otherwise pdPASS is returned. 775 * 776 * \defgroup xTaskAbortDelay xTaskAbortDelay 777 * \ingroup TaskCtrl 778 */ 779 BaseType_t xTaskAbortDelay( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 780 781 /** 782 * task. h 783 * <pre>UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask );</pre> 784 * 785 * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. 786 * See the configuration section for more information. 787 * 788 * Obtain the priority of any task. 789 * 790 * @param xTask Handle of the task to be queried. Passing a NULL 791 * handle results in the priority of the calling task being returned. 792 * 793 * @return The priority of xTask. 794 * 795 * Example usage: 796 <pre> 797 void vAFunction( void ) 798 { 799 TaskHandle_t xHandle; 800 801 // Create a task, storing the handle. 802 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 803 804 // ... 805 806 // Use the handle to obtain the priority of the created task. 807 // It was created with tskIDLE_PRIORITY, but may have changed 808 // it itself. 809 if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY ) 810 { 811 // The task has changed it's priority. 812 } 813 814 // ... 815 816 // Is our priority higher than the created task? 817 if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) ) 818 { 819 // Our priority (obtained using NULL handle) is higher. 820 } 821 } 822 </pre> 823 * \defgroup uxTaskPriorityGet uxTaskPriorityGet 824 * \ingroup TaskCtrl 825 */ 826 UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 827 828 /** 829 * task. h 830 * <pre>UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask );</pre> 831 * 832 * A version of uxTaskPriorityGet() that can be used from an ISR. 833 */ 834 UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 835 836 /** 837 * task. h 838 * <pre>eTaskState eTaskGetState( TaskHandle_t xTask );</pre> 839 * 840 * INCLUDE_eTaskGetState must be defined as 1 for this function to be available. 841 * See the configuration section for more information. 842 * 843 * Obtain the state of any task. States are encoded by the eTaskState 844 * enumerated type. 845 * 846 * @param xTask Handle of the task to be queried. 847 * 848 * @return The state of xTask at the time the function was called. Note the 849 * state of the task might change between the function being called, and the 850 * functions return value being tested by the calling task. 851 */ 852 eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 853 854 /** 855 * task. h 856 * <pre>void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState );</pre> 857 * 858 * configUSE_TRACE_FACILITY must be defined as 1 for this function to be 859 * available. See the configuration section for more information. 860 * 861 * Populates a TaskStatus_t structure with information about a task. 862 * 863 * @param xTask Handle of the task being queried. If xTask is NULL then 864 * information will be returned about the calling task. 865 * 866 * @param pxTaskStatus A pointer to the TaskStatus_t structure that will be 867 * filled with information about the task referenced by the handle passed using 868 * the xTask parameter. 869 * 870 * @xGetFreeStackSpace The TaskStatus_t structure contains a member to report 871 * the stack high water mark of the task being queried. Calculating the stack 872 * high water mark takes a relatively long time, and can make the system 873 * temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to 874 * allow the high water mark checking to be skipped. The high watermark value 875 * will only be written to the TaskStatus_t structure if xGetFreeStackSpace is 876 * not set to pdFALSE; 877 * 878 * @param eState The TaskStatus_t structure contains a member to report the 879 * state of the task being queried. Obtaining the task state is not as fast as 880 * a simple assignment - so the eState parameter is provided to allow the state 881 * information to be omitted from the TaskStatus_t structure. To obtain state 882 * information then set eState to eInvalid - otherwise the value passed in 883 * eState will be reported as the task state in the TaskStatus_t structure. 884 * 885 * Example usage: 886 <pre> 887 void vAFunction( void ) 888 { 889 TaskHandle_t xHandle; 890 TaskStatus_t xTaskDetails; 891 892 // Obtain the handle of a task from its name. 893 xHandle = xTaskGetHandle( "Task_Name" ); 894 895 // Check the handle is not NULL. 896 configASSERT( xHandle ); 897 898 // Use the handle to obtain further information about the task. 899 vTaskGetInfo( xHandle, 900 &xTaskDetails, 901 pdTRUE, // Include the high water mark in xTaskDetails. 902 eInvalid ); // Include the task state in xTaskDetails. 903 } 904 </pre> 905 * \defgroup vTaskGetInfo vTaskGetInfo 906 * \ingroup TaskCtrl 907 */ 908 void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState ) PRIVILEGED_FUNCTION; 909 910 /** 911 * task. h 912 * <pre>void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );</pre> 913 * 914 * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. 915 * See the configuration section for more information. 916 * 917 * Set the priority of any task. 918 * 919 * A context switch will occur before the function returns if the priority 920 * being set is higher than the currently executing task. 921 * 922 * @param xTask Handle to the task for which the priority is being set. 923 * Passing a NULL handle results in the priority of the calling task being set. 924 * 925 * @param uxNewPriority The priority to which the task will be set. 926 * 927 * Example usage: 928 <pre> 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 raise the priority of the created task. 939 vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 ); 940 941 // ... 942 943 // Use a NULL handle to raise our priority to the same value. 944 vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 ); 945 } 946 </pre> 947 * \defgroup vTaskPrioritySet vTaskPrioritySet 948 * \ingroup TaskCtrl 949 */ 950 void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ) PRIVILEGED_FUNCTION; 951 952 /** 953 * task. h 954 * <pre>void vTaskSuspend( TaskHandle_t xTaskToSuspend );</pre> 955 * 956 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. 957 * See the configuration section for more information. 958 * 959 * Suspend any task. When suspended a task will never get any microcontroller 960 * processing time, no matter what its priority. 961 * 962 * Calls to vTaskSuspend are not accumulative - 963 * i.e. calling vTaskSuspend () twice on the same task still only requires one 964 * call to vTaskResume () to ready the suspended task. 965 * 966 * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL 967 * handle will cause the calling task to be suspended. 968 * 969 * Example usage: 970 <pre> 971 void vAFunction( void ) 972 { 973 TaskHandle_t xHandle; 974 975 // Create a task, storing the handle. 976 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 977 978 // ... 979 980 // Use the handle to suspend the created task. 981 vTaskSuspend( xHandle ); 982 983 // ... 984 985 // The created task will not run during this period, unless 986 // another task calls vTaskResume( xHandle ). 987 988 //... 989 990 991 // Suspend ourselves. 992 vTaskSuspend( NULL ); 993 994 // We cannot get here unless another task calls vTaskResume 995 // with our handle as the parameter. 996 } 997 </pre> 998 * \defgroup vTaskSuspend vTaskSuspend 999 * \ingroup TaskCtrl 1000 */ 1001 void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION; 1002 1003 /** 1004 * task. h 1005 * <pre>void vTaskResume( TaskHandle_t xTaskToResume );</pre> 1006 * 1007 * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. 1008 * See the configuration section for more information. 1009 * 1010 * Resumes a suspended task. 1011 * 1012 * A task that has been suspended by one or more calls to vTaskSuspend () 1013 * will be made available for running again by a single call to 1014 * vTaskResume (). 1015 * 1016 * @param xTaskToResume Handle to the task being readied. 1017 * 1018 * Example usage: 1019 <pre> 1020 void vAFunction( void ) 1021 { 1022 TaskHandle_t xHandle; 1023 1024 // Create a task, storing the handle. 1025 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); 1026 1027 // ... 1028 1029 // Use the handle to suspend the created task. 1030 vTaskSuspend( xHandle ); 1031 1032 // ... 1033 1034 // The created task will not run during this period, unless 1035 // another task calls vTaskResume( xHandle ). 1036 1037 //... 1038 1039 1040 // Resume the suspended task ourselves. 1041 vTaskResume( xHandle ); 1042 1043 // The created task will once again get microcontroller processing 1044 // time in accordance with its priority within the system. 1045 } 1046 </pre> 1047 * \defgroup vTaskResume vTaskResume 1048 * \ingroup TaskCtrl 1049 */ 1050 void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; 1051 1052 /** 1053 * task. h 1054 * <pre>void xTaskResumeFromISR( TaskHandle_t xTaskToResume );</pre> 1055 * 1056 * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be 1057 * available. See the configuration section for more information. 1058 * 1059 * An implementation of vTaskResume() that can be called from within an ISR. 1060 * 1061 * A task that has been suspended by one or more calls to vTaskSuspend () 1062 * will be made available for running again by a single call to 1063 * xTaskResumeFromISR (). 1064 * 1065 * xTaskResumeFromISR() should not be used to synchronise a task with an 1066 * interrupt if there is a chance that the interrupt could arrive prior to the 1067 * task being suspended - as this can lead to interrupts being missed. Use of a 1068 * semaphore as a synchronisation mechanism would avoid this eventuality. 1069 * 1070 * @param xTaskToResume Handle to the task being readied. 1071 * 1072 * @return pdTRUE if resuming the task should result in a context switch, 1073 * otherwise pdFALSE. This is used by the ISR to determine if a context switch 1074 * may be required following the ISR. 1075 * 1076 * \defgroup vTaskResumeFromISR vTaskResumeFromISR 1077 * \ingroup TaskCtrl 1078 */ 1079 BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; 1080 1081 /*----------------------------------------------------------- 1082 * SCHEDULER CONTROL 1083 *----------------------------------------------------------*/ 1084 1085 /** 1086 * task. h 1087 * <pre>void vTaskStartScheduler( void );</pre> 1088 * 1089 * Starts the real time kernel tick processing. After calling the kernel 1090 * has control over which tasks are executed and when. 1091 * 1092 * See the demo application file main.c for an example of creating 1093 * tasks and starting the kernel. 1094 * 1095 * Example usage: 1096 <pre> 1097 void vAFunction( void ) 1098 { 1099 // Create at least one task before starting the kernel. 1100 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); 1101 1102 // Start the real time kernel with preemption. 1103 vTaskStartScheduler (); 1104 1105 // Will not get here unless a task calls vTaskEndScheduler () 1106 } 1107 </pre> 1108 * 1109 * \defgroup vTaskStartScheduler vTaskStartScheduler 1110 * \ingroup SchedulerControl 1111 */ 1112 void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; 1113 1114 /** 1115 * task. h 1116 * <pre>void vTaskEndScheduler( void );</pre> 1117 * 1118 * NOTE: At the time of writing only the x86 real mode port, which runs on a PC 1119 * in place of DOS, implements this function. 1120 * 1121 * Stops the real time kernel tick. All created tasks will be automatically 1122 * deleted and multitasking (either preemptive or cooperative) will 1123 * stop. Execution then resumes from the point where vTaskStartScheduler () 1124 * was called, as if vTaskStartScheduler () had just returned. 1125 * 1126 * See the demo application file main. c in the demo/PC directory for an 1127 * example that uses vTaskEndScheduler (). 1128 * 1129 * vTaskEndScheduler () requires an exit function to be defined within the 1130 * portable layer (see vPortEndScheduler () in port. c for the PC port). This 1131 * performs hardware specific operations such as stopping the kernel tick. 1132 * 1133 * vTaskEndScheduler () will cause all of the resources allocated by the 1134 * kernel to be freed - but will not free resources allocated by application 1135 * tasks. 1136 * 1137 * Example usage: 1138 <pre> 1139 void vTaskCode( void * pvParameters ) 1140 { 1141 for( ;; ) 1142 { 1143 // Task code goes here. 1144 1145 // At some point we want to end the real time kernel processing 1146 // so call ... 1147 vTaskEndScheduler (); 1148 } 1149 } 1150 1151 void vAFunction( void ) 1152 { 1153 // Create at least one task before starting the kernel. 1154 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); 1155 1156 // Start the real time kernel with preemption. 1157 vTaskStartScheduler (); 1158 1159 // Will only get here when the vTaskCode () task has called 1160 // vTaskEndScheduler (). When we get here we are back to single task 1161 // execution. 1162 } 1163 </pre> 1164 * 1165 * \defgroup vTaskEndScheduler vTaskEndScheduler 1166 * \ingroup SchedulerControl 1167 */ 1168 void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; 1169 1170 /** 1171 * task. h 1172 * <pre>void vTaskSuspendAll( void );</pre> 1173 * 1174 * Suspends the scheduler without disabling interrupts. Context switches will 1175 * not occur while the scheduler is suspended. 1176 * 1177 * After calling vTaskSuspendAll () the calling task will continue to execute 1178 * without risk of being swapped out until a call to xTaskResumeAll () has been 1179 * made. 1180 * 1181 * API functions that have the potential to cause a context switch (for example, 1182 * vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler 1183 * is suspended. 1184 * 1185 * Example usage: 1186 <pre> 1187 void vTask1( void * pvParameters ) 1188 { 1189 for( ;; ) 1190 { 1191 // Task code goes here. 1192 1193 // ... 1194 1195 // At some point the task wants to perform a long operation during 1196 // which it does not want to get swapped out. It cannot use 1197 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the 1198 // operation may cause interrupts to be missed - including the 1199 // ticks. 1200 1201 // Prevent the real time kernel swapping out the task. 1202 vTaskSuspendAll (); 1203 1204 // Perform the operation here. There is no need to use critical 1205 // sections as we have all the microcontroller processing time. 1206 // During this time interrupts will still operate and the kernel 1207 // tick count will be maintained. 1208 1209 // ... 1210 1211 // The operation is complete. Restart the kernel. 1212 xTaskResumeAll (); 1213 } 1214 } 1215 </pre> 1216 * \defgroup vTaskSuspendAll vTaskSuspendAll 1217 * \ingroup SchedulerControl 1218 */ 1219 void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION; 1220 1221 /** 1222 * task. h 1223 * <pre>BaseType_t xTaskResumeAll( void );</pre> 1224 * 1225 * Resumes scheduler activity after it was suspended by a call to 1226 * vTaskSuspendAll(). 1227 * 1228 * xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks 1229 * that were previously suspended by a call to vTaskSuspend(). 1230 * 1231 * @return If resuming the scheduler caused a context switch then pdTRUE is 1232 * returned, otherwise pdFALSE is returned. 1233 * 1234 * Example usage: 1235 <pre> 1236 void vTask1( void * pvParameters ) 1237 { 1238 for( ;; ) 1239 { 1240 // Task code goes here. 1241 1242 // ... 1243 1244 // At some point the task wants to perform a long operation during 1245 // which it does not want to get swapped out. It cannot use 1246 // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the 1247 // operation may cause interrupts to be missed - including the 1248 // ticks. 1249 1250 // Prevent the real time kernel swapping out the task. 1251 vTaskSuspendAll (); 1252 1253 // Perform the operation here. There is no need to use critical 1254 // sections as we have all the microcontroller processing time. 1255 // During this time interrupts will still operate and the real 1256 // time kernel tick count will be maintained. 1257 1258 // ... 1259 1260 // The operation is complete. Restart the kernel. We want to force 1261 // a context switch - but there is no point if resuming the scheduler 1262 // caused a context switch already. 1263 if( !xTaskResumeAll () ) 1264 { 1265 taskYIELD (); 1266 } 1267 } 1268 } 1269 </pre> 1270 * \defgroup xTaskResumeAll xTaskResumeAll 1271 * \ingroup SchedulerControl 1272 */ 1273 BaseType_t xTaskResumeAll( void ) PRIVILEGED_FUNCTION; 1274 1275 /*----------------------------------------------------------- 1276 * TASK UTILITIES 1277 *----------------------------------------------------------*/ 1278 1279 /** 1280 * task. h 1281 * <PRE>TickType_t xTaskGetTickCount( void );</PRE> 1282 * 1283 * @return The count of ticks since vTaskStartScheduler was called. 1284 * 1285 * \defgroup xTaskGetTickCount xTaskGetTickCount 1286 * \ingroup TaskUtils 1287 */ 1288 TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION; 1289 1290 /** 1291 * task. h 1292 * <PRE>TickType_t xTaskGetTickCountFromISR( void );</PRE> 1293 * 1294 * @return The count of ticks since vTaskStartScheduler was called. 1295 * 1296 * This is a version of xTaskGetTickCount() that is safe to be called from an 1297 * ISR - provided that TickType_t is the natural word size of the 1298 * microcontroller being used or interrupt nesting is either not supported or 1299 * not being used. 1300 * 1301 * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR 1302 * \ingroup TaskUtils 1303 */ 1304 TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION; 1305 1306 /** 1307 * task. h 1308 * <PRE>uint16_t uxTaskGetNumberOfTasks( void );</PRE> 1309 * 1310 * @return The number of tasks that the real time kernel is currently managing. 1311 * This includes all ready, blocked and suspended tasks. A task that 1312 * has been deleted but not yet freed by the idle task will also be 1313 * included in the count. 1314 * 1315 * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks 1316 * \ingroup TaskUtils 1317 */ 1318 UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION; 1319 1320 /** 1321 * task. h 1322 * <PRE>char *pcTaskGetName( TaskHandle_t xTaskToQuery );</PRE> 1323 * 1324 * @return The text (human readable) name of the task referenced by the handle 1325 * xTaskToQuery. A task can query its own name by either passing in its own 1326 * handle, or by setting xTaskToQuery to NULL. 1327 * 1328 * \defgroup pcTaskGetName pcTaskGetName 1329 * \ingroup TaskUtils 1330 */ 1331 char *pcTaskGetName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 1332 1333 /** 1334 * task. h 1335 * <PRE>TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );</PRE> 1336 * 1337 * NOTE: This function takes a relatively long time to complete and should be 1338 * used sparingly. 1339 * 1340 * @return The handle of the task that has the human readable name pcNameToQuery. 1341 * NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle 1342 * must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available. 1343 * 1344 * \defgroup pcTaskGetHandle pcTaskGetHandle 1345 * \ingroup TaskUtils 1346 */ 1347 TaskHandle_t xTaskGetHandle( const char *pcNameToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 1348 1349 /** 1350 * task.h 1351 * <PRE>UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );</PRE> 1352 * 1353 * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for 1354 * this function to be available. 1355 * 1356 * Returns the high water mark of the stack associated with xTask. That is, 1357 * the minimum free stack space there has been (in words, so on a 32 bit machine 1358 * a value of 1 means 4 bytes) since the task started. The smaller the returned 1359 * number the closer the task has come to overflowing its stack. 1360 * 1361 * @param xTask Handle of the task associated with the stack to be checked. 1362 * Set xTask to NULL to check the stack of the calling task. 1363 * 1364 * @return The smallest amount of free stack space there has been (in words, so 1365 * actual spaces on the stack rather than bytes) since the task referenced by 1366 * xTask was created. 1367 */ 1368 UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1369 1370 /* When using trace macros it is sometimes necessary to include task.h before 1371 FreeRTOS.h. When this is done TaskHookFunction_t will not yet have been defined, 1372 so the following two prototypes will cause a compilation error. This can be 1373 fixed by simply guarding against the inclusion of these two prototypes unless 1374 they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration 1375 constant. */ 1376 #ifdef configUSE_APPLICATION_TASK_TAG 1377 #if configUSE_APPLICATION_TASK_TAG == 1 1378 /** 1379 * task.h 1380 * <pre>void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction );</pre> 1381 * 1382 * Sets pxHookFunction to be the task hook function used by the task xTask. 1383 * Passing xTask as NULL has the effect of setting the calling tasks hook 1384 * function. 1385 */ 1386 void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction ) PRIVILEGED_FUNCTION; 1387 1388 /** 1389 * task.h 1390 * <pre>void xTaskGetApplicationTaskTag( TaskHandle_t xTask );</pre> 1391 * 1392 * Returns the pxHookFunction value assigned to the task xTask. 1393 */ 1394 TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 1395 #endif /* configUSE_APPLICATION_TASK_TAG ==1 */ 1396 #endif /* ifdef configUSE_APPLICATION_TASK_TAG */ 1397 1398 #if( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 ) 1399 1400 /* Each task contains an array of pointers that is dimensioned by the 1401 configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The 1402 kernel does not use the pointers itself, so the application writer can use 1403 the pointers for any purpose they wish. The following two functions are 1404 used to set and query a pointer respectively. */ 1405 void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue ) PRIVILEGED_FUNCTION; 1406 void *pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery, BaseType_t xIndex ) PRIVILEGED_FUNCTION; 1407 1408 #endif 1409 1410 /** 1411 * task.h 1412 * <pre>BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );</pre> 1413 * 1414 * Calls the hook function associated with xTask. Passing xTask as NULL has 1415 * the effect of calling the Running tasks (the calling task) hook function. 1416 * 1417 * pvParameter is passed to the hook function for the task to interpret as it 1418 * wants. The return value is the value returned by the task hook function 1419 * registered by the user. 1420 */ 1421 BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter ) PRIVILEGED_FUNCTION; 1422 1423 /** 1424 * xTaskGetIdleTaskHandle() is only available if 1425 * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h. 1426 * 1427 * Simply returns the handle of the idle task. It is not valid to call 1428 * xTaskGetIdleTaskHandle() before the scheduler has been started. 1429 */ 1430 TaskHandle_t xTaskGetIdleTaskHandle( void ) PRIVILEGED_FUNCTION; 1431 1432 /** 1433 * configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for 1434 * uxTaskGetSystemState() to be available. 1435 * 1436 * uxTaskGetSystemState() populates an TaskStatus_t structure for each task in 1437 * the system. TaskStatus_t structures contain, among other things, members 1438 * for the task handle, task name, task priority, task state, and total amount 1439 * of run time consumed by the task. See the TaskStatus_t structure 1440 * definition in this file for the full member list. 1441 * 1442 * NOTE: This function is intended for debugging use only as its use results in 1443 * the scheduler remaining suspended for an extended period. 1444 * 1445 * @param pxTaskStatusArray A pointer to an array of TaskStatus_t structures. 1446 * The array must contain at least one TaskStatus_t structure for each task 1447 * that is under the control of the RTOS. The number of tasks under the control 1448 * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function. 1449 * 1450 * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray 1451 * parameter. The size is specified as the number of indexes in the array, or 1452 * the number of TaskStatus_t structures contained in the array, not by the 1453 * number of bytes in the array. 1454 * 1455 * @param pulTotalRunTime If configGENERATE_RUN_TIME_STATS is set to 1 in 1456 * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the 1457 * total run time (as defined by the run time stats clock, see 1458 * http://www.freertos.org/rtos-run-time-stats.html) since the target booted. 1459 * pulTotalRunTime can be set to NULL to omit the total run time information. 1460 * 1461 * @return The number of TaskStatus_t structures that were populated by 1462 * uxTaskGetSystemState(). This should equal the number returned by the 1463 * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed 1464 * in the uxArraySize parameter was too small. 1465 * 1466 * Example usage: 1467 <pre> 1468 // This example demonstrates how a human readable table of run time stats 1469 // information is generated from raw data provided by uxTaskGetSystemState(). 1470 // The human readable table is written to pcWriteBuffer 1471 void vTaskGetRunTimeStats( char *pcWriteBuffer ) 1472 { 1473 TaskStatus_t *pxTaskStatusArray; 1474 volatile UBaseType_t uxArraySize, x; 1475 uint32_t ulTotalRunTime, ulStatsAsPercentage; 1476 1477 // Make sure the write buffer does not contain a string. 1478 *pcWriteBuffer = 0x00; 1479 1480 // Take a snapshot of the number of tasks in case it changes while this 1481 // function is executing. 1482 uxArraySize = uxTaskGetNumberOfTasks(); 1483 1484 // Allocate a TaskStatus_t structure for each task. An array could be 1485 // allocated statically at compile time. 1486 pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) ); 1487 1488 if( pxTaskStatusArray != NULL ) 1489 { 1490 // Generate raw status information about each task. 1491 uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime ); 1492 1493 // For percentage calculations. 1494 ulTotalRunTime /= 100UL; 1495 1496 // Avoid divide by zero errors. 1497 if( ulTotalRunTime > 0 ) 1498 { 1499 // For each populated position in the pxTaskStatusArray array, 1500 // format the raw data as human readable ASCII data 1501 for( x = 0; x < uxArraySize; x++ ) 1502 { 1503 // What percentage of the total run time has the task used? 1504 // This will always be rounded down to the nearest integer. 1505 // ulTotalRunTimeDiv100 has already been divided by 100. 1506 ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime; 1507 1508 if( ulStatsAsPercentage > 0UL ) 1509 { 1510 sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage ); 1511 } 1512 else 1513 { 1514 // If the percentage is zero here then the task has 1515 // consumed less than 1% of the total run time. 1516 sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter ); 1517 } 1518 1519 pcWriteBuffer += strlen( ( char * ) pcWriteBuffer ); 1520 } 1521 } 1522 1523 // The array is no longer needed, free the memory it consumes. 1524 vPortFree( pxTaskStatusArray ); 1525 } 1526 } 1527 </pre> 1528 */ 1529 UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const UBaseType_t uxArraySize, uint32_t * const pulTotalRunTime ) PRIVILEGED_FUNCTION; 1530 1531 /** 1532 * task. h 1533 * <PRE>void vTaskList( char *pcWriteBuffer );</PRE> 1534 * 1535 * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must 1536 * both be defined as 1 for this function to be available. See the 1537 * configuration section of the FreeRTOS.org website for more information. 1538 * 1539 * NOTE 1: This function will disable interrupts for its duration. It is 1540 * not intended for normal application runtime use but as a debug aid. 1541 * 1542 * Lists all the current tasks, along with their current state and stack 1543 * usage high water mark. 1544 * 1545 * Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or 1546 * suspended ('S'). 1547 * 1548 * PLEASE NOTE: 1549 * 1550 * This function is provided for convenience only, and is used by many of the 1551 * demo applications. Do not consider it to be part of the scheduler. 1552 * 1553 * vTaskList() calls uxTaskGetSystemState(), then formats part of the 1554 * uxTaskGetSystemState() output into a human readable table that displays task 1555 * names, states and stack usage. 1556 * 1557 * vTaskList() has a dependency on the sprintf() C library function that might 1558 * bloat the code size, use a lot of stack, and provide different results on 1559 * different platforms. An alternative, tiny, third party, and limited 1560 * functionality implementation of sprintf() is provided in many of the 1561 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note 1562 * printf-stdarg.c does not provide a full snprintf() implementation!). 1563 * 1564 * It is recommended that production systems call uxTaskGetSystemState() 1565 * directly to get access to raw stats data, rather than indirectly through a 1566 * call to vTaskList(). 1567 * 1568 * @param pcWriteBuffer A buffer into which the above mentioned details 1569 * will be written, in ASCII form. This buffer is assumed to be large 1570 * enough to contain the generated report. Approximately 40 bytes per 1571 * task should be sufficient. 1572 * 1573 * \defgroup vTaskList vTaskList 1574 * \ingroup TaskUtils 1575 */ 1576 void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 1577 1578 /** 1579 * task. h 1580 * <PRE>void vTaskGetRunTimeStats( char *pcWriteBuffer );</PRE> 1581 * 1582 * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS 1583 * must both be defined as 1 for this function to be available. The application 1584 * must also then provide definitions for 1585 * portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE() 1586 * to configure a peripheral timer/counter and return the timers current count 1587 * value respectively. The counter should be at least 10 times the frequency of 1588 * the tick count. 1589 * 1590 * NOTE 1: This function will disable interrupts for its duration. It is 1591 * not intended for normal application runtime use but as a debug aid. 1592 * 1593 * Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total 1594 * accumulated execution time being stored for each task. The resolution 1595 * of the accumulated time value depends on the frequency of the timer 1596 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. 1597 * Calling vTaskGetRunTimeStats() writes the total execution time of each 1598 * task into a buffer, both as an absolute count value and as a percentage 1599 * of the total system execution time. 1600 * 1601 * NOTE 2: 1602 * 1603 * This function is provided for convenience only, and is used by many of the 1604 * demo applications. Do not consider it to be part of the scheduler. 1605 * 1606 * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the 1607 * uxTaskGetSystemState() output into a human readable table that displays the 1608 * amount of time each task has spent in the Running state in both absolute and 1609 * percentage terms. 1610 * 1611 * vTaskGetRunTimeStats() has a dependency on the sprintf() C library function 1612 * that might bloat the code size, use a lot of stack, and provide different 1613 * results on different platforms. An alternative, tiny, third party, and 1614 * limited functionality implementation of sprintf() is provided in many of the 1615 * FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note 1616 * printf-stdarg.c does not provide a full snprintf() implementation!). 1617 * 1618 * It is recommended that production systems call uxTaskGetSystemState() directly 1619 * to get access to raw stats data, rather than indirectly through a call to 1620 * vTaskGetRunTimeStats(). 1621 * 1622 * @param pcWriteBuffer A buffer into which the execution times will be 1623 * written, in ASCII form. This buffer is assumed to be large enough to 1624 * contain the generated report. Approximately 40 bytes per task should 1625 * be sufficient. 1626 * 1627 * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats 1628 * \ingroup TaskUtils 1629 */ 1630 void vTaskGetRunTimeStats( char *pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ 1631 1632 /** 1633 * task. h 1634 * <PRE>BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction );</PRE> 1635 * 1636 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 1637 * function to be available. 1638 * 1639 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 1640 * "notification value", which is a 32-bit unsigned integer (uint32_t). 1641 * 1642 * Events can be sent to a task using an intermediary object. Examples of such 1643 * objects are queues, semaphores, mutexes and event groups. Task notifications 1644 * are a method of sending an event directly to a task without the need for such 1645 * an intermediary object. 1646 * 1647 * A notification sent to a task can optionally perform an action, such as 1648 * update, overwrite or increment the task's notification value. In that way 1649 * task notifications can be used to send data to a task, or be used as light 1650 * weight and fast binary or counting semaphores. 1651 * 1652 * A notification sent to a task will remain pending until it is cleared by the 1653 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was 1654 * already in the Blocked state to wait for a notification when the notification 1655 * arrives then the task will automatically be removed from the Blocked state 1656 * (unblocked) and the notification cleared. 1657 * 1658 * A task can use xTaskNotifyWait() to [optionally] block to wait for a 1659 * notification to be pending, or ulTaskNotifyTake() to [optionally] block 1660 * to wait for its notification value to have a non-zero value. The task does 1661 * not consume any CPU time while it is in the Blocked state. 1662 * 1663 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. 1664 * 1665 * @param xTaskToNotify The handle of the task being notified. The handle to a 1666 * task can be returned from the xTaskCreate() API function used to create the 1667 * task, and the handle of the currently running task can be obtained by calling 1668 * xTaskGetCurrentTaskHandle(). 1669 * 1670 * @param ulValue Data that can be sent with the notification. How the data is 1671 * used depends on the value of the eAction parameter. 1672 * 1673 * @param eAction Specifies how the notification updates the task's notification 1674 * value, if at all. Valid values for eAction are as follows: 1675 * 1676 * eSetBits - 1677 * The task's notification value is bitwise ORed with ulValue. xTaskNofify() 1678 * always returns pdPASS in this case. 1679 * 1680 * eIncrement - 1681 * The task's notification value is incremented. ulValue is not used and 1682 * xTaskNotify() always returns pdPASS in this case. 1683 * 1684 * eSetValueWithOverwrite - 1685 * The task's notification value is set to the value of ulValue, even if the 1686 * task being notified had not yet processed the previous notification (the 1687 * task already had a notification pending). xTaskNotify() always returns 1688 * pdPASS in this case. 1689 * 1690 * eSetValueWithoutOverwrite - 1691 * If the task being notified did not already have a notification pending then 1692 * the task's notification value is set to ulValue and xTaskNotify() will 1693 * return pdPASS. If the task being notified already had a notification 1694 * pending then no action is performed and pdFAIL is returned. 1695 * 1696 * eNoAction - 1697 * The task receives a notification without its notification value being 1698 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in 1699 * this case. 1700 * 1701 * pulPreviousNotificationValue - 1702 * Can be used to pass out the subject task's notification value before any 1703 * bits are modified by the notify function. 1704 * 1705 * @return Dependent on the value of eAction. See the description of the 1706 * eAction parameter. 1707 * 1708 * \defgroup xTaskNotify xTaskNotify 1709 * \ingroup TaskNotifications 1710 */ 1711 BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue ) PRIVILEGED_FUNCTION; 1712 #define xTaskNotify( xTaskToNotify, ulValue, eAction ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL ) 1713 #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) 1714 1715 /** 1716 * task. h 1717 * <PRE>BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken );</PRE> 1718 * 1719 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 1720 * function to be available. 1721 * 1722 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 1723 * "notification value", which is a 32-bit unsigned integer (uint32_t). 1724 * 1725 * A version of xTaskNotify() that can be used from an interrupt service routine 1726 * (ISR). 1727 * 1728 * Events can be sent to a task using an intermediary object. Examples of such 1729 * objects are queues, semaphores, mutexes and event groups. Task notifications 1730 * are a method of sending an event directly to a task without the need for such 1731 * an intermediary object. 1732 * 1733 * A notification sent to a task can optionally perform an action, such as 1734 * update, overwrite or increment the task's notification value. In that way 1735 * task notifications can be used to send data to a task, or be used as light 1736 * weight and fast binary or counting semaphores. 1737 * 1738 * A notification sent to a task will remain pending until it is cleared by the 1739 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was 1740 * already in the Blocked state to wait for a notification when the notification 1741 * arrives then the task will automatically be removed from the Blocked state 1742 * (unblocked) and the notification cleared. 1743 * 1744 * A task can use xTaskNotifyWait() to [optionally] block to wait for a 1745 * notification to be pending, or ulTaskNotifyTake() to [optionally] block 1746 * to wait for its notification value to have a non-zero value. The task does 1747 * not consume any CPU time while it is in the Blocked state. 1748 * 1749 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. 1750 * 1751 * @param xTaskToNotify The handle of the task being notified. The handle to a 1752 * task can be returned from the xTaskCreate() API function used to create the 1753 * task, and the handle of the currently running task can be obtained by calling 1754 * xTaskGetCurrentTaskHandle(). 1755 * 1756 * @param ulValue Data that can be sent with the notification. How the data is 1757 * used depends on the value of the eAction parameter. 1758 * 1759 * @param eAction Specifies how the notification updates the task's notification 1760 * value, if at all. Valid values for eAction are as follows: 1761 * 1762 * eSetBits - 1763 * The task's notification value is bitwise ORed with ulValue. xTaskNofify() 1764 * always returns pdPASS in this case. 1765 * 1766 * eIncrement - 1767 * The task's notification value is incremented. ulValue is not used and 1768 * xTaskNotify() always returns pdPASS in this case. 1769 * 1770 * eSetValueWithOverwrite - 1771 * The task's notification value is set to the value of ulValue, even if the 1772 * task being notified had not yet processed the previous notification (the 1773 * task already had a notification pending). xTaskNotify() always returns 1774 * pdPASS in this case. 1775 * 1776 * eSetValueWithoutOverwrite - 1777 * If the task being notified did not already have a notification pending then 1778 * the task's notification value is set to ulValue and xTaskNotify() will 1779 * return pdPASS. If the task being notified already had a notification 1780 * pending then no action is performed and pdFAIL is returned. 1781 * 1782 * eNoAction - 1783 * The task receives a notification without its notification value being 1784 * updated. ulValue is not used and xTaskNotify() always returns pdPASS in 1785 * this case. 1786 * 1787 * @param pxHigherPriorityTaskWoken xTaskNotifyFromISR() will set 1788 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the 1789 * task to which the notification was sent to leave the Blocked state, and the 1790 * unblocked task has a priority higher than the currently running task. If 1791 * xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should 1792 * be requested before the interrupt is exited. How a context switch is 1793 * requested from an ISR is dependent on the port - see the documentation page 1794 * for the port in use. 1795 * 1796 * @return Dependent on the value of eAction. See the description of the 1797 * eAction parameter. 1798 * 1799 * \defgroup xTaskNotify xTaskNotify 1800 * \ingroup TaskNotifications 1801 */ 1802 BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 1803 #define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) 1804 #define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) ) 1805 1806 /** 1807 * task. h 1808 * <PRE>BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait );</pre> 1809 * 1810 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 1811 * function to be available. 1812 * 1813 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 1814 * "notification value", which is a 32-bit unsigned integer (uint32_t). 1815 * 1816 * Events can be sent to a task using an intermediary object. Examples of such 1817 * objects are queues, semaphores, mutexes and event groups. Task notifications 1818 * are a method of sending an event directly to a task without the need for such 1819 * an intermediary object. 1820 * 1821 * A notification sent to a task can optionally perform an action, such as 1822 * update, overwrite or increment the task's notification value. In that way 1823 * task notifications can be used to send data to a task, or be used as light 1824 * weight and fast binary or counting semaphores. 1825 * 1826 * A notification sent to a task will remain pending until it is cleared by the 1827 * task calling xTaskNotifyWait() or ulTaskNotifyTake(). If the task was 1828 * already in the Blocked state to wait for a notification when the notification 1829 * arrives then the task will automatically be removed from the Blocked state 1830 * (unblocked) and the notification cleared. 1831 * 1832 * A task can use xTaskNotifyWait() to [optionally] block to wait for a 1833 * notification to be pending, or ulTaskNotifyTake() to [optionally] block 1834 * to wait for its notification value to have a non-zero value. The task does 1835 * not consume any CPU time while it is in the Blocked state. 1836 * 1837 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. 1838 * 1839 * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value 1840 * will be cleared in the calling task's notification value before the task 1841 * checks to see if any notifications are pending, and optionally blocks if no 1842 * notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX (if 1843 * limits.h is included) or 0xffffffffUL (if limits.h is not included) will have 1844 * the effect of resetting the task's notification value to 0. Setting 1845 * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged. 1846 * 1847 * @param ulBitsToClearOnExit If a notification is pending or received before 1848 * the calling task exits the xTaskNotifyWait() function then the task's 1849 * notification value (see the xTaskNotify() API function) is passed out using 1850 * the pulNotificationValue parameter. Then any bits that are set in 1851 * ulBitsToClearOnExit will be cleared in the task's notification value (note 1852 * *pulNotificationValue is set before any bits are cleared). Setting 1853 * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL 1854 * (if limits.h is not included) will have the effect of resetting the task's 1855 * notification value to 0 before the function exits. Setting 1856 * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged 1857 * when the function exits (in which case the value passed out in 1858 * pulNotificationValue will match the task's notification value). 1859 * 1860 * @param pulNotificationValue Used to pass the task's notification value out 1861 * of the function. Note the value passed out will not be effected by the 1862 * clearing of any bits caused by ulBitsToClearOnExit being non-zero. 1863 * 1864 * @param xTicksToWait The maximum amount of time that the task should wait in 1865 * the Blocked state for a notification to be received, should a notification 1866 * not already be pending when xTaskNotifyWait() was called. The task 1867 * will not consume any processing time while it is in the Blocked state. This 1868 * is specified in kernel ticks, the macro pdMS_TO_TICSK( value_in_ms ) can be 1869 * used to convert a time specified in milliseconds to a time specified in 1870 * ticks. 1871 * 1872 * @return If a notification was received (including notifications that were 1873 * already pending when xTaskNotifyWait was called) then pdPASS is 1874 * returned. Otherwise pdFAIL is returned. 1875 * 1876 * \defgroup xTaskNotifyWait xTaskNotifyWait 1877 * \ingroup TaskNotifications 1878 */ 1879 BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 1880 1881 /** 1882 * task. h 1883 * <PRE>BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );</PRE> 1884 * 1885 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro 1886 * to be available. 1887 * 1888 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 1889 * "notification value", which is a 32-bit unsigned integer (uint32_t). 1890 * 1891 * Events can be sent to a task using an intermediary object. Examples of such 1892 * objects are queues, semaphores, mutexes and event groups. Task notifications 1893 * are a method of sending an event directly to a task without the need for such 1894 * an intermediary object. 1895 * 1896 * A notification sent to a task can optionally perform an action, such as 1897 * update, overwrite or increment the task's notification value. In that way 1898 * task notifications can be used to send data to a task, or be used as light 1899 * weight and fast binary or counting semaphores. 1900 * 1901 * xTaskNotifyGive() is a helper macro intended for use when task notifications 1902 * are used as light weight and faster binary or counting semaphore equivalents. 1903 * Actual FreeRTOS semaphores are given using the xSemaphoreGive() API function, 1904 * the equivalent action that instead uses a task notification is 1905 * xTaskNotifyGive(). 1906 * 1907 * When task notifications are being used as a binary or counting semaphore 1908 * equivalent then the task being notified should wait for the notification 1909 * using the ulTaskNotificationTake() API function rather than the 1910 * xTaskNotifyWait() API function. 1911 * 1912 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details. 1913 * 1914 * @param xTaskToNotify The handle of the task being notified. The handle to a 1915 * task can be returned from the xTaskCreate() API function used to create the 1916 * task, and the handle of the currently running task can be obtained by calling 1917 * xTaskGetCurrentTaskHandle(). 1918 * 1919 * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the 1920 * eAction parameter set to eIncrement - so pdPASS is always returned. 1921 * 1922 * \defgroup xTaskNotifyGive xTaskNotifyGive 1923 * \ingroup TaskNotifications 1924 */ 1925 #define xTaskNotifyGive( xTaskToNotify ) xTaskGenericNotify( ( xTaskToNotify ), ( 0 ), eIncrement, NULL ) 1926 1927 /** 1928 * task. h 1929 * <PRE>void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken ); 1930 * 1931 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro 1932 * to be available. 1933 * 1934 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 1935 * "notification value", which is a 32-bit unsigned integer (uint32_t). 1936 * 1937 * A version of xTaskNotifyGive() that can be called from an interrupt service 1938 * routine (ISR). 1939 * 1940 * Events can be sent to a task using an intermediary object. Examples of such 1941 * objects are queues, semaphores, mutexes and event groups. Task notifications 1942 * are a method of sending an event directly to a task without the need for such 1943 * an intermediary object. 1944 * 1945 * A notification sent to a task can optionally perform an action, such as 1946 * update, overwrite or increment the task's notification value. In that way 1947 * task notifications can be used to send data to a task, or be used as light 1948 * weight and fast binary or counting semaphores. 1949 * 1950 * vTaskNotifyGiveFromISR() is intended for use when task notifications are 1951 * used as light weight and faster binary or counting semaphore equivalents. 1952 * Actual FreeRTOS semaphores are given from an ISR using the 1953 * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses 1954 * a task notification is vTaskNotifyGiveFromISR(). 1955 * 1956 * When task notifications are being used as a binary or counting semaphore 1957 * equivalent then the task being notified should wait for the notification 1958 * using the ulTaskNotificationTake() API function rather than the 1959 * xTaskNotifyWait() API function. 1960 * 1961 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for more details. 1962 * 1963 * @param xTaskToNotify The handle of the task being notified. The handle to a 1964 * task can be returned from the xTaskCreate() API function used to create the 1965 * task, and the handle of the currently running task can be obtained by calling 1966 * xTaskGetCurrentTaskHandle(). 1967 * 1968 * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set 1969 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the 1970 * task to which the notification was sent to leave the Blocked state, and the 1971 * unblocked task has a priority higher than the currently running task. If 1972 * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch 1973 * should be requested before the interrupt is exited. How a context switch is 1974 * requested from an ISR is dependent on the port - see the documentation page 1975 * for the port in use. 1976 * 1977 * \defgroup xTaskNotifyWait xTaskNotifyWait 1978 * \ingroup TaskNotifications 1979 */ 1980 void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 1981 1982 /** 1983 * task. h 1984 * <PRE>uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );</pre> 1985 * 1986 * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this 1987 * function to be available. 1988 * 1989 * When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private 1990 * "notification value", which is a 32-bit unsigned integer (uint32_t). 1991 * 1992 * Events can be sent to a task using an intermediary object. Examples of such 1993 * objects are queues, semaphores, mutexes and event groups. Task notifications 1994 * are a method of sending an event directly to a task without the need for such 1995 * an intermediary object. 1996 * 1997 * A notification sent to a task can optionally perform an action, such as 1998 * update, overwrite or increment the task's notification value. In that way 1999 * task notifications can be used to send data to a task, or be used as light 2000 * weight and fast binary or counting semaphores. 2001 * 2002 * ulTaskNotifyTake() is intended for use when a task notification is used as a 2003 * faster and lighter weight binary or counting semaphore alternative. Actual 2004 * FreeRTOS semaphores are taken using the xSemaphoreTake() API function, the 2005 * equivalent action that instead uses a task notification is 2006 * ulTaskNotifyTake(). 2007 * 2008 * When a task is using its notification value as a binary or counting semaphore 2009 * other tasks should send notifications to it using the xTaskNotifyGive() 2010 * macro, or xTaskNotify() function with the eAction parameter set to 2011 * eIncrement. 2012 * 2013 * ulTaskNotifyTake() can either clear the task's notification value to 2014 * zero on exit, in which case the notification value acts like a binary 2015 * semaphore, or decrement the task's notification value on exit, in which case 2016 * the notification value acts like a counting semaphore. 2017 * 2018 * A task can use ulTaskNotifyTake() to [optionally] block to wait for a 2019 * the task's notification value to be non-zero. The task does not consume any 2020 * CPU time while it is in the Blocked state. 2021 * 2022 * Where as xTaskNotifyWait() will return when a notification is pending, 2023 * ulTaskNotifyTake() will return when the task's notification value is 2024 * not zero. 2025 * 2026 * See http://www.FreeRTOS.org/RTOS-task-notifications.html for details. 2027 * 2028 * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's 2029 * notification value is decremented when the function exits. In this way the 2030 * notification value acts like a counting semaphore. If xClearCountOnExit is 2031 * not pdFALSE then the task's notification value is cleared to zero when the 2032 * function exits. In this way the notification value acts like a binary 2033 * semaphore. 2034 * 2035 * @param xTicksToWait The maximum amount of time that the task should wait in 2036 * the Blocked state for the task's notification value to be greater than zero, 2037 * should the count not already be greater than zero when 2038 * ulTaskNotifyTake() was called. The task will not consume any processing 2039 * time while it is in the Blocked state. This is specified in kernel ticks, 2040 * the macro pdMS_TO_TICSK( value_in_ms ) can be used to convert a time 2041 * specified in milliseconds to a time specified in ticks. 2042 * 2043 * @return The task's notification count before it is either cleared to zero or 2044 * decremented (see the xClearCountOnExit parameter). 2045 * 2046 * \defgroup ulTaskNotifyTake ulTaskNotifyTake 2047 * \ingroup TaskNotifications 2048 */ 2049 uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 2050 2051 /** 2052 * task. h 2053 * <PRE>BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );</pre> 2054 * 2055 * If the notification state of the task referenced by the handle xTask is 2056 * eNotified, then set the task's notification state to eNotWaitingNotification. 2057 * The task's notification value is not altered. Set xTask to NULL to clear the 2058 * notification state of the calling task. 2059 * 2060 * @return pdTRUE if the task's notification state was set to 2061 * eNotWaitingNotification, otherwise pdFALSE. 2062 * \defgroup xTaskNotifyStateClear xTaskNotifyStateClear 2063 * \ingroup TaskNotifications 2064 */ 2065 BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask ); 2066 2067 /*----------------------------------------------------------- 2068 * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES 2069 *----------------------------------------------------------*/ 2070 2071 /* 2072 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 2073 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 2074 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 2075 * 2076 * Called from the real time kernel tick (either preemptive or cooperative), 2077 * this increments the tick count and checks if any tasks that are blocked 2078 * for a finite period required removing from a blocked list and placing on 2079 * a ready list. If a non-zero value is returned then a context switch is 2080 * required because either: 2081 * + A task was removed from a blocked list because its timeout had expired, 2082 * or 2083 * + Time slicing is in use and there is a task of equal priority to the 2084 * currently running task. 2085 */ 2086 BaseType_t xTaskIncrementTick( void ) PRIVILEGED_FUNCTION; 2087 2088 /* 2089 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 2090 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 2091 * 2092 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 2093 * 2094 * Removes the calling task from the ready list and places it both 2095 * on the list of tasks waiting for a particular event, and the 2096 * list of delayed tasks. The task will be removed from both lists 2097 * and replaced on the ready list should either the event occur (and 2098 * there be no higher priority tasks waiting on the same event) or 2099 * the delay period expires. 2100 * 2101 * The 'unordered' version replaces the event list item value with the 2102 * xItemValue value, and inserts the list item at the end of the list. 2103 * 2104 * The 'ordered' version uses the existing event list item value (which is the 2105 * owning tasks priority) to insert the list item into the event list is task 2106 * priority order. 2107 * 2108 * @param pxEventList The list containing tasks that are blocked waiting 2109 * for the event to occur. 2110 * 2111 * @param xItemValue The item value to use for the event list item when the 2112 * event list is not ordered by task priority. 2113 * 2114 * @param xTicksToWait The maximum amount of time that the task should wait 2115 * for the event to occur. This is specified in kernel ticks,the constant 2116 * portTICK_PERIOD_MS can be used to convert kernel ticks into a real time 2117 * period. 2118 */ 2119 void vTaskPlaceOnEventList( List_t * const pxEventList, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 2120 void vTaskPlaceOnUnorderedEventList( List_t * pxEventList, const TickType_t xItemValue, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 2121 2122 /* 2123 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 2124 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 2125 * 2126 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 2127 * 2128 * This function performs nearly the same function as vTaskPlaceOnEventList(). 2129 * The difference being that this function does not permit tasks to block 2130 * indefinitely, whereas vTaskPlaceOnEventList() does. 2131 * 2132 */ 2133 void vTaskPlaceOnEventListRestricted( List_t * const pxEventList, TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION; 2134 2135 /* 2136 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS AN 2137 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 2138 * 2139 * THIS FUNCTION MUST BE CALLED WITH INTERRUPTS DISABLED. 2140 * 2141 * Removes a task from both the specified event list and the list of blocked 2142 * tasks, and places it on a ready queue. 2143 * 2144 * xTaskRemoveFromEventList()/xTaskRemoveFromUnorderedEventList() will be called 2145 * if either an event occurs to unblock a task, or the block timeout period 2146 * expires. 2147 * 2148 * xTaskRemoveFromEventList() is used when the event list is in task priority 2149 * order. It removes the list item from the head of the event list as that will 2150 * have the highest priority owning task of all the tasks on the event list. 2151 * xTaskRemoveFromUnorderedEventList() is used when the event list is not 2152 * ordered and the event list items hold something other than the owning tasks 2153 * priority. In this case the event list item value is updated to the value 2154 * passed in the xItemValue parameter. 2155 * 2156 * @return pdTRUE if the task being removed has a higher priority than the task 2157 * making the call, otherwise pdFALSE. 2158 */ 2159 BaseType_t xTaskRemoveFromEventList( const List_t * const pxEventList ) PRIVILEGED_FUNCTION; 2160 BaseType_t xTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem, const TickType_t xItemValue ) PRIVILEGED_FUNCTION; 2161 2162 /* 2163 * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY 2164 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS 2165 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER. 2166 * 2167 * Sets the pointer to the current TCB to the TCB of the highest priority task 2168 * that is ready to run. 2169 */ 2170 void vTaskSwitchContext( void ) PRIVILEGED_FUNCTION; 2171 2172 /* 2173 * THESE FUNCTIONS MUST NOT BE USED FROM APPLICATION CODE. THEY ARE USED BY 2174 * THE EVENT BITS MODULE. 2175 */ 2176 TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION; 2177 2178 /* 2179 * Return the handle of the calling task. 2180 */ 2181 TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION; 2182 2183 /* 2184 * Capture the current time status for future reference. 2185 */ 2186 void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION; 2187 2188 /* 2189 * Compare the time status now with that previously captured to see if the 2190 * timeout has expired. 2191 */ 2192 BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION; 2193 2194 /* 2195 * Shortcut used by the queue implementation to prevent unnecessary call to 2196 * taskYIELD(); 2197 */ 2198 void vTaskMissedYield( void ) PRIVILEGED_FUNCTION; 2199 2200 /* 2201 * Returns the scheduler state as taskSCHEDULER_RUNNING, 2202 * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED. 2203 */ 2204 BaseType_t xTaskGetSchedulerState( void ) PRIVILEGED_FUNCTION; 2205 2206 /* 2207 * Raises the priority of the mutex holder to that of the calling task should 2208 * the mutex holder have a priority less than the calling task. 2209 */ 2210 void vTaskPriorityInherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION; 2211 2212 /* 2213 * Set the priority of a task back to its proper priority in the case that it 2214 * inherited a higher priority while it was holding a semaphore. 2215 */ 2216 BaseType_t xTaskPriorityDisinherit( TaskHandle_t const pxMutexHolder ) PRIVILEGED_FUNCTION; 2217 2218 /* 2219 * Get the uxTCBNumber assigned to the task referenced by the xTask parameter. 2220 */ 2221 UBaseType_t uxTaskGetTaskNumber( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; 2222 2223 /* 2224 * Set the uxTaskNumber of the task referenced by the xTask parameter to 2225 * uxHandle. 2226 */ 2227 void vTaskSetTaskNumber( TaskHandle_t xTask, const UBaseType_t uxHandle ) PRIVILEGED_FUNCTION; 2228 2229 /* 2230 * Only available when configUSE_TICKLESS_IDLE is set to 1. 2231 * If tickless mode is being used, or a low power mode is implemented, then 2232 * the tick interrupt will not execute during idle periods. When this is the 2233 * case, the tick count value maintained by the scheduler needs to be kept up 2234 * to date with the actual execution time by being skipped forward by a time 2235 * equal to the idle period. 2236 */ 2237 void vTaskStepTick( const TickType_t xTicksToJump ) PRIVILEGED_FUNCTION; 2238 2239 /* 2240 * Only avilable when configUSE_TICKLESS_IDLE is set to 1. 2241 * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port 2242 * specific sleep function to determine if it is ok to proceed with the sleep, 2243 * and if it is ok to proceed, if it is ok to sleep indefinitely. 2244 * 2245 * This function is necessary because portSUPPRESS_TICKS_AND_SLEEP() is only 2246 * called with the scheduler suspended, not from within a critical section. It 2247 * is therefore possible for an interrupt to request a context switch between 2248 * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being 2249 * entered. eTaskConfirmSleepModeStatus() should be called from a short 2250 * critical section between the timer being stopped and the sleep mode being 2251 * entered to ensure it is ok to proceed into the sleep mode. 2252 */ 2253 eSleepModeStatus eTaskConfirmSleepModeStatus( void ) PRIVILEGED_FUNCTION; 2254 2255 /* 2256 * For internal use only. Increment the mutex held count when a mutex is 2257 * taken and return the handle of the task that has taken the mutex. 2258 */ 2259 void *pvTaskIncrementMutexHeldCount( void ) PRIVILEGED_FUNCTION; 2260 2261 #ifdef __cplusplus 2262 } 2263 #endif 2264 #endif /* INC_TASK_H */ 2265 2266 2267 2268