FreeRTOS api库函数之Task Notification(任务通知)

xTaskNotifyGive()
BaseType_t xTaskNotifyGive(TaskHandle_t xTaskToNotify);

每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 RTOS任务通知是直接发送到可以取消阻止接收任务的任务的事件,并且可选地更新接收任务的通知值。
xTaskNotifyGive()是一个宏,旨在将RTOS任务通知值用作轻量级和更快的二进制或计数信号量替代时使用。 FreeRTOS信号量是使用xSemaphoreGive()API函数给出的,xTaskNotifyGive()相当于使用接收RTOS任务的通知值。
当任务通知值被用作二进制或计数信号量等效时,被通知的任务应该使用ulTask​​NotifyTake()API函数而不是xTaskNotifyWait()API函数等待通知。
不得从中断服务例程调用xTaskNotifyGive()。请改用vTaskNotifyGiveFromISR()。
参数:
    xTaskToNotify 正在通知的RTOS任务的句柄,并使其通知值递增。
    要获取任务的句柄,请使用xTaskCreate()创建任务并使用pxCreatedTask参数,或使用xTaskCreateStatic()创建任务并存储返回的值,或者在调用xTaskGetHandle()时使用任务的名称。
    xTaskGetCurrentTaskHandle()API函数返回当前正在执行的RTOS任务的句柄。
返回:
    xTaskNotifyGive()是一个调用xTaskNotify()的宏,其eAction参数设置为eIncrement,导致所有调用返回pdPASS。

vTaskNotifyGiveFromISR()
void vTaskNotifyGiveFromISR(TaskHandle_t xTaskToNotify,BaseType_t * pxHigherPriorityTaskWoken);

可以从中断服务例程(ISR)调用的xTaskNotifyGive()版本。
每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 RTOS任务通知是直接发送到可以取消阻止接收任务的任务的事件,并且可选地更新接收任务的通知值。
vTaskNotifyGiveFromISR()是一个函数,旨在将RTOS任务通知值用作轻量级和更快的二进制或计数信号量替代时使用。 FreeRTOS信号量是使用xSemaphoreGiveFromISR()API函数从中断给出的,vTaskNotifyGiveFromISR()相当于使用接收RTOS任务的通知值。
当任务通知值被用作二进制或计数信号量等效时,被通知的任务应该使用ulTask​​NotifyTake()API函数而不是xTaskNotifyWait()API函数等待通知。
参数:
    xTaskToNotify 正在通知的RTOS任务的句柄,并使其通知值递增。
    要获取任务的句柄,请使用xTaskCreate()创建任务并使用pxCreatedTask参数,或使用xTaskCreateStatic()创建任务并存储返回的值,或者在调用xTaskGetHandle()时使用任务的名称。
    xTaskGetCurrentTaskHandle()API函数返回当前正在执行的RTOS任务的句柄。
    pxHigherPriorityTaskWoken * pxHigherPriorityTaskWoken必须初始化为0。
    如果发送通知导致任务解除阻塞,则vTaskNotifyGiveFromISR()会将* pxHigherPriorityTaskWoken设置为pdTRUE,并且未阻止的任务的优先级高于当前正在运行的任务。
    如果vTaskNotifyGiveFromISR()将此值设置为pdTRUE,则应在退出中断之前请求上下文切换。
    pxHigherPriorityTaskWoken是可选参数,可以设置为NULL。

ulTask​​NotifyTake()
uint32_t ulTask​​NotifyTake(BaseType_t xClearCountOnExit,TickType_t xTicksToWait);

