本篇介紹OS_FLAG.C中的檢測事件標誌組的標誌狀態函式

OS_FLAGS  OSFlagAccept (OS_FLAG_GRP  *pgrp,OS_FLAGS flags,INT8U wait_type,INT8U *perr)檢測事件標誌組的標誌狀態函式：

• 介紹一下wait_type：

在最後的程式碼中也有相關介紹，為了更好理解，下面具體解釋一下：

wait_type     specifies whether you want ALL bits to be set/cleared or ANY of the bitsto be set/cleared.
*                            You can specify the following argument:
*                            OS_FLAG_WAIT_CLR_ALL   You will check ALL bits in 'flags' to be clear (0)
*                            OS_FLAG_WAIT_CLR_ANY   You will check ANY bit  in 'flags' to be clear (0)
*                            OS_FLAG_WAIT_SET_ALL   You will check ALL bits in 'flags' to be set   (1)
*                            OS_FLAG_WAIT_SET_ANY   You will check ANY bit  in 'flags' to be set   (1)
*--wait_type:定義等待事件標誌位的方式.有以下四種引數選擇：
OS_FLAG_WAIT_CLR_ALL：所有指定事件標誌位清 (0)；
    OS_FLAG_WAIT_CLR_ANY：任意指定事件標誌位清 (0)；
    OS_FLAG_WAIT_SET_ALL：所有指定事件標誌位置 (1)；
    OS_FLAG_WAIT_SET_ANY：任意指定事件標誌位置 (1)。

所謂的消耗與否，就是事件組滿足條件後（獲得事件標誌組後），事件標誌組控制塊的對應事件標誌是否清除，如果清除，就稱為消耗掉，如果不清除，就成為不消耗。

程式碼中具體體現為：

result = (INT8U)(wait_type & OS_FLAG_CONSUME); /*將wiat_type與OS_FLAG_COUNSUME進行與，結果存放在result中*/
    if (result != (INT8U)0)						/*判斷我們是否需要清除標誌。*/
	{                 
        wait_type &= ~OS_FLAG_CONSUME;			/*不為0，消耗型，需要清除，wait_type儲存其取反之後的值*/
        consume    = OS_TRUE;					/*"清除"事件標誌位置1，需要對這個標誌清0*/
    } 
	else						/*result為0，非消耗型。不需要清除*/
	{
        consume    = OS_FALSE;					/*"清除"事件標誌位為0*/
    }
 

將wiat_type與OS_FLAG_COUNSUME進行邏輯與運算，結果存放在result中。若是rusult為0，則說明wait_type是沒有加上OS_FLAG_CONSUME的，也就是非消耗型別的，否則就是消耗型別的。

• 該函式中第二個需要解釋的點：

case OS_FLAG_WAIT_SET_ALL:             /*等待選擇的所有位都置1，即所有指定事件標誌位清 (0)*/
             flags_rdy = (OS_FLAGS)(pgrp->OSFlagFlags & flags);     /*提取我們需要的位*/
             if (flags_rdy == flags)		 /*必須匹配到我們需要的所有的位*/
			 {                   
                 if (consume == OS_TRUE)	/*如果是消耗型的*/
				 {                
                     pgrp->OSFlagFlags &= (OS_FLAGS)~flags_rdy;    /*將請求事件組中對應請求標誌位的位清零，消耗了事件*/
                 }
             }

以這個小片段為例，裡面有一個與運算：

flags_rdy = (OS_FLAGS)(pgrp->OSFlagFlags & flags);     /*提取我們需要的位*/

解釋一下我們是如何提取我們需要的位呢？這行語句為什麼進行與運算？

OSFlagFlags和flags都是8位。假定各自8位分別如上圖設定。當我們提取位的時候，就一一對應，進行邏輯與操作，並賦給flags_rdy：

if (flags_rdy == flags)		 /*必須匹配到我們需要的所有的位*/

如果是OS_FLAG_WAIT_SET_ANY等待型別，進行完與操作之後，

 if (flags_rdy != (OS_FLAGS)0) /*看是否有任何設定為1的標誌*/

