1-xTaskNotifyGive / xTaskNotifyGiveIndexed

task.h

 BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );

 BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, 
                                    UBaseType_t uxIndexToNotify );

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

当任务通知用作轻量级且更快的二进制或计数信号量替代方案时，可以使用宏 xTaskNotifyGive ()。 FreeRTOS 信号用通过使用 xSemaphoreGive () API 函数给出，而 xTaskNotifyGive () 与其等效，使用接收 RTOS 任务的一个通知值代替信号量。

xTaskNotifyGive () 和 xTaskNotifyGiveIndexed () 是等效宏——唯一的区别是 xTaskNotifyGiveIndexed () 可以在始终在数组内任何任务通知上操作，而 xTaskNotifyGive () 始终在数组索引 0 处的任务通知上运行。

当任务通知值用作二进制或等效计数信号量时，则被通知的任务应等待使用 ulTaskNotifyTake() API 函数的通知，而不是 xTaskNotifyWait() API 函数。

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

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

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

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

1.1 参数：

xTaskToNotify 正被通知的 RTOS 任务的句柄，且该任务的通知值正在递增。
要获取任务句柄，请使用 xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用返回值创建任务 xTaskCreateStatic() 并存储该值，或在 xTaskGetHandle() 调用中使用任务的名称。

当前执行的 RTOS 任务的句柄通过以下方式由 xTaskGetCurrentTaskHandle() API 函数返回。

uxIndexToNotify 目标任务通知值数组中的索引，通知值将发送给该索引。
uxIndexToNotify 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。 xTaskNotifyGive () 没有此参数，并且总是向索引 0 发送通知。

1.2 Returns:

xTaskNotifyGiveIndexed () 是用 eAction 参数调用 xTaskNotifyIndexed() 的宏， eAction 参数设置为 eIncrement，因此所有调用都返回 pdPASS。

1.3 用法示例：

/* main()创建的两个任务的原型。*/
static void prvTask1( void *pvParameters );
static void prvTask2( void *pvParameters );

/*main()创建的任务句柄。 */
static TaskHandle_t xTask1 = NULL, xTask2 = NULL;

/* 创建两个相互来回发送通知的任务，然后启动RTOS调度器。 */
void main( void )
{
    xTaskCreate( prvTask1, "Task1", 200, NULL, tskIDLE_PRIORITY, &xTask1 );
    xTaskCreate( prvTask2, "Task2", 200, NULL, tskIDLE_PRIORITY, &xTask2 );
    vTaskStartScheduler();
}
/*-----------------------------------------------------------*/

/* prvTask1()使用API的“索引”版本。*/
static void prvTask1( void *pvParameters )
{
    for( ;; )
    {
        /* 向prvTask2()发送通知，使其脱离阻塞状态。 */
        xTaskNotifyGiveIndexed( xTask2, 0 );

        /* 阻塞等待prvTask2()通知此任务。*/
        ulTaskNotifyTakeIndexed( 0, pdTRUE, portMAX_DELAY );
    }
}
/*-----------------------------------------------------------*/

/* prvTask2()使用API的原始版本(没有'Indexed')。 */
static void prvTask2( void *pvParameters )
{
    for( ;; )
    {
        /* 阻塞等待prvTask1()通知此任务。 */
        ulTaskNotifyTake( pdTRUE, portMAX_DELAY );

        /* 向prvTask1()发送通知，使其脱离阻塞状态。*/
        xTaskNotifyGive( xTask1 );
    }
}

2-vTaskNotifyGiveFromISR / vTaskNotifyGiveIndexedFromISR

task.h

 void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify,
                              BaseType_t *pxHigherPriorityTaskWoken );

 void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, 
                                     UBaseType_t uxIndexToNotify, 
                                     BaseType_t *pxHigherPriorityTaskWoken );

可在中断服务程序 (ISR) 中使用的 xTaskNotifyGive() 和 xTaskNotifyGiveIndexed() 的版本。请参阅文档页面，以获取关于 API 函数 xTaskNotifyGive() 的操作描述和必要的配置参数，以及向后兼容性信息。

2.1参数：

当前执行的 RTOS 任务的句柄通过以下方式由 xTaskGetCurrentTaskHandle() API 函数返回。

uxIndexToNotify 目标任务通知值数组中的索引，通知值将发送给该索引。uxIndexToNotify 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。xTaskNotifyGiveFromISR() 不具有此参数，并且始终将通知发送到索引 0。

pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken 必须初始化为 0。
如果发送通知导致任务解除阻塞，并且被阻塞任务的优先级高于当前运行的任务，vTaskNotifyGiveFromISR() 会将 *pxHigherPriorityTaskWoken 设 xTaskNotifyFromISR() 会将 *pxHigherPriorityTaskWoken 。

如果 vTaskNotifyGiveFromISR() 将此值设置为 pdTRUE ，则应在中断退出之前请求上下文切换。

pxHigherPriorityTaskWoken 为可选参数，且可设置为 NULL。

2.2 用法示例：

/* 这是一个通用外设驱动程序中传输函数的例子。RTOS任务调用传输函数，然后在阻塞状态下等待(因此不使用CPU时间)，直到它被通知传输完成。传输由DMA执行，DMA端中断用于通知任务。 */

static TaskHandle_t xTaskToNotify = NULL;

/* 外设驱动的传输功能。 */
void StartTransmission( uint8_t *pcData, size_t xDataLength )
{
    /* 此时，xTaskToNotify应该为NULL，因为没有正在进行的传输。如果需要，可以使用互斥来保护对外围设备的访问。 */
    configASSERT( xTaskToNotify == NULL );

    /* 存储调用任务的句柄。 */
    xTaskToNotify = xTaskGetCurrentTaskHandle();

    /*启动传输——传输完成时产生中断。*/
    vStartTransmit( pcData, xDatalength );
}
/*-----------------------------------------------------------*/

/* 结束中断传输 */
void vTransmitEndISR( void )
{
BaseType_t xHigherPriorityTaskWoken = pdFALSE;

    /*时xTaskToNotify不应该为NULL，因为传输正在进行中。*/
    configASSERT( xTaskToNotify != NULL );

    /*通知任务传输完成。*/
    vTaskNotifyGiveIndexedFromISR( xTaskToNotify, 0, &xHigherPriorityTaskWoken );

    /* 没有正在进行的传输，所以没有要通知的任务。 */
    xTaskToNotify = NULL;

    /* 如果xhigherprioritytaskkoken现在被设置为pdTRUE，那么应该执行上下文切换，以确保中断直接返回到最高优先级的任务。用于此目的的宏依赖于正在使用的端口，可以称为portEND_SWITCHING_ISR()。 */
    portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
/*-----------------------------------------------------------*/

/* 启动传输的任务，然后进入阻塞状态(因此不消耗任何CPU时间)，等待传输完成。*/
void vAFunctionCalledFromATask( uint8_t ucDataToTransmit, size_t xDataLength )
{
uint32_t ulNotificationValue;
const TickType_t xMaxBlockTime = pdMS_TO_TICKS( 200 );

    /* 通过调用上面所示的函数来启动传输。 */
    StartTransmission( ucDataToTransmit, xDataLength );

    /* 等待传输完成。 */
    ulNotificationValue = ulTaskNotifyTakeIndexed( 0, pdFALSE, xMaxBlockTime );

    if( ulNotificationValue == 1 )
    {
        /* 传输结束。 */
    }
    else
    {
        /* 对ulTaskNotifyTake()的调用超时。 */
    }
}

3-ulTaskNotifyTake / ulTaskNotifyTakeIndexed

task.h

 uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit,
                            TickType_t xTicksToWait );
 
 uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, 
                                   BaseType_t xClearCountOnExit, 
                                   TickType_t xTicksToWait );

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

ulTaskNotifyTake() 是一个宏，在任务通知被用作更快、更轻的二进制或计数信号量替代时使用。使用 xSemaphoreTake() API 函数获取 FreeRTOS 信号量，ulTaskNotifyTake() 是使用通知值代替信号量的等效宏。

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

当任务使用通知值作为二进制或计数信号量时，其他任务和中断应使用 xTaskNotifyGive() 宏，或 eAction 参数设置为 eIncrement 的 xTaskNotify() 函数（二者等效）。

ulTaskNotifyTake() 可以在退出时清除任务的通知值为 0，在这种情况下，通知值起到二进制信号量的作用；或在退出时递减任务的通知值，在这种情况下，通知值更像是计数信号量。

RTOS 任务可以使用 ulTaskNotifyTake() [可选]进入阻塞状态以等待任务的通知值。任务处于阻塞状态时不消耗任何 CPU 时间。

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

然而当通知被挂起时，xTaskNotifyWait() 将返回，当任务的通知值不为 0 时，ulTaskNotifyTake() 将返回，并在返回之前递减任务的通知值。

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

3.1 参数：

uxIndexToWaitOn 调用任务的数组中通知值的索引，调用任务将在该通知值上等待通知变成非零。uxIndexToWaitOn 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。

