Espressif ESP32-S2 Programming Manual page 886

Chapter 2. API Reference
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.
Return If a notification was received (including notifications that were already pending when xTaskNotifyWait
was called) then pdPASS is returned. Otherwise pdFAIL is returned.
Parameters
• 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 con-
figTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyWait() does not have this parameter
and always waits for notifications on index 0.
• 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.
• ulBitsToClearOnExit: If a notification is pending or received before the calling task ex-
its 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 ul-
BitsToClearOnExit 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 in-
cluded) 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).
• 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.
• 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.
void vTaskGenericNotifyGiveFromISR(TaskHandle_t
A version of xTaskNotifyGiveIndexed() that can be called from an interrupt service routine (ISR).
See https://www.FreeRTOS.org/RTOS-task-notifications.html
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 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.
Espressif Systems
xTaskToNotify, UBaseType_t uxIndexToNo-
tify, BaseType_t *pxHigherPriorityTaskWoken)
875
Submit Document Feedback
for more details.
Release v4.4