FreeRTOS-事件标志组源码分析

事件标志组的具体实现过程和前面信号量实现方式非常相似，信号量只能和单个任务或事件进行同步，而事件标志组能和多个任务或事件进行同步。事件标志组顾名思义就是用事件位来表示某个任务是否发生了，发生了的话就标记一个标志位，然后通知接收任务去做相应的处理工作。当然标志可以以组的形式出现，就是接收任务同时要求有多个事件(所有需求的标志都置位了)发生了才执行处理。

---

事件标志组的相关接口函数如下：

/* 创建事件标志组 */
xEventGroupCreate(void)
EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer )

/* 将指定事件位清除 */
xEventGroupClearBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear)
xEventGroupClearBitsFromISR(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear)

/* 将指定事件位置1 */
xEventGroupSetBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet)
xEventGroupSetBitsFromISR(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t * pxHigherPriorityTaskWoken)

/* 等待指定的事件位 */
xEventGroupWaitBits(EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait)

/* 获取当前事件标志组的值 */
xEventGroupGetBits(xEventGroup)
xEventGroupGetBitsFromISR(EventGroupHandle_t xEventGroup)	

关于静态分配和中断相关的接口函数这里就不分析了，这里只分析几个核心的函数，关于中断、静态分配的处理方式和非中断、动态的逻辑处理方式大同小异，前面信号量有分析过这块差异，可以触类旁通。先分析一下创建事件标志组的源码：

#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )

	EventGroupHandle_t xEventGroupCreate( void )
	{
	EventGroup_t *pxEventBits;
	
		/* 动态分配事件标志组存储空间 */
		pxEventBits = ( EventGroup_t * ) pvPortMalloc( sizeof( EventGroup_t ) ); /*lint !e9087 !e9079 see comment above. */

		if( pxEventBits != NULL )
		{
			/* 初始化事件位标志为0*/
			pxEventBits->uxEventBits = 0;
			/* 初始化任务等待事件标志列表 */
			vListInitialise( &( pxEventBits->xTasksWaitingForBits ) );

			#if( configSUPPORT_STATIC_ALLOCATION == 1 )
			{
				/* 使用动态分配 */
				pxEventBits->ucStaticallyAllocated = pdFALSE;
			}
			#endif

			traceEVENT_GROUP_CREATE( pxEventBits );
		}
		else
		{
			traceEVENT_GROUP_CREATE_FAILED(); /*lint !e9063 Else branch only exists to allow tracing and does not generate code if trace macros are not defined. */
		}

		return pxEventBits;
	}

#endif /* configSUPPORT_DYNAMIC_ALLOCATION */

代码比较简单，涉及到一个事件标志组的结构体，它的定义如下：

typedef struct EventGroupDef_t
{
	/* 保存事件标志位 */
	EventBits_t uxEventBits;
	/* 任务等待标志列表 */
	List_t xTasksWaitingForBits;

	#if( configUSE_TRACE_FACILITY == 1 )
		UBaseType_t uxEventGroupNumber;
	#endif

	#if( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
		uint8_t ucStaticallyAllocated; 
	#endif
} EventGroup_t;

事件标志组的定义是个32位的数据类型：

typedef uint32_t TickType_t;
typedef TickType_t EventBits_t;

这里要注意一下，虽然是个32位的数据类型变量，但是它只能存储24个事件位，剩余的8位用作其它功能使用，如下定义表明：

#if configUSE_16_BIT_TICKS == 1
	#define eventCLEAR_EVENTS_ON_EXIT_BIT	0x0100U
	#define eventUNBLOCKED_DUE_TO_BIT_SET	0x0200U
	#define eventWAIT_FOR_ALL_BITS			0x0400U
	#define eventEVENT_BITS_CONTROL_BYTES	0xff00U
#else
	#define eventCLEAR_EVENTS_ON_EXIT_BIT	0x01000000UL
	#define eventUNBLOCKED_DUE_TO_BIT_SET	0x02000000UL
	#define eventWAIT_FOR_ALL_BITS			0x04000000UL
	#define eventEVENT_BITS_CONTROL_BYTES	0xff000000UL
#endif

我的MCU使用的是第二个分支，可以看到最高的8位都被定义了，它们的用处分别是：