xTaskNotifyTake() 没有此参数，总是在索引 0 处等待通知。

xClearCountOnExit 如果收到 RTOS 任务通知且 xClearCountOnExit 设置为 pdFALSE，则 RTOS 任务的通知值在 ulTaskNotifyTake() 退出之前递减。这等同于通过成功调用 xSemaphoreTake() 而递减计数信号量的值。
如果收到 RTOS 任务通知且 xClearCountOnExit 设置为 pdTRUE，则 RTOS 任务的通知值在 ulTaskNotifyTake() 退出之前重设为 0。这等同于在成功调用 xSemaphoreTake() 后将二进制信号量的值保留为 0 （或为空，或为“不可用” ）。

xTicksToWait 在阻塞状态下等待接收通知的最长时间，如果通知在 ulTaskNotifyTake() 被调用时尚未挂起。
处于阻塞状态的 RTOS 任务不会消耗任何 CPU 时间。

时间以 RTOS tick 周期为单位。宏 pdMS_TO_TICKS() 可以将以毫秒为单位的时间转换成以 tick 为单位的时间。

3.2 Returns:

被递减或清楚之前的任务通知值的值（请参阅 xClearCountOnExit 的说明）。

3.3 用法示例：

/*中断处理程序。中断处理程序不执行任何处理，而是解阻塞一个高优先级的任务，在这个任务中，产生中断的事件正在被处理。如果任务的优先级足够高，那么中断将直接返回到该任务(因此它将中断一个任务，但返回到另一个任务)，因此处理将在时间上连续发生——就像所有的处理都在中断处理程序本身中完成一样。 */
void vANInterruptHandler( void )
{
BaseType_t xHigherPriorityTaskWoken;

    /* 中断清除 */
    prvClearInterruptSource();

    /*xhigherprioritytaskkoken必须初始化为pdFALSE。如果调用vTaskNotifyGiveFromISR()解除阻塞处理任务，并且处理任务的优先级高于当前运行任务的优先级，那么xhigherprioritytaskkoken将自动被设置为pdTRUE。
 */
    xHigherPriorityTaskWoken = pdFALSE;

    /*解除处理任务的阻塞，以便该任务可以执行中断所需的任何处理。xHandlingTask是任务的句柄，是在创建任务时获得的。 */
    vTaskNotifyGiveIndexedFromISR( xHandlingTask, 0, &xHigherPriorityTaskWoken );

    /* 如果xhigherprioritytaskkoken现在设置为pdTRUE，则强制上下文切换。用于完成此任务的宏依赖于端口，可以称为portEND_SWITCHING_ISR。 */
    portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
/*-----------------------------------------------------------*/

/*一个阻塞等待通知外设需要服务的任务，每次通知时处理外设中所有挂起的事件。*/
void vHandlingTask( void *pvParameters )
{
BaseType_t xEvent;

    for( ;; )
    {
        /*无限期地阻塞(没有超时，因此不需要检查函数的返回值)以等待通知。在这里，RTOS任务通知被用作二进制信号量，因此退出时通知值被清除为零。注意!真实的应用程序不应该无限期地阻塞，而是偶尔超时，以处理可能阻止中断发送更多通知的错误条件。

 */
        ulTaskNotifyTakeIndexed( 0,               /*第0个通知*/
                                 pdTRUE,          /* 退出前清除通知值。*/
                                 portMAX_DELAY ); /* 阻塞延时 */

        /* RTOS任务通知被用作二进制(而不是计数)信号量，因此只有在外围设备中所有挂起的事件都处理完毕后才返回等待进一步的通知。 */
        do
        {
            xEvent = xQueryPeripheral();

            if( xEvent != NO_MORE_EVENTS )
            {
                vProcessPeripheralEvent( xEvent );
            }

        } while( xEvent != NO_MORE_EVENTS );
    }
}

4-xTaskNotify / xTaskNotifyIndexed

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。

4.1参数：

xTaskToNotify 正在通知的 RTOS 任务的句柄。这是目标任务。要获取任务句柄， xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用返回值创建任务 xTaskCreateStatic() 并存储该值，或在 xTaskGetHandle() 调用中使用任务的名称。

当前执行的 RTOS 任务的句柄通过以下方式由 xTaskGetCurrentTaskHandle() API 函数返回。

uxIndexToNotify 目标任务通知值数组中的索引，通知值将发送给该索引。uxIndexToNotify 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。

xTaskNotify() 没有此参数，并且始终向索引 0 发送通知。

ulValue 用于更新目标任务的通知值。请参阅下面 eAction 参数的说明。
eAction 一种枚举类型，可以采用下表中记录的值之一来执行相关操作。

4.2 Returns:

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

4.3 用法示例：

/* 在xTask1Handle使用到的任务的第0个通知值中设置位8。*/
xTaskNotifyIndexed( xTask1Handle, 0, ( 1UL << 8UL ), eSetBits );

/* 向xTask2Handle引用的任务发送通知，可能会将任务从Blocked状态中移除，但不更新任务的通知值。*/
xTaskNotify( xTask2Handle, 0, eNoAction );

/* 将xTask3Handle引用的任务的通知值设置为0x50，即使任务没有读取它之前的通知值。 */
xTaskNotify( xTask3Handle, 0x50, eSetValueWithOverwrite );

/* 将xTask4Handle引用的任务的通知值设置为0xfff，但前提是这样做不会在任务获得通知值之前覆盖任务的现有通知值(通过调用xTaskNotifyWait()或ulTaskNotifyTake())。*/
if( xTaskNotify( xTask4Handle, 0xfff, eSetValueWithoutOverwrite ) == pdPASS )
{
    /* 更新任务通知的值 */
}
else
{
    /* 任务通知的值没有更新 */
}

5-xTaskNotifyAndQuery / xTaskNotifyAndQueryIndexed

task.h

 BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify,
                                 uint32_t ulValue,
                                 eNotifyAction eAction,
                                 uint32_t *pulPreviousNotifyValue );
 
 BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, 
                                        UBaseType_t uxIndexToNotify, 
                                        uint32_t ulValue, 
                                        eNotifyAction eAction, 
                                        uint32_t *pulPreviousNotifyValue );

