Quality RTOS & Embedded Software


ulTaskNotifyValueClear / ulTaskNotifyValueClearIndexed
[RTOS Task Notification API]


uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, 
                                 uint32_t ulBitsToClear );

uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear );
Each RTOS task has an array of task notifications. Each task notification has a notification state that can be either ‘pending’ or ‘not pending’, and a 32-bit notification value.

ulTaskNotifyValueClear() clears the bits specified by the ulBitsToClear bit mask in the notification value at array index uxIndexToClear of the task referenced by xTask.

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

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.

xTask The handle of the RTOS task that will have bits in its notification value cleared. Set xTask to NULL to clear bits in the notification value of the calling task.

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.

uxIndexToClear The index within the target task’s array of notification values in which to clear the bits. uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES. ulTaskNotifyValueClear() does not have this parameter and always clears bits in the notification value at index 0.
ulBitsToClear Bit mask of the bits to clear in the notification value of xTask. Set a bit to 1 to clear the corresponding bits in the task’s notification value. Set ulBitsToClear to 0xffffffff (UINT_MAX on 32-bit architectures) to clear the notification value to 0. Set ulBitsToClear to 0 to query the task’s notification value without clearing any bits.
The value of the target task’s notification value before the bits specified by ulBitsToClear were cleared.
Example usage:


unsigned long ulNotification, ulMessageReceivedMask;

/* Clear any message received events. */
ulMessageReceivedMask = 1u << MESSAGE_RECEIVED_BIT;
ulTaskNotifyValueClear( ulMessageReceivedMask );

/* Send a message that expects a response. */

/* Block this task until it has another pending notification. In this example,
the task only ever uses the MESSAGE_RECEIVED_BIT of its notification value,
so the next event can only ever be on message received. */

xTaskNotifyWait( 0u, /* Don’t clear any notification bits on entry. */
0u, /* Don’t clear any notification bits on exit. */

/* If there wasn’t a timeout, then the only possible event was received.
In this example, that is the MESSAGE_RECEIVED_EVENT. */

if( ulNotification == 0u )
/* Handle the response timeout. */
else if( ulNotification == ulMessageReceivedMask )
/* Process the response event. */
ulTaskNotifyValueClear( ulMessageReceivedMask );
/* The example task should only ever receive MESSAGE_RECEIVED_EVENTS. */

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