Chapter 2. API Reference
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 no-
tified 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.
Parameters
• 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().
• 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 config-
TASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyGiveFromISR() does not have this pa-
rameter and always sends notifications to index 0.
• pxHigherPriorityTaskWoken: vTaskNotifyGiveFromISR() will set *pxHigherPriority-
TaskWoken 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 run-
ning 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.
uint32_t ulTaskGenericNotifyTake(UBaseType_t uxIndexToWaitOn, BaseType_t xClearCoun-
tOnExit, TickType_t xTicksToWait)
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 un-
signed 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.
Espressif Systems 876
Submit Document Feedback
Release v4.4
To Next Page
Loading...