Chapter 2. API Reference
ulTaskNotifyTakeIndexed() is intended for use when a task notification is used as a faster and lighter weight bi-
nary 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 the task’s notification value to be
non-zero. 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.
Return The task’s notification count before it is either cleared to zero or decremented (see the xClearCoun-
tOnExit parameter).
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 non-zero. uxIndexToWaitOn must be less than con-
figTASK_NOTIFICATION_ARRAY_ENTRIES. xTaskNotifyTake() does not have this parameter
and always waits for notifications on index 0.
• 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.
• 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.
BaseType_t xTaskGenericNotifyStateClear(TaskHandle_t xTask, UBaseType_t uxIndexTo-
Clear)
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 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.
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
Espressif Systems 877
Submit Document Feedback
Release v4.4
To Next Page
Loading...