eventCLEAR_EVENTS_ON_EXIT_BIT	用于标示任务获取到对应标志后是否清除标志
eventUNBLOCKED_DUE_TO_BIT_SET	用于标示有任务的标记位被设置了
eventWAIT_FOR_ALL_BITS			用于标示任务需要等待所有标志位都被标记才执行
eventEVENT_BITS_CONTROL_BYTES	用于保存前面三个控制字节的状态

任务创建和数据结构分析完后开始分析事件标志位的一些操作。

将指定的事件标志位清除：

EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear )
{
EventGroup_t *pxEventBits = xEventGroup;
EventBits_t uxReturn;

	configASSERT( xEventGroup );
	configASSERT( ( uxBitsToClear & eventEVENT_BITS_CONTROL_BYTES ) == 0 );

	/* 进入临界区 */
	taskENTER_CRITICAL();
	{
		traceEVENT_GROUP_CLEAR_BITS( xEventGroup, uxBitsToClear );

		/* 获取事件组的事件标志位 */
		uxReturn = pxEventBits->uxEventBits;

		/* 清除对应的标志位 */
		pxEventBits->uxEventBits &= ~uxBitsToClear;
	}
	/* 退出临界区 */
	taskEXIT_CRITICAL();

	return uxReturn;
}

将指定事件标志位置1（这个函数建议和“等待指定事件位”函数联系起来看）

EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet )
{
ListItem_t *pxListItem, *pxNext;
ListItem_t const *pxListEnd;
List_t const * pxList;
EventBits_t uxBitsToClear = 0, uxBitsWaitedFor, uxControlBits;
EventGroup_t *pxEventBits = xEventGroup;
BaseType_t xMatchFound = pdFALSE;

	configASSERT( xEventGroup );
	configASSERT( ( uxBitsToSet & eventEVENT_BITS_CONTROL_BYTES ) == 0 );

	/* 获取任务等待事件标志列表(由于这里设置了标志位，所以要查看是否有任务因为等待这个标志而阻塞的，如果有，需要解除阻塞) */
	pxList = &( pxEventBits->xTasksWaitingForBits );
	pxListEnd = listGET_END_MARKER( pxList ); 
	vTaskSuspendAll();
	{
		traceEVENT_GROUP_SET_BITS( xEventGroup, uxBitsToSet );

		/* 获取任务等待事件标志列表的首个列表项 */
		pxListItem = listGET_HEAD_ENTRY( pxList );

		/* 设置某个事件标志 */
		pxEventBits->uxEventBits |= uxBitsToSet;

		/* 如果列表不为空执行此分支，表示有任务在等待这个标志位，当用户设置了后，需要从列表中删除等待的任务让其就绪 */
		while( pxListItem != pxListEnd )
		{
			/* 获取一个列表项 */
			pxNext = listGET_NEXT( pxListItem );
			/* 获取列表项值，列表项值保存着等待任务的条件控制信息 */
			uxBitsWaitedFor = listGET_LIST_ITEM_VALUE( pxListItem );
			xMatchFound = pdFALSE;

			/* 获取任务等待标志列表中任务的条件控制位(存储着用户在设置任务等待时传入的一些条件) */
			uxControlBits = uxBitsWaitedFor & eventEVENT_BITS_CONTROL_BYTES;
			/* 获取用户设置的标志请求位 */
			uxBitsWaitedFor &= ~eventEVENT_BITS_CONTROL_BYTES;

			/* 如果用户没有设置"满足所有标志才执行"，有其中任何一个标志被设置了，则执行这个分支 */
			if( ( uxControlBits & eventWAIT_FOR_ALL_BITS ) == ( EventBits_t ) 0 )
			{
				if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) != ( EventBits_t ) 0 )
				{	/* 查看任务等待的事件标志中有没被设置了的，有的话返回pdTRUE */
					xMatchFound = pdTRUE;
				}
				else
				{
					mtCOVERAGE_TEST_MARKER();
				}
			}
			/* 全部等待的标志位都被设置了，执行这个分支 */
			else if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) == uxBitsWaitedFor )
			{
				/* 返回pdTRUE */
				xMatchFound = pdTRUE;
			}
			else
			{
			}

			/* 等待(找)到了相应的标志，执行这个分支 */
			if( xMatchFound != pdFALSE )
			{
				if( ( uxControlBits & eventCLEAR_EVENTS_ON_EXIT_BIT ) != ( EventBits_t ) 0 )
				{
					/* 用户设置了清除，退出后清除设置了的位 */
					uxBitsToClear |= uxBitsWaitedFor;
				}
				else
				{
					mtCOVERAGE_TEST_MARKER();
				}

				/* 将任务从原来的事件和状态列表中删除，添加到就绪列表中，并且标记“标志位被设置了” */
				vTaskRemoveFromUnorderedEventList( pxListItem, pxEventBits->uxEventBits | eventUNBLOCKED_DUE_TO_BIT_SET );
			}

			/* 继续循环从任务等待事件标志列表取出任务查看 */
			pxListItem = pxNext;
		}

		/* 如果设置了退出清除标志，则这里获取清除后的值 */
		pxEventBits->uxEventBits &= ~uxBitsToClear;
	}
	/* 恢复任务调度器 */
	( void ) xTaskResumeAll();

	return pxEventBits->uxEventBits;
}

