07 FreeRTOS 事件组（event group）

1、事件组概念

1.1 基本概念

使用事件组可以等待某个事件、若干事件中的任意一个事件、若干事件中的所有事件，但是不能指定若干事件中的某些事件。

事件组可以简单地认为就是一个整数：这个整数的每一位表示一个事件；每一位事件的含义由程序员决定，比如：Bit0表示用来串口是否就绪，Bit1表示按键是否被按下；这些位，值为1表示事件发生了，值为0表示事件没发生；一个或多个任务、ISR都可以去写这些位，并且一个或多个任务、ISR都可以去读这些位；可以等待某一位、某些位中的任意一个，也可以等待多位。

事件组用一个整数来表示，其中的高8位留给内核使用，只能用其他的位来表示事件。

如果configUSE_16_BIT_TICKS是1，那么这个整数就是16位的，低8位用来表示事件；如果configUSE_16_BIT_TICKS是0，那么这个整数就是32位的，低24位用来表示事件。

configUSE_16_BIT_TICKS是用来表示Tick Count的，怎么会影响事件组？这只是基于效率来考虑。如果configUSE_16_BIT_TICKS是1，就表示该处理器使用16位更高效，所以事件组也使用16位；如果configUSE_16_BIT_TICKS是0，就表示该处理器使用32位更高效，所以事件组也使用32位。

事件组起通知作用，数据的保存还需要另想办法，比如用队列。

1.2 事件组与队列、信号量的区别

唤醒谁：

队列、信号量：事件发生时，只会唤醒一个任务。

事件组：事件发生时，会唤醒所有符号条件的任务，简单地说它有"广播"的作用。

是否清除事件：

队列、信号量：是消耗型的资源，队列的数据被读走就没了；信号量被获取后就减少了。

事件组：被唤醒的任务有两个选择，可以让事件保留不动，也可以清除事件。

2、事件组函数

2.1 创建

使用事件组之前，要先创建，得到一个句柄；使用事件组时，要使用句柄来表明使用哪个事件组。有两种创建方法：动态分配内存、静态分配内存。

/* 创建一个事件组，返回它的句柄。
 * 此函数内部会分配事件组结构体
 * 返回值: 返回句柄，非NULL表示成功
*/
EventGroupHandle_t xEventGroupCreate( void );

/* 创建一个事件组，返回它的句柄。
 * 此函数无需动态分配内存，所以需要先有一个StaticEventGroup_t结构体，并传入它的指针
 * 返回值: 返回句柄，非NULL表示成功
*/
EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer );

2.2 删除

对于动态创建的事件组，不再需要它们时，可以删除它们以回收内存。

/*
 * xEventGroup: 事件组句柄，你要删除哪个事件组
*/
void vEventGroupDelete( EventGroupHandle_t xEventGroup );

2.3 设置事件

可以设置事件组的某个位、某些位，使用的函数有2个：在任务中使用 xEventGroupSetBits()，在ISR中使用 xEventGroupSetBitsFromISR() 。有一个或多个任务在等待事件，如果这些事件符合这些任务的期望，那么任务还会被唤醒。

/* 设置事件组中的位
 * xEventGroup: 哪个事件组
 * uxBitsToSet: 设置哪些位?
 * 如果uxBitsToSet的bitX, bitY为1, 那么事件组中的bitX, bitY被设置为1
 * 可以用来设置多个位，比如 0x15 就表示设置bit4, bit2, bit0
 * 返回值: 返回原来的事件值(没什么意义, 因为很可能已经被其他任务修改了)
*/
EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
                            const EventBits_t uxBitsToSet );

/* 设置事件组中的位
 * xEventGroup: 哪个事件组
 * uxBitsToSet: 设置哪些位?
 * 如果uxBitsToSet的bitX, bitY为1, 那么事件组中的bitX, bitY被设置为1
 * 可以用来设置多个位，比如 0x15 就表示设置bit4, bit2, bit0
 * pxHigherPriorityTaskWoken: 有没有导致更高优先级的任务进入就绪态? pdTRUE-有,pdFALSE-没有
 * 返回值: pdPASS-成功, pdFALSE-失败
*/
BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
                                    const EventBits_t uxBitsToSet,
                                    BaseType_t * pxHigherPriorityTaskWoken );

值得注意的是，ISR中的函数，比如队列函数 xQueueSendToBackFromISR 、信号量函数 xSemaphoreGiveFromISR ，它们会唤醒某个任务，最多只会唤醒1个任务。

但是设置事件组时，有可能导致多个任务被唤醒，这会带来很大的不确定性。所以xEventGroupSetBitsFromISR函数不是直接去设置事件组，而是给一个FreeRTOS后台任务(daemon task)发送队列数据，由这个任务来设置事件组。

