Lines Matching full:the
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
50 * If tskKERNEL_VERSION_NUMBER ends with + it represents the version in development
51 * after the numbered release.
53 * The tskKERNEL_VERSION_MAJOR, tskKERNEL_VERSION_MINOR, tskKERNEL_VERSION_BUILD
54 * values will reflect the last released version number.
74 /* The direct to task notification feature used to have only a single notification
76 * configTASK_NOTIFICATION_ARRAY_ENTRIES. For backward compatibility, any use of the
77 * original direct to task notification defaults to using the first index in the
86 * be used as a parameter to vTaskDelete to delete the task.
91 struct tskTaskControlBlock; /* The old naming convention is used to prevent breaking kernel aware d…
96 * Defines the prototype to which the application task hook function must
104 eRunning = 0, /* A task is querying the state of itself, so must be running. */
105 eReady, /* The task being queried is in a ready or pending ready list. */
106 eBlocked, /* The task being queried is in the Blocked state. */
107 …eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with…
108 eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */
115 eNoAction = 0, /* Notify the task without updating its notify value. */
116 eSetBits, /* Set bits in the task's notification value. */
117 eIncrement, /* Increment the task's notification value. */
118 …WithOverwrite, /* Set the task's notification value to a specific value even if the previous val…
119 …eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read…
132 * Defines the memory ranges allocated to the task when an MPU is used.
158 /* Used with the uxTaskGetSystemState() function to return the state of each task
159 * in the system. */
162 …ndle_t xHandle; /* The handle of the task to which the rest of the informa…
163 … /* A pointer to the task's name. This value will be invalid if the task was …
164 UBaseType_t xTaskNumber; /* A number unique to the task. */
165 …eTaskState eCurrentState; /* The state in which the task existed when the stru…
166 …e_t uxCurrentPriority; /* The priority at which the task was running (may be inheri…
167 …UBaseType_t uxBasePriority; /* The priority to which the task will return if the…
168 …RUN_TIME_COUNTER_TYPE ulRunTimeCounter; /* The total run time allocated to the task so far, as def…
169 …StackType_t * pxStackBase; /* Points to the lowest address of the task's stack …
171 …StackType_t * pxTopOfStack; /* Points to the top address of the task's stack area. */
172 …StackType_t * pxEndOfStack; /* Points to the end address of the task's stack area. */
174 …; /* The minimum amount of stack space that has remained for the task since the task was created.…
176 UBaseType_t uxCoreAffinityMask; /* The core affinity mask for the task */
184 …eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected i…
191 * Defines the priority used by the idle task. This must not be modified.
217 * Macro to mark the start of a critical code region. Preemptive context
220 * NOTE: This may alter the stack (depending on the portable implementation)
236 * Macro to mark the end of a critical code region. Preemptive context
239 * NOTE: This may alter the stack (depending on the portable implementation)
273 * 0 to generate more optimal code when configASSERT() is defined as the constant
299 * Create a new task and add it to the list of tasks that are ready to run.
301 * Internally, within the FreeRTOS implementation, tasks use two blocks of
302 * memory. The first block is used to hold the task's data structures. The
303 * second block is used by the task as its stack. If a task is created using
305 * allocated inside the xTaskCreate() function. (see
307 * xTaskCreateStatic() then the application writer must provide the required
315 * access to the entire microcontroller memory map. Systems that include MPU
319 * @param pxTaskCode Pointer to the task entry function. Tasks
322 * @param pcName A descriptive name for the task. This is mainly used to
326 * @param usStackDepth The size of the task stack specified as the number of
327 * variables the stack can hold - not the number of bytes. For example, if
328 * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes
331 * @param pvParameters Pointer that will be used as the parameter for the task
334 * @param uxPriority The priority at which the task should run. Systems that
336 * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For
337 * example, to create a privileged task at priority 2 the uxPriority parameter
340 * @param pxCreatedTask Used to pass back a handle by which the created task
343 * @return pdPASS if the task was successfully created and added to a ready
344 * list, otherwise an error code defined in the file projdefs.h
363 * // Create the task, storing the handle. Note that the passed parameter ucParameterToPass
364 …* // must exist for the lifetime of the task, so in this case is declared static. If it was jus…
365 … an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
366 * // the new task attempts to access it.
370 * // Use the handle to delete the task.
411 * Create a new task and add it to the list of tasks that are ready to run.
413 * Internally, within the FreeRTOS implementation, tasks use two blocks of
414 * memory. The first block is used to hold the task's data structures. The
415 * second block is used by the task as its stack. If a task is created using
417 * allocated inside the xTaskCreate() function. (see
419 * xTaskCreateStatic() then the application writer must provide the required
423 * @param pxTaskCode Pointer to the task entry function. Tasks
426 * @param pcName A descriptive name for the task. This is mainly used to
427 * facilitate debugging. The maximum length of the string is defined by
430 * @param ulStackDepth The size of the task stack specified as the number of
431 * variables the stack can hold - not the number of bytes. For example, if
432 * the stack is 32-bits wide and ulStackDepth is defined as 100 then 400 bytes
435 * @param pvParameters Pointer that will be used as the parameter for the task
438 * @param uxPriority The priority at which the task will run.
441 * ulStackDepth indexes - the array will then be used as the task's stack,
442 * removing the need for the stack to be allocated dynamically.
445 * then be used to hold the task's data structures, removing the need for the
448 * @return If neither puxStackBuffer nor pxTaskBuffer are NULL, then the task
449 * will be created and a handle to the created task is returned. If either
450 * puxStackBuffer or pxTaskBuffer are NULL then the task will not be created and
456 * // Dimensions of the buffer that the task being created will use as its stack.
457 * // NOTE: This is the number of words the stack will hold, not the number of
462 * // Structure that will hold the TCB of the task being created.
465 * // Buffer that the task being created will use as its stack. Note this is
466 * // an array of StackType_t variables. The size of StackType_t is dependent on
467 * // the RTOS port.
470 * // Function that implements the task being created.
473 * // The parameter value is expected to be 1 as 1 is passed in the
474 * // pvParameters value in the call to xTaskCreateStatic().
488 * // Create the task without using any dynamic memory allocation.
490 * vTaskCode, // Function that implements the task.
491 * "NAME", // Text name for the task.
493 * ( void * ) 1, // Parameter passed into the task.
494 * tskIDLE_PRIORITY,// Priority at which the task is created.
495 * xStack, // Array to use as the task's stack.
496 * &xTaskBuffer ); // Variable to hold the task's data structure.
498 * // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have
499 * // been created, and xHandle will be the task's handle. Use the handle
500 * // to suspend the task.
539 * Create a new task and add it to the list of tasks that are ready to run.
540 * The function parameters define the memory regions and associated access
541 * permissions allocated to the task.
547 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
548 * documentation) plus an optional stack buffer and the memory region
551 * @param pxCreatedTask Used to pass back a handle by which the created task
554 * @return pdPASS if the task was successfully created and added to a ready
555 * list, otherwise an error code defined in the file projdefs.h
559 * // Create an TaskParameters_t structure that defines the task to be created.
562 * vATask, // pvTaskCode - the function that implements the task.
563 * "ATask", // pcName - just a text name for the task to assist debugging.
564 * 100, // usStackDepth - the stack size DEFINED IN WORDS.
565 * NULL, // pvParameters - passed into the task function as the function parameters.
566 …* ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the tas…
567 * cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
570 * // the task, with appropriate access permissions. Different processors have
571 * // different memory alignment requirements - refer to the FreeRTOS documentation
585 * // Create a task from the const structure defined above. The task handle
586 * // is requested (the second parameter is not NULL) but in this case just for
590 * // Start the scheduler.
593 * // Will only get here if there was insufficient memory to create the idle
623 * Internally, within the FreeRTOS implementation, tasks use two blocks of
624 * memory. The first block is used to hold the task's data structures. The
625 * second block is used by the task as its stack. If a task is created using
626 * xTaskCreateRestricted() then the stack is provided by the application writer,
627 * and the memory used to hold the task's data structure is automatically
628 * dynamically allocated inside the xTaskCreateRestricted() function. If a task
629 * is created using xTaskCreateRestrictedStatic() then the application writer
630 * must provide the memory used to hold the task's data structures too.
635 * for each of the normal xTaskCreate() parameters (see the xTaskCreate() API
636 * documentation) plus an optional stack buffer and the memory region
637 * definitions. If configSUPPORT_STATIC_ALLOCATION is set to 1 the structure
639 * StaticTask_t - which is then used to hold the task's data structure.
641 * @param pxCreatedTask Used to pass back a handle by which the created task
644 * @return pdPASS if the task was successfully created and added to a ready
645 * list, otherwise an error code defined in the file projdefs.h
649 * // Create an TaskParameters_t structure that defines the task to be created.
650 * // The StaticTask_t variable is only included in the structure when
651 * // configSUPPORT_STATIC_ALLOCATION is set to 1. The PRIVILEGED_DATA macro can
652 * // be used to force the variable into the RTOS kernel's privileged data area.
656 * vATask, // pvTaskCode - the function that implements the task.
657 * "ATask", // pcName - just a text name for the task to assist debugging.
658 * 100, // usStackDepth - the stack size DEFINED IN WORDS.
659 * NULL, // pvParameters - passed into the task function as the function parameters.
660 …* ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the tas…
661 * cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
664 * // the task, with appropriate access permissions. Different processors have
665 * // different memory alignment requirements - refer to the FreeRTOS documentation
674 * &xTaskBuffer; // Holds the task's data structure.
681 * // Create a task from the const structure defined above. The task handle
682 * // is requested (the second parameter is not NULL) but in this case just for
686 * // Start the scheduler.
689 * // Will only get here if there was insufficient memory to create the idle
714 * Memory regions are assigned to a restricted task when the task is created by
718 * @param xTaskToModify The handle of the task being updated.
720 * @param[in] pxRegions A pointer to a MemoryRegion_t structure that contains the
726 * // allowing read/write access for 1024 bytes starting at the beginning of the
727 * // ucOneKByte array. The other two of the maximum 3 definable regions are
740 * // memory as defined by the MPU configuration. At some point it is
741 * // desired that these MPU regions are replaced with that defined in the
743 * // for this purpose. NULL is used as the task handle to indicate that this
744 * // function should modify the MPU regions of the calling task.
747 * // Now the task can continue its function, but from this point on can only
748 * // access its stack and the ucOneKByte array (unless any other statically
767 * See the configuration section for more information.
769 * Remove a task from the RTOS real time kernel's management. The task being
772 * NOTE: The idle task is responsible for freeing the kernel allocated
774 * the idle task is not starved of microcontroller processing time if your
775 * application makes any calls to vTaskDelete (). Memory allocated by the
776 * task code is not automatically freed, and should be freed before the task
779 * See the demo application file death.c for sample code that utilises
782 * @param xTaskToDelete The handle of the task to be deleted. Passing NULL will
783 * cause the calling task to be deleted.
791 * // Create the task, storing the handle.
794 * // Use the handle to delete the task.
813 * Delay a task for a given number of ticks. The actual time that the
814 * task remains blocked depends on the tick rate. The constant
815 * portTICK_PERIOD_MS can be used to calculate real time from the tick
816 * rate - with the resolution of one tick period.
819 * See the configuration section for more information.
822 * vTaskDelay() specifies a time at which the task wishes to unblock relative to
823 * the time at which vTaskDelay() is called. For example, specifying a block
824 * period of 100 ticks will cause the task to unblock 100 ticks after
826 * of controlling the frequency of a periodic task as the path taken through the
827 * code, as well as other task and interrupt activity, will affect the frequency
828 * at which vTaskDelay() gets called and therefore the time at which the task
831 * absolute time (rather than a relative time) at which the calling task should
834 * @param xTicksToDelay The amount of time, in tick periods, that
835 * the calling task should block.
846 * // Simply toggle the LED every 500ms, blocking between each toggle.
864 * See the configuration section for more information.
870 * cause a task to block for the specified number of ticks from the time vTaskDelay () is
872 * execution frequency as the time between a task starting to execute and that task
873 * calling vTaskDelay () may not be fixed [the task may take a different path though the
877 * Whereas vTaskDelay () specifies a wake time relative to the time at which the function
878 * is called, xTaskDelayUntil () specifies the absolute (exact) time at which it wishes to
881 * The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a
884 * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the
885 * task was last unblocked. The variable must be initialised with the current time
886 * prior to its first use (see the example below). Following this the variable is
889 * @param xTimeIncrement The cycle time period. The task will be unblocked at
890 * time *pxPreviousWakeTime + xTimeIncrement. Calling xTaskDelayUntil with the
891 * same xTimeIncrement parameter value will cause the task to execute with
894 * @return Value which can be used to check whether the task was actually delayed.
895 * Will be pdTRUE if the task way delayed and pdFALSE otherwise. A task will not
896 * be delayed if the next expected wake time is in the past.
907 * // Initialise the xLastWakeTime variable with the current time.
911 * // Wait for the next cycle.
915 * // whether a deadline was missed if the code here took too long.
926 * vTaskDelayUntil() is the older version of xTaskDelayUntil() and does not
944 * A task will enter the Blocked state when it is waiting for an event. The
947 * xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task
948 * that is in the Blocked state is used in a call to xTaskAbortDelay() then the
949 * task will leave the Blocked state, and return from whichever function call
950 * placed the task into the Blocked state.
954 * take. For example, if the task was blocked on a queue the interrupt handler
955 * would then need to know if the queue was locked.
957 * @param xTask The handle of the task to remove from the Blocked state.
959 * @return If the task referenced by xTask was not in the Blocked state then
976 * See the configuration section for more information.
978 * Obtain the priority of any task.
980 * @param xTask Handle of the task to be queried. Passing a NULL
981 * handle results in the priority of the calling task being returned.
983 * @return The priority of xTask.
991 * // Create a task, storing the handle.
996 * // Use the handle to obtain the priority of the created task.
1001 * // The task has changed it's priority.
1006 * // Is our priority higher than the created task?
1035 * function to be available. See the configuration section for more information.
1037 * Obtain the base priority of any task.
1039 * @param xTask Handle of the task to be queried. Passing a NULL
1040 * handle results in the base priority of the calling task being returned.
1042 * @return The base priority of xTask.
1066 * See the configuration section for more information.
1068 * Obtain the state of any task. States are encoded by the eTaskState
1071 * @param xTask Handle of the task to be queried.
1073 * @return The state of xTask at the time the function was called. Note the
1074 * state of the task might change between the function being called, and the
1075 * functions return value being tested by the calling task.
1088 * available. See the configuration section for more information.
1092 * @param xTask Handle of the task being queried. If xTask is NULL then
1093 * information will be returned about the calling task.
1095 * @param pxTaskStatus A pointer to the TaskStatus_t structure that will be
1096 * filled with information about the task referenced by the handle passed using
1097 * the xTask parameter.
1099 * @param xGetFreeStackSpace The TaskStatus_t structure contains a member to report
1100 * the stack high water mark of the task being queried. Calculating the stack
1101 * high water mark takes a relatively long time, and can make the system
1102 * temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to
1103 * allow the high water mark checking to be skipped. The high watermark value
1104 * will only be written to the TaskStatus_t structure if xGetFreeStackSpace is
1107 * @param eState The TaskStatus_t structure contains a member to report the
1108 * state of the task being queried. Obtaining the task state is not as fast as
1109 * a simple assignment - so the eState parameter is provided to allow the state
1110 * information to be omitted from the TaskStatus_t structure. To obtain state
1111 * information then set eState to eInvalid - otherwise the value passed in
1112 * eState will be reported as the task state in the TaskStatus_t structure.
1121 * // Obtain the handle of a task from its name.
1124 * // Check the handle is not NULL.
1127 * // Use the handle to obtain further information about the task.
1130 * pdTRUE, // Include the high water mark in xTaskDetails.
1131 * eInvalid ); // Include the task state in xTaskDetails.
1151 * See the configuration section for more information.
1153 * Set the priority of any task.
1155 * A context switch will occur before the function returns if the priority
1156 * being set is higher than the currently executing task.
1158 * @param xTask Handle to the task for which the priority is being set.
1159 * Passing a NULL handle results in the priority of the calling task being set.
1161 * @param uxNewPriority The priority to which the task will be set.
1169 * // Create a task, storing the handle.
1174 * // Use the handle to raise the priority of the created task.
1179 * // Use a NULL handle to raise our priority to the same value.
1196 * See the configuration section for more information.
1202 * i.e. calling vTaskSuspend () twice on the same task still only requires one
1203 * call to vTaskResume () to ready the suspended task.
1205 * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL
1206 * handle will cause the calling task to be suspended.
1214 * // Create a task, storing the handle.
1219 * // Use the handle to suspend the created task.
1224 * // The created task will not run during this period, unless
1234 * // with our handle as the parameter.
1249 * See the configuration section for more information.
1257 * @param xTaskToResume Handle to the task being readied.
1265 * // Create a task, storing the handle.
1270 * // Use the handle to suspend the created task.
1275 * // The created task will not run during this period, unless
1281 * // Resume the suspended task ourselves.
1284 * // The created task will once again get microcontroller processing
1285 * // time in accordance with its priority within the system.
1300 * available. See the configuration section for more information.
1309 * interrupt if there is a chance that the interrupt could arrive prior to the
1313 * @param xTaskToResume Handle to the task being readied.
1315 * @return pdTRUE if resuming the task should result in a context switch,
1316 * otherwise pdFALSE. This is used by the ISR to determine if a context switch
1317 * may be required following the ISR.
1327 * @brief Sets the core affinity mask for a task.
1329 * It sets the cores on which a task can run. configUSE_CORE_AFFINITY must
1332 * @param xTask The handle of the task to set the core affinity mask for.
1333 * Passing NULL will set the core affinity mask for the calling task.
1335 * @param uxCoreAffinityMask A bitwise value that indicates the cores on
1336 * which the task can run. Cores are numbered from 0 to configNUMBER_OF_CORES - 1.
1342 * // The function that creates task.
1348 * // Create a task, storing the handle.
1351 * // Define the core affinity mask such that this task can only run
1355 * //Set the core affinity mask for the task.
1366 * @brief Gets the core affinity mask for a task.
1371 * @param xTask The handle of the task to get the core affinity mask for.
1372 * Passing NULL will get the core affinity mask for the calling task.
1374 * @return The core affinity mask which is a bitwise value that indicates
1375 * the cores on which a task can run. Cores are numbered from 0 to
1377 * the core affinity mask is 0x03.
1381 * // Task handle of the networking task - it is populated elsewhere.
1389 * // Create a task, storing the handle.
1392 * //Get the core affinity mask for the networking task.
1395 * // Here is a hypothetical scenario, just for the example. Assume that we
1396 * // have 2 cores - Core 0 and core 1. We want to pin the application task to
1397 * // the core different than the networking task to ensure that the
1401 * // The networking task can run on core 0, pin our task to core 1.
1419 * @param xTask The handle of the task to disable preemption. Passing NULL
1420 * disables preemption for the calling task.
1436 * // The task will not be preempted when it is executing in this portion ...
1438 * // ... until the preemption is enabled again.
1441 * // The task can be preempted when it is executing in this portion.
1453 * @param xTask The handle of the task to enable preemption. Passing NULL
1454 * enables preemption for the calling task.
1470 * // The task will not be preempted when it is executing in this portion ...
1472 * // ... until the preemption is enabled again.
1475 * // The task can be preempted when it is executing in this portion.
1492 * Starts the real time kernel tick processing. After calling the kernel
1495 * See the demo application file main.c for an example of creating
1496 * tasks and starting the kernel.
1502 * // Create at least one task before starting the kernel.
1505 * // Start the real time kernel with preemption.
1523 * NOTE: At the time of writing only the x86 real mode port, which runs on a PC
1526 * Stops the real time kernel tick. All created tasks will be automatically
1528 * stop. Execution then resumes from the point where vTaskStartScheduler ()
1531 * See the demo application file main. c in the demo/PC directory for an
1534 * vTaskEndScheduler () requires an exit function to be defined within the
1535 * portable layer (see vPortEndScheduler () in port. c for the PC port). This
1536 * performs hardware specific operations such as stopping the kernel tick.
1538 * vTaskEndScheduler () will cause all of the resources allocated by the
1550 * // At some point we want to end the real time kernel processing
1558 * // Create at least one task before starting the kernel.
1561 * // Start the real time kernel with preemption.
1564 * // Will only get here when the vTaskCode () task has called
1581 * Suspends the scheduler without disabling interrupts. Context switches will
1582 * not occur while the scheduler is suspended.
1584 * After calling vTaskSuspendAll () the calling task will continue to execute
1588 * API functions that have the potential to cause a context switch (for example,
1589 * xTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler
1602 * // At some point the task wants to perform a long operation during
1604 * // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
1605 * // operation may cause interrupts to be missed - including the
1608 * // Prevent the real time kernel swapping out the task.
1611 * // Perform the operation here. There is no need to use critical
1612 * // sections as we have all the microcontroller processing time.
1613 * // During this time interrupts will still operate and the kernel
1618 * // The operation is complete. Restart the kernel.
1637 * xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks
1640 * @return If resuming the scheduler caused a context switch then pdTRUE is
1653 * // At some point the task wants to perform a long operation during
1655 * // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
1656 * // operation may cause interrupts to be missed - including the
1659 * // Prevent the real time kernel swapping out the task.
1662 * // Perform the operation here. There is no need to use critical
1663 * // sections as we have all the microcontroller processing time.
1664 * // During this time interrupts will still operate and the real
1669 * // The operation is complete. Restart the kernel. We want to force
1670 * // a context switch - but there is no point if resuming the scheduler
1694 * @return The count of ticks since vTaskStartScheduler was called.
1707 * @return The count of ticks since vTaskStartScheduler was called.
1710 * ISR - provided that TickType_t is the natural word size of the
1725 * @return The number of tasks that the real time kernel is currently managing.
1727 * has been deleted but not yet freed by the idle task will also be
1728 * included in the count.
1741 * @return The text (human readable) name of the task referenced by the handle
1759 * @return The handle of the task that has the human readable name pcNameToQuery.
1779 * buffer and stack buffer. These are the same buffers that are supplied
1780 * at the time of creation.
1782 * @param xTask The task for which to retrieve the buffers.
1784 * @param ppuxStackBuffer Used to return a pointer to the task's stack buffer.
1786 * @param ppxTaskBuffer Used to return a pointer to the task's data structure
1809 * Returns the high water mark of the stack associated with xTask. That is,
1810 * the minimum free stack space there has been (in words, so on a 32 bit machine
1811 * a value of 1 means 4 bytes) since the task started. The smaller the returned
1812 * number the closer the task has come to overflowing its stack.
1814 * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the
1815 * same except for their return type. Using configSTACK_DEPTH_TYPE allows the
1816 * user to determine the return type. It gets around the problem of the value
1820 * @param xTask Handle of the task associated with the stack to be checked.
1821 * Set xTask to NULL to check the stack of the calling task.
1823 * @return The smallest amount of free stack space there has been (in words, so
1824 * actual spaces on the stack rather than bytes) since the task referenced by
1840 * Returns the high water mark of the stack associated with xTask. That is,
1841 * the minimum free stack space there has been (in words, so on a 32 bit machine
1842 * a value of 1 means 4 bytes) since the task started. The smaller the returned
1843 * number the closer the task has come to overflowing its stack.
1845 * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the
1846 * same except for their return type. Using configSTACK_DEPTH_TYPE allows the
1847 * user to determine the return type. It gets around the problem of the value
1851 * @param xTask Handle of the task associated with the stack to be checked.
1852 * Set xTask to NULL to check the stack of the calling task.
1854 * @return The smallest amount of free stack space there has been (in words, so
1855 * actual spaces on the stack rather than bytes) since the task referenced by
1864 * so the following two prototypes will cause a compilation error. This can be
1865 * fixed by simply guarding against the inclusion of these two prototypes unless
1866 * they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration
1877 * Sets pxHookFunction to be the task hook function used by the task xTask.
1878 * Passing xTask as NULL has the effect of setting the calling tasks hook
1890 * Returns the pxHookFunction value assigned to the task xTask. Do not
1902 * Returns the pxHookFunction value assigned to the task xTask. Can
1911 /* Each task contains an array of pointers that is dimensioned by the
1912 * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The
1913 * kernel does not use the pointers itself, so the application writer can use
1914 * the pointers for any purpose they wish. The following two functions are
1932 * The application stack overflow hook is called when a stack overflow is detected for a task.
1936 * @param xTask the task that just exceeded its stack boundaries.
1937 * @param pcTaskName A character string containing the name of the offending task.
1955 * The application idle hook is called by the idle task.
1956 * This allows the application designer to add background functionality without
1957 * the overhead of a separate task.
1976 * This hook function is called in the system tick handler after any OS work is completed.
1993 …* This function is used to provide a statically allocated block of memory to FreeRTOS to hold the …
1997 * @param ppxIdleTaskStackBuffer A handle to a statically allocated Stack buffer for the idle task
1998 …* @param pulIdleTaskStackSize A pointer to the number of elements that will fit in the allocated s…
2010 …* This function is used to provide a statically allocated block of memory to FreeRTOS to hold the …
2013 * In the FreeRTOS SMP, there are a total of configNUMBER_OF_CORES idle tasks:
2014 * 1. 1 Active idle task which does all the housekeeping.
2019 * The function vApplicationGetPassiveIdleTaskMemory is called with passive idle
2024 * @param ppxIdleTaskStackBuffer A handle to a statically allocated Stack buffer for the idle task
2025 …* @param pulIdleTaskStackSize A pointer to the number of elements that will fit in the allocated s…
2026 * @param xPassiveIdleTaskIndex The passive idle task index of the idle task buffer
2042 * Calls the hook function associated with xTask. Passing xTask as NULL has
2043 * the effect of calling the Running tasks (the calling task) hook function.
2045 * pvParameter is passed to the hook function for the task to interpret as it
2046 * wants. The return value is the value returned by the task hook function
2047 * registered by the user.
2058 * In single-core FreeRTOS, this function simply returns the handle of the idle
2059 * task. It is not valid to call xTaskGetIdleTaskHandle() before the scheduler
2062 * In the FreeRTOS SMP, there are a total of configNUMBER_OF_CORES idle tasks:
2063 * 1. 1 Active idle task which does all the housekeeping.
2067 * xTaskGetIdleTaskHandleForCore() with xCoreID set to 0 to get the Active
2069 * 1,2 ... ( configNUMBER_OF_CORES - 1 ) to get the Passive idle task handles.
2084 * the system. TaskStatus_t structures contain, among other things, members
2085 * for the task handle, task name, task priority, task state, and total amount
2086 * of run time consumed by the task. See the TaskStatus_t structure
2087 * definition in this file for the full member list.
2090 * the scheduler remaining suspended for an extended period.
2093 * The array must contain at least one TaskStatus_t structure for each task
2094 * that is under the control of the RTOS. The number of tasks under the control
2095 * of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function.
2097 * @param uxArraySize The size of the array pointed to by the pxTaskStatusArray
2098 * parameter. The size is specified as the number of indexes in the array, or
2099 * the number of TaskStatus_t structures contained in the array, not by the
2100 * number of bytes in the array.
2103 * FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the
2104 * total run time (as defined by the run time stats clock, see
2105 * https://www.FreeRTOS.org/rtos-run-time-stats.html) since the target booted.
2106 * pulTotalRunTime can be set to NULL to omit the total run time information.
2108 * @return The number of TaskStatus_t structures that were populated by
2109 * uxTaskGetSystemState(). This should equal the number returned by the
2110 * uxTaskGetNumberOfTasks() API function, but will be zero if the value passed
2111 * in the uxArraySize parameter was too small.
2117 * // The human readable table is written to pcWriteBuffer
2124 * // Make sure the write buffer does not contain a string.
2127 * // Take a snapshot of the number of tasks in case it changes while this
2146 * // For each populated position in the pxTaskStatusArray array,
2147 * // format the raw data as human readable ASCII data
2150 * // What percentage of the total run time has the task used?
2151 * // This will always be rounded down to the nearest integer.
2161 * // If the percentage is zero here then the task has
2162 * // consumed less than 1% of the total run time.
2170 * // The array is no longer needed, free the memory it consumes.
2189 * both be defined as 1 for this function to be available. See the
2190 * configuration section of the FreeRTOS.org website for more information.
2195 * Lists all the current tasks, along with their current state and stack
2203 * This function is provided for convenience only, and is used by many of the
2204 * demo applications. Do not consider it to be part of the scheduler.
2206 * vTaskListTasks() calls uxTaskGetSystemState(), then formats part of the
2209 * Stack usage specified as the number of unused StackType_t words stack can hold
2210 * on top of stack - not the number of bytes.
2212 * vTaskListTasks() has a dependency on the snprintf() C library function that might
2213 * bloat the code size, use a lot of stack, and provide different results on
2215 * functionality implementation of snprintf() is provided in many of the
2223 * @param pcWriteBuffer A buffer into which the above mentioned details
2225 * enough to contain the generated report. Approximately 40 bytes per
2228 * @param uxBufferLength Length of the pcWriteBuffer.
2245 * both be defined as 1 for this function to be available. See the
2246 * configuration section of the FreeRTOS.org website for more information.
2248 * WARN: This function assumes that the pcWriteBuffer is of length
2251 * use vTaskListTasks and supply the length of the pcWriteBuffer explicitly.
2256 * Lists all the current tasks, along with their current state and stack
2264 * This function is provided for convenience only, and is used by many of the
2265 * demo applications. Do not consider it to be part of the scheduler.
2267 * vTaskList() calls uxTaskGetSystemState(), then formats part of the
2270 * Stack usage specified as the number of unused StackType_t words stack can hold
2271 * on top of stack - not the number of bytes.
2273 * vTaskList() has a dependency on the snprintf() C library function that might
2274 * bloat the code size, use a lot of stack, and provide different results on
2276 * functionality implementation of snprintf() is provided in many of the
2284 * @param pcWriteBuffer A buffer into which the above mentioned details
2286 * enough to contain the generated report. Approximately 40 bytes per
2301 * must both be defined as 1 for this function to be available. The application
2304 * to configure a peripheral timer/counter and return the timers current count
2305 * value respectively. The counter should be at least 10 times the frequency of
2306 * the tick count.
2312 * accumulated execution time being stored for each task. The resolution
2313 * of the accumulated time value depends on the frequency of the timer
2314 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
2315 * Calling vTaskGetRunTimeStatistics() writes the total execution time of each
2317 * of the total system execution time.
2321 * This function is provided for convenience only, and is used by many of the
2322 * demo applications. Do not consider it to be part of the scheduler.
2325 * the uxTaskGetSystemState() output into a human readable table that displays the
2326 * amount of time each task has spent in the Running state in both absolute and
2329 * vTaskGetRunTimeStatistics() has a dependency on the snprintf() C library function
2330 * that might bloat the code size, use a lot of stack, and provide different
2332 * limited functionality implementation of snprintf() is provided in many of the
2340 * @param pcWriteBuffer A buffer into which the execution times will be
2342 * contain the generated report. Approximately 40 bytes per task should
2345 * @param uxBufferLength Length of the pcWriteBuffer.
2362 * must both be defined as 1 for this function to be available. The application
2365 * to configure a peripheral timer/counter and return the timers current count
2366 * value respectively. The counter should be at least 10 times the frequency of
2367 * the tick count.
2369 * WARN: This function assumes that the pcWriteBuffer is of length
2372 * vTaskGetRunTimeStatistics and supply the length of the pcWriteBuffer
2379 * accumulated execution time being stored for each task. The resolution
2380 * of the accumulated time value depends on the frequency of the timer
2381 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
2382 * Calling vTaskGetRunTimeStats() writes the total execution time of each
2384 * of the total system execution time.
2388 * This function is provided for convenience only, and is used by many of the
2389 * demo applications. Do not consider it to be part of the scheduler.
2391 * vTaskGetRunTimeStats() calls uxTaskGetSystemState(), then formats part of the
2392 * uxTaskGetSystemState() output into a human readable table that displays the
2393 * amount of time each task has spent in the Running state in both absolute and
2396 * vTaskGetRunTimeStats() has a dependency on the snprintf() C library function
2397 * that might bloat the code size, use a lot of stack, and provide different
2399 * limited functionality implementation of snprintf() is provided in many of the
2407 * @param pcWriteBuffer A buffer into which the execution times will be
2409 * contain the generated report. Approximately 40 bytes per task should
2425 * available. The application must also then provide definitions for
2428 * return the timers current count value respectively. The counter should be
2429 * at least 10 times the frequency of the tick count.
2432 * accumulated execution time being stored for each task. The resolution
2433 * of the accumulated time value depends on the frequency of the timer
2434 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
2435 * While uxTaskGetSystemState() and vTaskGetRunTimeStats() writes the total
2437 * returns the total execution time of just one task and
2438 * ulTaskGetRunTimePercent() returns the percentage of the CPU time used by
2441 * @return The total run time of the given task or the percentage of the total
2442 * run time consumed by the given task. This is the amount of time the task
2443 * has actually been executing. The unit of time is dependent on the frequency
2444 * configured using the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
2463 * available. The application must also then provide definitions for
2466 * return the timers current count value respectively. The counter should be
2467 * at least 10 times the frequency of the tick count.
2470 * accumulated execution time being stored for each task. The resolution
2471 * of the accumulated time value depends on the frequency of the timer
2472 * configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro.
2473 * While uxTaskGetSystemState() and vTaskGetRunTimeStats() writes the total
2475 * returns the total execution time of just the idle task and
2476 * ulTaskGetIdleRunTimePercent() returns the percentage of the CPU time used by
2477 * just the idle task.
2479 * Note the amount of idle time is only a good measure of the slack time in a
2480 * system if there are no other tasks executing at the idle priority, tickless
2483 * @return The total run time of the idle task or the percentage of the total
2484 * run time consumed by the idle task. This is the amount of time the
2485 * idle task has actually been executing. The unit of time is dependent on the
2486 * frequency configured using the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and
2513 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2514 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2520 * are a method of sending an event directly to a task without the need for such
2524 * update, overwrite or increment one of the task's notification values. In
2529 * [optionally] block to wait for a notification to be pending. The task does
2530 * not consume any CPU time while it is in the Blocked state.
2532 * A notification sent to a task will remain pending until it is cleared by the
2534 * un-indexed equivalents). If the task was already in the Blocked state to
2535 * wait for a notification when the notification arrives then the task will
2536 * automatically be removed from the Blocked state (unblocked) and the
2539 * **NOTE** Each notification within the array operates independently - a task
2540 * can only block on one notification within the array at a time and will not be
2545 * all task notification API functions operated on that value. Replacing the
2547 * new set of API functions that could address specific notifications within the
2548 * array. xTaskNotify() is the original API function, and remains backward
2549 * compatible by always operating on the notification value at index 0 in the
2551 * with the uxIndexToNotify parameter set to 0.
2553 * @param xTaskToNotify The handle of the task being notified. The handle to a
2554 * task can be returned from the xTaskCreate() API function used to create the
2555 * task, and the handle of the currently running task can be obtained by calling
2558 * @param uxIndexToNotify The index within the target task's array of
2559 * notification values to which the notification is to be sent. uxIndexToNotify
2563 * @param ulValue Data that can be sent with the notification. How the data is
2564 * used depends on the value of the eAction parameter.
2566 * @param eAction Specifies how the notification updates the task's notification
2570 * The target notification value is bitwise ORed with ulValue.
2574 * The target notification value is incremented. ulValue is not used and
2578 * The target notification value is set to the value of ulValue, even if the
2579 * task being notified had not yet processed the previous notification at the
2580 * same array index (the task already had a notification pending at that index).
2584 * If the task being notified did not already have a notification pending at the
2585 * same array index then the target notification value is set to ulValue and
2586 * xTaskNotifyIndexed() will return pdPASS. If the task being notified already
2587 * had a notification pending at the same array index then no action is
2591 * The task receives a notification at the specified array index without the
2596 * Can be used to pass out the subject task's notification value before any
2597 * bits are modified by the notify function.
2599 * @return Dependent on the value of eAction. See the description of the
2624 * xTaskNotifyAndQueryIndexed() performs the same operation as
2625 * xTaskNotifyIndexed() with the addition that it also returns the subject
2626 * task's prior notification value (the notification value at the time the
2627 * function is called rather than when the function returns) in the additional
2630 * xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the
2631 * addition that it also returns the subject task's prior notification value
2632 * (the notification value as it was at the time the function is called, rather
2633 * than when the function returns) in the additional pulPreviousNotifyValue
2660 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2661 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2667 * are a method of sending an event directly to a task without the need for such
2671 * update, overwrite or increment one of the task's notification values. In
2677 * to wait for a notification value to have a non-zero value. The task does
2678 * not consume any CPU time while it is in the Blocked state.
2680 * A notification sent to a task will remain pending until it is cleared by the
2682 * un-indexed equivalents). If the task was already in the Blocked state to
2683 * wait for a notification when the notification arrives then the task will
2684 * automatically be removed from the Blocked state (unblocked) and the
2687 * **NOTE** Each notification within the array operates independently - a task
2688 * can only block on one notification within the array at a time and will not be
2693 * all task notification API functions operated on that value. Replacing the
2695 * new set of API functions that could address specific notifications within the
2696 * array. xTaskNotifyFromISR() is the original API function, and remains
2697 * backward compatible by always operating on the notification value at index 0
2698 * within the array. Calling xTaskNotifyFromISR() is equivalent to calling
2699 * xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0.
2701 * @param uxIndexToNotify The index within the target task's array of
2702 * notification values to which the notification is to be sent. uxIndexToNotify
2706 * @param xTaskToNotify The handle of the task being notified. The handle to a
2707 * task can be returned from the xTaskCreate() API function used to create the
2708 * task, and the handle of the currently running task can be obtained by calling
2711 * @param ulValue Data that can be sent with the notification. How the data is
2712 * used depends on the value of the eAction parameter.
2714 * @param eAction Specifies how the notification updates the task's notification
2718 * The task's notification value is bitwise ORed with ulValue. xTaskNotify()
2722 * The task's notification value is incremented. ulValue is not used and
2726 * The task's notification value is set to the value of ulValue, even if the
2727 * task being notified had not yet processed the previous notification (the
2732 * If the task being notified did not already have a notification pending then
2733 * the task's notification value is set to ulValue and xTaskNotify() will
2734 * return pdPASS. If the task being notified already had a notification
2738 * The task receives a notification without its notification value being
2743 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
2744 * task to which the notification was sent to leave the Blocked state, and the
2745 * unblocked task has a priority higher than the currently running task. If
2747 * be requested before the interrupt is exited. How a context switch is
2748 * requested from an ISR is dependent on the port - see the documentation page
2749 * for the port in use.
2751 * @return Dependent on the value of eAction. See the description of the
2777 * xTaskNotifyAndQueryIndexedFromISR() performs the same operation as
2778 * xTaskNotifyIndexedFromISR() with the addition that it also returns the
2779 * subject task's prior notification value (the notification value at the time
2780 * the function is called rather than at the time the function returns) in the
2783 * xTaskNotifyAndQueryFromISR() performs the same operation as
2784 * xTaskNotifyFromISR() with the addition that it also returns the subject
2785 * task's prior notification value (the notification value at the time the
2786 * function is called rather than at the time the function returns) in the
2814 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2815 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2821 * are a method of sending an event directly to a task without the need for such
2825 * update, overwrite or increment one of the task's notification values. In
2829 * A notification sent to a task will remain pending until it is cleared by the
2831 * un-indexed equivalents). If the task was already in the Blocked state to
2832 * wait for a notification when the notification arrives then the task will
2833 * automatically be removed from the Blocked state (unblocked) and the
2838 * to wait for a notification value to have a non-zero value. The task does
2839 * not consume any CPU time while it is in the Blocked state.
2841 * **NOTE** Each notification within the array operates independently - a task
2842 * can only block on one notification within the array at a time and will not be
2847 * all task notification API functions operated on that value. Replacing the
2849 * new set of API functions that could address specific notifications within the
2850 * array. xTaskNotifyWait() is the original API function, and remains backward
2851 * compatible by always operating on the notification value at index 0 in the
2853 * xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0.
2855 * @param uxIndexToWaitOn The index within the calling task's array of
2856 * notification values on which the calling task will wait for a notification to
2862 * will be cleared in the calling task's notification value before the task
2866 * the effect of resetting the task's notification value to 0. Setting
2867 * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged.
2870 * the calling task exits the xTaskNotifyWait() function then the task's
2871 * notification value (see the xTaskNotify() API function) is passed out using
2872 * the pulNotificationValue parameter. Then any bits that are set in
2873 * ulBitsToClearOnExit will be cleared in the task's notification value (note
2876 * (if limits.h is not included) will have the effect of resetting the task's
2877 * notification value to 0 before the function exits. Setting
2878 * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged
2879 * when the function exits (in which case the value passed out in
2880 * pulNotificationValue will match the task's notification value).
2882 * @param pulNotificationValue Used to pass the task's notification value out
2883 * of the function. Note the value passed out will not be effected by the
2886 * @param xTicksToWait The maximum amount of time that the task should wait in
2887 * the Blocked state for a notification to be received, should a notification
2888 * not already be pending when xTaskNotifyWait() was called. The task
2889 * will not consume any processing time while it is in the Blocked state. This
2890 * is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be
2918 * Sends a direct to task notification to a particular index in the target
2927 * each of which is a 32-bit unsigned integer (uint32_t). The constant
2928 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
2934 * are a method of sending an event directly to a task without the need for such
2938 * update, overwrite or increment one of the task's notification values. In
2944 * semaphore equivalents. Actual FreeRTOS semaphores are given using the
2945 * xSemaphoreGive() API function, the equivalent action that instead uses a task
2949 * equivalent then the task being notified should wait for the notification
2950 * using the ulTaskNotifyTakeIndexed() API function rather than the
2953 * **NOTE** Each notification within the array operates independently - a task
2954 * can only block on one notification within the array at a time and will not be
2959 * all task notification API functions operated on that value. Replacing the
2961 * new set of API functions that could address specific notifications within the
2962 * array. xTaskNotifyGive() is the original API function, and remains backward
2963 * compatible by always operating on the notification value at index 0 in the
2965 * xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0.
2967 * @param xTaskToNotify The handle of the task being notified. The handle to a
2968 * task can be returned from the xTaskCreate() API function used to create the
2969 * task, and the handle of the currently running task can be obtained by calling
2972 * @param uxIndexToNotify The index within the target task's array of
2973 * notification values to which the notification is to be sent. uxIndexToNotify
2977 * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the
3004 * each of which is a 32-bit unsigned integer (uint32_t). The constant
3005 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
3011 * are a method of sending an event directly to a task without the need for such
3015 * update, overwrite or increment one of the task's notification values. In
3021 * Actual FreeRTOS semaphores are given from an ISR using the
3022 * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses
3026 * equivalent then the task being notified should wait for the notification
3027 * using the ulTaskNotifyTakeIndexed() API function rather than the
3030 * **NOTE** Each notification within the array operates independently - a task
3031 * can only block on one notification within the array at a time and will not be
3036 * all task notification API functions operated on that value. Replacing the
3038 * new set of API functions that could address specific notifications within the
3039 * array. xTaskNotifyFromISR() is the original API function, and remains
3040 * backward compatible by always operating on the notification value at index 0
3041 * within the array. Calling xTaskNotifyGiveFromISR() is equivalent to calling
3042 * xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0.
3044 * @param xTaskToNotify The handle of the task being notified. The handle to a
3045 * task can be returned from the xTaskCreate() API function used to create the
3046 * task, and the handle of the currently running task can be obtained by calling
3049 * @param uxIndexToNotify The index within the target task's array of
3050 * notification values to which the notification is to be sent. uxIndexToNotify
3056 * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
3057 * task to which the notification was sent to leave the Blocked state, and the
3058 * unblocked task has a priority higher than the currently running task. If
3060 * should be requested before the interrupt is exited. How a context switch is
3061 * requested from an ISR is dependent on the port - see the documentation page
3062 * for the port in use.
3083 * Waits for a direct to task notification on a particular index in the calling
3092 * each of which is a 32-bit unsigned integer (uint32_t). The constant
3093 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
3099 * are a method of sending an event directly to a task without the need for such
3103 * update, overwrite or increment one of the task's notification values. In
3109 * Actual FreeRTOS semaphores are taken using the xSemaphoreTake() API function,
3110 * the equivalent action that instead uses a task notification is
3114 * other tasks should send notifications to it using the xTaskNotifyGiveIndexed()
3115 * macro, or xTaskNotifyIndex() function with the eAction parameter set to
3118 * ulTaskNotifyTakeIndexed() can either clear the task's notification value at
3119 * the array index specified by the uxIndexToWaitOn parameter to zero on exit,
3120 * in which case the notification value acts like a binary semaphore, or
3121 * decrement the notification value on exit, in which case the notification
3125 * a notification. The task does not consume any CPU time while it is in the
3129 * ulTaskNotifyTakeIndexed() will return when the task's notification value is
3132 * **NOTE** Each notification within the array operates independently - a task
3133 * can only block on one notification within the array at a time and will not be
3138 * all task notification API functions operated on that value. Replacing the
3140 * new set of API functions that could address specific notifications within the
3141 * array. ulTaskNotifyTake() is the original API function, and remains backward
3142 * compatible by always operating on the notification value at index 0 in the
3144 * ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0.
3146 * @param uxIndexToWaitOn The index within the calling task's array of
3147 * notification values on which the calling task will wait for a notification to
3152 * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's
3153 * notification value is decremented when the function exits. In this way the
3155 * not pdFALSE then the task's notification value is cleared to zero when the
3156 * function exits. In this way the notification value acts like a binary
3159 * @param xTicksToWait The maximum amount of time that the task should wait in
3160 * the Blocked state for the task's notification value to be greater than zero,
3161 * should the count not already be greater than zero when
3162 * ulTaskNotifyTake() was called. The task will not consume any processing
3163 * time while it is in the Blocked state. This is specified in kernel ticks,
3164 * the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time
3167 * @return The task's notification count before it is either cleared to zero or
3168 * decremented (see the xClearCountOnExit parameter).
3195 * each of which is a 32-bit unsigned integer (uint32_t). The constant
3196 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
3200 * If a notification is sent to an index within the array of notifications then
3201 * the notification at that index is said to be 'pending' until it is read or
3202 * explicitly cleared by the receiving task. xTaskNotifyStateClearIndexed()
3203 * is the function that clears a pending notification without reading the
3204 * notification value. The notification value at the same array index is not
3205 * altered. Set xTask to NULL to clear the notification state of the calling
3210 * all task notification API functions operated on that value. Replacing the
3212 * new set of API functions that could address specific notifications within the
3213 * array. xTaskNotifyStateClear() is the original API function, and remains
3214 * backward compatible by always operating on the notification value at index 0
3215 * within the array. Calling xTaskNotifyStateClear() is equivalent to calling
3216 * xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0.
3218 * @param xTask The handle of the RTOS task that will have a notification state
3219 * cleared. Set xTask to NULL to clear a notification state in the calling
3220 * task. To obtain a task's handle create the task using xTaskCreate() and
3221 * make use of the pxCreatedTask parameter, or create the task using
3222 * xTaskCreateStatic() and store the returned value, or use the task's name in
3225 * @param uxIndexToClear The index within the target task's array of
3227 * will clear the state of the notification at index 1 within the array.
3229 * ulTaskNotifyStateClear() does not have this parameter and always acts on the
3232 * @return pdTRUE if the task's notification state was set to
3259 * each of which is a 32-bit unsigned integer (uint32_t). The constant
3260 * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the
3264 * ulTaskNotifyValueClearIndexed() clears the bits specified by the
3265 * ulBitsToClear bit mask in the notification value at array index uxIndexToClear
3266 * of the task referenced by xTask.
3270 * all task notification API functions operated on that value. Replacing the
3272 * new set of API functions that could address specific notifications within the
3273 * array. ulTaskNotifyValueClear() is the original API function, and remains
3274 * backward compatible by always operating on the notification value at index 0
3275 * within the array. Calling ulTaskNotifyValueClear() is equivalent to calling
3276 * ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0.
3278 * @param xTask The handle of the RTOS task that will have bits in one of its
3280 * notification value of the calling task. To obtain a task's handle create the
3281 * task using xTaskCreate() and make use of the pxCreatedTask parameter, or
3282 * create the task using xTaskCreateStatic() and store the returned value, or
3283 * use the task's name in a call to xTaskGetHandle().
3285 * @param uxIndexToClear The index within the target task's array of
3286 * notification values in which to clear the bits. uxIndexToClear
3289 * in the notification value at index 0.
3291 * @param ulBitsToClear Bit mask of the bits to clear in the notification value of
3292 * xTask. Set a bit to 1 to clear the corresponding bits in the task's notification
3294 * the notification value to 0. Set ulBitsToClear to 0 to query the task's
3298 * @return The value of the target task's notification value before the bits
3317 * Capture the current time for future use with xTaskCheckForTimeOut().
3319 * @param pxTimeOut Pointer to a timeout object into which the current time
3320 * is to be captured. The captured time includes the tick count and the number
3321 * of times the tick count has overflowed since the system first booted.
3334 * using a call to vTaskSetTimeOutState(). The captured time includes the tick
3335 * count and the number of times the tick count has overflowed.
3337 * @param pxTimeOut The time status as captured previously using
3338 * vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated
3339 * to reflect the current time status.
3340 * @param pxTicksToWait The number of ticks to check for timeout i.e. if
3342 * vTaskSetTimeOutState() or xTaskCheckForTimeOut()), the timeout has occurred.
3343 * If the timeout has not occurred, pxTicksToWait is updated to reflect the
3347 * returned and pxTicksToWait is updated to reflect the number of remaining
3355 * // that is filled by a UART interrupt. If there are not enough bytes in the
3356 * // Rx buffer then the task enters the Blocked state until it is notified that
3357 * // more data has been placed into the buffer. If there is still not enough
3358 * // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut()
3359 * // is used to re-calculate the Block time to ensure the total amount of time
3360 * // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This
3361 * // continues until either the buffer contains at least uxWantedBytes bytes,
3362 * // or the total amount of time spent in the Blocked state reaches
3363 * // MAX_TIME_TO_WAIT - at which point the task reads however many bytes are
3372 * // Initialize xTimeOut. This records the time at which this function
3376 * // Loop until the buffer contains the wanted number of bytes, or a
3380 * // The buffer didn't contain enough data so this task is going to
3381 * // enter the Blocked state. Adjusting xTicksToWait to account for
3382 * // any time that has been spent in the Blocked state within this
3383 * // function so far to ensure the total amount of time spent in the
3387 * //Timed out before the wanted number of bytes were available,
3388 * // exit the loop.
3392 * // Wait for a maximum of xTicksToWait ticks to be notified that the
3393 * // receive interrupt has placed more data into the buffer.
3397 * // Attempt to read uxWantedBytes from the receive buffer into pucBuffer.
3398 * // The actual number of bytes read (which might be less than
3419 * This function corrects the tick count value after the application code has held
3424 * vTaskStepTick(), xTaskCatchUpTicks() may move the tick count forward past a
3425 * time at which a task should be removed from the blocked state. That means
3426 * tasks may have to be removed from the blocked state as the tick count is
3429 * @param xTicksToCatchUp The number of tick interrupts that have been missed due to
3431 * computed by the application writer.
3433 * @return pdTRUE if moving the tick count forward resulted in a task leaving the
3454 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
3455 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3457 * Called from the real time kernel tick (either preemptive or cooperative),
3458 * this increments the tick count and checks if any tasks that are blocked
3464 * + Time slicing is in use and there is a task of equal priority to the
3471 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3475 * Removes the calling task from the ready list and places it both
3476 * on the list of tasks waiting for a particular event, and the
3477 * list of delayed tasks. The task will be removed from both lists
3478 * and replaced on the ready list should either the event occur (and
3479 * there be no higher priority tasks waiting on the same event) or
3480 * the delay period expires.
3482 * The 'unordered' version replaces the event list item value with the
3483 * xItemValue value, and inserts the list item at the end of the list.
3485 * The 'ordered' version uses the existing event list item value (which is the
3486 * owning task's priority) to insert the list item into the event list in task
3489 * @param pxEventList The list containing tasks that are blocked waiting
3490 * for the event to occur.
3492 * @param xItemValue The item value to use for the event list item when the
3495 * @param xTicksToWait The maximum amount of time that the task should wait
3496 * for the event to occur. This is specified in kernel ticks, the constant
3508 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3512 * This function performs nearly the same function as vTaskPlaceOnEventList().
3513 * The difference being that this function does not permit tasks to block
3523 * INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3527 * Removes a task from both the specified event list and the list of blocked
3531 * if either an event occurs to unblock a task, or the block timeout period
3534 * xTaskRemoveFromEventList() is used when the event list is in task priority
3535 * order. It removes the list item from the head of the event list as that will
3536 * have the highest priority owning task of all the tasks on the event list.
3537 * vTaskRemoveFromUnorderedEventList() is used when the event list is not
3538 * ordered and the event list items hold something other than the owning tasks
3539 * priority. In this case the event list item value is updated to the value
3540 * passed in the xItemValue parameter.
3542 * @return pdTRUE if the task being removed has a higher priority than the task
3543 * making the call, otherwise pdFALSE.
3551 * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS
3552 * AN INTERFACE WHICH IS FOR THE EXCLUSIVE USE OF THE SCHEDULER.
3554 * Sets the pointer to the current TCB to the TCB of the highest priority task
3565 * THE EVENT BITS MODULE.
3570 * Return the handle of the calling task.
3575 * Return the handle of the task running on specified core.
3582 * Shortcut used by the queue implementation to prevent unnecessary call to
3588 * Returns the scheduler state as taskSCHEDULER_RUNNING,
3594 * Raises the priority of the mutex holder to that of the calling task should
3595 * the mutex holder have a priority less than the calling task.
3600 * Set the priority of a task back to its proper priority in the case that it
3607 * priority task to inherit the higher priority task's priority - but the higher
3608 * priority task then timed out without obtaining the mutex, then the lower
3609 * priority task will disinherit the priority again - but only down as far as
3610 * the highest priority task that is still waiting for the mutex (if there were
3611 * more than one task waiting for the mutex).
3617 * Get the uxTaskNumber assigned to the task referenced by the xTask parameter.
3624 * Set the uxTaskNumber of the task referenced by the xTask parameter to
3635 * the tick interrupt will not execute during idle periods. When this is the
3636 * case, the tick count value maintained by the scheduler needs to be kept up
3637 * to date with the actual execution time by being skipped forward by a time
3638 * equal to the idle period.
3646 * Provided for use within portSUPPRESS_TICKS_AND_SLEEP() to allow the port
3647 * specific sleep function to determine if it is ok to proceed with the sleep,
3651 * called with the scheduler suspended, not from within a critical section. It
3653 * portSUPPRESS_TICKS_AND_SLEEP() and the low power mode actually being
3655 * critical section between the timer being stopped and the sleep mode being
3656 * entered to ensure it is ok to proceed into the sleep mode.
3663 * For internal use only. Increment the mutex held count when a mutex is
3664 * taken and return the handle of the task that has taken the mutex.
3676 * For SMP this is not defined by the port.
3683 * This function is only intended for use when implementing a port of the scheduler
3685 * is greater than 1. This function can be used in the implementation of portENTER_CRITICAL
3687 * It should be used in the implementation of portENTER_CRITICAL if port is running a
3695 * This function is only intended for use when implementing a port of the scheduler
3697 * is greater than 1. This function can be used in the implementation of portEXIT_CRITICAL
3699 * It should be used in the implementation of portEXIT_CRITICAL if port is running a
3707 * This function is only intended for use when implementing a port of the scheduler
3709 * should be used in the implementation of portENTER_CRITICAL_FROM_ISR if port is
3717 * This function is only intended for use when implementing a port of the scheduler
3719 * should be used in the implementation of portEXIT_CRITICAL_FROM_ISR if port is