Group that contains macros & functions for task notifications. More...

Collaboration diagram for Direct To Task Notifications:

Modules
	xTaskNotify

	xTaskNotifyWait

	xTaskNotifyGive

	ulTaskNotifyTake

	xTaskNotifyStateClear

Macros
#define	xTaskNotify(xTaskToNotify, ulValue, eAction) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL )
	Send an event directly to and potentially unblock an RTOS task, and optionally update one of the receiving task’s notification values. More...

#define	xTaskNotifyAndQuery(xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue) xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )
	Performs the same operation as xTaskNotify() with the addition that it also returns the target 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. More...

Functions
BaseType_t	xTaskGenericNotify (TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue) PRIVILEGED_FUNCTION

Detailed Description

Group that contains macros & functions for task notifications.

Macro Definition Documentation

◆ xTaskNotify

#define xTaskNotify	(	xTaskToNotify,
		ulValue,
		eAction
	)	xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), NULL )

#include <task.h>

Send an event directly to and potentially unblock an RTOS task, and optionally update one of the receiving task’s notification values.

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

Note: If you are using RTOS task notifications to implement binary or counting semaphore type behaviour then use the simpler xTaskNotifyGive() API function instead of xTaskNotify().

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.

xTaskNotify() is used to send an event directly to and potentially unblock an RTOS task, and optionally update one of the receiving task’s notification values in one of the following ways:

Write a 32-bit number to the notification value
Add one (increment) the notification value
Set one or more bits in the notification value
Leave the notification value unchanged

Note: This function must not be called from an interrupt service routine (ISR). Use xTaskNotifyFromISR() instead.

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().
ulValue	Data that can be sent with the notification. How the data is used depends on the value of the `eAction` parameter.
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.

Example Usage:

// Send a notification to the task referenced by xTask2Handle, potentially
// removing the task from the Blocked state, but without updating the task's
// notification value.
xTaskNotify( xTask2Handle, 0, eNoAction );
 
// Set the notification value of the task referenced by xTask3Handle to 0x50,
// even if the task had not read its previous notification value.
xTaskNotify( xTask3Handle, 0x50, eSetValueWithOverwrite );
 
// Set the notification value of the task referenced by xTask4Handle to 0xfff,
// but only if to do so would not overwrite the task's existing notification
// value before the task had obtained it (by a call to xTaskNotifyWait()
// or ulTaskNotifyTake()).
if( xTaskNotify( xTask4Handle, 0xfff, eSetValueWithoutOverwrite ) == pdPASS )
{
    // The task's notification value was updated.
}
else
{
    // The task's notification value was not updated.
}

◆ xTaskNotifyAndQuery

#define xTaskNotifyAndQuery	(	xTaskToNotify,
		ulValue,
		eAction,
		pulPreviousNotifyValue
	)	xTaskGenericNotify( ( xTaskToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) )

#include <task.h>

Performs the same operation as xTaskNotify() with the addition that it also returns the target 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.

Note: This function must not be called from an interrupt service routine (ISR). Use xTaskNotifyAndQueryFromISR() instead.

See also: http://www.FreeRTOS.org/RTOS-task-notifications.html

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().
ulValue	Data that can be sent with the notification. How the data is used depends on the value of the `eAction` parameter.
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`. xTaskNotifyAndQuery() always returns pdPASS in this case. eIncrement : The task's notification value is incremented. `ulValue` is not used and xTaskNotifyAndQuery() 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). xTaskNotifyAndQuery() 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 xTaskNotifyAndQuery() 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 xTaskNotifyAndQuery() 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.

Example Usage:

uint32_t ulPreviousValue;
 
// Send a notification to the task referenced by xTask2Handle, 
// potentially removing the task from the Blocked state, but without 
// updating the task's notification value.  Store the tasks notification 
// value in ulPreviousValue.
xTaskNotifyAndQuery( xTask2Handle, 0, eNoAction, &ulPreviousValue );
 
// Set the notification value of the task referenced by xTask3Handle 
// to 0x50, even if the task had not read its previous notification value. 
// The task's previous notification value is of no interest so the last 
// parameter is set to NULL.
xTaskNotifyAndQuery( xTask3Handle, 0x50, eSetValueWithOverwrite,  NULL );
 
// Set the notification value of the task referenced by xTask4Handle 
// to 0xfff,
// but only if to do so would not overwrite the task's existing notification
// value before the task had obtained it (by a call to xTaskNotifyWait()
// or ulTaskNotifyTake()).  The task's previous notification value is saved
// in ulPreviousValue.
if( xTaskNotifyAndQuery( xTask4Handle,
                         0xfff,
                         eSetValueWithoutOverwrite,
                         &ulPreviousValue ) == pdPASS )
{
    // The task's notification value was updated.
}
else
{
    // The task's notification value was not updated.
}

Function Documentation

◆ xTaskGenericNotify()

BaseType_t xTaskGenericNotify	(	TaskHandle_t	xTaskToNotify,
		uint32_t	ulValue,
		eNotifyAction	eAction,
		uint32_t *	pulPreviousNotificationValue
	)

#include <task.h>

Precondition: configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for this function to be available.

When configUSE_TASK_NOTIFICATIONS is set to one each task has its own private "notification value", which is a 32-bit unsigned integer (uint32_t).

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 the task's notification value. 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 xTaskNotifyWait() or ulTaskNotifyTake(). 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 xTaskNotifyWait() to [optionally] block to wait for a notification to be pending, or ulTaskNotifyTake() to [optionally] block to wait for its notification value to have a non-zero value. The task does not consume any CPU time while it is in the Blocked state.

See also: http://www.FreeRTOS.org/RTOS-task-notifications.html

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().
ulValue	Data that can be sent with the notification. How the data is used depends on the value of the `eAction` parameter.
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. xTaskGenericNotify() always returns pdPASS in this case. eIncrement : The task's notification value is incremented. `ulValue` is not used and xTaskGenericNotify() 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). xTaskGenericNotify() 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 xTaskGenericNotify() 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 xTaskGenericNotify() 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.

Returns: Dependent on the value of eAction. See the description of the eAction parameter.

Modules

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ xTaskNotify

◆ xTaskNotifyAndQuery

Function Documentation

◆ xTaskGenericNotify()