如果后台任务的优先级比当前被中断的任务优先级高， xEventGroupSetBitsFromISR 会设置 *pxHigherPriorityTaskWoken 为pdTRUE。

如果daemon task成功地把队列数据发送给了后台任务，那么 xEventGroupSetBitsFromISR 的返回值就是pdPASS。

2.4 等待事件

使用 xEventGroupWaitBits 来等待事件，可以等待某一位、某些位中的任意一个，也可以等待多位；等到期望的事件后，还可以清除某些位。

EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
                            const EventBits_t uxBitsToWaitFor,
                            const BaseType_t xClearOnExit,
                            const BaseType_t xWaitForAllBits,
                            TickType_t xTicksToWait );

先引入一个概念：unblock condition。一个任务在等待事件发生时，它处于阻塞状态；当期望的时间发生时，这个状态就叫"unblock condition"，非阻塞条件，或称为"非阻塞条件成立"；当"非阻塞条件成立"后，该任务就可以变为就绪态。

函数参数说明：

参数	说明
xEventGroup	等待哪个事件组？
uxBitsToWaitFor	等待哪些位？哪些位要被测试？
xWaitForAllBits	怎么测试？是 "AND" 还是 "OR" ？ pdTRUE: 等待的位，全部为 1; pdFALSE: 等待的位，某一个为 1 即可
xClearOnExit	函数提出前是否要清除事件？ pdTRUE: 清除 uxBitsToWaitFor 指定的位 pdFALSE: 不清除
xTicksToWait	如果期待的事件未发生，阻塞多久。可以设置为 0 ：判断后即刻返回；可设置为 portMAX_DELAY ：一定等到成功才返回；可以设置为期望的 Tick Count ，一般用 pdMS_TO_TICKS() 把 ms 转换为 Tick Count
返回值	返回的是事件值，如果期待的事件发生了，返回的是 " 非阻塞条件成立 " 时的事件值；如果是超时退出，返回的是超时时刻的事件值。

可以使用 xEventGroupWaitBits() 等待期望的事件，它发生之后再使用xEventGroupClearBits() 来清除。但是这两个函数之间，有可能被其他任务或中断抢占，它们可能会修改事件组。

可以使用设置 xClearOnExit 为pdTRUE，使得对事件组的测试、清零都在xEventGroupWaitBits() 函数内部完成，这是一个原子操作。

2.5 同步点

假如有一个事情需要多个任务协同，比如：任务A：炒菜；任务B：买酒；任务C：摆台。

A、B、C做好自己的事后，还要等别人做完；大家一起做完，才可开饭。

使用 xEventGroupSync() 函数可以同步多个任务：

可以设置某位、某些位，表示自己做了什么事；

可以等待某位、某些位，表示要等等其他任务；

期望的时间发生后， xEventGroupSync() 才会成功返回；

xEventGroupSync 成功返回后，会清除事件。

EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
                        const EventBits_t uxBitsToSet,
                        const EventBits_t uxBitsToWaitFor,
                        TickType_t xTicksToWait );

函数参数说明：

参数	说明
xEventGroup	哪个事件组？
uxBitsToSet	要设置哪些事件？我完成了哪些事件？比如 0x05( 二进制为 0101) 会导致事件组的 bit0,bit2 被设置为 1
uxBitsToWaitFor	等待那个位、哪些位？比如 0x15( 二级制 10101) ，表示要等待 bit0,bit2,bit4 都为 1
xTicksToWait	如果期待的事件未发生，阻塞多久。可以设置为 0 ：判断后即刻返回；可设置为 portMAX_DELAY ：一定等到成功才返回；可以设置为期望的 Tick Count ，一般用 pdMS_TO_TICKS() 把 ms 转换为 Tick Count
返回值	返回的是事件值，如果期待的事件发生了，返回的是 " 非阻塞条件成立 " 时的事件值；如果是超时退出，返回的是超时时刻的事件值。

3、示例代码

3.1 等待多个事件

设计程序：创建3个任务，

任务1，累加100000，然后设置事件bit0，

任务2，累减100000，然后设置事件bit1，

任务3，等待事件1和事件1；事件0或事件1

要先包含头文件#include "event_groups.h"

static int sum = 0;
static int dec = 0;
static QueueHandle_t xQueueCalcHandle;
static EventGroupHandle_t xEventGroupCalc;

void Task1Function( void * param)
{
	volatile int i = 0;	//使用volatile修饰，让系统不要去优化这个变量
	while(1){
		for(i = 0; i < 100000; i++){
			sum++;
		}
		//往队列中写入数据
		xQueueSend(xQueueCalcHandle, &sum, 0);
		//通知对方，设置事件0
		xEventGroupSetBits(xEventGroupCalc, (1<<0));

	}
}

