聊聊LiteOS事件模塊的結構體、初始化及常用操作

摘要：本文通過分析LiteOS事件模塊的源碼，深入掌握事件的使用。

事件（Event）是一種任務間通信的機制，可用於任務間的同步。多任務環境下，任務之間往往需要同步操作，一個等待即是一個同步。事件可以提供一對多、多對多的同步操作。本文通過分析LiteOS事件模塊的源碼，深入掌握事件的使用。

LiteOS事件模塊的源代碼，均可以在LiteOS開源站點https://gitee.com/LiteOS/LiteOS 獲取。事件源代碼、開發文檔，示例程序代碼如下：

• LiteOS內核事件源代碼

包括事件的私有頭文件kernel\base\include\los_event_pri.h、頭文件kernel\include\los_event.h、C源代碼文件kernel\base\los_event.c。

• 開發指南文檔–事件

在線文檔https://gitee.com/LiteOS/LiteOS/blob/master/doc/LiteOS_Kernel_Developer_Guide.md#%E4%BA%8B%E4%BB%B6。

1、事件結構體定義和常用宏定義

1.1 事件結構體定義

在文件kernel\base\include\los_event.h定義的事件控制塊結構體為EVENT_CB_S，結構體源代碼如下，結構體成員的解釋見注釋部分。

typedef struct tagEvent {
    UINT32 uwEventID;        /**< 事件ID，每一位標識一種事件類型 */
    LOS_DL_LIST stEventList; /**< 讀取事件的任務鏈表 */
} EVENT_CB_S, *PEVENT_CB_S;

開啟兼容POSIX的宏時LOSCFG_COMPAT_POSIX時，在文件kernel\base\include\los_event_pri.h還定義了結構體EventCond，如下：

#ifdef LOSCFG_COMPAT_POSIX
typedef struct {
    volatile INT32 *realValue;
    INT32 value;
    UINT32 clearEvent;
} EventCond;

1.2 事件常用宏定義

系統是否支持事件可以通過宏LOSCFG_BASE_IPC_EVENT來配置，默認開啟支持。在讀事件時，可以選擇讀取模式。讀取模式由如下幾個宏定義：

• 所有事件（LOS_WAITMODE_AND）：

邏輯與，基於接口傳入的事件類型掩碼eventMask，只有這些事件都已經發生才能讀取成功，否則該任務將阻塞等待或者返回錯誤碼。

• 任一事件（LOS_WAITMODE_OR）：

邏輯或，基於接口傳入的事件類型掩碼eventMask，只要這些事件中有任一種事件發生就可以讀取成功，否則該任務將阻塞等待或者返回錯誤碼。

• 清除事件（LOS_WAITMODE_CLR）：

這是一種附加讀取模式，需要與所有事件模式或任一事件模式結合使用（LOS_WAITMODE_AND | LOS_WAITMODE_CLR或 LOS_WAITMODE_OR | LOS_WAITMODE_CLR）。在這種模式下，當設置的所有事件模式或任一事件模式讀取成功后，會自動清除事件控制塊中對應的事件類型位。

  #define LOS_WAITMODE_AND                    4U

   #define LOS_WAITMODE_OR                     2U

   #define LOS_WAITMODE_CLR                    1U

2、事件常用操作

2.1 初始化事件

在使用事件前，必須使用函數UINT32 LOS_EventInit(PEVENT_CB_S eventCB)來初始化事件，需要的參數是結構體PEVENT_CB_S eventCB。分析下代碼，⑴處表示傳入的參數不能為空，否則返回錯誤碼。⑵關中斷后，事件.uwEventID初始化為0，然后初始化雙向循環鏈表.stEventList，用於掛在讀取事件的任務。

LITE_OS_SEC_TEXT_INIT UINT32 LOS_EventInit(PEVENT_CB_S eventCB)
{
    UINT32 intSave;

    LOS_TRACE(EVENT_CREATE, (UINTPTR)eventCB);

⑴  if (eventCB == NULL) {
        return LOS_ERRNO_EVENT_PTR_NULL;
    }

    intSave = LOS_IntLock();
⑵  eventCB->uwEventID = 0;
    LOS_ListInit(&eventCB->stEventList);
    LOS_IntRestore(intSave);
    return LOS_OK;
}

2.2 校驗事件掩碼

