xTaskNotify / xTaskNotifyIndexed
[RTOS 任务通知 API]

task.h

 BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify,
                         uint32_t ulValue,
                         eNotifyAction eAction );


 BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, 
                                UBaseType_t uxIndexToNotify, 
                                uint32_t ulValue, 
                                eNotifyAction eAction );

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

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

xTaskNotify() 用于将事件 直接发送到 RTOS 任务并可能取消该任务的阻塞状态，还可选择 以下列方式更新接收任务的通知值：

• 将 32 位数字写入通知值
• 添加一个（递增）通知值
• 设置通知值中的一个或多个位
• 保持通知值不变

xTaskNotify() 和 xTaskNotifyIndexed() 是等效的函数 - 唯一的区别 是 xTaskNotifyIndexed() 可以对数组内的任何任务通知进行操作， 而 xTaskNotify() 始终对数组索引 0 处的任务通知进行操作。

不得从中断服务例程 (ISR) 调用此函数。 使用 xTaskNotifyFromISR() 代替。

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

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

参数：

xTaskToNotify	正在通知的 RTOS 任务的句柄。 这是目标任务。 要获取任务句柄， xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用返回值创建任务 xTaskCreateStatic() 并存储该值，或在 调用 xTaskGetHandle() 中使用任务的名称。 当前执行的 RTOS 任务的句柄通过以下方式 由 xTaskGetCurrentTaskHandle() API 函数返回。
uxIndexToNotify	目标任务通知值数组中的索引， 通知值将发送给该索引。 uxIndexToNotify 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。 xTaskNotify() 没有此参数，并且始终向索引 0 发送通知。
ulValue	用于更新目标任务的通知值。 请参阅下面 eAction 参数的说明。
eAction	一种枚举类型，可以采用 下表中记录的值之一来执行相关操作。

返回：

除了 eAction 被设置为 eSetValueWithoutOverwrite 且目标任务的通知值 因目标任务已有挂起的通知而无法更新之外， 在所有情况下均返回 pdPASS。

用法示例：

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

/* Set bit 8 in the 0th notification value of the task referenced by 

xTask1Handle. */

xTaskNotifyIndexed( xTask1Handle, 0, ( 1UL << 8UL ), eSetBits );



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

}