xTaskNotifyWait / xTaskNotifyWaitIndexed
[RTOS 任务通知 API]

task.h

 BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry,
                             uint32_t ulBitsToClearOnExit,
                             uint32_t *pulNotificationValue,
                             TickType_t xTicksToWait );


 BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, 
                                    uint32_t ulBitsToClearOnEntry, 
                                    uint32_t ulBitsToClearOnExit, 
                                    uint32_t *pulNotificationValue, 
                                    TickType_t xTicksToWait );

[如果你使用 RTOS 任务通知来实现二进制或计数 信号量类型行为，请使用更简单的 ulTaskNotifyTake() API 函数， 而不要使用 xTaskNotifyWait()]

每个任务都有一组“任务通知” （或仅“通知” ），每个 通知都包含状态和一个 32 位值。 直达任务通知是直接发送至任务的事件， 可以取消阻塞接收任务，并 可以选择通过多种方式更新接收任务的某个通知值。 例如，通知可覆盖接收任务的一个通知值，或仅设置 接收任务的一个通知值中的一位或多位。

xTaskNotifyWait() 会等待调用任务接收通知，并有可选的超时。 如果等待的通知到达时，相关的接收 RTOS 任务已被阻塞且正在等待通知，则 接收 RTOS 任务将解除阻塞，通知也将清除。

注意：数组中每个通知都独立运行——在数组中的一个通知上一次只能阻塞一个任务，并且该任务不会被发送到任何其他数组索引的通知取消阻塞。

xTaskNotifyWait() 和 xTaskNotifyWaitIndexed() 是等效的宏，它们唯一的区别 是 xTaskNotifyWaitIndexed() 可以在数组内的任何任务通知上运行， 而 xTaskNotifyWait() 始终在数组索引 0 处的任务通知上运行。

xTaskNotifyGive() 不能从中断服务程序调用。 使用 vTaskNotifyGiveFromISR() 代替。

configUSE_TASK_NOTIFICATIONS 必须在 FreeRTOSConfig.h 中设置为 1（或保留为未定义）才能使用这些宏。 常量 configTASK_NOTIFICATION_ARRAY_ENTRIES 设置 任务通知的每个任务数组中的索引数量。

向后兼容性信息：
在 FreeRTOS V10.4.0 之前，每个任务有一个单一的“通知值”，且 所有任务通知 API 函数都在该值上运行。用通知值的数组 更换单个通知值需要 新的 API 函数集，该函数集应能在数组内处理 特定通知。 xTaskNotifyWait() 是原始 API 函数，并 通过始终在数组内索引 0 处的通知值上运行来保持 向后兼容。调用 xTaskNotifyWait() 等于调用 xTaskNotifyWaitIndexed()，其中 uxIndexToWaitOn 参数设置为 0。

参数：

uxIndexToWaitOn	调用任务的数组中通知值的索引， 调用任务将在该通知值上等待接收 通知。 uxIndexToWaitOn 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。 xTaskNotifyWait() 没有此参数，总是在索引 0 处等待通知。
ulBitsToClearOnEntry	在 xTaskNotifyWait() 函数入口， ulBitsToClearOnEntry 中设置的任何位都将在调用 RTOS 任务通知值中 被清除（在任务等待新通知之前）， 前提是在调用 xTaskNotifyWait() 时通知尚未 挂起。 例如，如果 ulBitsToClearOnEntry 为 0x01， 则任务通知值的位 0 将在函数入口 被清除。 将 ulBitsToClearOnEntry 设置为 0xffffffff (ULONG_MAX) 将 清除任务通知值中的所有位，有效 将值清除为 0。
ulBitsToClearOnExit	在 xTaskNotifyWait() 函数退出之前， ulBitsToClearOnExit 中设置的任何位都将在调用 RTOS 任务通知值中 被清除，前提是接收到通知。 在 RTOS 任务通知值保存到 *pulNotificationValue 中 之后清除位 （请参阅下面的 pulNotificationValue 的说明）。 例如，如果 ulBitsToClearOnExit 为 0x03，则位 0 和 位 1 将在函数退出之前 清除。 将 ulBitsToClearOnExit 设置为 0xffffffff (ULONG_MAX) 将 清除任务通知值中的所有位，有效 将值清除为 0。
pulNotificationValue	用于传出 RTOS 任务的通知值。 在由于 ulBitsToClearOnExit 的设置清除任何位之前，复制到 *pulNotificationValue 的值是 RTOS 任务的 通知值 。 如果不需要通知值，则设置 pulNotificationValue 为 NULL。
xTicksToWait	在阻塞状态下等待接收通知的最长时间， 前提是在调用 xTaskNotifyWait() 时通知尚未 挂起。 处于阻塞状态的 RTOS 任务不会消耗 任何 CPU 时间。 时间以 RTOS tick 周期为单位。 宏 pdMS_TO_TICKS() 可以 将以毫秒为单位的时间 转换为以 tick 为单位的时间。

返回：

在调用 xTaskNotifyWait() 时，如果收到通知， 或通知已经挂起，则返回 pdTRUE。

如果调用 xTaskNotifyWait() 在收到通知之前超时， 则返回 pdFALSE。

用法示例：

[更多示例来自主 RTOS 任务通知页面]

/* This task shows bits within the RTOS task notification value being used to pass

different events to the task in the same way that flags in an event group might

be used for the same purpose. */

void vAnEventProcessingTask( void *pvParameters )

{

uint32_t ulNotifiedValue;



    for( ;; )

    {

        /* Block indefinitely (without a timeout, so no need to check the function's

        return value) to wait for a notification.



        Bits in this RTOS task's notification value are set by the notifying

        tasks and interrupts to indicate which events have occurred. */

        xTaskNotifyWaitIndexed( 0,         /* Wait for 0th notification. */

                                0x00,      /* Don't clear any notification bits on entry. */

                                ULONG_MAX, /* Reset the notification value to 0 on exit. */

                                &ulNotifiedValue, /* Notified value pass out in

                                                     ulNotifiedValue. */

                                portMAX_DELAY );  /* Block indefinitely. */



        /* Process any events that have been latched in the notified value. */



        if( ( ulNotifiedValue & 0x01 ) != 0 )

        {

            /* Bit 0 was set - process whichever event is represented by bit 0. */

            prvProcessBit0Event();

        }



        if( ( ulNotifiedValue & 0x02 ) != 0 )

        {

            /* Bit 1 was set - process whichever event is represented by bit 1. */

            prvProcessBit1Event();

        }



        if( ( ulNotifiedValue & 0x04 ) != 0 )

        {

            /* Bit 2 was set - process whichever event is represented by bit 2. */

            prvProcessBit2Event();

        }



        /* Etc. */

    }

}