xTaskNotifyAndQueryIndexed() 执行的操作与 xTaskNotifyIndexed() 相同，还会在附加的 pulPreviousNotifyValue 参数中返回目标任务的上一个通知值（调用函数时的通知值，而不是函数返回时的通知值）。

xTaskNotifyAndQuery() 执行的操作与 xTaskNotify() 相同，同样，还会在附加的 pulPreviousNotifyValue 参数中返回目标任务的上一个通知值（调用函数时的通知值，而不是函数返回时的通知值）。

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

5.1 参数：

xTaskToNotify 正在通知的 RTOS 任务的句柄。这是目标任务。
要获取任务句柄， xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用返回值创建任务 xTaskCreateStatic() 并存储该值，或在 xTaskGetHandle() 调用中使用任务的名称。

当前执行的 RTOS 任务的句柄通过以下方式由 xTaskGetCurrentTaskHandle() API 函数返回。

uxIndexToNotify 目标任务通知值数组中的索引，通知值将发送给该索引。
uxIndexToNotify 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。

ulValue 用于更新目标任务的通知值。请参阅下面 eAction 参数的说明。
eAction 一种枚举类型，可以采用下表中记录的值之一来执行相关操作。
pulPreviousNotifyValue 可用于在 xTaskNotifyAndQuery() 操作修改任何位之前传递目标任务的通知值。pulPreviousNotifyValue 是一个可选参数，如不需要，可设置为 NULL。如果未使用pulPreviousNotifyValue，则考虑使用 xTaskNotify() 来代替 xTaskNotifyAndQuery()。

5.2 Returns:

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

5.3 用法示例：

uint32_t ulPreviousValue;

/* 在xTask1Handle引用的任务的第0个通知值中设置位8。将任务之前的第0个通知值(比特8设置之前)存储在ulPreviousValue中。 */
xTaskNotifyAndQueryIndexed( xTask1Handle, 
                            0, 
                            ( 1UL << 8UL ), 
                            eSetBits, 
                            &ulPreviousValue );

/* 向xTask2Handle引用的任务发送通知，可能会将任务从Blocked状态中移除，但不更新任务的通知值。将任务通知值存储在ulPreviousValue中。 */
xTaskNotifyAndQuery( xTask2Handle, 0, eNoAction, &ulPreviousValue );

/*将xTask3Handle引用的任务的通知值设置为0x50，即使任务没有读取它之前的通知值。任务之前的通知值不感兴趣，因此最后一个参数被设置为NULL。 */
xTaskNotifyAndQuery( xTask3Handle, 0x50, eSetValueWithOverwrite,  NULL );

/* 将xTask4Handle引用的任务的通知值设置为0xfff，但前提是这样做不会在任务获得通知值之前覆盖任务的现有通知值(通过调用xTaskNotifyWait()或ulTaskNotifyTake())。任务之前的通知值保存在ulPreviousValue中。 */
if( xTaskNotifyAndQuery( xTask4Handle,
                         0xfff,
                         eSetValueWithoutOverwrite,
                         &ulPreviousValue ) == pdPASS )
{
    /*任务的通知值已经更新。*/
}
else
{
    /* 任务的通知值未更新。 */
}

