/* * FreeRTOS Kernel V10.4.6 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * SPDX-License-Identifier: MIT * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of * the Software, and to permit persons to whom the Software is furnished to do so, * subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all * copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * * https://www.FreeRTOS.org * https://github.com/FreeRTOS * */ #ifndef INC_TASK_H #define INC_TASK_H #ifndef INC_FREERTOS_H #error "include FreeRTOS.h must appear in source files before include task.h" #endif /* *INDENT-OFF* */ #ifdef __cplusplus extern "C" { #endif /* *INDENT-ON* */ /*----------------------------------------------------------- * MACROS AND DEFINITIONS *----------------------------------------------------------*/ /* * If tskKERNEL_VERSION_NUMBER ends with + it represents the version in development * after the numbered release. * * The tskKERNEL_VERSION_MAJOR, tskKERNEL_VERSION_MINOR, tskKERNEL_VERSION_BUILD * values will reflect the last released version number. */ #define tskKERNEL_VERSION_NUMBER "V10.4.6" #define tskKERNEL_VERSION_MAJOR 10 #define tskKERNEL_VERSION_MINOR 4 #define tskKERNEL_VERSION_BUILD 6 /* The direct to task notification feature used to have only a single notification * per task. Now there is an array of notifications per task that is dimensioned by * configTASK_NOTIFICATION_ARRAY_ENTRIES. For backward compatibility, any use of the * original direct to task notification defaults to using the first index in the * array. */ #define tskDEFAULT_INDEX_TO_NOTIFY ( 0 ) #ifdef ESP_PLATFORM #define tskNO_AFFINITY ( 0x7FFFFFFF ) #endif /** * task. h * * Type by which tasks are referenced. For example, a call to xTaskCreate * returns (via a pointer parameter) an TaskHandle_t variable that can then * be used as a parameter to vTaskDelete to delete the task. * * \defgroup TaskHandle_t TaskHandle_t * \ingroup Tasks */ struct tskTaskControlBlock; /* The old naming convention is used to prevent breaking kernel aware debuggers. */ typedef struct tskTaskControlBlock * TaskHandle_t; /* * Defines the prototype to which the application task hook function must * conform. */ typedef BaseType_t (* TaskHookFunction_t)( void * ); /* Task states returned by eTaskGetState. */ typedef enum { eRunning = 0, /* A task is querying the state of itself, so must be running. */ eReady, /* The task being queried is in a ready or pending ready list. */ eBlocked, /* The task being queried is in the Blocked state. */ eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */ eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */ eInvalid /* Used as an 'invalid state' value. */ } eTaskState; /* Actions that can be performed when vTaskNotify() is called. */ typedef enum { eNoAction = 0, /* Notify the task without updating its notify value. */ eSetBits, /* Set bits in the task's notification value. */ eIncrement, /* Increment the task's notification value. */ eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */ eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */ } eNotifyAction; /* * Used internally only. */ typedef struct xTIME_OUT { BaseType_t xOverflowCount; TickType_t xTimeOnEntering; } TimeOut_t; /** * Defines the priority used by the idle task. This must not be modified. * * \ingroup TaskUtils */ #define tskIDLE_PRIORITY ( ( UBaseType_t ) 0U ) /** * task. h * * Macro for forcing a context switch. * * \defgroup taskYIELD taskYIELD * \ingroup SchedulerControl */ #define taskYIELD() portYIELD() /** * task. h * * Macro to mark the start of a critical code region. Preemptive context * switches cannot occur when in a critical region. * * NOTE: This may alter the stack (depending on the portable implementation) * so must be used with care! * * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL * \ingroup SchedulerControl */ #define taskENTER_CRITICAL() portENTER_CRITICAL() #define taskENTER_CRITICAL_FROM_ISR() portSET_INTERRUPT_MASK_FROM_ISR() /** * task. h * * Macro to mark the end of a critical code region. Preemptive context * switches cannot occur when in a critical region. * * NOTE: This may alter the stack (depending on the portable implementation) * so must be used with care! * * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL * \ingroup SchedulerControl */ #define taskEXIT_CRITICAL() portEXIT_CRITICAL() #define taskEXIT_CRITICAL_FROM_ISR( x ) portCLEAR_INTERRUPT_MASK_FROM_ISR( x ) /** * task. h * * Macro to disable all maskable interrupts. * * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS * \ingroup SchedulerControl */ #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS() /** * task. h * * Macro to enable microcontroller interrupts. * * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS * \ingroup SchedulerControl */ #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS() /* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is * 0 to generate more optimal code when configASSERT() is defined as the constant * is used in assert() statements. */ #define taskSCHEDULER_SUSPENDED ( ( BaseType_t ) 0 ) #define taskSCHEDULER_NOT_STARTED ( ( BaseType_t ) 1 ) #define taskSCHEDULER_RUNNING ( ( BaseType_t ) 2 ) /*----------------------------------------------------------- * TASK CREATION API *----------------------------------------------------------*/ /** * task. h * @code{c} * BaseType_t xTaskCreate( * TaskFunction_t pxTaskCode, * const char *pcName, * configSTACK_DEPTH_TYPE usStackDepth, * void *pvParameters, * UBaseType_t uxPriority, * TaskHandle_t *pxCreatedTask * ); * @endcode * * Create a new task and add it to the list of tasks that are ready to run. * * Internally, within the FreeRTOS implementation, tasks use two blocks of * memory. The first block is used to hold the task's data structures. The * second block is used by the task as its stack. If a task is created using * xTaskCreate() then both blocks of memory are automatically dynamically * allocated inside the xTaskCreate() function. (see * https://www.FreeRTOS.org/a00111.html). If a task is created using * xTaskCreateStatic() then the application writer must provide the required * memory. xTaskCreateStatic() therefore allows a task to be created without * using any dynamic memory allocation. * * See xTaskCreateStatic() for a version that does not use any dynamic memory * allocation. * * xTaskCreate() can only be used to create a task that has unrestricted * access to the entire microcontroller memory map. Systems that include MPU * support can alternatively create an MPU constrained task using * xTaskCreateRestricted(). * * @param pxTaskCode Pointer to the task entry function. Tasks * must be implemented to never return (i.e. continuous loop). * * @param pcName A descriptive name for the task. This is mainly used to * facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default * is 16. * * @param usStackDepth The size of the task stack specified as the number of * variables the stack can hold - not the number of bytes. For example, if * the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes * will be allocated for stack storage. * * @param pvParameters Pointer that will be used as the parameter for the task * being created. * * @param uxPriority The priority at which the task should run. Systems that * include MPU support can optionally create tasks in a privileged (system) * mode by setting bit portPRIVILEGE_BIT of the priority parameter. For * example, to create a privileged task at priority 2 the uxPriority parameter * should be set to ( 2 | portPRIVILEGE_BIT ). * * @param pxCreatedTask Used to pass back a handle by which the created task * can be referenced. * * @return pdPASS if the task was successfully created and added to a ready * list, otherwise an error code defined in the file projdefs.h * * Example usage: * @code{c} * // Task to be created. * void vTaskCode( void * pvParameters ) * { * for( ;; ) * { * // Task code goes here. * } * } * * // Function that creates a task. * void vOtherFunction( void ) * { * static uint8_t ucParameterToPass; * TaskHandle_t xHandle = NULL; * * // Create the task, storing the handle. Note that the passed parameter ucParameterToPass * // must exist for the lifetime of the task, so in this case is declared static. If it was just an * // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time * // the new task attempts to access it. * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle ); * configASSERT( xHandle ); * * // Use the handle to delete the task. * if( xHandle != NULL ) * { * vTaskDelete( xHandle ); * } * } * @endcode * \defgroup xTaskCreate xTaskCreate * \ingroup Tasks */ #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) BaseType_t xTaskCreate( TaskFunction_t pxTaskCode, const char * const pcName, /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ const configSTACK_DEPTH_TYPE usStackDepth, void * const pvParameters, UBaseType_t uxPriority, TaskHandle_t * const pxCreatedTask ); #endif #ifdef ESP_PLATFORM #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) BaseType_t xTaskCreatePinnedToCore( TaskFunction_t pvTaskCode, const char * const pcName, const uint32_t usStackDepth, void * const pvParameters, UBaseType_t uxPriority, TaskHandle_t * const pvCreatedTask, const BaseType_t xCoreID); #endif #endif /** * task. h * @code{c} * TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode, * const char *pcName, * uint32_t ulStackDepth, * void *pvParameters, * UBaseType_t uxPriority, * StackType_t *puxStackBuffer, * StaticTask_t *pxTaskBuffer ); * @endcode * * Create a new task and add it to the list of tasks that are ready to run. * * Internally, within the FreeRTOS implementation, tasks use two blocks of * memory. The first block is used to hold the task's data structures. The * second block is used by the task as its stack. If a task is created using * xTaskCreate() then both blocks of memory are automatically dynamically * allocated inside the xTaskCreate() function. (see * https://www.FreeRTOS.org/a00111.html). If a task is created using * xTaskCreateStatic() then the application writer must provide the required * memory. xTaskCreateStatic() therefore allows a task to be created without * using any dynamic memory allocation. * * @param pxTaskCode Pointer to the task entry function. Tasks * must be implemented to never return (i.e. continuous loop). * * @param pcName A descriptive name for the task. This is mainly used to * facilitate debugging. The maximum length of the string is defined by * configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. * * @param ulStackDepth The size of the task stack specified as the number of * variables the stack can hold - not the number of bytes. For example, if * the stack is 32-bits wide and ulStackDepth is defined as 100 then 400 bytes * will be allocated for stack storage. * * @param pvParameters Pointer that will be used as the parameter for the task * being created. * * @param uxPriority The priority at which the task will run. * * @param puxStackBuffer Must point to a StackType_t array that has at least * ulStackDepth indexes - the array will then be used as the task's stack, * removing the need for the stack to be allocated dynamically. * * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will * then be used to hold the task's data structures, removing the need for the * memory to be allocated dynamically. * * @return If neither puxStackBuffer nor pxTaskBuffer are NULL, then the task * will be created and a handle to the created task is returned. If either * puxStackBuffer or pxTaskBuffer are NULL then the task will not be created and * NULL is returned. * * Example usage: * @code{c} * * // Dimensions of the buffer that the task being created will use as its stack. * // NOTE: This is the number of words the stack will hold, not the number of * // bytes. For example, if each stack item is 32-bits, and this is set to 100, * // then 400 bytes (100 * 32-bits) will be allocated. #define STACK_SIZE 200 * * // Structure that will hold the TCB of the task being created. * StaticTask_t xTaskBuffer; * * // Buffer that the task being created will use as its stack. Note this is * // an array of StackType_t variables. The size of StackType_t is dependent on * // the RTOS port. * StackType_t xStack[ STACK_SIZE ]; * * // Function that implements the task being created. * void vTaskCode( void * pvParameters ) * { * // The parameter value is expected to be 1 as 1 is passed in the * // pvParameters value in the call to xTaskCreateStatic(). * configASSERT( ( uint32_t ) pvParameters == 1UL ); * * for( ;; ) * { * // Task code goes here. * } * } * * // Function that creates a task. * void vOtherFunction( void ) * { * TaskHandle_t xHandle = NULL; * * // Create the task without using any dynamic memory allocation. * xHandle = xTaskCreateStatic( * vTaskCode, // Function that implements the task. * "NAME", // Text name for the task. * STACK_SIZE, // Stack size in words, not bytes. * ( void * ) 1, // Parameter passed into the task. * tskIDLE_PRIORITY,// Priority at which the task is created. * xStack, // Array to use as the task's stack. * &xTaskBuffer ); // Variable to hold the task's data structure. * * // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have * // been created, and xHandle will be the task's handle. Use the handle * // to suspend the task. * vTaskSuspend( xHandle ); * } * @endcode * \defgroup xTaskCreateStatic xTaskCreateStatic * \ingroup Tasks */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode, const char * const pcName, /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ const uint32_t ulStackDepth, void * const pvParameters, UBaseType_t uxPriority, StackType_t * const puxStackBuffer, StaticTask_t * const pxTaskBuffer ); #endif /* configSUPPORT_STATIC_ALLOCATION */ /** * task. h * @code{c} * void vTaskDelete( TaskHandle_t xTaskToDelete ); * @endcode * * INCLUDE_vTaskDelete must be defined as 1 for this function to be available. * See the configuration section for more information. * * Remove a task from the RTOS real time kernel's management. The task being * deleted will be removed from all ready, blocked, suspended and event lists. * * NOTE: The idle task is responsible for freeing the kernel allocated * memory from tasks that have been deleted. It is therefore important that * the idle task is not starved of microcontroller processing time if your * application makes any calls to vTaskDelete (). Memory allocated by the * task code is not automatically freed, and should be freed before the task * is deleted. * * See the demo application file death.c for sample code that utilises * vTaskDelete (). * * @param xTaskToDelete The handle of the task to be deleted. Passing NULL will * cause the calling task to be deleted. * * Example usage: * @code{c} * void vOtherFunction( void ) * { * TaskHandle_t xHandle; * * // Create the task, storing the handle. * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); * * // Use the handle to delete the task. * vTaskDelete( xHandle ); * } * @endcode * \defgroup vTaskDelete vTaskDelete * \ingroup Tasks */ void vTaskDelete( TaskHandle_t xTaskToDelete ); /*----------------------------------------------------------- * TASK CONTROL API *----------------------------------------------------------*/ /** * task. h * @code{c} * void vTaskDelay( const TickType_t xTicksToDelay ); * @endcode * * Delay a task for a given number of ticks. The actual time that the * task remains blocked depends on the tick rate. The constant * portTICK_PERIOD_MS can be used to calculate real time from the tick * rate - with the resolution of one tick period. * * INCLUDE_vTaskDelay must be defined as 1 for this function to be available. * See the configuration section for more information. * * * vTaskDelay() specifies a time at which the task wishes to unblock relative to * the time at which vTaskDelay() is called. For example, specifying a block * period of 100 ticks will cause the task to unblock 100 ticks after * vTaskDelay() is called. vTaskDelay() does not therefore provide a good method * of controlling the frequency of a periodic task as the path taken through the * code, as well as other task and interrupt activity, will affect the frequency * at which vTaskDelay() gets called and therefore the time at which the task * next executes. See xTaskDelayUntil() for an alternative API function designed * to facilitate fixed frequency execution. It does this by specifying an * absolute time (rather than a relative time) at which the calling task should * unblock. * * @param xTicksToDelay The amount of time, in tick periods, that * the calling task should block. * * Example usage: * * void vTaskFunction( void * pvParameters ) * { * // Block for 500ms. * const TickType_t xDelay = 500 / portTICK_PERIOD_MS; * * for( ;; ) * { * // Simply toggle the LED every 500ms, blocking between each toggle. * vToggleLED(); * vTaskDelay( xDelay ); * } * } * * \defgroup vTaskDelay vTaskDelay * \ingroup TaskCtrl */ void vTaskDelay( const TickType_t xTicksToDelay ); /** * task. h * @code{c} * BaseType_t xTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement ); * @endcode * * INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available. * See the configuration section for more information. * * Delay a task until a specified time. This function can be used by periodic * tasks to ensure a constant execution frequency. * * This function differs from vTaskDelay () in one important aspect: vTaskDelay () will * cause a task to block for the specified number of ticks from the time vTaskDelay () is * called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed * execution frequency as the time between a task starting to execute and that task * calling vTaskDelay () may not be fixed [the task may take a different path though the * code between calls, or may get interrupted or preempted a different number of times * each time it executes]. * * Whereas vTaskDelay () specifies a wake time relative to the time at which the function * is called, xTaskDelayUntil () specifies the absolute (exact) time at which it wishes to * unblock. * * The macro pdMS_TO_TICKS() can be used to calculate the number of ticks from a * time specified in milliseconds with a resolution of one tick period. * * @param pxPreviousWakeTime Pointer to a variable that holds the time at which the * task was last unblocked. The variable must be initialised with the current time * prior to its first use (see the example below). Following this the variable is * automatically updated within xTaskDelayUntil (). * * @param xTimeIncrement The cycle time period. The task will be unblocked at * time *pxPreviousWakeTime + xTimeIncrement. Calling xTaskDelayUntil with the * same xTimeIncrement parameter value will cause the task to execute with * a fixed interface period. * * @return Value which can be used to check whether the task was actually delayed. * Will be pdTRUE if the task way delayed and pdFALSE otherwise. A task will not * be delayed if the next expected wake time is in the past. * * Example usage: * @code{c} * // Perform an action every 10 ticks. * void vTaskFunction( void * pvParameters ) * { * TickType_t xLastWakeTime; * const TickType_t xFrequency = 10; * BaseType_t xWasDelayed; * * // Initialise the xLastWakeTime variable with the current time. * xLastWakeTime = xTaskGetTickCount (); * for( ;; ) * { * // Wait for the next cycle. * xWasDelayed = xTaskDelayUntil( &xLastWakeTime, xFrequency ); * * // Perform action here. xWasDelayed value can be used to determine * // whether a deadline was missed if the code here took too long. * } * } * @endcode * \defgroup xTaskDelayUntil xTaskDelayUntil * \ingroup TaskCtrl */ BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement ); /* * vTaskDelayUntil() is the older version of xTaskDelayUntil() and does not * return a value. */ #define vTaskDelayUntil( pxPreviousWakeTime, xTimeIncrement ) \ { \ ( void ) xTaskDelayUntil( pxPreviousWakeTime, xTimeIncrement ); \ } /** * task. h * @code{c} * BaseType_t xTaskAbortDelay( TaskHandle_t xTask ); * @endcode * * INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this * function to be available. * * A task will enter the Blocked state when it is waiting for an event. The * event it is waiting for can be a temporal event (waiting for a time), such * as when vTaskDelay() is called, or an event on an object, such as when * xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task * that is in the Blocked state is used in a call to xTaskAbortDelay() then the * task will leave the Blocked state, and return from whichever function call * placed the task into the Blocked state. * * There is no 'FromISR' version of this function as an interrupt would need to * know which object a task was blocked on in order to know which actions to * take. For example, if the task was blocked on a queue the interrupt handler * would then need to know if the queue was locked. * * @param xTask The handle of the task to remove from the Blocked state. * * @return If the task referenced by xTask was not in the Blocked state then * pdFAIL is returned. Otherwise pdPASS is returned. * * \defgroup xTaskAbortDelay xTaskAbortDelay * \ingroup TaskCtrl */ BaseType_t xTaskAbortDelay( TaskHandle_t xTask ); /** * task. h * @code{c} * UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask ); * @endcode * * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. * See the configuration section for more information. * * Obtain the priority of any task. * * @param xTask Handle of the task to be queried. Passing a NULL * handle results in the priority of the calling task being returned. * * @return The priority of xTask. * * Example usage: * @code{c} * void vAFunction( void ) * { * TaskHandle_t xHandle; * * // Create a task, storing the handle. * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); * * // ... * * // Use the handle to obtain the priority of the created task. * // It was created with tskIDLE_PRIORITY, but may have changed * // it itself. * if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY ) * { * // The task has changed it's priority. * } * * // ... * * // Is our priority higher than the created task? * if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) ) * { * // Our priority (obtained using NULL handle) is higher. * } * } * @endcode * \defgroup uxTaskPriorityGet uxTaskPriorityGet * \ingroup TaskCtrl */ UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask ); /** * task. h * @code{c} * UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask ); * @endcode * * A version of uxTaskPriorityGet() that can be used from an ISR. */ UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask ); /** * task. h * @code{c} * eTaskState eTaskGetState( TaskHandle_t xTask ); * @endcode * * INCLUDE_eTaskGetState must be defined as 1 for this function to be available. * See the configuration section for more information. * * Obtain the state of any task. States are encoded by the eTaskState * enumerated type. * * @param xTask Handle of the task to be queried. * * @return The state of xTask at the time the function was called. Note the * state of the task might change between the function being called, and the * functions return value being tested by the calling task. */ eTaskState eTaskGetState( TaskHandle_t xTask ); /** * task. h * @code{c} * void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ); * @endcode * * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. * See the configuration section for more information. * * Set the priority of any task. * * A context switch will occur before the function returns if the priority * being set is higher than the currently executing task. * * @param xTask Handle to the task for which the priority is being set. * Passing a NULL handle results in the priority of the calling task being set. * * @param uxNewPriority The priority to which the task will be set. * * Example usage: * @code{c} * void vAFunction( void ) * { * TaskHandle_t xHandle; * * // Create a task, storing the handle. * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); * * // ... * * // Use the handle to raise the priority of the created task. * vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 ); * * // ... * * // Use a NULL handle to raise our priority to the same value. * vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 ); * } * @endcode * \defgroup vTaskPrioritySet vTaskPrioritySet * \ingroup TaskCtrl */ void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ); /** * task. h * @code{c} * void vTaskSuspend( TaskHandle_t xTaskToSuspend ); * @endcode * * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. * See the configuration section for more information. * * Suspend any task. When suspended a task will never get any microcontroller * processing time, no matter what its priority. * * Calls to vTaskSuspend are not accumulative - * i.e. calling vTaskSuspend () twice on the same task still only requires one * call to vTaskResume () to ready the suspended task. * * RT-Thread only supports suspending the current running thread. * This function must be called with NULL as the parameter. * * @param xTaskToSuspend Handle to the task being suspended. Passing a NULL * handle will cause the calling task to be suspended. * * Example usage: * @code{c} * void vAFunction( void ) * { * TaskHandle_t xHandle; * * // Create a task, storing the handle. * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); * * // ... * * // Use the handle to suspend the created task. * vTaskSuspend( xHandle ); * * // ... * * // The created task will not run during this period, unless * // another task calls vTaskResume( xHandle ). * * //... * * * // Suspend ourselves. * vTaskSuspend( NULL ); * * // We cannot get here unless another task calls vTaskResume * // with our handle as the parameter. * } * @endcode * \defgroup vTaskSuspend vTaskSuspend * \ingroup TaskCtrl */ void vTaskSuspend( TaskHandle_t xTaskToSuspend ); /** * task. h * @code{c} * void vTaskResume( TaskHandle_t xTaskToResume ); * @endcode * * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. * See the configuration section for more information. * * Resumes a suspended task. * * A task that has been suspended by one or more calls to vTaskSuspend () * will be made available for running again by a single call to * vTaskResume (). * * @param xTaskToResume Handle to the task being readied. * * Example usage: * @code{c} * void vAFunction( void ) * { * TaskHandle_t xHandle; * * // Create a task, storing the handle. * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); * * // ... * * // Use the handle to suspend the created task. * vTaskSuspend( xHandle ); * * // ... * * // The created task will not run during this period, unless * // another task calls vTaskResume( xHandle ). * * //... * * * // Resume the suspended task ourselves. * vTaskResume( xHandle ); * * // The created task will once again get microcontroller processing * // time in accordance with its priority within the system. * } * @endcode * \defgroup vTaskResume vTaskResume * \ingroup TaskCtrl */ void vTaskResume( TaskHandle_t xTaskToResume ); /** * task. h * @code{c} * void xTaskResumeFromISR( TaskHandle_t xTaskToResume ); * @endcode * * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be * available. See the configuration section for more information. * * An implementation of vTaskResume() that can be called from within an ISR. * * A task that has been suspended by one or more calls to vTaskSuspend () * will be made available for running again by a single call to * xTaskResumeFromISR (). * * xTaskResumeFromISR() should not be used to synchronise a task with an * interrupt if there is a chance that the interrupt could arrive prior to the * task being suspended - as this can lead to interrupts being missed. Use of a * semaphore as a synchronisation mechanism would avoid this eventuality. * * @param xTaskToResume Handle to the task being readied. * * @return pdTRUE if resuming the task should result in a context switch, * otherwise pdFALSE. This is used by the ISR to determine if a context switch * may be required following the ISR. * * \defgroup vTaskResumeFromISR vTaskResumeFromISR * \ingroup TaskCtrl */ BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ); /*----------------------------------------------------------- * SCHEDULER CONTROL *----------------------------------------------------------*/ /** * task. h * @code{c} * void vTaskStartScheduler( void ); * @endcode * * Starts the real time kernel tick processing. After calling the kernel * has control over which tasks are executed and when. * * See the demo application file main.c for an example of creating * tasks and starting the kernel. * * Example usage: * @code{c} * void vAFunction( void ) * { * // Create at least one task before starting the kernel. * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); * * // Start the real time kernel with preemption. * vTaskStartScheduler (); * * // Will not get here unless a task calls vTaskEndScheduler () * } * @endcode * * \defgroup vTaskStartScheduler vTaskStartScheduler * \ingroup SchedulerControl */ void vTaskStartScheduler( void ); /** * task. h * @code{c} * void vTaskEndScheduler( void ); * @endcode * * NOTE: At the time of writing only the x86 real mode port, which runs on a PC * in place of DOS, implements this function. * * Stops the real time kernel tick. All created tasks will be automatically * deleted and multitasking (either preemptive or cooperative) will * stop. Execution then resumes from the point where vTaskStartScheduler () * was called, as if vTaskStartScheduler () had just returned. * * See the demo application file main. c in the demo/PC directory for an * example that uses vTaskEndScheduler (). * * vTaskEndScheduler () requires an exit function to be defined within the * portable layer (see vPortEndScheduler () in port. c for the PC port). This * performs hardware specific operations such as stopping the kernel tick. * * vTaskEndScheduler () will cause all of the resources allocated by the * kernel to be freed - but will not free resources allocated by application * tasks. * * Example usage: * @code{c} * void vTaskCode( void * pvParameters ) * { * for( ;; ) * { * // Task code goes here. * * // At some point we want to end the real time kernel processing * // so call ... * vTaskEndScheduler (); * } * } * * void vAFunction( void ) * { * // Create at least one task before starting the kernel. * xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL ); * * // Start the real time kernel with preemption. * vTaskStartScheduler (); * * // Will only get here when the vTaskCode () task has called * // vTaskEndScheduler (). When we get here we are back to single task * // execution. * } * @endcode * * \defgroup vTaskEndScheduler vTaskEndScheduler * \ingroup SchedulerControl */ void vTaskEndScheduler( void ); /** * task. h * @code{c} * void vTaskSuspendAll( void ); * @endcode * * Suspends the scheduler without disabling interrupts. Context switches will * not occur while the scheduler is suspended. * * After calling vTaskSuspendAll () the calling task will continue to execute * without risk of being swapped out until a call to xTaskResumeAll () has been * made. * * API functions that have the potential to cause a context switch (for example, * xTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler * is suspended. * * Example usage: * @code{c} * void vTask1( void * pvParameters ) * { * for( ;; ) * { * // Task code goes here. * * // ... * * // At some point the task wants to perform a long operation during * // which it does not want to get swapped out. It cannot use * // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the * // operation may cause interrupts to be missed - including the * // ticks. * * // Prevent the real time kernel swapping out the task. * vTaskSuspendAll (); * * // Perform the operation here. There is no need to use critical * // sections as we have all the microcontroller processing time. * // During this time interrupts will still operate and the kernel * // tick count will be maintained. * * // ... * * // The operation is complete. Restart the kernel. * xTaskResumeAll (); * } * } * @endcode * \defgroup vTaskSuspendAll vTaskSuspendAll * \ingroup SchedulerControl */ void vTaskSuspendAll( void ); /** * task. h * @code{c} * BaseType_t xTaskResumeAll( void ); * @endcode * * Resumes scheduler activity after it was suspended by a call to * vTaskSuspendAll(). * * xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks * that were previously suspended by a call to vTaskSuspend(). * * @return If resuming the scheduler caused a context switch then pdTRUE is * returned, otherwise pdFALSE is returned. * * Example usage: * @code{c} * void vTask1( void * pvParameters ) * { * for( ;; ) * { * // Task code goes here. * * // ... * * // At some point the task wants to perform a long operation during * // which it does not want to get swapped out. It cannot use * // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the * // operation may cause interrupts to be missed - including the * // ticks. * * // Prevent the real time kernel swapping out the task. * vTaskSuspendAll (); * * // Perform the operation here. There is no need to use critical * // sections as we have all the microcontroller processing time. * // During this time interrupts will still operate and the real * // time kernel tick count will be maintained. * * // ... * * // The operation is complete. Restart the kernel. We want to force * // a context switch - but there is no point if resuming the scheduler * // caused a context switch already. * if( !xTaskResumeAll () ) * { * taskYIELD (); * } * } * } * @endcode * \defgroup xTaskResumeAll xTaskResumeAll * \ingroup SchedulerControl */ BaseType_t xTaskResumeAll( void ); /*----------------------------------------------------------- * TASK UTILITIES *----------------------------------------------------------*/ /** * task. h * @code{c} * TickType_t xTaskGetTickCount( void ); * @endcode * * @return The count of ticks since vTaskStartScheduler was called. * * \defgroup xTaskGetTickCount xTaskGetTickCount * \ingroup TaskUtils */ TickType_t xTaskGetTickCount( void ); /** * task. h * @code{c} * TickType_t xTaskGetTickCountFromISR( void ); * @endcode * * @return The count of ticks since vTaskStartScheduler was called. * * This is a version of xTaskGetTickCount() that is safe to be called from an * ISR - provided that TickType_t is the natural word size of the * microcontroller being used or interrupt nesting is either not supported or * not being used. * * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR * \ingroup TaskUtils */ TickType_t xTaskGetTickCountFromISR( void ); /** * task. h * @code{c} * uint16_t uxTaskGetNumberOfTasks( void ); * @endcode * * @return The number of tasks that the real time kernel is currently managing. * This includes all ready, blocked and suspended tasks. A task that * has been deleted but not yet freed by the idle task will also be * included in the count. * * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks * \ingroup TaskUtils */ UBaseType_t uxTaskGetNumberOfTasks( void ); /** * task. h * @code{c} * char *pcTaskGetName( TaskHandle_t xTaskToQuery ); * @endcode * * @return The text (human readable) name of the task referenced by the handle * xTaskToQuery. A task can query its own name by either passing in its own * handle, or by setting xTaskToQuery to NULL. * * \defgroup pcTaskGetName pcTaskGetName * \ingroup TaskUtils */ char * pcTaskGetName( TaskHandle_t xTaskToQuery ); /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ /** * task. h * @code{c} * TaskHandle_t xTaskGetHandle( const char *pcNameToQuery ); * @endcode * * NOTE: This function takes a relatively long time to complete and should be * used sparingly. * * @return The handle of the task that has the human readable name pcNameToQuery. * NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle * must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available. * * \defgroup pcTaskGetHandle pcTaskGetHandle * \ingroup TaskUtils */ TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ); /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ /** * task.h * @code{c} * UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ); * @endcode * * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for * this function to be available. * * Returns the high water mark of the stack associated with xTask. That is, * the minimum free stack space there has been (in words, so on a 32 bit machine * a value of 1 means 4 bytes) since the task started. The smaller the returned * number the closer the task has come to overflowing its stack. * * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the * same except for their return type. Using configSTACK_DEPTH_TYPE allows the * user to determine the return type. It gets around the problem of the value * overflowing on 8-bit types without breaking backward compatibility for * applications that expect an 8-bit return type. * * @param xTask Handle of the task associated with the stack to be checked. * Set xTask to NULL to check the stack of the calling task. * * @return The smallest amount of free stack space there has been (in words, so * actual spaces on the stack rather than bytes) since the task referenced by * xTask was created. */ UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ); /** * task.h * @code{c} * configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ); * @endcode * * INCLUDE_uxTaskGetStackHighWaterMark2 must be set to 1 in FreeRTOSConfig.h for * this function to be available. * * Returns the high water mark of the stack associated with xTask. That is, * the minimum free stack space there has been (in words, so on a 32 bit machine * a value of 1 means 4 bytes) since the task started. The smaller the returned * number the closer the task has come to overflowing its stack. * * uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the * same except for their return type. Using configSTACK_DEPTH_TYPE allows the * user to determine the return type. It gets around the problem of the value * overflowing on 8-bit types without breaking backward compatibility for * applications that expect an 8-bit return type. * * @param xTask Handle of the task associated with the stack to be checked. * Set xTask to NULL to check the stack of the calling task. * * @return The smallest amount of free stack space there has been (in words, so * actual spaces on the stack rather than bytes) since the task referenced by * xTask was created. */ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ); /* When using trace macros it is sometimes necessary to include task.h before * FreeRTOS.h. When this is done TaskHookFunction_t will not yet have been defined, * so the following two prototypes will cause a compilation error. This can be * fixed by simply guarding against the inclusion of these two prototypes unless * they are explicitly required by the configUSE_APPLICATION_TASK_TAG configuration * constant. */ #ifdef configUSE_APPLICATION_TASK_TAG #if configUSE_APPLICATION_TASK_TAG == 1 /** * task.h * @code{c} * void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction ); * @endcode * * Sets pxHookFunction to be the task hook function used by the task xTask. * Passing xTask as NULL has the effect of setting the calling tasks hook * function. */ void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction ); /** * task.h * @code{c} * void xTaskGetApplicationTaskTag( TaskHandle_t xTask ); * @endcode * * Returns the pxHookFunction value assigned to the task xTask. Do not * call from an interrupt service routine - call * xTaskGetApplicationTaskTagFromISR() instead. */ TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask ); /** * task.h * @code{c} * void xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask ); * @endcode * * Returns the pxHookFunction value assigned to the task xTask. Can * be called from an interrupt service routine. */ TaskHookFunction_t xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask ); #endif /* configUSE_APPLICATION_TASK_TAG ==1 */ #endif /* ifdef configUSE_APPLICATION_TASK_TAG */ /** * task.h * @code{c} * BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter ); * @endcode * * Calls the hook function associated with xTask. Passing xTask as NULL has * the effect of calling the Running tasks (the calling task) hook function. * * pvParameter is passed to the hook function for the task to interpret as it * wants. The return value is the value returned by the task hook function * registered by the user. */ BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void * pvParameter ); /** * xTaskGetIdleTaskHandle() is only available if * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h. * * Simply returns the handle of the idle task. It is not valid to call * xTaskGetIdleTaskHandle() before the scheduler has been started. */ TaskHandle_t xTaskGetIdleTaskHandle( void ); /** * task. h * @code{c} * BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction ); * BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction ); * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these * functions to be available. * * Sends a direct to task notification to a task, with an optional value and * action. * * Each task has a private array of "notification values" (or 'notifications'), * each of which is a 32-bit unsigned integer (uint32_t). The constant * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the * array, and (for backward compatibility) defaults to 1 if left undefined. * Prior to FreeRTOS V10.4.0 there was only one notification value per task. * * Events can be sent to a task using an intermediary object. Examples of such * objects are queues, semaphores, mutexes and event groups. Task notifications * are a method of sending an event directly to a task without the need for such * an intermediary object. * * A notification sent to a task can optionally perform an action, such as * update, overwrite or increment one of the task's notification values. In * that way task notifications can be used to send data to a task, or be used as * light weight and fast binary or counting semaphores. * * A task can use xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() to * [optionally] block to wait for a notification to be pending. The task does * not consume any CPU time while it is in the Blocked state. * * A notification sent to a task will remain pending until it is cleared by the * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their * un-indexed equivalents). If the task was already in the Blocked state to * wait for a notification when the notification arrives then the task will * automatically be removed from the Blocked state (unblocked) and the * notification cleared. * * **NOTE** Each notification within the array operates independently - a task * can only block on one notification within the array at a time and will not be * unblocked by a notification sent to any other array index. * * Backward compatibility information: * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and * all task notification API functions operated on that value. Replacing the * single notification value with an array of notification values necessitated a * new set of API functions that could address specific notifications within the * array. xTaskNotify() is the original API function, and remains backward * compatible by always operating on the notification value at index 0 in the * array. Calling xTaskNotify() is equivalent to calling xTaskNotifyIndexed() * with the uxIndexToNotify parameter set to 0. * * @param xTaskToNotify The handle of the task being notified. The handle to a * task can be returned from the xTaskCreate() API function used to create the * task, and the handle of the currently running task can be obtained by calling * xTaskGetCurrentTaskHandle(). * * @param uxIndexToNotify The index within the target task's array of * notification values to which the notification is to be sent. uxIndexToNotify * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotify() does * not have this parameter and always sends notifications to index 0. * * @param ulValue Data that can be sent with the notification. How the data is * used depends on the value of the eAction parameter. * * @param eAction Specifies how the notification updates the task's notification * value, if at all. Valid values for eAction are as follows: * * eSetBits - * The target notification value is bitwise ORed with ulValue. * xTaskNotifyIndexed() always returns pdPASS in this case. * * eIncrement - * The target notification value is incremented. ulValue is not used and * xTaskNotifyIndexed() always returns pdPASS in this case. * * eSetValueWithOverwrite - * The target notification value is set to the value of ulValue, even if the * task being notified had not yet processed the previous notification at the * same array index (the task already had a notification pending at that index). * xTaskNotifyIndexed() always returns pdPASS in this case. * * eSetValueWithoutOverwrite - * If the task being notified did not already have a notification pending at the * same array index then the target notification value is set to ulValue and * xTaskNotifyIndexed() will return pdPASS. If the task being notified already * had a notification pending at the same array index then no action is * performed and pdFAIL is returned. * * eNoAction - * The task receives a notification at the specified array index without the * notification value at that index being updated. ulValue is not used and * xTaskNotifyIndexed() always returns pdPASS in this case. * * pulPreviousNotificationValue - * Can be used to pass out the subject task's notification value before any * bits are modified by the notify function. * * @return Dependent on the value of eAction. See the description of the * eAction parameter. * * \defgroup xTaskNotifyIndexed xTaskNotifyIndexed * \ingroup TaskNotifications */ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t * pulPreviousNotificationValue ); #define xTaskNotify( xTaskToNotify, ulValue, eAction ) \ xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL ) #define xTaskNotifyIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction ) \ xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL ) /** * task. h * @code{c} * BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue ); * BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue ); * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * xTaskNotifyAndQueryIndexed() performs the same operation as * xTaskNotifyIndexed() with the addition that it also returns the subject * task's prior notification value (the notification value at the time the * function is called rather than when the function returns) in the additional * pulPreviousNotifyValue parameter. * * xTaskNotifyAndQuery() performs the same operation as xTaskNotify() with the * addition that it also returns the subject task's prior notification value * (the notification value as it was at the time the function is called, rather * than when the function returns) in the additional pulPreviousNotifyValue * parameter. * * \defgroup xTaskNotifyAndQueryIndexed xTaskNotifyAndQueryIndexed * \ingroup TaskNotifications */ #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) \ xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) #define xTaskNotifyAndQueryIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotifyValue ) \ xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) /** * task. h * @code{c} * BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken ); * BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken ); * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these * functions to be available. * * A version of xTaskNotifyIndexed() that can be used from an interrupt service * routine (ISR). * * Each task has a private array of "notification values" (or 'notifications'), * each of which is a 32-bit unsigned integer (uint32_t). The constant * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the * array, and (for backward compatibility) defaults to 1 if left undefined. * Prior to FreeRTOS V10.4.0 there was only one notification value per task. * * Events can be sent to a task using an intermediary object. Examples of such * objects are queues, semaphores, mutexes and event groups. Task notifications * are a method of sending an event directly to a task without the need for such * an intermediary object. * * A notification sent to a task can optionally perform an action, such as * update, overwrite or increment one of the task's notification values. In * that way task notifications can be used to send data to a task, or be used as * light weight and fast binary or counting semaphores. * * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block * to wait for a notification value to have a non-zero value. The task does * not consume any CPU time while it is in the Blocked state. * * A notification sent to a task will remain pending until it is cleared by the * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their * un-indexed equivalents). If the task was already in the Blocked state to * wait for a notification when the notification arrives then the task will * automatically be removed from the Blocked state (unblocked) and the * notification cleared. * * **NOTE** Each notification within the array operates independently - a task * can only block on one notification within the array at a time and will not be * unblocked by a notification sent to any other array index. * * Backward compatibility information: * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and * all task notification API functions operated on that value. Replacing the * single notification value with an array of notification values necessitated a * new set of API functions that could address specific notifications within the * array. xTaskNotifyFromISR() is the original API function, and remains * backward compatible by always operating on the notification value at index 0 * within the array. Calling xTaskNotifyFromISR() is equivalent to calling * xTaskNotifyIndexedFromISR() with the uxIndexToNotify parameter set to 0. * * @param uxIndexToNotify The index within the target task's array of * notification values to which the notification is to be sent. uxIndexToNotify * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyFromISR() * does not have this parameter and always sends notifications to index 0. * * @param xTaskToNotify The handle of the task being notified. The handle to a * task can be returned from the xTaskCreate() API function used to create the * task, and the handle of the currently running task can be obtained by calling * xTaskGetCurrentTaskHandle(). * * @param ulValue Data that can be sent with the notification. How the data is * used depends on the value of the eAction parameter. * * @param eAction Specifies how the notification updates the task's notification * value, if at all. Valid values for eAction are as follows: * * eSetBits - * The task's notification value is bitwise ORed with ulValue. xTaskNotify() * always returns pdPASS in this case. * * eIncrement - * The task's notification value is incremented. ulValue is not used and * xTaskNotify() always returns pdPASS in this case. * * eSetValueWithOverwrite - * The task's notification value is set to the value of ulValue, even if the * task being notified had not yet processed the previous notification (the * task already had a notification pending). xTaskNotify() always returns * pdPASS in this case. * * eSetValueWithoutOverwrite - * If the task being notified did not already have a notification pending then * the task's notification value is set to ulValue and xTaskNotify() will * return pdPASS. If the task being notified already had a notification * pending then no action is performed and pdFAIL is returned. * * eNoAction - * The task receives a notification without its notification value being * updated. ulValue is not used and xTaskNotify() always returns pdPASS in * this case. * * @param pxHigherPriorityTaskWoken xTaskNotifyFromISR() will set * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the * task to which the notification was sent to leave the Blocked state, and the * unblocked task has a priority higher than the currently running task. If * xTaskNotifyFromISR() sets this value to pdTRUE then a context switch should * be requested before the interrupt is exited. How a context switch is * requested from an ISR is dependent on the port - see the documentation page * for the port in use. * * @return Dependent on the value of eAction. See the description of the * eAction parameter. * * \defgroup xTaskNotifyIndexedFromISR xTaskNotifyIndexedFromISR * \ingroup TaskNotifications */ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t * pulPreviousNotificationValue, BaseType_t * pxHigherPriorityTaskWoken ); #define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \ xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) #define xTaskNotifyIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \ xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) /** * task. h * @code{c} * BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ); * BaseType_t xTaskNotifyAndQueryFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ); * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * xTaskNotifyAndQueryIndexedFromISR() performs the same operation as * xTaskNotifyIndexedFromISR() with the addition that it also returns the * subject task's prior notification value (the notification value at the time * the function is called rather than at the time the function returns) in the * additional pulPreviousNotifyValue parameter. * * xTaskNotifyAndQueryFromISR() performs the same operation as * xTaskNotifyFromISR() with the addition that it also returns the subject * task's prior notification value (the notification value at the time the * function is called rather than at the time the function returns) in the * additional pulPreviousNotifyValue parameter. * * \defgroup xTaskNotifyAndQueryIndexedFromISR xTaskNotifyAndQueryIndexedFromISR * \ingroup TaskNotifications */ #define xTaskNotifyAndQueryIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \ xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) ) #define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \ xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) ) /** * task. h * @code{c} * BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); * * BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); * @endcode * * Waits for a direct to task notification to be pending at a given index within * an array of direct to task notifications. * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this * function to be available. * * Each task has a private array of "notification values" (or 'notifications'), * each of which is a 32-bit unsigned integer (uint32_t). The constant * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the * array, and (for backward compatibility) defaults to 1 if left undefined. * Prior to FreeRTOS V10.4.0 there was only one notification value per task. * * Events can be sent to a task using an intermediary object. Examples of such * objects are queues, semaphores, mutexes and event groups. Task notifications * are a method of sending an event directly to a task without the need for such * an intermediary object. * * A notification sent to a task can optionally perform an action, such as * update, overwrite or increment one of the task's notification values. In * that way task notifications can be used to send data to a task, or be used as * light weight and fast binary or counting semaphores. * * A notification sent to a task will remain pending until it is cleared by the * task calling xTaskNotifyWaitIndexed() or ulTaskNotifyTakeIndexed() (or their * un-indexed equivalents). If the task was already in the Blocked state to * wait for a notification when the notification arrives then the task will * automatically be removed from the Blocked state (unblocked) and the * notification cleared. * * A task can use xTaskNotifyWaitIndexed() to [optionally] block to wait for a * notification to be pending, or ulTaskNotifyTakeIndexed() to [optionally] block * to wait for a notification value to have a non-zero value. The task does * not consume any CPU time while it is in the Blocked state. * * **NOTE** Each notification within the array operates independently - a task * can only block on one notification within the array at a time and will not be * unblocked by a notification sent to any other array index. * * Backward compatibility information: * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and * all task notification API functions operated on that value. Replacing the * single notification value with an array of notification values necessitated a * new set of API functions that could address specific notifications within the * array. xTaskNotifyWait() is the original API function, and remains backward * compatible by always operating on the notification value at index 0 in the * array. Calling xTaskNotifyWait() is equivalent to calling * xTaskNotifyWaitIndexed() with the uxIndexToWaitOn parameter set to 0. * * @param uxIndexToWaitOn The index within the calling task's array of * notification values on which the calling task will wait for a notification to * be received. uxIndexToWaitOn must be less than * configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyWait() does * not have this parameter and always waits for notifications on index 0. * * @param ulBitsToClearOnEntry Bits that are set in ulBitsToClearOnEntry value * will be cleared in the calling task's notification value before the task * checks to see if any notifications are pending, and optionally blocks if no * notifications are pending. Setting ulBitsToClearOnEntry to ULONG_MAX (if * limits.h is included) or 0xffffffffUL (if limits.h is not included) will have * the effect of resetting the task's notification value to 0. Setting * ulBitsToClearOnEntry to 0 will leave the task's notification value unchanged. * * @param ulBitsToClearOnExit If a notification is pending or received before * the calling task exits the xTaskNotifyWait() function then the task's * notification value (see the xTaskNotify() API function) is passed out using * the pulNotificationValue parameter. Then any bits that are set in * ulBitsToClearOnExit will be cleared in the task's notification value (note * *pulNotificationValue is set before any bits are cleared). Setting * ulBitsToClearOnExit to ULONG_MAX (if limits.h is included) or 0xffffffffUL * (if limits.h is not included) will have the effect of resetting the task's * notification value to 0 before the function exits. Setting * ulBitsToClearOnExit to 0 will leave the task's notification value unchanged * when the function exits (in which case the value passed out in * pulNotificationValue will match the task's notification value). * * @param pulNotificationValue Used to pass the task's notification value out * of the function. Note the value passed out will not be effected by the * clearing of any bits caused by ulBitsToClearOnExit being non-zero. * * @param xTicksToWait The maximum amount of time that the task should wait in * the Blocked state for a notification to be received, should a notification * not already be pending when xTaskNotifyWait() was called. The task * will not consume any processing time while it is in the Blocked state. This * is specified in kernel ticks, the macro pdMS_TO_TICKS( value_in_ms ) can be * used to convert a time specified in milliseconds to a time specified in * ticks. * * @return If a notification was received (including notifications that were * already pending when xTaskNotifyWait was called) then pdPASS is * returned. Otherwise pdFAIL is returned. * * \defgroup xTaskNotifyWaitIndexed xTaskNotifyWaitIndexed * \ingroup TaskNotifications */ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t * pulNotificationValue, TickType_t xTicksToWait ); #define xTaskNotifyWait( ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \ xTaskGenericNotifyWait( tskDEFAULT_INDEX_TO_NOTIFY, ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) ) #define xTaskNotifyWaitIndexed( uxIndexToWaitOn, ulBitsToClearOnEntry, ulBitsToClearOnExit, pulNotificationValue, xTicksToWait ) \ xTaskGenericNotifyWait( ( uxIndexToWaitOn ), ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) ) /** * task. h * @code{c} * BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify ); * BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify ); * @endcode * * Sends a direct to task notification to a particular index in the target * task's notification array in a manner similar to giving a counting semaphore. * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details. * * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these * macros to be available. * * Each task has a private array of "notification values" (or 'notifications'), * each of which is a 32-bit unsigned integer (uint32_t). The constant * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the * array, and (for backward compatibility) defaults to 1 if left undefined. * Prior to FreeRTOS V10.4.0 there was only one notification value per task. * * Events can be sent to a task using an intermediary object. Examples of such * objects are queues, semaphores, mutexes and event groups. Task notifications * are a method of sending an event directly to a task without the need for such * an intermediary object. * * A notification sent to a task can optionally perform an action, such as * update, overwrite or increment one of the task's notification values. In * that way task notifications can be used to send data to a task, or be used as * light weight and fast binary or counting semaphores. * * xTaskNotifyGiveIndexed() is a helper macro intended for use when task * notifications are used as light weight and faster binary or counting * semaphore equivalents. Actual FreeRTOS semaphores are given using the * xSemaphoreGive() API function, the equivalent action that instead uses a task * notification is xTaskNotifyGiveIndexed(). * * When task notifications are being used as a binary or counting semaphore * equivalent then the task being notified should wait for the notification * using the ulTaskNotificationTakeIndexed() API function rather than the * xTaskNotifyWaitIndexed() API function. * * **NOTE** Each notification within the array operates independently - a task * can only block on one notification within the array at a time and will not be * unblocked by a notification sent to any other array index. * * Backward compatibility information: * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and * all task notification API functions operated on that value. Replacing the * single notification value with an array of notification values necessitated a * new set of API functions that could address specific notifications within the * array. xTaskNotifyGive() is the original API function, and remains backward * compatible by always operating on the notification value at index 0 in the * array. Calling xTaskNotifyGive() is equivalent to calling * xTaskNotifyGiveIndexed() with the uxIndexToNotify parameter set to 0. * * @param xTaskToNotify The handle of the task being notified. The handle to a * task can be returned from the xTaskCreate() API function used to create the * task, and the handle of the currently running task can be obtained by calling * xTaskGetCurrentTaskHandle(). * * @param uxIndexToNotify The index within the target task's array of * notification values to which the notification is to be sent. uxIndexToNotify * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGive() * does not have this parameter and always sends notifications to index 0. * * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the * eAction parameter set to eIncrement - so pdPASS is always returned. * * \defgroup xTaskNotifyGiveIndexed xTaskNotifyGiveIndexed * \ingroup TaskNotifications */ #define xTaskNotifyGive( xTaskToNotify ) \ xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL ) #define xTaskNotifyGiveIndexed( xTaskToNotify, uxIndexToNotify ) \ xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ), eIncrement, NULL ) /** * task. h * @code{c} * void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken ); * void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken ); * @endcode * * A version of xTaskNotifyGiveIndexed() that can be called from an interrupt * service routine (ISR). * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for more details. * * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this macro * to be available. * * Each task has a private array of "notification values" (or 'notifications'), * each of which is a 32-bit unsigned integer (uint32_t). The constant * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the * array, and (for backward compatibility) defaults to 1 if left undefined. * Prior to FreeRTOS V10.4.0 there was only one notification value per task. * * Events can be sent to a task using an intermediary object. Examples of such * objects are queues, semaphores, mutexes and event groups. Task notifications * are a method of sending an event directly to a task without the need for such * an intermediary object. * * A notification sent to a task can optionally perform an action, such as * update, overwrite or increment one of the task's notification values. In * that way task notifications can be used to send data to a task, or be used as * light weight and fast binary or counting semaphores. * * vTaskNotifyGiveIndexedFromISR() is intended for use when task notifications * are used as light weight and faster binary or counting semaphore equivalents. * Actual FreeRTOS semaphores are given from an ISR using the * xSemaphoreGiveFromISR() API function, the equivalent action that instead uses * a task notification is vTaskNotifyGiveIndexedFromISR(). * * When task notifications are being used as a binary or counting semaphore * equivalent then the task being notified should wait for the notification * using the ulTaskNotificationTakeIndexed() API function rather than the * xTaskNotifyWaitIndexed() API function. * * **NOTE** Each notification within the array operates independently - a task * can only block on one notification within the array at a time and will not be * unblocked by a notification sent to any other array index. * * Backward compatibility information: * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and * all task notification API functions operated on that value. Replacing the * single notification value with an array of notification values necessitated a * new set of API functions that could address specific notifications within the * array. xTaskNotifyFromISR() is the original API function, and remains * backward compatible by always operating on the notification value at index 0 * within the array. Calling xTaskNotifyGiveFromISR() is equivalent to calling * xTaskNotifyGiveIndexedFromISR() with the uxIndexToNotify parameter set to 0. * * @param xTaskToNotify The handle of the task being notified. The handle to a * task can be returned from the xTaskCreate() API function used to create the * task, and the handle of the currently running task can be obtained by calling * xTaskGetCurrentTaskHandle(). * * @param uxIndexToNotify The index within the target task's array of * notification values to which the notification is to be sent. uxIndexToNotify * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. * xTaskNotifyGiveFromISR() does not have this parameter and always sends * notifications to index 0. * * @param pxHigherPriorityTaskWoken vTaskNotifyGiveFromISR() will set * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the * task to which the notification was sent to leave the Blocked state, and the * unblocked task has a priority higher than the currently running task. If * vTaskNotifyGiveFromISR() sets this value to pdTRUE then a context switch * should be requested before the interrupt is exited. How a context switch is * requested from an ISR is dependent on the port - see the documentation page * for the port in use. * * \defgroup vTaskNotifyGiveIndexedFromISR vTaskNotifyGiveIndexedFromISR * \ingroup TaskNotifications */ void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, BaseType_t * pxHigherPriorityTaskWoken ); #define vTaskNotifyGiveFromISR( xTaskToNotify, pxHigherPriorityTaskWoken ) \ vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( pxHigherPriorityTaskWoken ) ); #define vTaskNotifyGiveIndexedFromISR( xTaskToNotify, uxIndexToNotify, pxHigherPriorityTaskWoken ) \ vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( pxHigherPriorityTaskWoken ) ); /** * task. h * @code{c} * uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait ); * * uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait ); * @endcode * * Waits for a direct to task notification on a particular index in the calling * task's notification array in a manner similar to taking a counting semaphore. * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this * function to be available. * * Each task has a private array of "notification values" (or 'notifications'), * each of which is a 32-bit unsigned integer (uint32_t). The constant * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the * array, and (for backward compatibility) defaults to 1 if left undefined. * Prior to FreeRTOS V10.4.0 there was only one notification value per task. * * Events can be sent to a task using an intermediary object. Examples of such * objects are queues, semaphores, mutexes and event groups. Task notifications * are a method of sending an event directly to a task without the need for such * an intermediary object. * * A notification sent to a task can optionally perform an action, such as * update, overwrite or increment one of the task's notification values. In * that way task notifications can be used to send data to a task, or be used as * light weight and fast binary or counting semaphores. * * ulTaskNotifyTakeIndexed() is intended for use when a task notification is * used as a faster and lighter weight binary or counting semaphore alternative. * Actual FreeRTOS semaphores are taken using the xSemaphoreTake() API function, * the equivalent action that instead uses a task notification is * ulTaskNotifyTakeIndexed(). * * When a task is using its notification value as a binary or counting semaphore * other tasks should send notifications to it using the xTaskNotifyGiveIndexed() * macro, or xTaskNotifyIndex() function with the eAction parameter set to * eIncrement. * * ulTaskNotifyTakeIndexed() can either clear the task's notification value at * the array index specified by the uxIndexToWaitOn parameter to zero on exit, * in which case the notification value acts like a binary semaphore, or * decrement the notification value on exit, in which case the notification * value acts like a counting semaphore. * * A task can use ulTaskNotifyTakeIndexed() to [optionally] block to wait for * a notification. The task does not consume any CPU time while it is in the * Blocked state. * * Where as xTaskNotifyWaitIndexed() will return when a notification is pending, * ulTaskNotifyTakeIndexed() will return when the task's notification value is * not zero. * * **NOTE** Each notification within the array operates independently - a task * can only block on one notification within the array at a time and will not be * unblocked by a notification sent to any other array index. * * Backward compatibility information: * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and * all task notification API functions operated on that value. Replacing the * single notification value with an array of notification values necessitated a * new set of API functions that could address specific notifications within the * array. ulTaskNotifyTake() is the original API function, and remains backward * compatible by always operating on the notification value at index 0 in the * array. Calling ulTaskNotifyTake() is equivalent to calling * ulTaskNotifyTakeIndexed() with the uxIndexToWaitOn parameter set to 0. * * @param uxIndexToWaitOn The index within the calling task's array of * notification values on which the calling task will wait for a notification to * be non-zero. uxIndexToWaitOn must be less than * configTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyTake() does * not have this parameter and always waits for notifications on index 0. * * @param xClearCountOnExit if xClearCountOnExit is pdFALSE then the task's * notification value is decremented when the function exits. In this way the * notification value acts like a counting semaphore. If xClearCountOnExit is * not pdFALSE then the task's notification value is cleared to zero when the * function exits. In this way the notification value acts like a binary * semaphore. * * @param xTicksToWait The maximum amount of time that the task should wait in * the Blocked state for the task's notification value to be greater than zero, * should the count not already be greater than zero when * ulTaskNotifyTake() was called. The task will not consume any processing * time while it is in the Blocked state. This is specified in kernel ticks, * the macro pdMS_TO_TICKS( value_in_ms ) can be used to convert a time * specified in milliseconds to a time specified in ticks. * * @return The task's notification count before it is either cleared to zero or * decremented (see the xClearCountOnExit parameter). * * \defgroup ulTaskNotifyTakeIndexed ulTaskNotifyTakeIndexed * \ingroup TaskNotifications */ uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait ); #define ulTaskNotifyTake( xClearCountOnExit, xTicksToWait ) \ ulTaskGenericNotifyTake( ( tskDEFAULT_INDEX_TO_NOTIFY ), ( xClearCountOnExit ), ( xTicksToWait ) ) #define ulTaskNotifyTakeIndexed( uxIndexToWaitOn, xClearCountOnExit, xTicksToWait ) \ ulTaskGenericNotifyTake( ( uxIndexToWaitOn ), ( xClearCountOnExit ), ( xTicksToWait ) ) /** * task. h * @code{c} * BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToCLear ); * * BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask ); * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these * functions to be available. * * Each task has a private array of "notification values" (or 'notifications'), * each of which is a 32-bit unsigned integer (uint32_t). The constant * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the * array, and (for backward compatibility) defaults to 1 if left undefined. * Prior to FreeRTOS V10.4.0 there was only one notification value per task. * * If a notification is sent to an index within the array of notifications then * the notification at that index is said to be 'pending' until it is read or * explicitly cleared by the receiving task. xTaskNotifyStateClearIndexed() * is the function that clears a pending notification without reading the * notification value. The notification value at the same array index is not * altered. Set xTask to NULL to clear the notification state of the calling * task. * * Backward compatibility information: * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and * all task notification API functions operated on that value. Replacing the * single notification value with an array of notification values necessitated a * new set of API functions that could address specific notifications within the * array. xTaskNotifyStateClear() is the original API function, and remains * backward compatible by always operating on the notification value at index 0 * within the array. Calling xTaskNotifyStateClear() is equivalent to calling * xTaskNotifyStateClearIndexed() with the uxIndexToNotify parameter set to 0. * * @param xTask The handle of the RTOS task that will have a notification state * cleared. Set xTask to NULL to clear a notification state in the calling * task. To obtain a task's handle create the task using xTaskCreate() and * make use of the pxCreatedTask parameter, or create the task using * xTaskCreateStatic() and store the returned value, or use the task's name in * a call to xTaskGetHandle(). * * @param uxIndexToClear The index within the target task's array of * notification values to act upon. For example, setting uxIndexToClear to 1 * will clear the state of the notification at index 1 within the array. * uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. * ulTaskNotifyStateClear() does not have this parameter and always acts on the * notification at index 0. * * @return pdTRUE if the task's notification state was set to * eNotWaitingNotification, otherwise pdFALSE. * * \defgroup xTaskNotifyStateClearIndexed xTaskNotifyStateClearIndexed * \ingroup TaskNotifications */ BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, UBaseType_t uxIndexToClear ); #define xTaskNotifyStateClear( xTask ) \ xTaskGenericNotifyStateClear( ( xTask ), ( tskDEFAULT_INDEX_TO_NOTIFY ) ) #define xTaskNotifyStateClearIndexed( xTask, uxIndexToClear ) \ xTaskGenericNotifyStateClear( ( xTask ), ( uxIndexToClear ) ) /** * task. h * @code{c} * uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear ); * * uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear ); * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * * configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these * functions to be available. * * Each task has a private array of "notification values" (or 'notifications'), * each of which is a 32-bit unsigned integer (uint32_t). The constant * configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the * array, and (for backward compatibility) defaults to 1 if left undefined. * Prior to FreeRTOS V10.4.0 there was only one notification value per task. * * ulTaskNotifyValueClearIndexed() clears the bits specified by the * ulBitsToClear bit mask in the notification value at array index uxIndexToClear * of the task referenced by xTask. * * Backward compatibility information: * Prior to FreeRTOS V10.4.0 each task had a single "notification value", and * all task notification API functions operated on that value. Replacing the * single notification value with an array of notification values necessitated a * new set of API functions that could address specific notifications within the * array. ulTaskNotifyValueClear() is the original API function, and remains * backward compatible by always operating on the notification value at index 0 * within the array. Calling ulTaskNotifyValueClear() is equivalent to calling * ulTaskNotifyValueClearIndexed() with the uxIndexToClear parameter set to 0. * * @param xTask The handle of the RTOS task that will have bits in one of its * notification values cleared. Set xTask to NULL to clear bits in a * notification value of the calling task. To obtain a task's handle create the * task using xTaskCreate() and make use of the pxCreatedTask parameter, or * create the task using xTaskCreateStatic() and store the returned value, or * use the task's name in a call to xTaskGetHandle(). * * @param uxIndexToClear The index within the target task's array of * notification values in which to clear the bits. uxIndexToClear * must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. * ulTaskNotifyValueClear() does not have this parameter and always clears bits * in the notification value at index 0. * * @param ulBitsToClear Bit mask of the bits to clear in the notification value of * xTask. Set a bit to 1 to clear the corresponding bits in the task's notification * value. Set ulBitsToClear to 0xffffffff (UINT_MAX on 32-bit architectures) to clear * the notification value to 0. Set ulBitsToClear to 0 to query the task's * notification value without clearing any bits. * * * @return The value of the target task's notification value before the bits * specified by ulBitsToClear were cleared. * \defgroup ulTaskNotifyValueClear ulTaskNotifyValueClear * \ingroup TaskNotifications */ uint32_t ulTaskGenericNotifyValueClear( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear ); #define ulTaskNotifyValueClear( xTask, ulBitsToClear ) \ ulTaskGenericNotifyValueClear( ( xTask ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulBitsToClear ) ) #define ulTaskNotifyValueClearIndexed( xTask, uxIndexToClear, ulBitsToClear ) \ ulTaskGenericNotifyValueClear( ( xTask ), ( uxIndexToClear ), ( ulBitsToClear ) ) /** * task.h * @code{c} * void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ); * @endcode * * Capture the current time for future use with xTaskCheckForTimeOut(). * * @param pxTimeOut Pointer to a timeout object into which the current time * is to be captured. The captured time includes the tick count and the number * of times the tick count has overflowed since the system first booted. * \defgroup vTaskSetTimeOutState vTaskSetTimeOutState * \ingroup TaskCtrl */ void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ); /** * task.h * @code{c} * BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ); * @endcode * * Determines if pxTicksToWait ticks has passed since a time was captured * using a call to vTaskSetTimeOutState(). The captured time includes the tick * count and the number of times the tick count has overflowed. * * @param pxTimeOut The time status as captured previously using * vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated * to reflect the current time status. * @param pxTicksToWait The number of ticks to check for timeout i.e. if * pxTicksToWait ticks have passed since pxTimeOut was last updated (either by * vTaskSetTimeOutState() or xTaskCheckForTimeOut()), the timeout has occurred. * If the timeout has not occurred, pxTicksToWait is updated to reflect the * number of remaining ticks. * * @return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is * returned and pxTicksToWait is updated to reflect the number of remaining * ticks. * * @see https://www.FreeRTOS.org/xTaskCheckForTimeOut.html * * Example Usage: * @code{c} * // Driver library function used to receive uxWantedBytes from an Rx buffer * // that is filled by a UART interrupt. If there are not enough bytes in the * // Rx buffer then the task enters the Blocked state until it is notified that * // more data has been placed into the buffer. If there is still not enough * // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut() * // is used to re-calculate the Block time to ensure the total amount of time * // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This * // continues until either the buffer contains at least uxWantedBytes bytes, * // or the total amount of time spent in the Blocked state reaches * // MAX_TIME_TO_WAIT - at which point the task reads however many bytes are * // available up to a maximum of uxWantedBytes. * * size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes ) * { * size_t uxReceived = 0; * TickType_t xTicksToWait = MAX_TIME_TO_WAIT; * TimeOut_t xTimeOut; * * // Initialize xTimeOut. This records the time at which this function * // was entered. * vTaskSetTimeOutState( &xTimeOut ); * * // Loop until the buffer contains the wanted number of bytes, or a * // timeout occurs. * while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes ) * { * // The buffer didn't contain enough data so this task is going to * // enter the Blocked state. Adjusting xTicksToWait to account for * // any time that has been spent in the Blocked state within this * // function so far to ensure the total amount of time spent in the * // Blocked state does not exceed MAX_TIME_TO_WAIT. * if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE ) * { * //Timed out before the wanted number of bytes were available, * // exit the loop. * break; * } * * // Wait for a maximum of xTicksToWait ticks to be notified that the * // receive interrupt has placed more data into the buffer. * ulTaskNotifyTake( pdTRUE, xTicksToWait ); * } * * // Attempt to read uxWantedBytes from the receive buffer into pucBuffer. * // The actual number of bytes read (which might be less than * // uxWantedBytes) is returned. * uxReceived = UART_read_from_receive_buffer( pxUARTInstance, * pucBuffer, * uxWantedBytes ); * * return uxReceived; * } * @endcode * \defgroup xTaskCheckForTimeOut xTaskCheckForTimeOut * \ingroup TaskCtrl */ BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ); /*----------------------------------------------------------- * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES *----------------------------------------------------------*/ /* * Return the handle of the calling task. */ TaskHandle_t xTaskGetCurrentTaskHandle( void ); /* * Returns the scheduler state as taskSCHEDULER_RUNNING, * taskSCHEDULER_NOT_STARTED or taskSCHEDULER_SUSPENDED. */ BaseType_t xTaskGetSchedulerState( void ); #ifdef ESP_PLATFORM BaseType_t xTaskGetAffinity( TaskHandle_t xTask ); TaskHandle_t xTaskGetCurrentTaskHandleForCPU( BaseType_t cpuid ); TaskHandle_t xTaskGetIdleTaskHandleForCPU( UBaseType_t cpuid ); /* Unimplemented */ #if ( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 ) void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, BaseType_t xIndex, void * pvValue ); void * pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery, BaseType_t xIndex ); #if ( configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS ) typedef void (*TlsDeleteCallbackFunction_t)( int, void * ); void vTaskSetThreadLocalStoragePointerAndDelCallback( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue, TlsDeleteCallbackFunction_t pvDelCallback); #endif #endif #endif /* *INDENT-OFF* */ #ifdef __cplusplus } #endif /* *INDENT-ON* */ #endif /* INC_TASK_H */