每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 RTOS任务通知是直接发送到可以取消阻止接收任务的任务的事件,并且可选地更新接收任务的通知值。
ulTask​​NotifyTake()适用于将任务通知用作速度更快,重量更轻的二进制或计数信号量替代的情况。使用xSemaphoreTake()API函数获取FreeRTOS信号量,ulTask​​NotifyTake()相当于使用任务通知。
当任务将其通知值用作二进制或计数信号量时,其他任务和中断应使用xTaskNotifyGive()宏或xTaskNotify()函数向其发送通知,并将函数的eAction参数设置为eIncrement(两者等效) )。
ulTask​​NotifyTake()可以在退出时将任务的通知值清除为零,在这种情况下,通知值的作用类似于二进制信号量,或者在退出时减少任务的通知值,在这种情况下,通知值更像是计数信号量。
RTOS任务可以使用ulTask​​NotifyTake()来[可选]阻止等待任务的通知值为非零。任务在处于阻止状态时不消耗任何CPU时间。
当通知挂起时xTaskNotifyWait()将返回,当任务的通知值不为零时,ulTask​​NotifyTake()将返回,在返回之前递减任务的通知值。
参数:
    xClearCountOnExit 如果收到RTOS任务通知并且xClearCountOnExit设置为pdFALSE,则在ulTask​​NotifyTake()退出之前,RTOS任务的通知值将减少。这相当于通过成功调用xSemaphoreTake()递减计数信号量的值。
    如果收到RTOS任务通知并且xClearCountOnExit设置为pdTRUE,则在ulTask​​NotifyTake()退出之前,RTOS任务的通知值将重置为0。这相当于在成功调用xSemaphoreTake()之后二进制信号量保持为零(或为空或“不可用”)的值。
    xTicksToWait 在调用ulTask​​NotifyTake()时,如果通知尚未处于挂起状态,则在阻塞状态下等待接收通知的最长时间。
    当RTOS任务处于阻塞状态时,它不会占用任何CPU时间。
    时间在RTOS滴答期间指定。 pdMS_TO_TICKS()宏可用于将以毫秒为单位指定的时间转换为刻度中指定的时间。
返回:
    递减或清除任务的通知值之前的值

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

[如果您使用RTOS任务通知来实现二进制或计数信号量类型行为,那么使用更简单的xTaskNotifyGive()API函数而不是xTaskNotify()]
每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 xTaskNotify()用于直接向RTOS任务发送事件并可能取消阻止,并可选择通过以下方式之一更新接收任务的通知值:
    将32位数写入通知值
    添加一个(递增)通知值
    在通知值中设置一个或多个位
    保持通知值不变
不得从中断服务程序(ISR)调用此函数。请改用xTaskNotifyFromISR()。
参数:
    xTaskToNotify正在通知的RTOS任务的句柄。这是主题任务。
    要获取任务的句柄,请使用xTaskCreate()创建任务并使用pxCreatedTask参数,或使用xTaskCreateStatic()创建任务并存储返回的值,或者在调用xTaskGetHandle()时使用任务的名称。
    xTaskGetCurrentTaskHandle()API函数返回当前正在执行的RTOS任务的句柄。
    ulValue用于更新主题任务的通知值。请参阅下面的eAction参数说明。
    eAction一种枚举类型,可以采用下表中记录的值之一来执行相关操作。
执行eAction设置操作
eNoAction主题任务接收事件,但不更新其通知值。在这种情况下,不使用ulValue。
eSetBits主题任务的通知值将与ulValue按位OR运算。例如,如果ulValue设置为0x01,则位0将在主题任务的通知值中设置。同样,如果ulValue为0x04,则第2位将在主题任务的通知值中设置。通过这种方式,RTOS任务通知机制可以用作事件组的轻量级替代方案。
eIncrement主题任务的通知值将增加1,使对xTaskNotify()的调用等同于对xTaskNotifyGive()的调用。在这种情况下,不使用ulValue。
eSetValueWithOverwrite主题任务的通知值无条件设置为ulValue。通过这种方式,RTOS任务通知机制被用作xQueueOverwrite()的轻量级替代方案。
eSetValueWithoutOverwrite如果主题任务尚未有待通知,则其通知值将设置为ulValue。
如果主题任务已经有通知待处理,则其通知值不会更新,因为这样做会在使用之前覆盖之前的值。在这种情况下,对xTaskNotify()的调用失败并返回pdFALSE。
通过这种方式,RTOS任务通知机制被用作长度为1的队列上xQueueSend()的轻量级替代。
返回:
    除了将eAction设置为eSetValueWithoutOverwrite之外的所有情况都返回pdPASS,并且由于主题任务已经有通知待处理,因此无法更新主题任务的通知值。

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

