Quality RTOS & Embedded Software


[RTOS Task Notification API]


uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, 
                                 uint32_t ulBitsToClear );
Clears the bits specified by the ulBitsToClear bit mask in the notification value of the task referenced by xTask.

configUSE_TASK_NOTIFICATIONS must be set to 1 or left undefined in FreeRTOSConfig.h for ulTaskNotifyValueClear() to be available.

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.

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:
    #define TICKS_UNTIL_TIMEOUT  100

    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.  */
                     TICKS_UNTIL_TIMEOUT );

    /* 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.