6-xTaskNotifyAndQueryFromISR / xTaskNotifyAndQueryIndexedFromISR

task.h

 BaseType_t xTaskNotifyAndQueryFromISR( 
                      TaskHandle_t xTaskToNotify,
                      uint32_t ulValue,
                      eNotifyAction eAction,
                      uint32_t *pulPreviousNotifyValue,
                      BaseType_t *pxHigherPriorityTaskWoken );

 BaseType_t xTaskNotifyAndQueryIndexedFromISR( 
                      TaskHandle_t xTaskToNotify,
                      UBaseType_t uxIndexToNotify
                      uint32_t ulValue,
                      eNotifyAction eAction,
                      uint32_t *pulPreviousNotifyValue,
                      BaseType_t *pxHigherPriorityTaskWoken );

xTaskNotifyAndQueryIndexedFromISR() 执行的操作与xTaskNotifyIndexedFromISR() 执行的操作相同，此外，还会在附加的 pulPreviousNotifyValue 参数中返回目标任务的先前通知值 (函数被调用时的通知值，而不是函数返回时的通知值)。

xTaskNotifyAndQueryFromISR() 执行的操作与 xTaskNotifyFromISR() 执行的操作相同，此外还会在附加的 pulPreviousNotifyValue 参数中返回目标任务的先前通知值 (函数被调用时的通知值，而不是函数返回时的通知值)。

6.1 参数：

xTaskToNotify 正在通知的 RTOS 任务的句柄。这是目标任务。
要获取任务句柄， xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用返回值创建任务 xTaskCreateStatic() 并存储该值，或在 xTaskGetHandle() 调用中使用任务的名称。

当前执行的 RTOS 任务的句柄通过以下方式由 xTaskGetCurrentTaskHandle() API 函数返回。

uxIndexToNotify 目标任务通知值数组中的索引，通知值将发送给该索引。
uxIndexToNotify 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。

ulValue 用于更新目标任务的通知值。请参阅下面 eAction 参数的说明。
eAction 一种枚举类型，可以采用下表中记录的值之一来执行相关操作。
pulPreviousNotifyValue 可用于在xTaskNotifyAndQuery()操作修改任何位之前传递目标任务的通知值。
pulPreviousNotifyValue是一个可选参数，如不需要，可设置为 NULL。如果未使用 pulPreviousNotifyValue，则考虑使用 xTaskNotify() 来代替xTaskNotifyAndQuery()。

pxHigherPriorityTaskWoken * pxHigherPriorityTaskWoken必须初始化为pdFALSE (0)。
xTaskNotifyAndQueryFromISR ()将设置* pxHigherPriorityTaskWoken 如果发送通知导致一个任务解除阻塞，且解除阻塞的任务的优先级高于当前正在运行的任务，那么xTaskNotifyFromISR()将把*pxHigherPriorityTaskWoken设置为pdTRUE。

如果xTaskNotifyAndQueryFromISR()将该值设置为pdTRUE 那么应该在中断退出之前请求切换上下文。

pxHigherPriorityTaskWoken 为可选参数，且可设置为 NULL。

6.2 Returns:

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

6.3 用法示例：

void vAnISR( void )
{
/* 必须初始化为pdFALSE!*/
BaseType_t xHigherPriorityTaskWoken = pdFALSE. 
uint32_t ulPreviousValue;

    /* 在xTask1Handle引用的任务的第0个通知值中设置位8。将任务之前的第0个通知值(比特8设置之前)存储在lPreviousValue中。 */
    xTaskNotifyAndQueryIndexedFromISR( xTask1Handle,
                                       0,
                                       ( 1UL << 8UL ),
                                       eSetBits,
                                       &ulPreviousValue,
                                       &xHigherPriorityTaskWoken );

    /* 任务之前的通知值保存在ulPreviousValue中。 */

    /* 如果xTask1Handle引用的任务处于Blocked状态，等待通知，那么它现在将从Blocked状态移动到就绪状态。如果它的优先级高于当前正在执行的任务(被中断中断的任务)的优先级，那么xhigherprioritytaskkoken将被设置为pdTRUE，并且将该变量传递给portYIELD_FROM_ISR()调用将导致中断直接返回到未阻塞的任务。如果xhigherprioritytaskkoken仍然是pdFALSE，那么将它传递给portYIELD_FROM_ISR()将不起作用。 */

    portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}