我們可以使用函數UINT32 LOS_EventPoll(UINT32 *eventId, UINT32 eventMask, UINT32 mode)來校驗事件掩碼，需要的參數為事件結構體的事件編碼eventId、用戶傳入的待校驗的事件掩碼eventMask及讀取模式mode，返回用戶傳入的事件是否發生。返回值為0時表示用戶預期的事件沒有發生，否則表示用戶期望的事件發生。我們看下源碼，⑴處先檢查傳入參數的合法性，然后執行⑵處的函數OsEventPoll()進行校驗。

LITE_OS_SEC_TEXT UINT32 LOS_EventPoll(UINT32 *eventId, UINT32 eventMask, UINT32 mode)
{
    UINT32 ret;
    UINT32 intSave;

⑴  ret = OsEventParamCheck((VOID *)eventId, eventMask, mode);
    if (ret != LOS_OK) {
        return ret;
    }

    SCHEDULER_LOCK(intSave);
⑵  ret = OsEventPoll(eventId, eventMask, mode);
    SCHEDULER_UNLOCK(intSave);
    return ret;
}

我們繼續看下函數OsEventPoll()。如果是任一事件讀取模式，接下來的判斷不等於表示至少有一個事件發生了，返回值ret就表示哪些事件發生了。⑵如果是所有事情讀取模式，當邏輯與運算*eventId & eventMask還等於eventMask時，表示期望的事件全部發生了，返回值ret就表示哪些事件發生了。⑶當ret不為0，期望的事件發生，並且是清除事件讀取模式時，需要把已經發生的事情進行清除。看來，這個函數不僅僅是查詢事件有沒有發生，還會有更新事件編碼的動作。

LITE_OS_SEC_TEXT STATIC UINT32 OsEventPoll(UINT32 *eventId, UINT32 eventMask, UINT32 mode)
{
    UINT32 ret = 0;

    LOS_ASSERT(ArchIntLocked());
    LOS_ASSERT(LOS_SpinHeld(&g_taskSpin));

⑴  if (mode & LOS_WAITMODE_OR) {
        if ((*eventId & eventMask) != 0) {
            ret = *eventId & eventMask;
        }
    } else {
⑵      if ((eventMask != 0) && (eventMask == (*eventId & eventMask))) {
            ret = *eventId & eventMask;
        }
    }

⑶  if (ret && (mode & LOS_WAITMODE_CLR)) {
        *eventId = *eventId & ~ret;
    }

    return ret;
}

2.3 讀/寫事件

2.3.1 讀取指定事件類型

我們可以使用函數LOS_EventRead()來讀取事件，需要4個參數。eventCB是初始化好的事件結構體，eventMask表示需要讀取的事件掩碼，mode是上文說明過的讀取模式，timeout是讀取超時，單位是Tick。該函數又進一步調用函數OsEventRead()實現事件的讀取，如下：

LITE_OS_SEC_TEXT UINT32 LOS_EventRead(PEVENT_CB_S eventCB, UINT32 eventMask, UINT32 mode, UINT32 timeout)
{
    return OsEventRead(eventCB, eventMask, mode, timeout, FALSE);
}

下面通過分析函數OsEventRead()的源碼看看如何讀取事件的。函數參數多了個BOOL once，表示是否只讀取一次，對於函數LOS_EventRead()，once取值FALSE。

⑴處調用函數OsEventReadCheck()進行基礎的校驗，比如第25位保留不能使用，事件掩碼eventMask不能為零，讀取模式組合是否合法，不能中斷中讀取事件。如果是系統任務讀取事件，會打印警告信息。然后⑵繼續調用函數OsEventReadImp()來讀取事件。

LITE_OS_SEC_TEXT STATIC UINT32 OsEventRead(PEVENT_CB_S eventCB, UINT32 eventMask, UINT32 mode,
                                           UINT32 timeout, BOOL once)
{
    UINT32 ret;
    UINT32 intSave;

⑴  ret = OsEventReadCheck(eventCB, eventMask, mode);
    if (ret != LOS_OK) {
        return ret;
    }

    LOS_TRACE(EVENT_READ, (UINTPTR)eventCB, eventCB->uwEventID, eventMask, mode, timeout);

    SCHEDULER_LOCK(intSave);
⑵  ret = OsEventReadImp(eventCB, eventMask, mode, timeout, once, &intSave);
    SCHEDULER_UNLOCK(intSave);
    return ret;
}

