31 freertos任务通知-API函数

三十一、freertos任务通知-API函数
任务通知(任务消息邮箱 API 函数)

​ 要使用任务通知，必须将 FreeRTOSConfig.h 中的宏定义 configUSE_TASK_NOTIFICATIONS 设置为 1，默认是为 1 的， 所以任务通知是默认使能的。
使用如下 9 个函数可以实现 FreeRTOS 的任务消息邮箱：

xTaskNotifyGive()			发送通知，无通知值
vTaskNotifyGiveFromISR()	发送通知，无通知值
ulTaskNotifyTake()		等待通知，是为代替二进制信号量和计数信号量而专门设计的，和发送通知函数 xTaskNotifyGive()、 vTaskNotifyGiveFromISR()配合使用
xTaskNotify()				发送通知，带通知值
xTaskNotifyFromISR()		发送通知，带通知值
xTaskNotifyAndQuery()		发送通知，带通知值，并返回原通知值。
xTaskNotifyAndQueryFromISR() 发送通知，带通知值，并返回原通知值。
xTaskNotifyWait() 	全功能版的等待通知，可以根据不同的参数实现轻量级二进制信号量、计数信号量、事件组和长度为1的队列。
xTaskNotifyStateClear()	清除通知

---

一、发送任务通知的函数接口

xTaskNotifyGive() 、 
xTaskNotify() 、 
xTaskNotifyAndQuery() ， 都是以 xTaskGenericNotify()为原型

1. 任务发送通知函数 xTaskNotifyGive()

函 数 原 型：  
#define xTaskNotifyGive( xTaskToNotify )
			xTaskGenericNotify( ( xTaskToNotify ), ( 0 ), eIncrement, NULL )
功 能	：	 用于在任务中向指定任务发送任务通知，并更新对方的任务通知值（加 1 操作）
参 数	： 	 xTaskToNotify 接收通知的任务句柄， 并让其自身的任务通知值加 1。
返 回 值：	总是返回 pdPASS。

2. 在中断中向指定任务发送通知 vTaskNotifyGiveFromISR()

函数原型： void vTaskNotifyGiveFromISR(TaskHandle_t xTaskToNotify,
						BaseType_t *pxHigherPriorityTaskWoken);
功 能	：	用于在中断中向一个任务发送任务通知，并更新对方的任务通知值（加 1 操作）。含任务二值信号量，任务计数信号量。
参 数	：--xTaskToNotify 接收通知的任务句柄， 并让其自身的任务通知值加 1。
	   --pxHigherPriorityTaskWoken 保存中断退出前是否执行一次上下文切换。
返 回 值：	无。

3. 向指定的任务发送一个任务通知 xTaskNotify()

函数原型：  
 BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify,
								uint32_t ulValue,
								eNotifyAction eAction );
功 能	： 向指定的任务发送一个任务通知， 带有通知值并且用户可以指定通知值的发送方式。	 
参 数	： 
		--xTaskToNotify 需要接收通知的任务句柄。
		--ulValue 用于更新接收任务通知的任务通知值，具体如何更新由形参 eAction 决定。
		--eAction 任务通知值更新方式
返 回 值：如果被通知任务还没取走上一个通知，又接收了一个通知，则这次通知值未能更新并返回 pdFALSE， 而其他情况均返回pdPASS。

__eAction 任务通知值的状态表__

eAction 取值	含义
eNoAction	对象任务接收任务通知，但是任务自身的任务通知值不更新，即形参 ulValue 没有用。
eSetBits	对象任务接收任务通知， 同时任务自身的任务通知值与ulValue 按位或。 如果 ulValue设置为 0x01， 那么任务的通知值的位 0 将被置为 1。同样的如果 ulValue 设置为 0x04，那么任务的通知值的位 2 将被置为 1。在这种方式下，任务通知可以看成是事件标志的一种轻量型的实现， 速度更快
eIncrement	对象任务接收任务通知， 任务自身的任务通知值加 1，即形参ulValue 没有用。 这个时候调用 xTaskNotify()等同于调用xTaskNotifyGive()。
eSetValueWithOverwrite	对象任务接收任务通知，且任务自身的任务通知值会无条件的被设置为 ulValue。在这种方式下，任务通知可以看成是函数 xQueueOverwrite()的一种轻量型的实现， 速度更快。
eSetValueWithoutOverwrite	对象任务接收任务通知， 且对象任务没有通知值，那么通知值就会被设置为 ulValue。对象任务接收任务通知， 但是上一次接收到的通知值并没有取走 ，那么本次的通知值将不会更新 ，同时函数返回pdFALSE。在这种方式下，任务通知可以看成是函数 xQueueSend() 应用在队列深度为 1 的队列上的一种轻量型实现，速度更快。

4. 中断中发送任务通知 函数 xTaskNotifyFromISR()

函数原型：  
#define xTaskNotifyFromISR( xTaskToNotify, \
						  ulValue, \
						  eAction, \
						  pxHigherPriorityTaskWoken ) \
						xTaskGenericNotifyFromISR( ( xTaskToNotify ), \
					  	( ulValue ), \
					  	( eAction ), \
					  	NULL, \
					  	( pxHigherPriorityTaskWoken ) )
功 能	：	 在中断中向指定的任务发送一个任务通知。
参 数	： 
		--xTaskToNotify 指定接收通知的任务句柄。
		--ulValue 用于更新接收任务通知的任务通知值， 具体如何更新由形参 eAction 决定。
		--eAction 任务通知值的状态（见eAction 任务通知值的状态表）。
		--pxHigherPriorityTaskWoken 置为 pdTRUE，需要在中断退出前执行一次上下文切换，