7-xTaskNotifyFromISR / xTaskNotifyIndexedFromISR

task.h

 BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify,
                                uint32_t ulValue,
                                eNotifyAction eAction,
                                BaseType_t *pxHigherPriorityTaskWoken );

 BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, 
                                       UBaseType_t uxIndexToNotify, 
                                       uint32_t ulValue, 
                                       eNotifyAction eAction, 
                                       BaseType_t *pxHigherPriorityTaskWoken );

可从中断服务程序 (ISR) 中使用的 xTaskNotify() 和 xTaskNotifyIndexed() 版本。请参阅 xTaskNotify() API 函数的文档页面，了解有关其操作的描述和必要的配置参数，以及向后兼容性信息。

7.1 参数：

xTaskToNotify 正在通知的 RTOS 任务的句柄。这是目标任务。
要获取任务句柄， xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用返回值创建任务 xTaskCreateStatic() 并存储该值，或在调用 xTaskGetHandle() 中使用任务的名称。

当前执行的 RTOS 任务的句柄通过以下方式由 xTaskGetCurrentTaskHandle() API 函数返回。

uxIndexToNotify 目标任务通知值数组中的索引，通知值将发送给该索引。
uxIndexToNotify 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。

xTaskNotifyFromISR() 中没有此参数，总是向索引 0 发送通知。

ulValue 用于更新目标任务的通知值。请参阅下面 eAction 参数的说明。
eAction 一种枚举类型，可以采用下表中记录的值之一来执行相关操作。
pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken 必须初始化为 0。
如果发送通知导致某个任务解除阻塞，且被解除阻塞的任务的优先级高于当前运行的任务， xTaskNotifyFromISR() 会将 *pxHigherPriorityTaskWoken 设置为 pdTRUE。

如果 xTaskNotifyFromISR() 将此值设置为 pdTRUE，则应在中断退出之前请求上下文切换。请参阅以下示例。

pxHigherPriorityTaskWoken 为可选参数，且可设置为 NULL。

7.2 返回：

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

7.3 用法示例：

此示例演示了如何结合使用 xTaskNotifyFromISR() 和 eSetBits 操作。