将任务从列表中删除的源码如下：

void vTaskRemoveFromUnorderedEventList( ListItem_t * pxEventListItem, const TickType_t xItemValue )
{
TCB_t *pxUnblockedTCB;

	configASSERT( uxSchedulerSuspended != pdFALSE );

	/* 将新的列表项值存入列表项( taskEVENT_LIST_ITEM_VALUE_IN_USE 用于标记事件的列表项值正在使用中 ) */
	listSET_LIST_ITEM_VALUE( pxEventListItem, xItemValue | taskEVENT_LIST_ITEM_VALUE_IN_USE );

	/* 获取需要解锁的任务控制块 */
	pxUnblockedTCB = listGET_LIST_ITEM_OWNER( pxEventListItem ); 
	configASSERT( pxUnblockedTCB );
	/* 将任务从事件列表中移除 */
	( void ) uxListRemove( pxEventListItem );

	/* 将任务从状态列表中移除 */
	( void ) uxListRemove( &( pxUnblockedTCB->xStateListItem ) );
	/* 添加到就绪列表中 */
	prvAddTaskToReadyList( pxUnblockedTCB );

	/* 根据优先级判断是否执行任务切换 */
	if( pxUnblockedTCB->uxPriority > pxCurrentTCB->uxPriority )
	{
		xYieldPending = pdTRUE;
	}
}

等待指定的事件位

EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait )
{
EventGroup_t *pxEventBits = xEventGroup;
EventBits_t uxReturn, uxControlBits = 0;
BaseType_t xWaitConditionMet, xAlreadyYielded;
BaseType_t xTimeoutOccurred = pdFALSE;

	configASSERT( xEventGroup );
	configASSERT( ( uxBitsToWaitFor & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
	configASSERT( uxBitsToWaitFor != 0 );
	#if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
	{
		configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
	}
	#endif

	/* 挂起调度器 */
	vTaskSuspendAll();
	{
		/* 获取当前事件bit */
		const EventBits_t uxCurrentEventBits = pxEventBits->uxEventBits;

		/* 判断对应的标志是否被标记了，根据形参来判断是只需一个标志就行还是所有标志都要标记 */
		xWaitConditionMet = prvTestWaitCondition( uxCurrentEventBits, uxBitsToWaitFor, xWaitForAllBits );

		/* 如果标志位满足需求了，执行这个分支 */
		if( xWaitConditionMet != pdFALSE )
		{
			/* 返回当前已标记了的标志 */
			uxReturn = uxCurrentEventBits;
			/* 已满足需求，等待时间清零 */
			xTicksToWait = ( TickType_t ) 0;

			/* Clear the wait bits if requested to do so. */
			if( xClearOnExit != pdFALSE )
			{
				/* 如果返回标志位后需要清除标志位的话执行下面这句，由用户传入形参来决定是否清除(xClearOnExit) */
				pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
			}
			else
			{
				mtCOVERAGE_TEST_MARKER();
			}
		}
		/* 如果标志位不满足，并且设置了不等待，执行这个分支 */
		else if( xTicksToWait == ( TickType_t ) 0 )
		{
			/* 对应标志位没有达到需要，用户也没设置等待时间，直接返回当前事件标志位 */
			uxReturn = uxCurrentEventBits;
			xTimeoutOccurred = pdTRUE;
		}
		/* 标志位还未达到需求，并且用户设置了阻塞时间，执行这个分支 */
		else
		{
			if( xClearOnExit != pdFALSE )
			{
				/* 如果需要清除标志位的话执行下面这句，这个结果值会作为任务等待标志列表的列表项值 */
				uxControlBits |= eventCLEAR_EVENTS_ON_EXIT_BIT;
			}
			else
			{
				mtCOVERAGE_TEST_MARKER();
			}

			if( xWaitForAllBits != pdFALSE )
			{
				/* 如果任务要等待所有标志位都被标记才满足的话执行下面这句，这个结果值会作为任务等待标志列表的列表项值 */
				uxControlBits |= eventWAIT_FOR_ALL_BITS;
			}
			else
			{
				mtCOVERAGE_TEST_MARKER();
			}

			/* 这个函数前面分析的太多了，都腻了，就是把事件插入到任务等待标志列表然后放入延时列表里面阻塞，
			   事件列表项值为用户设置的等待标志位+前面设置的控制位结合，状态列表项值为等待时间 */
			vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | uxControlBits ), xTicksToWait );

			uxReturn = 0;

			traceEVENT_GROUP_WAIT_BITS_BLOCK( xEventGroup, uxBitsToWaitFor );
		}
	}
	/* 恢复调度器 */
	xAlreadyYielded = xTaskResumeAll();

	/* 等待时间不为0执行这个分支 */
	if( xTicksToWait != ( TickType_t ) 0 )
	{
		if( xAlreadyYielded == pdFALSE )
		{
			/* 前面恢复调度器函数没有进行任务切换，这里手动进行一次任务切换(因为前面将任务插到到了延时列表之后需要阻塞，要进行一次任务切换) */
			portYIELD_WITHIN_API();
		}
		else
		{
			mtCOVERAGE_TEST_MARKER();
		}

		/* 执行到这里说明延时时间到了或者接收到对应的标志了，返回当前标志位情况，然后复位任务的事件列表项值 */
		uxReturn = uxTaskResetEventItemValue();

		/* 返回的标志位如果发生了变化执行此分支 */
		if( ( uxReturn & eventUNBLOCKED_DUE_TO_BIT_SET ) == ( EventBits_t ) 0 )
		{
			/* 进入临界区 */
			taskENTER_CRITICAL();
			{
				uxReturn = pxEventBits->uxEventBits;

				/* 查看等待的标志事件是否满足需求，满足需求的话会返回pdTRUE */
				if( prvTestWaitCondition( uxReturn, uxBitsToWaitFor, xWaitForAllBits ) != pdFALSE )
				{
					if( xClearOnExit != pdFALSE )
					{
						/* 如果需要清除标志位的话执行下面这句，由用户传入形参来决定是否清除(xClearOnExit) */
						pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
					}
					else
					{
						mtCOVERAGE_TEST_MARKER();
					}
				}
				else
				{
					mtCOVERAGE_TEST_MARKER();
				}
				/* 返回结果 */
				xTimeoutOccurred = pdTRUE;
			}
			taskEXIT_CRITICAL();
		}
		else
		{
		}

		/* 返回当前标志位情况 */
		uxReturn &= ~eventEVENT_BITS_CONTROL_BYTES;
	}
	traceEVENT_GROUP_WAIT_BITS_END( xEventGroup, uxBitsToWaitFor, xTimeoutOccurred );

	( void ) xTimeoutOccurred;

	return uxReturn;
}

其中查看等待的标志事件是否满足需求的代码分析如下：

static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits, const EventBits_t uxBitsToWaitFor, const BaseType_t xWaitForAllBits )
{
BaseType_t xWaitConditionMet = pdFALSE;

	/* 所有等待的标志事件只要有一个被标志了，就执行这个分支 */
	if( xWaitForAllBits == pdFALSE )
	{
		/* 查看事件中是否有一个标志位被标记了 */
		if( ( uxCurrentEventBits & uxBitsToWaitFor ) != ( EventBits_t ) 0 )
		{
			/* 返回 pdTRUE */
			xWaitConditionMet = pdTRUE;
		}
		else
		{
			mtCOVERAGE_TEST_MARKER();
		}
	}
	/* 所有等待的标志事件只有全部被标志了，才执行这个分支 */
	else
	{
		/* 查看事件中是否所有标志都被标记了 */
		if( ( uxCurrentEventBits & uxBitsToWaitFor ) == uxBitsToWaitFor )
		{
			/* 返回 pdTRUE */
			xWaitConditionMet = pdTRUE;
		}
		else
		{
			mtCOVERAGE_TEST_MARKER();
		}
	}

	/* 返回结果 */
	return xWaitConditionMet;
}