void Task2Function( void * param)
{
	volatile int i = 0;	//使用volatile修饰，让系统不要去优化这个变量
	while(1){
		for(i = 0; i < 100000; i++){
			dec--;
		}
		//往队列中写入数据
		xQueueSend(xQueueCalcHandle, &dec, 0);
		//设置事件1
		xEventGroupSetBits(xEventGroupCalc, (1<<1));
	}
}

void Task3Function( void * param)
{
	int val1, val2;
	while(1){
		//平时等待事件
		xEventGroupWaitBits(xEventGroupCalc, (1<<0)|(1<<1), pdTRUE, pdTRUE, portMAX_DELAY);
		
		//等到事件后，读出数据的值
		xQueueReceive(xQueueCalcHandle, &val1, 0);
		xQueueReceive(xQueueCalcHandle, &val2, 0);
		printf("val1 = %d, val2 = %d\r\n", val1, val2);
	}
}

//main函数中
//创建事件组
	xEventGroupCalc = xEventGroupCreate();
	
	xQueueCalcHandle = xQueueCreate(2, sizeof(int));
	if(xQueueCalcHandle == NULL){
		printf("can not create queue\r\n");
	}
	
	xTaskCreate(Task1Function, "Task1", 100, NULL, 1, &xHandleTask1);
	xTaskCreate(Task2Function, "Task2", 100, NULL, 1, NULL);
	xTaskCreate(Task3Function, "Task3", 100, NULL, 1, NULL);

3.2 任务同步

设计程序：有买菜、做饭、摆台3个任务，只有等这三件事情都做完了才开始吃饭。

static void vCookingTask( void *pvParameters );
static void vBuyingTask( void *pvParameters );
static void vTableTask( void *pvParameters );

/*-----------------------------------------------------------*/

/* 事件组句柄 */
EventGroupHandle_t xEventGroup;

/* bit0: 摆台
 * bit1: 买菜
 * bit2: 炒菜
 */
#define TABLE    (1<<0)
#define BUYING   (1<<1)
#define COOKING  (1<<2)
#define ALL      (TABLE | BUYING | COOKING)

int main( void )
{
	prvSetupHardware();
	
    /* 创建递归锁 */
    xEventGroup = xEventGroupCreate( );

	if( xEventGroup != NULL )
	{
		/* 创建3个任务: 洗菜/生火/炒菜
		 */
		xTaskCreate( vCookingTask, "task1", 1000, "A", 1, NULL );
		xTaskCreate( vBuyingTask,  "task2", 1000, "B", 2, NULL );
		xTaskCreate( vTableTask,   "task3", 1000, "C", 3, NULL );

		/* 启动调度器 */
		vTaskStartScheduler();
	}
	else
	{
		/* 无法创建事件组 */
	}

	/* 如果程序运行到了这里就表示出错了, 一般是内存不足 */
	return 0;
}

/*-----------------------------------------------------------*/

/*-----------------------------------------------------------*/
static void vCookingTask( void *pvParameters )
{
	const TickType_t xTicksToWait = pdMS_TO_TICKS( 100UL );		
	int i = 0;
	
	/* 无限循环 */
	for( ;; )
	{
		/* 做自己的事 */
		printf("%s is cooking %d time....\r\n", (char *)pvParameters, i);
		
		/* 表示我做好了, 还要等别人都做好 */
		xEventGroupSync(xEventGroup, COOKING, ALL, portMAX_DELAY);
	
		/* 别人也做好了, 开饭 */
		printf("%s is eating %d time....\r\n", (char *)pvParameters, i++);
		vTaskDelay(xTicksToWait);
	}
}

static void vBuyingTask( void *pvParameters )
{
	const TickType_t xTicksToWait = pdMS_TO_TICKS( 100UL );		
	int i = 0;
	
	/* 无限循环 */
	for( ;; )
	{
		/* 做自己的事 */
		printf("%s is buying %d time....\r\n", (char *)pvParameters, i);
		
		/* 表示我做好了, 还要等别人都做好 */
		xEventGroupSync(xEventGroup, BUYING, ALL, portMAX_DELAY);
	
		/* 别人也做好了, 开饭 */
		printf("%s is eating %d time....\r\n", (char *)pvParameters, i++);
		vTaskDelay(xTicksToWait);
	}
}

static void vTableTask( void *pvParameters )
{
	const TickType_t xTicksToWait = pdMS_TO_TICKS( 100UL );		
	int i = 0;
	
	/* 无限循环 */
	for( ;; )
	{
		/* 做自己的事 */
		printf("%s is do the table %d time....\r\n", (char *)pvParameters, i);
		
		/* 表示我做好了, 还要等别人都做好 */
		xEventGroupSync(xEventGroup, TABLE, ALL, portMAX_DELAY);
	
		/* 别人也做好了, 开饭 */
		printf("%s is eating %d time....\r\n", (char *)pvParameters, i++);
		vTaskDelay(xTicksToWait);
	}
}