/* 中断处理程序本身不执行任何处理。相反，它解除了一个高优先级的任务，在这个任务中，产生中断的事件被处理。如果任务的优先级足够高，那么中断将直接返回到该任务(因此它将中断一个任务，但返回到另一个任务)，因此处理将在时间上连续发生——就像所有的处理都在中断处理程序本身中完成一样。中断外设的状态通过RTOS任务发送给任务通知。 */
void vANInterruptHandler( void )
{
BaseType_t xHigherPriorityTaskWoken;
uint32_t ulStatusRegister;

    /* 读取每个中断源的中断状态寄存器(例如，可能是Rx位、Tx位、缓冲区溢出位等)。 */
    ulStatusRegister = ulReadPeripheralInterruptStatus();

    /* 清除中断。 */
    vClearPeripheralInterruptStatus( ulStatusRegister );

    /* xhigherprioritytaskkoken必须初始化为pdFALSE。如果调用xTaskNotifyFromISR()解除阻塞处理任务，并且处理任务的优先级高于当前运行任务的优先级，那么xhigherprioritytaskkoken将自动被设置为pdTRUE。 */
    xHigherPriorityTaskWoken = pdFALSE;

    /* 解除处理任务的阻塞，以便该任务可以执行中断所需的任何处理。xHandlingTask是任务的句柄，是在创建任务时获得的。处理任务的第0个通知值与中断状态按位or -确保已经设置的位不会被覆盖。 */
    xTaskNotifyIndexedFromISR( xHandlingTask,
                               0,
                               ulStatusRegister,
                               eSetBits,
                               &xHigherPriorityTaskWoken );

    /* 如果xhigherprioritytaskkoken现在设置为pdTRUE，则强制上下文切换。用于完成此任务的宏依赖于端口，可以称为portEND_SWITCHING_ISR。 */
    portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
/* ----------------------------------------------------------- */

/* 一个阻塞等待通知外设需要服务的任务，每次通知时处理外设中所有挂起的事件。*/
void vHandlingTask( void *pvParameters )
{
uint32_t ulInterruptStatus;

    for( ;; )
    {
        /* 无限期地阻塞(没有超时，因此不需要检查函数的返回值)以等待通知。注意!真实的应用程序不应该无限期地阻塞，而是偶尔超时，以处理可能阻止中断发送更多通知的错误条件。*/
        xTaskNotifyWaitIndexed( 0,                  /* 等待第0次通知*/
                                0x00,               /* 进入时不要清除任何位。 */
                                ULONG_MAX,          /* 在退出时清除所有位。 */
                                &ulInterruptStatus, /* 接收通知值。 */
                                portMAX_DELAY );    /* 阻塞延时*/

        /* 处理接收到的通知值中设置的任何位。这假设外设设置位1为Rx中断，位2为Tx中断，位3为缓冲区溢出中断。*/
        if( ( ulInterruptStatus & 0x01 ) != 0x00 )
        {
            prvProcessRxInterrupt();
        }

        if( ( ulInterruptStatus & 0x02 ) != 0x00 )
        {
            prvProcessTxInterrupt();
        }

        if( ( ulInterruptStatus & 0x04 ) != 0x00 )
        {
            prvClearBufferOverrun();
        }
    }
}

8-xTaskNotifyWait / xTaskNotifyWaitIndexed

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() 代替。

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

8.1 参数：

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 为单位的时间。

8.2 Returns:

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

8.3 用法示例：

/* 此任务显示了RTOS任务通知值中的位，用于将不同的事件传递给任务，其方式与事件组中的标志用于相同目的的方式相同。*/

void vAnEventProcessingTask( void *pvParameters )
{
uint32_t ulNotifiedValue;

    for( ;; )
    {
        /* 无限期地阻塞(没有超时，因此不需要检查函数的返回值)以等待通知。该RTOS任务的通知值中的位由通知任务和中断设置，以指示发生了哪些事件。 */
        xTaskNotifyWaitIndexed( 0,         /* 等待第0次通知。 */
                                0x00,      /* 不要在进入时清除任何通知位。 */
                                ULONG_MAX, /* 退出时将通知值重置为0。 */
                                &ulNotifiedValue, /* 通知值在ulnotiffiedvalue中传递。 */
                                portMAX_DELAY );  /* 阻塞延时 */

        /* 通知值在ulnotiffiedvalue中传递。 */

        if( ( ulNotifiedValue & 0x01 ) != 0 )
        {
            /* 位0被设置-处理由位0表示的任何事件。 */
            prvProcessBit0Event();
        }

        if( ( ulNotifiedValue & 0x02 ) != 0 )
        {
            /*位1被设置-处理由位1表示的任何事件。 */
            prvProcessBit1Event();
        }

        if( ( ulNotifiedValue & 0x04 ) != 0 )
        {
            /* 位2被设置-处理由位2表示的任何事件。*/
            prvProcessBit2Event();
        }

        /* Etc. */
    }
}

9-xTaskNotifyStateClear / xTaskNotifyStateClearIndexed

task.h

 BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );

 BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, 
                                          UBaseType_t uxIndexToClear );

每个 RTOS 任务都有一个任务通知数组。每条任务通知都有通知状态，可以是“挂起”或“非挂起” ，以及一个 32 位通知值。

如果通知被发送到通知数组中的索引，那么该索引处的通知被称为“待定” ，直到任务读取其通知值，或通过调用 xTaskNotifyStateClear () 将通知状态明确清除为“非挂起”为止。

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

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

9.1 参数：

xTask 将收到此通知的 RTOS 任务的句柄状态已清除。将 xTask 设置为 NULL 以清除通知调用任务的状态。
要获取任务句柄，请使用 xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用返回值创建任务 xTaskCreateStatic() 并存储该值，或在调用 xTaskGetHandle() 中使用任务的名称。

当前执行的 RTOS 任务的句柄通过以下方式由 xTaskGetCurrentTaskHandle() API 函数返回。

uxIndexToClear 待采取行动通知值索引内的目标任务数组。例如，将 uxIndexToClear 设置为 1 将清除数组内索引为 1 时的通知状态。
uxIndexToClear 必须小于configTASK_NOTIFICATION_ARRAY_ENTRIES的值。

ulTaskNotifyStateClear() 没有此参数，并且始终作用于索引 0 的通知上。

9.2 Returns:

如果 xTask 引用的任务有挂起的通知，则通知已清除，然后返回 pdTRUE。如果 xTask 引用的任务有待处理的通知，那么返回 pdFALSE。

9.3 用法示例：