是將flags_rdy與0進行比較。然後執行相關操作。

• 第三個需要提醒的點：

if (consume == OS_TRUE)	/*如果是消耗型的*/
				 {                
                     pgrp->OSFlagFlags &= (OS_FLAGS)~flags_rdy;    /*將請求事件組中對應請求標誌位的位清零，消耗了事件*/
                 }

如果是消耗型的，在清除的時候，我們只清除了之前用到的位，並不是所有位都清除了。這點需要注意一下。

下面是該函式的原始碼：

/*$PAGE*/
/*
*********************************************************************************************************
*                              CHECK THE STATUS OF FLAGS IN AN EVENT FLAG GROUP
*									檢測事件標誌組的標誌狀態
* Description: This function is called to check the status of a combination of bits to be set or cleared
*              in an event flag group.  Your application can check for ANY bit to be set/cleared or ALL
*              bits to be set/cleared.
			   This call does not block if the desired flags are not present.
*描述：這個功能用來檢查位的組合狀態，來確定事件標誌組中的事件標誌位是置位還是清0。
		你的應用程式可以檢查任意一位是置位還是清0，也可以檢查所有位是置位還是清0。
*		這個呼叫不會被阻塞如果需要的事件標誌沒有產生。這點與於OSFlagPend()不同。
* Arguments  : pgrp          is a pointer to the desired event flag group.
*引數：						--pgrp：指向事件標誌組的指標
*              flags         Is a bit pattern indicating which bit(s) (i.e. flags) you wish to check.
*                            The bits you want are specified by setting the corresponding bits in
*                            'flags'.  e.g. if your application wants to wait for bits 0 and 1 then
*                            'flags' would contain 0x03.
*							--flags：指定需要檢查的事件標誌位。為1則檢查對應位；為0則忽若對應位。
									flags是事件組合的標誌,是位掩碼，表示事件要等待哪些位。
									如果應用程式等待任務組中事件標誌中的0和2，掩碼為0x05。
*              wait_type     specifies whether you want ALL bits to be set/cleared or ANY of the bits
*                            to be set/cleared.
*                            You can specify the following argument:
*                            OS_FLAG_WAIT_CLR_ALL   You will check ALL bits in 'flags' to be clear (0)
*                            OS_FLAG_WAIT_CLR_ANY   You will check ANY bit  in 'flags' to be clear (0)
*                            OS_FLAG_WAIT_SET_ALL   You will check ALL bits in 'flags' to be set   (1)
*                            OS_FLAG_WAIT_SET_ANY   You will check ANY bit  in 'flags' to be set   (1)
*							--wait_type:定義等待事件標誌位的方式.有以下四種引數選擇：
										OS_FLAG_WAIT_CLR_ALL：所有指定事件標誌位清 (0)；
										OS_FLAG_WAIT_CLR_ANY：任意指定事件標誌位清 (0)；
										OS_FLAG_WAIT_SET_ALL：所有指定事件標誌位置 (1)；
										OS_FLAG_WAIT_SET_ANY：任意指定事件標誌位置 (1)。
*                            NOTE: Add OS_FLAG_CONSUME if you want the event flag to be 'consumed' by
*                                  the call.  Example, to wait for any flag in a group AND then clear
*                                  the flags that are present, set 'wait_type' to:
*                                  OS_FLAG_WAIT_SET_ANY + OS_FLAG_CONSUME
*							註釋：如果需要在得到期望的事件標誌後，清除該事件標誌，則可以在呼叫函式時，
								 將該引數加上一個常量OS_FLAG_CONSUME。例如，如果等待事件標誌組中任意指定事件標誌位置位，
								 並且在任意事件標誌位置位後清除該位，則把引數wait_type設定為：OS_FLAG_WAIT_SET_ANY + OS_FLAG_CONSUME
								 所謂的消耗與否，就是事件組滿足條件後，獲得事件標誌組後。事件標誌組控制塊的對應事件標誌清除，即消耗掉。
*              perr          is a pointer to an error code and can be:
*                            OS_ERR_NONE               No error
*                            OS_ERR_EVENT_TYPE         You are not pointing to an event flag group
*                            OS_ERR_FLAG_WAIT_TYPE     You didn't specify a proper 'wait_type' argument.
*                            OS_ERR_FLAG_INVALID_PGRP  You passed a NULL pointer instead of the event flag
*                                                      group handle.
*                            OS_ERR_FLAG_NOT_RDY       The desired flags you are waiting for are not
*                                                      available.
*							--perr：是一個指向錯誤碼的指標，可以是一下幾種：
								  OS_ERR_NONE：無錯誤
								  OS_ERR_EVENT_TYPE：指標未指向事件標誌組錯
								  OS_ERR_FLAG_WAIT_TYPE：引數wait_type不是指定的四個方式之一。
								  OS_ERR_FLAG_INVALID_PGRP：pgrp為空指標
								  OS_ERR_FLAG_NOT_RDY：指定的事件標誌沒有發生。
* Returns    : The flags in the event flag group that made the task ready or, 0 if a timeout or an error
*              occurred.
*返回值：返回事件標誌組的事件標誌。如果是超時或者有錯誤發生，返回0
* Called from: Task or ISR
*呼叫：從任務或者中斷呼叫
* Note(s)    : 1) IMPORTANT, the behavior of this function has changed from PREVIOUS versions.  The
*                 function NOW returns the flags that were ready INSTEAD of the current state of the
*                 event flags.
	註釋：1）重點：該功能和之前版本的不同，現在版本的該功能返回的是就緒的標誌，而不是當前事件的狀態
*********************************************************************************************************
*/