我們繼續分析下函數OsEventReadImp()。⑴處當once為假時，調用校驗函數OsEventPoll()檢查事件eventMask是否發生。如果事件發生ret不為0，直接返回。ret為0，事件沒有發生時，執行⑵，如果超時時間timeout為0，調用者不能等待時，直接返回。⑶如果鎖任務調度時，不能讀取事件，返回錯誤碼。

⑷更新當前任務的阻塞的事件掩碼.eventMask和事件讀取模式.eventMode。執行⑸，更改當前任務的狀態不再是就緒狀態，設置為阻塞狀態，掛在事件的任務阻塞鏈表上。如果timeout不是永久等待，還會把任務掛在定時器排序鏈表里。⑹處觸發任務調度，后續程序需要等到讀取到事件才會繼續執行。

⑺如果等待時間超時，事件還不可讀，本任務讀取不到指定的事件時，返回錯誤碼。如果可以讀取到指定的事件時，執行⑻，檢查事件eventMask是否發生，然后返回結果值。

LITE_OS_SEC_TEXT STATIC UINT32 OsEventReadImp(PEVENT_CB_S eventCB, UINT32 eventMask, UINT32 mode,
                                              UINT32 timeout, BOOL once, UINT32 *intSave)
{
    UINT32 ret = 0;
    LosTaskCB *runTask = OsCurrTaskGet();

⑴  if (once == FALSE) {
        ret = OsEventPoll(&eventCB->uwEventID, eventMask, mode);
    }

 ⑵ if (ret == 0) {
        if (timeout == 0) {
            return ret;
        }

⑶      if (!OsPreemptableInSched()) {
            return LOS_ERRNO_EVENT_READ_IN_LOCK;
        }

⑷      runTask->eventMask = eventMask;
        runTask->eventMode = mode;

⑸      OsTaskWait(&eventCB->stEventList, OS_TASK_STATUS_PEND, timeout);

⑹      OsSchedResched();

        SCHEDULER_UNLOCK(*intSave);
        SCHEDULER_LOCK(*intSave);

⑺      if (runTask->taskStatus & OS_TASK_STATUS_TIMEOUT) {
            runTask->taskStatus &= ~OS_TASK_STATUS_TIMEOUT;
            return LOS_ERRNO_EVENT_READ_TIMEOUT;
        }

⑻      ret = OsEventPoll(&eventCB->uwEventID, eventMask, mode);
    }
    return ret;
}

2.3.2 寫入指定的事件類型

我們可以使用函數UINT32 LOS_EventWrite(PEVENT_CB_S eventCB, UINT32 events)來寫入指定的事件類型。該函數又進一步調用函數OsEventWrite()實現事件的寫入，如下所示：

LITE_OS_SEC_TEXT UINT32 LOS_EventWrite(PEVENT_CB_S eventCB, UINT32 events)
{
    return OsEventWrite(eventCB, events, FALSE);
}

下面通過分析OsEventWrite()的源碼看看如何寫入事件類型的。函數參數多了個BOOL once，表示是否只讀取一次，對於函數LOS_EventWrite()，once取值FALSE。⑴處代碼把事件結構體的事件掩碼和要寫入的事件類型events進行邏輯或計算，來完成事件的寫入。⑵如果等待事件的任務鏈表不為空，需要處理寫入事件后是否有任務能讀取到相應的事件。⑶處for循環依次遍歷事件阻塞鏈表上的任務，⑷獲取下一個任務nextTask。⑸處
分不同的讀取模式判斷事件是否符合任務resumedTask讀取事件的要求，如果滿足讀取事件，執行⑹設置退出標記exitFlag，然后調用函數OsTaskWake()把讀取事件的任務更改狀態並放入就緒隊列。⑺處如果參數once為真，則只處理事件的阻塞任務鏈表中的第一個任務。如果為假，繼續執行⑻，遍歷事件的阻塞任務鏈表中的每一個任務。⑼如果有任務讀取到事件，需要觸發任務調度。