返 回 值：上一个通知还没被取走，接着又收到一个通知返回 pdFALSE。

5. 中断中发送任务通知 通用函数 xTaskGenericNotifyFromISR()

函数原型：  
#if( configUSE_TASK_NOTIFICATIONS == 1 )
	BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, (1)
						uint32_t ulValue,		 				(2)
						eNotifyAction eAction, 					(3)
						uint32_t *pulPreviousNotificationValue, (4)
						BaseType_t *pxHigherPriorityTaskWoken ) (5)
功 能	：	 在 中 断 中 发 送 任 务 通 知 的 通 用 函 数。
参 数	： (1)： 指定接收通知的任务句柄。
	  --(2)：用于更新接收任务通知值， 具体如何更新由形参 eAction 决定。
	  --(3)：任务通知值更新方式。
	  --(4)：用于保存上一个任务通知值。
	  --(5)： *pxHigherPriorityTaskWoken 在使用之前必须先初始化为 pdFALSE ，如果被设置为pdTRUE在中断退出前要执行一次上下文切换。
返 回 值：任务还没取走上一个通知，函数调用失败并返回 pdFALSE。

6.任务通知发送函数 xTaskNotifyAndQuery()

函数原型： 
#define xTaskNotifyAndQuery( xTaskToNotify,ulValue,eAction,pulPreviousNotifyValue ) \
				xTaskGenericNotify( ( xTaskToNotify ), \
				( ulValue ), \
				( eAction ), \
				( pulPreviousNotifyValue ) )
功 能	：向指定的任务发送一个任务通知， 并返回对象任务的上一个通知值。
参 数	： 
	--xTaskToNotify 需要接收通知的任务句柄。
	--ulValue 用于更新接收任务通知值， 具体如何更新由形参 eAction 决定。
	--eAction 任务通知值的状态（见eAction 任务通知值的状态表）。
	-- pulPreviousNotifyValue 对象任务的上一个任务通知值，如果为 NULL， 则不需要回传， 这个时候就等价于函数 xTaskNotify()。
返 回 值： 上一个通知还没被取走，接着又收到一个通知返回 pdFALSE ，其他情况均返回pdPASS。

7.在中断中向任务发送通知xTaskNotifyAndQueryFromISR()

函数原型：
BaseType_t xTaskNotifyAndQueryFromISR(TaskHandle_t xTaskToNotify,
					uint32_t ulValue,
					eNotifyAction eAction,
					uint32_t *pulPreviousNotifyValue,
					BaseType_t *pxHigherPriorityTaskWoken );
功 能	： 在中断中向指定的任务发送一个任务通知， 并返回对象任务的上一个通知值。
参 数	： 
	--xTaskToNotify 需要接收通知的任务句柄。
	--ulValue 用于更新接收任务通知值， 具体如何更新由形参 eAction 决定。
	--eAction 任务通知值的状态（见eAction 任务通知值的状态表）。
	-- pulPreviousNotifyValue 对象任务的上一个任务通知值，如果为 NULL， 则不需要回传。
	--pxHigherPriorityTaskWoken 在使用之前必须先初始化为 pdFALSE ，如果被设置为pdTRUE在中断退出前要执行一次上下文切换。
返 回 值： 上一个通知还没被取走，接着又收到一个通知返回 pdFALSE ，其他情况均返回pdPASS。

二、获取任务通知函数

等待通知API函数只能用在任务中，没有带中断保护版本，因此只有两个API函数：
​ ulTaskNotifyTake()和xTaskNotifyWait ()。
前者是为代替二进制信号量和计数信号量而专门设计的，它和发送通知API函数xTaskNotifyGive()、vTaskNotifyGiveFromISR()配合使用；后者是全功能版的等待通知，可以根据不同的参数实现轻量级二进制信号量、计数信号量、事件组和长度为1的队列。

1. ulTaskNotifyTake()

函数原型：
uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit,
					TickType_t xTicksToWait );
功 能	：用于获取一个任务通知， 获取二值信号量、计数信号量类型的任务通知。
参 数	：
	--xClearCountOnExit 设置为 pdFALSE 时，函数 xTaskNotifyTake()退出前，将任务的通知值减 1，可以用来实现计数信号量；
					设置为 pdTRUE 时，函数xTaskNotifyTake()退出前，将任务通知值清零，可以用来实现二值信号量。
	--xTicksToWait 超时时间， 单位为系统节拍周期。
返 回 值： 返回任务的当前通知值， 在其减 1 或者清 0 之前。

2. xTaskNotifyWait()

函数原型：
BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry,
									uint32_t ulBitsToClearOnExit,
									uint32_t *pulNotificationValue,
									TickType_t xTicksToWait );
功 能	：用于等待一个任务通知，并带有超时等待。
参 数	：
	--ulBitsToClearOnEntry 函数执行前清零任务控制块中变量 ulNotifiedValue 那些位 。
	--ulBitsToClearOnExit 表示在函数退出前，清零任务控制块中变量 ulNotifiedValue 那些位，在清 0 前，接收到的任务通知值会先被保存到形参*pulNotificationValue 中。
	--pulNotificationValue 用于保存接收到的任务通知值。 如果 不需要使用，则设置为 NULL 即可 。
	--xTicksToWait 等待消息通知的最大等待时间。
返 回 值： 如果获取任务通知成功则返回 pdTRUE，失败则返回 pdFALSE。