Quality RTOS & Embedded Software

KERNEL

xTaskNotifyGive / xTaskNotifyGiveIndexed
[RTOS Task Notification API]


task.h

 BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );

BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify );

Each task has an array of ‘task notifications’ (or just ‘notifications’), each of which has a state and a 32-bit value. A direct to task notification is an event sent directly to a task that can unblock the receiving task, and optionally update one of the receiving task’s notification values in a number of different ways. For example, a notification may overwrite one of the receiving task’s notification values, or just set one or more bits in one of the receiving task’s notification values.

xTaskNotifyGive() is a macro intended for use when a task notification is being used as a light weight and faster binary or counting semaphore alternative. FreeRTOS semaphores are given using the xSemaphoreGive() API function, xTaskNotifyGive() is the equivalent that uses one of the receiving RTOS task’s notification values in place of a semaphore.

xTaskNotifyGive() and xTaskNotifyGiveIndexed() are equivalent macros – the only difference being xTaskNotifyGiveIndexed() can operate on any task notification within the array and xTaskNotifyGive() always operates on the task notification at array index 0.

When a task notification value is being used as a binary or counting semaphore equivalent then the task being notified should wait for the notification using the ulTaskNotifyTake() API function rather than the xTaskNotifyWait() 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.

xTaskNotifyGive() must not be called from an interrupt service routine. Use vTaskNotifyGiveFromISR() instead.

configUSE_TASK_NOTIFICATIONS must set to 1 in FreeRTOSConfig.h (or be left undefined) for these macros to be available. The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in each task’s array of task notifications.

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.

Parameters:
xTaskToNotify   The handle of the RTOS task being notified, and having its notification value incremented.

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().

The handle of the currently executing RTOS task is returned by the xTaskGetCurrentTaskHandle() API function.

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.

Returns:
xTaskNotifyGiveIndexed() is a macro that calls xTaskNotifyIndexed() with the eAction parameter set to eIncrement, so all calls returning pdPASS.


Example usage:

[More examples are referenced from the main RTOS task notifications page]


/* Prototypes of the two tasks created by main(). */
static void prvTask1( void *pvParameters );
static void prvTask2( void *pvParameters );

/* Handles for the tasks create by main(). */
static TaskHandle_t xTask1 = NULL, xTask2 = NULL;

/* Create two tasks that send notifications back and forth to each other,
then start the RTOS scheduler. */

void main( void )
{
xTaskCreate( prvTask1, “Task1”, 200, NULL, tskIDLE_PRIORITY, &xTask1 );
xTaskCreate( prvTask2, “Task2”, 200, NULL, tskIDLE_PRIORITY, &xTask2 );
vTaskStartScheduler();
}
/*———————————————————–*/

/* prvTask1() uses the ‘indexed’ version of the API. */
static void prvTask1( void *pvParameters )
{
for( ;; )
{
/* Send notification to prvTask2(), bringing it out of the
Blocked state. */

xTaskNotifyGiveIndexed( xTask2, 0 );

/* Block to wait for prvTask2() to notify this task. */
ulTaskNotifyTakeIndexed( 0, pdTRUE, portMAX_DELAY );
}
}
/*———————————————————–*/

/* prvTask2() uses the original version of the API (without the
‘Indexed’). */

static void prvTask2( void *pvParameters )
{
for( ;; )
{
/* Block to wait for prvTask1() to notify this task. */
ulTaskNotifyTake( pdTRUE, portMAX_DELAY );

/* Send a notification to prvTask1(), bringing it out of the
Blocked state. */

xTaskNotifyGive( xTask1 );
}
}






Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.