/* 一个示例UART发送函数。该函数启动UART传输，然后等待传输完成的通知。传输完成通知从UART中断发送。在传输开始之前，将清除调用任务的通知状态，以确保在任务试图阻塞其通知状态之前，它不会碰巧已经挂起。*/
void vSerialPutString( const signed char * const pcStringToSend,
                       unsigned short usStringLength )
{
const TickType_t xMaxBlockTime = pdMS_TO_TICKS( 5000 );

    /*xSendingTask持有等待传输完成的任务句柄。如果xSendingTask为NULL，则表示传输没有进行。不要开始发送新的字符串，除非前一个字符串的传输已经完成。*/
    if( ( xSendingTask == NULL ) && ( usStringLength > 0 ) )
    {
        /*确保调用任务的第0个通知状态不是挂起的。 */
        xTaskNotifyStateClearIndexed( NULL, 0 );

        /*存储传输任务的句柄。这用于在传输完成后解除阻塞任务。 */
        xSendingTask = xTaskGetCurrentTaskHandle();

        /* 开始发送字符串-然后传输由中断控制。*/
        UARTSendString( pcStringToSend, usStringLength );

        /*在Blocked状态下等待(因此不使用任何CPU时间)，直到UART ISR向xSendingTask发送第0个通知，以便在传输完成时通知(并解除阻塞)任务。 */
        ulTaskNotifyTake( 0, pdTRUE, xMaxBlockTime );
    }
}

10-ulTaskNotifyValueClear / ulTaskNotifyValueClearIndexed

task.h  

uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, 
                                 uint32_t ulBitsToClear );

uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, 
                                        UBaseType_t uxIndexToClear,
                                        uint32_t ulBitsToClear );

每个 RTOS 任务都有一个任务通知数组。每条任务通知都有通知状态，可以是“挂起”或“非挂起” ，以及一个 32 位通知值。
ulTaskNotifyValueClearIndexed() 清除 xTask 引用的任务的数组索引 uxIndexToClear 的通知值中 ulBitsToClear 位掩码指定的位。

ulTaskNotifyValueClear() 和 ulTaskNotifyValueClearIndexed() 是等效的宏 - 唯一的区别是 ulTaskNotifyValueClearIndexed() 可以对数组中的任何任务通知进行操作，而 ulTaskNotifyValueClear() 始终在数组索引 0 处对任务通知进行操作。

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

10.1参数：

xTask 将清除其通知值中的位的 RTOS 任务的句柄。将 xTask 设置为 NULL 以清除调用任务的通知值中的位。
若要获取任务句柄，请使用 xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用 xTaskCreateStatic() 创建任务并存储返回值，或在调用 xTaskGetHandle() 时使用任务名称。

当前执行的 RTOS 任务的句柄由 xTaskGetCurrentTaskHandle() API 函数返回。

uxIndexToClear 目标任务的通知值数组中的索引，用于清除其中的位。 uxIndexToClear 必须小于 configTASK_NOTIFICATION_ARRAY_ENTRIES。 ulTaskNotifyValueClear() 没有此参数，并且始终清除索引 0 处的通知值中的位。
ulBitsToClear 要在 xTask 的通知值中清除的位的位掩码。将位设置为 1 可清除任务的通知值中的相应位。将 ulBitsToClear 设置为 0xffffffff（32 位架构上的 UINT_MAX）以将通知值清除为 0。将 ulBitsToClear 设置为 0 以查询任务的通知值，而不清除任何位。

10.2 Returns:

清除 ulBitsToClear 指定的位之前的目标任务的通知值。

10.3 用法示例：

#define MESSAGE_RECEIVED_BIT 8
#define TICKS_UNTIL_TIMEOUT  100

unsigned long ulNotification, ulMessageReceivedMask;

/* 清除所有的消息接收事件。 */
ulMessageReceivedMask = 1u << MESSAGE_RECEIVED_BIT;
ulTaskNotifyValueClear( ulMessageReceivedMask );

/*发送一条得到响应的消息。 */
send_message();

/* 阻塞此任务，直到它有另一个挂起的通知。在本例中，任务只使用其通知值的MESSAGE_RECEIVED_BIT，因此下一个事件只能是接收到的消息。*/
xTaskNotifyWait( 0u, /* 不要在进入时清除任何通知位。 */
                 0u, /* 退出时不要清除任何通知位。 */
                 &ulNotification,
                 TICKS_UNTIL_TIMEOUT );

/*如果没有超时，则接收到唯一可能的事件。在本例中，它就是MESSAGE_RECEIVED_EVENT。 */
if( ulNotification == 0u ) 
{
    /* 超时响应处理 */
    process_response_timeout();
} 
else if( ulNotification == ulMessageReceivedMask )
{
    /* 处理响应事件。 */
    process_response();
    ulTaskNotifyValueClear( ulMessageReceivedMask );
} 
else 
{
    /* 示例任务应该只接收MESSAGE_RECEIVED_EVENTS。*/
    process_error();
}