LITE_OS_SEC_TEXT STATIC UINT32 OsEventWrite(PEVENT_CB_S eventCB, UINT32 events, BOOL once)
{
    LosTaskCB *resumedTask = NULL;
    LosTaskCB *nextTask = NULL;
    UINT32 intSave;
    UINT8 exitFlag = 0;

    if (eventCB == NULL) {
        return LOS_ERRNO_EVENT_PTR_NULL;
    }

    if (events & LOS_ERRTYPE_ERROR) {
        return LOS_ERRNO_EVENT_SETBIT_INVALID;
    }

    LOS_TRACE(EVENT_WRITE, (UINTPTR)eventCB, eventCB->uwEventID, events);

    SCHEDULER_LOCK(intSave);

⑴  eventCB->uwEventID |= events;
⑵  if (!LOS_ListEmpty(&eventCB->stEventList)) {
⑶      for (resumedTask = LOS_DL_LIST_ENTRY((&eventCB->stEventList)->pstNext, LosTaskCB, pendList);
             &resumedTask->pendList != &eventCB->stEventList;) {
⑷          nextTask = LOS_DL_LIST_ENTRY(resumedTask->pendList.pstNext, LosTaskCB, pendList);
⑸          if (((resumedTask->eventMode & LOS_WAITMODE_OR) && ((resumedTask->eventMask & events) != 0)) ||
                ((resumedTask->eventMode & LOS_WAITMODE_AND) &&
                 ((resumedTask->eventMask & eventCB->uwEventID) == resumedTask->eventMask))) {
⑹              exitFlag = 1;
                OsTaskWake(resumedTask, OS_TASK_STATUS_PEND);
            }
⑺          if (once == TRUE) {
                break;
            }
⑻          resumedTask = nextTask;
        }
    }

    SCHEDULER_UNLOCK(intSave);

    if (exitFlag == 1) {
⑼      LOS_MpSchedule(OS_MP_CPU_ALL);
        LOS_Schedule();
    }
    return LOS_OK;
}

2.4 清除事件

我們可以使用函數UINT32 LOS_EventClear(PEVENT_CB_S eventCB, UINT32 events)來清除指定的事件類型，下面通過分析源碼看看如何清除事件類型的。

函數參數為事件結構體eventCB和要清除的事件類型events。清除事件時首先會進行結構體參數是否為空的校驗，這些比較簡單。⑴處把事件結構體的事件掩碼和要清除的事件類型events進行邏輯與計算，來完成事件的清理。

LITE_OS_SEC_TEXT_MINOR UINT32 LOS_EventClear(PEVENT_CB_S eventCB, UINT32 events)
{
    UINT32 intSave;

    if (eventCB == NULL) {
        return LOS_ERRNO_EVENT_PTR_NULL;
    }

    LOS_TRACE(EVENT_CLEAR, (UINTPTR)eventCB, eventCB->uwEventID, events);

    SCHEDULER_LOCK(intSave);
⑴  eventCB->uwEventID &= events;
    SCHEDULER_UNLOCK(intSave);

    return LOS_OK;
}

2.5 銷毀事件

我們可以使用函數UINT32 LOS_EventDestroy(PEVENT_CB_S eventCB)來銷毀指定的事件控制塊，下面通過分析源碼看看如何銷毀事件的。

函數參數為事件結構體，銷毀事件時首先會進行結構體參數是否為空的校驗，這些比較簡單。⑴處如果事件的任務阻塞鏈表不為空，則不能銷毀事件。⑵把事件結構體的事件掩碼設置為0，完成事件的銷毀。

LITE_OS_SEC_TEXT_INIT UINT32 LOS_EventDestroy(PEVENT_CB_S eventCB)
{
    UINT32 intSave;
    UINT32 ret = LOS_OK;

    if (eventCB == NULL) {
        return LOS_ERRNO_EVENT_PTR_NULL;
    }

    SCHEDULER_LOCK(intSave);
⑴  if (!LOS_ListEmpty(&eventCB->stEventList)) {
        ret = LOS_ERRNO_EVENT_SHOULD_NOT_DESTORY;
        goto OUT;
    }

⑵  eventCB->uwEventID = 0;
OUT:
    SCHEDULER_UNLOCK(intSave);

    LOS_TRACE(EVENT_DELETE, (UINTPTR)eventCB, ret);
    return ret;
}

小結

本文帶領大家一起剖析了LiteOS事件模塊的源代碼，包含事件的結構體、事件初始化、事件創建刪除、申請釋放等。感謝閱讀，如有任何問題、建議，都可以留言給我們： https://gitee.com/LiteOS/LiteOS/issues 。為了更容易找到LiteOS代碼倉，建議訪問 https://gitee.com/LiteOS/LiteOS ，關注Watch、點贊Star、並Fork到自己賬戶下.謝謝。

 本文分享自華為雲社區《LiteOS內核源碼分析系列九 事件Event》，原文作者：zhushy 。

點擊關注，第一時間了解華為雲新鮮技術~