#if OS_FLAG_ACCEPT_EN > 0u
OS_FLAGS  OSFlagAccept (OS_FLAG_GRP  *pgrp,
                        OS_FLAGS      flags,
                        INT8U         wait_type,
                        INT8U        *perr)
{
    OS_FLAGS      flags_rdy;					/*定義一個"準備完畢"含量值*/
    INT8U         result;						/*結果*/
    BOOLEAN       consume;						/*定義一個"清除"事件標誌位(儲存值)*/
	#if OS_CRITICAL_METHOD == 3u                /*中斷被設定為型別3*/
		OS_CPU_SR     cpu_sr = 0u;
	#endif

	#ifdef OS_SAFETY_CRITICAL					/*如果定義了安全性中斷*/
		if (perr == (INT8U *)0)					/*如果錯誤碼指標為空，呼叫安全中斷異常函式*/
		{
			OS_SAFETY_CRITICAL_EXCEPTION();
		}
	#endif

	#if OS_ARG_CHK_EN > 0u						/*進行引數檢查*//*有效化pgrp指標*/
		if (pgrp == (OS_FLAG_GRP *)0)			/*如果pgrp指標為空*/
		{                       
			*perr = OS_ERR_FLAG_INVALID_PGRP;	/*將錯誤碼指標設定為OS_ERR_FLAG_INVALID_PGRP*/
			return ((OS_FLAGS)0);				/*返回0*/
		}
	#endif

    if (pgrp->OSFlagType != OS_EVENT_TYPE_FLAG)  /*有效化事件控制塊型別 如果不是事件型別標誌*/
	{         
        *perr = OS_ERR_EVENT_TYPE;				/*將錯誤碼指標設定為OS_ERR_EVENT_TYPE*/
        return ((OS_FLAGS)0);					/*返回0*/
    }

    result = (INT8U)(wait_type & OS_FLAG_CONSUME); /*將wiat_type與OS_FLAG_COUNSUME進行與，結果存放在result中*/
    if (result != (INT8U)0)						/*判斷我們是否需要清除標誌。*/
	{                 
        wait_type &= ~OS_FLAG_CONSUME;			/*不為0，需要清除，wait_type儲存其取反之後的值*/
        consume    = OS_TRUE;					/*"清除"事件標誌位置1，需要對這個標誌清0*/
    } 
	else										/*result為0，不需要清除*/
	{
        consume    = OS_FALSE;					/*"清除"事件標誌位為0*/
    }
	/*$PAGE*/
    *perr = OS_ERR_NONE;                       /*先將錯誤碼指標設定為無錯誤形式*/
    OS_ENTER_CRITICAL();					   /*關中斷（進入中斷）*/
    switch (wait_type)						   /*判斷等待型別，根據型別不同，處理相應的程式碼*/
	{
        case OS_FLAG_WAIT_SET_ALL:             /*等待選擇的所有位都置1，即所有指定事件標誌位清 (1)*/
             flags_rdy = (OS_FLAGS)(pgrp->OSFlagFlags & flags);     /*提取我們需要的位*/
             if (flags_rdy == flags)		 /*必須匹配到我們需要的所有的位*/
			 {                   
                 if (consume == OS_TRUE)	/*如果是消耗型的*/
				 {                
                     pgrp->OSFlagFlags &= (OS_FLAGS)~flags_rdy;    /*將請求事件組中對應請求標誌位的位清零，消耗了事件*/
                 }
             }
			 else				/*沒有匹配到我們需要的所有的位，阻塞，等待事件標誌組完成或者是超時*/
			 {
                 *perr = OS_ERR_FLAG_NOT_RDY;/*將錯誤碼設定為標誌位位準備好型別*/
             }
             OS_EXIT_CRITICAL();	/*開中斷*/
             break;

        case OS_FLAG_WAIT_SET_ANY:	/*如果等待型別為任意指定事件標誌位清(1)*/
             flags_rdy = (OS_FLAGS)(pgrp->OSFlagFlags & flags); 
             if (flags_rdy != (OS_FLAGS)0) /*看是否有任何設定為1的標誌*/
			 {           
                 if (consume == OS_TRUE) /*如果是消耗型別*/
				 {             
                     pgrp->OSFlagFlags &= (OS_FLAGS)~flags_rdy;     /*只清除我們需要的位*/
                 }
             }
			 else
			 {
                 *perr = OS_ERR_FLAG_NOT_RDY;	/*將錯誤型別設定為OS_ERR_FLAG_NOT_RDY*/
             }
             OS_EXIT_CRITICAL();				/*開中斷*/
             break;

#if OS_FLAG_WAIT_CLR_EN > 0u		/*允許生成 Wait on Clear 事件標誌程式碼*/
        case OS_FLAG_WAIT_CLR_ALL:   /* 等待型別為所有指定事件標誌位清 (0)；  */
             flags_rdy = (OS_FLAGS)~pgrp->OSFlagFlags & flags;    /*只提取我們需要的位 */
             if (flags_rdy == flags) {                     
                 if (consume == OS_TRUE) 
				 {                
                     pgrp->OSFlagFlags |= flags_rdy;      
                 }
             } 
			 else 
			 {
                 *perr = OS_ERR_FLAG_NOT_RDY;
             }
             OS_EXIT_CRITICAL();
             break;

        case OS_FLAG_WAIT_CLR_ANY:
             flags_rdy = (OS_FLAGS)~pgrp->OSFlagFlags & flags;   /* Extract only the bits we want      */
             if (flags_rdy != (OS_FLAGS)0) {               /* See if any flag cleared                  */
                 if (consume == OS_TRUE) {                 /* See if we need to consume the flags      */
                     pgrp->OSFlagFlags |= flags_rdy;       /* Set ONLY the flags that we got           */
                 }
             } else {
                 *perr = OS_ERR_FLAG_NOT_RDY;
             }
             OS_EXIT_CRITICAL();
             break;
#endif

        default:			/*預設情況下*/
             OS_EXIT_CRITICAL();/*開中斷（退出中斷）*/
             flags_rdy = (OS_FLAGS)0;/*將flags_rdy設定為0*/
             *perr     = OS_ERR_FLAG_WAIT_TYPE;/*錯誤碼設定為OS_ERR_FLAG_WAIT_TYPE*/
             break;
    }
    return (flags_rdy);/*返回flags_rdy*/
}
#endif

大概流程圖為：

END

不足之處還望提醒，謝過~