[如果您使用RTOS任务通知来实现二进制或计数信号量类型行为,那么使用更简单的xTaskNotifyGive()API函数而不是xTaskNotifyAndQuery()。
xTaskNotifyAndQuery()类似于xTaskNotify(),但包含一个附加参数,其中返回主题任务的先前通知值。
每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 xTaskNotifyAndQuery()用于直接向RTOS任务发送事件并可能取消阻止,并可选择通过以下方式之一更新接收任务的通知值:
    将32位数写入通知值
    添加一个(递增)通知值
    在通知值中设置一个或多个位
    保持通知值不变
不得从中断服务程序(ISR)调用此函数。
参数:
    xTaskToNotify正在通知的RTOS任务的句柄。这是主题任务。
    要获取任务的句柄,请使用xTaskCreate()创建任务并使用pxCreatedTask参数,或使用xTaskCreateStatic()创建任务并存储返回的值,或者在调用xTaskGetHandle()时使用任务的名称。
    xTaskGetCurrentTaskHandle()API函数返回当前正在执行的RTOS任务的句柄。
    ulValue用于更新主题任务的通知值。请参阅下面的eAction参数说明。
    eAction一种枚举类型,可以采用下表中记录的值之一来执行相关操作。
    pulPreviousNotifyValue可用于在xTaskNotifyAndQuery()的操作修改任何位之前传递主题任务的通知值。
    pulPreviousNotifyValue是一个可选参数,如果不需要,可以设置为NULL。如果未使用pulPreviousNotifyValue,请考虑使用xTaskNotify()代替xTaskNotifyAndQuery()。
执行eAction设置操作
eNoAction主题任务接收事件,但不更新其通知值。在这种情况下,不使用ulValue。
eSetBits主题任务的通知值将与ulValue按位OR运算。例如,如果ulValue设置为0x01,则位0将在主题任务的通知值中设置。同样,如果ulValue为0x04,则第2位将在主题任务的通知值中设置。通过这种方式,RTOS任务通知机制可以用作事件组的轻量级替代方案。
eIncrement主题任务的通知值将增加1,使对xTaskNotify()的调用等同于对xTaskNotifyGive()的调用。在这种情况下,不使用ulValue。
eSetValueWithOverwrite主题任务的通知值无条件设置为ulValue。通过这种方式,RTOS任务通知机制被用作xQueueOverwrite()的轻量级替代方案。
eSetValueWithoutOverwrite如果主题任务尚未有待通知,则其通知值将设置为ulValue。
如果主题任务已经有通知待处理,则其通知值不会更新,因为这样做会在使用之前覆盖之前的值。在这种情况下,对xTaskNotify()的调用失败并返回pdFALSE。
通过这种方式,RTOS任务通知机制被用作长度为1的队列上xQueueSend()的轻量级替代。
返回:
    除了将eAction设置为eSetValueWithoutOverwrite之外的所有情况都返回pdPASS,并且由于主题任务已经有通知待处理,因此无法更新主题任务的通知值。

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

[如果您使用RTOS任务通知来实现二进制或计数信号量类型行为,则使用更简单的vTaskNotifyGiveFromISR()API函数而不是xTaskNotifyAndQueryFromISR()。
xTaskNotifyAndQuery()类似于xTaskNotify(),但包含一个附加参数,其中返回主题任务的先前通知值。 xTaskNotifyAndQueryFromISR()是xTaskNotifyAndQuery()的一个版本,可以从中断服务例程(ISR)调用。
每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 xTaskNotifyAndQueryFromISR()用于直接向RTOS任务发送事件并可能取消阻止,并可选择通过以下方式之一更新接收任务的通知值:
    将32位数写入通知值
    添加一个(递增)通知值
    在通知值中设置一个或多个位
    保持通知值不变
参数:
    xTaskToNotify正在通知的RTOS任务的句柄。这是主题任务。
    要获取任务的句柄,请使用xTaskCreate()创建任务并使用pxCreatedTask参数,或使用xTaskCreateStatic()创建任务并存储返回的值,或者在调用xTaskGetHandle()时使用任务的名称。
    xTaskGetCurrentTaskHandle()API函数返回当前正在执行的RTOS任务的句柄。
    ulValue用于更新主题任务的通知值。请参阅下面的eAction参数说明。
    eAction一种枚举类型,可以采用下表中记录的值之一来执行相关操作。
    pulPreviousNotifyValue可用于在xTaskNotifyAndQueryFromISR()的操作修改任何位之前传递主题任务的通知值。
    pulPreviousNotifyValue是一个可选参数,如果不需要,可以设置为NULL。如果未使用pulPreviousNotifyValue,则考虑使用xTaskNotify()代替xTaskNotifyAndQueryFromISR()。
    必须将pxHigherPriorityTaskWoken * pxHigherPriorityTaskWoken初始化为pdFALSE(0)。
    如果发送通知导致任务解除阻塞,则xTaskNotifyAndQueryFromISR()会将* pxHigherPriorityTaskWoken设置为pdTRUE,并且未阻止任务的优先级高于当前正在运行的任务。
    如果xTaskNotifyAndQueryFromISR()将此值设置为pdTRUE,则应在退出中断之前请求上下文切换。请参阅下面的示例。
    pxHigherPriorityTaskWoken是可选参数,可以设置为NULL。
执行eAction设置操作
eNoAction主题任务接收事件,但不更新其通知值。在这种情况下,不使用ulValue。
eSetBits主题任务的通知值将与ulValue按位OR运算。例如,如果ulValue设置为0x01,则位0将在主题任务的通知值中设置。同样,如果ulValue为0x04,则第2位将在主题任务的通知值中设置。通过这种方式,RTOS任务通知机制可以用作事件组的轻量级替代方案。
eIncrement主题任务的通知值将增加1,使对xTaskNotify()的调用等同于对xTaskNotifyGive()的调用。在这种情况下,不使用ulValue。
eSetValueWithOverwrite主题任务的通知值无条件设置为ulValue。通过这种方式,RTOS任务通知机制被用作xQueueOverwrite()的轻量级替代方案。
eSetValueWithoutOverwrite如果主题任务尚未有待通知,则其通知值将设置为ulValue。
如果主题任务已经有通知待处理,则其通知值不会更新,因为这样做会在使用之前覆盖之前的值。在这种情况下,对xTaskNotify()的调用失败并返回pdFALSE。
通过这种方式,RTOS任务通知机制被用作长度为1的队列上xQueueSend()的轻量级替代。
返回:
    除了将eAction设置为eSetValueWithoutOverwrite之外的所有情况都返回pdPASS,并且由于主题任务已经有通知待处理,因此无法更新主题任务的通知值。

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

[如果您使用RTOS任务通知来实现二进制或计数信号量类型行为,那么使用更简单的vTaskNotifyGiveFromISR()API函数而不是xTaskNotifyFromISR()]
可以从ISR调用的xTaskNotify()版本。
每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 xTaskNotifyFromISR()用于直接向RTOS任务发送事件并可能取消阻止,并可选择通过以下方式之一更新接收任务的通知值:
    将32位数写入通知值
    添加一个(递增)通知值
    在通知值中设置一个或多个位
    保持通知值不变
参数:
    xTaskToNotify正在通知的RTOS任务的句柄。这是主题任务。
    要获取任务的句柄,请使用xTaskCreate()创建任务并使用pxCreatedTask参数,或使用xTaskCreateStatic()创建任务并存储返回的值,或者在调用xTaskGetHandle()时使用任务的名称。
    xTaskGetCurrentTaskHandle()API函数返回当前正在执行的RTOS任务的句柄。
    ulValue用于更新主题任务的通知值。请参阅下面的eAction参数说明。
    eAction一种枚举类型,可以采用下表中记录的值之一来执行相关操作。
    pxHigherPriorityTaskWoken * pxHigherPriorityTaskWoken必须初始化为0。
    如果发送通知导致任务解除阻塞,则xTaskNotifyFromISR()将* pxHigherPriorityTaskWoken设置为pdTRUE,并且未阻止任务的优先级高于当前正在运行的任务。
    如果xTaskNotifyFromISR()将此值设置为pdTRUE,则应在退出中断之前请求上下文切换。请参阅下面的示例。
    pxHigherPriorityTaskWoken是可选参数,可以设置为NULL。
执行eAction设置操作
eNoAction主题任务接收事件,但不更新其通知值。在这种情况下,不使用ulValue。
eSetBits主题任务的通知值将与ulValue按位OR运算。例如,如果ulValue设置为0x01,则位0将在主题任务的通知值中设置。同样,如果ulValue为0x04,则第2位将在主题任务的通知值中设置。通过这种方式,RTOS任务通知机制可以用作事件组的轻量级替代方案。
eIncrement主题任务的通知值将增加1,使对xTaskNotifyFromISR()的调用等同于对vTaskNotifyGiveFromISR()的调用。在这种情况下,不使用ulValue。
eSetValueWithOverwrite主题任务的通知值无条件设置为ulValue。通过这种方式,RTOS任务通知机制被用作xQueueOverwrite()的轻量级替代方案。
eSetValueWithoutOverwrite如果主题任务尚未有待通知,则其通知值将设置为ulValue。
如果主题任务已经有通知待处理,则其通知值不会更新,因为这样做会在使用之前覆盖之前的值。在这种情况下,对xTaskNotify()的调用失败。
通过这种方式,RTOS任务通知机制被用作长度为1的队列上xQueueSend()的轻量级替代。
返回:
    除了将eAction设置为eSetValueWithoutOverwrite之外的所有情况都返回pdPASS,并且由于主题任务已经有通知待处理,因此无法更新主题任务的通知值。

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

[如果您使用RTOS任务通知来实现二进制或计数信号量类型行为,那么使用更简单的ulTask​​NotifyTake()API函数而不是xTaskNotifyWait()]
每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 RTOS任务通知是直接发送到可以解除阻塞接收任务的任务的事件,并且可选地以多种不同方式更新接收任务的通知值。例如,通知可以覆盖接收任务的通知值,或者仅在接收任务的通知值中设置一个或多个位。
xTaskNotifyWait()等待,并带有可选的超时,以便调用任务接收通知。
如果接收的RTOS任务已经被阻塞,等待一个人到达时发出通知,则接收的RTOS任务将从阻止状态中删除并清除通知。
参数:
    ulBitsToClearOnEntry在调用xTaskNotifyWait()时,如果调用xTaskNotifyWait(),则在调用RTOS任务的xTaskNotifyWait()函数的通知值时(在任务等待新通知之前),将清除ulBitsToClearOnEntry中设置的任何位。
    例如,如果ulBitsToClearOnEntry为0x01,则在进入函数时将清除任务通知值的第0位。
    将ulBitsToClearOnEntry设置为0xffffffff(ULONG_MAX)将清除任务通知值中的所有位,从而有效地将值清除为0。
    ulBitsToClearOnExit如果收到通知,则在xTaskNotifyWait()函数退出之前,将在调用RTOS任务的通知值中清除ulBitsToClearOnExit中设置的任何位。
    在RTOS任务的通知值保存在* pulNotificationValue中后,这些位被清除(请参阅下面的pulNotificationValue说明)。
    例如,如果ulBitsToClearOnExit为0x03,则在函数退出之前,将清除任务通知值的第0位和第1位。
    将ulBitsToClearOnExit设置为0xffffffff(ULONG_MAX)将清除任务通知值中的所有位,从而有效地将值清除为0。
    pulNotificationValue用于传递RTOS任务的通知值。复制到* pulNotificationValue的值是RTOS任务的通知值,因为ulBitsToClearOnExit设置清除了任何位之前的值。
    如果不需要通知值,则将pulNotificationValue设置为NULL。
    xTicksToWait在调用xTaskNotifyWait()时,如果通知尚未处于挂起状态,则在阻塞状态下等待接收通知的最长时间。
    当RTOS任务处于阻塞状态时,它不会占用任何CPU时间。
    时间在RTOS滴答期间指定。 pdMS_TO_TICKS()宏可用于将以毫秒为单位指定的时间转换为刻度中指定的时间。
返回:
    pdTRUE如果收到通知,或者在调用xTaskNotifyWait()时通知已经挂起。
    如果在收到通知之前对xTaskNotifyWait()的调用超时,则为pdFALSE。

xTaskNotifyStateClear()
BaseType_t xTaskNotifyStateClear(TaskHandle_t xTask);

每个RTOS任务都有一个32位通知值,在创建RTOS任务时初始化为零。 RTOS任务通知是直接发送到可以取消阻止接收任务的任务的事件,并且可选地更新接收任务的通知值。
如果任务处于阻止状态以在通知到达时等待通知,则任务立即退出阻止状态,并且通知不会保持挂起状态。如果任务在通知到达时没有等待通知,则通知将保持挂起,直到接收任务读取其通知值。
xTaskNotifyStateClear()用于清除(Pending to Not Pending)待处理通知,而接收任务首先不需要读取其通知值。
xTaskNotifyStateClear()不会更改通知值。
参数:
    xTask将清除其通知状态的RTOS任务的句柄。将xTask设置为NULL以清除调用任务的通知状态。
    要获取任务的句柄,请使用xTaskCreate()创建任务并使用pxCreatedTask参数,或使用xTaskCreateStatic()创建任务并存储返回的值,或者在调用xTaskGetHandle()时使用任务的名称。
    xTaskGetCurrentTaskHandle()API函数返回当前正在执行的RTOS任务的句柄。
返回:
    如果xTask引用的任务有挂起通知,并且通知已清除,则返回pdTRUE。如果xTask引用的任务没有挂起通知,则返回pdFALSE。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值